SPI Tools for workflows

On this page:

1 SPI Tools API reference
2 Usage
3 Unhandled arguments
4 Error handling

SPI Tools API reference

If you need more technical information on the latest SPI Tools packages, please read the complete API reference.

Usage

Conditions, validators, and post-functions may have arguments that hold identifiers of different configuration elements in Jira. When these workflows are moved from one instance of Jira to another, those identifiers will most likely differ. It is also possible that the referenced configuration element may not even exist on the Jira instance where the Configuration Manager snapshot is being deployed. Let's look at an example of how to describe such arguments using SPI Tools, which will allow Configuration Manager to take care of all the hard work of creating the configuration elements and storing the correct identifiers or names.

The first thing we need to do is extend the AbstractWorkflowParticipantHandler class from SPI Tools and implement describeArguments(). This is an abstract implementation of WorkflowParticipantHandler, which provides the DSL for describing arguments.

@Override
protected void describeArguments() {
    condition("org.example.jira.MyConditionClass").
        hasMultiValueArgument("statusIds").ofType(ArgumentType.STATUS).byId().
            .withSeparator(",").withLiteralValues("none").and().
        hasSingleValueArgument("user").ofType(ArgumentType.USER).byKey();
}

In the example above, we instruct Configuration Manager that there is a condition with class org.example.jira.MyConditionClass, which has two arguments:

statusIds argument, which holds a comma-separated list of status identifiers and can also hold the value "none", which must be treated as a literal and not as a status identifier
user argument, which holds the key of a user in Jira

Configuration Manager will take care of parsing the argument values on export and re-constructing them on import.

Notice the usage of and() to chain the syntax declaration for the different arguments.

The last step is to declare the class in the atlassian-plugin.xml.

Unhandled arguments

If you need specific handling for a given argument, you can always override the transformUnhandledArgumentForExport() and transformUnhandledArgumentForImport() methods.

Error handling

The method handleError() will be invoked for any exception caught during a transformation of arguments. The default implementation will simply log the error. In this case, the untransformed value will be used for this argument.