Teamcenter カスタムワークフローハンドラー（DLL）実装ガイド

概要

Teamcenter の Workflow Designer（WF 作成画面）にカスタムハンドラーを表示させるには、ITK（Integration Toolkit）を使って C/C++ で DLL を実装し、Teamcenter に登録する必要がある。DLL を配置するだけでは機能せず、後述の「3点セット」がすべて揃って初めてハンドラーが WF Designer に表示される。

• 対象バージョン: Teamcenter Unified Architecture 以降（TC10〜TC14 系で基本構造は同一）
• 実装言語: C / C++
• 主な API: ITK の EPM 系関数群

---

ハンドラーの種類

Teamcenter のカスタムワークフローハンドラーには2種類ある。

種類	用途	関数シグネチャ	戻り値
Action Handler	タスクのアクション（開始・完了など）にフックして処理を実行する	int handler_func(EPM_action_message_t msg)	ITK_ok など整数
Rule Handler	タスクが進行してよいか条件を評価する	EPM_decision_t rule_func(EPM_rule_message_t msg)	EPM_go / EPM_nogo / EPM_undecided

ユースケース別の使い分け

Action Handler を使う場面

• ワークフロータスク完了時に外部システムへ通知を送る
• タスク開始時に関連データセットを自動作成・添付する
• オブジェクトの所有者・アクセス権を自動変更する
• 前タスクの結果を引き継いで次タスクの入力データを生成する

Rule Handler を使う場面

• 対象オブジェクトがチェックイン済みであることを確認する（EPM_nogo で進行を止める）
• 必須属性がすべて入力されているかを検証する
• 特定の型のオブジェクトだけを対象とするワークフロー条件を定義する
• 前フェーズの承認数・否認数を集計して次フェーズへの遷移可否を決定する

---

WF Designer への表示に必要な3点セット

「DLL を作ったのに WF Designer に表示されない」というトラブルの原因のほとんどは、以下の3点セットのどれかが欠けていることにある。

① TC_customization_libraries preference
        ↓ DLL をロードする
② BMIDE の Extension 定義（XML）
        ↓ 登録関数を呼び出すフックを設定する
③ C コード内の EPM_register_action_handler() / EPM_register_rule_handler()
        ↓ ハンドラー名を WF Designer に登録する

何を定義するか	どこで定義するか
WF Designer に表示される名前	EPM_register_***_handler() の第1引数（C コード）
登録関数を起動するフック	BMIDE の Extension 定義（XML）
DLL をロードする設定	TC_customization_libraries preference

TC 起動時のフロー

TC 起動
  ↓
TC_customization_libraries で対象 DLL をロード
  ↓
BMIDE の Extension 定義（XML）により
BMF_SESSION_register_epm_handlers にフックされた登録関数が呼び出される
  ↓
登録関数内の EPM_register_action_handler("名前", ...) が実行される
  ↓
WF Designer のハンドラー選択リストに "名前" が表示される

TC_customization_libraries の設定値フォーマット

• 値: DLL ファイル名を拡張子なしで指定する
  • 例: libplmdojo.dll → preference の値は libplmdojo
• スコープ: Site preference として設定することが一般的
• Teamcenter 起動時に preference に列挙されたライブラリが順に読み込まれる

---

実装手順

1. BMIDE で Extension 定義を作成する

BMIDE の Extensions\Rules フォルダを開き、Extensions フォルダを右クリックして「New Extension Definition」を選択する。ダイアログで以下を設定する。

項目	設定値
Business Object	Session
Business Object Type	Type
Operation	BMF_SESSION_register_epm_handlers
Extension Point	BaseAction

ビルド環境のセットアップ手順については /topics/bmide-windows-setup を参照。

2. 登録関数を実装する

BMIDE Extension から呼び出される登録関数の中で、Action Handler と Rule Handler の両方を一括登録できる。

/* 登録関数: BMIDE Extension から呼び出される */
int register_my_handlers(EPM_action_message_t msg)
{
    EPM_register_action_handler("MY_action_handler",
                                "My custom action handler",
                                my_action_func);

    EPM_register_rule_handler("MY_rule_handler",
                              "My custom rule handler",
                              my_rule_func);
    return ITK_ok;
}

3. ハンドラー本体を実装する

Action Handler の例

int my_action_func(EPM_action_message_t msg)
{
    tag_t   task        = msg.task;
    tag_t   root_task   = NULLTAG;
    int     n_targets   = 0;
    tag_t  *targets     = NULL;

    EPM_ask_root_task(task, &root_task);
    EPM_ask_attachments(root_task, EPM_target_attachment,
                        &n_targets, &targets);

    /* ビジネスロジックを実装 */
    /* ... */

    MEM_free(targets);
    return ITK_ok;
}

Rule Handler の例

EPM_decision_t my_rule_func(EPM_rule_message_t msg)
{
    tag_t  task      = msg.task;
    int    n_targets = 0;
    tag_t *targets   = NULL;

    EPM_ask_attachments(task, EPM_target_attachment,
                        &n_targets, &targets);

    if (n_targets == 0)
        return EPM_nogo;   /* 添付なし → 進行不可 */

    MEM_free(targets);
    return EPM_go;         /* 条件クリア → 進行可 */
}

4. DLL をビルドして配置する

BMIDE の「Project → Project Build」でビルドすると、出力先 \output\wntx64\lib\ に .dll と .lib が生成される。

ファイル	配置先
.dll	TC_ROOT\bin\
.lib	TC_ROOT\lib\

5. TC_customization_libraries preference に登録する

拡張子なしの DLL 名を preference の値として追加し、TC サーバーを再起動する。

---

主要 ITK API

API	用途
EPM_register_action_handler(name, desc, func)	アクションハンドラーを WF Designer に登録する
EPM_register_rule_handler(name, desc, func)	ルールハンドラーを WF Designer に登録する
EPM_ask_root_task(task, &root_task)	指定タスクのルートタスクを取得する
EPM_ask_attachments(task, type, &n, &tags)	タスクの添付オブジェクトを取得する（EPM_target_attachment など）
EPM_add_attachments(task, type, n, tags)	タスクに添付オブジェクトを追加する
TCTYPE_ask_object_type(tag, &type_tag)	オブジェクトの型タグを取得する
TCTYPE_ask_name(type_tag, &name)	型名を文字列で取得する
AOM_ask_value_string(tag, attr, &value)	オブジェクトの文字列属性値を取得する
AOM_save(tag)	オブジェクトへの変更を保存する
AOM_unlock(tag)	オブジェクトのロックを解除する
AE_find_datasettype(name, &type_tag)	データセット型を名前で検索する
AE_create_dataset_with_id(...)	ID 付きでデータセットを作成する

---

既存実装の調査方法

既存環境にカスタムハンドラーが実装されているかを確認する手順：

調査ポイント	確認方法
どの DLL が登録済みか	Rich Client → ツール → オプション → TC_customization_libraries preference の値を確認
実際に配置されている DLL	TC_ROOT\bin\ 以下のファイル一覧を確認
BMIDE の Extension 定義	BMIDE → Extensions\Rules → BMF_SESSION_register_epm_handlers フック定義を確認
ソースコード	EPM_register_action_handler の第1引数を grep して登録名を確認
DLL 内の文字列（ソースなし）	Windows: strings コマンド または Dependency Walker でハンドラー名の文字列を確認

---

よくあるトラブルと対処

トラブル1: ハンドラーが WF Designer に表示されない

原因と確認事項を優先順に示す。

1. TC_customization_libraries preference 未登録 / 値が誤っている

• preference の値に DLL 名が含まれているか確認する（拡張子なし）
• サーバーを再起動して preference が反映されているか確認する

2. BMIDE の Extension 定義が存在しない / 設定が誤っている

• Operation が BMF_SESSION_register_epm_handlers、Extension Point が BaseAction になっているか確認する
• Business Object が Session になっているか確認する
• BMIDE のパッケージが TC サーバーにデプロイされているか確認する

3. DLL が TC_ROOT\bin\ に存在しない

• ビルド成功後に TC_ROOT\bin\ への手動コピーが必要な場合がある
• ファイル名が preference に登録した名前と一致しているか確認する

4. 登録関数が呼び出されていない

• BMIDE Extension から登録関数への紐付けが正しいか確認する
• デバッグログを有効にして起動時にエラーが出ていないか確認する

トラブル2: DLL が TC 14.3 以降でロードされない

TC 14 系で DLL がロードされないケースが報告されている。確認事項：

• DLL が対象 TC バージョンの ITK ヘッダ・ライブラリでビルドされているか
• Visual Studio のバージョンが TC のサポート対象か（TC バージョンごとに推奨 VS バージョンが異なる）
• 64bit ビルドになっているか（TC 12 以降は wntx64 が標準）

根本原因については Siemens サポートへの問い合わせを推奨する。

トラブル3: ハンドラー変更後に反映されない

DLL を差し替えた後に変更が反映されない場合：

• TC サーバーの再起動が必要: DLL は TC 起動時に一度だけロードされる
• 実稼働環境では他セッションへの影響を考慮してメンテナンスウィンドウ内で対応する

トラブル4: Rule Handler の戻り値が正しく機能しない

• Rule Handler は EPM_decision_t 型を返す必要がある。int で定義すると型不一致になる
• EPM_nogo を返してもタスクが止まらない場合は、ハンドラーが Rule として登録されているか（Action ではなく）を確認する

---

TC バージョンによる差異

項目	状況
基本的な登録フロー	TC 10〜TC 14 系で同一（EPM_register_*_handler の仕組みは変わっていない）
ビルド環境	TC バージョンごとに推奨 Visual Studio バージョンが異なる。TC 14 系では VS 2019/2022 が対象
DLL アーキテクチャ	TC 12 以降は 64bit（wntx64）が標準。TC 11 以前の 32bit DLL は再ビルドが必要
BMIDE の UI	バージョン間で Extension 定義のダイアログ表示が変わることがあるが、設定項目は同一

TC バージョン固有の変更点（API 廃止・変更）については Siemens の公式リリースノートを参照すること。

---

関連トピック

• /topics/teamcenter
• /topics/bmide-windows-setup

---

参考

公開ドキュメント・コミュニティ

• TC_Custom Libraries - Siemens Documentation (TC 12.0) — TC_customization_libraries preference の公式説明
• Teamcenter Open Gate: Action handler and Rule handler — Action / Rule Handler の実装例（C コード付き）
• Teamcenter Open Gate: Workflow Action Handler Registration — ハンドラー登録フローの解説
• Teamcenter custom handler build in BMIDE - PLM Handbook — BMIDE Extension 定義の手順
• Teamcenter Workflow Handlers – Global PLM — Action / Rule Handler の概要
• Basic ITK Customization Concept Part-02 – Global PLM — EPM_decision_t の解説
• Leveraging Action and Rule Handlers in Teamcenter’s EPM Module (LinkedIn) — 使い分けの解説
• GitHub: hfplm/TeamCenter_custom_handler — カスタムハンドラーの実装例（C 言語）

Siemens Community

• ITK Custom Workflow Handler not showing up
• Custom Workflow handler not showing in the Task Action Handler list
• UNABLE TO LOAD CUSTOM DLL’S IN TC 14.3.07
• Quickest way to deploy DLL after handler change