SAP Solution Manager Connector

Table of Contents

This feature includes extension modules for the generic interface that provides two-way communication and ticket synchronization between OTRS and SAP Solution Manager (from now on referred to as SolMan in this document).

Note

SAP Solution Manager (reachable via local or remote network) is required for this feature.

OTRS implements generic interface invokers, operations and transports that are very specific to interact with a SolMan server. The modules are disabled by their registration in the system configuration to prevent confusions or wrong usage.

This is the list of settings that has to be enabled if you want to start using it.

GenericInterface::Transport::Module###HTTP::SOAPSolMan
GenericInterface::Operation::Module###SolMan::IncidentCreate
GenericInterface::Operation::Module###SolMan::IncidentUpdate
GenericInterface::Operation::Module###SolMan::RequestSystemGuid
GenericInterface::Invoker::Module###SolMan::IncidentCreate
GenericInterface::Invoker::Module###SolMan::IncidentUpdate
GenericInterface::Invoker::Module###SolMan::RequestSystemGuid

If the SAP Solution Manager Connector feature was installed as separate package, the system will keep the settings enabled during version upgrade.

Bidirectional Communication

The modules used by this feature provide communication between OTRS and a SAP Solution Manager system, however it is necessary to first setup both systems independently in order make sure that both systems work correctly and then execute all the necessary steps in the SolMan system to request and provide actions trough a non-SAP web service.

With this feature (and the necessary customized configuration) OTRS will be able to communicate with an existing SolMan by pretending to be another SolMan system, using the same function names, data structures and value types.

OTRS does not implement the full set of SolMan API. Please refer to the SolMan Web Services chapter below to check which ones are available in OTRS.

Prior to any attempt to creating an OTRS web service with this modules is necessary to know how SolMan handle concepts like priorities, states (SAPUserStatus), article types (TextTypes), etc. and the values for this concepts in the used instance of SolMan system, as well as in OTRS.

OTRS and the SolMan system should be able to communicate over the network to send and receive SOAP messages between them. Please be sure to open the necessary ports on both servers and any network device between them (like a switch or firewall).

In order to use this feature and the contained modules is necessary to create or modify a web service within OTRS. Please refer to the SolMan Web Services chapter below for more information.

Automatic Creation of Customer Users and Agents in OTRS

Tickets exchanged between OTRS and SolMan also transfer ticket owner and customer user.

If an incoming ticket creation/update contains data of an unknown agent, a new agent will be automatically created in OTRS. The same behavior exists similarly for customer users.

Multiple SolMan Instances

It is possible to connect to multiple SolMan instances from within the same OTRS system. Just use one web service per instance.

The system GUID of each system is stored separately and so is the ticket synchronization state.

SolMan Web Services

As mentioned above, a basic knowledge of both OTRS and SolMan web services is assumed.

An example web service is provided in development/webservices/SolManConnectorSOAP.yaml folder. It might be a good idea to keep this web services 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

There are 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 development/webservices/SolManConnectorSOAP/ExampleMapping-Invoker-*.xsl).

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

There are 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 development/webservices/SolManConnectorSOAP/ExampleMapping-Operation-*.xsl).

Facebook X LinkedIn