Create via Gateway

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

What is a 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 Hub 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:

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

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

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

Configuring a Create via Gateway Integration

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

Select the Create via Gateway template.

 Depending on the edition of Hub you are utilizing, you may not see all options shown below.

This will bring you to the New Integration screen.

Name your integration and select your 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.

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.

You will be directed to the 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:

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.

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

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

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.

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.

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

Click Save and then click Configure.

 Tip: Clicking ctrl+s on Windows and cmd+s on macOS will save your configuration.

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. 

 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.

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.

Once you've done this, you'll see your full conditional artifact routing group.

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:

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 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.

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

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

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.

Viewing Your Integrations

See the 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.

Landscape View

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

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

Hub 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!

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:

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 

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.

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.

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 Hub to successfully locate the artifact will be added to the example payload.

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.