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

6.6. メールテンプレートの利用

IM-MessageHub では、通常のテンプレートファイル以外にメールモジュールで利用可能なメールテンプレートを扱うことが可能です。具体的には、MailTemplateクラス で利用可能なメールテンプレートを扱うことができます。

コラム

「メールモジュール」の詳細は以下の通りです。
モジュール名 メールモジュール(標準機能/基盤機能)
モジュールID jp.co.intra_mart.im_javamail
この章では、IM-MessageHub でメールテンプレートを利用する方法を説明します。

6.6.1. メールテンプレートファイル

メールテンプレートファイルとは、メールモジュールで利用するテンプレート情報を定義した XML ファイルです。
メールテンプレートファイルを作成する上での規約、および、基本的な記述方法は以下の通りです。

6.6.1.1. ファイル名

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

<テンプレート名>_<ロケール>.xml

ファイル名を構成する要素( <~> によって囲まれている部分)の詳細は以下の通りです。
表:構成する要素の詳細
テンプレート名
メールテンプレートを表す任意の名称を指定します。
ロケール
メールテンプレートファイルのロケールを指定します。
言語ごとにメールテンプレートファイルを作成することで、多言語に対応することが可能です。

ロケールは <language>_<country>_<variant> 形式で指定します。

6.6.1.2. 配置場所

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

%CONTEXT_PATH%/WEB-INF/conf/mail_template/

作成したメールテンプレートファイルは、このルートディレクトリ配下に配置してください。
なお、メールモジュールはルートディレクトリ配下のサブフォルダを含めて管理対象としています。

新規に作成したメールテンプレートファイルを配置する際には intra-mart Accel Platform 標準で同梱されているメールテンプレートファイルと区別するために専用のフォルダを作成することを推奨します。

6.6.1.3. メールテンプレートのテンプレートフォーマット

メールテンプレートの作成例は以下の通りです。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?xml version="1.0" encoding="UTF-8"?>
<mail-template xmlns="http://www.intra-mart.co.jp/system/mail/template" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.intra-mart.co.jp/system/mail/template ../../../schema/mail-template.xsd ">
    <headers>
        <header name="Organization" value="IM-MessageHub Sample" />
    </headers>
    <from address="sekine@intra-mart.jp" personal="SEKINE" />
    <replyTo>
        <mail address="maruyama@intra-mart.jp" personal="MARUYAMA"/>
    </replyTo>
    <to>
        <mail address="aoyagi@intra-mart.jp" personal="AOYAGI" />
    </to>
    <cc>
        <mail address="ueda@intra-mart.jp" personal="UEDA_CC"/>
    </cc>
    <bcc>
        <mail address="ueda@intra-mart.jp" personal="UEDA_BCC"/>
    </bcc>
    <subject>Mail Title</subject>
    <body>
        Main Body Contents
    </body>
</mail-template>
表:設定が必要なタグとその詳細
タグ名 説明
headers
送信するメールに指定するメールヘッダー情報をまとめて定義するための親タグです。
headers タグの内部には、 header タグを複数定義することが出来ます。
header
送信するメールに指定するメールヘッダー情報を定義します。
header タグは属性として namevalue を持ち、 name にはメールヘッダー名を、 value にはメールヘッダーに対応する値を設定します。
from
差出人アドレスを定義します。
from タグは属性として addresspersonal を持ち、 address には差出人のアドレスを、 personal には差出人の表示名を設定します。
replyTo
返信先アドレスをまとめて定義するための親タグです。
replyTo タグの内部には、 mail タグを複数定義することが出来ます。
to
宛先アドレスをまとめて定義するための親タグです。
to タグの内部には、 mail タグを複数定義することが出来ます。
cc
カーボンコピー先のアドレスをまとめて定義するための親タグです。
cc タグの内部には、 mail タグを複数定義することが出来ます。
bc
ブラインドカーボンコピー先のアドレスをまとめて定義するための親タグです。
bcc タグの内部には、 mail タグを複数定義することが出来ます。
mail
メールアドレス情報を定義します。
mail タグは属性として、 addresspersonal を持ち、address にはアドレスを、 personal には表示名を設定します。
subject 送信するメールの件名を定義します。
body 送信するメールの本文を定義します。

注意

タグの定義順について

メールテンプレートで利用するタグには定義順が設定されています。
以下の順序で定義してください。
  1. headers
  2. from
  3. replyTo
  4. to
  5. cc
  6. bcc
  7. subject
  8. body

6.6.2. メールテンプレート用アノテーション

メールテンプレートを利用するには、Event クラスにメールテンプレートの情報をアノテーションで付加する必要があります。
  • アノテーション
    • jp.co.intra_mart.foundation.template.annotation.Template
  • 引数
    • mediaId
      • immh.im_mail.legacy を指定してください。
    • path
      • テンプレートファイルのパスを <%CONTEXT_PATH%/WEB-INF/ conf/mail_template > からの相対パスで指定してください。
メールテンプレートを利用するイベントの作成例は以下の通りです。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
package sample.message_hub.event;

import jp.co.intra_mart.foundation.message_hub.model.Event;
import jp.co.intra_mart.foundation.template.annotation.Template;

@Template(mediaId="immh.im_mail.legacy", path="jp.co.intra_mart/sample/mailtemplate")
public class SampleLegacyMailEvent extends Event {

	private static final long serialVersionUID = -8837862755292447983L;

}

6.6.3. メッセージの作成

メールテンプレートを利用したメッセージの作成方法は、「 IM-MessageHub を利用してメッセージを配信する 」で説明したメッセージの作成方法と変わりません。
ここでは、メール配信に関する詳細な設定方法について説明します。

6.6.3.1. Cc、Bcc の設定方法

IM-MessageHub では、メール配信を行う際の宛先メールアドレスは To として扱われます。
Cc、Bcc として扱う場合は、アドレス情報に属性を設定します。
表:属性名と属性値
属性名 属性値
im_mail.cc
メールアドレスを Cc として扱う場合、この属性値に 文字列 true を設定してください。
im_mail.bcc
メールアドレスを Bcc として扱う場合、この属性値に 文字列 true を設定してください。
宛先メールアドレスを Cc、Bcc として扱うサンプルは以下の通りです。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
package sample.message_hub.create;

import java.util.ArrayList;
import java.util.List;

import jp.co.intra_mart.foundation.context.Contexts;
import jp.co.intra_mart.foundation.context.model.AccountContext;
import jp.co.intra_mart.foundation.message_hub.mail.delivery.MailMessageDelivererConstants;
import jp.co.intra_mart.foundation.message_hub.model.Address;
import jp.co.intra_mart.foundation.message_hub.model.Event;
import jp.co.intra_mart.foundation.message_hub.model.Message;
import jp.co.intra_mart.foundation.message_hub.model.UserAddress;
import sample.message_hub.event.SampleLegacyMailEvent;

public class SampleLegacyMailCreator {

    /**
     * メッセージを作成します。
     */
    public static Message create() {

        // イベントの作成(メールテンプレート用のイベントを設定)
        final Event event = new SampleLegacyMailEvent();
        
        // 送信元アドレスの作成
        // 今回、送信元アドレスはアカウントコンテキスから取得しています。
        AccountContext context = Contexts.get(AccountContext.class);
        final Address fromAddress = new UserAddress(context.getUserCd());
        
        // 宛先アドレスの作成
        final List<Address> toAddressList = new ArrayList<Address>();

        // To設定
        toAddressList.add(new UserAddress("aoyagi")); 

        // Cc設定
        Address ccAddress = new UserAddress("ueda");
        ccAddress.setAttribute(MailMessageDelivererConstants.ATTRIBUTE_NAME_FOR_CC, Boolean.TRUE.toString()); // Cc設定用パラメータ
        toAddressList.add(ccAddress); 

        // Bcc設定
        Address bccAddress = new UserAddress("ueda");
        bccAddress.setAttribute(MailMessageDelivererConstants.ATTRIBUTE_NAME_FOR_BCC, Boolean.TRUE.toString()); // Bcc設定用パラメータ
        toAddressList.add(bccAddress);      
        
        // メッセージの作成
        final Message message = new Message(event, fromAddress, toAddressList);
        // ... message属性の設定は省略します ...
        
        // 作成したメッセージを返します。
        return message;
    }
}

コラム

6.6.4. メールアドレス解決の拡張

IM-MessageHub では、メール配信を行う際に、宛先、および、送信元のメールアドレス解決を行います。
この解決は、以下のインタフェースの実装が行います。
表:提供インタフェース一覧
インタフェース 説明
ToMailAddressResolver 配信メッセージに指定された宛先のメールアドレスを解決します。
FromMailAddressResolver 配信メッセージに指定された送信元のメールアドレスを解決します。
パッケージ名は、いずれも jp.co.intra_mart.foundation.message_hub.mail.delivery です。
例えば、このインタフェースを実装することにより以下を実現することができます。
  • アプリケーションがメールアドレス 1 と 2 に送るためのチェックボックスを用意し、その設定値を元にメールアドレスを解決する。
  • 別のシステムで管理されているメールアドレスを利用する。
各インタフェースの詳細は、APIドキュメントを参照してください。

6.6.4.1. 拡張例

ToMailAddressResolver、および、FromMailAddressResolver インタフェースの実装は、 ServiceLoaderUtil#loadPriority(Class) を利用して順番に実行されます。
インタフェースの実装を有効化するために以下を行ってください。
  • 「プロバイダ構成ファイル」を配置してください。
    (詳しくは、 APIドキュメント「 java.util.ServiceLoader 」を参照してください)
  • 実装クラスに 優先度 ( @Priority ) を設定してください。
    (詳しくは、APIドキュメント「 ServiceLoaderUtil 」、および、「 @Priority 」を参照してください)
ここでは、ToMailAddressResolver インタフェースの実装例、および、実装の有効化方法について説明します。
  • 実装例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
package sample.message_hub.address.resolver;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.Locale;

import jp.co.intra_mart.common.annotation.Priority;
import jp.co.intra_mart.foundation.mail.javamail.model.MailAddress;
import jp.co.intra_mart.foundation.message_hub.mail.delivery.ToMailAddressResolver;
import jp.co.intra_mart.foundation.message_hub.model.Event;
import sample.message_hub.event.SampleLegacyMailEvent;

/**
 * 宛先に対するメールアドレス解決用インターフェースのサンプル実装
 */
@Priority(value = 500)
public class SampleToMailAddressResolver implements ToMailAddressResolver {

    @Override
    public List<MailAddress> getMailAddress(final String userCd, final Date baseDate, final Locale locale) {

        // 独自のアプリケーションが管理する情報から、メールアドレスを取得する。
        final List<String> addressList = getAddressListByApplicationMaintainDB(userCd, baseDate);

        final List<MailAddress> result = new ArrayList<MailAddress>();
        for (final String address : addressList) {
            result.add(new MailAddress() {
                @Override
                public String getAddress() {
                    return address;
                }

                @Override
                public String getPersonal() {
                    return userCd; // ユーザコードで代替
                }
            });
        }

        return result;
    }

    @Override
    public boolean isSupported(final Event event) {
        // 今回作成したサンプルイベントの場合のみ適用
        return SampleLegacyMailEvent.class.isInstance(event);
    }

    private List<String> getAddressListByApplicationMaintainDB(final String userCd, final Date baseDate) {
        // ...
        // アプリケーションがDB上で管理するアドレス情報を、引数のユーザコードおよび基準日から取得するメソッド。
        // ...
    }

}

実装を有効化するために、プロバイダ構成ファイルを作成し、実装クラスの完全修飾クラス名(FQCN)を指定します。

  • META-INF/services/jp.co.intra_mart.foundation.message_hub.mail.delivery.ToMailAddressResolver

    sample.message_hub.address.resolver.SampleToMailAddressResolver
    

6.6.4.2. ToMailAddressResolver 一覧

intra-mart Accel Platform が提供している ToMailAddressResolver は以下の通りです。
表:ToMailAddressResolver一覧
クラス名(単純名) 優先度 説明 提供バージョン
IMBoxToMailAddressResolver 100
IMBox で指定されている宛先のメールアドレスを解決するクラスです。
2014 Winter(Iceberg)
StandardToMailAddressResolver 未設定
メッセージの宛先に指定されたユーザコード と ロケールを元に、IM-共通マスタ のプロファイルに設定されているメールアドレスを解決します。
基準日を「システム日時」としてユーザを検索します。

具体的には、MailAddressResolverUtil.getMailAddressContainer(String, Date, Locale) の結果を 以下の順番で検索し、最初に見つかったメールアドレスを返却します。
  1. MailAddressContainer.getMailAddress1()
  2. MailAddressContainer.getMailAddress2()
以下の場合、空のListが返却されます。
  • 指定されたユーザコードと基準日(=システム日時)に紐づくユーザが存在しなかった場合
  • メールアドレスがいずれも見つからなかった場合
このように、この実装クラスが返却するListの要素数は 0 または 1 です。これは、複数のメールアドレスが返却されることはないということを意味します。
このクラスは、全てのEventに対して有効です。
最後に読み込まれることを想定した標準実装であるため、優先度は指定されていません。
2014 Winter(Iceberg)

6.6.4.3. FromMailAddressResolver 一覧

intra-mart Accel Platform が提供している FromMailAddressResolver は以下の通りです。
表:FromMailAddressResolver一覧
クラス名(単純名) 優先度 説明 提供バージョン
IMBoxToMailAddressResolver 100
IMBox で指定されている送信元のメールアドレスを解決するクラスです。
2014 Winter(Iceberg)
StandardToMailAddressResolver 未設定
メッセージの送信元に指定されたユーザコード と ロケールを元に、IM-共通マスタ のプロファイルに設定されているメールアドレスを解決します。
基準日を「システム日時」としてユーザを検索します。
本クラスの getMailAddress(String, Date, Locale) メソッドは、StandardToMailAddressResolver#getMailAddress(String, Date, Locale) の 最初の要素を返却します。 結果が空のListだった場合は null を返却します。
このクラスは、全てのEventに対して有効です。
最後に読み込まれることを想定した標準実装であるため、優先度は指定されていません。
2014 Winter(Iceberg)