Skip to main content

Composing your action sequence

Creating a sequence

The action sequence card looks partly the same as the action cards for emails and HTTP requests. You indicate whether the action sequence should be active and where, and link events.

In this topic, we solely explain how the action sequence is created. For more information on preparing yourself for setting up an action sequence and the various tools you'll have at your disposal, see Action Sequences.

To create a sequence:

  1. Open the New automated action in one of the following ways:

    • Go to Modules > Action Management > Automated Actions and click New automated action.

    • Go to Modules > Action Management > New > Automated action.

  2. In the New automated action menu, pick the relevant (card) type.

  3. Click Create action.

    A new tab for the new action is opened.

  4. On top, behind ‘New action’, click the pen icon to set the name of the action.

  5. Determine when the action should trigger. You can change this later.

    Note

    For most card types, you can select events and select context menus. For some, only events are available. For Asset Management, you will select trigger types and specific card types. See Creating events to learn more about setting up events for your actions.

    Tip

    Use the Edit eventlightning bolt button to open any event available in the Select events menu.

    1. Click Select events, Select context menus, or Select card types, depending on the chosen card type.

    2. Search for events, or search through the list.

    3. Optionally, if using the Select events menu, use the Edit eventlightning bolt button to open any available event available.

    4. Tick the events that you want to link to the action.

    5. Press Apply.

    You have chosen triggers for your action. The triggers are displayed under the card type name and can be removed again by clicking the x icon. You can revisit this selection any time later on.

  6. Click Configure the action.

  7. Under What would you like to trigger?, select Action sequence.

    Note

    If you pick one of the other options, you can later on incorporate those in an action sequence.

  8. Set variables and value mappings if needed.

  9. Create the different steps of the sequence by adding one of the options for steps. Each HTTP step contains:

    1. A name. You use the name in later steps to refer to the response to this step. The name may only contains letters, numbers and underscores, so no space. It cannot start with a number.

    2. The HTTP Method: GET, POST, PUT, PATCH, or DELETE.

    3. The URL of the endpoint. This, and the content of the header and body fields, is explained in The URL and headers and The body.

    4. One or more headers. Click the plus button to add a header.

    5. When you use POST, PUT or PATCH: the Body. Enter the body of the request here.

    6. An execution rule. Indicate whether the step should always be executed, only if all previous steps succeeded, or only under a certain condition. In the latter case, set up a condition in FreeMarker. The step is then executed if the Freemarker output is 'true', and skipped if the output is 'false' or '' (empty). See Setting a custom condition for executing a step for an example.

    Note

    Other options are an email step, generate a document, repeating step, and Variable Assignment step.

  10. In the Description field, register what each step does. The names of the different steps might not be enough to see at a glance what the sequence does exactly.

  11. Save the card.

  12. Click on Finish your automated action to proceed.

  13. If the action is already ready for use, tick Activate action. In order to make the action work, tick Apply in the Self-Service Portal and/or Apply in the Operator Section.

  14. Save the card.

You have created an action sequence. Trigger the event to test if it works.

remark

Make sure the last character in a field is not a space. The sequence will not work when the content of a field ends with a space.

tip

Tools like RequestBin and Postman are useful to see what a request looks like to the receiving program.

The example below will create a call in TOPdesk:

example for action sequence.

Example for specifying which JSON or XML value to use

Let’s have a look at an example to find out how to correctly fill the Specify which JSON or XML value you want from the request/response body input field.

With a previous step, we have received a response body. By using websites such as JSONLint, automatically format the response in such a way that the structure becomes clearer. This gives you more insight in which values are nested in certain blocks, which is important for finding and using the right value in your next action sequence step.

Example 1: nested value

We received the following response body in an earlier step of our action sequence. If you have successfully tested this first step, the response body is found in the execution logs of the action sequence. Find this by looking for Response body: and copying the data behind it. Below is such a response body, in this case already formatted via JSONLint:

{
  "id": "27f69cfe-2855-4250-b166-b6b8d9d12193",
  "status": "firstLine",
  "number": "I 2204 150",
  "request": "02-04-2022 10:30 [GMT +2:00] John Smith: \nThe coffee machine does not work anymore",
  "requests": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/requests",
  "action": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/actions",
  "attachments": "/tas/api/incidents/id/27f69cfe-2855-4250-b166-b6b8d9d12193/attachments",
  "caller": {
      "id": "8a3956ef-d07d-4b67-816a-c432ef54e0ed",
      "dynamicName": "John Smith",
      "phoneNumber": "0610101010",
      "email": "jsmith@topdesk.com",
      "branch": {
          "id": "794fdd0c-254f-4991-b32c-8dcce199ab9f",
          "name": "TOPdesk USA",
          }
      }
}

To fill the Specify which JSON or XML value you want from the request/response body correctly, start with a ., followed by a value name of the first level. In this case, the first level is where we find id, status, number, request, requests, action, attachments, and caller.

If we choose caller, then we need to go one level deeper to tell TOPdesk which information about the caller we want to use. For each level we go deeper, we add another . in our input field.

Let’s say we need to use the name of the caller’s branch. In the example JSON above, we see we need to go to caller (first level), then to branch (second level), to name (third level). In the end, this results in the following input:

.caller.branch.name

Which is transformed by TOPdesk to:

${_responses["stepname"]["body"].call.caller.branch.name}

And alternative way of writing this is as follows:

${_responses["stepname"]["body"]["call"]["caller"]["branch"]["name"]}

Example 2: listed values

Not all requests give a response with the same structure. While the example above is about information of just one Call card, you sometimes get a list of similar values (or cards). An example of this is shown below with a list of possible statuses:

{
    {
    "id": "1b79a18e-d912-4e7f-861a-730402ad1c58",
    "name": "Registered",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "NOT_RESPONDED",
    "default": false
    },
    {
    "id": "8a2a122e-cc63-41e2-92bd-5b9da1772aa0",
    "name": "Planned",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "RESPONDED",
    "default": false
    },
    {
    "id": "ed5af114-0f70-4b40-8268-95135f6e66dc",
    "name": "In progress",
    "onHold": "NOT_ON_HOLD",
    "processingState": "NOT_COMPLETED",
    "response": "NOT_RESPONDED",
    "default": false
    }
}

In this case, we take the same steps as in the previous example. However, before we do so, we start by telling TOPdesk which entry in this list we want to look at. Do so by entering [x], where x stands for which entry we pick. The first entry is 0, the second one is 1, etc.

For this example, if we want to use the name of the second entry, we enter:

[1].name

Which results in:

${_responses["stepname"]["body"][1].name}

Handling error messages in actions

When an action cannot be fully executed, an error message is shown in the Execution logs. The log contains data on when an action was executed (also for successful executions), and for which card the action was performed. A maximum of 50 successful and unsuccessful executions are saved, before the oldest log entries are deleted.

To open the executions logs:

  1. Open an action from the Automated Actions overview.

  2. Click Open execution logs.

    You have opened the execution logs of your action.

On the left, a list of executions is shown. Click on a log entry to show the execution logs of a specific execution. On the right, the logs of the chosen execution appear and can be analyzed. You can enable (or disable) automatic refresh of the page, and filter the list of executions on their status.

If an action is performed for a specific card, you find a clickable link to that card right above the summary and details of an execution.

The shown execution dates are by default shown in UTC time. It is not possible to change this.

Permissions

For log entries to be accessible, an operator must have Read execution logs permission (under the Action Management - Automated Actions block) assigned.

Abort execution

If the execution of an action is either ‘queued’ or ‘in progress’, an Abort execution button appears below the Execution logs section.

Abort execution button under 'Execution logs' header.

When you abort an execution that is already in progress, it is stopped after the current step is completed.

[Action Management] API status codes

While troubleshooting your action sequence, you'll start looking for information about why a certain step doesn't work. TOPdesk's execution logs contain details about what happened in each step of a sequence, including what went well and what went wrong.

Each request done will contain an HTTP status code. These status codes are standardized and therefore mean the same for every application. Find an extensive list of HTTP status codes on the List of HTTP status codes Wikipedia page.

In this topic, we'll discuss a few of the more common error codes.

No execution log?

If there is no execution log, then the action wasn't triggered at all. In that case, you must first troubleshoot the trigger.

Most likely, the content of the request is invalid. It often comes with additional information, because this status code doesn't have just one specific cause. Some options are:

  • The field [...] does not exist: The field might be misspelled, not part of this API yet, or is not available in your TOPdesk version.

  • Request cannot be parsed: There are too many or too little whitespaces, (back)slashes, quotation marks, etc., or you try to update a field with a PUT or PATCH request that cannot be changed through the API.

  • The [...]-id [...] cannot be parsed: A unique ID doesn't contain hyphens, or is invalid in general.

  • The value for the field [...] cannot be parsed: When the content of a field contains a special character (e.g. "), which needs to be escaped by putting a backslash in front of it (\"). Another option is that the content for a date field does not follow the yyyy-MM-ddTHH:mm:ssZ (e.g. 2023-01-01T09:00.00Z) format.

For every request, so basically every step of an action sequence, you must provide TOPdesk with the login credentials of the Operator card you use for that request. And, of course, these credentials must be correct: the login name and a valid application password.

Just like regular operators, the Operator card you use for the API call must have sufficient permissions to perform a certain action. This error is generally caused by a lack of permissions, but might also be caused by a filter that prevents the operator from accessing all relevant cards. Also, make sure that Has Access and (ideally) API account are ticked on the Operator card.

With a 404 status code, the page cannot be found. In general, there is a spelling mistake in the URL (e.g. https:// is missing, or the use of capital letters is incorrect), or the unique ID of a card is incorrect.

This is a very general error message. However, within TOPdesk, we most often see this error when two actions try to edit the same card at the same time.