拡張検索照会定義

拡張検索機能は、検索照会を定義する JSON スキーマを介して使用可能になります。

メイン構造

JSON 形式の拡張検索照会定義は、以下を指定する 4 つのメイン・セクションで構成されています。
  • 検索を実行する場所 (datasource フィールド)
  • そのデータを検索する必要があるデータ (population フィールド)
  • 検索で返されるためにソース・エントリーが一致する必要がある追加条件 (filters フィールド)
  • 結果のフォーマット設定と表示の方法 (output フィールド)

datasource

datasource セクションには、すべてオプションの以下のフィールドが含まれています。
  • datatype (string) は、取得するデータのタイプ ( TASKS または INSTANCES) を定義します。 TASKS がデフォルト値です。
  • systemTypes (ストリングの配列) は、データを取得するシステムのタイプ ( Process、 BPEL、 Case) を定義します。 デフォルト値は、データのタイプによって異なります。
    • Process および BPEL (タスクの場合)
    • Process および Case (インスタンスの場合)
  • systemFilter (オブジェクト) は、検索時に含める、または含めないシステムのリストを定義します。 これは、 includes と excludes の 2 つのフィールド (ストリングの配列) を持つオブジェクトで、検索に含めるシステムの ID または除外するシステムの ID をそれぞれリストします。
以下の例は、システム ID が「4a8a5317-808e-48fe-964e-ff489ed356ce」のものを除くすべてのシステムで BPD (プロセス) タスクおよび BPEL タスクを検索するための datasource セクションの詳細を示しています。
"datasource": {
    "datatype": "TASKS",
    "systemTypes": ["Process", "BPEL"],
    "systemFilter": {
        "excludes": ["4a8a5317-808e-48fe-964e-ff489ed356ce"]
    }
}
以下のもう 1 つの例は、すべてのシステムでケース・インスタンスを検索するための datasource セクションの詳細を示しています。
"datasource": {
    "datatype": "INSTANCES",
    "systemTypes": ["Case"]
}

population

population セクションは現在、単一のターゲットをサポートしており、検索照会から省略することができます。
  • target (string): SELF (独自のタスクおよびインスタンスの検索)
以下の例は、デフォルトの population セクションの詳細を示しています。
"population": {
    "target": "SELF"
}

filters

フィルターは、パブリック・タスクまたはインスタンス・フィールドに対する一連の条件です。 filters セクションで定義された追加条件に一致するタスクまたはインスタンスのみが、検索によって返されます。 filters セクションには、すべてオプションの以下のフィールドが含まれています。
  • interaction (string) は、プライベート・フィールドを利用して、状態によるフィルタリングを容易にします。 これは、「保存済み検索」の interaction フィールドに相当し、同じ値をサポートします。
    • claimed: 要求されたがまだ完了していないタスク (インスタンス検索には無効)
    • available: まだ要求されておらず、まだ完了していないタスク (インスタンス検索には無効)
    • claimed_and_available: まだ完了していないタスク (インスタンス検索には無効)
    • completed: 完了したタスクまたはインスタンス
    • active: まだ完了していないインスタンス (タスク検索には無効)
    • failed: 失敗したインスタンス (タスク検索には無効)
    • all: 現在の状態に関係なく、すべてのタスクおよびインスタンス。
    デフォルト値は allです。
  • caseScope (string) は、ケース・インスタンスの検索範囲です。 設定される値は、以下のとおりです。
    • Allowed: 母集団が表示を許可されているすべてのケース・インスタンス
    • Assigned: 母集団に割り当てられているケース・インスタンスのみ
    デフォルト値は Assignedです。
  • v1_conditions : 保存済み検索条件 (すべて一致する必要がある条件の配列)
  • v1_queryFilter (string): SQL に似た構文。 GET /v1/tasks および PUT /v1/instances REST API の queryFilter パラメーターと同じです。
  • v1_searchFilter (string): フルテキスト検索構文 ( GET /v1/tasks REST API の searchFilter パラメーターと同じ)。
  • json_query (オブジェクト): 条件の AND、OR、および NOT の組み合わせをサポートする新しい JSON 構文。 json_query フィルターは JSON オブジェクト (ツリー) です。 これらのフィールドは、 and、 or、および notと組み合わせることができる保存済み検索条件 (field、 operator、 value) です。
    以下の例は、JSON 構文での照会を示しています。
    
"json_query": {
    ”not": {
        ”or": [{
            "field": "taskPriority",
            "operator": "GreaterThan",
            "value": 100
        },
        {
            ”and": [{
                "field": "customer",
                "operator": "Equals",
                "value": ”ACME corp."
            },
            {
                "field": "product",
                "operator": "Equals",
                "value": "CP4BA"
            }]
        }]
    }
}
以下の例は、優先順位が 100 より高く、「ACME」ワード (すべてのタスク・フィールド値にわたるフルテキスト検索) を含む少なくとも 1 つのフィールドを持つ、要求されたタスクを取得するための filters セクションの詳細を示しています。
"filters": {
  "interaction": "claimed",
  "json_query": {
    "field": "taskPriority",
    "operator": "GreaterThan",
    "value": 100
  },
  "v1_searchFilter": "ACME"
}

output

output セクションは、すべてオプションの以下のフィールドに基づいて、結果を表示する方法を定義します。
  • fields (ストリングの配列): 各タスクまたはインスタンスについて返すフィールドのリスト。
  • includeAllBusinessData (boolean): すべてのビジネス・データ・フィールドを一度に返します。false がデフォルト値です。
  • usersFullName (boolean): 結果内のユーザーの情報 (フルネームまたはユーザー ID) をフォーマット設定する方法を指定します。 true がデフォルト値です。
  • aliases (オブジェクトの配列): 別名のリスト (保存済み検索の aliases フィールドと同じ)
  • sort (オブジェクトの配列): 結果のソート方法を指定します。 配列内の各オブジェクトには 2 つのフィールドがあります。 field (ストリング) は結果をソートするフィールドの名前で、 order (ストリング) は、結果を昇順または降順のどちらのフィールド値でソートするかに応じて、 ASC または DESC (デフォルトは ASC) のいずれかです。
  • alphabeticalSort (string): アルファベット順と辞書式の順序でソートします ( sort フィールドで参照されるストリング・フィールドの場合)。
  • size (整数): 応答内の結果の最大数 (デフォルトの数は 25)。
  • stats (オブジェクト): 結果とともに返す統計。 現時点では、( calcStats パラメーターを trueに設定して保存済み検索を実行する場合と同じ) 単一タイプの統計を返すことができます。これは、 stats オブジェクトの type (ストリング) パラメーターを Basic に設定することで指定します。
以下の例は、タスク・ナラティブ、タスク ID、インスタンス ID、リスクのあるタスク、および一致するタスクのすべてのビジネス・データを要求するタスク検索の output セクションの詳細を示しています。これらのデータは、リスクのあるタスク時刻の昇順でソートされ、最大 50 件の結果が表示され、結果とともに基本統計が表示されます。
"output": {
    "fields": ["taskNarrative", "taskId", "instanceId", "taskAtRiskTime"],
    "includeAllBusinessData": true,
    "sort": [{
        "field": "taskAtRiskTime",
        "order": "ASC"
    }],
    "size": 50,
    "stats": {
        "type": "Basic"
    }
}

再使用可能な検索照会のメタデータ

保存済み検索と同様に、再使用可能な検索照会 REST API を使用して、拡張検索照会定義を保管し、チームと共有することができます。

metadata

再使用可能な検索照会には、以下のフィールドを持つ追加の metadata (オブジェクト) フィールドがあります。
  • name (string): 再使用可能な検索照会の必須の固有名。
  • description (string): 再使用可能な検索照会の説明 (オプション)。
  • sharing (オブジェクト): 再使用可能な検索照会に関するオプション情報が共有されます。 これには、以下のフィールドが含まれます。
    • shared (boolean): 他のユーザーと共有する場合は true 、それ以外の場合は false (デフォルト値)
    • teams (オブジェクトの配列): 検索照会を共有するプロセス・チームのリスト。 shared が trueのときに null、 undefined 、または空の場合、検索照会はすべてのユーザーに共有されます。 自分がメンバーまたはマネージャーである特定のプロセス・チームと共有するには、プロセス・チーム ID としてフィールド teamId を持つオブジェクトを使用して、このチームを配列に定義します (単一値が現在サポートされていることに注意してください)。
  • owner (オブジェクト): 再使用可能な検索照会を所有するユーザーに関する情報
  • creator (オブジェクト): 再使用可能な検索照会を作成したユーザーに関する情報
  • lastUpdater (オブジェクト): 再使用可能な検索照会を最後に更新したユーザーに関する情報
  • creationDate (string): 再使用可能な検索照会が作成されたときの ISO8601 タイム・スタンプ
  • lastUpdateDate (string): 再使用可能な検索照会が最後に更新されたときの ISO8601 タイム・スタンプ
以下の例は、再使用可能な検索照会の metadata セクションの詳細を示しています。
"metadata": {
    "name": "my tasks list",
    "description": "a search query that retrieves my task list",
    "sharing": {
        "shared": true,
        "teams": [{
            "teamId": "24.6615a4b0-fd38-4ea5-8bc0-69d2f107369e",
            "teamName": "Human Resources",
            "processAppName": "Hiring Sample"
        }],
    },
    "owner": {
        "id": "jane.doe@acme.com",
        "fullName": "Jane Doe"
    },
    "creator": {
        "id": "admin@acme.com",
        "fullName": "Administrator"
    },
    "lastUpdater": {
        "id": "user.name@ibm.com",
        "fullName": "User Name"
    },
    "creationDate": "2024-01-31T12:34:42.183Z",
    "lastUpdateDate": "2024-02-01T16:03:12.874Z"
}