Skip to main content
System StatusContact Support

Documentation related to the following products will soon be moved to a new portal: ( Agility, Agility Connect and Agility Integrations Continuum and ALM Connect
Links from the site will automatically redirect to the new site.
If you have any questions, please contact Support. Agility Community

VersionOne Setup


For Continuum to communicate with the VersionOne web service we must first setup the connectivity.

Configure the VersionOne Plugin

In the Continuum UI, upper right menu, select Administration > Manage Plugins. Select VersionOne on the left and fill in the appropriate values.

The Name field is an arbitrary name for this instance.

API Token will be an Access Token for a user in VersionOne. This user will need the proper permissions to be able to query the API and the projects that are necessary.

Refer to Authorizing External Application Access. Be sure to select Access Token, not OAuth2.

The URL will need to include the protocol and port if not port 80 or 443 (https).

If using hosted VersionOne, the URL will be in the following format. No port is required, but https is.

Make sure to check the "Is Default?" box.

The information you enter will be saved as you leave each field, make sure to leave the last field before moving to a new page.

Test Connectivity

Click on the Test Connection button to test the connection to VersionOne.

Possible responses from the page:

  • "SUCCESS: Connected to VersionOne at address..." - all is well

  • "Connection refused" - wrong port or address was used

  • "VersionOne server did not accept the credentials provided" - user id or password is wrong

  • "Operation timed out" - a timeout, wrong port, address or firewall issue

  • "nodename nor servname provided, or not known" - wrong address or dns issue

  • "VersionOne plugin is not configured properly" - credentials and address worked, but VersionOne isn't responding properly. Contact

Setup the Project to look for Work Items in Commit Messages

A best development practice is to have all source repository commits associated with a ticket in an issue or planning management system. This is usually done by putting the ticket or issue identifier in the commit message with some sort of flag or pattern that sets it apart from the rest of the log message.

In Continuum we can setup the project to parse the commit log messages as they come in and find the Work Items based on regular expressions. This will create a connection to the Work Item in Continuum and associate the Changes with it.

To lookup VersionOne 'Assets' (Stories, Backlog Items, Defects, etc) from the commit messages of incoming changes, simply add a Directive to any Projects configured to accept changes from a repository.

Return to Project Management page (right hand menu, Flow > Manage Projects) and select your project. Go to the Source tab.

Add a new Directive (look for the button below the form). This will add it below any other in the list. We want it to be first in the list so grab the Directive in the upper left and drag it up to the top of the list if it is not already first.

Select the VersionOne Lookup Action, and make sure the When is set to Always. If there are more than one VersionOne instances defined, you can specify the Name of which configured instance to use. Instance is optional, and will use the Is Default instance if left blank.

Your Directive should look as follows.

Advanced Options

The VersionOne Lookup supports several additional arguments, all of which are optional and not frequently used.

Arguments can be added using the 'editor', or can be entered as JSON text using the 'text' mode. 

To add a new argument, under Args click [+] add. In the first column replace newKey with one of the following options. In the second column replace null with the appropriate value.

  • expression - by default, a regular expression is used that will match any VersionOne Work Item. The expression can be modified here if desired. Must be a string value. This is the default if omitted: (?:[bBsSdD]|TS|Ts|tS|ts|AT|At|aT|at|TK|Tk|tK|tk)-\d+")

  • fields - by default, the 'message' and 'branch' properties of a change submission will be searched. It is unlikely any other properties would contain the work item, but nevertheless the option exists. Must be an array of strings like this: ["message", "branch"]

  • push_link - false by default if omitted. If set to true, will put a link to Continuum on the VersionOne Work Item asset.

  • ignore_secondary - If a VersionOne Secondary Workitem is specified in a commit, such as a Test (AT-12345) or a Task (TK-09876), then Continuum will affiliate the commit with the appropriate parent Primary Work item. true by default, which means no reference to the Secondary Work item will be kept in Continuum. If set to false, the Secondary will not be ignored, and a work item in Continuum will be created for both the Primary and Secondary work items.

When using the 'editor', make sure to include the square braces and double quotes exactly as shown in examples above.

Make a New Commit

Now return to your local source and commit / push another change. Make sure to include the Work Item identifier in the commit message. An example of a commit message with a VersionOne identifier is as follows:

 Changed the customer field label to be all upper case, S-01293

Return to the Versions tab on the Project Detail page, you now see a Work Item. Expand and click on the Work Item. Explore the various tabs on this screen and notice how the Change is associated with the Work Item.


Refer to Configuring a Pipeline to continue on with the tutorial when the Work Item is viewable in Continuum.