SIL Script Migration

Prerequisites

• Administrator access to both Jira DC and Jira Cloud instances

• Inventory of existing Power Scripts

• Knowledge of Simple Issue Language (SIL)

• Understanding of cloud environment constraints

• Review the Jira DC to Cloud script migration reference to learn which scripts migrate successfully and which scripts require readjustment.

Migration method

You can use an automated or manual migration method.

Automated migration

For automated script migration, use a tool such as Jira Cloud Migration Assistant (JCMA) or Configuration Manager for Jira (CMJ). When using a tool, the following consistencies help ensure script compatibility:

• Project and issue type names remain exact matches between Jira DC and Jira Cloud. This ensures project keys or issue type names used directly in scripts will continue to operate after migration.

• Custom field names are preserved as exact matches between Jira DC and Jira Cloud, but custom field IDs will be different.

  • If SIL aliases were used, which is a best practice, you can update the SIL aliases settings in Power Scripts for Jira Cloud. This way, the scripts will automatically work with the new IDs.

  • If custom field aliases were not used, the migration is a good opportunity to start using them.

• Status and transition names remain exact matches between Jira DC and Jira Cloud. This ensures scripts using status names, transition names, or IDs should continue to operate after migration.

For details, see Script migration process.

Manual migration

If you aren’t using a migration tool, scripts can still be migrated by uploading them to the SIL manager or through the Apps > Power Scripts > Self Help menu in Jira Cloud admin settings and then configuring them manually.

 Steps for manual script migration

This page explains the steps for manually migrating your SIL scripts from Jira Server/Data Center (Jira DC) to Jira Cloud.

While migrating scripts and settings from Jira Server/Data Center to Jira Cloud can be done manually, there are automation tools that can help with large script volumes. In such cases, we can provide assistance with the script migration process. See how to get help.

Prerеquisites

Your Power Scripts and SIL Engine version must be 5.8.0.0 or higher.

Procedure

1. Export all scripts from your Jira Server or DC instance.

   1. Open the SIL Manager and right-click the silprograms folder.

   2. From the dropdown menu that opens, select Download.
      

      

2. Install Power Script for Jira Cloud on your target cloud instance.

3. From the application server running Jira, create a zip file of the silprograms directory found in the Jira Home folder.

4. In your Jira Cloud instance:

   1. Navigate to the Apps > Power Scripts > Self Help page.

   2. Select the Backup/Restore tab.

   3. Upload the zip file.

Your SIL scripts are now migrated to the new Jira Cloud instance.

Script migration process

Post-migration testing

After the migration, test your scripts by performing a syntax check in the SIL Manager (in Power Scripts for Jira Cloud).

If a script passes the syntax test, it means that:

• The functions shown in this code are compatible with both Jira DC and Cloud environments.

• The syntax of the script it correct.

• Custom field IDs are correct or have been updated in the alias file.

Some scripts may not work identically between DC and cloud environments and can require adjustments due to differences in project names, issue type names, JQL queries, or other script-contained information. While using migration tools (JMCA or CMJ) improves the chances of successful script migration, these elements may still need to be adjusted to ensure the scripts operate in the cloud instance as expected.

Required post-migration script changes

When migrated between Jira DC and Jira Cloud, the following script types require additional changes: conditions and validator scripts, Live Fields, and mail handler scripts. In addition, all existing scripted JQL functions/keywords must be updated for Jira Cloud.

Conditions and validator scripts

Jira Cloud uses Jira Expressions language for conditions and validators; scripted conditions and validators are not currently supported in Jira Cloud. While many users find Jira Expressions challenging and time-intensive to work with, there are alternative approaches. As with other features in Jira Cloud, rather than directly converting scripts and replicating Data Center solutions, consider rethinking your approach. To learn about ways to continue using SIL scripted conditions and validators in Jira Cloud, see this article.

issue.issueType.name.match('^(Dev Task)$') == null || 
(issue.issueType.name.match('^(Dev Task)$') != null && 
issue.parent.subtasks.filter(subtask => subtask.assignee != null).length == 
issue.parent.subtasks.length)? true : false

//SIL code
boolean passConditionValue = true;
if(issueType == "Dev Task") {
    for(string s in subtasks(parent)) {
        if(s.issueType == "Dev Task && isNull(s.assignee)) {
            passConditionValue = false;
        }
    }
}
setIssueEntityPropertyValue(key, "passCondition", passConditionValue);

//Jira Expression
JSON.stringify(issue.properties['passCondition']).includes('true')

Live Fields scripts

Live Fields works differently in Jira DC versus Jira Cloud.

Because of these differences, all Live Fields scripts must be converted from SIL to JavaScript when migrating.

Example

//SIL (Data Center)
lfSet("summary", "Value to set");

//JavaScript (Cloud)
getFieldById("summary").setValue("Value to set");

Mail handler scripts

The Power Scripts incoming email service works differently in Jira Cloud than in Data Center. Due to Atlassian’s Cloud architecture, email scripts In Jira Cloud:

• Cannot intercept messages sent to your primary Atlassian address (youremail@atlassian.net).

• Can only intercept emails going to an external email accounts, such as Gmail.

Due to the differences in email handling between DC and Cloud, email scripts require different functions in each environment. Existing DC email scripts must be updated to use the new Cloud-compatible functions.

IncomingEmail mail = getIncomingEmail();
string issueKey = matchText(mail.subject, "[A-Z][A-Z]+-[0-9]+"); // find an issue key in the subject
if(isNull(issueKey)) {
	// if no issue key found, create a new issue
    string [] fields = {};
    fields += {"reporter", currentUserKey()};
    fields += {"assignee", getUserByEmail(mail.cc[0]).key}; 
    string newIssue = createIssue("TEST", "", "Task", mail.subject, "Minor", mail.body, {}, "", "", 0, fields);
    attachAllFilesFromEmail(newIssue);
    %newIssue%.watchers = getUserKeysFromEmails(mail.cc); 
} else {
	// if issue key found in subject, add a comment
    addComment(issueKey, currentUserKey(), mail.body);
}

IncomingEmail mail = getIncomingEmail();
string issueKey = mail.subject;
if(issueExists(issueKey)) {
    // add comment
    string commentText = mail.body;
    string userCommenting = getUserByEmail(mail.from).key;
    addComment(issueKey, userCommenting, commentText);
    attachAllFilesFromEmail(issueKey);
} else {
    // create issue
    string summary = mail.subject;
    string description = mail.body;
    string [] fields = {};
    fields += {"reporter", getUserByEmail(mail.from).key};
    createIssue("SCRUM", "", "Task", summary , "Minor", description, {}, "", "", fields);
}

Scripted JQL functions/keywords

Jira DC and Jira Cloud handle scripted JQL functions/keywords in fundamentally different ways. This difference stems from Jira's core architecture, not from Power Scripts functionality.

These architectural differences require the following changes to JQL script construction for Jira Cloud:

• Scripts no longer contain their own JQL searches within their code.

• Return statements require additional Cloud-specific operations.

• JQL scripts in Jira Cloud can update the search values of parent and child issues as well as the value within the issue that triggered the script.

Due to these differences, all existing scripted JQL functions/keywords must be updated to use the new methods in Jira Cloud.

Converting Groovy scripts to SIL

If your migration plan includes converting Groovy scripts to SIL, familiarize yourself with the key differences between the Groovy and SIL approaches to scripting.

import com.atlassian.confluence.user.DisabledUserManager
import com.atlassian.crowd.embedded.api.CrowdService
import com.atlassian.sal.api.component.ComponentLocator
import com.onresolve.scriptrunner.parameters.annotation.ShortTextInput

@ShortTextInput(label = "Users", description = "Type usernames of deactivated users you would like to reactivate, seperated by spaces")
String names
assert names

def disabledUsers = names.split()

def disabledUserManager = ComponentLocator.getComponent(DisabledUserManager)
def crowdService = ComponentLocator.getComponent(CrowdService)

disabledUsers.each { userName ->
    def user = crowdService.getUser(userName)
    if (user) {
        if (disabledUserManager.isDisabled(user)) {
            disabledUserManager.enableUser(user)
            log.info("User $user.name has been enabled")
        } else {
            log.info("User $user.name is not disabled")
        }
    } else {
        log.debug("User $userName was not found.")
    }
}

//Groovy approach
def issue = Issues.getByKey('SR-1') as MutableIssue

//SIL approach
string key = "SR-1";

//Groovy approach
setPriority('Highest')

//SIL approach
priority = "Highest";

import com.adaptavist.hapi.jira.issues.Issues
import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.MutableIssue
import com.atlassian.jira.issue.index.IssueIndexingParams
import com.atlassian.jira.issue.index.IssueIndexingService

def issueIndexingService = ComponentAccessor.getComponent(IssueIndexingService)

def issue = Issues.getByKey('SR-1') as MutableIssue

issue.set {
    setPriority('Highest')
    setSummary('my new summary')
}

issue.store()
issueIndexingService.reIndex(issue, IssueIndexingParams.INDEX_ISSUE_ONLY)

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.fields.CustomField
import com.atlassian.jira.issue.CustomFieldManager


CustomFieldManager cfm = ComponentAccessor.getCustomFieldManager();
CustomField templateCF = cfm.getCustomFieldObject(10112L);
log.error('[LOG] templateCF: ' + templateCF)

Map templateValue = issue.getCustomFieldValue(templateCF)
log.error('[LOG] templateValue: ' + templateValue)

boolean templateIsEmpty = templateValue.get("SELECTED_TEMPLATE") == null;

if (templateIsEmpty) {
    log.error("Template is empty")
    return false;
}

log.error("Template is not empty")
return true;

Jira DC to Cloud script migration reference

Learn more about which scripts migrate successfully from Jira DC to Cloud and which scripts will require adjustment.

Useful tools and scripts for post-migration script adjustment

for(JFilter f in admGetAllFilters()) {
    string oldFunction = "hasLinkType";
    
    if(contains(f.jql, oldFunction)) {
        runnerLog("Filter \"" + f.name + "\" [" + f.id + "] owned by " + userFullName(f.owner) + " <strong style=\"color:red;\">contains</strong> the function for removal: <strong>" + oldFunction + "</strong>", true);
    } else {
        runnerLog("Filter \"" + f.name + "\" [" + f.id + "] owned by " + userFullName(f.owner) + " <strong style=\"color:green;\">does not contain</strong> the function for removal: <strong>" + oldFunction + "</strong>", true);
    }
}

//Starting JQL format:
issueFunction in FUNCTION_NAME("PARAMETER") and ADDITIONAL_CONDITIONS

//Changes to:
FUNCTION_NAME = "PARAMETER" and ADDITIONAL_CONDITIONS

//starting JQL format
issueFunction in hasLinkType("Blockers") and resolution is empty

//would be changed to:
hasLinkType = "Blockers" and resolution is empty

for(JFilter f in admGetAllFilters()) {
    string oldFunction = "hasLinkType";
    string newFunction = "hasLinkType";
    
    if(contains(f.jql, oldFunction)) {
        string jql = f.jql;    
        string [] pieces = split(f.jql, oldFunction);
        
        jql = replace(pieces[0], "issueFunction in ", "") + newFunction;
        
        pieces[1] = replace(pieces[1], "(", " = ");
        pieces[1] = replace(pieces[1], ")", "");
        
        jql += pieces[1];
        f.jql = jql;
        
        admUpdateFilter(f);
        runnerLog("Filter \"" + f.name + "\" [" + f.id + "] owned by " + userFullName(f.owner) + " has been updated to use the new syntax for function: <strong>" + oldFunction + "</strong>", true);
    }
}