In this page

What is ScriptRunner?

(supported since Better PDF Exporter 1.5.0)

ScriptRunner is the most powerful app to extend and customize Jira with every kind of custom logic, expressed as Groovy scripts.

ScriptRunner integration features

  • You can export the ScriptRunner-managed custom script fields to PDF. (These are the fields which are powered by Groovy script written by you, giving you unlimited flexibility.)

(Need more features? Tell us in a support ticket!)

Tutorial video

The integration between Better PDF Exporter and ScriptRunner supports exporting ScriptRunner-managed fields to PDF. (Although the video below was captured about the app's Server version, the Cloud version is very similar.)

ScriptRunner PDF export samples

Issue with built-in script fields

ScriptRunner enables implementing custom fields whose values are programatically updated by scripts, in response to events like a workflow transition. In this sample, these are exported to the ScriptRunner Fields section, automatically formatted as date, number, etc. depending on their data types.

jira-scriptrunner-built-in-script-fields-export.pdf

Issue list with custom script fields

In addition to the event-driven script fields, ScriptRunner enables you to create fields that are powered by periodically executed Groovy scripts. Use these to synchronize data from your CRM system to Jira, to implement escalation processes, and so on. Without any further configuration, Better PDF Exporter will correctly export your custom field values to PDF!

jira-scriptrunner-custom-script-fields-export.pdf

Configuration

Configuring the ScriptRunner script fields

There is nothing to do. Better PDF Exporter will automatically recognize the script fields, and export them accordingly.

In fact, ScriptRunner does not introduce its own custom field types in Jira Cloud! This is a major difference between ScriptRunner's server and cloud versions.

Instead, ScriptRunner suggests the following technique to implement script fields in Jira Cloud:

  1. Use the built-in Jira custom field type that matches your data type (text, number, etc.).
  2. Use a script listener triggered by the Issue Updated and other webhook events (the events that require the field's value be updated).
  3. Execute a Groovy script in response to the event, and update the field value via the Jira REST API.

This way, you can easily update the script field's value at the events that affect that. Note that because this technique relies on the built-in custom field types, the script fields implemented this way will be correctly exported to PDF without any further configuration!

Example: exporting the last comment using a script field

The following example demonstrates how to use a ScriptRunner script listener to automatically copy the issue's last comment to the custom field "Last comment". The script finds the custom field by its name, loads all comments of the issue, then updates the field with the last comment's body text, all via the Jira REST API. After, you can export this field just like any other field to PDF.

Steps:

  1. Go to Jira and create a new custom field with the type "Text Field (multi-line)" and the name "Last comment".
  2. Add the custom field to the issue types you want to use it with.
  3. Click the cog icon "⚙" in the top right → AppsScript Listeners (under ScriptRunner).
  4. Create a new script listener with these settings:
    • Set the name to "Last comment listener".
    • Select the triggering events: Comment Created, Comment Deleted and Comment Updated.
    • Set this code:
      import java.text.SimpleDateFormat
      
      def outputCfName = 'Last comment'
      
      // -----------------------------------------
      
      def customFields = get('/rest/api/2/field')
              .asObject(List)
              .body
              .findAll { (it as Map).custom } as List<Map>
      def outputCfId = customFields.find { it.name == outputCfName }?.id
      
      def dateTimeFormatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");
      def result = get("/rest/api/2/issue/${issue.key}/comment")
              .header('Content-Type', 'application/json')
              .asObject(Map)
      if (result.status == 200) {
          def lastCommentBody = result.body.comments?.sort { a, b -> dateTimeFormatter.parse(a.created) <=> dateTimeFormatter.parse(b.created) }?.last().body
          return put("/rest/api/2/issue/${issue.key}")
              .header('Content-Type', 'application/json')
              .body([
                  fields:[
                      (outputCfId): lastCommentBody
                  ]
              ])
              .asString()
      } else {
          logger.error("Error retrieving issue comments ${result}")
      }
      
  5. Add a new comment to an issue that has the "Last comment" custom field configured for.
  6. Wait some seconds, because it takes a little for ScriptRunner to catch the event and run the script.
  7. Refresh the browser and check if the custom field contains the comment's text.
  8. Export the issue to PDF using any template, and voila: the last comment is correctly exported!

Note: the script above is written for demonstration purposes only, therefore it does not handle paging of comments or specific error cases.

For more script field examples, see the ScriptRunner user manual.

Learn more about ScriptRunner