Version 23.4.8843

• ArcScript
• 示例脚本
  • 使用事件输入
  • 使用运算器
  • 扩展示例脚本
• ArcScript 中的对象
  • 声明对象
  • 通过请求字符串传递对象
  • 选择属性值
  • 默认对象
• 命名对象
  • 脚本输入（_input）
  • 脚本输出（_out[n]）
  • HTTP 请求（_request）
  • HTTP 响应（_response）
  • HTTP 头部（_httpheaders）
  • HTTP Cookies（_cookies）
  • ASP.NET 会话（_session）
  • 知行之桥消息（_message）
    • 消息体
    • 添加跟踪消息头
    • 添加自定义标头
  • 映射上下文（_map）
  • 应用程序日志（_log）
  • 知行端口 (_connector)

ArcScript

ArcScript 是知行之桥中内置的一种基于 XML 的语言，可用于编写自定义处理逻辑。ArcScript 可以轻松地转换文件或消息，并与其它业务流程集成。知行之桥包含完整的示例脚本，用于发送电子邮件、执行批处理文件、处理文件等。可以从管理控制台将这些示例插入到脚本和事件中。

然而，ArcScript 也是一种高级编程语言，能够控制数据访问和处理的几乎每一个方面。可以使用关键字、属性、对象、运算器和对象集来编写脚本。

• 属性：名称-值中的名称部分，如 attribute=”地址”，value=”123 Pleasant Lane”。
  • ArcScript 中的属性也可以通过使用 # 字符代表的数组来表示，数组可以包含多个值, 每个值可以通过使用从1开始计数的索引来引用。
  • 举例来说, [myitem.myattribute#2] 将会指向myattribute 属性的第二个值。
• 对象: 一组相关的属性-值对，用于描述输入或输出。例如：

    Attribute="name" value="Bob"
    Attribute="address" value="123 Pleasant Lane"
    Attribute="phone" value="123-4567"
  

• 对象集：对象的列表：例如，一组客户的列表，包含客户地址和电话号码。
• 运算器：将对象作为输入并生成对象集作为输出的方法的通用名称。
• 关键字：ArcScript 语句，如 arc:set。

ArcScript 中包含了许多关键字，可以完成以下事情：

• 描述脚本的输入和输出。
• 使用高级编程结构，如 if／else 语句和 case 语句来控制执行流程。
• 调用运算器并定义自己的运算器。
• 创建和修改对象（运算器的输入）和对象集（运算器的结果）。
• 通过迭代运算器调用的对象来处理对象集。

示例脚本

ArcScript 是一种简单的、基于 XML 的语言，可用于事件中，实现强大的自动化功能。知行之桥包含用于自动化的常见操作（如发送电子邮件）的完整代码片段。在 Script 端口的设置选项卡或端口的“事件”选项卡上，单击插入片段并选择要执行的操作。必要的代码就会插入到光标处。

本节介绍了如何使用和扩展内含的代码片段来编写自定义处理逻辑。

使用事件输入

每个事件都提供了相关的输入，可以将其作为运算器的输入参数。输入参数由 info 部分的输入属性定义。

使用事件的预定义输入来处理发送或接收的文件，或发送包含任何错误信息的电子邮件。其它输入也是可用的。以下是接收后事件的可用输入。

<arc:info title="After Receive"  desc="This event is fired after receiving a file.">
  <input name="Filename"         desc="The name of the file that was sent." />
  <input name="FilePath"         desc="The path of the file that was received." />
  <input name="MessageId"        desc="The Id of the transmission." />
  <input name="ErrorMessage"     desc="If an error occurred, this will contain the error message." />
</arc:info>

使用运算器

使用内含的代码示例来调用一些内置运算器。下面的例子是在收到文件后发送电子邮件。要发送电子邮件，只需替换占位符的值即可：

<!-- Send Email -->
<arc:set attr="Subject"    value="Before Send"/>
<arc:set attr="Message"    value="File [Filename] was processed."/>
<arc:call op="appSendEmail"/>

扩展示例脚本

使用内含的代码示例将预定义的输入传入到运算器中，也可以传入特定于运算器的附加输入。例如，appSendEmail 运算器接收几个额外的输入，如正文、附件和 TLS／SSL 属性。可以使用 arc:set 关键字来提供这些值。

通过 arc:call 关键字，可以调用事件中的任何内置运算器，也可以调用 API。

使用其它 ArcScript 关键字来控制执行流程等。ArcScript 在计算上是完整的，它还具有许多增强功能，旨在使处理和自动化变得简单。请参阅[脚本] (./Scripting.html) 了解更多有关 ArcScript 语法及其功能的信息。

ArcScript 中的对象

对象集是由对象组成的，但在 ArcScript 中，对象本身的用途远不止于对象集的各个部分。它们也被用来表示运算器的输入。

声明对象

在 ArcScript 中，通过 arc:set 关键字来创建、命名和赋予属性值。

<arc:set item="input" attr="mask" value="*.txt" />

上面这行将名为 “input” 的对象上的 “mask” 属性设置为值 “*.txt”。在这种情况下，输入对象就像 ArcScript 中的一个变量。

然而，名为 input 的对象从未被声明。相反，当第一次尝试为它设置属性时，就会创建这个对象。在上面的例子中，如果输入对象还不存在，那么它就会被创建，并且 mask 属性会被设置。

通过请求字符串传递对象

作为显示的创建输入对象的替代，你可以通过请求字符串的方式传值。作为显式声明对象和将它们作为参数传递之间的区别的示例，请考虑以下声明对象的行，file，并将该项目传递给运算器以读取行：

<arc:set attr="file.file" value="[filepath]" />
<arc:call op="fileReadLine" in="file">

如果使用请求字符串，你可以用下面的语法：

<arc:call op="fileReadLine?file=[filePath | urlencode]">

注意这个方式要求使用 urlencode 来做 URL 转码。这个将避免任何因为值中的特殊字符引起的问题。

选择属性值

要引用一个属性，使用语法 item.attribute（例如，“input.mask”）。要查询一个属性值，将属性名用方括号包围起来([])。这将指示解释器想要评估字符串，而不是将其解释为字符串文字。

例如，以下代码片段：

<arc:set item="item1" attr="attr1" value="value1"/>
<arc:set item="item1" attr="attr2" value="item1.attr1"/>
<arc:set item="item1" attr="attr3" value="[item1.attr1]"/>

结果如下：

• item1.attr1 被分配给文字字符串值 “value1”。
• item1.attr2 被分配给文字字符串 “item1.attr1”。
• item1.attr3 被赋值为 “value1”，因为字符串 “[item1.attr1]” 在运行时被评估为 item1 的 attr1 属性。

注意，可以使用反斜杠来转义字符串中的方括号。

默认对象

在 ArcScript 的内部对象堆栈中，总有一个隐含的、未命名的对象，即默认对象。在以下两种情况下，为了使脚本更短，更容易编写，通常使用默认对象：

• 调用运算器：如果没有指定其它对象，默认对象就是默认传递给脚本所调用的运算器的对象。这意味着可以使用 arc:set 将属性写入默认的未命名对象，这些属性将作为输入传递给脚本中调用的下一个运算器。这是提供运算器所需参数的一种方式。
• 在运算器或脚本的输出中处理当前对象：如果没有为运算器的结果指定一个变量名，那么在调用运算器的 arc:call 块中，默认对象将引用运算器产生的当前对象。

只需省略 ArcScript 关键字的对象属性就可以来控制默认对象。

<arc:set attr="path" value="." />

命名对象

除了在脚本中声明的对象外，在脚本的作用域内还有一些内置的对象。在 ArcScript 中，内置对象或特殊对象是可用的，它们为访问 HTTP 请求、响应等部分提供了一个接口。这些特殊对象对于将 HTTP 请求中的输入映射到运算器输入非常有用。

下面的章节将详细介绍这些特殊对象。

脚本输入（_input）

脚本的输入可以从 _input 对象中读取。_input 对象包含了 URL 查询字符串中的变量和脚本执行时的 POST 数据。如果在 POST 数据中存在一个同名的变量，它将覆盖查询字符串中的值。

当从脚本中的默认对象中读取值时，就是从 _input 中读取值；同样，写到默认对象中的属性也会随着脚本的输入一起作为参数传递给运算器。只有在 info 块或脚本中定义的变量才会在 _input 对象中可用。

注意，在 arc:call 块中，_input 不再是默认对象，如果需要访问它，必须用名称来引用它。

脚本输出（_out[n]）

通过 arc:call 关键字产生的对象集中的当前对象可以通过默认对象或命名的特殊对象 “_outX” 来访问，其中 X 是 arc:call 关键字的嵌套级别。例如，如果在一个 arc:call 关键字里面，对象的名称将是 “_out1”。如果在三层嵌套的 arc:call 关键字里面，那么它的名字将是 “_out3”。

HTTP 请求（_request）

可以访问传递到 URL 查询字符串中的变量，POST 到脚本中的变量，以及作为 _request 对象中的属性集合的其它变量。要访问一个特定的属性集合，使用集合的名称作为要读取的属性的前缀。例如，[_request.qstring:name] 读取查询字符串中变量 “name” 的值，[_request.form:name] 读取表单数据中变量 “name” 的值。

HTTP 响应（_response）

响应对象允许脚本作者直接写入 HTTP 响应。可以在响应对象中设置下面列出的属性：

HTTP 头部（_httpheaders）

脚本和模板中的 _httpheaders 对象提供了对 HTTP 头部文件的简单访问。可以通过读取这个对象来读取 HTTP 请求头部。通过写入此对象，来写入传出的响应头部。例如，可以用下面的行来设置内容类型：

<arc:set  item="_httpheaders" attr="content-type" value="application/xml"/>

HTTP Cookies（_cookies）

可以使用 _cookies 对象在请求中检索 cookie，在响应中设置 cookie。具有多个 key／value 对的 cookie 被表示为与 cookie 的 key／value 对相对应的属性集合。Cookie 的名称在集合的每个属性前缀。

ASP.NET 会话（_session）

ASP.NET 会话变量在 ArcScript 中可以通过 _session 对象获得。存储在会话中的任何项都可以作为该对象的属性来访问。属性名代表了用于在会话中存储对象的 key。

知行之桥消息（_message）

当文件通过知行之桥工作流时，应用程序会向文件添加元数据；由此产生的原始文件和应用程序元数据的组合称为消息。元数据包括一个唯一的 ID（称为 MessageID），无论文件名是否有任何更改，它都能识别文件、处理过程中的失败和成功信息，以及在工作流中以编程方式推广的任何自定义元数据。

_message 对象提供了在脚本上下文中对这些元数据的访问（以及在可以解释脚本的端口字段中，如电子邮件发送端口中的主题字段）。通常，这是通过使用 _message 对象的 header:* 属性来实现的。

例如，当在知行之桥中处理文件时发生错误时，x-trapped-errordescription 头部会被添加到代表该文件的消息中。该头部存储了有关发生错误的信息，包括发生错误的端口 ID 和有关错误的调试信息。以下语法在脚本上下文中引用该头部：

[_message.header:x-trapped-errordescription]

消息体

如需访问消息体，可以使用 _message 对象的 __body__属性，比如：

[_message.body]

这里用字符串来返回消息体。

添加跟踪消息头

要向消息添加跟踪消息头，请使用 _message 项的 trackedheader 属性，如下所示：

<arc：set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.trackedheader:myHeaderName" value="myValue" />
<arc:push item="outfile" />

添加自定义标头

要向文件添加自定义标头，请设置端口推出的文件项的 Header:header_name 属性。 为清楚起见，从一个脚本开始，该脚本推送一个输出文件，该输出文件是输入文件的未修改版本：

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:push item="outfile" />

[FilePath] 变量解析为输入文件的完整路径（和文件名），因此该脚本只是使输出文件与输入文件相同。

此脚本的以下添加在推送文件之前将自定义标头添加到文件中：

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.Header:myHeaderName" value="myValue" />
<arc:push item="outfile" />

你可以通过导航到 设置 > 高级 页面的 高级设置 部分中的 跟踪标题 字段，并添加标题名称，使自定义标题可在日志中搜索。

映射上下文（_map）

_map 是 XML Map 端口中的一个特殊对象。在 _map 对象中设置的属性总是在之后的映射中可用（即这些属性不会被清除，而且 _map 对象永远不会超出作用域）。

_map 对象可以用来存储在映射中某一点计算出来的信息，并在映射的后面引用。例如，涉及 EDI 文档的映射可能需要计算文档中行项目的数量，然后在文档末尾的 CTT 段中包含这个计数值。行项目计数可以被计算并存储为一个 _map 对象的属性，这个属性可以在 CTT 段映射中被引用。

应用程序日志（_log）

_log 对象是进入知行之桥的应用日志的一个 hook，将这个对象的 info 属性设置为字符串，就会在应用日志中出现这个字符串：

<arc:set attr="_log.info" value="this string will appear in the Application Log when the script executes" />

这个属性可以在同一个脚本中多次设置，以将多个消息记录到应用程序日志中。属性值不需要被清除或追加，只需像上面的例子一样设置属性值，就会记录指定的值。

知行端口 (_connector)

_connector 对象提供访问当前端口属性参数的能力。注意，使用这个对象需要端口的脚本上下文；这通常在端口对应的事件中可用，和一些个别端口提供的运行 ArcScript 的能力。

可用的属性和端口配置文件夹下的 port.cfg 文件对应，可以用如下语法访问：

[_connector.propertyName]