Create via Gateway

The Create via Gateway Integration Template is only available in Editions that contain the Gateway add-on.  See Tasktop Editions table to determine if your edition contains this functionality.

What is a Create via Gateway Integration?

Create via Gateway Integration

An integration is quite simply the flow of information between two or more collections.  A Create via Gateway Integration, specifically, creates new artifacts in a work item collection or a container collection that connects to a repository, such as Jira, when they are sent to Tasktop via a Gateway Collection.  The Gateway Collection uses an inbound webhook to access event-based information in an external DevOps tool, such as Git or Jenkins.  

These types of events are “fire and forget” - they create something new in your repository, but they don’t expect anything back. As such, they don’t mandate a full-blown two way synchronization; a lighter one-way integration can do the trick.  

Here are some examples of what you can do with the Create via Gateway integration template:

Create via Gateway Use Cases

When you configure a Create via Gateway Integration, you can customize the field flow, artifact routing, and artifact filtering of your integration.


Video Tutorial

 Check out the video below to learn how to configure the Create via Gateway Integration Template.

(warning) This video assumes that you have already configured your repositories, models, and collections as outlined in the Quick Start Guide .



Use Case and Business Value

The Create via Gateway integration creates traceability between artifacts across the software development lifecycle. New artifacts will be created in a work item (repository) collection or container (repository) collection when artifacts are sent to Tasktop via a gateway collection. Optionally, these newly-created artifacts can be related to already-existing artifacts in the same repository.

For example, if your development team uses Gerrit for source code management and Solutions Business Manager (formerly Serena Business Manager) for Agile story management, you can set up an integration that would trigger the creation of changesets in SBM whenever changesets were created in Gerrit.  And if the changesets in Gerrit identify the stories in SBM to which they pertain, Tasktop would find the already-existing story in SBM and create a relationship between that story and the newly created changeset in SBM.

Changeset Traceability Integration

Additionally, if your QA team uses a tool like Selenium for test execution, and a tool like CA Agile Central (Rally) for test management, you can set up an integration that would trigger the creation of test results in CA Agile Central (Rally) when test results are created in Selenium. And if the test results from Selenium identify the tests in CA Agile Central (Rally) which they cover, Tasktop would find the already-existing test and create a relationship between the two artifacts.

Test Management Traceability Integration

Template Affordances

The Create via Gateway Integration Template allows you to flow artifacts from a single gateway collection into a single work item or container collection that connects to a repository.  When a new artifact is sent to Tasktop via our REST API, an artifact will be created in the target work item or container collection.


Template Affordances


Configuring a Create via Gateway Integration

To configure your integration, select Integrations at the top of the screen, then click New Integration.

Click 'New Integration'

Select the Create via Gateway template.

(lightbulb) Depending on the edition of Tasktop you are utilizing, you may not see all options shown below.

Select Template

This will bring you to the New Integration screen.

New Integration Screen

Name your integration and select your repositories and collections.

Name Integration and Select Repositories and Collections

You'll notice a configuration warning next to the Artifact Routing link if you haven't configured your routing yet. Routing is essential, since it tells your integration where (in which project, for example) to create each artifact's twin. You can learn more about Artifact Routing below.

You can click the Overview link on the right side of the Integration screen to get to the Overview screen.

Click 'Overview'

 Overview Screen

Field Flow

The field flow configured for a given integration specifies which fields should flow in that integration. For Create via Gateway integrations, you can choose to flow a given field (Update Normally) or to not flow a given field (No Update).

To get to the Field Flow screen, click Field Flow on the right pane of the Integration Configuration screen.

Click 'Field Flow'

You will be directed to the Field Flow screen.

Field Flow Screen

You can choose to flow a field ('update normally') or not flow it ('no update'). You'll notice that field flow goes in one direction only — from the gateway collection into the repository or database collection.

You can see the names of the mapped artifact fields for each collection on the far left and far right, with the model fields displayed in the middle. By default, model fields without mapped repository fields are hidden. You can see all model fields by checking the Show unmapped fields checkbox. Constant values will be identified by a grey box and the constant value icon.


Field Flow Icons

On the Field Flow screen, you will see a number of icons, which will help you understand any special properties or requirements for each field. If you hover your mouse over an icon, you will see a pop-up explaining what the icon means. You can also review their meanings in the legend below:

IconMeaning

Constant Value Icon

A constant value will be sent.

Note that:

  • If the icon is on the side of the collection, this means that a constant value will be sent to your model. This means that any time this collection is integrated with another collection, the other collection will receive this constant value for the field in question.
  • If the icon is on the side of the model, this means a constant value will be sent to your collection. This means that any time this collection is integrated with another collection, that this collection will receive this constant value for the field in question.

State Transition Icon

A state transition will be utilized. Note that:

(lightbulb) Note that Tasktop will update the field flow frequency for fields utilizing state transitions to 'no update.' This is because they are updated via the transition and not via normal 'field flow.' Do not modify the field flow frequency for this field.

Read Only Icon

Collection field is read-only and cannot receive data

Required for Creation Icon

To create artifacts in your collection, this field must be mapped to your model.

Required Icon

This is a required field in your model; it must be mapped to your collection.

Field Not Mapped

This field will not be updated as part of your integration, due to how you have configured it. This field flow configuration can be changed if you'd like.

Prohibited Field Flow

This field will not be updated as part of your integration because the mapping would be invalid. You do not have the option of changing this.

update normally icon

This field will update normally as part of your synchronize integration; this means it will be updated whenever it is modified on the corresponding artifact.

Artifact Routing 

Artifact Routing - Funnel Diagram
Artifact Routing is needed when artifacts are being created as part of an integration. In addition to knowing the repository in which artifacts should be created, Tasktop also needs to know which container (i.e., project, module, folder, etc) a given artifact should be created in. Specifying the artifact routing does this. 

To configure Artifact Routing, select Artifact Routing on the right pane of the Integration Configuration screen.
Click 'Artifact Routing'

Static Artifact Routing

In some cases, all artifacts in a gateway collection are routed to just one project in the target collection. In these instances, you can configure what is known as 'static artifact routing' (also known as 'explicit artifact routing').

To configure a static artifact route, use the Route More Projects buttons to add projects from your collections to your workspace and connect them using the Connect button.

(lightbulb) Note: Static artifact routes can have one or more source projects, but only a single target project.

Static Artifact Routing

In the example shown below, artifacts from Gateway Defects will be created in the Desktop Project in Jira.Static Artifact Routing Configured

Conditional Artifact Routing

Check out the video below to learn more about Conditional Artifact Routing:

 

In other cases, you may wish to route your gateway artifacts to multiple projects in the target collection.  In this scenario, a field value on the artifact is used to determine which project in the target collection the artifact should route to.

In these instances, you will configure what is known as conditional artifact routing to determine which project each artifact is created in within your target repository. Conditional artifact routing (also known as 'dynamic artifact routing') can be used to inspect a single-select field of an artifact and, depending on its value, to route that artifact to the appropriate project in the target collection.

Conditional artifact routes can have one or more source projects, and always have multiple target projects.

Conditional Artifact Routing

To create a conditional artifact route, use the Route More Projects buttons to add projects from your collections to your working space and connect them using the Connect button.

Configure Artifact Routing

Notice that after you've created your conditional artifact routing group, you'll be prompted to set the conditions that will define that route.

Configuration Needed


Click Save and then click Configure. You'll be brought to the Conditional Artifact Routing screen. Here you'll start by selecting the model field on the artifact that you would like to use to determine your artifact route. 

(lightbulb) Note: Conditional Artifact Routes can only be configured based on single-select fields in your model.

In the example below, the field Application contains the unique values that should determine the project an artifact will be created in in Jira.

Select Model Field for Conditional Routing
After you select the model field, you can identify one or more value to correspond to each target project. You can also use the Manage Values link to select from a list of values.
Set Conditions for Routing
Once you've done this, you'll see your full conditional artifact routing group.
Conditional Routing Set

You can also specify how you'd like to handle artifacts that do not meet any of the conditions specified by selecting one of the options provided at the bottom of the screen:

Specify Handling for Artifacts Not Matched by Conditional Filter

Artifact Filtering

When configuring your integration, you have several options available to refine which artifacts are eligible to flow. The final mechanism available is artifact filtering, which is configured at the Integration level.

Artifact Filtering - Funnel Diagram

Artifact Filtering enables you to set filters in order to limit which artifacts are eligible to flow in an integration.

To use a field for artifact filtering, it must:

  • Be a part of your model, and be mapped to the collection you are filtering from
  • Be one of the following field types:
    • Single Select
      • Note that in cases where 'allow unmapped values to flow' is enabled in the model, only fields that are already a part of the model will be considered for artifact filtering
    • Multi-Select
      • Note that in cases where 'allow unmapped values to flow' is enabled in the model, only fields that are already a part of the model will be considered for artifact filtering
    • Date
    • Date/Time
    • Duration
    • String

To configure Artifact Filtering, select Create filters (optional) from the Integration Configuration Overview screen, or select Artifact Filtering from the right pane of the Integration Configuration screen.

Click 'Artifact Filtering'

This will lead you to the Artifact Filtering Configuration screen, where you can configure one or more criteria for artifact filtering.  

(lightbulb) You can click the Collapse All button to view an easier-to-read summary of your artifact filtering statements.

Configure Artifact Filtering

 


Running your Integration

(warning) Please be aware that integrations will trigger changes in your end repositories and that misconfiguration can cause items to be duplicated or modified in unexpected ways. Additionally, there is no 'undo' in Tasktop or the repositories. If you have any questions, please contact support.

There are two ways to start or stop your integration:

From the Integration Configuration Screen

Simply click the Run button to run the integration, and the Stop button to stop the integration.

Click 'Run'
Click 'Stop'

From the Integrations List Page

Click Run or Stop next to each integration you would like to update. You can also use the Bulk Actions button to run or stop all integrations.

Run or Stop Integrations from Integration List

 Bulk Actions

Viewing Your Integrations

See Tasktop Editions table to determine if your edition contains Integration Landscape View functionality.

When viewing your integrations, you have the option of viewing them in either Landscape or List mode.

Integration Landscape View

Integration List View

Landscape View

See Tasktop Editions table to determine if your edition contains Integration Landscape View functionality.

 Learn more about the Integration Landscape view in the video below:

Tasktop will default to the Landscape View, which enables you to visualize your entire integration landscape and see how your integrations relate to one another.  Use our built-in filters to see as little or as much information as you'd like!

 

Here's a simplified view:

Integration Landscape - Simple View

If you'd like to see additional information, you can utilize the filters, or click on a repository node to modify which information is shown.

Some examples of additional information you can see are:

  • Models
  • Artifact Types
  • Artifact Creation Directionality Arrows
  • List of all relevant integrations (see this by clicking on the repository node)
    • Indicator of whether each integration is running or not

 Here's an example of a more detailed view:

Integration Landscape - Detailed View

List View

 If you'd like, you can toggle to List view, which will show you a list of all integrations you have created.

You can use this view to:

  • Start an Integration
  • Stop an Integration
  • Delete an Integration
  • Click into an Integration and modify its configuration 

Integration List View

 

Tips and Tricks

Creating Relationships Between Newly Created Artifacts and Existing Artifacts

If you'd like to create relationships between your newly created artifacts and existing artifacts in the same repository, please follow the additional steps listed below:

At the Model level: When creating your model, you can create a field that is of type “relationship” or “relationships”. You should use “relationship” when the newly-created artifact can only relate to one other artifact and “relationships” when the newly-created artifact can relate to multiple artifacts.

For example, the relationship field type, “Parent," should generally be singular, as most artifacts usually only have a single parent. However, if the relationship field type is called “Blocks”, it can likely be plural, as one artifact can block many artifacts.

In the use case example described at the top of this page, I want the relationship to be “Affects” because any incoming changeset can affect many stories. So I’ll configure a relationships field.

Add Relationships field to Model

At the Repository Collection level: When creating your repository collection, you will need to map a field in your repository to the relationship(s) field in your model. So, in the same example, if you want the relationship between the new changeset and the existing story to be “affects”, but the relationship is actually called “items linked” in SBM, you would need to map those two fields. You’ll need to do this for each relationship type configured in your model.

Configure Relationships at Collection Level

Map Relationships field to Collection

At the Gateway Collection Level: When creating your gateway collection, you will see that for each model field that is of relationship(s) type, you must specify the target repository that contains the related artifact(s). Once this is selected, the information needed for Tasktop to successfully locate the artifact will be added to the example payload.

Once Repository is Specified, Example Payload is Updated

Viewing Associated Configuration Elements

To view associated configuration elements (such as collections or models that utilize the integration you are viewing), click the Associated Elements tag in the upper right corner of the screen.

View Associated Elements

Associated Elements