Link Object Connector | OTRS Academy

Table of Contents

OTRS can accept requests from external systems to interact with the link object. The functionality needs to be configured in the Web Services module of the administrator interface. There are example configurations for both SOAP and REST methods.

To import the web service configuration:

Go to the Web Service Management screen in the administrator interface.
Click on the Add Web Service button in the left sidebar.
Click on the Import Web Service button in the left sidebar.
Select the file development/webservices/GenericLinkConnectorSOAP.yml or development/webservices/GenericLinkConnectorREST.yml within the OTRS home folder.
Click on the Import button.

These files contain the complete information to setup the web service. The web service can be customized after the import process, if needed. The result of this process will be the same as the manual procedure explained below, but with some useful comments are added to the operations. The imported web services are ready and able to handle all operations.

It is possible to setup the configuration manually, if you would not like to use the builtin configuration examples.

Note

The following steps are needed only, when the web services were not imported as explained above.

The following steps are required to provide a full working configuration:

Go to the Web Service Management screen in the administrator interface.
Click on the Add Web Service button in the left sidebar.
Fill the form with the following data:
- Name: LinkObjectConnector
- Debug threshold: Debug
- Network transport: HTTP::SOAP
Click on the Save button to enable the Add Operation selection and the Configure button for network transport.
Click on the network transport Configure button to show the transport options.
Use the following parameters:
- Namespace: https://otrs.org/LinkObjectConnector/
- Maximum message length: 100000
Click on the Save button. Wait until the page refreshes and then click on the Go back to web service button to continue.

The Add Operation selection provides seven operations for link:

Link::LinkAdd
Link::LinkDelete
Link::LinkDeleteAll
Link::LinkList
Link::PossibleLinkList
Link::PossibleObjectsLst
Link::PossibleTypesList

Add the Link::LinkAdd operation and set the name LinkAdd in the next screen. It does not need any further configuration.
Click on the Save button. Wait until the page refreshes and then click on the Go back to web service button to continue.
Repeat step 9 and step 10 for the other six Link:: operations.
After adding all operations, click on the Save and Finish button from the Edit Web Service: LinkObjectConnector screen.

Now you are on the Web Service Management overview screen and the new web service is ready and able to handle all operations.

Note

When the new web service is fully tested, the debug threshold could be changed to Notice. This will reduce the amount of data that will be kept in the database and only notice and error messages will be logged.

Usage

The link object feature provides functionality to link items (e.g. tickets, changes) from objects (e.g. Ticket, ITSMChangeManagement) in order to provide a logical connection.

To make easier to read and understand these requests here are some SOAP request templates showing the parameters for each operation.

`Link::LinkAdd` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <SourceObject>?</SourceObject>
    <SourceKey>?</SourceKey>
    <TargetObject>?</TargetObject>
    <TargetKey>?</TargetKey>
    <Type>?</Type>
    <State>?</State>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SourceObject: Object where the link originates.
SourceKey: ID of the originating object.
TargetObject: Object where the link points to.
TargetKey: ID of the target object.
Type: Type of the link.
State: State of the link, usually Valid.

`Link::LinkDelete` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <Object1>?</Object1>
    <Key1>?</Key1>
    <Object2>?</Object2>
    <Key2>?</Key2>
    <Type>?</Type>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
Object1: Object where the link originates.
Key1: ID of the originating object.
Object2: Object where the link points to.
Key2: ID of the target object.
Type: Type of the link.

`Link::LinkDeleteAll` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <Object>?</Object>
    <Key>?</Key>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
Object: Object where the links originate.
Key: ID of the originating object.

`Link::LinkList` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <Object>?</Object>
    <Key>?</Key>
    <Object2>?</Object2>
    <State>?</State>
    <Type>?</Type>
    <Direction>?</Direction>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
Object: Object where the links originate.
Key: ID of the originating object.
Object2: Optional restriction of the object where the links point to.
State: State of the links, usually Valid.
Type: Optional restriction of the link type.
Direction: Optional restriction of the link direction (Source or Target).

`Link::PossibleLinkList` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.

`Link::PossibleObjectsList` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <Object>?</Object>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
Object: Object where the links originate.

`Link::PossibleTypesList` Request Template

<RootElement>
    <UserLogin>?</UserLogin>
    <Password>?</Password>
    <SessionID>?</SessionID>
    <Object1>?</Object1>
    <Object2>?</Object2>
</RootElement>

UserLogin and Password: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
SessionID: Used for authentication. This is optional, but either a user login with a password or a session ID have to be provided.
Object1: Object where the link originates.
Object2: Object where the link points to.

Examples

The following examples use all objects and types that are available in OTRS using the default configuration. If you have changed the link default configurations, the examples might have to be modified.