Web Service Configuration

Web Service Configuration
Prev	Chapter 20. Generic Interface	Next

From its design the web services were conceived to be portable from one OTRS system to another, e.g. from a test or development environment to a production system. Therefore it was needed to have an easy way to extract the web service configuration from the database, and import it to another. To accomplish this task Generic Interface uses YAML files as the web services configuration basis.

Why YAML? YAML is a markup language designed to be human friendly to read and write (it is easier to understand than JSON), it does not have some of the limitations of XML like numeric tags, it is open, standardized, and is complete enough to store the whole web service configuration.

Note

To learn more about YAML please visit http://www.yaml.org/.

The following is a web service configuration file example in YAML format:

---
Debugger:
  DebugThreshold: debug
Description: This an example of a web service configuration
Provider:
  Operation:
    CloseIncident:
      Description: This is a SolMan test operation
      MappingInbound: {}
      MappingOutbound: {}
      RemoteSystemGuid: ''
      Type: SolMan::CloseIncident
    Test:
      Description: This is a test operation
      MappingInbound:
        Config:
          KeyMapDefault:
            MapTo: ''
            MapType: Keep
          KeyMapExact:
            Prio: Priority
          ValueMap:
            Priority:
              ValueMapExact:
                Critical: 5 Very High
                Information: 1 Very Low
                Warning: 3 Normal
          ValueMapDefault:
            MapTo: 3 Normal
            MapType: MapTo
        Type: Simple
      MappingOutbound:
        Config:
          KeyMapDefault:
            MapTo: ''
            MapType: Ignore
          KeyMapExact:
            Priority: Prio
          ValueMap:
            Prio:
              ValueMapExact:
                1 Very Low: Information
                3 Normal: Warning
                5 Very High: Critical
          ValueMapDefault:
            MapTo: ''
            MapType: Ignore
        Type: Simple
      Type: Test::Test
  Transport:
    Config:
      MaxLength: 10000000
      NameSpace: http://www.example.com/actions
    Type: HTTP::SOAP
RemoteSystem: remote.system.description.example.com
Requester:
  Invoker:
    Test:
      Description: This is a test invoker
      Events:
        - Asynchronous: 1
          Event: TicketCreate
        - Asynchronous: 0
          Event: ArticleUpdate
      MappingInbound:
        Type: Simple
      MappingOutbound:
        Type: Simple
      Type: Test::Test
  Transport:
    Config:
      Authentication:
        Password: '*******'
        Type: BasicAuth
        User: otrs
      Encoding: utf-8
      Endpoint: http://www.example.com:8080/endpoint
      NameSpace: http://www.example.com/actions
      SOAPAction: Yes
      SOAPActionSeparator: '#'
    Type: HTTP::SOAP

Configuration Details

General

Description: a short text that describes the web service.
RemoteSystem: a short description of the Remote System.
Debugger: a container for the debugger settings.
Provider: a container for the provider settings.
Requester: a container for the requester settings.

Debugger

DebugThreshold: the debugger level
Possible Values
- debug: all logs are stored in the database.
- info: info, notice and error level logs are stored in the database.
- notice: notice and error level logs are stored in the database.
- error: only error level logs are stored in the database.

Provider

Operation: a container for each operation settings.
Transport: a container for provider network transport settings.

Operation

<OperationName>: Unique name for the operation, container for its own operation settings (cardinality 0..n, but not duplicate).

<OperationName>

This section is based on operations from type "Test::Test" other operations might contain more or different settings.

Description: a short text that describes the operation.
MappingInbound: a container for the mapping settings for the incoming request data.
MappingOutbound: a container for the mapping settings for the outgoing response data.
Type: the operation backend, in Controller::Operation format.

MappingInbound

This section is based on mappings from type "Simple". Other mappings might contain more or different settings.

Config: a container for this mapping settings.
Type: the mapping backend.

Config

KeyMapDefault: a container for all non mapped keys settings.
ValueMapDefault: a container for all non mapped values settings.
KeyMapExact: a container for all exact key mappings (cardinality 0 .. 1).
KeyMapRegEx: a container for all regular expression key mappings (cardinality 0 .. 1).
ValueMap: a container for all value mappings (cardinality 0 .. 1).

KeyMapDefault

MapTo: the new value to be used (only applicable if MapType is set to MapTo).
MapType: the rule for the mapping.
Possible Values
- Keep: leave unchanged.
- Ignore: drop.
- MapTo: change to the MapTo value.

ValueMapDefault

Similar to KeyMapDefault.

KeyMapExact

<oldkey>: <newkey> (cardinality 0 .. n but not duplicate).

KeyMapRegEx

<oldkey(RegEx)>: <newkey> ( cardinality 0 .. n but no duplicates).

ValueMap

<newkey>: a container for value mappings for this new key (cardinality depends on the new keys from KeyMapExact and KeyMapRegEx).

<newkey>

ValueMapExact: a container for all exact value mappings (cardinality 0 .. 1).
ValueMapRegEx: a container for all regular expression value mappings (cardinality 0 .. 1).

valueMapExact

<oldvalue>: <newvalue> ( cardinality 0 .. n but not duplicate).

ValueMapRegEx

<oldvalue(RegEx)>: <newvalue> ( cardinality 0 .. n but not duplicate).

MappingOutbound

Same as MappingInbound.

Transport

This section is based on the provider network transport HTTP::SOAP, other transports might contain more or different settings.

Config: a container for the specific network transport configuration settings.
Type: the provider network transport backend.

Config

MaxLength: the maximum length in bytes to be read in a SOAP message by OTRS.
NameSpace: an URI that gives a context to all operations that belongs to this web service.

Requester

Invoker: a container for each invokers' settings.
Transport: a container for requester network transport settings.

Invoker

<InvokerName>: Unique name for the invoker, container for its own invoker settings (cardinality 0..n, but not duplicate).

<InvokerName>

This section is based on invokers from type "Test::Test" other invokers might contain more or different settings.

Description: a short text that describes the invoker
Events: a container for a unnamed list of event trigger settings.
MappingInbound: a container for the mapping settings for the incoming response data.
MappingOutbound: a container for the mapping settings for the outgoing request data.
Type: the invoker backend, in Controller::Invoker format.

Events

List Element: (cardinality 0 .. n)
- Asynchronous: to set if the invoker execution will be delegated to the Scheduler
  Possible Values
  - 0: not handled by the Scheduler.
  - 1: handled by the Scheduler.
- Event: the name of the event trigger.
  Possible Values (for ticket events)
  - TicketCreate
  - TicketDelete
  - TicketTitleUpdate
  - TicketUnlockTimeoutUpdate
  - TicketQueueUpdate
  - TicketTypeUpdate
  - TicketServiceUpdate
  - TicketSLAUpdate
  - TicketCustomerUpdate
  - TicketFreeTextUpdate
  - TicketFreeTimeUpdate
  - TicketPendingTimeUpdate
  - TicketLockUpdate
  - TicketArchiveFlagUpdate
  - TicketStateUpdate
  - TicketOwnerUpdate
  - TicketResponsibleUpdate
  - TicketPriorityUpdate
  - HistoryAdd
  - HistoryDelete
  - TicketAccountTime
  - TicketMerge
  - TicketSubscribe
  - TicketUnsubscribe
  - TicketFlagSet
  - TicketFlagDelete
  - TicketSlaveLinkAdd
  - TicketSlaveLinkDelete
  - TicketMasterLinkDelete
  Possible Values (for article events)
  - Article Events
  - ArticleCreate
  - ArticleFreeTextUpdate
  - ArticleUpdate
  - ArticleSend
  - ArticleBounce
  - ArticleAgentNotification
  - ArticleCustomerNotification
  - ArticleAutoResponse
  - ArticleFlagSet
  - ArticleFlagDelete
  - ArticleAgentNotification
  - ArticleCustomerNotification

MappingInbound

Same as Operation MappingInbound

MappingOutbound

Same as Operation MappingInbound.

Transport

This section is based on the requester network transport HTTP::SOAP, other transports might contain more or different settings.

Config: a container for the specific network transport configuration settings.
Type: the requester network transport backend.

Config

Authentication: a container for authentication settings.
Encoding: the SOAP Message request encoding
Endpoint: the URI of the Remote Server web service to accept OTRS requests
NameSpace: an URI that gives a context to all invokers that belongs to this web service.
SOAPAction: to send an empty or filled SOAPAction header in the SOAP Message (in "<NameSpace> <Separator> <Action>" format).
Possible Values
- YES: to send a filled SOAPAction header.
- No: to send an empty SOAPAction header.
SOAPActionSeparator: to set the <Separator> of a filled SOAPAction header.
Possible Values
- '/': used for .net web services.
- '#': used for all the rest web services.

Authentication

User: the privileged user name that has access to the remote web service.
Password: the password for privileged user in plain text.
Type: the type of authentication.