Outdated documentation

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

Administrator Interface

This package has no administrator interface, but extends the web service with new operations.

See also

In order to use this feature, a new web service has to be configured in the Web Services screen of the administrator interface.

Contents

• Processes & Automation
  • Web Services

The main feature of this package is to extend the OTRS generic interface that enables OTRS to accept requests from external systems to interact with the link object.

Each operation requires a valid agent user login name and a password or a session ID. This session ID can be obtained using the SessionCreate operation from session connector that is available by default in OTRS.

This package includes the following generic interface operations.

Link::LinkAdd

This operation is used to create a link between two objects.

Link::LinkDelete

This operation is used to remove a link between two objects.

Link::LinkDeleteAll

This operation is used to remove all link of an object.

Link::LinkList

This operation shows all links of an object, optionally restricted by another object, link type and link direction.

Link::PossibleLinkList

This operation shows all possible link types between objects that are registered in the OTRS system.

Link::PossibleObjectsList

This operation shows all objects that can be used for linking.

Link::PossibleTypesList

This operation shows all possible link types between two given objects.

Due to the nature of the generic interface and the operations included in this package an external software is needed to send the requests to the OTRS system.

For testing we recommend the use of:

• OTRS Perl SOAP Requester script: some of the variables in this script such as URL, NameSpace and Operation will need to be changed to match the current web service, the operation to be executed and the data to be sent.
• SoapUI by SMARTBEAR: this is an open source software designed to test web services using SOAP messages.

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.

Create New Link

This example will show how to create a link, using the Link::LinkAdd generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <SourceObject>Ticket</SourceObject>
       <SourceKey>1</SourceKey>
       <TargetObject>Ticket</TargetObject>
       <TargetKey>2</TargetKey>
       <Type>Normal</Type>
       <State>Valid</State>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <Success>1</Success>
   </namesp1:RootElementResponse>
   

Remove Link

This example will show how to remove the previously created link, using the Link::LinkDelete generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <Object1>Ticket</Object1>
       <Key1>1</Key1>
       <Object2>Ticket</Object2>
       <Key2>2</Key2>
       <Type>Normal</Type>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <Success>1</Success>
   </namesp1:RootElementResponse>
   

Remove All Links

This example will show how to alternatively remove the previously created link (and all other links of this ticket), using the Link::LinkDeleteAll generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <Object>Ticket</Object>
       <Key>1</Key>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <Success>1</Success>
   </namesp1:RootElementResponse>
   

Show All Links

This example will show all links of an object, using the Link::LinkList generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <Object>Ticket</Object>
       <Key>1</Key>
       <State>Valid</State>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <RootElement>
           <Direction>Source</Direction>
           <Key>2</Key>
           <Object>Ticket</Object>
           <Type>Normal</Type>
       </RootElement>
       <RootElement>
           <Direction>Source</Direction>
           <Key>3</Key>
           <Object>Ticket</Object>
           <Type>ParentChild</Type>
       </RootElement>
       <RootElement>
           <Direction>Target</Direction>
           <Key>4</Key>
           <Object>Ticket</Object>
           <Type>ParentChild</Type>
       </RootElement>
   </namesp1:RootElementResponse>
   

Show All Possible Links

This example will show all possible link types between objects, using the Link::PossibleLinkList generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <RootElement>
           <Object1>Ticket</Object1>
           <Object2>Ticket</Object2>
           <Type>Normal</Type>
       </RootElement>
       <RootElement>
           <Object1>Ticket</Object1>
           <Object2>Ticket</Object2>
           <Type>ParentChild</Type>
       </RootElement>
   </namesp1:RootElementResponse>
   

Show All Possible Objects

This example will show all objects that can be linked to a given object, using the Link::PossibleObjectsList generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <Object>Ticket</Object>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <PossibleObject>Ticket</PossibleObject>
   </namesp1:RootElementResponse>
   

Show All Possible Types

This example will show all link types between two given objects, using the Link::PossibleTypesList generic interface operation.

1. Send the following SOAP request to the OTRS system.

   <RootElement>
       <UserLogin>johnsmith</UserLogin>
       <Password>Secret123</Password>
       <Object1>Ticket</Object1>
       <Object2>Ticket</Object2>
   </RootElement>
   

2. The server response should be something similar to this one.

   <namesp1:RootElementResponse>
       <PossibleType>Normal</PossibleType>
       <PossibleType>ParentChild</PossibleType>
   </namesp1:RootElementResponse>