Perform bulk modifications or loops with repeating steps

Similar to an HTTP step, a repeating step can be added to an action sequence. You will find the option for adding a repeating step after you have decided to trigger an action sequence as action.

In this topic, we mainly look at the various functionalities within a repeating step. In Example for setting up repeating steps, we have a look at an example and use the FreeMarker language to get more out of this functionality.

To add a repeating step to an action, click on Add a repeating step to add a step that should be performed multiple times within your action sequence.

After clicking the ‘Add a repeating step’ button, a new step is added to the action sequence.

Besides various options you might recognise of other steps in action sequences, a repeating step contains the following fields and sections to help you set up your step:

By filling in the field ‘Number of repetitions’, you tell TOPdesk how often the whole repeating step must be repeated. To know how far down the list of repetitions TOPdesk is when executing the action sequence, it uses the variable i. This is the ‘repetition index’. The repetition index is incremented by one every time the step is repeated, up until the set number of total repetitions is reached.

Within the repeating step, use [i] in the code of your step to get to the ith element of the list. This helps you in getting information about that element on the list and use it in your step.

By using [i] in your code, you tell TOPdesk to not simply repeat all steps in exactly the same way, but to perform the steps for element i in your list. See Example for setting up repeating steps below for this concept being used.

In this example, we have a look at using repeating steps to update the mobile phone number on a Person card every time the phone number on the Mobile phone asset card assigned to them has been changed.

We’ll focus on the extra steps you need to take to set up your repeating step. Therefore, we will not discuss the trigger (a change on the Mobile phone asset card), and various basic parts of the action sequence such as Authorization headers and variables. These are explained in more detail in Integrate and automate with Action Sequences.

In this example, the list consists of all Person cards that are linked to our Mobile phone asset. We get this list by performing a GET request to our TOPdesk. The first step in our action sequence is a regular HTTP step. Create this first step by clicking Add an HTTP step. We call it ‘Get all assignments’. Then, use the following URL, based on the Update an existing asset API endpoint:

/tas/api/assetmgmt/assets/${_card["id"]!}/assignments

The variable ${_card["id"]!} represents UNID (system field) and is added via the Insert Value button. This ensures that the list of assignments of the relevant asset is requested. When this step is performed, the list of all assignments (including all persons the mobile phone is assigned to) is returned in the response body.

Figure 1. The first step in our action sequence

Next up, we add a step that fills the mobile phone number on every Person card we just requested. Click Add a repeating step to add a new step to the action sequence that gives us the possibility to perform one or more steps for every element on the list.

In Number of repetitions, enter the following:

${_responses["Get all assignments"]["body"].persons?size}

To break down this input:

Now that we know how often the step must be repeated, we tell TOPdesk which actions to actually repeat. To update a field on Person cards, we use the Update a person by id PUT API endpoint to fill the URL:

/tas/api/persons/id/${_responses["Get all assignments"]["body"].persons[i].person.id}

Let’s break down this input again:

Because TOPdesk increments i by 1 with every repetition, TOPdesk knows that with every repetition it has to grab the information for the next person on the list.

We now tell TOPdesk what to actually do on the Person cards. For this example, in the Body field, we enter the following to use the Asset card’s phone number field and fill the Person card’s Mobile Number field:

{"mobileNumber": "${_card["phone-number"]!}"}

Please mind that ‘phone-number’ is a custom field in Asset Management. You can use whatever field you want to copy information from.

This will result in the following repeating step:

Figure 2. The repeating step in our action sequence

At last, we use the Continue repeating field to set whether the loop should always attempt to complete the list, or to stop when a repetition has failed.