Webservices related to Scenarios

The notion of 'Scenario' is defined as a series of actions that will be applied to a profile in an automated way on the basis of a trigger event and of filters, in order to personalize the communication.

The creation of a scenario is not possible through API. It must necessarily be done via the ACTITO interface. For additional information on this subject, we invite you to read the chapter dedicated to 'Scenarios'.

However, the execution of a scenario for a given profile can be triggered by several factors:

  • by an event (unsubscribing, opening an e-mail,...)

  • by a planned task (computation of profiles intended for a scenario (such as an anniversary,...)

  • by an external trigger (API or webservice call)

Webservices related to scenarios enable you to:

  • obtain information about existing scenarios and their interactions

  • trigger a scenario for a given profile

images/download/attachments/615292664/image2019-3-22_16-13-56.png

Setting up a scenario for trigger by API

In order to let a scenario be triggered by webservice, it must be set up with that in mind during its creation.

Among the available 'Start events', you will need to choose a 'Start' block. It is the only start event which will allow to trigger the event by API. After activating it, a scenario cannot be modified anymore. It is therefore necessary to decide whether a scenario will be triggered by API as soon as you create it.

images/download/attachments/615292664/image2019-4-9_17-29-18.png

Obtaining information about existing scenarios for a profile table.

In order to trigger a scenario by API, using the technical name of the targeted scenario is necessary.

This technical name does not match the display name that you chose at the creation of the scenario. Moreover, it is not easily found within the ACTITO interface.

To retrieve the technical name of a scenario, you can use the operation GET/entity/{e}/table{t}/scenario

This method will allow you to obtain the list the list of every scenario linked to a specific database.

You will need to enter the following parameters:

  • the entity to which the profile table belongs

  • the name of the profile table targeted by the scenario

  • a filter on the display name, in order to focus on a specific scenario. You can use asterisks before and after the search term to carry out a partial search

  • a filter allowing you to only get scenarios triggered by webservices (isStartEventTriggered=true)

  • a filter allowing you to only get active scenarios (isActive=true)

images/download/attachments/615292664/image2019-3-22_16-38-59.png

Example of a request and its response: (Download this example)

GET/entity/{e}/table/{t}/scenario
Curl call
curl -X GET --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/scenario?name=Doc*&isStartEventTriggered=true&isActive=true"
 
Response body
{
"workflows": [
{
"name": "DocScenarioAPI60dd2012-b296-43fc-bae5-6cb6c1b2d170",
"id": 11160,
"isStartEventTriggered": true,
"isActive": true
}
]
}

The response will give you the two IDs that can be used to trigger a scenario by webservice call:

  • "name": this is the technical name of the scenario. It is based on the display name followed by a string of characters

  • "id": this is the auto-generated technical id

Triggering a scenario by API

When a profile fits the scenario trigger condition that you defined in your internal system, you can program a webservice call which will trigger the ACTITO scenario for this profile.

To do so, you need to use the operation POST/entity/{e}/table/{t}/scenario/{s}/profile/{p}

The parameters needed are:

  • the entity to which the profile table belongs

  • the name of the profile table targeted by the scenario

  • the id of the scenario: you can use either the technical name of the scenario or its auto-generated technical id. Both are obtained with the GET method described above

  • the id of the profile: it can be its technical id ("profileId") or a "keyAttribute=value" pair

images/download/attachments/615292664/image2019-3-22_17-5-19.png

Example of a request and its response: (Download this example)

POST/entity/{e}/table{t}/scenarios/{s}/profile{p}
Curl call
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/scenario/11160/profile/147471"
 
Response body
{
"interactionBusinessKey": "df98b314-d1cc-4cbc-bb55-7a71ef695d39"
}

You will obtain the business key of the interaction as response.