Web Services

OTRS as Provider

Remote Request:

1. HTTP request

   • OTRS receives HTTP request and passes it through the layers.

   • The provider module is in charge to execute and control these actions.

2. Network transport

   • The network transport module decodes the data payload and separates the operation name from the rest of the data.

   • The operation name and the operation data are returned to the provider.

3. Data external

   • Data as sent from the remote system (this is not a module based layer).

4. Mapping

   • The data is transformed from the external system format to the OTRS internal format as specified in the mapping configuration for this operation (mapping for incoming request data).

   • The already transformed data is returned to the provider.

5. Data internal

   • Data as transformed and prepared to be passed to the operation (This is not a module based layer).

6. Operation

   • Receives and validates data.

   • Performs user access control.

   • Executes the action.

OTRS Response:

1. Operation

   • Returns result data to the provider.

2. Data internal

   • Data as returned from operation.

3. Mapping

   • The data is transformed back to the remote system format as specified in the mapping configuration (mapping for outgoing response data).

   • The already transformed data is returned to the provider.

4. Data external

   • Data as transformed and prepared to be passed to network transport as response.

5. Network transport

   • Receives the data already in the remote system format.

   • Constructs a valid response for this network transport type.

6. HTTP response

   • The response is sent back to the web service client.

   • In the case of an error, an error response is sent to the remote system (e.g. SOAP fault, HTTP error, etc).

OTRS as Requester

OTRS Request:

1. Event trigger handler

   • Based on the web service configuration determines if the request will be synchronous or asynchronous.

     • Synchronous

       • A direct call to the requester is made in order to create a new request and to pass it through the layers.

     • Asynchronous

       • Create a new generic interface (requester) task for the OTRS daemon (by delegating the request execution to the scheduler daemon, the user experience could be highly improved, otherwise all the time needed to prepare the request and the remote execution will be added to the OTRS events that trigger those requests).

       • In its next cycle the OTRS daemon process reads the new task and creates a call to the requester that will create a new request and then passes it through the layers.

2. Invoker

   • Receives data from the event.

   • Validates received data (if needed).

   • Call core modules to complement the data (if needed).

   • Return the request data structure or send a stop communication signal to the requester, to gracefully cancel the request.

3. Data internal

   • Data as passed from the invoker (this is not a module based layer).

4. Mapping

   • The data is transformed to the remote system format as specified in the mapping configuration (mapping for outgoing response data).

   • The already transformed data is returned to the requester.

5. Data external

   • Data as transformed and prepared for sending to the remote system.

6. Network transport

   • Receives the remote operation name and the data already transformed to the remote system format from the requester.

   • Constructs a valid request for the network transport.

   • Sends the request to the remote system and waits for the response.

Remote Response:

1. Network transport

   • Receives the response and decodes the data payload.

   • Returns the data to the requester.

2. Data external

   • Data as received from the remote system.

3. Mapping

   • The data is transformed from the external system format to the OTRS internal format as specified in the mapping configuration for this operation (mapping for incoming response data).

   • The already transformed data is returned to the requester.

4. Data internal

   • Data as transformed and ready to be passed back to the requester.

5. Invoker

   • Receives return data.

   • Handles the data as needed specifically by each invoker (included error handling if any).

   • Return the Invoker result and data to the Requester.

6. Event handler or OTRS daemon

   • Receives the data from the requester. In the case of the OTRS daemon this data might contain information to create a task in the future.

OTRS as Provider – HTTP::REST

The configuration might be a bit more complicated, as it grows dynamically for each configured operation by adding route mapping for each operation and valid request methods for each operation to the default transport settings.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Route mapping for Operation ‘<OperationName>’ *

Define the route that should get mapped to this operation. Variables marked by a : will get mapped to the entered name and passed along with the others to the mapping (e.g. /Ticket/:TicketID).

In this setting a resource path is set. This path must be defined according to the needs of the web service considering that the path in conjunction with the HTTP request method determines the generic interface operation to be executed.

Path can contain variables in the form of :<VariableName>. Each path string that fits on the position of the variable name will be added to the request payload using the variable name defined in this setting. Examples:

Valid requests for /Resource route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One

Invalid requests for /Resource route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource?Param1=One

Valid requests for /Resource/:ID route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1?Param1=One

In both cases ID = 1 will be sent to the operation as part of the payload. In the second case also Param1 = One will be added, depending on the HTTP request method other parameters will be added if they come as a JSON string in the request header.

Invalid requests for /Resource/:ID route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One

Valid requests for /Resource/OtherResource/:ID/:Color route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1/Red
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherReosurce/123/Blue?Param1=One

In the first example ID = 1 and Color = Red, while in the second ID = 123 and Color = Blue.

Invalid requests for /Resource/OtherResource/:ID/:Color route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1?Param1=One

In the first example the part of the path /OtherResource is missing as well as the :Color variable. In the second example just the :Color variable is missing.

Valid request methods for Operation ‘<OperationName>’

Limit this operation to specific request methods. If no method is selected all requests will be accepted.

The HTTP request methods to determine the operation to use together with the route mapping, possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE.

Totally different operations can share exactly the same mapping path, but the request method must be unique for each operation, in order to determine correctly the operation to use on each request.

Maximum message length *

Specifies the maximum size (in bytes) for REST messages that OTRS will process.

Send Keep-Alive *

This configuration defines if incoming connections should get closed or kept alive.

Additional response headers (all operations)

Optionally, you may want to define additional response headers for all operations. These may be used to add static header values to every response. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response headers (operation specific)

These headers will be set in responses for the selected operation. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

OTRS as Provider – HTTP::SOAP

It is quite simple to configure the HTTP::SOAP protocol as provider.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Check SOAPAction *

Set to Yes in order to check the received SOAPAction header (if not empty). Set to No in order to ignore the received SOAPAction header.

SOAPAction scheme *

Select how SOAPAction should be constructed. Some web services send a specific construction.

SOAPAction separator *

Character to use as separator between name space and SOAP operation. Usually .Net web services use / as separator.

Namespace *

URI to give SOAP methods a context, reducing ambiguities.

Request name scheme *

Select how SOAP request function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.

Response name scheme *

Select how SOAP response function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.

Maximum message length *

Specifies the maximum size (in bytes) for SOAP messages that OTRS will process.

Additional response headers (all operations)

Optionally, you may want to define additional response headers for all operations. These may be used to add static header values to every response. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response headers (operation specific)

These headers will be set in responses for the selected operation. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response SOAP namespaces (all operations)

These namespaces will be used in every response.

Additional response SOAP namespaces (operation specific)

These namespaces will be used in responses for this specific operation.

Sort options

Outbound sort order for XML fields (structure starting below function name wrapper) – see documentation for SOAP transport.

Web Service Operation

The actions that can be performed when you are using OTRS as a provider are called operations. Each operation belongs to a controller. Controllers are collections of operations or invokers, normally operations from the same controller need similar settings and share the same configuration dialog. But each operation can have independent configuration dialogs if needed.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.

Description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the description will be also displayed in the overview table.

Operation backend

This OTRS operation back end module will be called internally to process the request, generating data for the response.

The operation back end is pre-populated and cannot be edited. You will see this parameter when you choose the operation on the web service edit screen. The field is only informative.

Mapping for incoming request data

The request data will be processed by this mapping, to transform it to the kind of data OTRS expects.

Mapping for outgoing response data

The response data will be processed by this mapping, to transform it to the kind of data the remote system expects.

Include Ticket Data

Whether to include ticket data in response or not.

Mappings are fields that normally appear on every operation, but other special fields can appear in non default configuration dialogs to fulfill specific needs of the operation.

Normally there are two mapping configuration sections for each operation, one for the incoming data and another one for the outgoing data. You can choose different mapping types (back ends) for each mapping direction, since their configuration is independent from each other and also independent from the operation back end. The normal and most common practice is that the operation uses the same mapping type in both cases (with inverted configuration). The complete mapping configuration is done in a separate screen which depends on the mapping type.

In the left part of the screen on the action column you have the options to go back to web service (discarding all changes since the last save) and delete. If you click on the last one, a dialog will open and ask you if you like to remove the operation. Click on the Delete button to confirm the removal of the operation and its configuration or click on the Cancel button to close the delete dialog.

Generic Link Object Invoker

Additionally to the configuration item functionality, the Generic::LinkObject invoker provides the functionality to link objects, like ticket to configuration items or configuration items to configuration items together. The invoker can get used to pull new links from a remote system or keep the provided links in sync and delete removed links from the OTRS database. There are no limits in linking different objects.

For linking different objects together the following mapping keys need values:

- SourceClass
- SourceObject
- TargetClass
- TargetObject
- Type

The OTRS internal object ID can be provided directly with the key SourceKey and TargetKey or can get looked up by providing the OTRS object number with the keys SourceNumber and TargetNumber.

To keep the OTRS in synchronized with the remote system it is possible to select different link combinations, e.g. parent-child ticket to ticket, to get synchronized. This means if a remote link combination was removed the local link will get removed, too.

The synchronization of configuration item classes can be limited by selection the classes that should get synchronized from the list in the invoker administration view.

Generic Operations Invoker

The Generic::Operations invoker allows you to define Stages where each mapping defined as stage are executed next to each other. The output of one stage will be the input of the next stage.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.

Description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the description will be also displayed in the overview table.

Operation backend

This OTRS operation back end module will be called internally to process the request, generating data for the response.

The operation back end is pre-populated and cannot be edited. You will see this parameter when you choose the operation on the web service edit screen. The field is only informative.

Mapping for outgoing response data

The response data will be processed by this mapping, to transform it to the kind of data the remote system expects.

Mapping for incoming request data

The request data will be processed by this mapping, to transform it to the kind of data OTRS expects.

User for operations *

The operations will be processed by using this user.

Stages

Here you can add stages which will be processed next to each other. It is possible to add as many stages as needed by the Add stage button.

Click on the Save button to have a Configure button next to each stage. Here you can add XSLT stylesheet for each stage.

Event Triggers

This invoker will be triggered by the configured events.

Add Event Trigger

To add a new event select the event object and event name and click on the + button.

Configuration Item Invoker

The ITSM::ConfigItem invoker provides the functionality to request a list of configuration items from a remote system with the generic interface. A complete mapping between the name of remote value keys to the local configuration item class definitions is possible. In order to give the possibility to define all class attributes in the mapping, an advanced mapping is provided.

For handling remote configuration items and links, an advanced mapping is provided with this feature. To use this functionality select the ITSMConfigItem in the mapping select box.

One of those advanced mapping features are static values. These make it possible to define static values for defined keys, for example setting the configuration item class for each item. These entries can overwrite data send from the remote system.

Another feature provided by the advanced mapping are transforming strings to list structures. For creating a list out of a string, a list separator can be defined, for example ;. The separator field takes a regular expressions which make a more complex separators like ;(?:\s+)? (a ; optionally followed by multiple white spaces) possible.

It is possible to define where the index of the elements should take place in the configuration item structure. For this the placeholder ###INDEX### has to be placed in the key mapping. The configuration in the screenshot would store the separated IP address list into a new interface each. If no index is defined in the mapping, the index will increase the main attribute counter, like a suffix.

The configuration item Number attribute is used to make the logical connection between the remote data and the data stored in the OTRS database. To create and update configuration items with this invoker values for the following keys are required:

- Name
- Class
- Number
- DeploymentState
- IncidentState

The values for these keys (except Number) can be static or provided by the remote system.

Configuration Item Synchronization Invoker

The ITSM::ConfigItemSync invoker provides the functionality to synchronize configuration items between two OTRS instances using a special synchronization invoker. That invoker allows to define invokers for create, update and delete synchronizations, that gets called automatically if needed.

To synchronize configuration items between two systems, it is needed to add a web service with an invoker of type ITSM::ConfigItemSync. This invoker is the basic (search) invoker that is used to perform ITSM object searches on the remote system to determine configuration items to be modified.

It works with two steps on every sync action:

1. At first depending on the change that was made in the local system (add, update or delete a configuration item) the invoker performs a related search on the remote system to determine, if it is needed to create, update or delete a remote configuration item.

2. On the second step, a related invoker for create actions, update actions or delete actions is called, which executes the main changes on the remote system. Those invokers have to be created as well and needs to be of invoker type ITSM::ConfigItem to make sure the communication works properly.

See the enclosed overview of example invokers:

Within the search invoker configuration, the worker invokers to perform the changes needs to be configured separately for every action in the related drop-down menus.

If an invoker is not configured for the related action, it will be omitted. The configured invoker will be listed within every drop-down and can be selected easily for the different actions.

The different invokers needs to map their data. For this to work properly, it is recommend to use the mapping module ITSMConfigItem, which will be described through this documentation, but in fact it is also possible to use other types of mappings like XSLT if configured properly.

Since this structure calls remote systems, it is needed to configure at least the connection credentials to access the remote CMDB.

All other configurations can be set optional, but they are not needed for the basic feature to work.

To be sure the search invoker just listens on specific events, this functionality extends the possibilities of the Invoker event filter feature from OTRS, that can be used to add additional conditions to the event triggers, which are configured for the search invoker. One example could be, that just configuration items of ITSM class Computer gets synchronized to the remote system.

The configuration of the remote system, that gets synchronized does not need to be special but for it needs to provide at least an operation for the search executions and a separate operation for each sync action that needs to be performed.

Ticket Invoker

This feature adds the functionality of the invokers TicketCreate and TicketUpdate for web services.

In addition, the package follows HTTP redirect responses (HTTP code 301, 307 and 308) for outbound communication of HTTP::REST and HTTP::SOAP based web services.

Further the package allows to send empty body HTTP requests (POST, PUT, PATCH) for outbound communication of HTTP::REST based web services.

TicketCreate and TicketUpdate invoker returns the complete ticket and article data based on ticket ID and article ID of the triggered event.

Prepare the invocation of the configured remote web service. Event data:

my $Result = $InvokerObject->PrepareRequest(
    Data => {                                               # data payload
        TicketID => 123,
        ArticleID => 123,                                   # optional
    },
);

Invoker result:

{
    Data => {
        Ticket => {
            Title         => 'some ticket title',
            Queue         => 'some queue name',
            Lock          => 'some lock name',              # optional
            Type          => 'some type name',              # optional
            Service       => 'some service name',           # optional
            SLA           => 'some SLA name',               # optional
            State         => 'some state name',
            Priority      => 'some priority name',
            Owner         => 'some user login',             # optional
            Responsible   => 'some user login',             # optional
            CustomerUser  => 'some customer user login',
            PendingTime {       # optional
                Year   => 2011,
                Month  => 12
                Day    => 03,
                Hour   => 23,
                Minute => 05,
            },
        },
        Article => {
            SenderType       => 'some sender type name',    # optional
            AutoResponseType => 'some auto response type',  # optional
            From             => 'some from string',         # optional
            Subject          => 'some subject',
            Body             => 'some body'
            ContentType      => 'some content type',        # ContentType or MimeType and Charset is required
            MimeType         => 'some mime type',
            Charset          => 'some charset',
            TimeUnit         => 123,                        # optional
        },
        DynamicField => [                                   # optional
            {
                Name   => 'some name',
                Value  => 'Value',                          # value type depends on the dynamic field
            },
            # ...
        ],
         Attachment => [
            {
                Content     => 'content'                    # base64 encoded
                ContentType => 'some content type'
                Filename    => 'some fine name'
            },
            # ...
        ],
    },
};

OTRS as Requester – HTTP::REST

In the case of HTTP::REST, this configuration also grows dynamically depending on the configured invokers. Authentication and SSL options are similar to the ones in HTTP::SOAP.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Endpoint *

URI of the remote system to indicate specific location for accessing a web service.

Timeout *

Timeout value for requests.

Authentication

An optional authentication mechanism to access the remote system. Select an authentication mechanism from the list and additional fields will appear.

Credential *

Select a credential that has been added in the Credentials screen. Click on the Add credential button to open the credential management screen.

Certification Authority (CA) Certificate

The full path and name of the certification authority certificate file that validates SSL certificate.

Certification Authority (CA) Directory

The full path of the certification authority directory where the CA certificates are stored in the file system.

Use Proxy Options *

Show or hide proxy options to connect to the remote system.

Controller mapping for Invoker ‘<InvokerName>’ *

The controller that the invoker should send requests to.

Variables marked by a : will get replaced by the data value and passed along with the request (e.g. /Ticket/:TicketID?UserLogin=:UserLogin&Password=:Password).

Valid request command for Invoker ‘<InvokerName>’

A specific HTTP command to use for the requests with this invoker (optional).

Default command

The default HTTP command to use for the requests. Possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE. If no command is selected, Default command is used.

Additional request headers (all invokers)

Optionally, you may want to define additional request headers for all invokers. These may be used to add static header values to every request. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request headers (invoker specific)

These headers will be set in requests for the selected invoker. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

If at least two invokers are added the requester transport screen for HTTP::REST is extended with two fields.

Controller mapping for Invoker ‘<InvokerName>’ *

In this setting a resource path is set. This path must be defined according to the needs of the remote web service and following its definition.

Path can contain variables in the form of :<VariableName> for each variable name that matches the current data (to be sent), will be replaced by the corresponding data value. This matched variable names and values will be removed from the current data. Depending on the HTTP request command the remaining data could be sent as a JSON string in the request body or as query parameters within the URI.

Examples for data Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four.

• Controller mapping: /Resource, after replacements: /Resource, remaining data: Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four

• Controller mapping: /Resource/:Var1, after replacements: /Resource/One, remaining data: Var2 = Two, Var3 = Three and Var4 = Four

• Controller mapping: /Resource/:Var1?Param1=:Var2&Var3=:Var3, after replacements: /Resource/One?Param1=Two&Var3=Three, remaining data: Var4 = Four

Valid request command for Invoker ‘<InvokerName>’

This determines the HTTP request method to use. Possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE. If no command is selected, Default command is used.

OTRS as Requester – HTTP::SOAP

For the requester HTTP::SOAP network transport there are more fields to be set.

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Endpoint *

URI of the remote system to indicate specific location for accessing a web service.

Timeout *

Timeout value for requests.

Set SOAPAction *

Set to Yes in order to send a filled SOAPAction header. Set to No in order to send an empty SOAPAction header.

SOAPAction scheme *

Select how SOAPAction should be constructed. Some web services require a specific construction.

SOAPAction separator *

Character to use as separator between name space and SOAP operation. Usually .Net web services use / as separator.

Namespace *

URI to give SOAP methods a context, reducing ambiguities.

Request name scheme *

Select how SOAP request function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.

Response name scheme *

Select how SOAP response function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.

Encoding

The character encoding for the SOAP message contents.

Authentication

An optional authentication mechanism to access the remote system. Select an authentication mechanism from the list and additional fields will appear.

Credential *

Select a credential that has been added in the Credentials screen. Click on the Add credential button to open the credential management screen.

Certification Authority (CA) Certificate

The full path and name of the certification authority certificate file that validates SSL certificate.

Certification Authority (CA) Directory

The full path of the certification authority directory where the CA certificates are stored in the file system.

Use Proxy Options *

Show or hide proxy options to connect to the remote system.

Additional request headers (all invokers)

Optionally, you may want to define additional request headers for all invokers. These headers will be set in every request.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request headers (invoker specific)

These headers will be set in requests for the selected invoker. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request SOAP namespaces (all invokers)

These namespaces will be used in every request.

Additional request SOAP namespaces (invoker specific)

These namespaces will be used in requests for this specific invoker.

Sort options

Outbound sort order for XML fields (structure starting below function name wrapper) – see documentation for SOAP transport.

XSLT Mapping

XSLT stylesheet *

Here you can add or modify your XSLT mapping code.

The editing field allows you to use different functions like automatic formatting, window resize as well as tag- and bracket-completion.

Use key attribute

For incoming data this option defines if XML key attributes are converted into a Perl data structure or if they are ignored.

Example: Incoming XML data

<Article>
    <Subject>some subject</Subject>
    <Body>some body</Body>
    <ContentType>text/plain; charset=utf8</ContentType>
    <TimeUnit>1</TimeUnit>
</Article>
<Attachment>
    <Content>someTestData</Content>
    <ContentType>text/plain</ContentType>
    <Filename>test1.txt</Filename>
</Attachment>
<Attachment Content="someTestData" ContentType="text/plain" Filename="test2.txt" />

Resulting Perl data with Use key attribute disabled:

$VAR1 = {
    Article => {
        Body => 'some body',
        ContentType => 'text/plain; charset=utf8',
        Subject => 'some subject',
        TimeUnit => '1',
    },
    Attachment => [
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test1.txt',
        },
        {},
    ],
};

Resulting Perl data with Use key attribute enabled:

$VAR1 = {
    Article => {
        Body => 'some body',
        ContentType => 'text/plain; charset=utf8',
        Subject => 'some subject',
        TimeUnit => '1',
    },
    Attachment => [
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test1.txt',
        },
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test2.txt',
        },
    ],
};

Attribute options

This option must be used in order to use key attributes for outgoing elements. First level options define the elements which should receive key attributes. Second level options define which sub elements should be converted into attributes and attached to the surrounding element. Only two levels of options are considered for key attributes. These will be used for any level of elements in the XML structure (not only the first level).

Please note that sorting of elements in the attribute options is possible but will not affect how key attributes are treated.

If every sub element of an element is converted into attributes and the element contains a specific ContentKey sub element, the content of this sub element will be used as value of the surrounding element. Please see the following example as illustration for these options.

Example: XSLT mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:date="http://exslt.org/dates-and-times" version="1.0" extension-element-prefixes="date">
        <xsl:template match="RootElement">
        <xsl:copy>
            <header>
                <messageID>someMessageID</messageID>
                <Attachment>
                    <ContentKey>text1.txt</ContentKey>
                    <Content>someValue</Content>
                    <ContentType>text/plain</ContentType>
                </Attachment>
                <Attachment>
                    <Filename>text2.txt</Filename>
                    <Content>someValue</Content>
                    <ContentType>text/plain</ContentType>
                </Attachment>
                <Attachment>
                    <ContentKey>text3.txt</ContentKey>
                    <Content>someValue</Content>
                    <ContentDisposition>inline</ContentDisposition>
                    <ContentType>text/plain</ContentType>
                </Attachment>
            </header>
            <ticketID>someTicketID</ticketID>
            <returnCode>0</returnCode>
        </xsl:copy>
    </xsl:template>
</xsl:transform>

Data includes

Select one or more sets of data that were created at earlier request/response stages to be included in mappable data.

These sets will appear in the data structure at /DataInclude/<DataSetName> (see debugger output of actual requests for details).