This page provides a list of the methods and operations that are supported the workflow programming language.
The syntax for each method or operation is presented in the format: [name]([data type] parameter): [data type].
The methods and operations that are described on this page are grouped by the object type that they are related to.
To use a method or operation, simply add a dot after any field and write the name of the method or operation.
You can continue to add methods and operations to the statement until it generates the desired condition.
For example:
whencomments.added.isNotEmpty
With code completion, the workflow editor displays a list of possible options that can be used with the preceding element.
Methods display the syntax and the object type they are associated with in the schema.
Operations are formatted in dark blue text in the editor and display a description of each available operation.
Issues
Changes that are applied to an issue are managed by a series of transactions.
A transaction is a collection of current changes that are either saved to the database or discarded as a set.
When a user edits an issue, a new transaction is started. The transaction is completed when the user clicks the Submit button.
The single transaction includes all of the changes that were made to the issue.
Rules that are not executed according to a schedule are processed at the end of a transaction.
Scheduled rules and scheduled blocks in state-machine rules are only processed for issues that are already reported or become reported in the current transaction.
The following methods are available for use with issues.
See also Issue Fields.
getId(): string
Description
Returns the issue ID.
Example
user.notify("Issue is overdue","Please, look at the issue: "+issue.getId());
getUrl(): string
Description
Returns the issue URL.
Example
user.notify("Issue is overdue","Please, look at the issue: "+issue.getUrl());
Gets the comments that are edited in the current transaction.
Comments that are added and removed are not considered as edited.
These values are represented by the issue.comments.added and issue.comments.removed properties.
Add a tag with the specified name to an issue.
YouTrack adds the first matching tag that is visible to the current user.
If a match is not found, a new private tag is created for the current user.
When you use this method to add the star tag to an issue, the current user is added to the list of watchers.
To add a tag that is not visible to the current user, use the applyCommand method instead.
Use "add tag <tagName>" for the command parameter and specify the login for the owner of the tag in the runAs parameter.
Remove a tag with the specified name from an issue.
If the specified tag is not attached to the issue, an exception is thrown.
This method only works when the logged-in user is also the owner of the tag.
To remove a tag that is owned by another user, use the applyCommand method instead.
Use "remove tag <tagName>" for the command parameter and specify the login for the owner of the tag in the runAs parameter.
The following methods are related to the lifecycle of an issue. The lifecycle of an issue consists of the following stages:
Stage
Description
1. Issue is created in this transaction
The issue is still in draft form and does not have an issue ID. The default custom field values are set in this stage.
Rules are not triggered during this stage.
2. Issue is draft
Changes are made after creation but before the issue is reported. This stage includes all edits to the draft issue.
Stateless and state-machine rules can be triggered during this stage.
Scheduled rules and scheduled blocks in state-machine rules are not processed.
3. Issue becomes reported in this transaction
The issue becomes reported. The issue is submitted and is assigned an ID.
All rules including scheduled rules and scheduled blocks in state-machine rules are processed during this stage.
4. Issue is reported
This stage includes all changes made to an issue after it has been reported.
All rules including scheduled rules and scheduled blocks in state-machine rules are processed during this stage.
5. Issue is deleted in this transaction
The issue is deleted and is not available after this transaction is complete.
Rules are not triggered during this stage.
isReported(): Boolean
Description
Checks whether an issue is already reported or becomes reported in this transaction (stages 3 and 4).
To apply changes to an issue draft (stage 2), use !isReported().
The following methods are related to the issue.resolved property.
This property is set based on the values that are stored in a custom field with a state data type.
Each value that can be stored in this field has a Resolved property.
This property determines whether the issue is considered to be resolved when it assigned a value for this field.
The resolved property is associated with the issue, which means that these methods do not contain references to the custom field.
isResolved(): Boolean
Description
Checks whether an issue is assigned a state that is considered resolved.
These methods can be used to send notifications to unregistered users with an email address.
To send notifications to existing users, use the notify, notifyAllUsers,
sendMail, and sendJabber methods.
If overused, sending email messages to unregistered users can slow down the performance of your YouTrack server, which is not designed for use as a bulk email service.
You can configure a system property to set a daily email message limit. For more information, see Configuration Parameters.
getNotificationEmail(): string
Description
Returns the email address that is used to send notifications for the project.
If a From address is not set for the project, the From address for the YouTrack server is returned.
The sender of the email message.
If this parameter is not set, the project From address is used.
If a From address is not set for the project, the From address for the YouTrack server is used.
fromEmail
email
The email address of the primary recipient.
cc
The email addresses of additional recipients who receive a copy of the message.
Multiple email addresses are delimited with commas.
If this parameter is not set, the message is sent to a single recipient.
subject
The subject line of the email message
body
The email message text.
Description
Sends an email message with the specified parameters.
Example
whencomments.added.isNotEmpty{if(Reporteremail!=null){sendMail(Reporteremail,"[YouTrack, Commented]","New comment was added: "+comments.added.first.text));}}
wikify(string text): string
Parameters
text
The string of text to convert to HTML.
Description
Converts text with wiki markup to HTML.
Use this method to send "pretty" notifications to unregistered users.
Example
whencomments.added.isNotEmpty{foreachcommentincomments.added{sendMail("myuser@example.com","Issue is commented",wikify(comment.text));}}
Fields
The following operations are available for all fields.
becomes([field] value): Boolean
Parameters
value
The value to check for the specified field.
Description
Checks whether a specific value is set for a field in the current transaction.
The message that is displayed to the user that describes the field requirement.
Description
Asserts that a value is set for a field.
If a value for the required field is not set, the field is highlighted in the issue and the specified message is displayed.
Example
stateApproved{enter{Assignee.required("Please select an assignee");}
CustomFields
The following method is available for CustomField types.
See also CustomField Fields.
getPresentation(): string
Description
Returns the presentation of the value for a custom field.
Example
if(!Type.name.eq(Type.getPresentation(),opts)){message("The "+Type.getPresentation()+" has been changed.");}
ProjectFields
The following methods are available for ProjectField types.
See also ProjectField Fields.
Returns the UserGroup by whom the tag is updatable.
If the tag is updatable only by its owner, returns null.
Example
varupdatable=tag.getUpdateShareGroup();
SavedQuery
The following methods are available for SavedQuery types.
You can specify a saved search with the literal reference {savedSearch: [savedSearchName]}.
See also IssueTag Fields.
The workflow programming language contains a set of predefined sequences.
These sequences include issues, comments, tags, users, issue links, enumerated custom fields, versions, builds, ownedFields, groups, states, static elements for sets of values, and strings.
The workflow language does not let you define your own sequence of elements.
When you reference a sequence, you can look up the values that are stored in a specific field for each element.
For example, issue.comments returns a sequence of IssueComment elements.
You can find the first comment that was added to the issue with the operations added and first.
You can then access fields for the first IssueComment, such as text or author.
A statement that returns this field would look something like this:
Checks whether the user is a member of the specified group.
Example
whenAssignee.changed&&Assignee!=null{if(permittedGroup!=null&&!Assignee.isInGroup(permittedGroup.name)){message(l10n(Pleasetakeintoaccountthatnewassignee' {Assignee.fullName} 'isn't included into the visibility group '{permittedGroup.name}'!));}}
If true and the specified tag does not exist or is not visible to the user and the user has permission to create tags, a new tag with the specified name is created.
If false, the message is not sent when changes are performed on behalf of the current user.
The corresponding flag is unchecked.
Otherwise, the message is sent anyway.
Description
Sends an email notification to the email address that is set in the user profile.
Example
varprojectLeader=project.leader;projectLeader.notify("Attention","Please pay attention to "+getId());projectLeader.sendJabber("Please look at "+getId());
sendMail(string subject, string body): void
Parameters
subject
The subject line text of the email notification.
body
The message text of the email notification.
Description
An alias for notify(subject, body, true)
Example
sendMail(Reporteremail,"[YouTrack, Commented]","New comment was added: "+comments.added.first.text));
sendJabber(string text): void
Parameters
text
The message text for the Jabber notification.
Description
Sends a notification message over Jabber.
Similar to notify method, the message won't be sent on own changes and corresponding flag unchecked.
Example
project.leader.sendJabber("Please pay attention to "+getId());
The following operation is available for use with User objects.
Returns all of the users who are members of the specified group.
Example
varusers=Assigneesgroup.getUsers();
notifyAllUsers(string subject, string body): void
Parameters
subject
The subject line of the email notification.
body
The message text of the email notification.
Description
Sends an email notification to all of the users who are members of the group.
Example
permittedGroup.oldValue.notifyAllUsers("Visibility has been changed","The visibility group for the issue "+"<a href=\""+issue.getUrl()+"\">"+issue.getId()+"</a> has been changed to "+permittedGroup.name);