Outdated documentation

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

Web服务

在联网的世界中，工单系统需要能够对来自其他系统的请求作出反应，并向其他系统发送请求或信息：

  • CRM系统
  • 项目管理系统
  • 文档管理系统
  • 还有更多

工单系统必须可以通过其他服务到达，而无需服务人员的人工干预。

OTRS通过 通用接口 支持此需求。它允许管理员在不了解脚本语言的情况下为特定任务创建Web服务。OTRS对传入的REST或SOAP请求作出反应，并创建对象或透明地向其他系统提供对象数据。

Web服务是两个系统之间的通信方法，在我们的例子中是OTRS和远程系统。在其配置中，操作 或 调用程序 确定通信方向，映射 和 传输 负责接收和解释数据的方式。

在其配置中，可以定义Web服务可以在内部执行哪些动作（操作）、OTRS请求可以执行远程系统哪些操作（调用程序）、数据如何从一个系统转换到另一个系统（映射）以及通信将在哪个协议上进行（传输）。

通用接口是一种框架，可以使用已经构建的构建块以预定义的方式为OTRS创建Web服务，这些构建块彼此独立且可互换。

Generic Interface

The generic interface consists of a multiple layer framework that lets OTRS communicate with other systems via a web service. This communication could be bi-directional:

  • OTRS as provider: OTRS acts as a server listening to requests from the external system, processing the information, performing the requested action, and answering the request.
  • OTRS as requester: OTRS acts as a client collecting information, sending the request to the remote system, and waiting for the response.

Generic Interface Layers

The generic interface is build based on a layer model, to be flexible and easy to customize.

A layer is a set of files, which control how the generic interface performs different parts of a web service. Using the right configuration, one can build different web services for different external systems without creating new modules.

注解

If the remote system does not support the current bundled modules of the generic interface, special modules need to be developed for that specific web service.

Generic Interface Layers

Generic Interface Layers

Network Transport

This layer is responsible for the correct communication with the remote system. It receives requests and generates responses when acting as provider, and generates requests and receives responses when acting as requester.

Requester communication could be initiated during an event triggered by a generic interface module or any other OTRS module. This event is caught by the event handler and depending on the configuration the event will be processed directly by the requester object or delegated to the scheduler (a separated daemon designed to process tasks asynchronously).

Data Mapping

This layer is responsible for translating data structures between OTRS and the remote system (data internal and data external layers). Usually remote systems have different data structures than OTRS (including different values and names for those values), and here resides the importance of the layer to change the received information into something that OTRS can understand and on the opposite way send the information to each remote system using their data dictionaries.

Example: Priority (OTRS) might be called Prio in a remote system and it could be that value 1 very low (OTRS) should be mapped to Information in the remote system.

Controller

Controllers are collections of similar operations or invokers. For example, a ticket controller might contain several standard ticket operations. Custom controllers can be implemented, for example a TicketExternalCompany controller which may contain similar functions as the standard ticket controller, but with a different data interface, or function names (to adapt to the remote system function names) or complete different code.

One application for generic interface could be to synchronize information with one remote system that only can talk with another remote system of the same kind. In this case new controllers needs to be developed and the operations and invokers has to emulate the remote system behavior in such way that the interface that OTRS exposes is similar to the interface of the remote system.

Operation (OTRS as a provider)

An operation is a single action that can be performed within OTRS. All operations have the same programming interface, they receive the data into one specific parameter, and return a data structure with a success status, potential error message and returning data.

Normally operations uses the already mapped data (internal) to call core modules and perform actions in OTRS like: create a ticket, update a user, invalidate a queue, send a notification, etc. An operation has full access to the OTRS API to perform the action.

Invoker (OTRS as a requester)
An invoker is an action that OTRS performs against a remote system. Invokers use the OTRS core modules to process and collect the needed information to create the request. When the information is ready it has to be mapped to the remote system format in order to be sent to the remote system, that will process the information, execute the action and send the response back, to either process the success or handle errors.

Generic Interface Communication Flow

The generic interface has a defined flow to perform actions as a provider and as a requester. These flows are described below:

OTRS as Provider

Remote Request:

  1. HTTP request
    • OTRS receives HTTP request and passes it through the layers.
    • The provider module is in charge to execute and control these actions.
  2. 网络传输
    • The network transport module decodes the data payload and separates the operation name from the rest of the data.
    • The operation name and the operation data are returned to the provider.
  3. Data external
    • Data as sent from the remote system (this is not a module based layer).
  4. 映射
    • The data is transformed from the external system format to the OTRS internal format as specified in the mapping configuration for this operation (mapping for incoming request data).
    • The already transformed data is returned to the provider.
  5. Data internal
    • Data as transformed and prepared to be passed to the operation (This is not a module based layer).
  6. 操作
    • Receives and validates data.
    • Performs user access control.
    • Executes the action.

OTRS Response:

  1. 操作
    • Returns result data to the provider.
  2. Data internal
    • Data as returned from operation.
  3. 映射
    • The data is transformed back to the remote system format as specified in the mapping configuration (mapping for outgoing response data).
    • The already transformed data is returned to the provider.
  4. Data external
    • Data as transformed and prepared to be passed to network transport as response.
  5. 网络传输
    • Receives the data already in the remote system format.
    • Constructs a valid response for this network transport type.
  6. HTTP response
    • The response is sent back to the web service client.
    • In the case of an error, an error response is sent to the remote system (e.g. SOAP fault, HTTP error, etc).

OTRS as Requester

OTRS Request:

  1. Event trigger handler

    • Based on the web service configuration determines if the request will be synchronous or asynchronous.

      • Synchronous

        • A direct call to the requester is made in order to create a new request and to pass it through the layers.

      • Asynchronous

        • Create a new generic interface (requester) task for the OTRS daemon (by delegating the request execution to the scheduler daemon, the user experience could be highly improved, otherwise all the time needed to prepare the request and the remote execution will be added to the OTRS events that trigger those requests).
        • In its next cycle the OTRS daemon process reads the new task and creates a call to the requester that will create a new request and then passes it through the layers.

  2. 调用程序

    • Receives data from the event.
    • Validates received data (if needed).
    • Call core modules to complement the data (if needed).
    • Return the request data structure or send a stop communication signal to the requester, to gracefully cancel the request.

  3. Data internal

    • Data as passed from the invoker (this is not a module based layer).

  4. 映射

    • The data is transformed to the remote system format as specified in the mapping configuration (mapping for outgoing response data).
    • The already transformed data is returned to the requester.

  5. Data external

    • Data as transformed and prepared for sending to the remote system.

  6. 网络传输

    • Receives the remote operation name and the data already transformed to the remote system format from the requester.
    • Constructs a valid request for the network transport.
    • Sends the request to the remote system and waits for the response.

Remote Response:

  1. 网络传输
    • Receives the response and decodes the data payload.
    • Returns the data to the requester.
  2. Data external
    • Data as received from the remote system.
  3. 映射
    • The data is transformed from the external system format to the OTRS internal format as specified in the mapping configuration for this operation (mapping for incoming response data).
    • The already transformed data is returned to the requester.
  4. Data internal
    • Data as transformed and ready to be passed back to the requester.
  5. 调用程序
    • Receives return data.
    • Handles the data as needed specifically by each invoker (included error handling if any).
    • Return the Invoker result and data to the Requester.
  6. Event handler or OTRS daemon
    • Receives the data from the requester. In the case of the OTRS daemon this data might contain information to create a task in the future.

管理Web服务

A web service is a communication method between two systems, in our case OTRS and a remote system.

The heart of the web service is its configuration, where it is defined what actions the web service can perform internally (operation), what actions the OTRS request can perform remote system (invokers), how data is converted from one system to the other (mapping), and over which protocol the communication will take place (transport).

通用接口是一种框架，可以使用已经构建的构建块以预定义的方式为OTRS创建Web服务，这些构建块彼此独立且可互换。

使用此屏幕可管理系统中的Web服务。默认情况下，新的OTRS安装不包含Web服务。Web服务管理屏幕位于 流程和自动化 组的 Web服务 模块中。

Web Service Management Screen

Web服务管理屏幕

若要创建一个Web服务：

  1. 点击左侧边栏中的 添加Web服务 按钮。
  2. 填写必填字段。
  3. 点击 保存 按钮。
Create New Web Service Screen

创建新的Web服务屏幕

若要编辑一个Web服务：

  1. 点击Web服务列表中的一个Web服务。
  2. 修改字段。
  3. 点击 保存 或 保存并完成 按钮。
Edit Web Service Screen

编辑Web服务屏幕

若要删除一个Web服务：

  1. 点击Web服务列表中的一个Web服务。
  2. 点击左侧边栏中的 删除Web服务 按钮。
  3. 点击确认对话框中的 删除 按钮。
Delete Web Service Screen

删除Web服务屏幕

若要克隆一个Web服务：

  1. 点击Web服务列表中的一个Web服务。
  2. 点击左侧边栏中的 克隆Web服务 按钮。
  3. 为这个Web服务输入一个新的名称。
Clone Web Service Screen

克隆Web服务屏幕

若要导出一个Web服务：

  1. 点击Web服务列表中的一个Web服务。
  2. 点击左侧边栏中的 导出Web服务 按钮。
  3. 在计算机中选择一个位置以保存 Export_ACL.yml 文件。

警告

所有存储在WEB服务配置中的密码都将以纯文本格式导出。

若要查看一个Web服务的配置历史：

  1. 点击Web服务列表中的一个Web服务。
  2. 点击左侧边栏中的 配置历史 按钮。
Web Service Configuration History Screen

Web服务的配置历史屏幕

若要为一个Web服务使用调试器：

  1. 点击Web服务列表中的一个Web服务。
  2. 点击左侧边栏中的 调试器 按钮。
Web Service Debugger Screen

Web服务调试器屏幕

若要导入一个Web服务：

  1. 点击左侧边栏中的 添加Web服务 按钮。
  2. 点击左侧边栏中的 导入Web服务 按钮。
  3. 点击对话框中的 浏览… 按钮。
  4. 选择一个先前导出的 .yml 文件。
  5. 为导入的Web服务添加名称（可选）。否则，该名称将取自配置文件名。
  6. 点击 导入 按钮。

Web服务设置

The web service configuration needs to be saved on each level. This means that if a setting is changed, links to other, deeper parts of the configuration will be disabled forcing you to save the current configuration level. After saving the disabled links will be re-enabled again allowing you to continue with the configuration.

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

Web服务通用设置

Web Service Settings - General

Web服务设置 - 通用

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

名称 *
此资源的名称。 可以在此字段中输入任何类型的字符，包括大写字母和空格。 名称将显示在概览表中。
描述
类似于注释，但可以在此处添加较长的文本。
远程系统
This field can be used to add a description for the remote system.
调试阀值

默认值是 debug。当以这种方式配置时，所有通信日志都在数据库中注册。每个后续的调试阈值都比系统中设置的更严格，并且丢弃的通信日志的顺序更低。

调试阀值级别（从低到高）：

  • 调试
  • Info（信息）
  • Notice（注意）
  • 错误
有效性
设置此资源的有效性。 如果此字段设置为 有效，则每个资源即可仅在OTRS中使用。 将此字段设置为 无效 或 临时无效 将禁止此资源的使用。

提供程序Web服务设置

Web Service Settings - OTRS as Provider

Web服务设置 - OTRS作为提供程序

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

网络传输

选择要与Web服务一起使用的网络传输。可能的值是 HTTP::REST 和 HTTP::SOAP。

注解

选择传输方法后，您必须单击 保存 按钮保存配置。一个 配置 按钮将显示在此字段旁边。

配置
The Configure button is visible only, after a network transport was selected and saved. See the configuration for OTRS as Provider - HTTP::REST and OTRS as Provider - HTTP::SOAP below.
添加操作

只有在选择并保存网络传输之后，此选项才可见。选择一个操作将打开一个新的配置屏幕。

Web Service Settings - OTRS as Provider - Operation

Web服务设置 - OTRS作为提供程序 - 操作

OTRS作为提供程序 - HTTP::REST

The configuration might be a bit more complicated, as it grows dynamically for each configured operation by adding route mapping for each operation and valid request methods for each operation to the default transport settings.

Web Service Settings - OTRS as Provider - HTTP\:\:REST

Web服务设置 - OTRS作为提供程序 - HTTP::REST

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

Route mapping for Operation ‘<OperationName>’ *

Define the route that should get mapped to this operation. Variables marked by a : will get mapped to the entered name and passed along with the others to the mapping (e.g. /Ticket/:TicketID).

In this setting a resource path is set. This path must be defined according to the needs of the web service considering that the path in conjunction with the HTTP request method determines the generic interface operation to be executed.

Path can contain variables in the form of :<VariableName>. Each path string that fits on the position of the variable name will be added to the request payload using the variable name defined in this setting. Examples:

Valid requests for /Resource route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One

Invalid requests for /Resource route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource?Param1=One

Valid requests for /Resource/:ID route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1?Param1=One

In both cases ID = 1 will be sent to the operation as part of the payload. In the second case also Param1 = One will be added, depending on the HTTP request method other parameters will be added if they come as a JSON string in the request header.

Invalid requests for /Resource/:ID route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One

Valid requests for /Resource/OtherResource/:ID/:Color route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1/Red
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherReosurce/123/Blue?Param1=One

In the first example ID = 1 and Color = Red, while in the second ID = 123 and Color = Blue.

Invalid requests for /Resource/OtherResource/:ID/:Color route mapping:

https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1
https://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1?Param1=One

In the first example the part of the path /OtherResource is missing as well as the :Color variable. In the second example just the :Color variable is missing.

Valid request methods for Operation ‘<OperationName>’

Limit this operation to specific request methods. If no method is selected all requests will be accepted.

The HTTP request methods to determine the operation to use together with the route mapping, possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE.

Totally different operations can share exactly the same mapping path, but the request method must be unique for each operation, in order to determine correctly the operation to use on each request.

Maximum message length *
Specifies the maximum size (in bytes) for REST messages that OTRS will process.
Send Keep-Alive *
This configuration defines if incoming connections should get closed or kept alive.
Additional response headers (all operations)

Optionally, you may want to define additional response headers for all operations. These may be used to add static header values to every response. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response headers (operation specific)

These headers will be set in responses for the selected operation. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

OTRS作为提供程序 - HTTP::SOAP

It is quite simple to configure the HTTP::SOAP protocol as provider.

Web Service Settings - OTRS as Provider - HTTP\:\:SOAP

Web服务设置 - OTRS作为提供程序 - HTTP::SOAP

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

Check SOAPAction *
Set to Yes in order to check the received SOAPAction header (if not empty). Set to No in order to ignore the received SOAPAction header.
SOAPAction scheme *
Select how SOAPAction should be constructed. Some web services send a specific construction.
SOAPAction separator *
Character to use as separator between name space and SOAP operation. Usually .Net web services use / as separator.
Namespace *
URI to give SOAP methods a context, reducing ambiguities.
Request name scheme *
Select how SOAP request function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.
Response name scheme *
Select how SOAP response function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.
Maximum message length *
Specifies the maximum size (in bytes) for SOAP messages that OTRS will process.
Additional response headers (all operations)

Optionally, you may want to define additional response headers for all operations. These may be used to add static header values to every response. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response headers (operation specific)

These headers will be set in responses for the selected operation. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional response SOAP namespaces (all operations)
These namespaces will be used in every response.
Additional response SOAP namespaces (operation specific)
These namespaces will be used in responses for this specific operation.

注解

Some headers are blocked for safety purposes. If needed, the list of blocked headers can be changed in the following system configuration using the settings:

  • GenericInterface::Invoker::OutboundHeaderBlacklist
  • GenericInterface::Operation::OutboundHeaderBlacklist
Sort options
Outbound sort order for XML fields (structure starting below function name wrapper) - see documentation for SOAP transport.

Web Service Operation

The actions that can be performed when you are using OTRS as a provider are called operations. Each operation belongs to a controller. Controllers are collections of operations or invokers, normally operations from the same controller need similar settings and share the same configuration dialog. But each operation can have independent configuration dialogs if needed.

Add Web Service Operation Screen

Add Web Service Operation Screen

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

名称 *
此资源的名称。 可以在此字段中输入任何类型的字符，包括大写字母和空格。 名称将显示在概览表中。
描述
Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the description will be also displayed in the overview table.
Operation backend

This OTRS operation back end module will be called internally to process the request, generating data for the response.

The operation back end is pre-populated and cannot be edited. You will see this parameter when you choose the operation on the web service edit screen. The field is only informative.

Mapping for incoming request data
The request data will be processed by this mapping, to transform it to the kind of data OTRS expects.
Mapping for outgoing response data
The response data will be processed by this mapping, to transform it to the kind of data the remote system expects.
Include Ticket Data
Whether to include ticket data in response or not.

Mappings are fields that normally appear on every operation, but other special fields can appear in non default configuration dialogs to fulfill specific needs of the operation.

Normally there are two mapping configuration sections for each operation, one for the incoming data and another one for the outgoing data. You can choose different mapping types (back ends) for each mapping direction, since their configuration is independent from each other and also independent from the operation back end. The normal and most common practice is that the operation uses the same mapping type in both cases (with inverted configuration). The complete mapping configuration is done in a separate screen which depends on the mapping type.

In the left part of the screen on the action column you have the options to go back to web service (discarding all changes since the last save) and delete. If you click on the last one, a dialog will open and ask you if you like to remove the operation. Click on the Delete button to confirm the removal of the operation and its configuration or click on the Cancel button to close the delete dialog.

请求者Web服务设置

The network transport configuration for the requester is similar to the configuration for the provider.

Web Service Settings - OTRS as Requester

Web服务设置 - OTRS作为请求者

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

网络传输

选择要与Web服务一起使用的网络传输。可能的值是 HTTP::REST 和 HTTP::SOAP。

注解

选择传输方法后，您必须单击 保存 按钮保存配置。一个 配置 按钮将显示在此字段旁边。

配置

The Configure button is visible only, after a network transport was selected and saved. See the configuration for OTRS as Requester - HTTP::REST and OTRS as Requester - HTTP::SOAP below.

It is possible to use both object and array format as a JSON response of the remote system. However, in the case it is an array, system stores it as an object internally, where ArrayData is used as a key and a value is an array. Because of that, responded JSON array can be mapped efficiently, but has to be considered as an object described above (key is ArrayData, but * can also be used as wildcard).

添加错误处理模块

This option is visible only, after a network transport was selected and saved. Selecting an error handling module will open a new screen for its configuration.

Web Service Settings - OTRS as Provider - Error Handling Module

Web服务设置 - OTRS作为请求者 - 错误处理模块

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

名称 *
此资源的名称。 可以在此字段中输入任何类型的字符，包括大写字母和空格。 名称将显示在概览表中。
描述
Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the description will be also displayed in the overview table.
Invoker filter
Only execute error handling module for selected invokers.
Error message content filter

Enter a regular expression to restrict which error messages should cause error handling module execution. Error message subject and data (as seen in the debugger error entry) will be considered for a match.

Example: Enter ^.*401 Unauthorized.*$ to handle only authentication related errors.

Error stage filter

Only execute error handling module on errors that occur during specific processing stages.

Example: Handle only errors where mapping for outgoing data could not be applied.

Error code
An error identifier for this error handling module. This identifier will be available in XSLT mapping and shown in debugger output.
Error message
An error explanation for this error handling module. This message will be available in XSLT mapping and shown in debugger output.
匹配后停止
Defines if processing should be stopped after module was executed, skipping all remaining modules or only those of the same back end. Default behavior is to resume, processing the next module.

OTRS作为请求者 - HTTP::REST

In the case of HTTP::REST, this configuration also grows dynamically depending on the configured invokers. Authentication and SSL options are similar to the ones in HTTP::SOAP.

Web Service Settings - OTRS as Requester - HTTP\:\:REST

Web服务设置 - OTRS作为请求者 - HTTP::REST

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

Endpoint *
URI of the remote system to indicate specific location for accessing a web service.
Timeout *
Timeout value for requests.
Authentication
An optional authentication mechanism to access the remote system. Select an authentication mechanism from the list and additional fields will appear.
Credential *
Select a credential that has been added in the Credentials screen. Click on the Add credential button to open the credential management screen.
Certification Authority (CA) Certificate
The full path and name of the certification authority certificate file that validates SSL certificate.
Certification Authority (CA) Directory
The full path of the certification authority directory where the CA certificates are stored in the file system.
Use Proxy Options *
Show or hide proxy options to connect to the remote system.
Controller mapping for Invoker ‘<InvokerName>’ *

The controller that the invoker should send requests to.

Variables marked by a : will get replaced by the data value and passed along with the request (e.g. /Ticket/:TicketID?UserLogin=:UserLogin&Password=:Password).

Valid request command for Invoker ‘<InvokerName>’
A specific HTTP command to use for the requests with this invoker (optional).
Default command
The default HTTP command to use for the requests. Possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE. If no command is selected, Default command is used.
Additional request headers (all invokers)

Optionally, you may want to define additional request headers for all invokers. These may be used to add static header values to every request. Just click on the Add header button and fill both header and value fields. There is no limit in number of additional header lines.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request headers (invoker specific)

These headers will be set in requests for the selected invoker. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

注解

Some headers are blocked for safety purposes. If needed, the list of blocked headers can be changed in the following system configuration using the settings:

  • GenericInterface::Invoker::OutboundHeaderBlacklist
  • GenericInterface::Operation::OutboundHeaderBlacklist

OTRS作为请求者 - HTTP::SOAP

For the requester HTTP::SOAP network transport there are more fields to be set.

Web Service Settings - OTRS as Requester - HTTP\:\:SOAP

Web服务设置 - OTRS作为请求者 -HTTP::SOAP

添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。

Endpoint *
URI of the remote system to indicate specific location for accessing a web service.
Timeout *
Timeout value for requests.
Set SOAPAction *
Set to Yes in order to send a filled SOAPAction header. Set to No in order to send an empty SOAPAction header.
SOAPAction scheme *
Select how SOAPAction should be constructed. Some web services require a specific construction.
SOAPAction separator *
Character to use as separator between name space and SOAP operation. Usually .Net web services use / as separator.
Namespace *
URI to give SOAP methods a context, reducing ambiguities.
Request name scheme *
Select how SOAP request function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.
Response name scheme *
Select how SOAP response function wrapper should be constructed. FunctionName is used as example for actual invoker or operation name. FreeText is used as example for actual configured value.
Encoding
The character encoding for the SOAP message contents.
Authentication
An optional authentication mechanism to access the remote system. Select an authentication mechanism from the list and additional fields will appear.
Credential *
Select a credential that has been added in the Credentials screen. Click on the Add credential button to open the credential management screen.
Certification Authority (CA) Certificate
The full path and name of the certification authority certificate file that validates SSL certificate.
Certification Authority (CA) Directory
The full path of the certification authority directory where the CA certificates are stored in the file system.
Use Proxy Options *
Show or hide proxy options to connect to the remote system.
Additional request headers (all invokers)

Optionally, you may want to define additional request headers for all invokers. These headers will be set in every request.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request headers (invoker specific)

These headers will be set in requests for the selected invoker. The purpose of this setting is the same as above.

Header value variables marked by a : will get replaced by the corresponding data value (e.g. :TicketID becomes 1).

Additional request SOAP namespaces (all invokers)
These namespaces will be used in every request.
Additional request SOAP namespaces (invoker specific)
These namespaces will be used in requests for this specific invoker.

注解

Some headers are blocked for safety purposes. If needed, the list of blocked headers can be changed in the following system configuration using the settings:

  • GenericInterface::Invoker::OutboundHeaderBlacklist
  • GenericInterface::Operation::OutboundHeaderBlacklist
Sort options
Outbound sort order for XML fields (structure starting below function name wrapper) - see documentation for SOAP transport.

Web Service Mapping

There are cases where you need to transform the data from one format to another (map or change data structure), because normally a web service is used to interact with a remote system, that is highly probable that is not another OTRS system and/or could not understand the OTRS data structures and values. In these cases some or all values have to be changed, and sometimes even the names of the values (keys) or even the complete structure, in order to match with the expected data on the other end. To accomplish this task the generic interface mapping layer exists.

Simple Web Service Mapping

Simple Web Service Mapping

Each remote system has it own data structures and it is possible to create new mapping modules for each case (e.g. there is a customized mapping module for SAP Solution Manager available as feature add-on), but it is not always necessary. The module Mapping::Simple should cover most of the mapping needs.

注解

When the Mapping::Simple does not cover all mapping needs for a web service, a new mapping module should be created.

This module gives you the opportunity to set default values to map for each key or value for the whole communication data.

At the beginning of the screen you will see a general section where you can set the default rules that will apply for all the unmapped keys and values. There are three options available, these options are listed below:

Keep (leave unchanged)
It does not touch the keys or values in any way.
Ignore (drop key/value pair)
When this is applied to the key it deletes the key and value, because when a key is deleted then in consequence its associated value is deleted too. When this is applied to the value, only the value is deleted, keeping the key, that now will be associated to an empty value.
Map to (use provided value as default)
All keys and/or values without a defined map rule will use this as default. When you select this option a new text field will appear to set this default.

Clicking on the plus button for new key map will display a new box for a single mapping configuration. You can add as many key mappings as needed. Just click on the plus button again and a new mapping box will appear below the existing one. From this mapping boxes you can define a map for a single key, with the next options:

Exact value(s)
The old key string will be changed to a new one if the old key matches exactly.
Regular expression
The key string will be replaced following a regular expression rule.

Pressing the new value map plus button will display a new row for a value map. Here it is also possible to define rules for each value to be mapped with the same options as for the key map (exact value and regular expression). You can add as many values to map as needed, and if you want to delete one of them, just click on the minus button for each mapping value row.

Deleting the complete key mapping section (box) is possible, just push on the minus button located on the up right corner of each box that you want to delete.

If you need to delete a complete mapping configuration, go back to the corresponding operation or invoker screen, look for the mapping direction that you select before and set its value to -, and save the configuration to apply the changes.

It is possible to define XSLT templates for mapping.

XSLT Web Service Incoming Mapping

XSLT Web Service Incoming Mapping

XSLT Mapping

XSLT stylesheet *

Here you can add or modify your XSLT mapping code.

The editing field allows you to use different functions like automatic formatting, window resize as well as tag- and bracket-completion.

Use key attribute

For incoming data this option defines if XML key attributes are converted into a Perl data structure or if they are ignored.

Example: Incoming XML data

<Article>
    <Subject>some subject</Subject>
    <Body>some body</Body>
    <ContentType>text/plain; charset=utf8</ContentType>
    <TimeUnit>1</TimeUnit>
</Article>
<Attachment>
    <Content>someTestData</Content>
    <ContentType>text/plain</ContentType>
    <Filename>test1.txt</Filename>
</Attachment>
<Attachment Content="someTestData" ContentType="text/plain" Filename="test2.txt" />

Resulting Perl data with Use key attribute disabled:

$VAR1 = {
    Article => {
        Body => 'some body',
        ContentType => 'text/plain; charset=utf8',
        Subject => 'some subject',
        TimeUnit => '1',
    },
    Attachment => [
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test1.txt',
        },
        {},
    ],
};

Resulting Perl data with Use key attribute enabled:

$VAR1 = {
    Article => {
        Body => 'some body',
        ContentType => 'text/plain; charset=utf8',
        Subject => 'some subject',
        TimeUnit => '1',
    },
    Attachment => [
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test1.txt',
        },
        {
            Content => 'someTestData',
            ContentType => 'text/plain',
            Filename => 'test2.txt',
        },
    ],
};
Attribute options

This option must be used in order to use key attributes for outgoing elements. First level options define the elements which should receive key attributes. Second level options define which sub elements should be converted into attributes and attached to the surrounding element. Only two levels of options are considered for key attributes. These will be used for any level of elements in the XML structure (not only the first level).

Please note that sorting of elements in the attribute options is possible but will not affect how key attributes are treated.

If every sub element of an element is converted into attributes and the element contains a specific ContentKey sub element, the content of this sub element will be used as value of the surrounding element. Please see the following example as illustration for these options.

XSLT Web Service Outgoing Mapping

XSLT Web Service Outgoing Mapping

Example: XSLT mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:date="http://exslt.org/dates-and-times" version="1.0" extension-element-prefixes="date">
        <xsl:template match="RootElement">
        <xsl:copy>
            <header>
                <messageID>someMessageID</messageID>
                <Attachment>
                    <ContentKey>text1.txt</ContentKey>
                    <Content>someValue</Content>
                    <ContentType>text/plain</ContentType>
                </Attachment>
                <Attachment>
                    <Filename>text2.txt</Filename>
                    <Content>someValue</Content>
                    <ContentType>text/plain</ContentType>
                </Attachment>
                <Attachment>
                    <ContentKey>text3.txt</ContentKey>
                    <Content>someValue</Content>
                    <ContentDisposition>inline</ContentDisposition>
                    <ContentType>text/plain</ContentType>
                </Attachment>
            </header>
            <ticketID>someTicketID</ticketID>
            <returnCode>0</returnCode>
        </xsl:copy>
    </xsl:template>
</xsl:transform>
Data includes

Select one or more sets of data that were created at earlier request/response stages to be included in mappable data.

These sets will appear in the data structure at /DataInclude/<DataSetName> (see debugger output of actual requests for details).