Outdated documentation

You are looking at the documentation for an older release. For the latest information, please see current release documentation.

Web Services¶

The actions that can be performed when you are using OTRS as a requester are called invokers. Each invoker belongs to a controller (controllers are collections of operations or invokers). Usually invokers from the same controller need similar settings and share the same configuration dialogs. Each invoker can have independent configuration dialogs if needed.

After installation of the package, two new invokers will be available in the Invokers section. Selecting an invoker from the drop-down list will open a new settings window.

Request Example¶

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'
            },
            # ...
        ],
    },
};

Note

The invoker will return the newest article of the ticket if no article ID is given.

Note

The invoker will not return dynamic fields with undefined values, because the same named operations TicketCreate and TicketUpdate does not handle dynamic fields with undefined values.

Advanced Filtering for Outgoing Data¶

For outgoing data, it is possible to define what kind of ticket fields, article fields or dynamic fields the request should contain. Furthermore it is possible to filter by article type and article sender type.

The different filter options can be selected within every single invoker configuration and are listed in section Settings for outgoing request data.

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 invoker. Click on the Delete button to confirm the removal of the invoker and its configuration or click on the Cancel button to close the delete dialog.

Add Web Service Invoker Screen

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

General Invoker Data¶

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 comment will be also displayed in the overview table.
Invoker backend: This invoker back end module will be called to prepare the data to be sent to the remote system, and to process its response data. The field is read-only, it was selected in the previous screen.

Settings for Outgoing Request Data¶

Ticket fields: A multi-select menu containing the available ticket attributes (fields), that can be submitted to a remote system. Just the fields that are selected will be included in outgoing requests.
Article fields: A multi-select menu containing the available article attributes (fields), that can be submitted to a remote system. Just the fields that are selected will be included in outgoing requests.
Ticket dynamic fields: A multi-select menu containing the available ticket dynamic fields, that can be submitted to a remote system. Just the dynamic fields that are selected will be included in outgoing requests.
Article dynamic fields: A multi-select menu containing the available article dynamic fields, that can be submitted to a remote system. Just the dynamic fields that are selected will be included in outgoing requests.
Number of articles: A text field containing the maximum number of articles, that will be transmitted during an outgoing request. The articles will be selected from newest (latest) to oldest. If no number is given, just the latest article will be transmitted.
Communication channels: The outgoing request data will only consider articles of the selected communication channels. If left empty, articles created by all communication channels will be used.
Customer visibility: The outgoing request data will only consider articles created with the selected customer visibility.
Sender Types: The outgoing request data will only consider articles created by the selected sender types. If left empty, articles created by all sender types will be used.

Mapping¶

Normally there are two mapping configuration sections for each invoker, 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 invoker back end. The normal and most common practice is that the invoker 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.

Mapping for outgoing request data: The data from the invoker will be processed by this mapping, to transform it to the kind of data the remote system expects.
Mapping for incoming response data: The response data will be processed by this mapping, to transform it to the kind of data the invoker expects.

Settings for Incoming Response Data¶

It is possible to automatically save certain data of incoming responses to local dynamic fields. The different filter options can be selected within every single invoker configuration.

Remote Ticket ID dynamic field: A drop-down menu containing the available ticket dynamic fields in the system. If such a dynamic field is selected, the received ticket ID from the remote system will be used, to be saved within the selected dynamic field.
Ticket dynamic fields: A multi-select menu containing the available ticket dynamic fields in the system. All selected dynamic fields, that also available in the response data and containing values, will be saved to the local dynamic fields.

The dynamic field values of the response data will be used from the following data structure:

<Ticket>
    <DynamicField>..</DynamicField>
</Ticket>

and/or

<Ticket>
    <Article>
        <DynamicField>..</DynamicField>
    </Article>
</Ticket>

The system configuration option GenericInterface::Invoker::Settings::ResponseDynamicField was added as a fallback for the dynamic fields that should contain the result ticket ID of the related response data. It shall be used, if the configuration was not added via the invoker GUI and both configurations should not be used at the same time!

Event Triggers¶

Event triggers are events within OTRS such as TicketCreate, ArticleSend, etc. These can act as triggers to execute the invoker. Each invoker needs to have at least one event trigger registered, or the invoker will be useless, because it will never be called. Additionally a set of rules (conditions) for each event can be defined to have more control over the triggering of the events. These rules depend on the data of the object associated with the event. The asynchronous property of the event triggers define if the OTRS process will handle the invoker or if it will be delegated to the OTRS daemon.

Note

The OTRS daemon is a separate set of process that executes tasks in the background. Using this the OTRS process itself will not be affected if the remote system takes a long time to respond, if it is not available or if there are network problems. If you do not use the OTRS daemon using web services can make OTRS slow or non-responsive. Therefore it is highly recommend to use asynchronous event triggers as often as possible.

In order to access this section you have to save the current invoker by clicking on the Save button.

Event: 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 plus button. Asynchronous event triggers are handled by the OTRS daemon in background (recommended). Synchronous event triggers would be processed directly during the web request.

To add an event trigger:

Select the event family from the first list.
Select the event name from the second list.
Set the asynchronous property. If unchecked means that the event trigger will not be asynchronous.
Click on the plus button. A new event trigger will be created and it will be listed on the invoker event triggers list.

From the event triggers list each events shows if it contains conditions or not. The edit button next to the condition property allows to add or edit the current conditions of the event.

To delete an event trigger, simply locate the event trigger to be deleted in the event triggers list and click on the trash icon at the end of the row. This will open a dialog that asks you if you are sure to delete the event trigger. Click on the Delete button to remove the event trigger from the list, or click on the Cancel button to close the dialog.

Sometimes defining an event to trigger an invoker could result in many unnecessary or wrong request to a remote server. Event conditions could be set to restrict the triggering of the invoker in such cases.

Add Web Service Invoker Event Screen

To access the event settings screen where the conditions can be defined is necessary to be in the invoker screen and from there click on the edit icon next to the condition status on the event where this condition should take effect.

Within the event settings screen in the action bar there is a button to go back to the invoker screen as well as a button to remove all the event conditions. By default the screen is pre-populated with the first condition. Update the type of linking between conditions if more than one condition is planned, then change the type of linking from Condition 1 if more than one field is planned. Both linking fields accept and, or or xor as values.

Fill the field name, set the matching type (String for exact match, Regexp for regular expression or Validation Module) and set the value to match (in case of validation module the full class name like Kernel::GenericInterface::Event::Validation::ValidateDemo).

To add more fields to the condition, click on the plus button in the fields header. To remove a field, click on the minus button in the field row. It is necessary to keep at least one field per condition.

To add more conditions click on the button below the last condition box. To remove a condition, click on the minus button in the condition header. It is necessary to keep at least one condition in the set. To remove all conditions use the button in the sidebar.

OTRS as Requester - HTTP::REST¶

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.