Jira workflow validator (Preview)

The jira:workflowValidator module defines a validator that can be added to workflow transitions in company-managed projects (see: Advanced workflow configuration).

Validators check that any input made to the transition is valid before the transition is performed. In this case, input also refers to data entered by the user on the transition screen. If a validator fails, the work item does not progress to the destination status of the transition, the transition's post functions are not executed, and the error message of the failed validator is shown.

Validators added by Forge apps are implemented with:

• Jira expressions that are provided upfront in the manifest or built dynamically on the configuration page
• lambda functions

Validating with Jira expressions

The work item validated by the Jira expression includes changes made on the transition screen, which makes this way of defining validators particularly suitable for cases where the state to validate can be modified during the transition.

A workflow validator only evaluates to true if the provided Jira expression evaluates to true. It will evaluate to false in all other cases, including:

• the Jira expression fails to evaluate because of errors or returns anything other than a Boolean value (in this case, an avi:jira:failed:expression event is sent)
• the app providing the workflow validator is uninstalled

If the expression returns a string value, that value will be shown as the error message on the transition.

Example

A validator that checks if the work item is assigned would look like this:

1
2
modules:
  jira:workflowValidator:
    - key: my-forge-workflow-validator
      name: Work item is assigned validator
      description: This validator allows the transition where the work item has an assignee.
      expression: issue.assignee != null
      errorMessage: "The transition failed because no one is assigned to the task. Assign the task to a user and try again."

Context variables

The following context variables are available to expressions:

• user (User): The user who performs the transition.
• issue (Work item): The work item that is about to be transitioned. Includes changes made on the transition screen.
• originalIssue (Work item): The work item before changes were made on the transition screen. This variable is not available when validator is defined for the initial transition.
• project (Project): The project the work item belongs to.
• transition (Transition): The transition that the validator is being evaluated against.
• workflow (Workflow): The workflow that contains the validator.
• config (JSON): The configuration saved on the configuration page with custom UI Jira bridge.

Additionally, these are available for Jira Service Desk transitions:

• customerRequest (CustomerRequest): The customer request that is about to be transitioned.
• serviceDesk (ServiceDesk): The service desk the customer request belongs to.

Adding validator configuration with custom UI

Expression-based workflow validators often require some degree of the configuration of their behavior. For example, you may want to allow a state transition only if the work item has a particular label, and you want the project administrator to configure that label. For this purpose, three additional properties in the manifest allow you to declare the custom UI resources that will show:

• the form that is shown when a workflow validator is first created
• the form that is shown when a workflow validator is edited
• the read-only view or summary of the configuration

The create and edit pages should present a form with configuration relevant to the validator. In order to persist this information in Jira, the page needs to use the workflowRules API.

When evaluating the validator, the configuration saved that way will be available to the Jira expression under the config context variable.

The config context variable is stored under the extension.validatorConfig key in the context object returned from the getContext API in the custom UI bridge.

Example

To create a validator that displays the custom UI, declare it in the manifest as follows:

1
2
modules:
  jira:workflowValidator:
    - key: my-forge-workflow-validator
      name: Work item summary contains text validator
      description: This validator allows the transition where the summary of an work item contains the text defined on the workflow validator configuration page.
      expression: "issue.summary.includes(config['key']) == true"
      edit:
        resource: edit-resource
      create:
        resource: create-resource
      view:
        resource: view-resource
resources:
  - key: create-resource
    path: static/create/build
  - key: edit-resource
    path: static/edit/build
  - key: view-resource
    path: static/view/build
permissions:
  scopes:
    - manage:jira-configuration

To get the product context in the create, edit, and view resources defined in the manifest, use view.getContext function.

1
2
import { view } from '@forge/bridge';

function App() {
  const [context, setContext] = useState();
  const [config, setConfig] = useState();

  useEffect(() => {
    view.getContext().then(ctx => {
      setContext(ctx);
      setConfig(ctx.extension.validatorConfig)
    });
  }, []);
}

To save the user input to the config context variable, pass the callback function returning stringified JSON to the workflowRules.onConfigure function.

1
2
import { workflowRules } from '@forge/jira-bridge';

const onConfigureFn = async () => {
  var config = {
    'key': 'value'
  };

  return JSON.stringify(config);
};

// calling onConfigure from async function
try {
  await workflowRules.onConfigure(onConfigureFn);
} catch (e) {
  // Handle the error.
}

// calling onConfigure from non-async function
workflowRules
    .onConfigure(onConfigureFn)
    .catch(e => {
        // Handle the error.
    });

Overriding Jira expression

Additionally, you can override the entire Jira expression from the manifest. To do that, include the expression property in the returned JSON. For example:

1
2
const onConfigureFn = async () => {
  var config = {
    "expression": "dynamically built expression"
  };

  return JSON.stringify(config);
};

New workflow editor

The new workflow editor supports this module in the same way. You can use same custom UI resources and the same functions for managing configuration.

If you want to detect whether the new editor is being used, check for whether the key extension.isNewEditor is true in the object returned from the view.getContext function. This key will be unset in the old workflow editor.

1
2
import { view } from '@forge/bridge';

const context = await view.getContext();
const isNewEditor = context.extension.isNewEditor || false;

Validating with lambda functions

A function must be declared in the manifest and configured for a given validator. It is then invoked on every transition to which the validator has been added. When the function is invoked, an argument it passed to it with the following information about the transition:

1
2
{
  "issue": {
    "key": "work item key"
  },
  "transition": {
    "from": {
      "id": "status id"
    },
    "to": {
      "id": "status id"
    },
    "modifiedFields": {
      "labels": null,
      "customfield_10020": "Text input",
      "customfield_10021": {
        "self": "https://your-domain.atlassian.net/jira/rest/api/3/customFieldOption/10001",
        "value": "Single select option",
        "id": "10001"
      },
      "description": {
        "type": "doc",
        "version": 1,
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Completely new description"
              }
            ]
          }
        ]
      }
    }
  }
}

The function returns an object containing two properties:

• result - a Boolean value indicating whether the transition is allowed
• errorMessage - the error message to show if the result is false. Otherwise, this property is ignored and doesn't have to be included

Modified Fields

The modifiedFields section contains the updated values of fields that were changed during the work item transition. These fields are presented in the same format as those in the REST API v3: Get issue.

Specific details about certain fields include:

• Array-type fields set to empty or null during the transition will be represented as null in modifiedFields.
• For fields that contain user information, only the accountId is returned:

1
2
{
  "modifiedFields": {
    "assignee": {
      "accountId": "0000-0000-0000-0000"
    }
  }
}

Supported field types

Modified fields are available for field types listed below.

System fields:

• Affects Version
• Fix Version
• Component
• Description
• Assignee
• Resolution
• Priority
• Work Type
• Labels
• Linked Issues
• Comment

System custom fields:

• Team
• Sprint
• Parent
• Text Field
• Text Area
• User Picker
• Multi-User Picker
• Date Picker
• Date-Time
• Labels
• Select
• Multi-Select
• Cascading Select
• Multi-Checkboxes
• Radio Buttons
• URL
• Float

All Forge custom fields

Scopes

The OAuth 2.0 scope read:jira-work must be granted to the app to ensure that modifiedFields are attached; otherwise, they won't be included.

Example

To create a validator that allows transitions only for work items in the project with key PRO, declare it like this in the manifest:

1
2
modules:
  jira:workflowValidator:
    - key: my-forge-workflow-validator
      name: Project is PRO validator
      description: This validator will allow the transition only if the project is PRO.
      function: validate
  function:
    - key: validate
      handler: status.validate

To implement the actual logic in the src/status.js file:

1
2
export const validate = args => {
  const issueKey = args.issue.key;

  return {
    result: issueKey.startsWith('PRO'),
    errorMessage: 'Only PRO project can use this flow'
  };
}

Properties

i18n object

Jira expressions events

Whenever an app-registered Forge workflow validator based on a Jira expression fails while executing, an avi:jira:failed:expression event is sent.

You can subscribe to this event in Forge apps. If you want to use this feature you have to include the OAuth scope manage:jira-configuration in the app manifest.