IM-FormaDesigner for Accel Platform プログラミングガイド 第14版 2019-04-01

12.2. APIの仕様を確認する

ここでは、ワークフロー案件処理Web APIの仕様が掲載されているAPIドキュメントへのアクセス方法を説明します。
また、APIドキュメントで不足している情報については本章で補足説明します。

12.2.1. Web上からAPI仕様を参照し実行する

ワークフロー案件処理Web APIでは、Swagger Specificationを利用して、APIドキュメントを intra-mart Accel Platform 上のWeb アプリケーションとして提供しています。
Swagger Specificationでは、APIの仕様の確認だけでなく、画面上からパラメータ情報を入力することでWeb APIを実行することが可能です。

12.2.1.1. Swagger Specificationを表示する

Swagger Specificationから、提供されているWeb APIのURL一覧と各APIの実行に必要なリクエスト情報を確認することができます。
  1. Swagger Specificationを利用するための intra-mart Accel Platform の環境を構築します。
    • 以下のモジュールをインストールした環境を構築してください。
      • IM-FormaDesigner for Accel Platform
    • IM-BIS ワークフロー案件処理Web APIについては、以下のモジュールをインストールした環境を構築してください。
      • IM-BIS for Accel Platform
  2. メニューからSwagger Specificationへアクセスします。
    • IM-FormaDesigner ワークフロー案件処理Web API
      • 「サイトマップ」-「Forma開発者」-「Webサービス APIドキュメント」-「ワークフロー」をクリックし、Swagger Specificationを表示します。
    • IM-BIS ワークフロー案件処理Web API
      • 「サイトマップ」-「IM-BIS開発者」-「Webサービス APIドキュメント」-「ワークフロー」をクリックし、Swagger Specificationを表示します。
      ../../_images/web_api_document.png

12.2.1.2. Swagger SpecificationからWeb APIを実行する

Swagger Specificationの画面に表示されているリクエスト情報のひな形を編集し、実際にWeb APIを実行することが可能です。
  1. URLの一覧から実行したAPIを押下します。
    • APIのURLを押下すると、APIの詳細ページが表示されます。

      ../../_images/swagger1.png
  2. 表示されたAPIの詳細画面からパラメータ情報を押下します。
    • パラメータ情報のJSON Schemaの部分を押下すると、Valueフィールドにパラメータ情報のひな形のJSONが編集可能な状態で表示されます。

      ../../_images/swagger2.png
  3. 表示されたパラメータ情報のひな形を編集します。
    ../../_images/swagger3.png
    • ひな形のJSONを編集し、案件の処理が実行できるパラメータを作成します。
      • パラメータ例
      {
        "applyBaseDate": "2015/07/28",
        "matterName": "sample_matter",
        "applyExecuteUserCode": "aoyagi",
        "userParam": {},
        "formaUserParam": {
         "items" : {
            "textbox1" : "あいうえお"
         }
        },
        "applyAuthUserCode": "aoyagi",
        "flowId": "web_api_test"
      }
      
  4. Web APIの実行ボタンを押下します。
    • 必要なパラメータを入力した上で「Try it out!」ボタンを押下します。

      ../../_images/swagger4.png
  5. Web APIの実行結果を確認します。
    • Web APIの実行に成功した場合は、Response情報が表示されます。

      Response情報
      Response Headers HTTP通信のレスポンスヘッダとしてメタ情報が表示されます。
      Response Code
      HTTP通信のレスポンスコードが表示されます。
      APIの呼び出しに成功した場合は 200 が返却されます。
      認可制御でエラーになった場合は 403 が返却されます。
      Response Body APIの実行結果の詳細が表示されます。
      ../../_images/swagger5.png

注意

Swagger SpecificationからWeb APIを実行した場合でも実際の案件処理が動作します。
本番環境では実施しないでください。

注意

Web APIの認証ユーザはSwagger Specificationの画面を操作しているログインユーザが設定されます。

12.2.1.3. 提供APIのURL一覧

提供されるWeb APIは以下のとおりです。

12.2.1.3.1. IM-FormaDesigner

各種一覧取得メソッドを提供するWebサービス
メソッド パス 説明
POST /api/forma/imw/selectUnprocessActvMatterNodeList 未処理ノード一覧を取得します。
POST /api/forma/imw/selectUnprocessActvMatterNodeListCount 未処理ノード一覧件数を取得します。
POST /api/forma/imw/selectProcessedActvMatterList 処理済一覧(未完了)を取得します。
POST /api/forma/imw/selectProcessedActvMatterListCount 処理済一覧(未完了)件数を取得します。
POST /api/forma/imw/selectRefActvMatterList 参照一覧(未完了)を取得します。
POST /api/forma/imw/selectRefActvMatterListCount 参照一覧(未完了)件数を取得します。
POST /api/forma/imw/selectRefActvMatterAdminHandleLevelList 参照一覧(未完了)管理マネージャ(操作レベルを含む)を取得します。
POST /api/forma/imw/selectRefActvMatterAdminHandleLevelListCount 参照一覧(未完了)管理マネージャ(操作レベルを含む)件数を取得します。
案件の処理や、処理時に必要な情報取得メソッドを提供するWebサービス
メソッド パス 説明
POST /api/forma/imw/apply 申請処理を実行します。
POST /api/forma/imw/applyFromUnapply 未申請状態の案件の申請処理を実行します。
POST /api/forma/imw/approve 承認処理を実行します。
POST /api/forma/imw/approveEnd 承認終了処理を実行します。
POST /api/forma/imw/createTempSave
一時保存案件を新規登録します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/forma/imw/updateTempSave
一時保存案件を更新します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/forma/imw/deleteTempSave
一時保存案件を削除します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/forma/imw/deny 否認処理を実行します。
POST /api/forma/imw/discontinue 取止め処理を実行します。
POST /api/forma/imw/draft 起票案件を新規登録します。
POST /api/forma/imw/fileupload ファイルをアップロードします。
POST /api/forma/imw/reapply 再申請処理を実行します。
POST /api/forma/imw/reserve 保留処理を実行します。
POST /api/forma/imw/reserveCancel 保留解除処理を実行します。
POST /api/forma/imw/pullBack 引戻し処理を実行します。
POST /api/forma/imw/sendBack 差戻し処理を実行します。
POST /api/forma/imw/transfer 振替処理を実行します。
ファイルアップロードメソッドなどを提供するWebサービス
メソッド パス 説明
POST /api/forma/imw/fileupload ファイルアップロード用のWeb API

12.2.1.3.2. IM-BIS

各種一覧取得メソッドを提供するWebサービス
メソッド パス 説明
POST /api/bis/imw/selectUnprocessActvMatterNodeList 未処理ノード一覧を取得します。
POST /api/bis/imw/selectUnprocessActvMatterNodeListCount 未処理ノード一覧件数を取得します。
POST /api/bis/imw/selectProcessedActvMatterList 処理済一覧(未完了)を取得します。
POST /api/bis/imw/selectProcessedActvMatterListCount 処理済一覧(未完了)件数を取得します。
POST /api/bis/imw/selectRefActvMatterList 参照一覧(未完了)を取得します。
POST /api/bis/imw/selectRefActvMatterListCount 参照一覧(未完了)件数を取得します。
POST /api/bis/imw/selectRefActvMatterAdminHandleLevelList 参照一覧(未完了)管理マネージャ(操作レベルを含む)を取得します。
POST /api/bis/imw/selectRefActvMatterAdminHandleLevelListCount 参照一覧(未完了)管理マネージャ(操作レベルを含む)件数を取得します。
案件の処理や、処理時に必要な情報取得メソッドを提供するWebサービス
メソッド パス 説明
POST /api/bis/imw/apply 申請処理を実行します。
POST /api/bis/imw/applyFromUnapply 未申請状態の案件の申請処理を実行します。
POST /api/bis/imw/approve 承認処理を実行します。
POST /api/bis/imw/approveEnd 承認終了処理を実行します。
POST /api/bis/imw/createTempSave
一時保存案件を新規登録します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/bis/imw/updateTempSave
一時保存案件を更新します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/bis/imw/deleteTempSave
一時保存案件を削除します。
申請・起票前に一時保存を行った案件が対象です。
POST /api/bis/imw/deny 否認処理を実行します。
POST /api/bis/imw/discontinue 取止め処理を実行します。
POST /api/bis/imw/draft 起票案件を新規登録します。
POST /api/bis/imw/fileupload ファイルをアップロードします。
POST /api/bis/imw/reapply 再申請処理を実行します。
POST /api/bis/imw/reserve 保留処理を実行します。
POST /api/bis/imw/reserveCancel 保留解除処理を実行します。
POST /api/bis/imw/pullBack 引戻し処理を実行します。
POST /api/bis/imw/sendBack 差戻し処理を実行します。
POST /api/bis/imw/transfer 振替処理を実行します。
ファイルアップロードメソッドなどを提供するWebサービス
メソッド パス 説明
POST /api/bis/imw/fileupload ファイルアップロード用のWeb API

12.2.2. パラメータ情報の仕様を確認する

ワークフロー案件処理APIと同様に、パラメータはワークフローデータ・アプリケーションデータの2つが必要です。
パラメータは、リクエストボディからJSON形式で送信します。

12.2.2.1. ワークフローデータ

パラメータ(ワークフローデータ)については、Swagger Specificationのスキーマ情報から確認することができます。
パラメータの各プロパティについては、ワークフロー案件処理API(スクリプト開発モデル)と同様です。詳細は「 IM-FormaDesigner for Accel Platform APIドキュメント(スクリプト開発モデル) 」を参照してください。

12.2.2.2. アプリケーションデータ

Swagger Specificationのスキーマ情報ではMapのデータ構造を表現できないため、パラメータ(アプリケーションデータ)については本ドキュメントにてインタフェースを説明します。

12.2.3. パラメータ(アプリケーションデータ)

基本的には、ワークフロー案件処理API(スクリプト開発モデル)のパラメータ(アプリケーションデータ)のオブジェクトをJSONにフォーマットして指定します。
ただし、以下のデータ型についてはJSONに直接指定できないため、ワークフロー案件処理Web API独自の指定方法を定めています。
  • 日付型
  • タイムスタンプ型
  • ファイル

12.2.3.1. アプリケーションデータ(入力アイテムデータ)

基本的には、ワークフロー案件処理API(スクリプト開発モデル)のアプリケーションデータ(入力アイテムデータ)のオブジェクトをJSONにフォーマットして指定します。
  • 日付型・タイムスタンプ型
    • ISO 8601 の規格に従った文字列(YYYYMMDDThhmmss+0900)にて指定します。
  • (例)JSON

    "formaUserParam": {
        "items": {
            "textbox1": "あいうえお",
            "number1": 1000,
            "calendar1": "2010-07-28T22:25:51Z"
        }
    }
    

12.2.3.2. アプリケーションデータ(テーブルアイテムデータ)

基本的には、ワークフロー案件処理API(スクリプト開発モデル)のアプリケーションデータ(テーブルアイテムデータ)のオブジェクトをJSONにフォーマットして指定します。
  • 日付型・タイムスタンプ型
    • ISO 8601 の規格に従った文字列(YYYYMMDDThhmmss+0900)にて指定します。
  • (例)JSON

    "formaUserParam": {
        "items": {
            "tb1": [
                {
                    "tb1_textbox1": "明細1 - りんご",
                    "tb1_textbox2": "明細1 - バナナ"
                },
                {
                    "tb1_textbox1": "明細1 - ぶどう",
                    "tb1_textbox2": "明細1 - 苺"
                }
            ],
            "tb2": [
                {
                    "tb2_number1": 345.678,
                    "tb2_calendar1": "2010-07-28T22:25:51Z"
                },
                {
                    "tb2_number1": 99999,
                    "tb2_calendar1": "2015-07-23T22:25:51Z"
                }
            ]
        }
    }
    

12.2.3.3. アプリケーションデータ(ファイルアップロードアイテムデータ)

ファイルアップロードアイテムデータについてはトークン方式にて指定を行います。
  1. ファイルアップロード用のWeb APIを実行します。
    リクエスト情報は、以下のように送信します。
    リクエストヘッダ
    フィールド名
    Content-Type multipart/form-data
    Accept application/json
    リクエストパラメータ
    フィールド名
    file ファイルデータ

    コラム

    ファイルのアップロードに成功すると、トークンとファイル名が返却されます。
    複数のファイルをアップロードする場合は、複数回リクエストを発行し、トークンを取得してください。
  2. 取得したトークンをアプリケーションデータ(ファイルアップロードアイテムデータ)のJSONに指定します。
    • (例)JSON

      "formaUserParam": {
          "items": {
            ...
          },
          "files": [
                      {
                          "token": "8e9vzec9jacb1cy",
                          "fileName": "sample_file.txt",
                          "uploadItemId": "attach_fileupload_item1",
                          "notes": "サンプル備考1"
                      },
                      {
                          "token": "8e9vzikscacfwcy",
                          "fileName": "sample_file.jpg",
                          "uploadItemId": "attach_fileupload_item1",
                          "notes": "サンプル備考2"
                      }
                  ]
      }

12.2.4. 注意事項

注意

  • Web APIはワークフロー案件処理Web APIを拡張した機能であり、ワークフロー案件処理Web APIの同様の制限が存在します。

  • Web APIのContent-Type・Acceptは、application/jsonのみの対応となり、application/xmlには対応していません。

  • formaUserParamの文字列型のパラメータに対して、ISO 8601 の規格に従った日付文字列が送信された場合は、日付型・タイムスタンプ型として処理されます。

  • Web APIを利用してワークフローの申請を行う場合、パラメータ(アプリケーションデータ)に指定できるアイテムは、申請ノードに設定されている画面遷移のフォームに含まれるものに限定されます。
    Web APIを利用してワークフローの承認を行う場合、パラメータ(アプリケーションデータ)に指定できるアイテムは、承認ノードに設定されている画面遷移のフォームに含まれるものに限定されます。
  • 以下のWeb APIを実行した場合は、現状、formaUserParamパラメータを指定してもアプリケーションデータは更新されません。

IM-FormaDesigner
メソッド パス 説明
POST /api/forma/imw/deny 否認処理を実行します。
POST /api/forma/imw/discontinue 取止め処理を実行します。
POST /api/forma/imw/reserve 保留処理を実行します。
POST /api/forma/imw/reserveCancel 保留解除処理を実行します。
POST /api/forma/imw/pullBack 引戻し処理を実行します。
POST /api/forma/imw/sendBack 差戻し処理を実行します。
IM-BIS
メソッド パス 説明
POST /api/bis/imw/deny 否認処理を実行します。
POST /api/bis/imw/discontinue 取止め処理を実行します。
POST /api/bis/imw/reserve 保留処理を実行します。
POST /api/bis/imw/reserveCancel 保留解除処理を実行します。
POST /api/bis/imw/pullBack 引戻し処理を実行します。
POST /api/bis/imw/sendBack 差戻し処理を実行します。