...
Are you interested in using Project Configurator to migrate workflows that contain conditions, validators, or post-functions defined by a third-party app? Let's discover how easily this can be achieved.
Is the workflow app already supported?
Navigate to the list of supported workflow plugins. This list includes the most popular Jira apps for workflows, and there are new additions to it from time to time. If your third-party app is already supported, then you do not need to create a new extension and can start moving workflows that use this app immediately. If the app is not supported, follow the next steps with the help of an example based on the app Workflow Essentials for Jira.
Step 1: Create the workflow feature and export its XML descriptor
Install the third-party app in the Jira instance you will use to develop and test the extension, then create a workflow that has the conditions, validators, or post-functions (collectively, workflow functions) that you want to support with Project Configurator. In this guide, we focus on:
...
Open the XML file with your preferred editor and navigate to the section of the XML where the functions are defined.
Step 2: Implement interface HookPointCollection
Unless your extension already has another implementation of com.awnaba.projectconfigurator.extensionpoints.common.HookPointCollection, to which you can add the extensions for these workflow functions, create a new instance of this interface:
...
| Code Block | ||
|---|---|---|
| ||
@Profile("pc4j-extensions") @Component
public class WES4JExtensionModule implements HookPointCollection {
} |
Step 3: Implement the workflow extensions
DateCompareCondition
Analyze
Examine the workflow functions in the exported XML file. For example, start with the Date Compare condition. Looking in the XML, you will find the two occurrences of this condition:
...
There are no other references to other entities in Jira, so when you implement support for the "FIELD_ID" argument, you are finished with this condition. The default action for PCJ, when a workflow is migrated, is to transfer it to the other instance as it is; for all other elements in the condition that do not reference entities in Jira, you do not need to do anything.
Define location
In order to create the WorkflowHookPoint, you have to provide information about the location within the workflow descriptor of the string that this extension is dealing with. In this case, the location of this string may be described as "the text node under an 'arg' element that has an attribute called 'name', equal to 'FIELD_ID' under a 'function' element that has another 'arg' with attribute 'name' equal to 'class.name' that is equal to 'de.codecentric.jira.condition.DateComparisonCondition'. This description must be provided as an XPath v1 expression that identifies this location:
...
| Tip |
|---|
Don't know XPath? No problem! If you are not familiar with XPath, don't worry! You will have to learn yet another arcane piece of technology. As you will see, all the XPath expressions that you need to cover all your workflows are essentially the same, just with different values for the 'class.name' or 'name' attributes for the args, and then applying them for condition, validator, or function elements. Wait until you see another example! |
Define the content of the reference
You must specify the content of the string. We know the string contains either the internal name of a system field or the numeric ID of a custom field. As discussed before, when a system field is present, we can simply ignore it, as it is not necessary to do anything with it in the migration.
...
| Tip |
|---|
Code Notes
This class also has a builder that can be used like this: ...
... |
Assign specific user post-function
Let's look at this post-function, which will be the second extension to implement.
Analyze
This is an occurrence of this post-function inside a workflow descriptor:
...
This is similar to what we did with the Date Compare condition, so let's dive in.
Define location
As in any workflow extension, you have to specify the location of the reference string within the descriptor as an XPath:
...
Notice how the structure of this XPath location is similar to the one used for the previous condition.
Define the content of the reference
In this case, the reference consists of a single username. As in the previous extension, if you look at the Javadoc for SimpleReferenceProcessorFactory you will notice there is an option to retrieve a built-in ReferenceProcessor that handles plain user names.
...
| Tip |
|---|
Now test it! Your second workflow extension is completed now. Congratulations again! Refer to the tips in section 8 for ideas on how to test this extension. |
...