Jira workflow condition (preview)

The jira:workflowCondition module creates a workflow condition that can be configured on workflow transitions in company-managed projects (see: Advanced workflow configuration).

Conditions control whether the user can execute a transition. If a condition fails, the user won't be able to execute the transition. For example, the user won't see the transition button on the View issue page.

Condition based on a Jira expression

You can use Jira expressions to evaluate the condition result.

For example, a condition that checks if the issue is assigned would look like this:

1
2
jira:workflowCondition:
  - key: my-forge-workflow-condition
    name: Issue is assigned condition
    description: This condition allows executing the transition if the issue has an assignee.
    expression: issue.assignee != null

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

• 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 condition has been uninstalled

Context variables

The following context variables are available to expressions:

• user (User): The user the condition is evaluated for.
• issue (Issue): The issue selected for the transition.
• project (Project): The project the issue belongs to.
• transition (Transition): The transition that the condition is being evaluated against.
• workflow (Workflow): The workflow that contains the condition.
• config (JSON): The configuration saved on the configuration page with custom UI Jira bridge.
• groupOperator (String): The logical operator for a group the condition belongs to. Possible results are: AND, OR, or null. The null is returned if there is only one condition in the transition.

Additionally, these are available for Jira Service Desk transitions:

• customerRequest (CustomerRequest): The customer request selected for transition.
• serviceDesk (ServiceDesk): The service desk the customer request belongs to.

Adding condition configuration with custom UI

Expression-based workflow conditions often require some degree of the configuration of their behavior. For example, you may want to allow a user to transition the issue to a specific state only if the user is in a particular group and you want the project admin to configure that group. 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 condition is first created
• the form that is shown when a workflow condition 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 condition. In order to persist this information in Jira, the page needs to use the workflowRules API.

When evaluating the condition, 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.conditionConfig key in the context object returned from the getContext API in the custom UI bridge.

Example

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

1
2
jira:workflowCondition:
  - key: my-forge-workflow-condition
    name: Issue is assigned condition
    description: This condition allows executing the transition if the issue has an assignee.
    expression: issue.assignee != null
    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.conditionConfig)
    });
  }, []);
}

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);
};

Properties

Jira expressions events

Whenever an app-registered Forge workflow condition 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.