タスクとプレイブックAPIドキュメンテーション

はじめに

Gainsightでは、ユーザーがタスクを作成及び更新できるようになり、コックピットリセットAPIを使ってタスクとプレイブックの詳細を取得することもできます。

ビジネスユースケース: コックピットデータにアクセスすることで恩恵を受けるすべてのチームが常にGainsightを使用しているわけではありません。彼らは自分たちで選んで使っているシステムを持っており、Gainsightがそれらとよりよく統合することを期待しています。開発リソースをお持ちのお客様は、APIを使用して、Gainsightと他のシステムとの間で、より緊密でカスタマイズされた統合を構築できます。これらのAPIにより、ユーザーはコックピットデータを統合し、ワークフローを他のシステムで構築することが可能です。

ユーザーはコックピットリセットAPIを使って次のアクションを実行することができます:

タスクの作成：これにより、既存のCTAの新しいタスクが作成されます。
更新タスク：これにより、既存のタスクの詳細が更新されます。
タスクの取得：これにより、CTAに関連付けられているタスクの一覧が返されます。
プレイブックの取得：これにより、プレイブックの設定が取得され、CTAに適用されます。

認証する

API アクセスは、固有のアクセスキーを使用して制御されます。REST API要求を送信するGainsightテナントのアクセスキーを取得するにはGainsight 管理者に連絡してください。アクセスキーを生成または共有する方法の詳細については、Gainsight 管理者は API アクセスキーの生成 の記事を参照できます。
アクセスキーを取得した後は、GainsightへのすべてのAPIリクエストのリクエストヘッダー「accesskey」の一部として、アクセスキーを渡す必要があります。

注意：AccessKeyに有効期限はありません。

ヘッダー

キー	値
アクセスキー：	アクセスキーを生成する方法の詳細については、「認証する」セクションを参照してください。
コンテンツタイプ	JSON

タスクAPIの作成

タスクAPIの作成はGainsightで新しいCSタスクを作成するために使われます。会社ID/関係ID、CTA ID、タスク名、所有者ID入力などの必須フィールドを渡して、タスクを作成することができます。

会社IDと所有者IDについては、任意の識別子を使って、対応する会社に結合することができます。

注意：ユーザーは一度に1つのタスクのみを作成/更新することができます。

ユーザーは日付フィールドをYYYY-MM-DD形式で入力する必要があります。

ユーザーはタスクを作成するときに入力する追加のフィールド (CSタスクオブジェクトのフィールド) を渡すことができます。参照IDはエラーが発生したタスクの作成を返すために使われます。CSタスクのセットに対して任意の一意の値を指定することができます。

タイプ、ステータス、プライオリティの正しい値が渡されることを確認するのは、APIを呼び出すアプリケーション次第です。構成が一致しない場合は、エラーが表示されます。

注意：このAPIを使って作成されたタスクはCSタスクであり、Eメールタスクではありません。

方法の詳細

APIの詳細	説明
リクエスト方法	ポスト
リクエストパラメータ	該当なし
リクエストエンドポイント	/v2/cockpit/task

リクエストのサンプル

{
  "requests": [
      {
          "record": {
              "referenceId": "123",
              "CtaId": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
              "Name": "Ext-T5",
              "OwnerEmail": "athakur@gainsight.com",
              "DueDate": "2020-05-09",
              "status": "New",
              "priority": "High",
              "Description": "Hey!! How are you!!",
              "DT_Boolean__gc": true,
              "DT_Currency__gc": "43.68",
              "DT_Date__gc": "2020-05-19",
              "DT_DateTime__gc": "2020-06-16T12:30:00Z",
              "DT_Picklist__gc": "New Customer",
              "DT_Email__gc": "test123@test.com",
              "DT_GSID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
              "DT_MultiPicklist__gc": "A; B",
              "DT_Number__gc": "30.40",
              "DT_Percentage__gc": "97.56",
              "DT_RTA1__gc": "HEY, Anything New in coding world!!",
              "DT_WhoID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
              "DT_String__gc": "Test",
              "DT_URL__gc": "http://localhost:8091/v2/cockpit/task/",
              "CompanyLookup": "IBM",
              "DT_CompanyNameLookup__gc": "IBM",
              "OwnerLookup": "athakur@gainsight.com"
          }
      }
  ],
  "lookups": {
      "OwnerId": {
          "fields": {
              "OwnerEmail": "Email"
          },
          "lookupField": "Gsid",
          "objectName": "gsuser",
          "multiMatchOption": "FIRSTMATCH",
          "onNoMatch": "ERROR"
      },
      "DT_UserLookup__gc": {
          "fields": {
              "OwnerLookup": "Email"
          },
          "lookupField": "Gsid",
          "objectName": "gsuser",
          "multiMatchOption": "FIRSTMATCH",
          "onNoMatch": "ERROR"
      },
      "DT_CompanyIDLookup__gc": {
          "fields": {
              "CompanyLookup": "Name"
          },
          "lookupField": "Gsid",
          "objectName": "company",
          "multiMatchOption": "FIRSTMATCH",
          "onNoMatch": "ERROR"
      }
  }
}

応答成功のサンプル

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "65eddbcf-3bbc-4c49-9f41-ea43536d2fe0",
  "data": {
      "success": [
          {
              "123": "1S032PUJRW05J6NDZ5QJ6SAGPRTLHPMPMLJ4"
          }
      ],
      "failure": []
  },
  "message": null
}

応答失敗のサンプル

応答失敗のサンプル:

{
    "result": false,
    "errorCode": <ERROR_CODE>,
    "errorDesc": <ERROR_DESC>, // If the issue comes while resolving the request
    "requestId": <REQUEST_ID>,   
    "data": {
        "success": [],
        "failure": [
        {
            "1": "ERROR_MESSAGE" // Reference ID to highlight issue when creating
        }
      ]
    },
    "message": null
}

無効なルックアップオブジェク構成のリクエスト (HTTPステータス：400):

{
    "result": false,
    "errorCode": "COCKPIT_9703",
    "errorDesc": "Following lookup field have invalid filter configuration to resolve - DT_UserLookup__gc -> gsuser: UserLookup",
    "requestId": "8e35c24e-adf4-46fa-a0b5-48e26af1fbd7",
    "data": {},
    "message": null
}

タスクAPIの更新

タスクAPIの更新はGainsightで新しいCSタスクを更新するために使われます。このAPIにCSタスクID (GSID) と参照IDを強制的に渡して、更新する CSタスクを識別し、結果をフォーマットしてタスクを作成する必要があります。

ユーザーはCSタスクを更新するフィールドとその値のリストを渡すことができます。更新の成功又は失敗 (理由付き) が応答で送信されます。

以下は、期日の利用可能なカスケードオプションです:

ALL_OPEN_TASKS (Default)
OPEN_TASKS_AND_CTA
いいえ

方法の詳細

APIの詳細	説明
リクエスト方法	入力
リクエストパラメータ	該当なし
リクエストエンドポイント	/v2/cockpit/task

リクエストのサンプル

{
    "requests": [
        {
            "record": {
                "referenceId": "ID1",
                "gsid":"1S032PUJRW05J6NDZ5CIQGVI96XQP7SUCYGV",
                "Name": "Covid-task1---update1",
                "OwnerEmail": "mkandagatla@gainsight.com",
                "DueDate": "2020-06-30",
                "status": "Open",
                "priority": "High",
                "Description": "Hey!! How are you!!",
                "DT_Boolean__gc": false,
                "DT_Currency__gc": "45.68",
                "DT_Date__gc": "2020-07-19",
                "DT_DateTime__gc": "2020-07-16T12:30:00Z",
                "DT_Picklist__gc": "New Customer",
                "DT_Email__gc": "test12345@test.com",
                "DT_GSID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
                "DT_MultiPicklist__gc": "A; B",
                "DT_Number__gc": "30.40",
                "DT_Percentage__gc": "97.56",
                "DT_RTA1__gc": "HEY, Anything New in coding world!!",
                "DT_WhoID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
                "DT_String__gc": "Test",
                "DT_URL__gc": "http://localhost:8091/v2/cockpit/task/v2",
                "CompanyLookup": "IBM",
                "DT_CompanyNameLookup__gc": "IBM",
                "OwnerLookup": "athakur@gainsight.com",
                "dueDateCriteria":"OPEN_TASKS_AND_CTA"
            }
        }
    ],
    "lookups": {
        "OwnerId": {
            "fields": {
                "OwnerEmail": "Email"
            },
            "lookupField": "Gsid",
            "objectName": "gsuser",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        },
        "DT_UserLookup__gc": {
            "fields": {
                "OwnerLookup": "Email"
            },
            "lookupField": "Gsid",
            "objectName": "gsuser",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        },
        "DT_CompanyIDLookup__gc": {
            "fields": {
                "CompanyLookup": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }
    }
}

応答成功のサンプル

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "1e6cc9fa-2291-4fdc-99f1-af11f50b709b",
    "data": {
        "success": [
            {
                "ID1": "1S032PUJRW05J6NDZ5CIQGVI96XQP7SUCYGV"
            }
        ],
        "failure": []
    },
    "message": null
}

応答失敗のサンプル

{
    "result": false,
    "errorCode": <ERROR_CODE>,
    "errorDesc": <ERROR_DESC>, // If the issue comes while resolving the request
    "requestId": <REQUEST_ID>,  
    "data": {
        "success": [],
        "failure": [
        {
            "REFERENCE_ID": "ERROR_MESSAGE" // If the issue comes while processing the records
        }
      ]
    },
    "message": null

}

タスクリストAPIの取得

タスクリストAPIの取得は、Gainsightでタスクのリストを取得するために使われます。1回のリクエストで最大1000個のタスクを取得できます。それ以上ある場合は、ページ番号/ページサイズを使って、全てのタスクの詳細を取得します。

方法の詳細

APIの詳細	説明
リクエスト方法	ゲット
リクエストパラメータ	pn - ページ番号 (必須 = 誤) - (デフォルト値 - 1) pn - ページサイズ (必須 = 誤) - (デフォルト値 - 1000) 含む - 選択に表示するフィールドをさらに含める (必須 = 誤) - (デフォルトフィールド - 表示する必須フィールドの限定セット)
パスパラメータ	CTAのGSID
リクエスト本文	なし
リクエストエンドポイント	/v2/cockpit/task/list/<CTA_GSID>
リクエストURLのサンプル：クエリパラメータのない[取得]呼び出し	/v2/cockpit/task/list/<CTA_GSID>
リクエストURLのサンプル：ページ番号とサイズを指定した[取得]呼び出し	/v2/cockpit/task/list/<CTA_GSID>?pn=1&ps=500
リクエストURLのサンプル：includesを使用した[取得]呼び出し	/v2/cockpit/task/list/<CTA_GSID>?includes=DT_Date__gc,DT_DateTime__gc

応答のサンプル

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "0eb5d905-9a0c-479e-b423-809eb0ded6bf",
  "data": [
      {
          "ClosedDate": "2020-05-21",
          "CtaId__gr.Name": "Ext. API 12.31",
          "DueDate": "2020-05-20",
          "Gsid": "1S032PUJRW05J6NDZ52CIIS4W30AE8L6G2TF",
          "IsClosed": true,
          "Name": "T2",
          "OwnerId__gr.Name": "Ankush Thakur",
          "PriorityId__gr.Name": "Medium",
          "StatusId__gr.Name": "Closed Success",
          "TypeId__gr.Name": "Task"
      },
      {
          "CtaId__gr.Name": "Ext. API 12.31",
          "DueDate": "2020-05-20",
          "Gsid": "1S032PUJRW05J6NDZ5LXU7O2V74YIBZOJQ9Y",
          "IsClosed": false,
          "Name": "T1",
          "OwnerId__gr.Name": "Ankush Thakur",
          "PriorityId__gr.Name": "Medium",
          "StatusId__gr.Name": "New",
          "TypeId__gr.Name": "Task"
      }
  ],
  "message": null
}

プレーブック構成の取得 (getPlaybookConfig) API

プレーブック構成の取得APIは、全てのプレーブック構成のリストを取得するために使われます。「Et」は、選択リスト構成が返されるエンティティタイプに使われます。「Etid」は関係タイプIDである関係のエンティティIDです。

方法の詳細

APIの詳細	説明
リクエスト方法	ゲット
リクエストパラメータ	et - エンティティタイプ (必須 = 誤) entityId - エンティティタイプ (必須 = 誤) アクティブ - 正の場合はアクティブなプレイブックを提供し、値が渡されない場合はすべてのプレイブックを提供します (必須 = 誤) タイプ - 取得するプレーブックのタイプを指定できるタイプ名
リクエスト本文	なし
リクエストエンドポイント	/v2/cockpit/admin/playbook?active=true&et=COMPANY
アクティブなタイプが指定されたリクエストURLの例	/v2/cockpit/admin/playbook?active=true&et=COMPANY&type=Risk,Expansion
アクティブなタイプが指定されていないリクエストの例	/v2/cockpit/admin/playbook?et=COMPANY

応答のサンプル

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "47c07857-3c5f-4be7-94c6-35425c349451",
    "data": [
        {
            "name": "NPS® Promoter",
            "gsid": "1I0012M2PCTA9UHOTWU9URUYK9YA3NMHKZAQ",
            "active": true,
            "entityType": "GLOBAL",
            "typeId": "1I00650WACZ7F0X9HRGSO2D9AT5CEK0911SE",
            "typeName": "Expansion"
        },
        {
            "name": "Company All PB",
            "gsid": "1I0012M2PCTA9UHOTWA0IOL2KWQE67QDVAK9",
            "active": true,
            "entityType": "COMPANY",
            "typeId": "1I00650WACZ7F0X9HRJRX1GBJ9TG5ERJHGGY",
            "typeName": "ALL_CTA_TYPE"
        },
        {
            "name": "PB for Risk from Company",
            "gsid": "1I0012M2PCTA9UHOTWVWQUD5FQD306ZCETTA",
            "active": true,
            "entityType": "COMPANY",
            "typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "typeName": "Risk"
        },
        {
            "name": "Global All PB",
            "gsid": "1I0012M2PCTA9UHOTW0GONZA5YY73UXZEDYD",
            "active": true,
            "entityType": "GLOBAL",
            "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
            "typeName": "ALL_CTA_TYPE"
        },
        {
            "name": "mkRiskCompanyPb",
            "gsid": "1I0012M2PCTA9UHOTWETI540W8WP0IY4GKH0",
            "active": true,
            "entityType": "COMPANY",
            "typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "typeName": "Risk"
        },
        {
            "name": "Covid Email Tasks",
            "gsid": "1I0012M2PCTA9UHOTW0CQ6C8DGAZXF2ED5GH",
            "active": true,
            "entityType": "GLOBAL",
            "typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "typeName": "Risk"
        },
        {
            "name": "Covid Tasks",
            "gsid": "1I0012M2PCTA9UHOTWHMSXXRGOYN9QQXQG9N",
            "active": true,
            "entityType": "GLOBAL",
            "typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "typeName": "Risk"
        }
    ],
    "message": null
}

NPS、ネットプロモーター、およびネットプロモータースコアは、Satmetrix Systems, Inc.、Bain & Company、およびBain & Company and Fred Reichheldの登録商標です。