ルールエンジンのCall External APIアクションでGainsightのTimelineAPIを呼び出してアクティビティを登録する

目的

この記事では、Gainsightのルールエンジンを使用して、GainsightAPIを呼び出し、Timeline APIを通じてアクティビティを登録する方法を説明します。具体的には、CSVファイルからRelationshipのタイムラインアクティビティにデータを登録する手順を紹介します。

この記事で紹介する方法は、ルールエンジンから「Single Activity Save API」を利用する方法のため、データを１行挿入するたびにAPIをコールしますので、スロットル制限に注意する必要があります。少量のデータであれば1回のルールでアクティビティを取り込むことができますが、データ量が多い場合は、ルールエンジンを利用しないBulk Activity Save API を利用したこちらの方法をご参照ください。

シナリオ

CSVファイルからRelationshipのタイムラインアクティビティにデータを登録する。

手順

CSVファイルを準備してS3にUPする

CSVファイルに必要なデータを入力します。以下は例です：

ContextName,TypeName,ExternalId,Subject,Notes,ActivityDate,Author,CompanyName,RelationshipName,Ant__jie_guo__c,internalAttendees,externalAttendees
Relationship,会議,1234567890,超会議,重要な会議,2024-05-16T01:00:00.000+09:00,mnishimi@gainsight.com,Mariko Test 商事,導入サービス,,xxx@gainsight.com,yyy@gainsight.com
...

完成したCSVファイルをS3バケットにアップロードします。

カスタムコネクタを作成する
- コネクタ2.0の設定画面に移動します。
- 新しいカスタムコネクタを作成し、Gainsightの APIエンドポイントを設定します。
  認証タイプはトークンベースで、ヘッダーにはAccesskey→アクセスキーを入れます。（アクセスキーはGenerate API Access Key参照）URLにはインスタンスのホスト名を入力して保存します。接続テストしてもエラーになりますが気にしなくてOKです。
  ※参考：Configure Custom Connectors

ExternalActionを作成する

作成したカスタムコネクタを使用して、外部アクションを作成します。
External Actionの設定画面で、APIリクエストの詳細を入力します。

設定は以下のようにします。

BasicInformation
- HTTPメソッド：POST
- URL：https://ホスト名.gainsightcloud.com/v1/ant/es/activity

Payload（以下はサンプル）

{
  "records": s
    {
      "ContextName": "Relationship",
      "TypeName": "{{TypeName}}",
      "ExternalId": "{{ExternalId}}",
      "Subject": "{{Subject}}",
      "Notes": "{{Notes}}",
      "ActivityDate": "{{ActivityDate}}",
      "Author": "{{Author}}",
      "CompanyName": "{{CompanyName}}",
      "GsRelationshipTypeId": "{{GsRelationshipTypeId}}",
      "RelationshipName": "{{RelationshipName}}",
      "internalAttendees":"{{internalAttendees}}",
      "externalAttendees":"{{externalAttendees}}"
      }
  ],
    "lookups": {
        "AuthorId": {  
            "fields": {
                "Author": "Email" 
            },
            "lookupField": "Gsid",
            "objectName": "GsUser",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        },
     "GsCompanyId": {
       "fields": {
         "CompanyName": "Name"
       },
      "lookupField": "Gsid",
      "objectName": "Company",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
     },
      "GsRelationshipId": {
        "fields": {
           "RelationshipName": "Name"
         },
         "lookupField": "Gsid",
         "objectName": "Relationship",
         "multiMatchOption": "FIRSTMATCH",
         "onNoMatch": "ERROR"
       },
        "InternalAttendees": {
            "fields": {
                "internalAttendees": "Email"
            },
            "lookupField": "Gsid",
            "objectName": "GsUser",
            "multiMatchOption": "MARKASERROR"
        },
      "ExternalAttendees": {
        "fields": {
            "externalAttendees": "Person_ID__gr.Email",
            "GsCompanyId": "Company_ID"
        },
        "lookupField": "Gsid",
        "objectName": "Company_Person",
        "multiMatchOption": "FIRSTMATCH"
       }
    }
}

ペイロードが正しいかどうか、テストして確認します。
※参考：Configure External Actions

ルールエンジンを作成する
- Gainsightのルールエンジンを開き、新しいルールを作成します。
- データソースとしてS3バケット内のCSVファイルを指定します。
  ※ISO 8601 formatに沿ったCSVファイルを準備しているので、ActivityDateはStringでセットしておきます。
  Gainsight内の日時データを利用する場合はこちらの記事を参照して下さい。
- 先ほど作成したExternal Actionをルールに追加しフィールドをペイロードにマッピングします。
  
  ※参考：Call External API Action Type
ルールエンジンを実行する
- ルールエンジンを実行し、CSVファイルのデータがGainsightのTimeline APIを通じてアクティビティとして登録されることを確認します。
その他

実行結果の詳細は、ExternalActionsのカスタムアクションのExecutionHistoryから確認することができます。
ただし、APIコール結果に何らかのエラーが発生してもルールエンジン実行結果はエラーとなりません。ExternalActionsのカスタムアクションのExecutionHistoryのResponse内に、エラーがある場合はエラーコードが表示されますのでそこを確認する必要があります。