EDQケース管理APIの使用

7 EDQケース管理APIの使用

EDQには、ケースの取得と更新、フィルタの実行およびロード・テストを可能にするRESTベースのインタフェースのセットが用意されています。

ケース管理APIを開くには、Launchpadの「Webサービス」ドロップダウン・メニューから「ケース管理API仕様」を選択します。サービスを選択すると、自動的にロードされます。この章では、EDQサービスが次の場所にインストールされていると仮定します。

http://edqserver:8001/edq

この章では、これらのインタフェースと、そのインタフェースを使用して実行できる操作について詳細に説明します。次のトピックが含まれています:

7.1 ケースまたはアラートの詳細の取得

単一のケースまたはアラートの詳細を取得するには、外部または内部IDを使用してインタフェースをコールします。

GET http://edqserver:8001/edq/cm/getcase/{id}[?sourcedata=true]

次の表は、このコールでサポートされている入力プロパティを示しています:

プロパティ	タイプ	必須	説明
Id	String	はい	ケース識別子。S2-1241などの外部IDまたは数値の内部IDを指定します。
sourcedata	Boolean	いいえ	trueに設定すると、ソースおよび関係データが含められます(アラートのみ)。ノート: このプロパティは、EDQ 12.2.1.4.3以降のリリースで使用できます。

次の表は、ケースごとに表示される出力プロパティを示しています:

プロパティ	タイプ	必須	説明
Id	String	はい	外部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
internalid	Integer	はい	内部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
source	String	はい	ケース・ソース名。
sourceid	String	はい	ケース・ソース識別子。
type	String	はい	ケースまたはアラートのタイプ。
parentid	Integer	いいえ	アラートの場合、格納しているケースの内部ID。
key	String	はい	ケース・キー。
description	String	いいえ	ケースの説明。
createdby	String	はい	ケースを作成したユーザーの名前。
createdbyid	Integer	はい	ケースを作成したユーザーの内部ID。
createdbydisplay	String	はい	ケースを作成したユーザーの表示名。
createdwhen	String	はい	作成タイムスタンプ。
modifiedby	String	はい	直近の変更を行ったユーザーの名前。
modifiedbyid	Integer	はい	直近に変更を加えたユーザーの内部ID。
modifiedbydisplay	String	はい	直近に変更を加えたユーザーの表示名。
modifiedwhen	String	はい	直近の変更のタイムスタンプ。
assigneduser	String	いいえ	現在割り当てられているユーザーの名前。ケースが割り当てられていない場合、この値は存在しません。
assigneduserid	String	いいえ	現在割り当てられているユーザーの内部ID。ケースが割り当てられていない場合、この値は存在しません。
assigneduserdisplay	String	いいえ	現在割り当てられているユーザーの表示名。ケースが割り当てられていない場合、この値は存在しません。
assignedby	String	いいえ	直近の割当てを行ったユーザーの名前。
assignedbyid	Integer	いいえ	直近の割当てを行ったユーザーの内部ID。
assignedbydisplay	String	いいえ	直近の割当てを行ったユーザーの表示名。
assignedwhen	String	いいえ	直近の割当てのタイムスタンプ。
priority	Integer	はい	ケース優先度。最小: 0 最大: 3
state	String	はい	現在の状態。
statechangedby	String	いいえ	直近の状態変更を行ったユーザーの名前。
statechangedbyid	Integer	いいえ	直近の状態変更を行ったユーザーの内部ID。
statechangedbydisplay	String	いいえ	直近の状態変更を行ったユーザーの表示名。
statechangedwhen	String	いいえ	直近の状態変更のタイムスタンプ。
derivedstate	String	はい	導出状態
reviewflag	Boolean	はい	新しいレビュー・フラグ。
reviewflagupdatedby	String	いいえ	直近のレビュー・フラグ変更を行ったユーザーの名前。
reviewflagupdatedbyid	String	いいえ	直近のレビュー・フラグ変更を行ったユーザーの内部ID。
reviewflagupdatedbydisplay	String	いいえ	直近のレビュー・フラグ変更を行ったユーザーの表示名。
reviewflagupdatedwhen	String	いいえ	直近のレビュー・フラグ変更のタイムスタンプ。
permission	String	いいえ	ケース権限。値は、ケース管理の管理で定義された内部キーです。
extendedattributen	String	いいえ	拡張属性
extendedattributenmodifiedby	String	いいえ	拡張属性nに対する直近の変更を行ったユーザーの名前。
extendedattributenmodifiedbyid	Integer	いいえ	拡張属性nに対する直近の変更を行ったユーザーの内部ID。
extendedattributenmodifiedbydisplay	String	いいえ	拡張属性nに対する直近の変更を行ったユーザーの表示名。
extendedattributenmodifiedwhen	String	いいえ	拡張属性nに対する直近の変更のタイムスタンプ。
extendedattributenlabel	String	いいえ	拡張属性nのラベル。

設定されていない値は省略されます。拡張属性は、JSONオブジェクトに含まれており、oedq_local_home/casemanagementディレクトリ内のシステムflags.xmlファイルの定義から導出されます。

タイムスタンプはISO形式(YYYY-MM-DDTHH:MM:SS.mmmZ)で戻されます

sourcedataフラグがtrueに設定され、その結果がアラートを対象とする場合、出力プロパティにはsourcedataおよびrelationships属性も含まれます。

次の表は、sourcedata属性に対して表示される出力プロパティを示しています:

プロパティ	説明
relationships	関係データ
sourcedata	ソース・データ

次の表は、relationship属性に対して表示される出力プロパティを示しています:

プロパティ	説明
inputname	入力ストリームの内部名。
recordid	ソース・レコードの内部ID。
relatedinputname	関連入力ストリームの内部名。
relatedrecordid	関連ソース・レコードの内部ID。
rulename	関連ソース・レコードの内部ID。
priorityscore	関係を生成したルールの名前。

sourcedataオブジェクトは、入力オブジェクトの配列であり、それぞれに入力ストリーム名とラベル、および関連付けられた属性ラベルとソース・レコードが含まれます。

次に、単純なアラートの関係およびソース・データの例を示します:

"relationships": [
  {
    "inputname": "workdata 1",
    "recordid": 77,
    "relatedinputname": "refdata 1",
    "relatedrecordid": 199342,
    "rulename": "MatchRule1",
    "priorityscore": 0
  }
],
"sourcedata": [
  {
    "inputname": "refdata 1",
    "label": "refdata",
    "labels": {
      "ID": "ID",
      "TITLE": "TITLE",
      "FIRSTNAME": "FIRSTNAME",
      "LASTNAME": "LASTNAME",
      "TELEPHONE": "TELEPHONE",
      "NewAttribute": "AGE",
      "NewAttribute1": "type"
    },
    "records": [
      {
        "recordid": 199342,
        "data": {
          "ID": 48,
          "TITLE": "Doctor",
          "FIRSTNAME": "Riaz",
          "LASTNAME": "Audoire",
          "TELEPHONE": "05305 937614",
          "NewAttribute": 67,
          "NewAttribute1": "I"
        }
      }
    ]
  },
  {
    "inputname": "workdata 1",
    "label": "workdata",
    "labels": {
      "ID": "ID",
      "TITLE": "TITLE",
      "FIRSTNAME": "FIRSTNAME",
      "LASTNAME": "LASTNAME",
      "TELEPHONE": "TELEPHONE",
      "NewAttribute": "AGE",
      "NewAttribute1": "type"
    },
    "records": [
      {
        "recordid": 77,
        "data": {
          "ID": 48,
          "TITLE": "Doctor",
          "FIRSTNAME": "Riaz",
          "LASTNAME": "Audoire",
          "TELEPHONE": "05305 937614",
          "NewAttribute": 3,
          "NewAttribute1": "I"
        }
      }
    ]
  }
]

7.2 保存済フィルタまたはレポートの実行

runfilterを使用して、保存済ケース管理フィルタまたはレポートを実行します。取得された結果が生成され、JSON形式で表示されます。フィルタ結果は、ケース管理アプリケーションと同じルールに従って制限されます。このコールでは、限られた数の結果が、使用可能な結果の合計数とともに戻されます。この制限を指定できます。デフォルトの制限は100です。

保存済ケース管理フィルタまたはレポートを実行するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cm/runfilter?filter=NAME[&global=true][&limit=100][&sql=false]

実行するフィルタを記述するJSONオブジェクトを作成し、HTTP POSTを使用してRESTコールのリクエスト本体でそれを送信することもできます。たとえば、

POST http://edqserver:8001/edq/cm/runfilter
{
  "filter": "string",
  "global": true,
  "limit": 50,
  "sourcedata": true
}

次の表は、runfilterでサポートされている入力プロパティを示しています:

プロパティ	説明
filter	フィルタまたはインライン・フィルタ定義の名前。「JSON形式のフィルタ定義」を参照してください。
global	trueに設定すると、グローバル・フィルタが指定されます。
orderby	問合せの並替え基準列を定義する文字列の配列。フィルタ定義と同じ列名を使用します。`asc`または`desc`接尾辞を追加して、順序の向きを制御します。たとえば: `orderby: ["source", "description desc", "extendedattribute4 asc"]`
limit	1-1000の範囲の結果制限。最小: 1 最大: 1000 デフォルト値は100です。
sql	使用可能な場合、falseに設定すると非SQL実行が強制されます。この属性は、`GET`コールでのSQLの使用を制御します。
sourcedata	trueに設定すると、ソースおよび関係データが含められます(アラートのみ)。

このコードが正常に実行されると、ケースの詳細が生成され、JSON形式で表示されます:

{
  "version": 1,
  "report": false,
  "count": 1000,
  "more": true,
  "cases": [
     array of case/alert details
   ]
}

countおよびmore属性には、UIで表示される値が反映されます。たとえば、フィルタに「100アイテム、サーバー上の合計196」と表示される場合、count = 196で、more = falseです。フィルタに「100アイテム、>サーバー上の1,000」と表示される場合、count = 1000で、more = trueです。

レポート実行では、結果は次の構造を持つJSONオブジェクトです:

{
  "version": 1,
  "report": true,
  "xlabels": [array of X axis labels],
  "ylabels": [array of Y axis labels],
  "scores":  [2 dimensional array of row/col values]
}

レポートでは、各軸で複数のアイテムがサポートされるため、ラベル配列の要素は文字列の配列になります。

7.3 ケースまたはアラートの詳細の更新

ケースまたはアラートの詳細を更新するには、変更する詳細を指定するJSONオブジェクトを作成する必要があります。

たとえば、

POST http://edqserver:8001/edq/cm/update

リクエストのペイロードは、次の表にリストされた属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
failonanyerror	Boolean	trueの場合、更新がエラーで終了すると、リクエストは失敗します。優先度が範囲外であるなど、更新の値が無効な場合、コールは常に失敗します。個別の更新で発生するエラーには、権限の問題が含まれます。
updates	配列	個々のケース/アラート更新リクエストの配列。配列に1000を超える要素を含めることはできません。

次の表は、updates配列の各オブジェクトに含めることができる属性を示しています:

プロパティ	タイプ	必須	説明
Id	String	はい	外部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
internalid	Integer	はい	内部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
description	String	いいえ	ケースの説明。
assigneduser	String	いいえ	現在割り当てられているユーザーの名前。ケースが割り当てられていない場合、この値は存在しません。
priority	Integer	はい	ケース優先度。最小: 0 最大: 3
reviewflag	Boolean	いいえ	新しいレビュー・フラグ。
permission	String	いいえ	ケース権限。値は、ケース管理の管理で定義された内部キーです。
extendedattributen	String	いいえ	拡張属性。
statechange	オブジェクト	いいえ	状態変更の定義。

statechangeオブジェクトには、次のオブジェクトを含めることができます:

プロパティ	説明
transition	(必須)遷移名。
comment	状態変更のコメント。
restrictingpermission	コメントに適用する制限権限。UI名ではなく、権限のキーを指定します。

たとえば、

{
  "updates": [
    {
      "id": "ECS-234",
      "assigneduser": "john.sheridan",
      "priority": 3,
      "statechange": {
        "transition": "toMatch",
        "comment": "Updated by API call"
      }
    }
  ]
}

コールが成功した結果(ステータス200)は、個々のケース/アラート更新の結果を含むstatus配列を持つオブジェクトです。各ステータス・オブジェクトには、次の属性が含まれます:

プロパティ	説明
ok	trueの場合、更新が成功したことを示します。
reason	`ok`がfalseに設定されている場合、失敗の理由コード。
message	更新が失敗した場合の追加メッセージ。

次に、エラー・レスポンスの例を示します:

{ "status": [
    { "ok": false,
      "reason": "unknown_user",
      "message": "Unknown user \"tamie.grindy\""
    }
  ]
}

7.4 1つ以上のケースまたはアラートへのコメントの追加

1つ以上のケースまたはアラートにコメントを追加するには、ケース/アラートのコメント定義を指定するJSONオブジェクトを作成する必要があります。

たとえば、

POST /edq/cm/addcomments

リクエストのペイロードは、次の表にリストされた属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
failonanyerror	Boolean	trueの場合、更新がエラーで終了すると、リクエストは失敗します。権限が不明であるなど、更新の値が無効な場合、コールは常に失敗します。個別の更新で発生するエラーには、ケースの欠落が含まれます。
comments	配列	個々のケース/アラートのコメント定義の配列。配列に1000を超える要素を含めることはできません。

次の表は、comments配列の各オブジェクトに含めることができる属性を示しています:

プロパティ	タイプ	必須	説明
Id	String	いいえ	外部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
internalid	Integer	いいえ	内部ケースID。外部ケースIDまたは内部ケースIDのいずれかを指定する必要があります。
comment	String	はい	コメント・テキスト。
restrictingpermission	String	いいえ	コメントに適用する制限権限。UI名ではなく、権限のキーを指定します。

コールが成功した結果(ステータス200)は、個々のケース/アラート更新の結果を含むstatus配列を持つオブジェクトです。

7.5 1つ以上のケースまたはアラートの削除

コールを行うユーザーには、ケース管理の一括削除権限が必要です。ケースまたはアラートを削除するには、削除するケース/アラートのIDの配列を含むJSONオブジェクトを作成し、HTTP POSTを使用してRESTコールのリクエスト本体でそれを送信します。たとえば、

POST http://edqserver:8001/edq/cm/deletecases
{ "deleteemptycases": true,
  "ids": [
     1213423,
	 454344,
	 "X1-123",
	 "X1-456"
  ]
}

POSTのペイロードは、次の属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
ids	配列	削除するケース/アラートの配列ID。各要素は、数値の内部IDまたは文字列の外部ID ("S2-1231"など)です。配列に1000を超える要素を含めることはできません。
deleteemptycases	Boolean	trueの場合、含まれているすべてのアラートが削除済のケースも削除されます。デフォルトは、falseです。

コールが成功した結果は、次の属性を持つオブジェクトです:

プロパティ	タイプ	説明
count	数値	コールによって削除されたケース/アラートの数。

7.6 フィルタを使用したケースまたはアラートの一括削除

コールを行うユーザーには、ケース管理の一括削除権限が必要です。フィルタを使用してケースまたはアラートを一括削除するには、フィルタ名を含むJSONオブジェクトを作成し、HTTP POSTを使用してRESTコールのリクエスト本体でそれを送信します。次のインタフェースを使用します:

POST http://edqserver:8001/edq/cm/bulkdelete

POSTのペイロードは、次の属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
filter	文字列またはJSONオブジェクト	フィルタまたはインライン・フィルタ定義の名前。「JSON形式のフィルタ定義」を参照してください。
global	Boolean	trueに設定すると、グローバル・フィルタが指定されます。
deleteemptycases	Boolean	trueの場合、含まれているすべてのアラートが削除済のケースも削除されます。デフォルトは、falseです。

一括削除は非同期で実行されます。コールの結果は、実行に対応するキーを含むJSONオブジェクトです。

{
  "executionkey":"a279513d1ea44b0198094ac31ae68258"
}

このキーを使用して、実行の完了をポーリングできます。「一括操作の実行ステータスの確認」を参照してください。

一括削除操作を取り消す場合は、bulkoperationメソッドを使用します。「一括操作の取消し」を参照してください。

7.7 フィルタを使用したケースまたはアラートの一括更新

コールを行うユーザーには、ケース管理の一括更新権限と、状態変更定義で使用される遷移で定義された権限が必要です。

フィルタを使用してケースまたはアラートを一括更新するには、フィルタ名を含むJSONオブジェクトを作成し、HTTP POSTを使用してRESTコールのリクエスト本体でそれを送信します。次のインタフェースを使用します:

POST http://edqserver:8001/edq/cm/bulkupdate

POSTのペイロードは、次の属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
filter	文字列またはJSONオブジェクト	フィルタまたはインライン・フィルタ定義の名前。「JSON形式のフィルタ定義」を参照してください。
global	Boolean	trueに設定すると、グローバル・フィルタが指定されます。この値は、名前付きフィルタでのみ使用できます。
assignment	JSONオブジェクト	グループおよびユーザー割当ての定義。
statechanges	JSONオブジェクト	オリジン状態から遷移定義へのマップ。 statechangesは、フィルタに定義されているソースとケースのタイプがすべて同じワークフローにマップされる場合に指定できます。
edits	JSONオブジェクト	属性の編集。サポートされるキーは、description、priority、reviewflag、permission、stateexpiryおよびextendedattributeNです。

assignmentで使用されるオブジェクトには、次の属性があります:

プロパティ	タイプ	説明
groups	文字列の配列	グループ名のリスト。
users	文字列の配列	ユーザー名のリスト。nullを使用して、「未割当て」を指定します。
groupbycase	Boolean	trueに設定すると、ケースごとに割当てがグループ化されます。

editsオブジェクトには、次の属性を含めることができます:

プロパティ	タイプ	説明
description	String	ケースまたはアラートの説明。nullを使用して、現在の値をクリアします。
priority	Integer	0-3の範囲のケースまたはアラート優先度。
reviewflag	Boolean	レビュー・フラグ。
permission	String	ケースまたはアラート権限。
stateexpiry	日付	状態の有効期限のタイムスタンプ。
extendedattributeN	文字列、数値またはブール	拡張属性。

例

{ "filter": {
    "source": "WFP",
    "type": "alert",
    "state": ["one", "two"]
  },
 
  "statechanges": {
    "one": {
      "transition": "toThree",
      "comment": "one to three"
    }
  },
 
  "edits": {
    "description": "Alert description",
    "priority": 1,
    "extendedattribute3": "string 3",
    "extendedattribute1": true,
    "permission": "CMPermission1",
    "stateexpiry": "2024-12-10T00:00:00Z"
  },
 
  "assignment": {
    "groups": ["Administrators"],
    "users": ["user1", null]
  }
}

一括更新操作は非同期で実行されます。コールの結果は、実行に対応するキーを含むJSONオブジェクトです。

"executionkey":"a279513d1ea44b0198094ac31ae68258"

このキーを使用して、実行の完了をポーリングできます。「一括操作の実行ステータスの確認」を参照してください。

完了時に実行ステータスとともに戻される結果オブジェクトには、次の属性があります:

プロパティ	タイプ	説明
processed	Integer	一括更新中に処理されたケースまたはアラートの数。
rejected	Integer	ロックの問題により更新できなかったケースまたはアラートの数。
failedassignments	Integer	ユーザーに表示権限がないために割り当てられなかったケースまたはアラートの数。
failedtransitions	Integer	遷移が定義されているが、その遷移が拒否されたケースまたはアラートの数。

一括更新操作を取り消す場合は、bulkoperationメソッドを使用します。「一括操作の取消し」を参照してください。

7.8 レポートの実行

汎用フィルタを使用してケース管理レポートを実行するには、次のインタフェースを使用します:

http://edqserver:8001/edq/cm/report

POSTのペイロードは、次の表にリストされた属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
filter	JSONオブジェクト	フィルタ定義。
xaxis	文字列の配列	X軸の属性名。
yaxis	文字列の配列	Y軸の属性名。
xaggregation	数値または日付の集計	X軸の集計定義。
yaggregation	数値または日付の集計	Y軸の集計定義。

xaxisおよびyaxis属性は、X軸とY軸を形成するために使用される属性を指定します。属性名は、フィルタ定義で使用されます。集計定義が指定されている場合、対応する軸には単一の数値フラグまたは日付属性が必要です。集計属性がnullに設定されている場合、集計は実行されず、軸には離散値が含まれます。

数値フラグの集計定義には、次の表にリストされた属性があります:

プロパティ	タイプ	説明	デフォルト値
granularity	Number	軸の粒度。	10
offset	Number	オフセット	0
hideempty	Boolean	trueの場合、空の行/列を非表示にします。	false

日付の集計定義には、次の属性があります:

プロパティ	タイプ	説明	デフォルト値
granularity	Number	軸の粒度。YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTEまたはSECONDである必要があります。	MONTH
hideempty	Boolean	trueの場合、空の行/列を非表示にします。	false

7.9 ケースおよびアラートのエクスポート

ユーザーには、Excelへのエクスポートのケース管理権限が必要です。

ファイルまたはURLにケースおよびアラートをエクスポートする非同期操作を開始するには、次のインタフェースを使用します:

POST http://edqserver:8001/edq/cm/export

サポートされる出力形式は、JSON、JSON行、XLSXおよびCSVです。POSTのペイロードは、次の属性を含むJSONオブジェクトです:

プロパティ	タイプ	説明
filter	文字列またはJSONオブジェクト	フィルタまたはインライン・フィルタ定義の名前。「JSON形式のフィルタ定義」を参照してください。
global	Boolean	グローバル名前付きフィルタの場合はtrueに設定します。この値は、名前付きフィルタでのみ使用できます。
orderby	文字列の配列	列の順序付け。
sourcedata	Boolean	trueに設定すると、ソースおよび関係データが含められます(アラートのみ)。JSONおよびJSON行の出力でのみサポートされます。
limit	Number	エクスポート・ファイルに書き込まれるケースおよびアラートの数の制限。
destination	JSONオブジェクト	出力先の定義。
format	String	出力ファイル形式。json、jsonlines、xlsxまたはcsvである必要があります。
label	String	エクスポートを説明するオプションのラベル。このラベルは、一括ステータス・レポートで戻され、エクスポート・トリガーで使用できます。

destinationオブジェクトは必須であり、次の属性が含まれます:

プロパティ	タイプ	説明
location	String	(必須)パッケージ・ファイルのファイル名またはURL。絶対ファイル名以外が指定されている場合、その場所はローカル・ホーム構成ディレクトリが基準になります。
credentials	String	URLの場所へのリクエストを認証するために使用される格納済資格証明の名前。場所がファイルである場合、この値は無視されます。URLに単純なユーザー名/パスワード認証が必要な場合は、基本の格納済資格証明を使用します。
platformcredentials	Boolean	trueに設定すると、ファイルのアップロードおよびダウンロード操作にプラットフォーム資格証明が使用されます。Oracle Cloud Infrastructure (OCI)、Amazon Web Services (AWS)およびGoogle Cloud Platform (GCP)でサポートされます。
method	String	アップロードに使用されるHTTPメソッド。場所がファイルである場合、この値は無視されます。デフォルトのメソッドはPUTです。
multipart	String	大きいファイルのアップロードに使用されるマルチパート・メカニズム。サポートされる値は、aws、s3およびociです。awsとs3は同等です。

コールの結果は、実行に対応するキーを含むJSONオブジェクトです。

"executionkey":"a279513d1ea44b0198094ac31ae68258"

このキーを使用して、実行の完了をポーリングできます。「一括操作の実行ステータスの確認」を参照してください。

エクスポートが完了すると、/casemanagement/exportパスを使用してトリガーが実行されます。トリガーに渡される単一の引数は、次の属性を持つオブジェクトです:

プロパティ	タイプ	説明
failed	Boolean	エクスポートがエラーで完了した場合はtrueです。
cancelled	Boolean	エクスポートが取り消された場合はtrueです。
start	String	エクスポートが開始された日時。
end	String	エクスポートが完了した日時。
error	String	実行がエラーで完了した場合のエラー・メッセージ。この値は、failedがtrueである場合にのみ存在します。
userid	Integer	エクスポートを開始するユーザーのID。
label	String	実行エクスポート・ペイロードからコピーされたラベル。
location	String	出力場所。値は、絶対ファイル名またはURLです。
format	String	出力ファイル形式。

次に、出力ファイルを電子メール添付で送信するトリガーの例を示します:

addLibrary("usercache");
addLibrary("mail");
addLibrary("logging");
 
function getPath() {
  return "/casemanagement/export"
}
 
function run(path, id, env, status) {
  if (!status.failed && !status.cancelled) {
    logger.log(Level.INFO, "CM: {0}: {1} exported {2} to {3} ({4})", status.label, usercache.getUser(status.userid).userName, status.count, status.location, status.format)
 
    var mh  = Mail.open({enabled : true});
    var msg = mh.newMessage("An export from cm")
       
    msg.text = "Export complete"
    msg.addTo("someuser@example.com")
    msg.type = "text/plain";
    msg.addAttachment(status.location, "application/jsonl")
    msg.send()
  }
}

一括エクスポート操作を取り消す場合は、bulkoperationメソッドを使用します。「一括操作の取消し」を参照してください。

7.10 JSON形式のフィルタ定義

runfilter、bulkdelete、bulkupdateおよびエクスポートAPIで使用されるフィルタは、グローバル・フィルタの名前または検索条件を定義するJSONマップにすることができます。これらの条件には、ケース管理UIでサポートされている標準属性および拡張属性のいずれかを含めることができます。現在、ケースのコメントおよび遷移を使用した検索はサポートされていません。

runfilterペイロードでは、追加のorderby属性がサポートされます。これは、問合せの並替え基準列を定義する文字列の配列です。

次の表に、フィルタ・マップで使用可能な属性を示します:

プロパティ	タイプ	説明	Null値可能	否定可能
id	文字列または文字列の配列	ケースID。	いいえ	はい
internalid	整数または整数の配列	ケース内部ID。	いいえ	はい
key	String	ケース・キーのフリーフォーム・テキスト検索。	いいえ	いいえ
description	String	ケースの説明のフリーフォーム・テキスト検索。	いいえ	いいえ
source	文字列または文字列の配列	ソース名。	いいえ	いいえ
sourceid	文字列または文字列の配列	ソース識別子。	はい	はい
type	ケース/アラート・タイプ	"case"または"alert"である必要があります。	いいえ	いいえ
createdbyid	整数または整数の配列	ケースまたはアラートを作成したユーザーのID。	いいえ	はい
createdwhen	日付、日付の配列または日付範囲	ケースまたはアラートが作成された時点のタイムスタンプ。	はい	はい
modifiedbyid	整数または整数の配列	ケースまたはアラートを変更したユーザーのID。	いいえ	はい
modifiedwhen	日付、日付の配列または日付範囲	ケースまたはアラートが変更された時点のタイムスタンプ。	はい	はい
assigneduserid	整数または整数の配列	現在割り当てられているユーザーのID。ケースが割り当てられていない場合は-1を指定します。	いいえ	はい
assignedbyid	整数または整数の配列	直近の割当てを行ったユーザーのID。	いいえ	はい
assignedwhen	日付、日付の配列または日付範囲	直近の割当てのタイムスタンプ。	はい	はい
state	文字列または文字列の配列	現在の状態	いいえ	はい
statechangebyid	整数または整数の配列	直近の状態変更を行ったユーザーのID。	はい	はい
statechangedwhen	日付、日付の配列または日付範囲	直近の状態変更のタイムスタンプ。	はい	はい
stateexpiry	日付、日付の配列または日付範囲	ケースまたはアラート状態の有効期限のタイムスタンプ。	はい	はい
derivedstate	文字列または文字列の配列	導出状態	はい	はい
permission	文字列または文字列の配列	ケース権限。値は、ケース管理の管理で定義された内部キーです。	はい	はい
reviewflag	Boolean	新しいレビュー・フラグ。trueまたはfalseである必要があります。	いいえ	いいえ
reviewflagupdatedbyid	整数または整数の配列	直近のレビュー・フラグ変更を行ったユーザーのID。	はい	はい
reviewflagupdatedwhen	日付、日付の配列または日付範囲	直近のレビュー・フラグ変更のタイムスタンプ。	はい	はい
priority	整数または整数の配列	ケース優先度。値は0-3の範囲である必要があります。	はい	はい
extendedattributeN	値、配列または範囲	拡張属性n。	はい	はい
extendedattributeNmodifiedbyid	整数または整数の配列	拡張属性nに対する直近の変更を行ったユーザーのID。	はい	はい
extendedattributeNmodifiedwhen	日付、日付の配列または日付範囲	拡張属性nに対する直近の変更のタイムスタンプ。	はい	はい
sourceattributes	テストの配列へのソースのマップ	ソース属性および関係属性のフィルタ。「ソース属性を使用したフィルタ」を参照してください。

タイムスタンプ値を持つフィルタ属性については、「日付を使用したフィルタ」を参照してください。

拡張属性を使用したフィルタについては、「拡張属性のフィルタ」を参照してください。

「否定可能」列に「はい」がある属性テストの場合、"negated"という接尾辞が付けられたフィルタ名を持つブール属性を追加して、テストを反転できます。たとえば、次のフィルタ設定では、権限が設定されていないすべてのアラートを選択します:

"type": "alert",
"permission": null,
"permissionnegated": true

ソース属性を使用したフィルタ

sourceattributesフィルタ値は、ソースに関連付けられた属性および関係のテストの配列に対するソース名のマップです。テスト配列の各要素には、次の属性があります:

属性	タイプ	説明
input	String	ケース管理UIに表示される入力ストリームの名前。関係テストには、Relationshipsを使用します。
attribute	String	ケース管理UIに表示されるストリームの属性の名前。
value	オブジェクト	比較対象の値。値は、null、スカラー値、配列、または数値や日付の範囲です。
negated	Boolean	trueに設定すると、テストが否定されます。

各ソース名は、フィルタのsourceリストにも指定する必要があります。

inputおよびattributeの値は、ケース管理UIの「ブラウザ」ペインの「ソース属性」セクションに表示されるストリームおよびソース属性のラベルです。UIでは、ラベルを編集して、ストリームに同じラベルを複数回使用できます。フィルタであいまいなラベルが使用されている場合、APIはコールを拒否します。

たとえば:

{ "source": ["Screening", "Test"],
  "sourceattributes": {
    "Screening": [
      { "input": "workdata",
	    "attribute": "firstname",
	    "value": "j%"
      },
      { "input": "workdata",
        "attribute": "lastname",
        "value": ["kirk", "doohan"]
      }
    ],
    "Test": [
      { "input": "Relationships",
        "attribute": "Rule Name",
        "value": "R0012 or R002%",
        "negated": true
      },
      { "input": "Watchlist",
        "attribute": "dob",
        "value": { "from": "1990-01-01T00:00:00Z", "to": "2023-11-21T12:34:56Z" }
      }
    ]
  }
}

日付を使用したフィルタ

タイムスタンプであるフィルタ属性は、null、単一のISOタイムスタンプ文字列、タイムスタンプ文字列の配列、または日付範囲オブジェクトとして指定できます。タイムスタンプ文字列は、.mmmミリ秒の部分を省略できます。

たとえば、次はすべてcreatedwhen属性の有効な設定です:

"createdwhen": null
"createdwhen": "2023-10-11T12:34:56Z"
"createdwhen": ["2023-10-11T12:34:56Z", "2024-01-08T11:01:12Z"]
"createdwhen": {"from": "2023-01-01T00:00:00Z", "to": "2024-12-31T23:59:59Z"}

日付範囲オブジェクトには、次の属性を含めることができます:

属性	タイプ	説明
from	日付文字列	日付範囲の下限。fromまたはtoのいずれかの値を指定する必要があります。
to	日付文字列	日付範囲の上限。fromまたはtoのいずれかの値を指定する必要があります。
inclusive	Boolean	trueの場合、範囲に上限が含まれます。

拡張属性のフィルタ

extendedattributeNフィルタで指定される値は、関連付けられたフラグのタイプによって異なります。

次の表は、フラグ・タイプおよび関連付けられた値の形式を示しています:

ファイル・タイプ	値の形式
ブール	null、trueまたはfalse
文字列	null、文字列または文字列の配列
数値	null、数値、数値の配列または数値範囲

数値範囲は、次の属性を持つJSONオブジェクトで指定されます:

属性	タイプ	説明
from	日付文字列	数値範囲の下限。
to	日付文字列	数値範囲の上限。
inclusive	Boolean	trueの場合、範囲に上限が含まれます。

例:

"extendedattribute1": null,
"extendedattribute2": true,
"extendedattribute3": "string",
"extendedattribute4": ["monday", "tuesday"],
"extendedattribute5": 20,
"extendedattribute6": [2,4,5,8,37.4],
"extendedattribute7": {"from": 10, "to": 55, "inclusive": true]

7.11 一括操作の取消し

次のインタフェースを使用して、更新、削除、エクスポートなどの一括操作を取り消すことができます:

DELETE http://edqserver:8001/edq/cm/bulkoperation/EXECUTIONKEY

POSTコールのペイロードは、一括操作を開始したコールによって戻された実行キーを指定するexecutionkey属性を含むJSONオブジェクトです。

結果は、cancelled属性を含むJSONオブジェクトで、取消しリクエストを受信したときに操作が完了していなかった場合はtrueに設定されます。

7.12 一括操作の実行ステータスの確認

コールの実行時に結果として取得される実行キーを使用して、更新、削除、エクスポートなどの一括操作のステータスを確認できます。完了した実行のステータスは、完了後に1時間利用できます。

一括操作のステータスを取得するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cm/bulkstatus/EXECUTIONKEY

URLのEXECUTIONKEYコンポーネントは、前の一括削除コールから戻されたキーです。キーが不明な場合、リクエストは404エラーで失敗します。

POSTのペイロードは、次の属性を持つJSONオブジェクトです:

プロパティ	タイプ	説明
complete	Boolean	実行が完了した場合はtrueです。それ以外の場合はfalseです。
failed	Boolean	実行がエラーで完了した場合はtrueです。実行が完了していないか、エラーなしで終了した場合はfalseです。
start	String	実行が開始された開始日時。
end	String	実行が完了した開始日時。この値は、completeがtrueである場合にのみ存在します。
error	String	実行がエラーで完了した場合のエラー・メッセージ。この値は、completeおよびfailedがtrueである場合にのみ存在します。
result	オブジェクト	削除、更新またはエクスポートされたケースおよびアラートの数を含む結果オブジェクト。

たとえば:

{
  "complete": true,
  "failed": false,
  "start": "2022-08-24T17:34:44.990Z",
  "end": "2022-08-24T17:34:45.448Z",
  "result": {
    "count": 20
  }
}

7.13 ロード・テスト用の複数のフィルタの実行

複数の保存済フィルタおよびレポート・タイミングを実行するには、次のインタフェースを使用します:

POST http://edqserver:8001/edq/cm/filtertest?[?sql=false]

POSTのペイロードは、次の属性を含むJSONオブジェクトです:

プロパティ	タイプ	説明
filter	String	フィルタ名。
global	Boolean	trueに設定すると、グローバル・フィルタが指定されます。
count	Integer	フィルタの繰返し数。1つのテストでのフィルタ実行の合計数は、フィルタ実行スレッドの最大数を超えないようにしてください。デフォルトのフィルタ実行スレッドの制限は100です。スレッド制限を設定するには、`director.properties`に`cm.search.thread.limit`プロパティを設定します。

たとえば:

{
  "tests": [
    { "filter": "NAME1", "global": true, "count": 50 },
    { "filter": "NAME2", "global": true, "count": 50 },
    ...
  ]
}

コールの結果はJSONオブジェクトです:

{
  duration: total duration of tests in milliseconds,
  results: [
    { "filter": "NAME1", "global": true, "count": 50, "xids": [internal execution ids for each invocation] },
    ...
  ]
}

results配列要素のfilter、globalおよびcount属性には、入力オブジェクト内の値が反映されます。xidsは、フィルタの各実行の内部実行IDです。

7.14 ケース管理の管理REST APIの使用

REST APIを使用して、ケース・ソース、ワークフロー、権限およびグローバル・フィルタをリストおよび削除できます。これらのAPIは、主に自動RESTテスト・フレームワークで使用します。

ケース管理の管理REST APIのRESTインタフェースは、次のとおりです:

http://edqserver:8001/edq/cmadmin

このインタフェースでは、次のタスクを実行できます。

ケース・ソースのリストの取得

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があります。

ケース・ソースのリストを取得するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cmadmin/sources

結果は、それぞれ次の属性を含むオブジェクトの配列です:

プロパティ	タイプ	説明
name	String	ケース・ソースの名前。
prefix	String	ケース・ソースの接頭辞。
description	String	ケース・ソースの説明。
permission	String	ケース・ソースに関連付けられた権限。

ケース・ソースの削除

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があり、「ソースの削除」権限を持っている必要があります。

ケース・ソースを削除するには、次のインタフェースを使用します:

DELETE http://edqserver:8001/edq/cmadmin/source/NAME

このコールは、NAME属性で指定されたケース・ソースを削除します。

ケース・ワークフローのリストの取得

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があります。

ケース・ワークフローのリストを取得するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cmadmin/workflows

結果は、それぞれ次の属性を含むオブジェクトの配列です:

プロパティ	タイプ	説明
version	Number	ワークフローのバージョン。
name	String	ワークフローの名前。
label	String	ワークフローのラベル。
description	String	ワークフローの説明

ケース・ワークフローの削除

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があり、「ソースの削除」権限を持っている必要があります。

ケース・ワークフローを削除するには、次のインタフェースを使用します:

DELETE http://edqserver:8001/edq/cmadmin/workflow/NAME

このコールは、NAME属性で指定されたケース・ワークフローを削除します。

ケース管理動的権限のリストの取得

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があります。

ケース管理動的権限のリストを取得するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cmadmin/permissions

結果は、それぞれ次の属性を含むオブジェクトの配列です:

プロパティ	タイプ	説明
key	String	権限の内部キー。
name	String	権限の名前。
description	String	権限の説明。

ケース管理動的権限の削除

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があり、「ソースの削除」権限を持っている必要があります。

ケース管理動的権限を削除するには、次のインタフェースを使用します:

DELETE http://edqserver:8001/edq/cmadmin/permission/KEY

このコールは、KEY属性で指定されたケース管理動的権限を削除します。

ケース・グローバル・フィルタのリストの取得

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があり、「グローバル・フィルタの編集」権限を持っている必要があります。ユーザーが「グローバル・フィルタの編集」権限を持っていない場合、各フィルタに関連付けられた権限(存在する場合)によって結果がフィルタされます。

ケース・グローバル・フィルタのリストを取得するには、次のインタフェースを使用します:

GET http://edqserver:8001/edq/cmadmin/filters

結果は、それぞれ次の属性を含むオブジェクトの配列です:

プロパティ	タイプ	説明
name	String	フィルタ名。
description	String	フィルタの説明。
permission	String	フィルタに関連付けられた権限。
report	Boolean	フィルタでレポートを生成する場合はtrueです。

ケース・グローバル・フィルタの削除

ユーザーは、ケース管理の管理アプリケーションにアクセスできる必要があり、「グローバル・フィルタの編集」権限を持っている必要があります。

ケース・グローバル・フィルタを削除するには、次のインタフェースを使用します:

DELETE http://edqserver:8001/edq/cmadmin/filter/NAME

このコールは、NAME属性で指定されたケース・グローバル・フィルタを削除します。