Skip to main content
System StatusContact Support
Digital.ai Agility Community

Integrate Tools Using Digital.ai Agility Connect

With Digital.ai Agility Connect, the objective is to integrate applications with Continuum Plugins as the bridge and support synchronization of similar assets between the applications that are being integrated—for example, you can integrate Digital.ai Agility and Jira and have assets such as Epic, Story, and so on synchronized between Digital.ai Agility and Jira.

Overview

Digital.ai Agility Connect is an enterprise integration solution for integrating Digital.ai Agility with other ALM tools such as TeamForge and Jira.

Digital.ai Agility Connect supports integration between Digital.ai Agility, TeamForge, Jira, ServiceNow and Azure DevOps/TFS. 

 

 

Software Supported Version for Integration
Digital.ai Agility 20.0 and later
Jira (Jira Cloud, Jira Service Desk, and Jira on Prem) 7.1.x and later
Azure

Hosted Azure TFS: Dev18.M172.1

TeamForge 19.x and later
ServiceNow Orlando and Paris

Agility Connect supports MongoDB versions 3.6.x and 4.0.x.

Integrating Digital.ai Agility with another tool involves creating the asset mapping between the tools and saving the mapping. For example, you can create a mapping to have the Stories asset always synchronized between Agility and Jira.

Agility Connect Stand-alone Mode

Stand-alone Agility Connect is a stripped-down version of Continuum. Agility Connect was built on top of Continuum and you might be overwhelmed with the other functions of Continuum if you intend to use Agility Connect only. In this case, you can switch to the Agility Connect stand-alone mode by using an Agility Connect-only license. Using an Agility Connect license in Continuum exposes the Agility Connect functions (UIs and menus) only.

clipboard_e802bb28b4046349f4d78366f19f0519c.png

Configure the Agility Connect Service

  • Go to Settings > System and add your Continuum site's domain name to the UI URL (External) field.

clipboard_ebc09ab695268dc86e8e10457a767aa98.png

 

  • Edit the /etc/continuum/continuum.yaml file and:
    • Add Agility Connect (ECHO) as a feature to Continuum (under "features"). Once added, the Agility Connect service starts automatically in a minute or two. You can also start the Agility Connect service by restarting Continuum (ctm-restart-services).
    • Add echo_datasync_count that determines the number of Agility Connect threads that can run in parallel. The echo_datasync_count is by default set to 10. You can increase or decrease this count per your requirements.
    • Add Echo Data Migration as one of the features if you want to Migrate Assets from Jira to Digital.ai Agility.
    • Add Echo Import Mapping as one of the features if you want to Migrate your ALM Connect Data to Agility Connect.

clipboard_e0c45ee6618e220281184ac3f9ca390ca.png

  • Typically, the ctm-echo_sync service is added automatically to the service.conf file as long as the service.conf file is available at its default location (/etc/continuum/service.conf). If you have the service.conf file at a custom location (especially in a hosted setup), make sure that you have the ctm-echo_datasync service added to the service.conf file.

clipboard_ec19edc7ccfb6f0355736ba780b6a8362.png

Create the Mapping—Tutorial

While the process of creating a mapping is consistent regardless of the tools you integrate, this tutorial walks you through the process of mapping the fields of the Stories asset between Agility and Jira.

Configure the Continuum Plugins

Make sure you have the Agility and Jira plugins configured in Continuum.

1. Log on to Continuum as an administrator.

2. Click the Administration icon ( ctm02.png ) at the top right and select Connections > Plugins from the menu.

3. Configure the Agility and Jira plugins. For more information, see Agility and Jira plugin documentation.

    clipboard_e00f3703dd20b5c44543ef8503b4a7d18.png

 

    clipboard_ee7c33d38e0f05fd0561608e393881eb2.png

  • You must select All Teams from the Team drop-down list while configuring the plugins. 
  • You must not create or update work items using the Admin user account (that has access to all the projects in a Jira or Agility instance, for example) used to set up the Continuum plugins. Sync events in Agility Connect fail if you do so. 

Alternatively, you can also click + Create from the Create Mapping page to configure or modify the Agility Connect-supported Continuum plugins.

clipboard_e89bf5343c487ed6e5d38f2deb3b60f11.png

The Mappings List Page

1. Click the Administration icon ( ctm02.png ) at the top right and select Connections > Agility Connect from the menu. The Mappings List page appears.

Here's the Mappings List page.

clipboard_e4594437ff5bc0596d333e8047be15ef9.png

The Mappings List page lists all the mappings available with the following information.

clipboard_e6b46014ba0c8f8c679cd3824a8010447.png

Status (1)

  • Shows a mapping's current status (Active or Inactive).

Health (2)

  • Sync events can—at times—fail due to certain issues—for example, network outage.
  • The Health column shows whether a mapping has any sync issues.
  • A tick mark means the sync was successful with no errors whatsoever.
  • In case of any sync issues, no further sync can happen until you resolve the issues.
  • The Health column shows the number of issues with a mapping, clicking which takes you to the Logs page of that particular failed event.
     

Here's an example of the Logs page of a failed event.

clipboard_ef2943a8575a144da757e31ee5271ef33.png

 

  • Click the View Log icon to view the webhook log for the event.
  • Once you have fixed the issues, you can click the Retry icon to attempt syncing the failed event manually.
  • The Retry Count column shows the number of manual retry attempts you have made so far.

 

View Logs (3)

Click View Logs link to view the complete logs for all the sync events between the tools you mapped.

clipboard_ee09048d8c782398c298430f8bad33a80.png

As you can see, the Logs page has information such as the event type (CREATE/UPDATE), error details (if any), source and destination IDs, and the status of the event (Success, Processing or Failed). As discussed earlier, you can also view the webhook log for any event and retry sync manually from the Logs page.

Options (4) and (6)

The Options menu lets you:

  • Activate or inactivate a mapping (the toggle icon).
  • Delete a mapping (the delete icon).
  • Set up the email subject prefix for emails generated in case of sync failures (the email icon). To enable Email Notification Status, you must have configured the SMTP Server for Continuum and enabled.

clipboard_ea7d560fe3dd82bd46468052899a30bdc.png

Create Mapping (5)

The Create Mapping button to create new mappings, which is discussed next.

Import Mapping (7)

See Migrate your ALM Connect Data to Agility Connect.

Step 1: Configure the Integration

1. Click Create Mapping from the Mappings List page. The Create Mapping page appears.

   Name the integration and select the applications, projects, and asset types you want to integrate. 

    clipboard_e7f487a2b8626baebc33ac8ec5b50f8f5.png

 

2. Type a name in the Name text box. 

3. Select the tools you want to integrate from the System 1 and System 2 drop-down lists. For this tutorial, select Agility and Jira from System 1 and System 2 drop-down lists respectively.

4. Select the Agility and Jira projects that contain the assets you want to have synchronized between the two applications.

5. Click Add Project and select the Agility and Jira projects from the drop-down lists. Repeat this step to map as many Agility and Jira projects you want. 

While you can create a mapping to sync assets of up to 10 Agility and Jira projects, a multi-project mapping can only let you view and map fields common to all the selected Agility and Jira projects.

  • There's no need to select a project for ServiceNow as ServiceNow is not project-based. 
  • See Sync Workitems Based on Teams if you want to set up mapping only to sync workitems created or updated by specific teams. 

5. Select the Agility asset type and Jira issue type from the Asset Types and Issue Types drop-down lists respectively.

6. Click Next.

Step 2: Create the Field Mapping

You can either choose to automatically map the fields or you can do it manually.

Auto Map

The fields that are auto-mapped are predefined in Agility Connect for each asset type.

Auto-mapping of fields is not defined for TeamForge/Azure asset types and so you cannot automatically map TeamForge/Azure fields with other tools.

clipboard_e5f5f2c7177db6849b956e83dc9670cb8.png

  • Click Auto Map to create a bidirectional automatic mapping of the default mandatory fields as defined in Agility Connect.
  • Once the fields are auto-mapped, you can manually map more fields (click Add Field), if required.
  • Auto-mapping of fields is only available when you create field mappings. It is not available when you edit a mapping.

Here's an example of the auto-mapped fields of Agility and Jira.

clipboard_e801a48c06052ab2a7de9b91c606abfa6.png
 

  • The Field Mapping page lets you map the fields of the assets (Stories, Epics, etc.) from the two applications that are being integrated.
  • There are two drop-down lists, one each to the left and right-hand sides of the forward/backward mapping arrows. 
  • When a field is forward-mapped (clipboard_ee88c3097e3cec411e5a88a0cc57d0094.png), any changes to the field on the left is synced with the field on the right.
  • When a field is backward-mapped (clipboard_e3b0990920c2fe8ecbd1ceb6014b7e075.png), any changes to the field on the right is synced with the field on the left.
  • Selecting both the arrows syncs the fields bi-directionally.
  • You can map as many fields as you want. Just add a new field mapping row (Add Field button), select the fields to map, and select the mapping direction. 

clipboard_eb08bc0cba6c4df78752ab02f4cde6725.png

 

Mapping Iteration/Sprints

When you create a mapping, you can map the Iteration and Sprint fields of Agility and Jira respectively, to have these fields synced when you create or update a workitem in Agility or Jira. 

clipboard_e8080d16f2fde5887b143b91400497cc1.png

Mapping Fields with Workflow-Transitions

Some of the fields such as the "Status" field can have workflow transitions defined as part of their tracker configuration. You must consider such transition rules when you create your mapping. If you map a field violating a status transition workflow, the mapping can fail.

Here's an illustration.

Suppose, you have a Jira workflow configured for the Status field, which is set to "Open" initially (the default value), transitions to "In Progress" before you can set it to "Pending". 

clipboard_ec8e7a5611d8c3b01c9231688016efccf.png

In this case, when you create a field value mapping for the Status field, you must make sure that you do not select "Pending" as the default value in Jira as illustrated in the following image.

clipboard_ec667d02daadb9f4c12fac0db5d6310d6.png 

In the case of Jira, you can click the workflow icon next to the Status field to view the Jira workflow definitions in Agility Connect.

 

clipboard_ed84af9bb25fb621e13a2468de286ea32.png

Filter Fields by Type

You can filter the fields by type (Mandatory, Read-Only, and Optional) to have just the fields you want to map readily available from the drop-down lists.

clipboard_efaf902590222eae9665c55f40149ffb0.png

  • You can hover over a field to view its type—for example, Text, Number, Date, Single-Select drop-down, etc.
  • You can map fields of the same type—for example, you can only map a Text type field with another text type field. 
  • Field names in the drop-down list are prefixed with a color-coded dot.

Mapping Endemic Fields ("No Field" mapping)

It is quite possible for the asset types (of tools being integrated) to have endemic fields native only to themselves. In other words, a tool may have a field for which you may not have an equivalent field to map on the other tool.

For example, a Portfolio Item in Agility (mapped to an Epic in Jira) has a "Category" field that further classifies the Portfolio Item into various types such as Epic, Feature, Capability, and so on. However, Jira has no such sub-classification of Epics, which means the "Category" field in Agility can never be mapped with another field in Jira. The "No Field" mapping comes in handy in such cases.

In this case, you can map the Agility's "Category" field to "No Field" (a read-only field) and select a default value for "Category". Once done, any sync event that originates from Jira to Agility takes the predefined default value for the "Category" field and updates the Agility's asset accordingly.

 

clipboard_ec74ea11ae9754631bc979c7f79cef874.png

 

Conflict Resolution and Sync Interval Settings

Once you create mappings and activate them and as messages get to the Agility Connect's queue for processing, it is quite possible for a bi-directional mapping to have more than one message (from the tools at both sides of the mapping) waiting to be processed. For example, when a sync event fails for a mapping, any subsequent updates (sync events) would also fail. However, when you fix the issues and retry the failed sync events manually, multiple messages for the same mapping can get into the queue for processing at the same time. This creates a conflict situation, which if left unresolved, can have the messages processed on a first-in-first-out basis, and that in turn can result in the assets being synced in an undesirable manner.

This is where the Conflict Resolution settings come in handy. The Conflict Resolution setting lets you select one of the tools so that the selected tool's messages prevail over the other in case of conflicts.  

You can set up conflict resolution both at the field level and at the mapping level. Field level conflict resolution settings override mapping level settings. If not configured at the field level, the mapping level conflict resolution setting kicks in whenever conflicts occur during sync events. 

  • To configure conflict resolution for a field, once you are through with field mappings, click the Settings icon for a field and select one of the options: System 1 wins, System 2 wins, or None.

clipboard_e82eb14abc78cd0fb1c55a615bf89cf96.png

  • To configure conflict resolution at the mapping level, click the Conflict Resolution toggle button in the Additional Mapping section and select one of the options: System 1 wins or System 2 wins.

Sync Interval Settings—The Sync Interval Settings drop-down list lets you select the time interval between sync events. While a one-minute sync interval is recommended, you can increase it if you want. Setting a 20 seconds sync interval can adversely impact conflict resolution.

clipboard_e65f7cbcdb4327ed7cd1804a141220a12.png

Legends

The legends at the top right (click Legend) can assist you in identifying the different types of fields you select from the drop-down lists.

clipboard_ec0769973e57b47da9373eb599d7adad9.png

For example,

  • Mandatory fields are marked with a red dot.
  • Optional fields are marked with a blue dot. 
  • Read-only fields are marked with a grey dot

 

Field Value Mapping

You can create a value-level mapping of certain field types such as the Single-Select Drop-down. For example, the Status field has three values that are mapped as shown in the following illustration.

  1. Click Show Mapping/Hide Mapping toggle link. 
  2. Click Add Value
  3. Select the values from the drop-down lists to map the values of the two applications.
  4. Select the mapping directions using the map arrows. 
  5. Repeat steps 2 through 4 to map more values. 
  6. You can also select one of the values as the default value. Select the option button from the Default column. 

clipboard_e8e666e9e957ce2fc969281c712209204.png

  1. You can also set default values for text-type fields. After mapping text-type fields, click the Default Value link and type the default value for the text field. 

clipboard_ecdaa4a8cdda4debbe7a90b1ad2172dd9.png

Here's an example of a list of fields with mapping.

clipboard_e32272654a24f698bb5f9e5dee6568cce.png

Additional Mapping

Use the Additional Mapping section to enable/disable mapping for Comments, Attachments, and Relationships at the mapping level. You can also configure Conflict Resolution, Sync Reference, and conditional sync (Sync Specific Workitem) settings.

clipboard_ec0ed088bb7f4f680681b8a0b0cbd1e28.png

  • Comments: Click the Comments toggle button to sync comments and conversations of the workitem.
  • Attachments: Click the Attachments toggle button to sync attachments of the workitem. 
  • Conflict Resolution: See Conflict Resolution discussed earlier in this tutorial.

 

Relationships

Click the Relationships toggle button to define the parent-child relationship between the mapping you create/edit and the other mapping. For example, if you have a mapping created to sync Agility and Jira Epics (parent), you can enable Relationships and select another mapping (from the drop-down list) created to sync Agility and Jira Stories, for example, as a child. Once done, any Story you create or update—as a child of an Epic—would be synced exactly with the same relationship on the other tool.

Setting up Relationships is not possible with ServiceNow. 

clipboard_e7af640827a56beaf891538dd7a3ec46e.png 

Sync Reference

Sync Reference creates backlinks for easy navigation to the synced workitems.

  • Sync Reference can be either uni or bidirectional.
  • A bidirectional Sync Reference, if configured, updates both the source and destination tools with the backlinks to the synced workitems.
  • The ID and URL fields, if mapped, are updated with the workitem ID and URL of the synced workitems.
  • The ID and URL fields you map for Sync Reference must be optional/editable in both the tools being integrated.
  • Simply enabling the Sync Reference without any ID/URL field mapping updates the Links section with a reference (workitem ID and URL) to the synced workitem.

clipboard_e9a37c82e960d4fbb4a5c7ca6a07c7fe3.png

Sync Specific Workitem

Instead of syncing workitems unconditionally for all the create/edit events, you can choose to have workitems synced conditionally (for example, if and only if a field has a particular value). For example, you may have the workitems synced if and only if the Status field is set to "Open". 

You can use the following comparison operators to build your filters.

  • Equals
  • Not Equals
  • Contains
  • Not Contains

In addition, you can nest conditions using the AND and OR logical operators.

  1. Enable the Sync Specific Workitem option.
  2. Select the Filter tab and build your conditional filters.

clipboard_e72c4c8787e811fb1f15d470e2c33c899.png

In case you have a multi-project mapping, you can create project-specific conditional filters.

  1. Select the Project Specific Filter tab and define the filter.

clipboard_e6cbfd83882716d879258b28526ed5c2a.png

Dependencies

Agility supports assigning upstream and downstream dependencies for its assets. Jira supports a similar function via the "Blocked by" and "Blocks" links. Turn on Dependencies to sync any upstream and downstream dependencies created in Agility with the "Blocked by" and "Blocks" fields of Jira. 

While you add dependencies for an asset in Agility, make sure the dependencies have been synced already with Jira. 

clipboard_e3f330f5b5e0aa5759c5bd5fcf893c813.png

 

Once you have mapped as many fields as required, click Save & Preview

Step 3: Preview and Integrate

The Preview and Integrate page shows you a comprehensive view of the mapping as configured in steps 1 and 2 discussed earlier. 

 

  1. At this stage, you can click Edit and fine-tune your mappings, if required. 
  2. You can also choose to update the mapping direction. For this tutorial, let us choose Bidirectional
  3. Activate the mapping using the Activate/De-activate toggle button.
  4. Click Save and Complete to save the mapping. 

Your mapping is now active. Update a story in Agility Lifecycle and verify if the changes are synced with the right Jira issue and vice-versa.

Sync Workitems Based on Teams

With Agility Connect, you can create mappings to sync workitems created or updated:

  • by specific teams in Agility with specific teams in Jira
  • by specific teams in Agility with specific projects in Jira
  • in Agility projects (or subprojects) with teams in Jira

Sync Workitems Created or Updated by Specific Teams in Agility with Teams in Jira

Objective: You have an Agility project with multiple teams and a Jira project with multiple teams. Create a mapping to sync workitems created by specific teams in Agility with specifc teams in Jira. 

  1. Set out to create a new map as discussed earlier.
  2. Select the Agility and Jira systems, projects, and asset types as usual and click Next.

clipboard_e89eb5413ca8483d680b1236d0bfb06d4.png

  1. Map (or Auto Map) the fields you want to sync and in doing so map the team field in Agility with the team field in Jira. 

clipboard_ecce6043b036aa797fb91868ea5a32566.png

  1. Click the Show Mapping link.
  2. Click Add Value.
  3. Select the Agility and Jira teams you want to map from the drop-down lists.
  4. Repeat steps 4 and 5 to map as many teams as you want. 

clipboard_e0131155e40fea2d10e6da6f305df51d4.png

  1. Proceed with the rest of the mapping process as discussed earlier.

You have now created a mapping that syncs workitems created or updated by specific teams in Agility and Jira. 

Sync Workitems Created or Updated in an Agility Project (or subproject) with Teams in a Jira Project

Objective: You have a handful of Agility projects (or subprojects) and a Jira project with multiple teams. Create a mapping to sync workitems created in Agility projects with specific teams in the Jira project.

  1. Set out to create a new map as discussed earlier.
  2. Select the Agility and Jira systems, projects, and asset types as usual and click Next

clipboard_e7a06f313bc872313cad6a52b1ae383f5.png

  1. Map (or Auto Map) the fields you want to sync and in doing so map the Planning Level field in Agility to the team field in Jira. 

clipboard_e718480df84443a39bd1ba667650433e1.png

  1. Click the Show Mapping link.
  2. Click Add Value.
  3. Select the Agility project and the Jira team you want to map from the drop-down lists. 
  4. Repeat steps 4 and 5 to map as many mappings as you want between the Agility projects and Jira teams. 

clipboard_ef5942fe6bc64103c78883241b6efa35e.png

  1. Proceed with the rest of the mapping process as discussed earlier.

You now have a mapping that syncs workitems created or updated by specific teams in Jira with specific projects in Agility and vice versa. 

Sync Workitems Created or Updated by Specific Teams in Agility with Projects in Jira

Objective: You have an Agility project (with multiple teams) and a handful of Jira projects. Create a mapping to sync workitems created by specific teams in the Agility project with the Jira projects.

  1. Set out to create a new map as discussed earlier.
  2. Select the Agility and Jira systems, projects, and asset types as usual and click Next

    However, create a project mapping wherein there is a one-many relationship between the Agility project and Jira projects. In other words, use the Add Project button to map a single Agility project (with teams) to multiple Jira projects. 

    In this scenario, you would typically want to map multiple Jira projects (meant for individual teams in the Agility project) with multiple teams in the Agility project. 

clipboard_ef9827594138ec2a2c225df047c64f1a1.png

  1. Map (or Auto Map) the fields you want to sync and in doing so map the team field in Agility with the Project (mandatory) field in Jira. 

clipboard_e30f50b49d43da1a4849e3bff624f0624.png

  1. Click the Show Mapping link.
  2. Click Add Value.
  3. Select the Agility team and the Jira project you want to map from the drop-down lists. 
  4. Repeat steps 4 and 5 to map as many mappings as you want between the Agility teams and Jira projects. 

clipboard_e24751eea2687e15ca2f1652eec9252c2.png

    If you are syncing bi-directionally and when you have one or more teams in Agility that are not mapped to projects in Jira, you must map one of the unmapped teams to "No Project". This is to prevent duplicate syncing of workitems created  in Jira with the teams in Agility. 

clipboard_e84495617f462176dd794a16b38b413ef.png

  1. Proceed with the rest of the mapping process as discussed earlier.

You now have a mapping that syncs work items created or updated by specific teams in Agility with specific projects in Jira and vice versa.

Poll for Missed Events: Work Item Change Detection

Certain real-world conditions such as network issues, server issues, and so on can leave the create or update event data from the source system in limbo. In such cases, the data originating from the source system may not ever make it to the destination system for syncing. 

Work Item Change Detection is a polling mechanism (introduced in Agility Connect 21.0) that comes in handy in such situations. 

clipboard_ece8201c87c5a10dafc00efebf9cf9bee.png

Configuring the Work Item Change Detection setting polls for such missed events at regular intervals, fetches the missed event data, if any, and sends the data to the destination system for syncing. The data sync, in this case, happens in the same chronology of events as found in the source system. In other words, the history of source events is honored when the sync happens. 

The default polling interval is 12 hours. The available polling intervals in the drop-down list range from 2-24 hours.

Create a Mapping to Migrate Assets from Jira to Digital.ai Agility (Beta)

This is a beta feature in Agility Connect 21.0. Do not use this in a production setup. 

You can now create a mapping solely for the purpose of migrating your Jira assets to Digital.ai Agility. clipboard_ef347add91f43b354c286b67a20f9a85b.png

Use the Data Migration configuration to specify the date range to migrate data. However, the maximum window for data migration is three months.

Once you create a mapping for the purpose of data migration, select the Schedule Now check box (it is mandatory to schedule the data migration to run immediately) and activate the mapping, all the Jira assets created or updated within the given date range are fetched and synced with the Digital.ai Agility. 

You have three options when you want to activate the mapping as shown in the following illustration. 

 

clipboard_e10c3f52077e56f16f4af25a4dce8a7c5.png

  • You can activate both the data migration and data sync, which is what you would do if you want to have the mapping do the data migration immediately and continue with the data sync going forward. 
  • You can activate data migration alone, which means the mapping would just do the data migration and not be doing the live data sync for future sync events.
  • You can activate data sync alone, which means the mapping would just do the data sync and not the data migration. This is as good as disabling the Data Migration configuration.  

A mapping, created for the sole purpose of data migration cannot be modified for any other purpose at a later point in time. 

You cannot use (modify) an existing mapping (that has been activated at least once after creation) to do the data migration. 

While you can migrate data from Jira to Digital.ai Agility, you cannot use this feature to migrate data from Digital.ai Agility to other tools.

Migrate your ALM Connect Data to Agility Connect (Beta)

This is a beta feature in Agility Connect 21.0. Do not use this in a production setup.

You can now export your ALM Connect mappings and import them into Digital.ai Agility Connect. This saves you from manually recreating the ALM Connect mappings in Agility Connect from the scratch.

You must export the ALM Connect event and mapping data in JSON and XML formats respectively. 

  • The JSON file consists of the synced event data.
  • The XML file consists of the mapping (integration) configuration data. 

clipboard_eeaa2a8725e55507f535baf030c12b2d9.png

  1. Click Import Mapping from the Mappings List page.
  2. Click Upload File and select the mapping and integration configuration files.
  3. Click Import Mapping.
  4. Select the systems and projects that you want to map.
  5. Click Next.
  6. Review the imported mapping, edit if required, and save the mapping.

Mapping Customizations (Beta)

This is a beta feature in Agility Connect 21.0. Do not use this in a production setup. 

When you map the fields from two different tools, you may have to, at times, resolve certain field-level incompatibilities. You may have to do some data transformations to make the data from the source system acceptable by the destination system.

Agility Connect Customizations is a python based framework that lets you define such transformational customizations required when you create a mapping. This framework has a set of predefined functions that are readily consumable from within the UI in the form of code templates.

The Customization Code editor has been templatized with a predefined code snippet. You can simply use one of the available customization functions to define your customizations with little or no coding knowledge. However, the possibilities are limited only to your imagination as you can even write advanced code to define more complex customizations in case you are well versed with Python.  

Here is an example use case to illustrate how it works. 

Let us assume you want to map the Description fields of Jira and Digital.ai Agility and in doing so you want to truncate the description field values from Digital.ai Agility to 20 characters before syncing with Jira. 

  1. Set out to create a mapping as usual and in doing so, click the settings icon (cogwheel) of the Digital.ai Agility's Description field. 

clipboard_efdfb5f7c036962f2bd1330bddabe32b0.png

  1. Click Customize Jira Description. The Customization Code editor shows up. 

clipboard_effb224460c2765992d4562f617173245.png

  1. Now, edit the second line of the code wihch is output_value = input_value and make it output_value = utils.truncate(input_value, 20).

The final code looks like this:

clipboard_e3786837c642b244cc8c5466239e10dcc.png

  1. Now, click Save as Draft to save the code and proceed with the mapping creation process as discussed earlier. 

That's it. You have now created a mapping with customization that truncates the Digital.ai Agility Description field values to 20 characters before syncing it with the Jira Description field. 

Here's the list of customization functions available for use with your mappings:

utils.truncate(input_value, length)

input_value: String (mandatory)
length: Integer (mandatory)

This method truncates the input string beyond the given length parameter and returns the remainder of the string.

utils.text_to_int(input_value, default_value)

input_value: String (mandatory)
default_value: Integer (optional)

This method converts the input_value to an integer and returns it, provided it's a valid integer in string format.  Otherwise, if a default value is provided then that will be returned.  Else an exception is raised.

utils.text_to_float(input_value, default_value)

input_value: String (mandatory)
default_value: Float (optional)

This method converts the input_value to an float and returns it, provided it's a valid float in string format.  Otherwise if a default value is provided then that will be returned.  Else an exception is raised.

utils.multi_to_single(input_value, priority_list)

input_value: An array of selected values for the multi-select field. (Mandatory)
priority_list: An array of display values in order pf priority to be considered when mapping it to the single select field on the other side.  The array is allowed to be empty.  (Mandatory)

This method picks one choice from the possibly many values in the input_value, based on the priority_list provided.  If no value in the priority_list matches any of the values in the input_value then the first value is returned.  If the priority_list is empty then too the first value is returned.

utils.text_to_single(input_value, default_value)

input_value: String (Mandatory)
input_value: String (Optional)

The input value must match the display value of the mapped single select field.  In that case, the method returns that single select fields value.  Else if a default_value is provided then the same is attempted with that value.  Otherwise, an exception is raised.

FAQs

Here's a list of FAQs about Agility Connect. 

I have an Agility Story with tasks in it. How can I sync the Agility tasks with Jira?

Use case: Tasks in Agility are part of Stories (Stories > Tasks). Whereas, Jira has a separate asset called Tasks that also supports Subtasks (Tasks > Subtasks). You want the Agility Stories > Tasks synced with Jira Tasks > Subtasks. 

Step 1: Create a mapping between the Agility Story and Jira Tasks assets to sync Agility Stories with Jira Tasks. 

Step2: Create another mapping between Agility Tasks and Jira Subtasks to sync Agility Tasks with Jira Subtasks. 

Matrix of Agility Connect Features Supported for Integrating Digital.ai Agility with Other Tools

 

Features Digital Agility <-> Jira Digital Agility <-> Jira Cloud Digital Agility <-> AzureDevOps Digital Agility <-> Teamforge Digital Agility <-> JSD Digital Agility<-> ServiceNow
Auto Map X
Attachments X
Comments/Conversations X
Multiple Project Support N/A
Relationships X N/A
Sync Reference (backlinks in Source and target) X
Auto Create Webhook X
Mapping Conflict Resolution X
Resync Functionality X
Sync on specific conditions(Conditional filtering)
Sync Workitem Based on Teams X X X
Dependencies X X X
Workitem Change detection X X X X
Field level Customizations
Import Mapping-ALMC X X X X
Echo Data Migration X X X X
Migration using fields X
Field Mapping            
Single Select
Multi-Select X X
Text
Date
DateTime
Number
User Picker X X X
Text Markdown X
Teams X X
Field Conflict Resol - Check all fields X
Categiry Support(No Field) X
Direction            
Uni-direction
Bi-Directional
Asset type            
Epic N/A N/A
Features (Using No field config) N/A N/A
Stories N/A N/A
Defects/Bugs N/A N/A
Tasks X X N/A N/A
Theme N/A N/A
Sub-tasks X X N/A N/A
Service Request N/A N/A N/A N/A N/A
Incidents N/A N/A N/A N/A
Service Request With approvals N/A N/A N/A N/A N/A
Catalog Tasks N/A N/A N/A N/A N/A
Requests
Custom tables (that inherit ServiceNow Task table) X X X X X


Knows Issues

  • When you map fields from hosted Jira and Azure assets and when sync happens for a create or update event—all but the user type fields are synced successfully. The user type fields are ignored.
  • Mapping of HTML text and simple text fields is not supported.

21.0 Known Issues

  • A validation message appears when you map text and single-select fields without selecting a default value.
  • The field mapping page goes blank when you map text and single-select fields bi-directionally and add a default value to it.