intra-mart Accel Platform IM-MessageHub プログラミングガイド 第3版 2021-04-01

4.3. テンプレートを定義する

次に、配信するメッセージのテンプレートを定義します。
ここでは、テンプレートの仕様や規約、および、テンプレートのフォーマットについて説明します。

4.3.1. テンプレートファイル

テンプレートファイルとは、 IM-MessageHub で利用するテンプレート情報を定義した XML ファイルです。
テンプレートファイルを作成する上での規約、および、仕様は以下の通りです。

4.3.1.1. ファイル名

テンプレートファイル名の命名規約は以下の通りです。

<配信先メディアID>-<イベントID>_<ロケール>.xml

テンプレートファイル名は、配信先メディアやイベントによって決定されます。
動的に決定が行われる箇所(<~>によって囲まれている部分)についての詳細は以下の通りです。
表:動的に決定が行われる箇所の詳細
配信先メディアID
テンプレートファイルを適用する「 配信先メディア 」の ID を指定します。
intra-mart Accel Platform で提供している配信先メディアID の詳細については、「 配信先メディア一覧 」を参照してください。

今回のサンプルでは、 IMBox の ApplicationBox 向けのテンプレートを作成します。配信先メディアID は immh.imbox.appbox です。
イベントID
テンプレートファイルを適用するイベントの ID を指定します。
イベントIDは、適用するイベントクラスの FQCN(完全修飾クラス名)です。

今回のサンプルでは、 sample.message_hub.event.SampleMessageEvent がイベントID になります。
ロケール
テンプレートファイルのロケールを指定します。
言語ごとにテンプレートファイルを作成することで、多言語に対応したメッセージを配信することが可能です。
ロケールは <language>_<country>_<variant> 形式で指定します。

今回のサンプルでは、日本語( ja )、英語( en )、中国語( zh_CN )、および、ロケール指定なしを定義します。
テンプレートファイルは、これらの情報を省略して命名することも可能です。
詳しくは「 テンプレートファイルの解決順 」を参照してください。

コラム

メディア共通テンプレートについて

テンプレートファイル名の「配信先メディアID」を省略した場合、そのテンプレートは、全ての配信先メディアで共通的に利用されるテンプレートとなります。
これを「メディア共通テンプレート」と呼びます。

新たにテンプレートを定義する際は、メディア共通テンプレートも作成してください。
これにより、システムに新しい配信先メディアが増えた場合でも、新たにテンプレートファイルを作成する必要がなくなります。

メディア共通テンプレートを作成する際の注意点は以下の通りです。
  • 既存の配信先メディアで必要となるヘッダー情報を全て定義してください。
    必須ヘッダーの詳細は「 必須ヘッダ情報 」を参照してください。
  • 利用する言語分のテンプレートファイルを作成してください。
  • どの配信先メディアに配信されても違和感の無い内容にしてください。簡潔で短い内容であることを推奨します。

4.3.1.2. 配置場所

IM-MessageHub は以下のディレクトリをルートディレクトリとして、テンプレートファイルを管理します。

%PUBLIC_STORAGE_PATH%/im_template/

作成したテンプレートファイルは、このルートディレクトリ配下に配置してください。

なお、 IM-MessageHub はルートディレクトリ配下のサブディレクトリを含めて管理対象としています。
新規に作成したテンプレートファイルは、 intra-mart Accel Platform 標準で同梱されるテンプレートファイルと区別するため、専用のディレクトリを作成することを推奨します。
今回のサンプルで利用するテンプレートファイルの配置場所は以下の通りです。
いずれも、 %PUBLIC_STORAGE_PATH%/im_template/sample/ ディレクトリ直下に配置しています。
  • IMBox の ApplicationBox 向けテンプレートファイル

    • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent.xml (ロケール指定なし)
    • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_ja.xml (日本語)
    • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_en.xml (英語)
    • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_zh_CN.xml (中国語)
  • メディア共通テンプレート

    • sample.message_hub.event.SampleMessageEvent.xml (ロケール指定なし)
    • sample.message_hub.event.SampleMessageEvent_ja.xml (日本語)
    • sample.message_hub.event.SampleMessageEvent_en.xml (英語)
    • sample.message_hub.event.SampleMessageEvent_zh_CN.xml (中国語)

4.3.1.3. テンプレートファイルの解決順

IM-MessageHub は、イベント、配信先メディア、および、対象となるロケールを元に利用するテンプレートファイルを解決します。
テンプレートファイルの解決順は以下の通りです。
  1. 「配信先メディアID」、「イベントID」、「ロケール」が全て一致するテンプレートファイル
  2. 「配信先メディアID」、「イベントID」が一致するテンプレートファイル
  3. 「イベントID」、「ロケール」が一致するテンプレートファイル
  4. 「イベントID」が一致するテンプレートファイル
ロケールに関しては更に以下の順で評価されます。
  1. language 」「 country 」「 variant 」が全て一致
  2. language 」「 country 」が一致
  3. language 」が一致

コラム

テンプレートファイルが解決できなかった場合

上記手順を通してテンプレートファイルの解決が行えなかった場合、 IM-MessageHub ではデフォルトテンプレートファイルを利用します。
デフォルトテンプレートファイルが配置されているパスは以下の通りです。

%PUBLIC_STORAGE_PATH%/im_template/default_template.xml
例として、イベントに SampleMessageEvent 、配信先メディアIDに immh.imbox.appbox 、ロケールに日本語( ja )が指定された場合、IM-MessageHub は以下の順番でテンプレートファイルの解決を行います。
  1. immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_ja.xml
  2. immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent.xml
  3. sample.message_hub.event.SampleMessageEvent_ja.xml
  4. sample.message_hub.event.SampleMessageEvent.xml
  5. default_template.xml (デフォルトテンプレートファイル)

4.3.2. テンプレートフォーマット

テンプレートを作成するためのフォーマットの詳細は以下の通りです。

4.3.2.1. 本文

配信を行うメッセージと、その付帯情報を定義します。
テンプレートの定義例は以下の通りです。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?xml version="1.0" encoding="UTF-8"?>
<template-data xmlns="http://www.intra-mart.co.jp/system/template/template-data" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.intra-mart.co.jp/system/template/template-data ../schema/template-data.xsd">
    <headers>
        <header name="subject"          value="Message Title" /> 
        <header name="url"              value="http://www.intra-mart.jp/" />
        <header name="application_info" value="Application-Information" />
    </headers>
    <body>
        Main Message Contents.
    </body>
</template-data>
設定が必要なタグとその説明は、以下の通りです。
  • headers タグ

    テンプレートに関するヘッダー情報をまとめて定義するための親タグです。
    headers タグの内部には、 header タグを複数定義することが出来ます。

  • header タグ

    テンプレートに関するヘッダー情報を定義します。

    header タグは属性として namevalue を持ち、name にはヘッダー名を、 value にはヘッダー名に対応する値を設定します。
    intra-mart Accel Platform が提供している配信先メディアによっては、必ず設定しなければならないヘッダー情報が存在します。
    詳しくは「 必須ヘッダ情報 」を参照してください。

  • body タグ

    配信を行うメッセージ本文を定義します。

4.3.2.2. 置換処理(プレースホルダ)

IM-MessageHub のテンプレートは、プレースホルダを利用した置換処理に対応しています。
テンプレートファイルの例は以下の通りです。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8"?>
<template-data xmlns="http://www.intra-mart.co.jp/system/template/template-data" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://www.intra-mart.co.jp/system/template/template-data ../schema/template-data.xsd">
    <headers>
        <header name="application_placeholder" value="${applicationPlaceholder}" />
    </headers>
    <body>
        Main Message Contents.
        
        --------------------------------
        
        Replace Value : ${replaceValue}
    </body>
</template-data>
  • プレースホルダは、 ${<プレースホルダ名>} というフォーマットで定義します。
    プレースホルダ名は、英数字大文字小文字のキャメルケースで定義する事を推奨します。
  • テンプレートファイルに指定されたプレースホルダは、メッセージに指定された同名の属性に置換されます。
    例えば、メッセージの作成時に Message#setAttribute(” foo ”, ” bar ”) と設定された場合、テンプレートファイル上の ${ foo } は bar に置換されます。
    詳しくは「 置換処理の対応 」を参照してください。
  • テンプレートファイル上でプレースホルダが設定可能な箇所は以下の通りです。
    • header タグの value 属性内
    • body タグ内

警告

プレースホルダ名に「.(ドット)」を含めないでください。
今後のアップデートにおいて、設定したプレースホルダが正しく動作しなくなる可能性があります。

4.3.3. 完成したテンプレートファイルのサンプル

今回は、以下のようなテンプレートファイルを作成します。
(メディア共通テンプレートのサンプルは割愛します)
  • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_ja.xml (日本語)
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <?xml version="1.0" encoding="UTF-8"?>
    <template-data xmlns="http://www.intra-mart.co.jp/system/template/template-data" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.intra-mart.co.jp/system/template/template-data ../schema/template-data.xsd">
    <headers>
        <header name="subject" value="IM-MessageHub プログラミングガイド サンプル"/>
        <header name="url"     value="${url}"/>
    </headers>
    <body>
    サンプルアプリケーションからの通知です。
    通知処理日時:${sendDate}
    </body>
    </template-data>
    
  • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_en.xml (英語)
    および、 immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent.xml (ロケール指定なし)
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <?xml version="1.0" encoding="UTF-8"?>
    <template-data xmlns="http://www.intra-mart.co.jp/system/template/template-data" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.intra-mart.co.jp/system/template/template-data ../schema/template-data.xsd">
    <headers>
        <header name="subject" value="IM-MessageHub Programming Guide Sample"/>
        <header name="url"     value="${url}"/>
    </headers>
    <body>
    Notification from the Sample Application.
    Notification processing Date : ${sendDate}
    </body>
    </template-data>
    
  • immh.imbox.appbox-sample.message_hub.event.SampleMessageEvent_zh_CN.xml (中国語)
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <?xml version="1.0" encoding="UTF-8"?>
    <template-data xmlns="http://www.intra-mart.co.jp/system/template/template-data" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.intra-mart.co.jp/system/template/template-data ../schema/template-data.xsd">
    <headers>
        <header name="subject" value="IM-MessageHub 编程指南 样本"/>
        <header name="url"     value="${url}"/>
    </headers>
    <body>
    通知从示例应用程序。
    通知处理日期: ${sendDate}
    </body>
    </template-data>