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:

• Cascading Select:
  type: null | { parent: { id: string; value: string };
    child: { id: string; value: string } | null;
}

  js
  getFieldById("customfield_10035").getValue()
  
  // example return value
  Parent 1 - Child 1.1

• Original Estimate:
  type: number|null

  js
  const originalEstimateField = getFieldById("timeoriginalestimate");
  originalEstimateField.getValue();
  
  //example return value
  4 | null

• Summary:
  type: string

  js
  getFieldById("summary").getValue()
  

  
  

• Description:
  type: string | ADF 

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

  More details about ADF: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

• Labels:
  type: string[]
  
  

• PriorityField
  type: {id: string, name: string, iconUrl?: string, }
  

  js
  const priority = getFieldById("priority"); 
  priority.getValue();
  
  //example return value
  {id: "12345", name: "test"}

• AssigneeField
  type:  null | { accountId: string, }

  js
  const assignee = getFieldById("assignee");
  assignee.getValue();
  
  //example return value
  {accountId: "dfqsw43ref"}

• ReporterField
  type:  null | { accountId: string, }

  js
  const reporter = getFieldById("reporter");
  reporter.getValue();
  
  //example return value
  {accountId: "dfqsw43ref",}

• FixVersionsField
  type: { id: string, name: string }

  js
  const fixVersions = getFieldById("fixVersions");
  fixVersions.getValue();
  
  //example return value
  {id: "1234", name: "version One"}

• ComponentsField
  type: { id: string, name: string }

  js
  const components = getFieldById("components");
  components.getValue();
  
  //example return value
  {id: "1234", name: "Component One"}

• IssueTypeField =
  type: { id: string, name: string }
  

  js
  const issueType = getFieldById("issuetype"); 
  issueType.getValue();
  
  //example return value
  {id: "1234", name: "Task"}

• Parent Field
  type: { id: "10001", key: "DEMO-1000" } | null

  js
  const parentField = getFieldById("parent"); 
  parentField.getValue();
  
  //example return value 
  { id: "10001", key: "DEMO-1000" } | null

• Custom SelectField
  type: null | {id: string, value: string,}

  js
  const singleSelect = getFieldById("customfield_01231");
  singleSelect.getValue();
  
  //example return value
  {id: "12345",value: "helloWorld",} 

• Custom MultipleSelectField
  type: { id: string, value: string,}[]

  js
  const multipleSelect = getFieldById("customfield_01232");
  multipleSelect.getValue();
  
  //example return value 
  [{id: "12345", value: "helloWorld",}, {id: "67890",value: "fooBar",}] 

• Custom UserPickerField=
  type: null | { accountId: string,} }

  js
  const userPicker = getFieldById("customfield_10984");
  userPicker.getValue();
  
  //example return value
  {accountId: "394urfjj9r2",}

• Custom MultiUserPickerField
  type: {accountId: string }[]

  js
  const userPicker = getFieldById("customfield_10984");
  userPicker.getValue();
  
  //example return value
  [{accountId: "394urfjj9r2",},{accountId: "432-jftpwer0",},]

• Custom paragraph
  type: ParagraphField
  

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

  More details about ADF: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/

• Custom text field
  type: string
  
  

• Custom checkbox fields
  type: { id: string, value: string,}[]

  js
  const checkboxValue = getFieldById("customfield_02133").getValue();  
  
  
  //example return value
  [{"id":"10021","value":"A"},{"id":"10022","value":"B"}]

• Custom Radio Buttons Field
  type: string | null

  js
  const radiobutons = getFieldById("customfield_02134").getValue();  
  
  //example return value
  "10021"

• Custom Url Field
  type: string | null
  

  js
  const url = getFieldById("customfield_02135").getValue();  
  
  
  //example return value
  "https://www.adaptavist.com"

• Custom Date Picker Field
  type: string | null
  

  js
  const date = getFieldById("customfield_02136").getValue();  
  
  //example return value
  "2023-11-14"

• Custom Date Time Picker Field
  type: string | null
  

  js
  const dateTime = getFieldById("customfield_10035”).getValue();
  
  //example return value 
  "2024-03-13T15:30+03:00"

• Custom URL Field
  type: string | null

  js
  const url = getFieldById("customfield_02137").getValue();  
  
  //example return value
  "https://adaptavist.com"

• Custom Number Field
  type: string | null

  js
  const number = getFieldById("customfield_02138").getValue();  
  
  //example return value
  100

• Status
  type: {id: string, name: string }

  js
  // returns StatusField
  const statusField = getFieldById("status"); 
  statusField.getValue();
  
  //example return value
  {id: "12345", name: "test"}

• Affects versions
  type: {id: string, name: string }

  js
  // returns Affects versions
  const versions = getFieldById("versions"); 
  versions.getValue();
  
  //example return value
  {id: "10001", name: "2"}

• Due date
  type: string | null


  js
  // returns due date
  const dueDate = getFieldById("duedate").getValue();  
  
  //example return value
  "2024-11-05"

• Target start date
  type: string | null


  js
  // returns target start date
  const targetStart = getFieldById("customfield_10022").getValue();  
  
  //example return value
  "2024-11-05"

• Target end date
  type: string | null


  js
  // returns target end date
  const targetEnd = getFieldById("customfield_10023").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")
}

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)

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

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

• Custom Url Field
  string
  

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

• Custom Date Picker Field
  string - Format must be yyyy-mm-dd

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

• Custom Number Field
  number
  

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

• Status
  setValue(transitionId: string ) // String of transition ID

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

• Due date
  string - Format must be yyyy-mm-dd

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

• Target start date
  string - Format must be yyyy-mm-dd

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

• Target end date
  string - Format must be yyyy-mm-dd

  js
  const targetEnd = getFieldById("customfield_10023").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)