Journey Definition Overview

The journey definition is a structured group of instructions that form an acyclic
graph and is described in XML syntax.
During execution of the journey, this graph is traversed based on chosen options
and input data retrieved from user interaction. The journey execution ends when
a response instruction is reached. This will give the result of the journey.
The chapters below describe the different entities of the XML syntax used to
specify a journey for execution on EWP.

Journey Definition Instructions

Journey

Journey is the root element of a journey definition.
Table 1 Elements

Instruction

are the building blocks for a journey definition that specify the behavior during
journey execution.
Some instructions may refer to other instructions, creating a parent-child
relationship.

Once an instruction is executed, its children instructions will be executed
recursively in a depth first strategy, and then another instruction in the same level
as the parent instruction will execute.
The following instruction types are defined:
— argument
— dynamicargument
— question
— options
— dynamicoptions
— exists
— matches
— switch
— response
— responsematching
The available set of instructions is below grouped into instructions for user input,
session data, control flow and session finalization. The following chapters
describe each of the listed instruction types in detail.

Session Data Instructions

The instructions in this section can be used to store data for the ongoing session.
Any data that is captured during journey execution is stored as key value pairs
called arguments.
These arguments can be referred to from all instructions, the syntax $
{argument-key} is during execution resolved to the argument-value stored for
the given argument-key.

Argument

Purpose
The argument instruction is used to add data to the user session so it can be
retrieved later by other instructions
The data to be stored is a key and avalue pair, see Table 2.
Any previous value that was associated to the same key will be overwritten.

Table 2 Element

<argument>
<key>yearofbirth</key>
<value>1990</value>
</argument>
<argument>
<key>yearssincebirth</key>
<value>${age}</value>
</argument>

Example Explanation
The argument with key yearofbirth will be added to the user session, with the
value of 1990.
The argument with key yearssincebirth will be added to the user session, with
the value contained in the argument with key ${age}.
If no argument is found an error will be thrown.

dynamicarguments

Purpose
To get arguments from a service provider to be added to the user session.
This instruction causes a request with a set of arguments being sent to a given
URL. In response a set with arguments is received that will be added to the user
session.
The request is synchronous and journey execution will halt until response is
received or time-out.
With this construction, it is possible to pass user input onto the service provider
for further processing.
The arguments sent in response could be used to control the execution path of
the journey or they could be used in response to the end user.

Table 3 Elements

<dynamicarguments>
<url>https://provider-gateway.com/djs/dynamicarguments?get</url →
>
<arguments>
<argument>
<key>username</key>
<value>Walden</value>
</argument>
<argument>
<key>age</key>
<value>${age}</value>
</argument>
<arguments>
</dynamicarguments>

Example Explanation
A request with the arguments username and age will be sent to https://providergateway.
com/djs/dynamicarguments?get.
The Username has value Walden, and age has the value of age argument from
the user session.
All data received in the response from the service provider will be added to the
session. If no argument with the key age is found, an error will be thrown.

User Input Instructions

This set of instructions allows for gathering input data from the user.
The journey execution proceeds until a user input instruction is reached, then it
halts and returns a response to be used by the client application to prompt the
user for input data.
The client should enter the required user input to continue the execution of the
journey.

Question

To present a question to the user and to retrieve a corresponding answer.
When a question instruction is encountered, the journey execution is paused, and
the question is prompted to the user.
The client should then resume the journey execution by sending an answer to the
question in a new request.
Note: It is important to flag questions as confidential if the expected answer
may contain confidential data, otherwise the received answer could be
exposed in log files.

<question>
<key>username</key>
<retries>3</retries>
<confidential>false</confidential>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Please enter your name</textmessage>
</text>
</texts>
</display>
<validation>
<pattern>&a-zA-Z]+</pattern>
<errormessage>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Only letters allowed.</textmessage>
</text>
</texts>
</errormessage>
</validation>
<transform><format>Name: ${username}</format></transform>
</question>

Example Explanation
A question will be prompted to the user, its answer will be stored in an argument
with the key username. The question is not confidential, so the answer will
appear in the audit logs.

The text Please enter your name will be displayed to the user case its
preferred language is English, or DJS will prompt an error stating that there is no
text for the user's language, and the session will be terminated.
The answer will be validated against the ba-zA-Z]+ regular expression.
If the answer is valid, its value will be transformed into the string: Name: $
{username}, and ${username} is the placeholder that will be replaced with the
value which has been just entered by the user.
After the transformation, which is optional, the value will be stored as an
argument in the session with the key username.
If the answer is invalid, the user will have three others retry attempts. If all the
retry attempts fail, the session will be terminated, and an error will be prompted
to the user.
In every retry attempt, an error message with the text Only letters allowed.
is displayed to the user if it has preferred language as English, or DJS will prompt
an error stating that there is no text for the user's language, and the session will
be terminated.

Options

A list of options to be presented to the user, who may select only one choice. This
is kind of a (sub)-menu presented to the user.
When a choice is selected, the set of instructions associated to it will be executed.
This set of instructions can include any instruction, including other options
instruction.
When an options instruction is encountered, the journey execution is paused, and
the available options are prompted to the user.
The client should then resume the execution by sending an answer containing the
chosen option in a new request.
This is explained in detail in the API section of this document.

<options>
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Final Confirmation</textmessage>
</text>
</texts>
</header>
<optionslist>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Purchase product</textmessage>
</text>
</texts>
</display>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Your order has been placed</textmessage>
</text>
</texts>
</response>
</instructions>
</option>
<option>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Cancel</textmessage>
</text>
</texts>
</display>
<instructions>
<response>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Order cancelled</textmessage>
</text>
</texts>
</response>
</instructions>
</option>
</optionlist>
</options>

Example Explanation
A set of options will be prompted to the user.
There is a header to explain what the options are, and if the user has English as
preferred language, the text will be Final Confirmation.
Two options will be displayed, one called Purchase product, the other one called
Cancel.
If the first option is chosen, a response instruction will run and show the text
Your order has been placed to the user.
If the second option is chosen, a response instruction will run and show the text
Order cancelled to the user.

dynamicoptions

Dynamic options work in an analogous way as options, but instead of having
pre-defined options written in the journey definition, the options can be
dynamically fetched during the journey execution. This makes it possible to
customize the options for each user based on either provided user input or other
user preferences.
When this instruction is encountered, a list of set of arguments is retrieved from
the specified URL. Each option is comprised by a set of arguments, and you
receive a list of options, thus a list of set of arguments. An option in the dynamic
options can only contain the argument instruction. Except for the default option,
which can contain any instruction and it is pre-defined in the journey definition.
The default option will be chosen automatically if no options are given by the
service provider. If no options are received and there is no default option, an error
will be thrown.
Analogous to dynamic arguments, you can specify arguments in the request,
enabling the service provider to customize the response.
There is only one display text in dynamic options, and this will be used to render
every option. This display text should contain placeholders that will be
substituted by the set of arguments that exists for each option.
When a dynamic options instruction is encountered, the journey execution is
paused, and the available options are prompted to the user. The client should

then resume the execution by sending an answer containing the chosen option in
a new request. This is explained in detail in the API section of this document.
When the option is chosen, each argument in the option's set of arguments is
stored in the session.

<dynamicoptions>
<header>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Special Offers</textmessage>
</text>
</texts>
</header>
<footer>
<texts>
<text>
<languagecode>en</language>
<textmessage>Please select one of the options above</textmessage>
</text>
</texts>
</footer>
<url>https://provider-gateway.com/djs/dynamicoptions?get</url>
<display>
<texts>
<text>
<languagecode>en</languagecode>
<textmessage>Your bonus of ${amount} with validity of ${validity}</textmessage>
</text>
</texts>
</display>
<arguments>
<argument>
<key>campaign</key>
<value>summerspecial</value>
</argument>
<argument>
<key>code</key>
<value>${customkey}</value>
</argument>
</arguments>
</dynamicoptions>

Example Explanation
A list of options will be retrieved from https://provider-gateway.com/djs/
dynamicoptions?get
Two arguments will be sent to the provider: campaign, with the value
summerspecial, and code, with the value contained in the argument with key
customkey.
If no options are received, an error will be thrown, since there is no default option.
A header will be displayed with the text Special Offers, and a footer with the text
Please select one of the options above.
A list of options will be displayed, substituting the argument templates for the
ones received in the response. One example of the list could be:
— Your bonus of 10USD with validity of 1 month
— Your bonus of 50USD with validity of 3 months