Automation Rules

Automation Rules

Automation Rules add greater flexibility to Targetprocess by applying new triggered responses to changes within or outside of the application.

This feature adds the ability to automatically react to a change in Targetprocess or an event in a third party service, execute custom logic, and form a pack of changes that will be made in Targetprocess as a result. For example:

• If a comment is added to a Request - reopen the Request.
• If a GitHub pull request is merged - change the state of the related User Story (or any other entity).
• And many additional use cases.

Automation Rules may also replace complex solutions made by the combination of Web Hooks and Metrics. However, the Automation Rules do not replace Metrics on their own. This feature covers many complex scenarios where the use of the Metrics is a current workaround.

Targetprocess admins may access the Automation Rules Setup UI in settings:

More detailed documentation about Automation Rules can be found here. Information about JavaScript support is available here.

In further blog posts we will review some of the possible scenarios that can be covered with the Automation Rules in more detail and describe how they can be implemented using the feature.

We've divided these scenarios into two major groups:

• Internal Automation. These are scenarios where an Automation Rule reacts to an event in Targetprocess and makes changes also in Targetprocess.
• External Integrations. In these scenarios events trigger Automation Rules from an external system.

Internal Automation

When a Request is Created - Create a Related Bug

To implement such a scenario the Modified Entity source should be selected for an Automation Rule. Here is the rule in action:

When a Team Iteration is Created - Estimate its Velocity

Let's review a more complex scenario that requires one of the key features of the Automation Rules - the ability to execute custom JavaScript.

In Targeprocess we have very powerful API V.2 DSL that is used for querying data. It's used in Metrics and for reading data by our frontend, and in external or internal integrations. This DSL is extremely flexible in terms of filtering, grouping, and mapping requested data. However, for many business scenarios our flexible query DSL is not enough because it's impossible to for example:

• save some temporary information that will be needed later in a variable;
• do some complex calculations based on queried records and some additional data in a loop;
• query additional data from Targetprocess.

To increase the flexibility of Targetprocess we've introduced the ability to use the most popular programming language on the Earth - JavaScript in Automation Rules.

The start of this configuration is similar to the previous rule except this case rule is triggered by Created Team Iteration. The interesting part is hidden in the actions section. In this case the rule should set the Velocity of the new Team Iteration to an average of the 5 latest completed Team Iterations' effort of the given Team. To achieve this behavior Execute JavaScript function action should be used. This action is described via the body of the JavaScript function that accepts as input information about the event that triggered the rule. Within this function it's possible to read data from Targetprocess using API V.2 DSL.

For this rule the definition of the JavaScript action looks like this:

const api = context.getService("targetprocess/api/v2");

// read completed team iterations for the created team iteration's team from targeprocess
const response = await api.queryAsync("TeamIteration", {
    where: `Id!=${args.ResourceId} and Team.Id=${args.Changed.Team.Id} and Progress == 1`,
    select: `{id,startDate,effort}`,
    orderBy: 'startDate desc',
    take: 5
});

// if there are no previous team iterations for the created team iteration's team
// there is no need to update anything because we can't estimate velocity
if (response.length <= 0) {
    return [];
}

// calculate average effort of closed team iteration of the created team iteration's team
const avgEffort = response.reduce((acc, x) => acc + x.effort, 0) / response.length;

// return command to update create team iteration with calculated velocity
return [
    {
        command: "targetprocess:UpdateResource",
        payload: {
            resourceType: "TeamIteration",
            resourceId: args.ResourceId,
            fields: {
                Velocity: avgEffort
            }
        }
    }
];

External Integrations

For External Integrations we added an incoming web hook source for Automation Rules. This source allows us to create a unique HTTP endpoint in Targetprocess that can be used for integrations with any service that can send HTTP requests with JSON content.

When a GitLab Pipeline Passes - Move a Related Entity to Another State

Automation Rules make it possible to connect the workflow of entities in Targetprocess with events in GitLab for example. In this example, the naming convention is used for linking branches to entities in Targetprocess:

When a GitLab Commit is Pushed  - Add a New Record to the Sources Tab on Entity View

With Automation Rules it's possible to link commits in version control to a related entity. There is also no need for configuring Targetprocess Git Plugin and SSH access for it anymore.

What's Next

Better Suggestions for JavaScript

The current JavaScript editor supports only basic suggestions. We want to add suggestions that depend on a modified entity or an external event.

Automation Rules Navigation

At the moment rules are displayed as a plain list. We want to make it possible for users to organize created rules in a more comfortable way.

Better Diagnostics

Right now only errors are displayed in the diagnostics pop-up. We want to extend it to display information about successful rule executions - for example, the results of filtering.