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

目的

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

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

シナリオ

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

手順

1. 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. カスタムコネクタを作成する

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

     

      

3. ExternalActionを作成する

   • 作成したカスタムコネクタを使用して、外部アクションを作成します。
   • External Actionの設定画面で、APIリクエストの詳細を入力します。
   • 設定は以下のようにします。
     • BasicInformation
       • HTTPメソッド：POST
       • URL：https://ホスト名.gainsightcloud.com/v1/ant/es/activity
     • Payload（以下はサンプル）

       {
         "records": [
           {
             "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
        

4. ルールエンジンを作成する

   • Gainsightのルールエンジンを開き、新しいルールを作成します。
   • データソースとしてS3バケット内のCSVファイルを指定します。
     ※ISO 8601 formatに沿ったCSVファイルを準備しているので、ActivityDateはStringでセットしておきます。

     

     
      
   • 先ほど作成したExternal Actionをルールに追加しフィールドをペイロードにマッピングします。

     

      

     

     
     ※参考：Call External API Action Type

5. ルールエンジンを実行する

   • ルールエンジンを実行し、CSVファイルのデータがGainsightのTimeline APIを通じてアクティビティとして登録されることを確認します。

     

     
      

6. その他

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

   

APIコールのリミット内に収まるようであれば、このようにルールエンジンからGainsightAPIを呼び出して利用することも可能となります。

関連記事：製品Tips：TimelineAPIでタイムライン アクティビティを登録する（ルールエンジンを利用しない方法）