Web Services | OTRS Academy

Table of Contents

As mentioned in the feature list, a basic knowledge of both OTRS and SolMan web services is assumed.

An example web service is provided with the package in doc/SolManConnectorExample.yml. It might be a good idea to keep this web service installed (but disabled) as a duplicate on your system as a reference.

For necessary and recommended modifications of each web service part see sections below. Modifications refer to the provided example.

Requester Transport

Be sure to use HTTP::SOAPSolMan transport. This is necessary for correct namespace generation.

Set the endpoint (URI) of your SolMan instance and set authentication, proxy and SSL options if necessary.

The SOAPAction options, namespace and name scheme should not be changed.

Requester Invokers

This package includes three different invoker controllers that provide functionality for all supported function calls.

The SolMan::IncidentCreate controller handles initial transfer of a ticket to SolMan (e.g. ProcessIncident, ReplicateIncident).
The SolMan::IncidentUpdate controller handles follow-up transfer of a ticket to SolMan (e.g. AcceptIncidentProcessing, AddInfo, CloseIncident, RejectIncidentSolution, VerifyIncidentSolution).
The SolMan::RequestSystemGuid controller is used to request system GUID information from SolMan.

It is important to differentiate between IncidentCreate and IncidentUpdate controllers. Otherwise the invoker names do not make a difference handling-wise in OTRS (except CloseIncident which will croak if you try to update an already closed ticket).

If an update-type invoker is triggered for a ticket without any previous sync activity, they will automatically trigger a create type invoker (ProcessIncident if it exists or alternatively ReplicateIncident).

The invoker for requesting the SolMan system GUID is triggered automatically whenever this information is not known in OTRS.

Every regular invoker will transfer all existing articles that have not been transferred to this point.

By default, the AddInfo invoker will be triggered for every article created in OTRS via an event trigger. It is highly recommended to configure event triggers for all relevant invokers (e.g. for state and priority changes) and to restrict them via event conditions (e.g. to tickets in specific queues).

Requester Mapping

Mapping between OTRS and SolMan is done in OTRS via XSLT configuration.

The provided configuration contains working XSLT templates. For standard requirements it is only necessary to modify the outbound mapping template in regard to:

OTRS file path for XSL helper templates
OTRS → SolMan state mapping
OTRS → SolMan priority mapping
Dynamic field selection and name mapping
OTRS → SolMan article type mapping

The templates have to be modified individually per invoker but are (by default) identical for all regular invokers.

The data structure provided by the invokers is similar to the structure of the OTRS ticket connector but with some modifications and extra data. This is a quick reference:

<Customer>
    <*> customer attributes, e.g. 'UserEmail' </*>
</Customer>
<Owner>
    <*> owner (agent) attributes, e.g. 'UserEmail' </*>
</Owner>
<SolMan>
    <IncidentId> incident id </IncidentId>
    <IncidentGuid> incident guid </IncidentGuid>
    <LocalSystemGuid> OTRS system guid </LocalSystemGuid>
    <RemoteSystemGuid> SolMan system guid </RemoteSystemGuid>
</SolMan>
<Ticket>
    <Article> # can occur 0-n times
        <Attachment> # can occur 0-n times
            <*> attachment attributes, e.g. 'Filename' </*> # 'Content' is base64-encoded automatically
        </Attachment>
        <DynamicField> # can occur 0-n times
            <Name> dynamic field name </Name>
            <Value> dynamic field value(s) </Value>
        </DynamicField>
        <*> article attributes, e.g. 'From' </*>
    </Article>
    <DynamicField> # can occur 0-n times
        <Name> ticket dynamic field name </Name>
        <Value> ticket dynamic field value(s) </Value>
    </DynamicField>
    <*> ticket attributes, e.g. 'TicketNumber' </*>
</Ticket>

The default XSLT template types are provided as individual files for reference (see doc/ExampleMapping-Invoker-*.xsl provided by the package).

Requester Error Handling

Some error handling modules are pre-configured used to reschedule requests if a specific problem occurs. Rescheduled requests are executed in 1 minute intervals for up to 5 tries.

By defaults all transport errors cause a reschedule as well as data preparation where the SolMan system GUID could not be retrieved.

Also requests are rescheduled if SolMan returns an error code, except if this code is 01, 02, 03 or 04.

It is recommended to change retry options to your needs and to check if the error code specific handling matches your requirements.

Provider Transport

To avoid confusion you should use the HTTP::SOAPSolMan transport. Contrary to the requester this is not strictly necessary.

Modify message length if necessary.

The SOAPAction options, namespace and name scheme should not be changed.

Provider Operations

This package includes three different operation controllers that provide functionality for all supported function calls.

The SolMan::IncidentCreate controller handles initial transfer of a ticket from SolMan (e.g. ProcessIncident, ReplicateIncident).
The SolMan::IncidentUpdate controller handles follow-up transfer of a ticket from SolMan (e.g. AcceptIncidentProcessing, AddInfo, CloseIncident, RejectIncidentSolution, VerifyIncidentSolution).
The SolMan::RequestSystemGuid controller is used to provide system GUID information to SolMan.

It is important to differentiate between IncidentCreate and IncidentUpdate controllers. Otherwise the invoker names do not make a difference handling-wise in OTRS.

If a ticket has pending updates that need to be transferred from OTRS to SolMan (e.g. new articles), update from SolMan are temporarily blocked.

Due to the nature of SolMan, the sent attachments cannot be assigned to more than one article. Articles sent within a request will automatically attached to the last article created within this request. If the request does not contain any article, a dummy article will be created for the attachments.

Provider Mapping

Mapping between OTRS and SolMan is done in OTRS via XSLT configuration.

The provided configuration contains working XSLT templates. For standard requirements it is only necessary to modify the inbound mapping template in regard to:

OTRS file path for XSL helper templates
OTRS target queue
SolMan → OTRS state mapping
SolMan → OTRS priority mapping
Dynamic field selection and name mapping
SolMan → OTRS article type mapping

The templates have to be modified individually per operation but are (by default) identical for all regular operations.

The data structure expected by the operations is similar to the structure of the OTRS ticket connector but with some modifications and extra data. This is a quick reference:

<Attachment> # can occur 0-n times
    <*> attachment attributes, e.g. 'Filename' </*> # 'Content' is base64-decoded automatically
</Attachment>
<Ticket>
    <Article> # can occur 0-n times
        <*> article attributes, e.g. 'From' </*>
    </Article>
    <DynamicField> # can occur 0-n times
        <Name> ticket dynamic field name </Name>
        <Value> ticket dynamic field value(s) </Value>
    </DynamicField>
    <*> ticket attributes, e.g. 'TicketNumber' </*>
</Ticket>
<SolMan>
    <IncidentGuid> incident guid </IncidentGuid>
    <LocalSystemGuid> OTRS system guid </LocalSystemGuid>
    <RemoteSystemGuid> SolMan system guid </RemoteSystemGuid>
    <Person> # can occur 0-n times
        <Meta>
            <ID> OTRS id of agent / or login of customer user </ID>
            <ExternalID> SolMan id of person </ExternalID>
            <Type> CustomerUser, Owner or Agent </Type>
        </Meta>
        <*> agent or customer user attributes, e.g. 'UserEmail' </*>
    </Person>
</SolMan>

The default XSLT template types are provided as individual files for reference (see doc/ExampleMapping-Operation-*.xsl provided by the package).

Facebook X LinkedIn