There are two types of snippets code. Syntax snippets contain code that is used to create common code syntaxes like loops or conditional statements. Functional snippets consist of code that is used to perform a function or operation such as creating a new Jira issue.

Syntax Snippets

Syntax snippets are helpful for new or experience experienced script creators who are looking to quickly add functionality to a script without typing and without memorizing the specific syntax. They do not perform any action by themselves but can easily be combined with a functional snippet to create a custom script.

FOR loop objects - inserts the basic syntax for a loop that iterates through an object such as an array or array of structs. This is commonly used when importing data from CSV for JSON. See the documentation about FOR loops for more information.

for(string s in array_of_string) {
    // do something
}

FOR loop with index - inserts the basic syntax for a loop that iterates a fixed number of times using an index. See the documentation about FOR loops for more information.

for(int i = 0; i < size(array); i++) {
    // do something
}

IF - ELSE - The most common conditional logic statement will be used in almost any script. See the documentation about IF - ELSE statements for more information.

if(condition) {
    // do something
} else {
    // do something else
}

WHILE - A less popular type of loop then the FOR loop but no less important. This form evaluates the condition first and then executes the instructions in the body. See the documentation about WHILE loops for more information.

while(condition) {
    // do something

DO WHILE - A less popular type of loop then than the FOR loop and even less popular then than the WHILE loop. Similar to the WHILE loop except the condition is evaluated after the execution of the encapsulated block. So, even if the condition is false, the instructions will still be evaluated once. See the documentation about DO WHILE loops for more information.

do {
    // do something
} while(condition);

Functional Snippets

Unlike the syntax based snippets, functional snippets actually perform an action or an operation to achieve a desired outcome.

General

General script snippets are scripts that don’t fit into a specific category. This does not mean they are any less useful only that they may not be triggered from a specific place.

Create an issue - Create a new issue in Jira using the createIssue() routinefunction. This routine function is popularly used in postfunctions for creating subtasks.

string newKey = createIssue("TEST", "", "Story", "This issue was created by SIL"); //basic example of creating an issue
if(newKey != null) {
    //some additional changes to the issue after it is created.
    %newKey%.assignee = "admin";
    %newKey%.labels += "sil_ticket";
}

Bulk change issues - A very useful bit of code, this snippet uses standard Jira JQL to select issues using the selectIssues() routine function. Then, the issues are iterated over using a loop giving the script creator to perform some type of scripted change to each issue that was selected. This type of script is very useful for scheduled scripts such as escalation scripts, scripts that can be used in the SIL Runner gadget, or ad-hoc scripts run directly from the SIL Manager.

const string jql = "project = TEST"; // change the JQL to match your reality 
for(string k in selectIssues(jql, 100)) { // select first 100 issues 
    //%k%.newCustomField = %k%.customfield_12345; //migrate values from a CF to another using 'newCustomField' alias.
    //%k%.description = "[CHANGED]" + %k%.description; //add a prefix to description
    runnerLog("Selected issue " + k + ", summary :" + %k%.summary); //prints to the editor console
}

Select a row from a table - This script is a basic example of the code needed to select a single row of data from a database. Please note that a data source configuration is required for this script to function.

struct country {
    int id;
    string name;
    string code;
};

string param = "RO";
country c = sql("External_DB_CHANGEME", "SELECT id, name, iso_code FROM countries WHERE iso_code = ?", param); //match field for field in the structure

Select multiple rows from a table - This script is a basic example of the code needed to select multiple rows of data from a database. Please note that a data source configuration is required for this script to function.

struct country {
    int id;
    string name;
    string code;
};

string param = "RO";
country [] allcountries = sql("External_DB_CHANGEME", "SELECT id, name, iso_code FROM countries"); //match field for field in the structure

Send email - A basic example of how to send an email from a SIL script. Please note that the mail configuration must be in place in order to send emails. A quick way to test sending emails is to set the mail configuration to Container Sender. See the mail configuration documentation for more information.

//sends an email to the project leader and PMGroup group, CC to component leader for 'mycomponent'
string [] tos = { projectPM(project), "PMGroup", "somedirectemail@fooandgoo.com" };
sendEmail(tos, getProjectComponentLead(project, "mycomponent"), 
         "[SUBJECT] Snippet email subject", 
         "BODY of email: You should be informed that " + currentUser() + " has sent you this message via a PowerScripts automation");

Current Issue

Script snippets under the current issue category are focused on reading/writing data to Jira issues. They can be executed in a variety of different methods including workflow triggers and listeners.

Change the issue - An example for changing or updating fields on an issue. For more information about accessing data for regular Jira fields or custom fields see the Variable Resolution documentation page.

//This assumes we're in the context of an issue.
runnerLog("Current issue " + key + ", summary :" + summary); //prints to the editor console. 
//Uncomment one or more of the following:
//newCustomField = customfield_12345; //migrate value from a CF to another using 'newCustomField' alias.
//description += "[CHANGED]; //add a sufffix to description
//#{Story Points} = 5; //addressing a CF by name

Subtasks - An example for accessing and iterating through the subtasks for an issue. This is useful for keeping data and statuses in sync between subtasks and the parent issue.

for(string s in subtasks(key)) { //iterate over subtasks of current issue
    //if the subtask isn't closed
    if(%s%.status != "Closed") {
        //do something to the subtask
        runnerLog("Subtask is:" + s);
    }
}

Linked issues - An example for accessing and iterating through the linked issues for an issue. This is useful for keeping data and statuses in sync between linked issues and the main issue.

for(string l in linkedIssues(key)) { //iterate over linked issues of the current issue
    //do something with those issues
    runnerLog("Linked issue:" + l); //print it to the editor console
}

Attachments - An example for accessing and iterating through the attachments for an issue. This could be useful in condition or validator scripts that check to see if an attachment has been added to the issue.

for(string a in attachments) { //iterate over the attachments of the current issue
    //do something to the attachments:
    runnerLog("Attachment :" + a);
}

Add a comment - Example code for adding a comment to an issue. This can be useful for informing users of changes or updates that were performed by script automation so they are aware of the changes.

addComment(key, currentUser(), 
            "Comment from SIL logged for the current user (" + currentUser() + 
            ") against the current issue: " + key);

Listeners

Listener scripts are very similar to workflow scripts with the difference being on how they are triggered. Listeners can be triggered for many other events then the workflow is capable of triggering, such as when a field is updated on an issue. For more information about configuring listeners see the SIL Listeners documentation page.

React to a field change only - This listener snippet contains code that will only be executed if a specific field was updated as part of the change event.

if(isIssueFieldChanged("description")) { //check if the field of interest was changed
    JFieldChange change = getEventIssueFieldChange("description"); //get the change
    logPrint("INFO", "Old value >>" + change.oldVal + "<< New value >>" + change.newVal + "<<"); //do something
}

React to multiple field changes - This listener snippet contains code that will be executed if any change is detected on the issue. The code can be further refined to respond to specific change types as needed.

JFieldChange [] changes = getEventIssueChanges();
for(JFieldChange change in changes) {
    //see if the changes are of interest and do something with them:
    logPrint("INFO", "Field " + change.field + "; old value >>" + change.oldVal + "<< New value >>" + change.newVal + "<<");
}

Workflows

Workflow snippets contain examples of scripts that would be triggered from a workflow. This includes condition scripts, validator scripts, and postfunction scripts. For more information about adding automation to workflows see the Workflow Automation documentation page.

Simple postfunction - This snippet gives example code for a simple postfunction. One of the most popular places for adding scripted automation postfunction scripts are good for setting custom field values automatically. For more information about accessing data for regular Jira fields or custom fields see the Variable Resolution documentation page.

//You can do any change to the issue in postfunctions. key and project are implied
//assign the issue to the current user
assignee = currentUser();
//set the due date to be 2 weeks from today
dueDate = currentDate() + "2w";
//add user as an approver using the approver custom field
customfield_12345 = projectPM(project);
logPrint("INFO", "Postfunction for issue " + key + " was executed"); //prints a message in the log

Simple validator on user roles Postfunction to increase priority - This snippet gives example code for preventing users who are not in a specific project role from performing the workflow transition.

const string errMsg = "Only users in the manager role may perform this action!"; //error message to display to the user
string[] roles = userRoles(project, currentUser()); //get project roles for current user
if(!arrayElementExists(roles, "managers")) { //check to see if the 'manager' project role is in the list
    //if no 'manager' role is present return false so the validator fails the error message will then be displayed to the user
    return false, errMsg;
}
return true;

Validator for user input - This validator is used during a transition that has a transition screen. It reads the input data from the transition screen and uses it to evaluate the condition.

if(!hasInput("comment")) { //verifies if there's some value on the comment field on this transition. Requires a screen
    return false, "You need to add a comment to transition issue " + key;
}

Simple condition - This snippet gives example code for preventing users who are not in a specific project role from performing the workflow transition. The difference between this condition script and the validator snippet script is that conditions do not display messages back to the users.

//condition - transition only available to user in managers role
string[] roles = userRoles(project, currentUser()); //get project roles for current user
if(!arrayElementExists(roles, "managers")) { //check to see if the 'manager' project role is in the list
    //if no 'manager' role is present return false so the next transition will disappear
    return false;
}
return true;

Postfunction to increase priority - This snippet gives example code for setting the priority as part of a postfunction.

setting the priority as part of a postfunction.

//increase priority for the current issue
if(priority == "Lowest" || priority == "Low") {
    priority = "High";
} else if(priority == "Normal") {
    priority = "Highest";
}
logPrint("INFO", "Priority for " + key + " is now :" + priority); //prints a message in the log