付録L.6 コーディングガイド

<この項の構成>
(1) はじめに
(2) 基本用語説明
(3) Workflow Server-Libraryで取得可能な情報
(4) 案件
(5) アプリケーション構築に関数一般的な説明
(6) 性能を考慮したアプリケーション設計
(7) その他

(1) はじめに

コーディングガイドとして,Workflow Server - LibraryでWorkflow業務アプリケーションを作成する上で,分かりにくい点,間違えやすい点などを記述しています。

Workflow Server - Libraryは,ログインしたユーザが,自分のトレーにある案件を操作するインタフェースを公開しています。一般的には,他人のトレーにある案件は操作できません。他人のトレーにある案件を操作する場合,又は特定ビジネスプロセス下の全案件を対象とする操作を行う場合は,Workflow Library - Extensionを使用してください。

(2) 基本用語説明

ビジネスプロセス
業務の流れを定義したもので,Workflow Definerで定義します。一般的には旅費精算,資材発注などの業務単位で定義します。ビジネスプロセス定義,BP定義,BPとも呼びます。
ビジネスプロセスの一つの業務ステップをノードと呼びます。案件を投入するノードを「ソース」,終了するノードを「シンク」と呼びます。
ワーク
ある業務の一つの実例です。ビジネスプロセスへ案件が投入されるとワークが生成されます。案件がシンクノードへ遷移すると,当該ワークは終了します。
ワークを生成するには,そのワークに,ビジネスプロセス定義内で一つしかない(ユニークな)IDを付ける必要があります。このIDをワークID(案件識別子フォーマット)と呼びます。
案件,ケース
各ユーザに回覧される処理単位を案件と呼びます。案件は,ワークフローで回覧する文書やメモなどを含めた情報の集まりです。ユーザトレーやロールトレーに配布される作業は,この案件単位になります。案件はワークに属し,一つのワークには複数の案件が存在することがあります。例えば,案件が複写され,二つのノードに同時に回覧されている場合,ワークには二つの案件が属しています。
なお,Workflow Definerのソースノード定義では,案件をケースと呼びます。ケースは,文書やメモなどの情報の入れ物としての呼称です。実体としての違いはありませんが,Workflow Server - Libraryでは,業務の中での作業単位として,「案件」という用語を一般に使用しています。

例えば,上記の用語を資材発注業務の場合に当てはめると,以下のイメージになります。

用語イメージ
ビジネスプロセス資材発注業務
ノード申請,承認 …等の各々の作業
ワーク発注申請から業者発注までの一連の仕事
ワークID発注依頼書の依頼書番号や発注番号
案件発注依頼書の入れ物

ビジネスプロセス定義,ワーク,ノード,案件の関連は,次に示す図のようになります。

[図データ]

承認ノードの処理ユーザのトレーをユーザトレー1,同様に経理部ノードをユーザトレー2,資材部ノードをユーザトレー3とする。

(3) Workflow Server-Libraryで取得可能な情報

(a) 取得可能な情報

ワークフローの情報は,大きく分けて以下の3種類の情報があります。

種別説明
オブジェクト情報ワークフローが保持する情報。
それぞれのオブジェクトIDを基に取得。(BP,ワーク,ケース,ユーザ,ロールの種別があります。)
ディレクトリ情報Groupmax Addressで管理している組織・ユーザの情報。
ユーザ情報文書・メモやユーザ属性など,ユーザが任意に設定する情報。
オブジェクト情報
ワークフローの制御用の情報で,それぞれの「オブジェクトID」より取得できます。
それぞれのオブジェクト種別で取得できる情報に関してはHwfGetObjectAttributeExなどを参照してください。
ディレクトリ情報
ワークフローでは,Groupmax Addressで登録した組織情報や,ユーザ情報はオブジェクト情報として管理していません。そのためこれらの情報を取得する際には,HwfGetOrganizationList(組織一覧の取得),HwfGetUserListFromOrgan (組織下のユーザ一覧の取得),HwfGetUserInfo(ユーザ属性情報の取得)など専用の関数を使用して取得します。
ユーザ情報
「文書とメモ」や「案件ユーザ属性」など,業務に応じて追加する任意情報のことです。それぞれの取得関数が用意されています。広い意味では外部データベースに持つ情報も含めますが,この場合はユーザアプリケーションでSQLを実行するなどをして制御する必要があります。
(b) オブジェクトID(OID)

Groupmax Workflowの制御用の情報はオブジェクトとして,データベース(Object Server)に保持しています。OIDとはデータベース内の情報を特定するユニークなIDのことです。Workflow Server - Libraryで何か作業を行う場合,半数以上の関数がこのOIDによってオブジェクトを特定します。例えば,自トレー内の案件を処理する場合,まずその案件を特定する情報として案件のオブジェクトIDを取得します。次にその案件のオブジェクトIDを使用して案件処理開始関数などを発行します。

(c) 文書とメモ

「文書」と「メモ」の違いについて説明します。どちらも任意のファイルを格納できますが,次に示す違いがあります。

種別説明
メモIntegrated Desktop案件エディタで表示しません。(メモタイプがSの本文メモを除く。)
またデータオブジェクト(データメモ)として,ファイルをデータベース(Object Server)に,1個だけ格納できます。
文書Integrated Desktop案件エディタの添付文書として表示されます。

なお,文書・メモともに1案件あたりの上限は設定していませんが,多いほどサーバで管理する情報も増えます。不必要に多くならないようにすることを推奨します。特に統合ノードを使用する場合,統合元の全案件の添付文書・メモが統合先の案件に集められますので注意してください。

文書・メモファイルのサイズには特に制限はありませんが,回線性能にあわせて考慮してください。(注意:データメモは32KBまでの制限があります。)

(d) 案件ユーザ属性

「案件ユーザ属性」とは,Workflow Definerでビジネスプロセス定義を作成する際に,ケース定義に追加することのできる,文字型,整数型,日時型の属性のことです。Workflow Definerではケース属性,Workflow Server - Libraryではユーザ属性と呼んでいます。

下図にWorkflow Definerの定義画面の例を示します。

[図データ]

それぞれの設定可能な範囲を以下に示します。

ケース属性種別範囲
文字型31バイトまで
整数型数字だけで-2,147,483,647~2,147,483,647の範囲
日時型1970年1月1日10:00:00~2038年1月19日03:14:07

あるノードでユーザ属性を参照・更新する場合,Workflow Definerでビジネスプロセス定義を作成するときに,当該ノードの「ユーザ処理リスト」に,ユーザ属性への作業を定義しておく必要があります。

例えば,アプリケーションがAというノードで,Bという属性値を取得するのであれば,Aノードの「ユーザ処理リスト」で,「属性値の参照」を定義しておく必要があります。なお同一ノードにおいて更新も行う場合は,「属性値の直接更新,属性値の選択更新」など更新だけ定義しておくことで参照も可能になります。

[図データ]

案件情報を一覧で取得する関数(HwfGetCaseSelectData,HwfSubstitutionGetCaseなど)では文字型,整数型,日時型の各型の属性に対して5個まで取得できます。これはWorkflow Definerで定義した属性のそれぞれの型で上から5個に相当します。5個以上定義した場合は,HwfGetAttributeValueByUserDefNameExなどユーザトレー内案件属性操作関数を使用して取得してください。

(4) 案件

(a) 上位案件/下位案件
  1. 単体案件
    単純な案件の構造です。Workflowシステムが利用する制御情報も文書・メモ,ユーザ属性などのすべてが一つの案件オブジェクトに含まれています。下図のようなイメージになります。

    [図データ]

  2. 上位案件/下位案件
    ソースノードから一度の投入時に複数個のケースを投入する場合や,「待ち合わせノード」で複数の案件が集まる場合には,以後のノードでは複数のケースをまとめて一つの単位として扱います(以下の図参照)。Workflowシステムでは複数の案件を制御するため,制御用の案件を生成し,階層構造として管理します。

    [図データ]

    この形式の場合,制御用の案件(階層の上位にある案件)を上位案件,実際の文書・メモ,ユーザ情報などが入っている案件(階層の下位にある案件)を下位案件といいます。この状態の場合,Workflow Definerで定義したケースはすべて下位案件になっています。
    イメージ的には以下の図のようになります。

    [図データ]

ユーザトレーに直接追加されている案件は単体案件又は上位案件です。このため案件一覧取得関数(HwfGetCaseSelectDataなど)で簡単に取得できるのは単体案件又は上位案件の情報です。下位案件も含めて一括して取得するとパラメタが複雑になります。

案件処理用の関数(HwfPrefixCase,HwfSuffixCase,HwfGetCaseDocument,HwfUpdateCaseDocumentなど)では案件のオブジェクトIDとして単体案件又は上位案件のオブジェクトIDを指定します。また実際にユーザ属性や文書・メモの参照・設定するために単体案件又は下位案件のケース名称やオブジェクトIDを指定します。

案件のユーザ属性操作用の関数(WFocGetAttrValueByUserDefName,HwfSetCaseByUserDefNameなど)では,属性を設定する単体案件又は下位案件のオブジェクトIDを直接指定します。

下位案件を意識したコーディングは難易度が高くなるため,上記に注意してアプリケーションを作成してください。

(b) 案件の状態遷移

案件の処理状態の遷移を下図に示します。

図L-1 代表的なトレー内操作

[図データ]

(5) アプリケーション構築に関数一般的な説明

(a) アプリケーションの汎用性

アプリケーションを作成する際どこまでの汎用性を持たせるかによって,作成の難易度が変わってきます。

たとえば,Integrated Desktopのような全ての業務を処理する汎用的なアプリケーションを作成するとなると,複雑になり難易度が上がります。しかし業務(ビジネスプロセス)を特定し,作業内容を固定できれば,コーディングは単純になります。

Workflow Server - Libraryを初めて使用される場合は,業務(ビジネスプロセス)を固定にすることをお勧めします。Workflow Server - Libraryの関数は推奨関数だけでも60個以上ありますが,これらは前記の複雑な処理を実現するために用意されており,業務内容が決まっていれば10個程度の関数で実現可能です。

図L-2 案件投入の例

[図データ]

(b) アプリケーションの構築例

Workflow Server - Libraryを使ったアプリケーションの構築例を以下に示します。

  1. バッチ的に処理するアプリケーションの例
    ビジネスプロセス定義にアプリケーション処理用のノードを作成し,アプリケーション作業用の架空ユーザIDを割り当てます。当該ユーザのトレー内全案件を対象とし,先頭から順次処理します。シンクノードの前に案件データを一括してユーザデータベースに格納したりする場合などに使用します。
    また,Windows NTサービスなどに登録するアプリケーションとする場合,この形態とする必要があります。
  2. 3階層アプリケーションの例
    クライアント・サーバ間をOpenTP1などのOLTPプログラムで接続し,OLTPサーバでWorkflow Server - Libraryアプリケーションを起動する3階層アプリケーションも構築可能です。
(c) 情報の削除に関する注意

ワークはWorkflow Monitorなどで削除したり,終了済みワークをワーク削除ユーティリティで一括して削除したりします。ユーザヒストリは保存する件数(デフォルトは50)を定義し,これを超えた場合,古いものから順に削除します。このためユーザヒストリ自体が消去されていたり,ユーザヒストリが残っていてもワーク実体が削除され,ワークヒストリなどが参照できなくなることがあります。送信ログ型のアプリケーションを作成する場合には上記を考慮してください。

ユーザヒストリはWorkflow Monitorなどから最大1,023まで増やすことが可能ですが,サーバのメモリを圧迫するため推奨できません。ユーザヒストリが削除されても,ワークID等の情報をアプリケーションや外部データベースに保存しておけば,ワークが残っている限りワークヒストリなどの情報を参照することが可能です。HwfGetWorkStatus,HwfGetWorkHistoryDirectなどの関数を参照してください。

(d) オブジェクト属性値に関する注意

案件のトレー種別,階層種別,状態コード,優先度,処理種別,同報状態コードなど,オブジェクト属性値にはいくつかの候補値からいずれかの値が返却される場合があります。これらのオブジェクト属性は,将来のバージョンで新しい機能をサポートした場合,新しい候補値が追加される可能性があります。

アプリケーションをWorkflowのバージョンに依存しない構造とするには,これらの拡張性を考慮し,新しい候補値が返却されることを前提として設計するように推奨します。

(e) ユーザ処理リストに関する説明

Workflow Definerのユーザ処理リストでは案件作業用の各種の情報を定義します。これらにはWorkflow Serverが処理するもの,Integrated Desktopを使用した場合はIntegrated Desktopが処理するもの,アプリケーションが処理する必要があるものがあります。

項番Definer定義Library 種別コード対応する処理の実行者
1属性値の直接入力案件のユーザ属性に任意値設定("03")Integrated Desktop案件エディタでユーザ属性の参照・設定を行います。
アプリケーションでユーザ属性操作を行う場合はこれらのユーザ処理リストが必要であり,ユーザトレー内案件属性操作関数(HwfSetCaseByUserDefNameなど)で処理する必要があります。
2属性値の選択更新案件のユーザ属性に候補値設定("04")Integrated Desktop案件エディタでユーザ属性の参照・設定を行います。
アプリケーションでユーザ属性操作を行う場合はこれらのユーザ処理リストが必要であり,ユーザトレー内案件属性操作関数(HwfSetCaseByUserDefNameなど)で処理する必要があります。
3属性値の参照案件の属性値を一覧表示時に出力("09")Integrated Desktop案件エディタでユーザ属性の参照・設定を行います。
アプリケーションでユーザ属性操作を行う場合はこれらのユーザ処理リストが必要であり,ユーザトレー内案件属性操作関数(HwfSetCaseByUserDefNameなど)で処理する必要があります。
4予約値の自動設定(Libraryでは取得しません。)Workflow Serverが処理します。
5文書の登録案件に文書を追加格納("02")Integrated Desktopは処理しません。アプリケーション用の補助情報です。
6複写先選択案件の複写先を指定("13")Integrated Desktop案件エディタで複写先選択が可能になります。
アプリケーションの場合は,HwfCreateCopyInfEx関数で複写先情報を作成し,案件属性操作関数で設定する必要があります。
7作業者の指定案件の作業者を指定("14")Integrated Desktop案件エディタで作業者指定が可能になります。
アプリケーションの場合は,WFocSelectNextUser関数などで設定する必要があります。
8作業者の自動指定(Libraryでは取得しません。)Workflow Serverが処理します。
9配布先ロールの指定配布キーを指定("15")Integrated Desktop案件エディタで指定可能です。
アプリケーションの場合は,HwfGetDeliverKey関数及び案件属性操作関数で設定する必要があります。
10任意データの参照任意データを参照("10")Integrated Desktopでは処理しません。
アプリケーション用の補助情報です。
11AP起動アプリケーションプログラムを起動("11")Integrated DesktopのINBOX,帳票棚を使用する場合はIntegrated Desktopがダウンロード,起動を行います。
INBOX,帳票棚をアプリケーションで作成する場合,HwfDownLoadFileEx関数などを使用して登録ファイルを取得し,起動処理・終了確認処理など作成する必要があります。アプリケーション・フォームをサーバに登録しない場合,このユーザ処理リストは使用しません。
12Groupmaxフォーム表示アプリケーションプログラムを起動("11")Integrated DesktopのINBOX,帳票棚を使用する場合はIntegrated Desktopがダウンロード,起動を行います。
INBOX,帳票棚をアプリケーションで作成する場合,HwfDownLoadFileEx関数などを使用して登録ファイルを取得し,起動処理・終了確認処理など作成する必要があります。アプリケーション・フォームをサーバに登録しない場合,このユーザ処理リストは使用しません。
13案件の文書DB格納案件情報をGroupmax Document Managerへ格納("12")Integrated Desktop案件エディタでは自動的に処理します。
アプリケーションの場合はDocument Manager SDKを使用して,Document Managerへ文書を格納するアプリケーションを作成する必要があります。
14作業状態の選択更新案件の任意ユーザ状態コードへ候補値設定("08")Integrated Desktop案件エディタ用の情報です。
15(ソースノードで「ワークIDを新規に設定する」をチェックした場合,自動的に生成)案件の生成,投入("01")案件投入処理を行います。HwfPutCase関数などの「投入モード」パラメタの指定値に影響します。
16(ソースノードで「ワークIDを新規に設定しない」をチェックした場合,自動的に生成)サブノードからの案件投入("05")Integrated Desktop案件エディタでは自動的に処理します。

(6) 性能を考慮したアプリケーション設計

Workflow Server - Libraryでは多くのお客様の要望にお答えするために,アプリケーション開発の自由度と機能拡充のための数多くの関数をサポートしています。

アプリケーションを開発される場合は,以下に示す注意事項を参考にし,性能を十分考慮したアプリケーションの構築をお願いいたします。

(a) 転送データ量に関する考慮

転送データは大きいほど性能は悪くなります。特に回線性能が低い場合重要なポイントとなります。

例えば以下の注意点があります。

  1. 文書・メモとして添付するファイルに関する注意
    文書・メモとして市販アプリケーションのデータをそのまま添付しようとする場合,そのサイズに注意してください。一般には単純なテキストファイルやCSVファイルの方がサイズが小さく,推奨できます。同様に添付する文書・メモ数があまり多くならないような運用を推奨いたします。
  2. 取得する属性情報に関する注意
    案件一覧表示などでは必要な情報を十分検討し,必要最低限の情報のみを取得するようにしてください。例えばHwfGetCaseSelectData関数で案件の情報を取得する場合,"selectparam"パラメタにBWF_ALL_PARAMETER を指定して案件オブジェクト内の全情報を取得するような処理は行わず,必要な情報だけを取得する処理を推奨いたします。
(b) 関数発行回数に関する考慮

関数発行回数はできる限り減らすようにお願いします。Workflow Server - Libraryの関数の多くはワークフローサーバと通信を行っています。たとえば,1関数0.2秒で処理されるとしても,100回発行すれば20秒かかります。

  1. 取得件数増加に対する注意
    案件一覧表示やユーザヒストリ表示などの一覧表示系のアプリケーションを作成する場合,一覧表示の対象とする情報は,1関数で取得可能な情報にとどめ,別関数が必要な情報は詳細情報として対象案件を絞り込んだ後に取得する方法を推奨します。
    例えば,ユーザトレー内の案件一覧を表示するアプリケーションを作成する場合,取得する案件のユーザ属性を文字・数値・日付それぞれ五つまでに制限できれば,1関数で取得可能となります。しかし,五つ以上の属性を表示する場合は,別関数で取得する必要があるため,取得案件数×別関数 回の関数が発行れることになります。
  2. 分割して取得する場合の注意
    Workflow Server - Libraryの関数では,1回の発行で取得できる情報の量に制限がある場合があります。この場合,全情報を取得するためには分割して取得する必要がありますが,取得する上限にご注意ください。
    例えば,ユーザトレーの案件を取得するアプリケーションを設計した場合を考えます。単純に全案件の情報を取得するように設計すると,何千件もの案件が溜まった場合,取得に膨大な時間が掛かります。
    なお,同じ例で対象件数が不明な場合,一度関数を発行して案件の総数を調べた上で全案件情報の取得領域を確保し,再度関数を発行する方法がありますが,この方法も推奨できません。1回の関数発行で取得する件数を30件などに決めて取得し,それよりも件数が多い場合に改めて関数を発行するなどの方法で,件数調査要の無駄な関数発行を減らすことができます。
(c) 処理の対象となるオブジェクト数に対する考慮

Workflow Server - Libraryの関数で取得する情報の絞り込み方によって,サーバ側で処理対象が膨大になることで性能が悪くなることもあります。例えば以下の注意点があります。

  1. 案件一覧取得時のユーザモードの注意
    案件一覧取得関数では,ロールトレーも含めて関数発行ユーザが処理できる案件一覧を取得するモードがあります。(例えばHwfGetCaseSelectData関数 "getmode"パラメタのBWF_USER_MODEV2 など) このモードでは関数発行ユーザが所属する全ロールのトレーもチェックします。ユーザがいくつものロールに所属する運用環境では性能が悪くなる可能性があります。
  2. 案件一覧取得時のBPモードの注意
    案件一覧取得関数ではビジネスプロセスの全案件を取得するモードがあります。対象が多くなる場合,性能が悪くなる可能性があります。 (注意:取得できる案件はログインユーザのホームサーバと同一サーバにある案件に限られます。マルチサーバ構成でログインユーザのホームサーバとビジネスプロセス定義の登録サーバが異なる場合は,一部の情報しか取得できません。なお本モードは旧バージョンとの互換性のために残されているモードです。このような情報参照にはWorkflow Library - Extensionをご利用ください。)
  3. オブジェクトの検索に関する注意
    オブジェクトの検索関数,関数(HwfSelectObjectIdなど)では,検索対象の数を考慮してください。特に案件を何万件も滞留させている環境で,案件を検索する処理は推奨できません。
  4. 分割して取得する場合のソート処理に関する注意
    案件,ユーザ,ロールなどの情報を一覧取得し,かつ一回の関数の発行では必要な全情報が取得できず分割して取得する場合,ソート指定は行わないようにお願いします。(HwfGetCaseSelectData, HwfGetUserAnd, HwfGetRoleAnd などが該当します。)要求毎にソート処理を行うため,サーバに負荷が掛かります。特にサーバに処理能力が低いマシンを使用している場合に注意が必要です。

(7) その他

(a) Workflow Serverをジャーナル回復させる場合の注意

Workflow ServerはHigh - end Object Serverと組み合わせることによって,障害発生時に,ジャーナルから障害発生時まで回復させることができます。この場合のアプリケーション開発に関する注意事項を示します。

(ジャーナル回復に関する注意事項一般はシステム管理者ガイドを参照してください。)

文書・メモはジャーナル回復されません。(データオブジェクトを除く) このため,ジャーナル回復を期待する場合は文書・メモを使用しないことが推奨です。しかし文書・メモを使用したいと言う場合,ディスクをミラー化するなどの方法で文書・メモの信頼性を上げる方法もあります。また,削除されても業務そのものには実害が無いコメント情報として添付する場合も考えられます。

後者の場合アプリケーションでの考慮が必要になります。この場合文書・メモ取得関数(HwfGetCaseDocumentなど)がエラーリターンしても処理が続行できるようにアプリケーションを構築しておく必要があります。