Gainsightを使い始めるとき、今のシステムで管理しているCSMの活動履歴をGainsightのタイムラインに取り込みたい場合があります。Salesforceのイベントやタスクのアクティビティであれば、条件に合えばGainsightのSalesforce Activities to Timelineの機能を使って過去のアクティビティ履歴をGainsightのタイムラインに取り込むことができます。ただ、Salesforce以外のシステムにある活動履歴や、条件に合わない場合はこの機能を利用することができません。
そんなとき、GainsightのTimelineAPIを使うと、データを直接Gainsightのタイムラインアクティビティに登録することができます。
この記事では一例として、このTimelineAPIを使ってCSVファイルのデータをGainsightのタイムラインに取り込む方法をご紹介していきます。
事前準備と手順
Gainsight環境
- インポートするタイムラインアクティビティタイプとフィールドを準備
- APIアクセスキーの生成
インポートデータ
- インポートするタイムラインアクティビティデータのCSVを準備
プログラム作成
- APIを呼び出すための環境（プログラム）を準備
これらについて、１つずつ説明していきます。
1．インポートするタイムラインアクティビティタイプとフィールドを準備
今回は過去の活動履歴をインポートするためのアクティビティタイプとして「APIインポート」というアクティビティタイプを作成しました。デフォルトのフィールド以外にカスタムのテキストフィールドも追加し、このようなフィールドを設定しています。
- 件名（デフォルト）
- メモ（デフォルト）
- アクティビティ日付（デフォルト）
- 内部出席者（追加）
- 結果（追加）
実際に登録するデータの内容に合わせて準備してください。
参考：Configure Timeline Settings
2．APIアクセスキーの生成
TimelineAPIを使うために、Gainsightテナントのアクセスキーを取得する必要があります。アクセスキーの取得方法はGenerate API Access Keyにありますので、これを参考にアクセスキーを取得しておきます。
3．インポートするタイムラインアクティビティデータのCSVを準備
今回は複数の活動履歴データを一気に登録するため、Bulk Activity Save API を利用します。このAPIに必要なパラメータを確認し、必須のパラメータが必ずデータに含まれるようにします。データのフォーマットも要件に合わせます。
- ContextName*：CompanyかRelationship
- ExternalId*アクティビティを識別するためのユニークな値(String)
- Author*：アクティビティ所有者のメールアドレスか名前
- Subject*：アクティビティの件名
- Notes*：アクティビティのメモ
- Activity Date：アクティビティのDateTime値。（ISO 8601 format - `yyyy-MM-dd'T'HH:mm:ss.SSSXXX’）値がない場合は現在時刻が入る
- TypeName*：アクティビティタイプの名前
- CompanyName*：会社名
- internalAttendees：内部出席者のリスト
- Ant__jie_guo__c：カスタムで登録した「結果」フィールドに入る値
今回はアクティビティタイプに内で登録するフィールドに、カスタムで「結果」というテキストフィールドを作成しました。APIでこのフィールドに値を登録するためには、フィールドのAPI名を利用する必要があります。
API名は、管理＞データ管理＞アクティビティタイムライン のオブジェクト内にあるフィールド「結果」を開くと「フィールド名」で確認することができます。ここでは、「Ant__jie_guo__c」が「結果」フィールドのAPI名です。
登録用に作成したのは以下のようなCSVファイルです。
ContextName,ExternalId,Author,Subject,Notes,ActivityDate,TypeName,CompanyName,internalAttendees,Ant__jie_guo__c
Company,601565632811,mnishimi@gainsight.com,初回オンボーディングミーティングの実施,"新規顧客への製品やサービスの紹介 利用開始に必要な手続きの案内顧客の質問に対する答えとサポートの提供 成功的な利用開始のためのベストプラクティスの共有",2023/7/1,APIインポート,テスト会社,ysasaki@gainsight.com;mnishimi+gene1@gainsight.com,完了
Company,272530894891,mnishimi@gainsight.com,顧客フィードバック収集セッション,"顧客からの直接的なフィードバックを収集 製品やサービスに対する顧客の満足度の評価 改善点や新しい要望の特定 顧客との関係強化と信頼構築",2023/8/20,APIインポート,テスト会社,mnishimi+gene1@gainsight.com,対応中
Company,289551039141,mnishimi@gainsight.com,製品アップデート説明会,"最新の製品アップデートや新機能についての情報提供 アップデートによる顧客へのメリットの説明 アップデートに関する質問への対応 アップデートの利用促進",2023/9/1,APIインポート,テスト会社,ysasaki@gainsight.com,保留
Company,228702246781,mnishimi@gainsight.com,Q&Aサポートセッションの開催,"顧客からの質問に対する専門的な回答提供 問題解決のサポートとガイダンス よくある質問(FAQ)の更新と情報共有 サポート体験の向上と顧客満足度の向上",2023/9/14,APIインポート,テスト会社,ysasaki@gainsight.com;mnishimi+gene1@gainsight.com,完了
Company,561558271081,mnishimi@gainsight.com,サービス改善のための戦略会議,"サービス改善に向けた戦略立案と実行計画の策定 チーム内でのアイデアや意見の共有 パフォーマンス指標(KPI)に基づく評価と分析 継続的な改善と成長を目指す取り組み",2023/10/2,APIインポート,テスト会社,ysasaki@gainsight.com,対応中
4．APIを呼び出すための環境（プログラム）を準備
ここまで来たら、APIを呼び出すためのプログラムを作成します。プログラムは開発環境に合わせてお好きなものをご利用いただければと思います。
ここではPhythonで作成したテストプログラムのサンプルコードを掲載しています。このサンプルプログラムの実行環境にはGoogleのColabを利用しました。
import os
import csv
import json
import requests
from datetime import datetime
from google.colab import userdata
accessKey= userdata.get('accessKey')
# Replace these values with your actual Gainsight credentials and CSV file path
api_key = accessKey
api_endpoint = 'https://ご利用のインスタンスホスト名.gainsightcloud.com/'
csv_file_path = CSVファイル.csv'
# Check if the CSV file exists before opening it
if not os.path.exists(csv_file_path):
raise FileNotFoundError(f'CSV file not found: {csv_file_path}')
# Read CSV file and convert to JSON
records_data = {"records": []}
with open(csv_file_path, 'r', encoding='utf-8') as csv_file:
csv_reader = csv.DictReader(csv_file)
for row in csv_reader:
# Format the date to match the desired format in the JSON
activity_date = datetime.strptime(row['ActivityDate'], '%Y/%m/%d').strftime('%Y-%m-%dT%H:%M:%S.000-07:00')
record = {
"ContextName": row['ContextName'],
"TypeName": row['TypeName'],
"ExternalId": row['ExternalId'],
"Subject": row['Subject'],
"Notes": row['Notes'],
"ActivityDate": activity_date,
"Author": row['Author'],
"CompanyName": row['CompanyName'],
"Ant__jie_guo__c": row['Ant__jie_guo__c'],
"internalAttendees": row['internalAttendees'].split(';')
}
records_data["records"].append(record);
# Define lookups separately
lookups_data = {
"AuthorId": {
"fields": {
"Author": "Email"
},
"lookupField": "Gsid",
"objectName": "GsUser",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"GsCompanyId": {
"fields": {
"CompanyName": "Name"
},
"lookupField": "Gsid",
"objectName": "Company",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"InternalAttendees": {
"fields": {
"internalAttendees": "Email"
},
"lookupField": "Gsid",
"objectName": "GsUser",
"multiMatchOption": "MARKASERROR"
}
}
# Combine records and lookups in the final request data
request_data = {"records": records_data["records"], "lookups": lookups_data}
# Convert the data to JSON string
request_string = json.dumps(request_data, indent=2, ensure_ascii=False)
json_data = json.dumps(request_data)
# Print the JSON result
# print(request_string)
# Set up API headers
headers = {
'Content-Type': 'application/json',
'Accesskey': f'{api_key}',
}
# Make API request to Gainsight Bulk Activity Save API
api_url = f'{api_endpoint}/v1/ant/es/activity/bulk'
response = requests.post(api_url, data = json_data, headers=headers)
# Check the response status
if response.status_code == 200:
print('CSV data successfully uploaded to Gainsight.')
print(json.loads(response.text))
else:
print(f'Error uploading CSV data to Gainsight. Status code: {response.status_code}, Response: {response.text}')使用上の注意：
本サンプルプログラムは、あくまで例示目的です。このサンプルプログラムを使用する際には、その動作の安全性、適切性、および目的への適合性を自己の責任で確認していただく必要があります。本サンプルプログラムの使用によって生じたいかなる結果についても、提供者は一切の責任を負いません。
また、本サンプルプログラムに関して、提供者からの技術的なサポートや保証は提供されません。不具合やエラーが発生した場合でも、提供者はその修正や対応を義務付けられるものではありません。
ユーザーはこれらの条件を理解し、同意した上でサンプルプログラムを利用するものとします。
Bulk Activity Save APIのパラメータ、メソッドやエラーコード、制限などは、Timeline APIsのドキュメントをご参照ください。
このプログラムを実行して処理が成功すると、以下のようにタイムラインに活動履歴が登録されます。
