Behaviours

[All Adaptavist Apps]

Page tree

You can reference the functions and properties outlined below within your behaviour scripts.

Read/Update fields

Access a field

All supported fields (description, summary, assignee, labels, priority) can be accessed by using getFieldById(fieldID).

For example:

const theDescription = getFieldById("description")
theDescription.setName("The description name");
const theValue = "the value is " + theDescription.getValue();
console.log(theValue);

Access a changed field

If your script is triggered onChange you can use the getChangeField() function. This function will return an object with the same structure as getFieldById.

For example:

const changedField = getChangeField()
if(changedField.getName() == "summary") {
	console.log("The summary has changed!");
}

Available Read Methods

Note that these are only accessible on the object returned by getFieldById.

MethodDescriptionExample
getValue()

Returns the value of a field

Return type depends on the field you’re updating:

  • Summary: string

  • Description: string or Atlassian Doc Format depending on your Jira configuration

  • Labels: string[]

  • Priority: { name: string, id: string }

  • Assignee: { accountId: string, displayName: string }

getFieldById("summary").getValue()

getName()

Returns the name of a field

Return type: String

getFieldById("summary").getName()

getDescription()

Returns the description of the field

Return type: String

getFieldById("summary").getDescription()

isVisible()

Returns whether the field has been hidden

Return type: boolean

getFieldById("summary").isVisible()

getId()

Returns the id of the field

Return type: string

getFieldById("summary").getId()

isReadOnly()

Returns whether the field has been set as read-only

Return type: boolean

getFieldById("summary").isReadOnly()

Available Write Methods

Note these are only accessible on the object returned by getFieldById and getChange.

If you are setting a field value which is in Atlassian Doc Format, Atlassian provides a tool that allows you to generate the ADF. You can read more in Atlassian's documentation.
MethodDescriptionExample

setName(name)

Updates the field name

Parameter: name

Parameter type: string

getFieldById("summary").setName("A new name")

setDescription(desc)

Updates the field description

Parameter: desc

Parameter type: string


getFieldById("summary").setDescription("A new description")



setVisible(visible)

Updates the fields visibility

Parameter: visibile

Parameter type: boolean

getFieldById("summary").setVisible(false)

setValue(value)

Updates the field value

Parameter: value

Parameter type: Depends on the field you’re updating

  • Summary: string

  • Description: string or Atlassian Doc Format depending on your Jira configuration

  • Labels: string[]

  • Priority: { name: string, id: string }

  • Assignee: { accountId: string, displayName: string }

getFieldById("summary").setValue(<FieldValue>)

setReadOnly(readable)

Sets a field to read-only

Parameter: readable

Parameter type: boolean

getFieldById("summary").setReadOnly(true)

Make REST Requests

You can use makeRequest to hit the Jira Cloud REST API.

Parameters:

url: string of the rest endpoint

requestOptions: Optional request options of type RequestInit | typescript - v3.7.7

Return type: Promise<{status: number, body: JSON }>

For example:

const res = await makeRequest("/rest/api/2/myself");
if(res.body.accountId == "the accountId") {
logger.info("User is bob");
}

Some Jira REST APIs are not supported on Atlassian Forge and will, therefore, not work on the Behaviours feature. For example, requests with OAuth2 permission scopes generally work on Forge. Where this scope is absent, we expect that the API endpoint is not supported on Forge.

You can make a POST request that specifies request options and headers with the makeRequest method. You can also make other types of REST requests, including PUT or POST. The example below shows how to make a POST request to the Jira expression API to test if an issue has more than 25 characters in the description and if so, to set some text in the summary field.

const body = `{
    "expression": "issue.description.plainText.length >25",
    "context": {
        "issue": {
            "key": "DEMO-1" // Specify the Issue key to test agains
        },
        "project": {
            "key": "DEMO" // Specify the project key here for the project of the issue being tested against
        }
    }
}`;
 
const res = await makeRequest("/rest/api/3/expression/eval?expand=meta.complexity", {
method: "POST",
headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
body: body
});
 
if(res.body.value === false){
    getFieldById("summary").setValue("Description field has less than 25 characters");
}else{
    getFieldById("summary").setValue("Description field has more than 25 characters");
}

Logs

A logger is available, which will allow admins to view logs on the log page. This can be accessed by using the logger object.

Using the logger allows you to read the logs from your scripts inside the ScriptRunner Logs page.

For example:

logger.info("hello world");

Available functions - each method takes a string parameter:

  • warn(msg)

  • debug(msg)

  • info(msg)

  • trace(msg)