Automation Center API

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：21分

    • オートメーションセンター API は、プロセス、ロボット、および実行ジョブを作成および更新するためのエンドポイントを提供します。

    この API を使用して、繰り返されるタスクのエンドツーエンドの自動化を定義し、それらのタスクを管理および監視できます。

    この API を使用すると、ServiceNow インスタンス内で次のタイプのイベントを作成できます。
    • ロボット：ボットプロセスを実行するソフトウェアエージェント。RPA ロボットは、有人または無人で実行できます。
    • プロセス：特定のロボット上の RPA のインスタンス。ジョブの実行を担当します。プロセスを一意に識別するには、プロセス ID とロボット ID の両方を指定する必要があります。
    • 実行：ロボットプロセスで実行する特定のタスク。たとえば、あるリソースから情報をコピーして別のリソースにコピーするタスクなど (メールからスプレッドシートに情報をコピーする場合など) です。
    たとえば、この API を使用して、アプリケーションへのログイン、情報のコピーと貼り付け、ドキュメントとファイルの移動や、メール、PDF、フォームからのコンテンツの抽出を行うことができます。

    通常、最初にロボットを作成し、その後でそのロボットに関連付けられたプロセスを作成する必要がありますが、これは API による強制ではありません。ただし、ロボットとプロセスのジョブ実行を試行する前に、ロボットとプロセスを作成する必要があります。作成しなければジョブ要求は失敗します。

    注:
    • この API を使用してイベントを削除することはできません。デフォルトでは、イベントは 14 日後にインスタンスから自動的に削除されます。
    • 1 回の呼び出しで最大 2,000 件のレコードを渡すことができます。この値は変更できません。

    この API を使用するには、Automation Center プラグインがアクティブになっており、ユーザーが sn_as.automation_technical_user または sn_ac.automation_admin のいずれかのロールを持っている必要があります。

    Automation Center - POST /sn_ac/automation/rpa

    ロボット、プロセス、および実行イベントを作成します。

    これらのイベントはプロセスの自動化を提供します。Automation Center の概要および実行ダッシュボードに表示され、複数の RPA ベンダーからの出力を測定および監視します。

    URL 形式

    バージョニングされた URL：/api/sn_ac/{api_version}/automation/rpa

    デフォルトの URL：/api/sn_ac/v1/automation/rpa

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    departmentName プロセスおよびロボットイベントタイプのみ。イベントが属する部門の名前。
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの department フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの department フィールド。

    データタイプ：文字列
    domainId イベントが属するドメインの sys_id。
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • execution：自動化実行 [sn_ac_automation_execution] テーブルの sys_domain フィールド。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの sys_domain フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの sys_domain フィールド。

    データタイプ：文字列
    endtime 実行イベントタイプのみ。実行の終了時刻。この値は、自動化実行 [sn_ac_automation_execution] テーブルの end_time フィールドに保存されます。

    形式：YYYY-MM-DD HH:MM:SS

    データタイプ：文字列
    environment 実行イベントタイプのみ。実行の環境 (URL など)。この値は、自動化実行 [sn_ac_automation_execution] テーブルの environment フィールドに保存されます。
    注:
    この値は ServiceNow インスタンスでは使用されず、実装に必要な値を含めることができます。

    データタイプ：文字列
    errorMessage 実行イベントタイプのみ。エラーメッセージログの名前。この値は、自動化実行 [sn_ac_automation_execution] テーブルの message フィールドに保存されます。

    データタイプ：文字列
    eventName 必須です。イベントタイプの名前。この値は、処理するイベントのタイプを決定します。
    有効な値 (大文字と小文字を区別)：
    • execution
    • process
    • robot

    データタイプ：文字列
    id 必須です。関連付けられたイベントの数値による一意の識別子。
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • execution：自動化実行 [sn_ac_automation_execution] テーブルの automation_execution_id フィールド。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの correlation_id フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの correlation_id フィールド。

    データタイプ：整数
    name プロセスおよびロボットイベントタイプのみ。必須です。イベントの名前。
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの name フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの name フィールド。

    データタイプ：文字列
    priority 実行イベントタイプのみ。実行の優先度。
    可能な値 (大文字と小文字を区別)：
    • Critical
    • High
    • 中程度
    • Low
    この値は、自動化実行 [sn_ac_automation_execution] テーブルの priority フィールドに保存されます。

    データタイプ：文字列

    デフォルト：なし - ダッシュボードに表示されません
    processId 実行イベントタイプのみ。必須です。実行を実行するプロセスの一意の識別子。この値は、Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの対応するプロセスレコードの correlation_id フィールドにあります。

    その後、この値は、自動化実行 [sn_ac_automation_execution] テーブルの automation フィールドに保存されます。

    データタイプ：文字列
    robotId 実行イベントタイプのみ。必須です。実行を実行するロボットの一意の識別子。この値は、Base ロボット [cmdb_ci_base_rpa_robot] テーブルの対応するロボットレコードの correlation_id フィールドにあります。

    その後、この値は、自動化実行 [sn_ac_automation_execution] テーブルの robot フィールドに保存されます。

    データタイプ：文字列
    source 必須です。イベントが属するソース (「servicenow_rpa」など)。この値は、自動化ソース [sn_ac_automation_source] テーブルの internal_name フィールドにあります。
    その後、この値は、イベントタイプに応じて次のテーブルに保存されます。
    • execution：自動化実行 [sn_ac_automation_execution] テーブルの Source フィールド。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの Source フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの Source フィールド。

    データタイプ：文字列
    starttime 実行イベントタイプのみ。実行の開始時刻。この値は、自動化実行 [sn_ac_automation_execution] テーブルの start_time フィールドに保存されます。

    形式：YYYY-MM-DD HH:MM:SS

    データタイプ：文字列
    state ロボットおよび実行イベントタイプのみ。関連付けられたイベントのステータス。
    ロボットの可能な値 (大文字と小文字を区別)：
    • Cancelled
    • 完了
    • エラー
    • キューに格納
    • Running
    デフォルト：Queued
    実行の可能な値 (大文字と小文字を区別)：
    • Available
    • Busy
    • Disconnected
    • New
    • Responsive
    デフォルト：New
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • execution：自動化実行 [sn_ac_automation_execution] テーブルの state フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの robot_state フィールド。

    データタイプ：文字列
    status プロセスイベントタイプのみ。必須です。プロセスのステータス。
    可能な値 (大文字と小文字を区別)：
    • Build
    • In Maintenance
    • In Use
    • Retired
    この値は、Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの life_cycle_stage_status フィールドに保存されます。

    データタイプ：文字列
    triggeredBy 実行イベントタイプのみ。実行のトリガーソース。この値は、自動化実行 [sn_ac_automation_execution] テーブルの trigger_by フィールドに保存されます。
    注:
    この値は ServiceNow インスタンスでは使用されず、実装に必要な値を含めることができます。

    データタイプ：文字列
    type プロセスおよびロボットイベントタイプのみ。プロセスの場合は必須、ロボットの場合はオプションです。実行する処理のタイプ。
    可能な値 (大文字と小文字を区別)：
    • Attended
    • Unattended
    この値は、イベントタイプに応じて次のテーブルに保存されます。
    • process：Base ボットプロセス [cmdb_ci_base_rpa_process] テーブルの process_type フィールド。
    • robot：Base ロボット [cmdb_ci_base_rpa_robot] テーブルの robot_type フィールド。

    データタイプ：文字列

    デフォルト：ロボットの場合は Unattended
    version ロボットイベントタイプのみ。ロボットのバージョン。

    この値は、Base ロボット [cmdb_ci_base_rpa_robot] テーブルの version フィールドに保存されます。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 失敗。必須フィールドがないか、要求に無効な値が含まれているために、要求は却下されました。関連するエラーメッセージに失敗の理由が記載されています。

    応答本文のパラメーター

    名前 説明
    result 要求が成功した場合は空です。失敗の場合は、追加情報が提供されます。

    データタイプ：オブジェクト

    "result": {
  "fields": {
    "<record_number>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "reason": "String"
}
    たとえば、レコード 1、2、および 3 のすべてに必須フィールドがない場合は、次のようなメッセージが返されます。
    {
  "result": {
    "fields": {
      "1": [
        "id"
      ],
      "2": [
        "status"
      ],
      "3": [
        "name"
      ]
    },
    "reason": "We are not able to process the data as following records have insufficient data"
  }
}

    cURL 要求

    次のコード例は、3 つのロボットイベントタイプレコードをポストする方法を示しています。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 8001,
    name: "Quotes system Automation Robot",
    state: "Available",
    status: "In Use",
    version: 5.6,
    departmentName: "Customer Support",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8002,
    name: "Invoice Matching Robot",
    state: "Responsive",
    status: "In Maintenance",
    version: 3,
    departmentName: "HR",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8003,
    name: "Data Reconciliation Robot",
    state: "Busy",
    status: "Retired",
    version: 2,
    departmentName: "Finance",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  }]
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、3 つのプロセスイベントタイプレコードをポストする方法を示しています。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 9001,
    name: "RPA Execution Process",
    status: "In Maintenance",
    type: "Attended",
    departmentName: "Customer Support",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9002,
    name: "Customer Onboarding",
    status: "In Use",
    type: "Attended",
    departmentName: "Finance",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9003,
    name: "Data Reconciliation",
    status: "Retired",
    type: "Unattended",
    departmentName: "HR",
    source: "servicenow_rpa",
    eventName: "process"
  }]
}" \
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、3 つの実行イベントタイプレコードをポストする方法を示しています。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 7001,
    name: "Customer Onboarding",
    starttime: "2022-03-18 00:49:13",
    endtime: "2022-03-20 00:58:03",
    state: "Running",
    priority: "Critical",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9001,
    robotId: 8001,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7002,
    name: "Data Reconciliation",
    starttime: "2022-04-30 00:19:11",
    endtime: "2022-05-02 00:41:35",
    state: "Error",
    priority: "Low",
    environment: "system",
    triggeredBy: "API",
    processId: 9002,
    robotId: 8002,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7003,
    name: "Customer Onboarding",
    starttime: "2022-01-22 02:38:53",
    endtime: "2022-01-23 02:50:44",
    state: "Queued",
    priority: "Moderate",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9003,
    robotId: 8003,
    source: "servicenow_rpa",
    eventName: "execution"
  }]
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、プロセスを作成または更新する方法を示しています。プロセスを作成するには、プロセスを実行するためのすべての必須パラメーターと、「process」に設定した eventName を渡します。プロセスの作成に必要な必須パラメーターは、id、type、status、name、および source です。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9001,
name: "RPA Execution Process",
status: "In Maintenance",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、プロセスを公開する方法を示しています。プロセスを公開するには、「Published」に設定した status パラメーターを渡します。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9002,
name: "RPA Execution Process",
status: "Published",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、ロボットを作成または更新する方法を示しています。ロボットを作成するには、ロボットのすべての必須パラメーターと、「robot」に設定した eventName を渡します。ロボットの作成に必要な必須パラメーターは、id、status、name、および source です。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 8001,
name: "Quotes system Automation Robot",
state: "Available",
status: "In Use",
version: 5.6,
departmentName: "Customer Support",
type: "Unattended",
source: "servicenow_rpa",
eventName: "robot"
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None

    cURL 要求

    次のコード例は、実行を作成または更新する方法を示しています。実行を作成するには、実行のすべての必須パラメーターと、「execution」に設定した eventName を渡します。実行の作成に必要な必須パラメーターは、id、processId、robotId、および source です。

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 7001,
name: "Customer Onboarding",
starttime: "2022-03-18 00:49:13",
endtime: "2022-03-20 00:58:03",
state: "Running",
priority: "Critical",
environment: "http://acqa.servicenow.com",
triggeredBy: "Schedule",
processId: 9001,
robotId: 8001,
source: "servicenow_rpa",
eventName: "execution",
errorMessage:"Error due to Inactivity"
}]
} "\
--user "username":"password"

    このエンドポイントは、成功した場合には HTTP ステータスコードのみを返し、失敗した場合は HTTP ステータスコードとエラーメッセージを返します。

    None