Using the Workflow API
Use the information on this page to learn how to work with specific entities in the workflow API that are not described in other sections of the workflow reference.
Accessing Properties, Custom Fields, and Issue Links
Follow these guidelines to access issue properties, values in custom fields, and issue links.
- Predefined Issue Fields
-
Predefined issue fields like
summary
,description
, andreporter
are all properties of theissue
entity.const summary = issue.summary; issue.summary = "Just a bug"; - Custom Field Values
-
References to values in a custom field vary based on whether the field stores single or multiple values.
For fields that store single values, you can reference the value directly:
const state = issue.fields.State; issue.fields.State = ctx.State.Open; if (issue.fields.State.name === ctx.State.Fixed.name) { // Do stuff }For fields that store multiple values, the values are stored as a set. The operations that are available for sets are described in more detail in the next section.
const versions = issue.fields["Fix versions"]; versions.forEach(function (v) { subtask.fields["Fix versions"].add(v); });
- Aliases
-
If you set the
alias
property for a custom field in therequirements
statement, you can use this alias to access values for the field as well. For example, if the alias for the Fix versions field is set toFV
:issue.fields.FV.forEach(function (v) { // Do stuff }); - Issue Links
-
Issue link types are accessed by their inward or outward name. For example,
relates to
orparent for
. Issue links are always treated as a set.const parent = issue.links["subtask of"].first(); parent.links["parent for"].add(issue);
Note that custom fields and issue link types that contain spaces or other non-alphabetic characters must be set in quotation marks and brackets.
Working with Set Objects
There are several groups of operations you can do with multiple values (returned as Set<value type>):
Access them directly (
first()
,last()
,get(index)
) or by iterator (entries()
,values()
).Traverse over all values in Set with
forEach(visitor)
.Look for values with
find(predicate)
and check if a value is in Set withhas(value)
.Check size with
isEmpty()
,isNotEmpty()
andsize
property.Modify content with
add(element)
,remove(element)
andclear()
.Get the current changes for a Set object with the
added
,removed
andisChanged
properties.
For a detailed description of this object, see Set.
Calling Methods
Finding Specific Entities
There are two ways to find a specific entity, like an issue or a user, and use it in a workflow script:
Add it in the requirements and reference it in the context. Use this approach as often as you can, as it is the most reliable. If the specified entity is not found in your database, the script is not executed.
If the first option is not applicable for whatever reason, use the
findBy*
andfind*By*
methods from the workflow API:
Use findBy*
methods to find a single occurrence of a specific entity:
Use find*By*
methods to find child entities:
Finding Multiple Issues
Sometimes you might want to find a set of issues that match certain criteria and process them in the scope of a single rule. For example, you can compile a list of issues and send it as an email message. In these situations, the search API can help. Here's a simple example: