Web服务¶
The actions that can be performed when you are using OTRS as a requester are called invokers. Each invoker belongs to a controller (controllers are collections of operations or invokers). Usually invokers from the same controller need similar settings and share the same configuration dialogs. Each invoker can have independent configuration dialogs if needed.
安装本软件包之后，调用程序 部分将提供两个新的调用程序。从下拉列表中选择调用程序将打开一个新的设置窗口。
请求示例¶
TicketCreate 和 TicketUpdate 调用程序根据触发事件的工单ID和信件ID返回完整的工单和信件数据。
准备调用已配置的远程web服务。事件数据：
my $Result = $InvokerObject->PrepareRequest(
Data => { # data payload
TicketID => 123,
ArticleID => 123, # optional
},
);
调用程序结果：
{
Data => {
Ticket => {
Title => 'some ticket title',
Queue => 'some queue name',
Lock => 'some lock name', # optional
Type => 'some type name', # optional
Service => 'some service name', # optional
SLA => 'some SLA name', # optional
State => 'some state name',
Priority => 'some priority name',
Owner => 'some user login', # optional
Responsible => 'some user login', # optional
CustomerUser => 'some customer user login',
PendingTime { # optional
Year => 2011,
Month => 12
Day => 03,
Hour => 23,
Minute => 05,
},
},
Article => {
SenderType => 'some sender type name', # optional
AutoResponseType => 'some auto response type', # optional
From => 'some from string', # optional
Subject => 'some subject',
Body => 'some body'
ContentType => 'some content type', # ContentType or MimeType and Charset is required
MimeType => 'some mime type',
Charset => 'some charset',
TimeUnit => 123, # optional
},
DynamicField => [ # optional
{
Name => 'some name',
Value => 'Value', # value type depends on the dynamic field
},
# ...
],
Attachment => [
{
Content => 'content' # base64 encoded
ContentType => 'some content type'
Filename => 'some fine name'
},
# ...
],
},
};
注解
如果没有给定信件ID，调用程序将返回工单的最新信件。
注解
调用程序不会返回具有未定义值的动态字段，因为同名操作 TicketCreate 和 TicketUpdate 不处理具有未定义值的动态字段。
传出数据的高级过滤器¶
对于传出数据，可以定义请求应包含的工单字段、信件字段或动态字段的类型。此外，还可以按信件类型和信件发件人类型进行筛选。
可以在每个调用程序配置中选择不同的过滤器选项，并在 传出请求数据设置 部分中列出。
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 invoker. Click on the Delete button to confirm the removal of the invoker and its configuration or click on the Cancel button to close the delete dialog.
Add Web Service Invoker Screen
添加或编辑此资源时，可以使用以下设置。 标有星号的字段是必填字段。
通用调用程序数据¶
- 名称 *
- 此资源的名称。 可以在此字段中输入任何类型的字符，包括大写字母和空格。 名称将显示在概览表中。
- 描述
- 向此资源添加其它信息。 为了更清晰，建议始终将此字段填充为带有完整句子的资源描述，因为注释也将显示在概览表中。
- 调用程序后端
- 将调用此调用程序后端模块来准备要发送到远程系统的数据，并处理其响应数据。该字段是只读的，它是在前一个屏幕中选定的。
传出请求数据设置¶
- 工单字段
- 包含可用工单属性（字段）的多选菜单，可提交给远程系统。只有选定的字段将包含在传出请求中。
- 信件字段
- 包含可提交到远程系统的可用信件属性（字段）的多选菜单。只有选定的字段将包含在传出请求中。
- 工单动态字段
- 包含可用工单动态字段的多选菜单，可提交给远程系统。只有所选的动态字段将包含在传出请求中。
- 信件动态字段
- 包含可提交到远程系统的可用信件动态字段的多选菜单。只有所选的动态字段将包含在传出请求中。
- 信件数
- 文本字段，包含在传出请求期间发送的最大信件数。信件将从最新（最近）到最旧进行选择。如果没有给定编号，只会发送最新的信件。
- 通信渠道
- 传出请求数据将只考虑所选通信渠道的信件。如果留空，将使用所有通信渠道创建的信件。
- 客户可见度
- 传出请求数据将只考虑使用所选客户可见性创建的信件。
- 发件人类型
- 传出请求数据将只考虑由选定的发件人类型创建的信件。如果保留为空，则将使用所有发件人类型创建的信件。
映射¶
Normally there are two mapping configuration sections for each invoker, 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 invoker back end. The normal and most common practice is that the invoker 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.
- 映射出站请求数据
- 调用程序的数据将通过此映射进行处理，以将其转换为远程系统所期望的数据类型。
- 映射入站请求数据
- 响应数据将通过此映射进行处理，以将其转换为调用程序期望的数据类型。
传入响应数据的设置¶
可以将传入响应的某些数据自动保存到本地动态字段。可以在每个调用程序配置中选择不同的过滤器选项。
- 远程工单ID动态字段
- 包含系统中可用工单动态字段的下拉菜单。如果选择了这样的动态字段，则将使用从远程系统接收的工单ID，并将其保存在所选的动态字段中。
- 工单动态字段
- 包含系统中可用工单动态字段的多选菜单。所有选定的动态字段（在响应数据中也可用并包含值）都将保存到本地动态字段中。
响应数据的动态字段值将从以下数据结构中使用：
<Ticket>
<DynamicField>..</DynamicField>
</Ticket>
和/或
<Ticket>
<Article>
<DynamicField>..</DynamicField>
</Article>
</Ticket>
添加了系统配置选项 GenericInterface::Invoker::Settings::ResponseDynamicField，作为应包含相关响应数据的结果工单ID的动态字段的备用。如果配置不是通过调用程序GUI添加的，则应使用它，并且两个配置不应同时使用！
事件触发器¶
Event triggers are events within OTRS such as TicketCreate, ArticleSend, etc. These can act as triggers to execute the invoker. Each invoker needs to have at least one event trigger registered, or the invoker will be useless, because it will never be called. Additionally a set of rules (conditions) for each event can be defined to have more control over the triggering of the events. These rules depend on the data of the object associated with the event. The asynchronous property of the event triggers define if the OTRS process will handle the invoker or if it will be delegated to the OTRS daemon.
注解
The OTRS daemon is a separate set of process that executes tasks in the background. Using this the OTRS process itself will not be affected if the remote system takes a long time to respond, if it is not available or if there are network problems. If you do not use the OTRS daemon using web services can make OTRS slow or non-responsive. Therefore it is highly recommend to use asynchronous event triggers as often as possible.
In order to access this section you have to save the current invoker by clicking on the Save button.
- 事件
- 配置事件将触发这个调用程序。
- 添加事件触发器
- To add a new event select the event object and event name and click on the plus button. Asynchronous event triggers are handled by the OTRS daemon in background (recommended). Synchronous event triggers would be processed directly during the web request.
To add an event trigger:
- Select the event family from the first list.
- Select the event name from the second list.
- Set the asynchronous property. If unchecked means that the event trigger will not be asynchronous.
- Click on the plus button. A new event trigger will be created and it will be listed on the invoker event triggers list.
From the event triggers list each events shows if it contains conditions or not. The edit button next to the condition property allows to add or edit the current conditions of the event.
To delete an event trigger, simply locate the event trigger to be deleted in the event triggers list and click on the trash icon at the end of the row. This will open a dialog that asks you if you are sure to delete the event trigger. Click on the Delete button to remove the event trigger from the list, or click on the Cancel button to close the dialog.
Sometimes defining an event to trigger an invoker could result in many unnecessary or wrong request to a remote server. Event conditions could be set to restrict the triggering of the invoker in such cases.
Add Web Service Invoker Event Screen
To access the event settings screen where the conditions can be defined is necessary to be in the invoker screen and from there click on the edit icon next to the condition status on the event where this condition should take effect.
Within the event settings screen in the action bar there is a button to go back to the invoker screen as well as a button to remove all the event conditions. By default the screen is pre-populated with the first condition. Update the type of linking between conditions if more than one condition is planned, then change the type of linking from Condition 1 if more than one field is planned. Both linking fields accept and, or or xor as values.
Fill the field name, set the matching type (String for exact match, Regexp for regular expression or Validation Module) and set the value to match (in case of validation module the full class name like Kernel::GenericInterface::Event::Validation::ValidateDemo).
To add more fields to the condition, click on the plus button in the fields header. To remove a field, click on the minus button in the field row. It is necessary to keep at least one field per condition.
To add more conditions click on the button below the last condition box. To remove a condition, click on the minus button in the condition header. It is necessary to keep at least one condition in the set. To remove all conditions use the button in the sidebar.
OTRS as Requester - HTTP::REST¶
If at least two invokers are added the requester transport screen for HTTP::REST is extended with two fields.
- Controller mapping for Invoker ‘<InvokerName>’ *
In this setting a resource path is set. This path must be defined according to the needs of the remote web service and following its definition.
Path can contain variables in the form of
:<VariableName>for each variable name that matches the current data (to be sent), will be replaced by the corresponding data value. This matched variable names and values will be removed from the current data. Depending on the HTTP request command the remaining data could be sent as a JSON string in the request body or as query parameters within the URI.Examples for data Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four.
- Controller mapping:
/Resource, after replacements:/Resource, remaining data: Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four - Controller mapping:
/Resource/:Var1, after replacements:/Resource/One, remaining data: Var2 = Two, Var3 = Three and Var4 = Four - Controller mapping:
/Resource/:Var1?Param1=:Var2&Var3=:Var3, after replacements:/Resource/One?Param1=Two&Var3=Three, remaining data: Var4 = Four
- Controller mapping:
- Valid request command for Invoker ‘<InvokerName>’
- This determines the HTTP request method to use. Possible options: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT and TRACE. If no command is selected, Default command is used.