Behaviours API

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

Read/update fields

Access a field

All supported fields can be accessed by using getFieldById(fieldID).

For example:

js
const theDescription = getFieldById("description")
theDescription.setName("The description name");
const theValue = "the value is " + theDescription.getValue();
logger.info(theValue);

Accessing custom fields

• Custom fields cannot be accessed by their field name and instead have to be accessed by their ID e.g customfield_01232

• The ID of the custom field can be found by either utilising the Jira Cloud REST API to make a request to the field endpoint https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-fields/#api-rest-api-3-field-get such as https://YOUR_ATLASSIAN_INSTANCE/rest/api/3/field

• When selecting a custom field as the affected field, the custom field ID will display at the top of the Create modal screen.
  

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:

js
const changedField = getChangeField()
if(changedField.getName() == "summary") {
	logger.info("The summary has changed!");
}

Available read methods

It is important to note that these methods are only accessible on the object returned by getFieldById.

getContext

{ 
    localId: string, 
    cloudId: string, 
    enviroment: string, 
    moduleKey: string, 
    siteUrl: string, 
    accountId: string, 
    licence: string, 
    timeZone: string, 
    extension: { 
        viewType: string, 
        issueType: { 
            id: string, 
            name: string 
        }, 
        project: { 
            id: string, 
            key: string, 
            type: string
        }
    }
}

        issue: { 
            id: string, 
            key: string, 
        }

js
const context = await getContext()

js
const context = await getContext()
context.accountId

Access the project key of the current project.

js
const context = await getContext()
context.extension.project.key

Access the ID of the current issue type.

js
const context = await getContext()
context.extension.issueType.id

Access the current issue key when on an issue view

js
const context = await getContext()
context.extension.issue.key

getDescription

Returns the description of the field

Return type: String

js
getFieldById("summary").getDescription()

getId

Returns the id of the field

Return type: string

js
getFieldById("summary").getId()

getName

Returns the name of a field

Return type: String

js
getFieldById("summary").getName()

getOptionsVisibility

Returns the options that are visible for a field.

Return Type: Object

{options: Array<string>, isVisble: boolean}

Supported Fields:

• Priority
• Issue Type
• Select List Fields
• Multi-Select List Fields
• Checkbox Fields

js
getFieldById("priority").getOptionsVisibility()

js
getFieldById("issuetype").getOptionsVisibility()

Note:  This method works for On Change events only and always returns undefined for On Load events.

getType

Returns the type of the field.

Return type: string

js
getFieldById("summary").getType()

getValue

Returns the value of a field. The return type depends on the field you’re updating:

javascript
// returns Affects versions
const versions = getFieldById("versions"); 
versions.getValue();

//example return value
{id: "10001", name: "2"}

javascript
const assignee = getFieldById("assignee");
assignee.getValue();

//example return value
{accountId: "dfqsw43ref"}

javascript
getFieldById("customfield_10035").getValue()

// example return value
Parent 1 - Child 1.1

javascript
const components = getFieldById("components");
components.getValue();

//example return value
{id: "1234", name: "Component One"}

javascript
const checkboxValue = getFieldById("customfield_02133").getValue();  


//example return value
[{"id":"10021","value":"A"},{"id":"10022","value":"B"}]

javascript
const date = getFieldById("customfield_02136").getValue();  

//example return value
"2023-11-14"

javascript
const dateTime = getFieldById("customfield_10035”).getValue();

//example return value 
"2024-03-13T15:30+03:00"

javascript
const userPicker = getFieldById("customfield_10984");
userPicker.getValue();

//example return value
[{accountId: "394urfjj9r2",},{accountId: "432-jftpwer0",},]

javascript
const multipleSelect = getFieldById("customfield_01232");
multipleSelect.getValue();

//example return value 
[{id: "12345", value: "helloWorld",}, {id: "67890",value: "fooBar",}] 

javascript
const number = getFieldById("customfield_02138").getValue();  

//example return value
100

javascript
// string is for Plain-text editor
// Rich-text editor (ADF format)
type ParagraphField = {
	string | ADParagraphField
}

javascript
const radiobutons = getFieldById("customfield_02134").getValue();  

//example return value
"10021"

javascript
const singleSelect = getFieldById("customfield_01231");
singleSelect.getValue();

//example return value
{id: "12345",value: "helloWorld",} 

javascript
const url = getFieldById("customfield_02135").getValue();  


//example return value
"https://www.adaptavist.com"

javascript
const userPicker = getFieldById("customfield_10984");
userPicker.getValue();

//example return value
{accountId: "394urfjj9r2",}

javascript
// We return a string or ADF (Atlassian Doc Format), depending on your Jira configuration
type ADF = {
    version: 1,
    type: 'doc',
    content: Node[]
}

javascript
// returns due date
const dueDate = getFieldById("duedate").getValue();  

//example return value
"2024-11-05"

javascript
const fixVersions = getFieldById("fixVersions");
fixVersions.getValue();

//example return value
{id: "1234", name: "version One"}

javascript
const issueType = getFieldById("issuetype"); 
issueType.getValue();

//example return value
{id: "1234", name: "Task"}

javascript
const originalEstimateField = getFieldById("timeoriginalestimate");
originalEstimateField.getValue();

//example return value
4 | null

javascript
const parentField = getFieldById("parent"); 
parentField.getValue();

//example return value 
{ id: "10001", key: "DEMO-1000" } | null

javascript
const priority = getFieldById("priority"); 
priority.getValue();

//example return value
{id: "12345", name: "test"}

javascript
const projectPicker = getFieldById("customfield_10001"); 
projectPicker.getValue();

//example return value
{projectId: "10899"}

javascript
const reporter = getFieldById("reporter");
reporter.getValue();

//example return value
{accountId: "dfqsw43ref",}

javascript
// returns StatusField
const statusField = getFieldById("status"); 
statusField.getValue();

//example return value
{id: "12345", name: "test"}

javascript
getFieldById("summary").getValue()

javascript
// returns target end date
const targetEnd = getFieldById("customfield_10023").getValue();  

//example return value
"2024-11-05"

javascript
// returns target start date
const targetStart = getFieldById("customfield_10022").getValue();  

//example return value
"2024-11-05"

isCreateView

Returns whether or not the current view is the Create View.

Return type: boolean

js
if(isCreateView()){
    getFieldById("summary").setValue("This code works only on the Create View");
}

isIssueView

Returns whether or not the current view is the Issue View.

Return type: boolean

js
if (isIssueView()){
    getFieldById("summary").setValue("This code works only on the Issue View")
}

isTransitionView

Returns whether or not the current view is the Transition View.

Return type: boolean

js
if(isTransitionView()){
    const descriptionField = getFieldById("description");

    descriptionField.setValue({
        version: 1,
        type: "doc",
        content: [
            {
                type: "paragraph",
                content: [
                    {
                        type: "text",
                        text: "This code works only on the Transition View"
                    }
                ]
            }
        ]
    });
}

isReadOnly

Returns whether the field has been set as read-only.

Return type: boolean

js
getFieldById("summary").isReadOnly()

isRequired

Returns whether or not the field is required.

Return type: boolean

js
getFieldById("summary").isRequired()

isVisible

Returns whether the field has been hidden.

Return type: boolean

js
getFieldById("summary").isVisible()

Available write methods

It is important to note that these methods are only accessible on the object returned by getFieldById and getChange.

setDescription(desc)

Updates the field description.

Parameter: desc

Parameter type: string

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

setName(name)

Updates the field name.

Parameter: name

Parameter type: string

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

setOptionVisibility(options,isVisible)

Updates the values that are selectable in a field.

Parameter:  options

Parameter type: Array<string> - Strings of the option value IDs

Parameter:  isVisible

Parameter type: boolean

Note: setting isVisible to true shows the specified option values in the field only, whereas false hides the specified option values in the field.

js
getFieldById("priority").setOptionsVisibility(["1","2"], true)

js
getFieldById("issuetype").setOptionsVisibility(["12345","67890"], true)

setReadOnly(readable)

Sets a field to read-only.

Parameter: readable

Parameter type: boolean

js
const summary = getFieldById("summary").setReadOnly(true)

setRequired(required)

Updates a field as to whether or not it should be required.

Parameter: required

Parameter type: boolean

js
getFieldById("summary").setRequired(true)

setValue(value)

javascript
getFieldById("versions").setValue(["10000","10001"])

javascript
const assignee = getFieldById("assignee")assignee.setValue("5556634")

javascript
getFieldById("customfield_10054").setValue({
  parentId: "1030",
  childId: "1031"
})

javascript
getFieldById("components").setValue(["12345","56789"])

javascript
const checkbox = getFieldById("customfield_02133").setValue(['10021','10022'])

javascript
const datePicker = getFieldById("customfield_02136").setValue('2023-11-14')

javascript
const multipleSelect = getFieldById("customfield_01232")
multipleSelect.setValue(["4", "5"])

javascript
const multiUserPicker = getFieldById("customfield_012322")
multiUserPicker.setValue(["557058:db4467a5-32f3-48f9-be3b-687a1bc0468c", "712020:b81688df-0c5d-44cb-bc11-315f0e8e4390"])

javascript
const numberField = getFieldById("customfield_02138").setValue(100')

javascript
// Plain-text editor: | type ADF = {version: 1,  type: 'doc', content: Node[]} // Rich-text editor (ADF format)//

javascript
const radioButtons = getFieldById("customfield_02135").setValue('10021')

javascript
const singleSelect = getFieldById("customfield_01231")
singleSelect.setValue("3")

javascript
const urlField = getFieldById("customfield_02134").setValue("https://www.adaptavist.com")

javascript
const singleUserPicker = getFieldById("customfield_012321")
singleUserPicker.setValue("557058:db4467a5-32f3-48f9-be3b-687a1bc0468c")

javascript
const dueDate = getFieldById("duedate").setValue("2024-11-05")

javascript
getFieldById("fixVersions").setValue(["12345","56789"]) 

javascript
getFieldById("issuetype").setValue("12345")   

javascript
getFieldById("timeoriginalestimate").setValue(4)

javascript
getFieldById("parent").setValue("10001")

javascript
const priority = getFieldById("priority")priority.setValue("2")

javascript
getFieldById("customfield_10001").setValue("10899")

javascript
getFieldById("reporter").setValue("1234-3434-324234") 

javascript
getFieldById("status").setValue("10")

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

javascript
const targetEnd = getFieldById("customfield_10023").setValue("2024-11-05")

javascript
const targetStart = getFieldById("customfield_10022").setValue("2024-11-05")

setVisible(visible)

Updates the visibility of the field.

Parameter: visible

Parameter type: boolean

js
getFieldById("summary").setVisible(false)

Behaviours on screen tabs

It is important to note that all Behaviours on screen tabs methods are only accessible on the object returned by getScreenTabById.

js
type ScreenTab = {
    getId: () => string;
    isVisible: () => boolean;
    setVisible: (isVisible: boolean) => void;
    focus: () => void;
}

getId

Returns the screen tab identifier.

Return type:  string

js
getId(): string

isVisible

Returns true if the tab is currently visible. Returns false otherwise.

Return type:  boolean

js
isVisible(): boolean

setVisible

Changes tab visibility.

Return type:  void

js
setVisible(value: boolean): ScreenTabAPI

tab.setVisible(false);

focus

Switches the focus to a given screen tab. Automatically puts other visible tabs out of focus.

Return type:  void

js
focus(): ScreenTabAPI

tab.focus();

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:

js
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.

js
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)