Digital.ai Agility

Digital.ai Agility (Formerly known as VersionOne).

Prerequisites

User privileges

Create one user of Digital.ai Agility system, dedicated to integration. User should not be used to do any operations from Digital.ai Agility's user interface.
Integration user should have atleast the minimum Team Member role through which he/she must be able to create/update work item.
If Digital.ai Agility Project/Release Entity needs to be created/updated through integration, then Integration user should have at the minimum Project Admin role.
For further information on how to set the access rights on project, please refer to the Appendix section How to add permissions on Project.

Linking BuildRuns with ChangeSets

A special build parameter needs to be created in the source system, for example, Jenkins project which is used for synchronization. The parameter's name and type are specified below.
The same source system's build parameter created above should be mapped with Digital.ai Agility's field 'ChangeSets.ID' during field mapping configuration of Digital.ai Agility BuildRuns.

Parameter Name

Parameter Type

ChangeSetId

String

System Configuration

Before you continue with the integration, you must first configure Digital.ai Agility. Click System Configuration to learn the step-by-step process to configure a system. Refer to the screenshot given below:

If the system is deployed on HTTPS and a self-signed certificate is used, then you will have to import the SSL Certificate to be able to access the system from OpsHub Integration Manager. Click Import SSL Certificates to learn how to import SSL certificate.

Digital.ai Agility System form details

Field Name

Description

System type

Select the system type you want to configure

System Name

Give a unique name to the system

Version

Provide the version of your Digital.ai Instance. To find out the version of Digital.ai Agility, refer to Find the version of Digital.ai Agility

Digital.ai Agility Server URL

Digital.ai Agility Server URL is used for connecting to Digital.ai Agility application

Digital.ai Agility Authentication Type

Digital.ai Agility Authentication Type to be used for authentication

Digital.ai Agility Time Zone

Digital.ai Agility Time Zone-you can find this information from /config.v1. Based on this information, you can accordingly select the timezone. E.g., if TimeZoneId field in /config.v1 is shown as Eastern Time, then you need to select 'USEastern'. If TimeZoneId field has some other value, then select appropriate value accordingly

Mapping Configuration

Map the fields between Digital.ai Agility and the other system to be integrated to ensure that the data between both the systems synchronize correctly. Click Mapping Configuration to learn the step-by-step process to configure mapping between the systems.

Note: When Digital.ai Agility system is the destination system , it is mandatory to set Project Path field. In this field, you can select the Digital.ai Agility Project to be integrated.

Advanced Mapping Use Case

If the user wants to take the decision based on the unmapped field in the advanced mapping of any mapped field, then the unmapped field's Xpath can be configured using the specific XSL patterns.

For example, Description field is mapped in the mapping, and the ComplexityRank field is not mapped in the mapping. If the user wants to take decision based on ComplexityRank field in the advanced mapping of Description field, then the user can define the source Xpath for ComplexityRank, using the below XSL patterns:

XSL Pattern: Any tag where prefix is XSL and Attribute is `select`

Example:

<Description>
  <xsl:variable name="Value" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    select="SourceXML/updatedFields/Property/ComplexityRank" />
  <xsl:value-of xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    select="concat(SourceXML/updatedFields/Property/Description,$Value)"/>
</Description>

XSL Pattern: Tag is `<xsl:if>` and Attribute is `test`

Example:

<Description>
  <xsl:if xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    test="SourceXML/updatedFields/Property/ComplexityRank != ''">
    <xsl:value-of xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      select="SourceXML/updatedFields/Property/Description"/>
  </xsl:if>
</Description>

XSL Pattern: Tag is `<xsl:when>` and Attribute is `test`

Example:

<Description>
  <xsl:choose xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:when test="SourceXML/updatedFields/Property/ComplexityRank != ''">
      <xsl:value-of xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        select="SourceXML/updatedFields/Property/Description"/>
    </xsl:when>
  </xsl:choose>
</Description>

Mapping for Soft Delete Configuration

When Digital.ai Agility is the target system in the integration, the Soft delete operation is performed by default in the synchronization of the Source Delete event.
After the soft delete operation is performed by OpsHub Integration Manager in Digital.ai Agility, the entity will be deleted in the Digital.ai Agility.
To only enable the logical delete operation in the target, "IsDeleted" field shall be mapped with the default value "No" in the Delete Mode mapping.

Note: For the "Actual" entity, the Soft delete operation is not available due to API limitation.

Integration Configuration

Set a time to synchronize data between Digital.ai Agility and the other system to be integrated. Also, define parameters and conditions, if any, for integration. Click Integration Configuration to learn the step-by-step process to configure integration between two systems.

Note: As per OpsHub Integration Manager's default behavior, when you integrate projects that have child projects, child projects' entities also sync when integration starts. Look at the sample below. The 'Demo Project' shown here has two child projects as well. That means when you integrate 'Demo Project', child projects within it - CAB Approval and eCAB Approval - will also sync by default.

To avoid this behavior, you can configure criteria in a manner that child projects are excluded during the integration. For example, you can set a query that specifies that data from only the project in the given integration's scope has to be synchronized.

The criteria query, in this case, should be: Scope.Name = 'Project Name for which entities needs to be sync'.

Let's look at the example below. In this case, 'Demo Project' is the parent project with child projects within. Now, as we only want to integrate the parent project, choose 'Yes' in the Criteria Configuration drop-down field and add the query in the format give above i.e. Scope.Name = 'Demo Project'.

The criteria query, in this case, should be: Scope.Name = 'Project Name for which entities needs to be sync'.

Example: Scope.Name = 'Demo Project'

You can sync multiple projects as well. The criteria query, in this case, should be Scope.Name='Project 1'|Scope.Name='Project 2' as shown below:

Click Criteria Configuration to learn how to configure criteria.

Additional Settings

Actuals Sync

Digital.ai Agility's Actuals allow users to log time that they spend working on issues. Actuals can be created on Story, Defect, and Task.

Ways to Sync Actuals

There are two ways to sync Actuals.

Actuals as a field of the parent entity (Defect, Task, Story)
Actuals as a separate entity with the parent entity, for example child relation between Actuals and parent entity

Note: Actual as entity is the preferred approach. Do not use both the approaches together as it will lead to inconsistent data in end system.

Sync Actuals as a field of parent entity

If you want to sync Actuals, then you can map the following fields during field mapping of the parent entities.

Actual Field Name

Data Type

Is Read-Only?

Description

Estimate

[Timeunit]

Original Estimate to complete the work

ToDo

[Timeunit]

Remaining time left to complete the work

Actuals.Value

[Timeunit]

Time spent working on an issue i.e. Time logged in actual.

Actuals.Date

Date

Date on which the work was logged

Actuals.Member

User

User who logged the work and created actual

Please ensure to turn off the Conflict Detection flag for these fields, and turn on the Overwrite flag when configuring field mapping. For further details, please refer to Field Mapping Configuration.

Known Limitations

Conflict Detection will not work on Worklog fields.
If overwrite flag is turned off for actual fields, new value will not be written in the target.
If an update is made on one Actual, the update will not synchronize to the corresponding worklog created in target system.

Sync Actuals as a different entity

If you want to sync Actuals as a different entity, then you can map the following fields during field mapping of Digital.ai Agility entities:

Actual Field Name

Data Type

Is Read-Only?

Description

Date

Date on which actual was logged

Member

User

User who logged the actual

Value

[Timeunit]

Time spent working on an issue i.e. time logged in actual.

Project Path

Date

Yes

Project path of parent work item

Workitem.Number

Text

Yes

Display Id of parent entity

To sync Actuals as a different entity, you need to configure a different integration for Actuals and provide issue relationship in the field mapping.

Give parent entity relationship in issue relationship during Actuals field mapping.
Select parent entities whose Actuals you want to sync during integration configuration of Actuals.

Default Behavior

If Actuals.Date is not mapped, Actuals will be created on current date.
If Actuals.Member is not mapped or mapped with an incorrect value (user email does not exist in Digital.ai Agility), Actuals will be created by the integration user.

Criteria Configuration

Query

Query in Digital.ai Agility system is the valid Digital.ai Agility Rest API based criteria query, which is valid against Digital.ai Agility metadata. To validate metadata, refer to Rest API URL e.g [https://www12.v1host.com//meta.v1/Story]. Within that one can get property name from DisplayAttribute tag.

For example:

<DisplayByAttribute href="https://www12.v1host.com/partner_opshub2/meta.v1/Story/Priority.Name" tokenref="Story.Priority.Name"/>

Where Priority.Name is a valid field on which one can specify query.

Sample Query

Priority.Name="High";ChangeDate>="2010-09-24T14:35:35.041"
An example of criteria with one 'Lookup field (System Lookup field)': Priority.Name="High"
An example of criteria with one custom Lookup field and one date field: Custom_StartDate="2010-09-24T14:35:35.041";Custom_Effort="1"
An example of criteria with 'contains on text field or created by (or some other user field) = some user': CreatedBy.Username="syncuser"

Known Limitations

Epic Planned End Date or Sprint End Date

Digital.ai Agility API returns actual date + 1 in Planned end date field of Epic and end date of Sprint. Therefore, there will be a difference of 1 day when synchronizing this field. When Digital.ai Agility is the source system, following sample Advance XSL can be used to overcome this limitation:

When Digital.ai Agility is the source system:

<Target_Field>
  <xsl:if xmlns:xsl="http://www.w3.org/1999/XSL/Transform" test="SourceXML/updatedFields/Property/PlannedEnd">
    <xsl:variable name="sourceFormat" select="'yyyy-MM-dd'"/>
    <xsl:variable name="targetFormat" select="'yyyy-MM-dd'"/>
    <xsl:variable name="calendarVar" select="utils:getCalendar(SourceXML/updatedFields/Property/PlannedEnd,$sourceFormat)"/>
    <xsl:value-of select="cal:add($calendarVar,5, -1)"/>
    <xsl:value-of select="utils:transformCalender($calendarVar, $targetFormat)"/>
  </xsl:if>
</Target_Field>

Replace Target_Field with the internal name of target field.

When Digital.ai Agility is target system, following sample Advance XSL can be used to overcome this limitation:

When Digital.ai Agility is the target system:

<PlannedEnd>
  <xsl:if xmlns:xsl="http://www.w3.org/1999/XSL/Transform" test="SourceXML/updatedFields/Property/Source_Field">
    <xsl:variable name="sourceFormat" select="'yyyy-MM-dd'"/>
    <xsl:variable name="targetFormat" select="'yyyy-MM-dd'"/>
    <xsl:variable name="calendarVar" select="utils:getCalendar(SourceXML/updatedFields/Property/Source_Field,$sourceFormat)"/>
    <xsl:value-of select="cal:add($calendarVar,5, 1)"/>
    <xsl:value-of select="utils:transformCalender($calendarVar, $targetFormat)"/>
  </xsl:if>
</PlannedEnd>

Replace Source_Field from above XSL with the internal name of source field.

Username of the User if not set

When Digital.ai Agility is the source system, and the user type field is mapped for sync, and the username of that user is not set. Then, in that case, the user will be read as empty, and synchronization will happen according to the mapping configuration.

Appendix

Find the version of Digital.ai Agility Instance

Open Digital.ai Agility instance login page e.g., https://www1.v1host.com/
You can find the version of Digital.ai Agility instance on this page as shown in the image below:

How to add permissions on Project

Log-in to Digital.ai Agility with user having administrative privileges.
Navigate to Admin tab.
In Projects tab navigate to Member Roles tab and find the project on which permission need to be granted.

Click on Manage button in front of the project.

For the user, select the role and click on Apply on the right-hand corner of the pop-up to save the changes.

Custom Fields

To create a custom field in Digital.ai Agility:

Load the Digital.ai Agility User Interface in browser using the Server URL.
Log in with a user having administrative rights.
Click on the Admin on the top.
Select Configuration > Custom Fields.

Click on the Add Field button in the row of the relevant asset in which you want to add the custom field (this is the story type configured in integration).

Enter the Display Name of the new custom field (SyncEntity in this case).
Select appropriate Field Type for the custom field (Text in this case).
Click on OK.

Click on Publish Changes, shown in the previous window.
After field is created, System Name of the field is the Internal Name of custom fields.

Inline Image Support for Digital.ai Agility

You can add inline images in rich text type of fields from Digital.ai Agility UI. Such inline images will get synchronized from Digital.ai Agility to the target system. When Digital.ai Agility is your target system, then an inline image is just visible in the rich text type fields and not as an attachment.

How to find out the project id

Navigate to Admin > Projects as shown in the image below.

Open the project in a new tab, which is configured in integration as shown in the image below:

Copy the project id from Digital.ai Agility URL as shown in the image below:

PreviousDatabase NextDigital.ai TeamForge

Last updated 50 minutes ago

Prerequisites

User privileges

Linking BuildRuns with ChangeSets

System Configuration

Mapping Configuration

Advanced Mapping Use Case

XSL Pattern: Any tag where prefix is XSL and Attribute is select

XSL Pattern: Tag is <xsl:if> and Attribute is test

XSL Pattern: Tag is <xsl:when> and Attribute is test

Mapping for Soft Delete Configuration

Integration Configuration

Additional Settings

Actuals Sync

Criteria Configuration

Query

Sample Query

Known Limitations

Epic Planned End Date or Sprint End Date

When Digital.ai Agility is the source system:

When Digital.ai Agility is the target system:

Username of the User if not set

Appendix

Find the version of Digital.ai Agility Instance

How to add permissions on Project

Custom Fields

Inline Image Support for Digital.ai Agility

How to find out the project id

XSL Pattern: Any tag where prefix is XSL and Attribute is `select`

XSL Pattern: Tag is `<xsl:if>` and Attribute is `test`

XSL Pattern: Tag is `<xsl:when>` and Attribute is `test`