Introduction to ArcScript

Version 21.0.8222


Introduction to ArcScript


ArcScript

ArcScript はArcESB に含まれているXML ベースの言語で、カスタム処理ロジックの記述に使用できます。ArcScript により、簡単にファイルやメッセージを変換し、他のビジネスプロセスと統合することができます。 Arc includes complete Example Scripts for sending emails, executing batch files, working with files, and more.これらのサンプルを、管理コンソールからお客様のスクリプトおよびイベントに挿入することができます。

ArcScript は、データアクセスおよびプロセッシングのあらゆる側面の管理を可能にするハイレベルなプログラミング言語です。スクリプトを書く際には、キーワード、アトリビュート、アイテム、オペレーション、およびフィードを使います。

  • アトリビュート: name-value ペアのname 部分で、attribute=”address”, value=”123 Pleasant Lane” のように使われます。
    • Attributes in ArcScript can also be denoted as an array by using the # character. This means that the array can contain more than one value, where each value may be referred to using 1-based indexing.
    • For example, [myitem.myattribute#2] would refer to the second value in the myattribute attribute.
  • アイテム: Attribute-value ペアの関連するグループで、インプットとアウトプットを説明します。例:
      Attribute="name" value="Bob"
      Attribute="address" value="123 Pleasant Lane"
      Attribute="phone" value="123-4567"
    
  • フィード: アイテムのリスト。例えば、アドレスと電話番号を含む顧客のリストなど。
  • オペレーション: アイテムをインプットとして受け、フィードをアウトプットとして生成するメソッドの一般名。
  • キーワード: arc:set のようなArcScript ステートメント。

ArcScript は多様なキーワードを持ち、次のようなことが可能です:

  • スクリプトのインプットとアウトプットを説明する。
  • 実行フローを管理するためにIf/else 構文やcase 構文などのハイレベルなプログラミング構成を使う。
  • オペレーションを呼び出し、カスタムオペレーションを定義する。
  • アイテム、オペレーションのインプット、フィード、オペレーションの結果を作成し、変更する。
  • アイテムの反復によりオペレーション呼び出しからの結果フィードを処理する。

サンプルスクリプト

ArcScript は、パワフルな自動化機能を可能にするためにイベントで使用できるシンプルなXML ベースの言語です。Arc includes complete code snippets for automating common actions, such as sending an email.スクリプトコネクタの[設定] タブまたはコネクタの[イベント]タブで、[スニペットを挿入]をクリックして、実行するアクションを選択します。必要なコードがカーソルに挿入されています。

このセクションでは、付属のコードスニペットを使用および拡張してカスタム処理ロジックを記述する方法について説明します。

イベントインプットの使用

各イベントには、操作のインプットパラメータとして使用できる関連インプットがあります。インプットパラメータは、info セクションのインプット属性によって定義されています。

イベントの定義済みインプットを使用して、送受信されたファイルを処理するか、エラーメッセージを含むE メールを送信します。他のインプットも利用可能です。以下は、After Receive イベントで利用可能なインプットです。

<arc:info title="After Receive"  desc="このイベントはファイルを受信した後に発生します。">
  <input name="Filename"         desc="送信されたファイルの名前。" />
  <input name="FilePath"         desc="受信されたファイルのパス。" />
  <input name="MessageId"        desc="トランスミッションのId。" />
  <input name="ErrorMessage"     desc="エラーが発生した場合は、エラーメッセージが表示されます。" />
</arc:info>

オペレーションの使用

付属のコード例を使用して、組み込み操作のいくつかを呼び出します。次の例では、ファイルを受信した後にE メールを送信します。E メールを送信するには、単にプレースホルダーの値を置き替えます。

<!-- E メールを送信 -->
<arc:set attr="Subject"    value="Before Send"/>
<arc:set attr="Message"    value="File [Filename] was processed."/>
<arc:call op="appSendEmail"/>

サンプルスクリプトの拡張

付属のコード例を使用して、定義済みのインプットをオペレーションに渡します。オペレーションに固有の追加のインプットを渡すこともできます。例えば、appSendEmail オペレーションは、本文、添付ファイル、SSL/TLS プロパティなど、いくつかの追加インプットを受け付けます。これらの値は、arc:set キーワードで指定できます。

arc:call キーワードを使用すると、イベント内の任意の組み込み操作を呼び出したり、API を呼び出すこともできます。

実行フローなどを制御するには、他のArcScript キーワードを使用してください。ArcScript is computationally complete.また、処理と自動化を簡単にするためにデザインされた多くの機能強化もあります。ArcScript の構文とその機能について詳しくは、スクリプティング を参照してください。

ArcScript のアイテム

フィードは、アイテムにより成り立ちますが、ArcScript ではアイテムはフィードの部品という以上の働きをします。アイテムは、オペレーションにインプットを提供するために使われることもあります。

アイテムの宣言

ArcScript では、アイテムは、arc:set キーワードを通じて作成され、名付けられ、アトリビュート値を与えられます。

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

このラインは、input という名前のアイテムの、mask アトリビュートに*text という値をセットします。この場合、インプットアイテムはArcScript の変数の働きをします。

ただし、input という名前のアイテムは宣言されていません。その代わりに、初回にアトリビュートをセットしようとすると、そのアイテムが生成されます。上の例では、インプットアイテムが存在していない場合、そのアイテムが生成され、mask アトリビュートがセットされます。

アトリビュート値の選択

アトリビュートを参照するには、構文_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 では、デフォルトアイテムという、アイテムの層の中に黙示的で名付けられていないアイテムがあります。次の2つのケースでは、デフォルトアイテムは共通してスクリプトをより短く、簡単に書くために使われています。

  • オペレーションの呼び出し:デフォルトアイテムは、他に指定されたアイテムがない場合に、デフォルトで呼び出されたオペレーションに渡されるアイテムです。これはつまり、arc:set を使って、デフォルトの名付けられていないアイテムのアトリビュートを書いて、そのアトリビュートがスクリプト内の次のオペレーションのインプットとして渡されることを意味します。これは、オペレーションに必要なパラメータを提供する一つの方法です。
  • オペレーションまたはスクリプトのアウトプット内の現在のアイテムを処理:オペレーションの結果の変数名を指定しなかった場合、オペレーションを起動するarc:call ブロックの内部でデフォルトアイテムはオペレーションで生成された現在のアイテムを参照します。

ArcScript のキーワードのアイテムアトリビュートを単に省略することでデフォルトアイテムを操作する:

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

名前付きアイテム

スクリプト内で宣言されたアイテムに加えて、スクリプトのスコープでは、いくつかのビルトインアイテムが利用可能です。ArcScript では、ビルトイン、もしくは特殊なアイテムが利用可能で、HTTP リクエスト、レスポンスの部分にアクセスするインターフェースを提供します。特殊なアイテムはHTTP リクエストのインプットを処理のインプットにマッピングするために役立ちます。

以下のセクションで、特殊なアイテムについて説明します。

スクリプトインプット (_input)

スクリプトへのインプットは _input アイテムから参照されます。_input アイテムは、スクリプトが実行される際のURL クエリ文字列およびPOST データの中に見出せる変数を含みます。もし、POST データに同じ名前の変数が存在する場合には、クエリ文字列の値を上書きします。

スクリプト内のデフォルトアイテムから値を読む場合、_input から値を読んでいます。同様に、デフォルトアイテムに書き込みたいアトリビュートは、インプットスクリプトと共にオペレーションのパラメータとして渡されます。情報ブロック、もしくはスクリプト内に定義された変数だけが_input アイテム内では有効です。

arc:call ブロックの内部では、_input はデフォルトアイテムではなく、アクセスするためには名前を参照しなければなりません。

スクリプトアウトプット (_out[n])

arc:call キーワードにより生成されたフィード内の現在のアイテムは、デフォルトアイテムもしくは名前を指定された特殊アイテム”_outX” を通じてアクセスすることができます。X はarc:call キーワードのネスティングのレベルです。例えば、単一のarc:call キーワードの内部の場合、アイテム名は”_out1” です。arc:call キーワードの3つのネストレベルの内部の場合、”_out3” となります。

HTTP リクエスト (_request)

URL クエリ文字列に渡された変数、POST されたスクリプト、および_request アイテム内のアトリビュートのコレクションの変数にアクセスできます。アトリビュートの指定されたコレクションにアクセスするには、読みたいアトリビュートの接頭辞としてコレクションを使います。例えば、[_request.qstring:name] はクエリ文字列内の”name” 変数の値を読み、[_request.form:name] はフォームデータの”name” 変数の値を読みます。

q[uery]string:* クエリ文字列パラメータにアクセス。
form:* フォームデータ内の変数の値にアクセス。
server:* サーバー変数の値にアクセス。
body リクエストのraw コンテンツ(ボディ)にアクセス。
bodybase64 Access the base64-encoded contents (body) of the request.
auth:* ユーザーの認証情報にアクセス。ユーザーが[_request.auth:isauthenticated] にアクセス認証されているかを確かめます。
other:* Access other information about the request.[_request.other:applicationpath] でアプリケーションパスを取得します。

HTTP レスポンス (_response)

レスポンスアイテムは、スクリプトの書き手がHTTP レスポンスに対して直接書き込むことを許容します。レスポンスアイテム内に、以下のリストのアトリビュートをセットすることができます。

cookie:* レスポンスにcookie をセットする。アトリビュート名は、”cookie” を接頭するcookie 名で、cookie の値がアトリビュートの名前となります。
writefile レスポンスに指定されたパスの内容を書く。
redirect クライアントのブラウザにリダイレクトヘッダーを送る。これはブラウザを別のURL にリダイレクトするために使われます。
statuscode レスポンスのHTTP ステータスコードをセットする。
statusdescription レスポンスのHTTP ステータス説明をセットする。

HTTP ヘッダー (_httpheaders)

_httpheaders アイテムは、スクリプトおよびテンプレート内でHTTP ヘッダーに簡単にアクセスすることを可能にします。アイテムを読むことで、HTTP リクエストヘッダーを読むことができます。アイテムに書き込むことで、outgoing レスポンスヘッダーに対して書き込むことができます。必要な情報は、以下のようにしてライン付きのコンテンツタイプをセットすることができます。

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

HTTP クッキー (_cookies)

_cookies アイテムを使って、リクエスト内でcookie を取得したり、レスポンス内でcookie をセットすることができます。複数のkey/value ペアのcookie はcookie のkey/value ペアに対応するアトリビュートのコレクションとして表されます。cookie 名は、それぞれのコレクションのアトリビュートで接頭されます。

ASP. NET セッション (_session)

ASP.NET セッション変数は、ArcScript では、_session アイテム経由で利用可能です。セッション内に保存されたオブジェクトは、このアイテムのアトリビュートとしてアクセスできます。アトリビュート名は、セッション内でオブジェクトを保存する際のキーとなります。

Arc Message (_message)

When a file passes through an Arc workflow, the application adds metadata to the file. The resulting combination of the original file and application metadata is called a message.

The _message item provides access to the body and metadata of a message in scripting contexts (and in connector fields that can interpret scripting, such as the Subject field in the Email Send Connector).

Metadata

The message metadata includes:

  • A unique ID (called a MessageID) that identifies the file regardless of any changes to the filename
  • Information about failures and successes during processing
  • Any custom metadata promoted programmatically in the Flow

To access message metadata, use the header:* attribute of the _message item. For example, when an error occurs while processing a file in Arc, the x-trapped-errordescription header is added to the message that represents that file. This header stores information about the error that occurred, including the ConnectorID where the error occurred and debugging information about the error. The following syntax references this header within a scripting context:

[_message.header:x-trapped-errordescription]

Body

To access the body of a message, use the body attribute of the _message item, as shown below:

[_message.body]

This returns the body of the message as a string.

Mapping Context (_map)

The _map item is a special item available in the XML Map Connector. Attributes set in the _map item are always available later in the mapping (i.e. these attributes are not cleared and the _map item is never out of scope).

The _map item is useful for storing information that is calculated at one point in the mapping and referenced later in the mapping. For example, a mapping involving an EDI document may need to count the number of Line Items in the document, and then include this count value in a CTT segment at the end of the document. The Line Item count can be calculated and stored as an attribute of the _map item, then that attribute can be referenced within the CTT segment mapping.

アプリケーションログ (_log)

The _log item is a hook into Arc’s Application Log. Setting the info attribute of this item to a string causes that string to appear in the Application Log.例:

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

This attribute can be set multiple times within the same script to log multiple messages to the Application Log. The attribute value does not need to be cleared or appended, simply setting the attribute value like the above example will cause the specified value to be logged.

Arc Connector (_connector)

The _connector item provides access to the fields/properties of the current connector. Note that using this item requires a scripting context within the connector; this is always available via the events of any connector, and some connectors can also evaluate ArcScript within special configurable fields.

The available properties are the same as the values stored in the port.cfg file within the connector’s folder, and should be accessed using the following syntax:

[_connector.propertyName]