State Transitions

Introduction

Once you've configured your Person Reconciliation strategy, your next step will be to configure State Transitions, if your repository utilizes state transitions or workflows.  

Some repositories require that a state transition be performed in order to update the value of certain fields (for example, when an artifact must move from a status of New to In Progress to Closed, but cannot move directly from New to Closed).  If state transitions are supported for your repository, you will see a State Transition sash at the bottom of the Collection Configuration screen.

You can also review our  Connector Docs to see if state transitions are supported for the repository you are connecting to.

Instructions

If state transitions are supported for your repository, you will see a State Transition sash at the bottom of the Collection Configuration screen:

To set a state transition, click 'Configure State Transitions.'  This will lead you to the State Transition screen.  Click '+New State Transition.'

This will lead you to the New State Transition Screen.  Here you can name your transition and choose between two State Transition Types:

• Transition Graph (Recommended)
• Extension

Transition Graph 

To configure state transitions within Tasktop's UI, select 'Transition Graph' as your State Transition Type.

Next, you'll select the repository field you'd like to apply the transition to.

 If you don't see the field you'd like to utilize, make sure that the field is mapped and that its transform is set to 'copy' on the repository side.  Once you set the transform to 'Copy,' you will see a 'Configure State Transition' link.  Click that to return to the State Transition screen.

Now you can select that field on the New State Transition screen:

 If you encounter a 'Read-Only' error when selecting this field, please ensure the Field Flow frequency for this field is set to 'No Update' on the Field Flow screen.

Now that you've selected your field, you'll see the Transition Configuration Panel on your screen:

You can use the 'New Transition' pane to configure your state transitions within Tasktop's UI.  In order for your integration to work, these must be configured to match the configuration within the repository itself exactly.

When entering values in the 'From State' and 'To State' fields, the values should match the values within the repository (not the model).  They must be entered exactly as they appear in the repository, and are both case sensitive and space sensitive.  The 'Transition Name' must also match the transition name that is configured within the repository exactly.

Here is an example of a transition that has been configured.  Note that when you view a transition (by clicking on it in the graph), you'll see its configuration on the right so that you can make any needed modifications.  You'll also see a 'New Transition' pane immediately underneath, so that you can add additional transitions.

 Note: Multiple transitions between two states in a single direction are not supported. Only a single transition to and/or from two individual states can be configured. Transitions that loop over a single state are also not supported. 

Parameters

If your transition requires a parameter, you can add it by clicking 'Add Parameter.'

The Parameter name must match the field name within the repository exactly.  You can either set a constant value for your parameter, or configure the transition to flow a value based on your field mappings. 

In the image below, we've set a constant value, which will tell Tasktop to add a "Re-opened" tag to the artifact when it moves through the 'Re-open' transition:

You can also set a Parameter that is set based on a field in the model:

To map the field, you can click the 'map' icon:

This will bring you to the Parameter Field Value Mappings pop-up:

Here you can manually enter the parameter field values on the left that exist within your repository, and map them to the model fields on the right. The field values entered must match the field values that exist in the repository exactly (they are case- and space- sensitive).

After you have completed mapping your field values, click 'Apply' to apply your changes.

Saving and Viewing

 Here's an example of a completed Transition Graph:

Make sure that your completed graph matches the state transition configuration in your repository exactly.  If it does not match, you will see errors when running the integration.  Once confirmed, click 'Save' and 'Done.'  

You will then be able to see your State Transition on the State Transition screen:

You will also notice a state transition icon on the collection pill on the Field Mapping screen, to denote that a transition graph is being utilized:

Extensions  

In order to successfully flow field values for fields that require state transitions, a state transition extension can also be set. 

If you choose to configure state transitions via an extension, rather than utilizing the transition graph, your first step will be to create and save the extension itself from the Settings screen.  If you need help creating the extension, you can find more information in the Extensions (Settings) section.

Once the extension is configured, you can select 'Extension' as the State Transition Type on the New Transition Screen:

Next, select the model field(s) that you'd like to apply the extension to:

You can then select the extension you'd like to use:

Click 'Save' and then 'Done.'  You'll now see the State Transition Extension listed on the State Transition screen:

And you'll notice the state transition icon on the model pill and the model drop-down on the Field Flow screen:

You'll also see it listed at the top of the screen when you view the Field Mapping Configuration screen for that field:

 Note: When using a State Transition Extension, the Transform settings of the Status configuration needs to be set from 'Copy' to 'None' on the repository side. This can be done in the Field Mapping screen. Click 'Save' and then 'Done.'  

 Note that the extension will only impact how data flows from the model to the repository (Jira in this case).  If you would like impact how data flows from the repository to the model (and then to whichever target collection is connected on the other side), you will need to configure the field appropriately.  If you would like to use a state transition extension on the other side, you must configure that on the corresponding collection's State Transition screen.

Next Steps

Now that your State Transitions are configured, your collection configuration is complete.  Once all the collections you'd like to utilize in your integration are set up, it's time to move on to Step 4: Configure your Integration.