OTRS通用接口包含一个多层框架,让OTRS能够通过一个WEB服务与其它系统通讯,这个通讯可以是双向的:
OTRS作为提供者:OTRS作为一个服务器运行,监听来自外部系统的请求、处理信息、执行请求的操作并答复请求。
OTRS作为请求者:OTRS作为一个客户端运行,收集信息、发送请求到远程系统并等待答复。
通用接口是基于层构建的模型,使用灵活且易于定制。
层是一个文件的集合,控制通用接口如何执行一个WEB服务的不同部分。使用正确的配置,你可以给不同的外部系统构建不同的WEB服务,而不用创建新的模块。
如果远程系统不支持目前通用接口捆绑的模块,需要为那个特定的WEB服务开发特殊的模块。
OTRS自带的通用接口模块随着时间流逝会更新和增长。
本层负责与远程系统的正确通讯。它在OTRS作为提供者时接收请求并生成响应,在OTRS作为请求者时生成请求并接收响应。
提供者通讯由一个新的WEB服务处理程序“nph-genericinterface.pl”处理。
请求者通讯可以在一个通用接口模块或其它任何OTRS模块触发事件过程中初始化。这个事件由事件处理程序捕获,取决于配置,这个事件由请求者对象直接处理或委派给计划程序(一个单独的守护进程,设计来异步处理任务)处理。
本层负责在OTRS和远程系统之间转化数据结构(内部数据和外部数据层)。通常远程系统拥有与OTRS不同的数据结构(包括不同的值和这些值的名称),这就是本层的重要性:将收到的信息转为OTRS能够理解的东西,在相反的方向上将这些信息使用远程系统的数据字典发送给每个远程系统。
示例:OTRS中的“Priority(优先级)”在远程系统中可能叫做“Prio”,它的值“1-低”(OTRS)应当映射为远程系统中的“Information”。
控制器是相似的操作或调用程序的合集。例如,一个工单控制器可能包含数个标准工单操作。可以定制控制器,例如,一个“TicketExternalCompany”控制器可能包含与标准工单控制器相似的功能,但有不同的数据接口或函数名称(适应远程系统的函数名称)或完全不同的代码。
一个通用接口应用可以与一个远程系统同步信息,只可以跟另一个相同类型的远程系统。在这种情况下,需要开发新的控制器,并且操作和调用程序必须模拟远程系统行为,这样OTRS暴露的接口就类似于远程系统的接口。
操作是一个能在OTRS内执行的单个动作。所有的操作有相同的编程接口,它们接收数据到一个指定的参数,并返回一个数据结构,包含成功状态、潜在的错误消息和返回数据。
通常操作使用已经映射的数据(内部)来调用核心模块并执行OTRS中的动作如:创建一个工单、更新一个用户、使一个队列无效、发送一个通知等等。一个操作有OTRS API的全部权限以执行这个动作。
通用接口有定义的流程来执行作为提供者和请求者的操作
这些流程描述如下:
HTTP请求
OTRS接收到HTTP请求并传递它。
提供者模块负责执行和控制这些操作。
网络传输
网络传输模块解码数据有效载荷并从剩余数据中分离操作的名称。
操作名称和操作数据都返回给提供者。
外部数据
从远程系统发来的数据(这不是一个基于模块的层)。
映射
按这个操作指定的映射配置(进入的请求数据映射)将数据从外部系统格式转化为OTRS内部格式。
已转化的数据返回给提供者。
内部数据
数据已经转化并准备传递到操作(这不是一个基于模块的层)。
操作
接收并验证数据。
执行用户访问控制。
执行操作。
事件触发器处理程序
基于WEB服务配置确定请求是同步还是异步。
同步
直接调用请求者以便创建一个新的请求,并通过这个层传递。
异步
为OTRS守护进程创建一个新的通用接口(请求者)任务,通过委派该请求执行到计划程序进程,大大改善了用户体验。否则准备该请求和远程执行需要的所有时间都会加到触发这些请求的OTRS事件上。
在下一个循环中OTRS守护进程读取新任务并创建一个到请求者的调用,请求者会创建一个新的请求并通过这个层传递它。
调用程序
接收来自事件的数据。
验证收到的数据(如果需要)。
调用核心模块来补足数据(如果需要)。
返回请求数据结构,或发送一个中止通讯信号给请求者以取消这个请求。
内部数据
自请求者传来的数据(这不是一个基于模块的层)。
映射
按映射配置(出站响应数据的映射)指定的格式将数据转化为远程系统的格式。
已经转化的数据返回给请求者。
外部数据
转化后的数据准备发送给远程系统。
网络传输
从请求者接收远程操作名称和已经转化为远程系统格式的数据
为网络传输构建一个有效的请求
将请求发送给远程系统并等待响应。
一个WEB服务是两个系统(在我们的例子中,就是OTRS和一个远程系统)间进行通讯的方法。
WEB服务的核心是它的配置,在配置中定义了WEB服务能够在内部执行什么操作(Operation操作)、OTRS请求能够在远程系统执行什么操作(Invokers调用程序),数据如何从一个系统转换到另外的系统(Mapping映射)以及通过什么协议进行通讯 (Transport传输)
通用接口是一个框架,使得在OTRS中能够用预定义的方法、使用已经构建的相互独立且可互换的块来创建WEB服务。
WEB服务图形界面是一个工具,允许你在用户友好、便捷的界面构建复杂的WEB服务配置。它允许:
创建和删除WEB服务。
导入和导出已有WEB服务的配置(用YAML文件格式)。
在WEB服务历史窗口查看、还原和导出已有WEB服务的老配置。
在调试窗口跟踪每个WEB服务所有的通讯日志。
在系统管理页面系统管理员部分的“WEB服务”链接通向WEB服务概览窗口,你可以管理WEB服务的配置。在这个窗口你可以添加新的WEB服务或修改已有WEB服务的配置。
每个WEB服务配置窗口的上部分有一行‘面包条’风格的导航路径,通过这个导航路径可以知道我们在WEB服务配置中的准确位置,还可以让用户随时跳回到配置流程的任何位置(这个跳回操作不会保存任何修改内容)。
要创建一个新的WEB服务,点击“添加WEB服务”按钮,并输入需要的信息。
这部分必填的字段只有WEB服务的“名称”,要求系统唯一且不得留空。其它字段也是配置需要的如“调试阈值”和“有效性”,但是这些字段已经有默认值了。
“调试阈值”的默认值是“调试”,当配置为这个方式时所有的通讯日志都会记录到数据库中。每个随后的调试阈值都有更多的限制并会丢弃比当前阈值级别低的通讯日志。
调试阈值级别(从低到高)
Debug(调试)
Info(信息)
Notice(注意)
Error(错误)
还可以为“OTRS作为服务提供方”和“OTRS作为服务请求方”定义网络传输协议。
点击“保存”按钮来将新的WEB服务注册到数据库中,或点击“取消”按钮丢弃这个操作。现在可以返回到WEB服务概览窗口。
如果你已经有一个YAML格式的WEB服务配置文件,你可以点击窗口左侧的“导入WEB服务”按钮。导入WEB服务的更多信息请检查下一部分的“修改WEB服务”。
要为一个WEB服务添加或修改更多细节,点击WEB服务概览窗口中WEB服务的名称。
在 OTRS Business Solution™中有可用的示例Web服务,你知道吗?
在这个窗口你有处理一个WEB服务所有部分的完整功能集。在左侧的操作栏中你可以找到一些按钮,允许你在一个WEB服务上执行所有可能的操作。
克隆WEB服务。
导出WEB服务。
导入WEB服务。
配置历史。
删除WEB服务
调试器
“配置历史”和“调试器”会打开不同的窗口。
要克隆一个WEB服务,你需要点击“克隆WEB服务”按钮。在打开的对话框中你可以为这个克隆的WEB服务使用默认的名称或设置一个新名称。
记住:WEB服务的名称必须是系统中唯一的。
点击“克隆”按钮来创建这个WEB服务的克隆或“取消”按钮关闭这个对话框。
“导出WEB服务”按钮让你转储当前WEB服务配件到一个YAML文件,下载并保存到你的文件系统中。这在你要从一个服务器迁移WEB服务到另外的服务器时特别有用,例如从测试环境到生产系统。
所有存储在WEB服务配置中的密码都将以纯文本格式导出。
在点击“导出WEB服务”按钮后,你的浏览器会出现一个保存文件对话框,就像你在网页上点击了一个文件下载链接一样的。
不同操作系统中不同浏览器有它自己的保存对话框窗口和风格。取决于浏览器和它的配置,可能不会显示对话框而是直接将文件保存到一个默认目录中。如有需要请检查你的浏览器文档以获取更多的特定说明。
导入WEB服务功能必须使用一个有效的WEB服务配置的YAML文件。点击“导入WEB服务”按钮,浏览配置文件或在输入框中输入文件的完整路径。
点击“导入”按钮以从一个文件创建一个新的WEB服务或“取消”关闭这个对话框。
WEB服务的名称会使用配置文件的文件名(例如文件是MyWebservice.yml,则WEB服务将命名为MyWebservice)。如果在系统中已经有一个与之同名的WEB服务,系统会打开修改WEB服务窗口,让你修改导入的WEB服务的名称。
对WEB服务配置所做的每个修改都会在WEB服务历史中创建一条新条目(就像一个日志)。WEB服务历史窗口显示一个WEB服务配置所有版本的列表。在“配置历史列表”中的每一行(版本)代表WEB服务历史中一个单独的修订。
点击一行可以显示在特定日期/时间的整个配置,这个配置会显示在本窗口的“历史详细信息”部分。你还可以在这里导出选定的WEB服务配置版本或者恢复这个版本到当前的WEB服务配置。
“导出WEB服务配置”与修改WEB服务窗口中的“导出WEB服务”功能完全一样。更多信息请参考那部分内容。
如果对当前WEB服务配置的修改没有按预期工作,可以手动轻易恢复修改内容到原状,你可以点击“恢复WEB服务配置”按钮。这会打开一个对话框问你是否确定恢复到这个WEB服务配置。点击对话框中的“恢复WEB服务配置”按钮用选定版本替换当前的配置,或点击“取消”直接关闭对话框。
记住:存储在WEB服务配置中的任何密码都将以纯文本格式导出。
恢复一个配置时请一定小心,因为这个过程是不可逆的。
有时需要完全删除一个WEB服务,如要这样做你可以点击“删除WEB服务按钮”,会弹出一个确认对话框。
点击“删除”按钮来确认删除这个WEB服务或点击“取消”关闭对话框。
删除一个WEB服务后无法撤销,请在删除一个WEB服务时一定要小心。
调试器存储了一个WEB服务的日志。在调试器窗口你可以跟踪该WEB服务作为提供者或请求者类型的所有通讯日志。
显示这个窗口后,请求列表开始载入。在列表完全载入后你可以选择一行(即一条通讯序列)来检查它的详细信息,这个详细信息显示在窗口下方。
你可以使用窗口右边的过滤器来收缩通讯列表,你可以过滤的内容有:
通讯类型(提供者或请求者)
日期:在一个特定日期之前或之后
远程IP地址
以上所有组合
在设置了过滤器后,点击“刷新”按钮,就会显示满足搜索条件的新列表。
取决于过滤器的搜索条件,新列表可能无返回结果。
在窗口左侧的操作栏中你可以选择“返回WEB服务”,或点击“清除”按钮清空调试器日志,这会打开一个对话框确认清除日志,点击对话框中的“清除”按钮执行清除操作或点击“取消”关闭这个对话框。
在“请求详细信息”部分你可以看到选定通讯的所有详细信息。在这里你可以跟踪完整流并检查可能的错误或确认成功响应。
回到修改WEB服务窗口,现在我们准备回顾窗口右侧。在这里我们可以修改一个WEB服务的所有通用信息如名称、描述、调试阈值等等。此外下面还有两个部分允许我们修改通讯类型“OTRS作为提供者”和“OTRS作为请求者”的特定参数。
WEB服务配置需要在每个级别保存,这意味着如果修改了一个设置,到其它部分(这个配置更深层次的部分)的链接将被禁用,强迫你保存当前的配置级别。在保存后禁用了的链接会被重新启用,允许你使用这个配置继续。
在“OTRS作为提供者”部分可以设置或配置网络传输协议,只有注册了的网络传输后端才会显示在列表中。要配置网络传输,点击“配置”按钮。在这部分还可以添加新操作,从“添加操作”列表中选择一个可用的操作,这会引领你到操作配置窗口。在保存了这个新操作后它就会在上面的表格里列出。
在“OTRS作为请求者”部分与前面非常类似,但你可以在这里添加调用程序而不是“操作”。
点击“保存”按钮以保存并继续配置这个WEB服务,“保存并完成”保存并返回到WEB服务概览窗口,或者“取消”会丢弃当前配置级别的修改内容并返回到WEB服务概览窗口。
你其它的通用接口配置窗口(如网络传输、操作、调用程序和映射窗口)一样,初始化配置(添加)窗口仅提供了两个选项“保存”和“取消”。如果是重新查看这个配置,会出现新的选项“保存并完成”。这个功能的行为定义如下。
“保存”将存储当前配置级别到数据库并且会返回到之前的窗口以回顾你的修改内容或配置更深层次的设置。
“保存并完成”将存储当前配置级别到数据库并且会返回到配置层次之前的窗口(到上一个配置级别)。
“取消”将丢弃当前配置级别的任何配置修改内容,并且会返回到配置层次之前的窗口(到上一个配置级别)。
将来可用的网络传输列表可能会增加,目前只有“HTTP::SOAP”和“HTTP::REST”传输可用。每个传输有不同的配置选项,并且可能使用不同的前端界面来配置它们。
配置“HTTP::SOAP”作为提供者很简单。只有两个设置“命名空间”和“消息的最大长度”。这些字段是必填的,第一个是一个URI(统一资源标识符),为SOAP方法指定一个上下文,减少歧义;第二个是你可以指定OTRS能够处理SOAP消息的最大尺寸(单位:字节)。
对于“HTTP::REST”,配置可能要稍微复杂一些,因为它的设置会根据配置的操作而动态增长,给每个操作添加两个设置:“路由映射,用于操作 ‘<操作名称>’:”和“有效的请求方法,用于操作 ‘<操作名称<’:”到默认的传输设置“消息的最大长度:”和“发送Keep-Alive(保持连接):”之前。
路由映射,用于操作 ‘<操作名称>’:
在这个设置中设置一个资源路径,这个路径必须根据WEB服务考虑的需求来定义,这个路径与HTTP请求方法相结合来确定要执行的通用接口操作。
路径中可以包含变量,格式为‘:<VariableName>’。在变量位置的每个路径字符串会用这个设置中定义的变量名称替换后添加到请求的有效载荷中。
例子:
路由映射:/Resource
有效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One
无效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource?Param1=One
路由映射:/Resource/:ID
有效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1?Param1=One
在这两种情况下,ID=1都会发送到操作作为有效载荷的一部分。在这2种情况还添加了Param1=One,取决于HTTP请求方法还会添加其它参数(如果它们在请求头字段中作为一个JSON字符串)。
无效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource?Param1=One
路由映射:/Resource/OtherResource/:ID/:Color
有效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1/Red
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherReosurce/123/Blue?Param1=One
在第一个例子中,ID = 1且Color = Red,第二个例子中ID = 123且Color = Blue。
无效的请求:
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1
http://localhost/otrs/nph-genericinterface.pl/Webservice/Test/Resource/OtherResource/1?Param1=One
在第一个例子中,路径缺失了'/OtherResource'和:Color变量,在第二个例子中只缺失了:Color变量。
有效的请求方法,用于操作‘<操作名称>’:
HTTP请求方法结合路由映射来确定要使用的操作,可能的选项有:CONNECT、DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT和TRACE。
完全不同的操作可以共享完全相同的映射路径,但是为了正确地确定使用的操作,每个操作的请求方法必须是唯一的。
当你使用OTRS作为一个WEB服务提供者时可以完执行的动作叫“操作”。每个操作属于一个控制器。控制器是操作或调用程序的集合,一般地,同一控制器中的操作需要类似的设置并共享相同的配置对话框,但是如果需要每个操作可以有独立的配置对话框。
一般出现在操作中的字段是名称、描述、后端和映射,其它特殊字段可以出现在非默认配置对话框中以达到操作的特殊需要。
每个操作一般有两个映射配置部分,一个是进入数据映射,另外一个是出站数据映射。你可以为每个映射方向选择不同的映射类型(后端),因为它们的配置是彼此独立的,并且操作后端也是独立的。通常和最普遍的做法是操作在这两种情况下(反向的配置)使用相同的映射类型。完整的映射配置在一个单独的窗口(取决于映射类型)中完成。
操作后端是预先选择的,不能编辑。如果在WEB服务编辑窗口选择了该操作你就会看到这个参数。这个字段仅用于提供信息。
在窗口左侧的操作栏中你有这些选项:“返回到WEB服务”(丢弃上次保存后的所有修改内容)和“删除”。如果你点击了“删除”,会打开一个对话框问你是否要删除这个操作,点击“删除”按钮确认删除该操作和它的配置,或点击“取消”关闭对话框。
WEB服务请求者的网络传输配置类似于提供者的配置。对于请求者的“HTTP::SOAP”网络传输需要设置更多的字段。
除了“端点”(远程系统上的WEB服务用来接受请求的URI)和“命名空间”是必填字段外,你还要指定:
SOAP消息的编码(如utf-8、latin1、iso-8859-1、cp1250等等)
SOAP动作头:你可以使用这个来发送一个空的或填满的SOAPAction头。设置为“否”且SOAP消息中的SOAP动作头会是一个空的字符串,或者设置为“是”以发送‘命名空间’#‘动作’格式的SOAP动作并定义分隔符(通常.NET WEB服务是“/”,REST是“#”)。
身份认证:设置身份认证机制,设置为“-”不使用任何身份认证,或从列表中选择一个身份认证后会出现相关的详细字段。
目前只实现了“HTTP基本认证”机制。你可以根据远程系统配置决定是否要用它。如果要使用“HTTP基本认证”,你必须提供用户名和密码来访问远程系统。
如果你提供了一个身份认证密码并且随后你导出这个WEB服务到一个YAML文件,这个密码会以明文字符串导出到YAML文件中。请知悉这一点并在需要时采取必要的预防措施。
至于HTTP::REST,这个配置也会根据配置的调用程序动态增长,给每个调用程序添加两个设置:“控制器映射,用于调用程序 ‘<调用程序名称>:”和“有效的请求命令,用于调用程序 ‘<调用程序名称>’:”。身份认证和SSL选项类似于HTTP::SOAP。
主机
远程系统的主机名称或IP地址和端口号,如果没有端口号,默认使用80端口。
控制器映射,用于调用程序<调用程序名称>:
在这个设置中设置一个资源路径,这个路径必须根据远程WEB服务的需求来定义,并遵从它的规定。
路径可以包含‘:<变量名称>’格式的变量,每个变量名称匹配(要发送的)当前数据将被对应的数据值替换。匹配的变量名称和值将从当前数据中移除。取决于HTTP请求命令,剩余的数据可以在请求正文中作为一个JSON字符串或在URI中作为查询参数发送。
例子:
当前数据:Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four。
控制器映射:/Resource
替换后:
/Resource
剩余数据:
Var1 = One, Var2 = Two, Var3 = Three and Var4 = Four
控制器映射:/Resource/:Var1
替换后:
/Resource/One
剩余数据:
Var2 = Two, Var3 = Three and Var4 = Four
控制器映射:/Resource/:Var1?Param1=:Var2&Var3=:Var3
替换后:
/Resource/One?Param1=Two&Var3=Three
剩余数据:
Var4 = Four
有效的请求命令,用于调用程序 ‘<调用程序名称>’:
这个字段确定使用的HTTP请求方法,可能的选项有:CONNECT、DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT和TRACE。如果没有选择命令,则使用默认命令。
默认命令
用作所有没有定义请求命令的调用程序的最后依靠。
当你使用OTRS作为一个WEB服务请求者时能够执行的操作称之为“调用程序”。每个调用程序属于一个控制器(控制器是操作或调用程序的集合)。通常在相同控制器中的调用程序需要类似的设置和共同相同的配置对话框。每个调用程序如果需要可以有独立的配置对话框。
在每个调用程序配置中通常是名称、描述、后端和映射字段,附加的事件触发器和其它特殊字段的列表可以出现在非默认的配置对话框中以满足调用程序特殊的需求。
每个调用程序通常有两个映射配置部分,一个是对进入的数据,另外一个是对发出的数据。你可以给每个映射方向选择不同的映射类型(后端),因为它们的配置是彼此独立的,调用程序后端也是独立的。通常和最普遍的做法是调用程序在这两种情况下(反射的配置)使用相同的映射类型。完整的映射配置在一个单独的窗口(取决于映射类型)中完成。
操作后端是预先选择的,不能编辑。如果在WEB服务编辑窗口选择了该调用程序你就会看到这个参数。这个字段仅用于提供信息。
事件触发器是OTRS中的事件比如“工单创建”、“信件发送”等等。这些事件可以作为执行调用程序的触发器。每个调用程序需要注册至少一个事件触发器,否则调用程序就没用,因为它永远不会被调用。事件触发器的异步属性定义是由OTRS进程处理这个调用程序还是委托给OTRS守护进程处理。
OTRS守护进程是一个执行后台任务的单独的进程集,使用守护进程就不会影响OTRS进程本身,比如服务不可用或有网络问题,远程系统花费大量时间才响应。如果你不使用OTRS守护进程,则使用WEB服务会导致OTRS变慢或无法响应。所以强烈推荐尽可能使用异步事件触发器。
要添加一个事件触发器,首先从第一个列表中选择事件家族,然后从第二个列表中选择事件名称,然后设置异步属性(未选中即意味着事件触发器不是异步的),最后点击“+”按钮。就会创建一个新的事件触发器,会在调用程序的“事件触发器”列表中列出。
要删除一个事件触发器,简单定位到“事件触发器”列表中要删除的事件触发器,点击行尾的“垃圾桶”图标即可。这会打开一个对话框问你是否确认删除该事件触发器,点击“删除”从列表中删除这个事件触发器,或“取消”关闭对话框。
在窗口左侧操作栏你有两个选项:“返回到WEB服务”(丢失上次保存以来的所有修改内容)和“删除”。如果你点击了“删除”按钮,会弹出一个对话框问你是否要删除这个调用程序,点击“删除”删除这个调用程序和它的配置,或“取消”关闭删除对话框。
有这种情况:你需要将一种格式的数据转化为另外的格式(映射或修改数据结构),因为通常一个WEB服务用来与一个远程系统交互,很可能不是另外一个OTRS系统并且/或者不能理解OTRS数据结构和值。在这些情况下一些或所有值必须被修改,有些时候甚至值的名称(键)或整个结构都需要修改,才能匹配另外一端期望的数据。
每个远程系统都有它自己的数据结构,可以为每种情况创建新的映射模块(例如:OTRS自带有一个为SAP Solution Manager定制的映射模块),但并不总是需要这样单独定制,Mapping::Simple模块可以涵盖大部分的映射需求。
当Mapping::Simple无法处理一个WEB服务所有的映射需求时,就需要创建一个映射模块。要学习关于如何创建一个新的映射模块的更多内容,请参阅OTRS开发手册。
这个模块让你有机会设置默认值来映射整个通讯数据中的每个键或值。
在窗口的开始部分你会看到一个通用部分,在这里你可以设置默认规则,适用于所有没有映射的键和值。还有3个选项可用,如下列表:
保持(保持不变):不对键或值做任何改动。
忽略(丢弃键/值对):当这个选项用于键时它会删除键和值,因为当一个键被删除时结果就是键相关的值也被删除。当这个选项用于值时,只有这个值被删除,保留键(现在会关联一个空值)。
映射到(使用提供键或值为默认):所有没有定义映射规则的键和/或值,使用这个映射作为默认映射,当你选择这个选项后会出现一个新的文本字段,用来设置默认键或值。
点击“+”按钮来添加新的键映射,会显示一个新框用于一个特定映射配置。你可以根据需要的随意添加键映射。只需再次点击“+”按钮,在已有映射的下面会出现一个新的映射框。从这个映射你可以定义一个特定键的映射,有下列选项:
准确值:如果原键完全匹配,原键字符串会变为一个新的键。
正则表达式:键字符串会按照一个正则表达式规则进行替换。
点击新增值映射的“+”按钮,会显示一个新行用于值映射。在这里也有键映射那样的选项(准确值和正则表达式)来定义每个值映射。你可以根据需要随意添加值映射,如果你要删除一个值映射,只需点击每个值映射行后面的“-”按钮即可。
可以删除完整的键映射部分(框),只需点击要删除的键映射框右上角的“-”按钮即可。
如果你要删除一个完整的映射配置,返回到相应的操作或调用程序窗口,找到之前选择的映射方向并设置其值为“-”,然后保存配置即可。
bin/otrs.Console.pl
Admin::WebService::*
系列命令被设计为一组基本但快速、强大的的工具以处理WEB服务配置。它们让你能够执行下列操作:
Add(添加):使用一个YAML文件作为配置源来创建WEB服务。
Update(更新):修改一个已有的WEB服务,使用一个不同的或修改过的YAML文件来修改WEB服务的配置。
Dump(转储):将当前的WEB服务的配置保存到一个文件。
List(列表):获取当前系统中注册的所有WEB服务的完整清单。
Delete(删除):从系统中删除一个WEB服务。使用它的时候要小心,因为这个操作无法复原。
例子:创建一个新的WEB服务配置:
shell> bin/otrs.Console.pl Admin::WebService::Add --name <webservice_name> --source-path /path/to/yaml/file
从WEB服务的设计来说,它主要考虑从一个OTRS系统到另外一个OTRS系统的可移植性,例如从一个测试或开发环境移植到生产系统。所以需要有一种容易的方式来从数据库提取WEB服务配置,并将它导入到另外一个系统。为完成这个任务,通用接口使用YAML文件作为WEB服务的配置基础。
为什么是YAML?YAML是一种标记语言,设计为人类友好的读和写(它比JSON更容易理解)。它没有XML的一些限制如数字标签,它是开放的和标准化的,并且完全足够用来存储整个WEB服务配置。
要学习关于YAML的更多内容,请访问http://www.yaml.org/。
下面是一个YAML格式的WEB服务配置文件例子:
--- 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
Description(描述):描述WEB服务的简短文本。
RemoteSystem(远程系统):远程系统的简短描述。
Debugger(调试器):调试器设置的一个容器。
Provider(提供者):提供者设置的一个容器。
Requester(请求者):请求者设置的一个容器。
调试阈值:调试器的级别。
可能的值
debug(调试):所有日志都存储到数据库。
info(信息):info(信息)、notice(注意)和error(错误)级别的日志存储到数据库。
notice(注意):notice(注意)和error(错误)级别的日志存储到数据库。
error(错误):只有error(错误)级别的日志存储到数据库。
Operation(操作):每个操作设置的一个容器。
Transport(传输):提供者网络传输设置的一个容器。
<OperationName操作名称>:操作的唯一名称,它自己的操作设置的容器(可以加基数0..n,但不能重复)。
这部分基于来自“Test::Test”类型的操作,其它操作可能包含更多或不同的设置。
Description(描述):描述这个操作的简短文本。
MappingInbound(入站映射):进入的请求数据的映射设置容器。
MappingOutbound(出站映射):外发的响应数据的映射设置容器。
Type(类型):操作后端,格式为Controller::Operation。
本部分内容基于映射类型“Simple(简单)”,其它映射类型可能包含更多或不同的设置。
Config(配置):这个映射设置的容器。
Type(类型):映射后端。
KeyMapDefault(默认的键映射):所有未映射的键的设置的容器。
ValueMapDefault(默认的值映射):所有未映射的值的设置的容器。
KeyMapExact(准确的键映射):所有准确的键映射(基数0 .. 1)的容器。
KeyMapRegEx(正则键映射):所有正则表达式的键映射(基数0 .. 1)的容器。
ValueMap(值映射):所有值映射(基数0 .. 1)的容器。
MapTo(映射到):使用新的值(只适用于MapTo映射类型)。
MapType(映射类型):映射的规则。
可能的值
Keep(保持):保持不变
Ignore(忽略):丢弃。
MapTo(映射到):修改为MapTo的值。
<newkey(新键)>:这个新键的值映射容器(基数取决于来自KeyMapExact和KeyMapRegEx的新键)。
Invoker(调用程序):每个调用程序的设置的容器。
Transport(传输):请求者网络传输设置的容器。
<InvokerName调用程序名称>:该调用程序的唯一名称,它自己的调用程序设置的容器(基数 0 .. n,但不能重复)。
本部分内容基于调用程序类型“Test::Test”,其它调用程序类型可能包含更多或不同的设置。
Description(描述):描述这个调用程序的简短文本。
Events(事件):事件触发器的未命名列表的容器。
MappingInbound(入站映射):进入的响应数据的映射设置容器。
MappingOutbound(出站映射):外发的请求数据的映射设置容器。
Type(类型):Controller(控制器)::Invoker(调用程序)格式的调用程序后端。
列表元素:(基数 0 .. n)。
异步:设置是否委派给OTRS守护进程执行调用程序。
可能的值
0:不由OTRS守护进程执行调用程序。
1:由OTRS守护进程执行调用程序。
Event(事件):事件触发器的名称。
可能的值(用于工单事件)
工单创建
TicketDelete(删除工单)
TicketTitleUpdate(更新工单标题)
TicketUnlockTimeoutUpdate(更新工单解锁超时)
TicketQueueUpdate(更新工单队列)
TicketTypeUpdate(更新工单类型)
TicketServiceUpdate(更新工单服务)
TicketSLAUpdate(更新工单SLA)
TicketCustomerUpdate((更新工单客户联系人)
TicketPendingTimeUpdate(更新工单挂起时间)
TicketLockUpdate(更新工单锁定)
TicketArchiveFlagUpdate(更新工单归档标识)
TicketStateUpdate(更新工单状态)
TicketOwnerUpdate(更新工单所有者)
TicketResponsibleUpdate(更新工单负责人)
TicketPriorityUpdate(更新工单优先级)
HistoryAdd(添加历史)
HistoryDelete(删除历史)
TicketAccountTime(工单占用时间)
TicketMerge(合并工单)
TicketSubscribe(关注工单)
TicketUnsubscribe(取消关注工单)
TicketFlagSet(设置工单标识)
TicketFlagDelete(删除工单标识)
TicketSlaveLinkAdd(添加‘从工单’链接)
TicketSlaveLinkDelete(删除‘从工单’链接)
TicketMasterLinkDelete(删除‘主工单’链接)
可能的值(用于信件事件)
ArticleCreate(创建信件)
ArticleUpdate(更新信件)
ArticleSend(发送信件)
ArticleBounce(退回信件)
ArticleAgentNotification(服务人员通知信件)
ArticleCustomerNotification(客户通知信件)
ArticleAutoResponse(自动响应信件)
ArticleFlagSet(设置信件标识)
ArticleFlagDelete(删除信件标识)
本部分基于请求者的网络传输HTTP::SOAP,其它的传输可能包含更多或不同的设置。
Config(配置):这个特定的网络传输配置的容器。
Type(类型):请求者的网络传输后端。
Authentication(身份认证):身份认证设置的容器。
Encoding(编码):需要将SOAP消息编码。
Endpoint(端点):远程服务器WEB服务的URI,用来接受OTRS的请求。
NameSpace(命名空间):一个URI,给定一个属于这个WEB服务的所有调用程序的上下文环境。
SOAPAction(SOAP动作):在SOAP消息中发送一个空的或填满的SOAPAction头(用“<NameSpace> <Separator> <Action>”格式)。
可能的值
Yes(是):发送一个填满的SOAPAction头。
No(否):发送一个空的SOAPAction头。
SOAPActionSeparator(SOAP动作分隔符):设置填满的SOAP动作头的<分隔符>。
可能的值
'/':用于.NET WEB服务。
'#':用于所有其它的WEB服务。
连接器本质上是动作(在OTRS作为WEB服务提供者时叫操作,在OTRS作为WEB服务请求者时啊调用程序)的集合。但是它也可以包含特殊的映射或传输。
一个连接器可以只有操作、只有调用程序或者两者都有。一个连接器甚至可以使用其它连接器的一部分如映射或传输(如果它们不是部署为特定的连接器的话)。
换句话说,连接器不局限于控制器层,在需要时还能扩展到数据映射或网络传输层。
由于通用接口的模块化设计,连接器可以看作是一个插件;这意味着通过添加连接器,通用接口的能力可以扩展使用在:OTRS功能插件、OTRS定制模块、第三方模块等等。
在当前版本的OTRS中有下列连接器可以使用:
会话
工单
这个连接器有能力创建一个有效的会话ID,能够用在其它任何操作中。
提供:
操作:
创建会话
创建一个新的有效会话ID,用在其它连接器比如创建工单的其它操作中。
要在其它连接器的其它操作中使用这个会话ID,需要该操作通过会话ID部署身份认证。所有剩下的捆绑操作都有能力接受一个有效的会话ID作为一个身份认证方法。
可能的属性:
<SessionCreate> <!--You have a MANDATORY CHOICE of the next 2 items at this level--> <!--Optional:--> <UserLogin>?</UserLogin> <!--Optional:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Optional:--> <Password>?</Password> </SessionCreate>
这个连接器提供与工单交互的基本功能。
提供:
操作:
工单创建
更新工单
获取工单
搜索工单
提供一个接口以在OTRS中创建一个工单。一个工单必须包含一个信件并包含数个附件,所有定义的动态字段也可以在创建工单操作时设置。
可能的属性:
<TicketCreate> <!--You have a MANDATORY CHOICE of the next 3 items at this level--> <!--Optional:--> <UserLogin>?</UserLogin> <!--Optional:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Optional:--> <SessionID>?</SessionID> <!--Optional:--> <Password>?</Password> <Ticket> <Title>?</Title> <!--You have a MANDATORY CHOICE of the next 2 items at this level--> <!--Optional:--> <QueueID>?</QueueID> <!--Optional:--> <Queue>?</Queue> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <TypeID>?</TypeID> <!--Optional:--> <Type>?</Type> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ServiceID>?</ServiceID> <!--Optional:--> <Service>?</Service> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <SLAID>?</SLAID> <!--Optional:--> <SLA>?</SLA> <!--You have a MANDATORY CHOICE of the next 2 items at this level--> <!--Optional:--> <StateID>?</StateID> <!--Optional:--> <State>?</State> <!--You have a MANDATORY CHOICE of the next 2 items at this level--> <!--Optional:--> <PriorityID>?</PriorityID> <!--Optional:--> <Priority>?</Priority> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <OwnerID>?</OwnerID> <!--Optional:--> <Owner>?</Owner> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ResponsibleID>?</ResponsibleID> <!--Optional:--> <Responsible>?</Responsible> <CustomerUser>?</CustomerUser> <!--Optional:--> <CustomerID>?</CustomerID> <!--Optional:--> <PendingTime> <!--You have a CHOICE of the next and the other 5 items at this level--> <Diff>?</Diff> <Year>?</Year> <Month>?</Month> <Day>?</Day> <Hour>?</Hour> <Minute>?</Minute> </PendingTime> </Ticket> <Article> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ArticleTypeID>?</ArticleTypeID> <!--Optional:--> <ArticleType>?</ArticleType> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <SenderTypeID>?</SenderTypeID> <!--Optional:--> <SenderType>?</SenderType> <!--Optional:--> <From>?</From> <Subject>?</Subject> <Body>?</Body> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ContentType>?</ContentType> <Charset>?</Charset> <MimeType>?</MimeType> <!--Optional:--> <HistoryType>?</HistoryType> <!--Optional:--> <HistoryComment>?</HistoryComment> <!--Optional:--> <AutoResponseType>?</AutoResponseType> <!--Optional:--> <TimeUnit>?</TimeUnit> <!--Optional:--> <NoAgentNotify>?</NoAgentNotify> <!--Zero or more repetitions:--> <ForceNotificationToUserID>?</ForceNotificationToUserID> <!--Zero or more repetitions:--> <ExcludeNotificationToUserID>?</ExcludeNotificationToUserID> <!--Zero or more repetitions:--> <ExcludeMuteNotificationToUserID>?</ExcludeMuteNotificationToUserID> </Article> <!--Zero or more repetitions:--> <DynamicField> <Name>?</Name> <!--1 or more repetitions:--> <Value>?</Value> </DynamicField> <!--Zero or more repetitions:--> <Attachment> <Content>cid:61886944659</Content> <ContentType>?</ContentType> <Filename>?</Filename> </Attachment> </TicketCreate>
‘更新工单’操作用来修改已有工单的属性或者添加一个新的信件(包括附件和所有定义的工单和信件的动态字段)。
没有必要创建一个信件来修改一个工单的属性。
可能的属性:
<TicketUpdate> <!--You have a MANDATORY CHOICE of the next 3 items at this level--> <!--Optional:--> <UserLogin>?</UserLogin> <!--Optional:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Optional:--> <SessionID>?</SessionID> <!--Optional:--> <Password>?</Password> <!--You have a CHOICE of the next 2 items at this level--> <TicketID>?</TicketID> <TicketNumber>?</TicketNumber> <!--Optional:--> <Ticket> <!--Optional:--> <Title>?</Title> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <QueueID>?</QueueID> <!--Optional:--> <Queue>?</Queue> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <TypeID>?</TypeID> <!--Optional:--> <Type>?</Type> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ServiceID>?</ServiceID> <!--Optional:--> <Service>?</Service> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <SLAID>?</SLAID> <!--Optional:--> <SLA>?</SLA> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <StateID>?</StateID> <!--Optional:--> <State>?</State> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <PriorityID>?</PriorityID> <!--Optional:--> <Priority>?</Priority> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <OwnerID>?</OwnerID> <!--Optional:--> <Owner>?</Owner> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ResponsibleID>?</ResponsibleID> <!--Optional:--> <Responsible>?</Responsible> <!--Optional:--> <CustomerUser>?</CustomerUser> <!--Optional:--> <CustomerID>?</CustomerID> <!--Optional:--> <PendingTime> <!--You have a CHOICE of the next and the other 5 items at this level--> <Diff>?</Diff> <Year>?</Year> <Month>?</Month> <Day>?</Day> <Hour>?</Hour> <Minute>?</Minute> </PendingTime> </Ticket> <!--Optional:--> <Article> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ArticleTypeID>?</ArticleTypeID> <!--Optional:--> <ArticleType>?</ArticleType> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <SenderTypeID>?</SenderTypeID> <!--Optional:--> <SenderType>?</SenderType> <!--Optional:--> <From>?</From> <Subject>?</Subject> <Body>?</Body> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <ContentType>?</ContentType> <Charset>?</Charset> <MimeType>?</MimeType> <!--Optional:--> <HistoryType>?</HistoryType> <!--Optional:--> <HistoryComment>?</HistoryComment> <!--Optional:--> <AutoResponseType>?</AutoResponseType> <!--Optional:--> <TimeUnit>?</TimeUnit> <!--Optional:--> <NoAgentNotify>?</NoAgentNotify> <!--Zero or more repetitions:--> <ForceNotificationToUserID>?</ForceNotificationToUserID> <!--Zero or more repetitions:--> <ExcludeNotificationToUserID>?</ExcludeNotificationToUserID> <!--Zero or more repetitions:--> <ExcludeMuteNotificationToUserID>?</ExcludeMuteNotificationToUserID> </Article> <!--Zero or more repetitions:--> <DynamicField> <Name>?</Name> <!--1 or more repetitions:--> <Value>?</Value> </DynamicField> <!--Zero or more repetitions:--> <Attachment> <Content>cid:166861569966</Content> <ContentType>?</ContentType> <Filename>?</Filename> </Attachment> </TicketUpdate>
这个操作用来获取一个工单的所有属性,包括动态字段、所有信件和属于工单的所有附件。
可能的属性:
<TicketGet> <!--You have a MANDATORY CHOICE of the next 3 items at this level--> <!--Optional:--> <UserLogin>?</UserLogin> <!--Optional:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Optional:--> <SessionID>?</SessionID> <!--Optional:--> <Password>?</Password> <!--1 or more repetitions:--> <TicketID>?</TicketID> <!--Optional:--> <DynamicFields>?</DynamicFields> <!--Optional:--> <Extended>?</Extended> <!--Optional:--> <AllArticles>?</AllArticles> <!--Optional:--> <ArticleSenderType>?</ArticleSenderType> <!--Optional:--> <ArticleOrder>?</ArticleOrder> <!--Optional:--> <ArticleLimit>?</ArticleLimit> <!--Optional:--> <Attachments>?</Attachments> <!--Optional:--> <HTMLBodyAsAttachment>?</HTMLBodyAsAttachment> </TicketGet>
‘搜索工单’操作返回匹配一个预定义条件的工单编号列表。
可能的属性:
<TicketSearch> <!--You have a MANDATORY CHOICE of the next 3 items at this level--> <!--Optional:--> <UserLogin>?</UserLogin> <!--Optional:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Optional:--> <SessionID>?</SessionID> <!--Optional:--> <Password>?</Password> <!--Optional:--> <Limit>?</Limit> <!--Zero or more repetitions:--> <TicketNumber>?</TicketNumber> <!--Zero or more repetitions:--> <Title>?</Title> <!--Zero or more repetitions:--> <Queues>?</Queues> <!--Zero or more repetitions:--> <QueueIDs>?</QueueIDs> <!--Optional:--> <UseSubQueues>?</UseSubQueues> <!--Zero or more repetitions:--> <Types>?</Types> <!--Zero or more repetitions:--> <TypeIDs>?</TypeIDs> <!--Zero or more repetitions:--> <States>?</States> <!--Zero or more repetitions:--> <StateIDs>?</StateIDs> <!--Zero or more repetitions:--> <StateType>?</StateType> <!--Zero or more repetitions:--> <StateTypeIDs>?</StateTypeIDs> <!--Zero or more repetitions:--> <Priorities>?</Priorities> <!--Zero or more repetitions:--> <PriorityIDs>?</PriorityIDs> <!--Zero or more repetitions:--> <Services>?</Services> <!--Zero or more repetitions:--> <ServiceIDs>?</ServiceIDs> <!--Zero or more repetitions:--> <SLAs>?</SLAs> <!--Zero or more repetitions:--> <SLAIDs>?</SLAIDs> <!--Zero or more repetitions:--> <Locks>?</Locks> <!--Zero or more repetitions:--> <LockIDs>?</LockIDs> <!--Zero or more repetitions:--> <OwnerIDs>?</OwnerIDs> <!--Zero or more repetitions:--> <ResponsibleIDs>?</ResponsibleIDs> <!--Zero or more repetitions:--> <WatchUserIDs>?</WatchUserIDs> <!--Zero or more repetitions:--> <CustomerID>?</CustomerID> <!--Zero or more repetitions:--> <CustomerUserLogin>?</CustomerUserLogin> <!--Zero or more repetitions:--> <CreatedUserIDs>?</CreatedUserIDs> <!--Zero or more repetitions:--> <CreatedTypes>?</CreatedTypes> <!--Zero or more repetitions:--> <CreatedTypeIDs>?</CreatedTypeIDs> <!--Zero or more repetitions:--> <CreatedPriorities>?</CreatedPriorities> <!--Zero or more repetitions:--> <CreatedPriorityIDs>?</CreatedPriorityIDs> <!--Zero or more repetitions:--> <CreatedStates>?</CreatedStates> <!--Zero or more repetitions:--> <CreatedStateIDs>?</CreatedStateIDs> <!--Zero or more repetitions:--> <CreatedQueues>?</CreatedQueues> <!--Zero or more repetitions:--> <CreatedQueueIDs>?</CreatedQueueIDs> <!--Zero or more repetitions:--> <DynamicFields> <!--You have a MANDATORY CHOICE of the next 6 items at this level--> <!--Optional:--> <Equals>?</Equals> <!--Optional:--> <Like>?</Like> <!--Optional:--> <GreaterThan>?</GreaterThan> <!--Optional:--> <GreaterThanEquals>?</GreaterThanEquals> <!--Optional:--> <SmallerThan>?</SmallerThan> <!--Optional:--> <SmallerThanEquals>?</SmallerThanEquals> </DynamicFields> <!--Optional:--> <Ticketflag> <!--Optional:--> <Seen>?</Seen> </Ticketflag> <!--Optional:--> <From>?</From> <!--Optional:--> <To>?</To> <!--Optional:--> <Cc>?</Cc> <!--Optional:--> <Subject>?</Subject> <!--Optional:--> <Body>?</Body> <!--Optional:--> <FullTextIndex>?</FullTextIndex> <!--Optional:--> <ContentSearch>?</ContentSearch> <!--Optional:--> <ConditionInline>?</ConditionInline> <!--Optional:--> <ArticleCreateTimeOlderMinutes>?</ArticleCreateTimeOlderMinutes> <!--Optional:--> <ArticleCreateTimeNewerMinutes>?</ArticleCreateTimeNewerMinutes> <!--Optional:--> <ArticleCreateTimeNewerDate>?</ArticleCreateTimeNewerDate> <!--Optional:--> <ArticleCreateTimeOlderDate>?</ArticleCreateTimeOlderDate> <!--Optional:--> <TicketCreateTimeOlderMinutes>?</TicketCreateTimeOlderMinutes> <!--Optional:--> <ATicketCreateTimeNewerMinutes>?</ATicketCreateTimeNewerMinutes> <!--Optional:--> <TicketCreateTimeNewerDate>?</TicketCreateTimeNewerDate> <!--Optional:--> <TicketCreateTimeOlderDate>?</TicketCreateTimeOlderDate> <!--Optional:--> <TicketLastChangeTimeOlderMinutes>?</TicketLastChangeTimeOlderMinutes> <!--Optional:--> <TicketLastChangeTimeNewerMinutes>?</TicketLastChangeTimeNewerMinutes> <!--Optional:--> <TicketLastChangeTimeNewerDate>?</TicketLastChangeTimeNewerDate> <!--Optional:--> <TicketLastChangeTimeOlderDate>?</TicketLastChangeTimeOlderDate> <!--Optional:--> <TicketChangeTimeOlderMinutes>?</TicketChangeTimeOlderMinutes> <!--Optional:--> <TicketChangeTimeNewerMinutes>?</TicketChangeTimeNewerMinutes> <!--Optional:--> <TicketChangeTimeNewerDate>?</TicketChangeTimeNewerDate> <!--Optional:--> <TicketChangeTimeOlderDate>?</TicketChangeTimeOlderDate> <!--Optional:--> <TicketCloseTimeOlderMinutes>?</TicketCloseTimeOlderMinutes> <!--Optional:--> <TicketCloseTimeNewerMinutes>?</TicketCloseTimeNewerMinutes> <!--Optional:--> <TicketCloseTimeNewerDate>?</TicketCloseTimeNewerDate> <!--Optional:--> <TicketCloseTimeOlderDate>?</TicketCloseTimeOlderDate> <!--Optional:--> <TicketPendingTimeOlderMinutes>?</TicketPendingTimeOlderMinutes> <!--Optional:--> <TicketPendingTimeNewerMinutes>?</TicketPendingTimeNewerMinutes> <!--Optional:--> <TicketPendingTimeNewerDate>?</TicketPendingTimeNewerDate> <!--Optional:--> <TicketPendingTimeOlderDate>?</TicketPendingTimeOlderDate> <!--Optional:--> <TicketEscalationTimeOlderMinutes>?</TicketEscalationTimeOlderMinutes> <!--Optional:--> <TTicketEscalationTimeNewerMinutes>?</TTicketEscalationTimeNewerMinutes> <!--Optional:--> <TicketEscalationTimeNewerDate>?</TicketEscalationTimeNewerDate> <!--Optional:--> <TicketEscalationTimeOlderDate>?</TicketEscalationTimeOlderDate> <!--Optional:--> <ArchiveFlags>?</ArchiveFlags> <!--Zero or more repetitions:--> <OrderBy>?</OrderBy> <!--Zero or more repetitions:--> <SortBy>?</SortBy> <!--Zero or more repetitions:--> <CustomerUserID>?</CustomerUserID> </TicketSearch>
下面是一个基本但完整的YAML格式的WEB服务配置文件,通过SOAP网络传输方法使用了所有的工单连接器操作。为了在OTRS中使用它,你需要复制它的内容到一个叫GenericTicketConnectorSOAP.yml
的文件,并且在系统管理页面进入WEB服务窗口,然后在WEB服务概览窗口点击“添加WEB服务”按钮,然后在添加WEB服务窗口点击“导入WEB服务”按钮,将这个文件导入到OTRS中。
--- Debugger: DebugThreshold: debug TestMode: 0 Description: Ticket Connector SOAP Sample FrameworkVersion: 3.4.x git Provider: Operation: SessionCreate: Description: Creates a Session MappingInbound: {} MappingOutbound: {} Type: Session::SessionCreate TicketCreate: Description: Creates a Ticket MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketCreate TicketUpdate: Description: Updates a Ticket MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketUpdate TicketGet: Description: Retrieves Ticket data MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketGet TicketSearch: Description: Search for Tickets MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketSearch Transport: Config: MaxLength: 100000000 NameSpace: http://www.otrs.org/TicketConnector/ Type: HTTP::SOAP RemoteSystem: '' Requester: Transport: Type: ''
类似的例子可以用REST网络传输做到,REST WEB服务使用HTTP操作比如“POST”、“GET”、“PUT”、“PATCH”等等。这个操作连同一个叫做资源的URI路径一起定义一个OTRS通用接口操作或调用程序(取决于通讯方式)。
下列的例子为‘创建会话’使用/Session资源,为搜索工单和创建工单使用
/Ticket资源,为获取工单和更新工单使用/Ticket/{TicketID}郑源(这里{TicketID}是一个工单的实际工单ID,例如/Ticket/123)。为了在OTRS中使用它,你需要复制它的内容到一个叫GenericTicketConnectorREST.yml
的文件,并且在系统管理页面进入WEB服务窗口,然后在WEB服务概览窗口点击“添加WEB服务”按钮,然后在添加WEB服务窗口点击“导入WEB服务”按钮,将这个文件导入到OTRS中。
--- Debugger: DebugThreshold: debug TestMode: '0' Description: Ticket Connector REST Sample FrameworkVersion: 3.4.x git Provider: Operation: SessionCreate: Description: Creates a Session MappingInbound: {} MappingOutbound: {} Type: Session::SessionCreate TicketCreate: Description: Creates a Ticket MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketCreate TicketGet: Description: Retrieves Ticket data MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketGet TicketSearch: Description: Search for Tickets MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketSearch TicketUpdate: Description: Updates a Ticket MappingInbound: {} MappingOutbound: {} Type: Ticket::TicketUpdate Transport: Config: KeepAlive: '' MaxLength: '100000000' RouteOperationMapping: SessionCreate: RequestMethod: - POST Route: /Session TicketCreate: RequestMethod: - POST Route: /Ticket TicketGet: RequestMethod: - GET Route: /Ticket/:TicketID TicketSearch: RequestMethod: - GET Route: /Ticket TicketUpdate: RequestMethod: - PATCH Route: /Ticket/:TicketID Type: HTTP::REST RemoteSystem: '' Requester: Transport: Type: ''
下列代码是一个Perl脚本,可以通过通用接口连接到OTRS。为了执行工单连接器提供的操作,它使用了两个Perl的CPAN模块:SOAP::Lite和Data::Dumper。在你尝试运行这个脚本之前,请确保你的环境能够使用这些模块。
#!/usr/bin/perl -w # -- # otrs.SOAPRequest.pl - sample to send a SOAP request to OTRS Generic Interface Ticket Connector # Copyright (C) 2001-2018 OTRS AG, https://otrs.com/ # -- # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0.txt. # -- use strict; use warnings; # use ../ as lib location use File::Basename; use FindBin qw($RealBin); use lib dirname($RealBin); use SOAP::Lite; use Data::Dumper; # --- # Variables to be defined. # this is the URL for the web service # the format is # <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl/Webservice/<WEB_SERVICE_NAME> # or # <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl/WebserviceID/<WEB_SERVICE_ID> my $URL = 'http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnector'; # this name space should match the specified name space in the SOAP transport for the web service. my $NameSpace = 'http://www.otrs.org/TicketConnector/'; # this is operation to execute, it could be TicketCreate, TicketUpdate, TicketGet, TicketSearch # or SessionCreate. and they must to be defined in the web service. my $Operation = 'TicketCreate'; # this variable is used to store all the parameters to be included on a request in XML format. Each # operation has a determined set of mandatory and non mandatory parameters to work correctly. Please # check the OTRS Admin Manual in order to get a complete list of parameters. my $XMLData = ' <UserLogin>some user login</UserLogin> <Password>some password</Password> <Ticket> <Title>some title</Title> <CustomerUser>some customer user login</CustomerUser> <Queue>some queue</Queue> <State>some state</State> <Priority>some priority</Priority> </Ticket> <Article> <Subject>some subject</Subject> <Body>some body</Body> <ContentType>text/plain; charset=utf8</ContentType> </Article> '; # --- # create a SOAP::Lite data structure from the provided XML data structure. my $SOAPData = SOAP::Data ->type( 'xml' => $XMLData ); my $SOAPObject = SOAP::Lite ->uri($NameSpace) ->proxy($URL) ->$Operation($SOAPData); # check for a fault in the soap code. if ( $SOAPObject->fault ) { print $SOAPObject->faultcode, " ", $SOAPObject->faultstring, "\n"; } # otherwise print the results. else { # get the XML response part from the SOAP message. my $XMLResponse = $SOAPObject->context()->transport()->proxy()->http_response()->content(); # deserialize response (convert it into a perl structure). my $Deserialized = eval { SOAP::Deserializer->deserialize($XMLResponse); }; # remove all the headers and other not needed parts of the SOAP message. my $Body = $Deserialized->body(); # just output relevant data and no the operation name key (like TicketCreateResponse). for my $ResponseKey ( keys %{$Body} ) { print Dumper( $Body->{$ResponseKey} ); } }
下列的代码是一个Perl脚本,可以通过通用接口连接到OTRS。为了执行工单连接器提供的操作,它使用了三个Perl的CPAN模块:JSON、REST::Client和Data::Dumper。在你尝试运行这个脚本之前,请确保你的环境能够使用这些模块。
#!/usr/bin/perl # -- # otrs.RESTRequest.pl - sample to send a REST request to OTRS Generic Interface Ticket Connector # Copyright (C) 2001-2018 OTRS AG, https://otrs.com/ # -- # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0.txt. # -- use strict; use warnings; ## nofilter(TidyAll::Plugin::OTRS::Perl::Dumper) # use ../ as lib location use File::Basename; use FindBin qw($RealBin); use lib dirname($RealBin); use JSON; use REST::Client; # --- # Variables to be defined # This is the HOST for the web service the format is: # <HTTP_TYPE>:://<OTRS_FQDN>/nph-genericinterface.pl my $Host = 'http://localhost/otrs/nph-genericinterface.pl'; my $RestClient = REST::Client->new( { host => $Host, } ); # This is the Controller and Request the format is: # /Webservice/<WEB_SERVICE_NAME>/<RESOURCE>/<REQUEST_VALUE> # or # /WebserviceID/<WEB_SERVICE_ID>/<RESOURCE>/<REQUEST_VALUE> # This example will retrieve the Ticket with the TicketID = 1 (<REQUEST_VALUE>) my $ControllerAndRequest = '/Webservice/GenericTicketConnectorREST/Ticket/1'; my $Params = { UserLogin => "some user login", # to be filled with valid agent login Password => "some user password", # to be filled with valid agent password DynamicFields => 1, # optional, if set to 1, # ticket dynamic fields included in response AllArticles => 1, # optional, if set to 1, # all ticket articles are included in response # more options to be found in # /Kernel/GenericInterface/Operation/Ticket/TicketGet.pm's # Run() subroutine documentation. }; my @RequestParam; # As sample web service configuration for TicketGet uses HTTP method GET all other parameters needs # to be sent as URI query parameters # ---- # For GET method my $QueryParams = $RestClient->buildQuery( %{ $Params } ); $ControllerAndRequest .= $QueryParams; # The @RequestParam array on position 0 holds controller and request @RequestParam = ($ControllerAndRequest); $RestClient->GET(@RequestParam); # ---- # # ---- # # For POST method # my $JSONParams = encode_json $Params; # # The @RequestParam array on position 0 holds controller and request # # on position 1 it holds the JSON data string that gets posted # @RequestParam = ( # $ControllerAndRequest, # $JSONParams # ); # $RestClient->POST(@RequestParam); # # ---- # If the host isn't reachable, wrong configured or couldn't serve the requested page: my $ResponseCode = $RestClient->responseCode(); if ( $ResponseCode ne '200' ) { print "Request failed, response code was: $ResponseCode\n"; exit; } # If the request was answered correctly, we receive a JSON string here. my $ResponseContent = $RestClient->responseContent(); my $Data = decode_json $ResponseContent; # Just to print out the returned Data structure: use Data::Dumper; print "Response was:\n"; print Dumper($Data);
用上面给出的通用工单连接器REST配置的例子,我们可以:
创建工单:在/Ticket路径上使用POST方法。
搜索工单:在/Ticket路径上使用GET方法。
更新工单:在/Ticket/{TicketID}路径上使用PATCH方法,{TicketID}是代表传输配置中:TicketID的模板。
获取工单:在/Ticket/{TicketID}路径上使用GET方法,{TicketID}是代表传输配置中:TicketID的模板。
cURL命令:
shell> curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket?UserLogin=agent&Password=123" -H "Content-Type: application/json" -d "{\"Ticket\":{\"Title\":\"REST Create Test\", \"Type\": \"Unclassified\", \"Queue\":\"Raw\",\"State\":\"open\",\"Priority\":\"3 normal\",\"CustomerUser\":\"customer\"},\"Article\":{\"Subject\":\"Rest Create Test\",\"Body\":\"This is only a test\",\"ContentType\":\"text/plain; charset=utf8\"}}" -X POST
响应:
{ "ArticleID":5484, "TicketNumber":"1001936", "TicketID":"1686" }
cURL命令:
curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/1686?UserLogin=agent&Password=123"
响应:
{ "Ticket": [ { "Age": 777, "PriorityID": 3, "ServiceID": "", "Type": "Unclassified", "Responsible": "root@localhost", "StateID": 4, "ResponsibleID": 1, "ChangeBy": 2, "EscalationTime": 0, "Changed": "2014-06-30 19:08:14", "OwnerID": 2, "RealTillTimeNotUsed": 0, "GroupID": 1, "Owner": "agent", "CustomerID": "OTRS", "TypeID": 1, "Created": "2014-06-30 19:08:12", "Priority": "3 normal", "UntilTime": 0, "EscalationUpdateTime": 0, "QueueID": 2, "Queue": "Raw", "State": "open", "Title": "REST Create Test", "CreateBy": 2, "TicketID": 1686, "StateType": "open", "EscalationResponseTime": 0, "UnlockTimeout": 0, "EscalationSolutionTime": 0, "LockID": 1, "TicketNumber": "1001936", "ArchiveFlag": "n", "Lock": "unlock", "CreateTimeUnix": 1404173292, "SLAID": "", "CustomerUserID": "customer" } ] }
cURL命令:
curl "http://localhost/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Ticket/1686?UserLogin=agent&Password=123" -H "Content-Type: application/json" -d "{\"Ticket\":{\"Queues\":\"Postmaster\"}}" -X PATCH
响应:
{ "TicketNumber":"1001936", "TicketID":"1686" }