Web Service Configuration

Configuration Details
General
Debugger
Provider
Operation
Requester
Invoker

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 test operation
      MappingInbound: {}
      MappingOutbound: {}
      RemoteSystemGuid: ''
      Type: Test::Test
    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.