こんにちは。CData Software Japan の色川です。
労働人口の減少や働く価値観の多様化などさまざまな背景から、人材の資質や能力を効果的に活用するタレントマネジメントが注目されています。すでにタレントマネジメントをサポートするシステムやサービスを活用されている企業も多いと思います。
タレントマネジメントを有効に機能させるには、人材データベースが必要不可欠で、そこには従業員（タレント）のスキルや経験など様々なデータが必要です。基礎的な従業員（タレント）データとしては労務（勤怠に関する情報）もその1つかも知れません。
この記事では、TeamSpirit の勤怠情報を、タレントマネジメントサービスのカオナビへ連携する方法をご紹介します。
TeamSpirit
TeamSpirit は、株式会社チームスピリットが提供する、勤怠管理・工数管理・経費精算などの機能を融合したクラウドサービスです。
TeamSpirit は、Salesforce プラットフォーム上で稼働するアプリケーションとして提供されています。さまざまな勤務形態に柔軟・高セキュリティで対応することができ、「組織を1歩強くするための機能」が豊富に提供されています。充実したレポート機能もその1つです。
この記事では、TeamSpirit のレポート機能を利用してデータを取得します。
カオナビ
カオナビは株式会社カオナビが提供するタレントマネジメントをサポートするクラウドサービスです。戦略的な人事を実現するために、テレワーク・生産性向上・人材不足など、現代のさまざまな人事課題に対応しています。
タレントマネジメントは業種業界や企業ごとにポイントが異なる個社性が強い分野ですが、カオナビではシステムだけではなくサポートも合わせた両輪で提供しているのが強みです。
システム面での特徴としては、カスタム自由な人材データベースなど、個社性の高い分野であるタレントマネジメントをサポートするために、徹底的に磨き上げられた柔軟設計になっています。
外部データと接続可能なカオナビAPI が公開されており、こちらを利用して基幹システムや外部サービスと連携させることができます。
この記事では、カオナビAPI を利用して、カオナビにデータを登録しています。
CData Arc
CData Arc は、CData 製品の中で「自動化/Automate」を担うデータ連携ツールです。「B2B 連携をもっとシンプルに」をコンセプトに、ファイル連携 & DB 連携 & API 連携といったB2B 連携に必要なすべてをノーコード・ローコードでつなぐことができるプラットフォームです。
この記事のシナリオ
この記事では、TeamSpirit の勤怠情報をカオナビへ連携する方法をご紹介します。
具体的には、TeamSpirit で月次単位に集計されたの勤怠レポートのデータをもとに、カオナビへ従業員（タレント）別に勤怠記録として登録するシナリオをイメージしています。
事前準備
事前準備として、必要な製品のインストールや、連携元・連携先の構成を確認していきましょう。
CData 製品のダウンロードとインストール
この記事のシナリオでは、こちらの製品を利用します。30 日間のトライアルライセンスが提供されていますので、ぜひお手元で試してみてください。
CData Arc
CData Arc のインストールはこちらを参考にしてください。
CData Arc スタートアップガイドとナレッジベース
CData Arc を使いはじめるときは、こちらも参考にしてください。
CData Arc に関するナレッジは、こちらにまとめています。あわせて参考にしてください。
TeamSpirit の構成
勤怠のデータと言っても、断面・粒度や内容は様々ですが、この記事では「従業員別に月次単位で集計された勤怠データ」を取得します。
この記事では、TeamSpirit の特長の1つでもある充実したレポート機能を利用して、勤怠情報レポートからデータを取得するアプローチを試してみました。
データを取得するもととなるレポートは「レポート: 勤怠(ver.3.0) - [データ] 月別勤怠一覧」を利用しました。対象とするレポートのSalesforce Id を控えておいてください。
TeamSpirit はSalesforce プラットフォーム上で稼働するアプリケーションです。TeamSpirit との接続にはCData Arc のSalesforce コネクタを利用しました。
カオナビの構成
この記事では、カオナビに含まれている「勤怠履歴」「〇〇年度勤怠記録」のシートを複製して「2022年度勤怠記録」として用意しました。
なお、カオナビAPI のv1 は2023年3月でサポート終了が予告されています。この記事ではカオナビAPI のv2 を利用しています。
まずは用意したシートをAPI で操作できるように「操作対象の管理」で指定します。この記事のシナリオで実行する「シート情報」API ではシートID の指定が必要です。シートID を控えておいてください。
カオナビAPI へのアクセスにはアクセストークンが必要です。アクセストークンには有効期限があるため、連携フローの中で発行して利用します。ここではアクセストークン発行のために必要なConsumer Key と Consumer Secret を控えておいてください。
この記事では、カオナビとの接続・更新にはCData Arc のREST コネクタを利用しました。
カオナビAPI の詳細については、カオナビのAPI ドキュメントを参照してください。
ちなみに、この記事とは逆のパターンですが「カオナビからのデータ取得」については、CData API Driver でサンプルとして使えるカオナビ用API Profile をご用意しています。カオナビからデータを取得するシナリオについては、こちらを利用するとよりシンプルに実現頂けると思います。詳しくはこちらの記事を参考にしてください。
カオナビの API をドライバー化：各種ツールから接続してみた | CData Software Blog
連携フローの作成
それではCData Arc で連携フローを作成していきましょう。このシナリオで作成する連携フローは以下のような流れになっています。
Script コネクタの部分（レポートデータを取得するストアドプロシージャ実行へのパラメータ設定）など、やや複雑に感じる部分もあるかも知れませんが、「TeamSpirit の月別勤怠一覧レポートを実行して、レポートから取得した勤怠データを、カオナビAPI が期待するリクエスト形式にマッピングして、REST コネクタでカオナビAPI を実行してデータを登録」する流れです。
コネクタ 内容
1 Script 6 のカオナビAPI 実行時に利用するアクセストークンを取得 & 3 のレポート実行ストアドプロシージャに指定するパラメータを発行（生成・出力）
2 XMLMap(1) 1 を 3 へマッピング（GetCustomReport ストアドプロシージャのパラメータ設定）
3 Salesforce GetCustomReport ストアドプロシージャで、TeamSpirit の「月別勤怠一覧」レポートを実行してデータを取得
4 XMLMap(2) 3 で取得した勤怠データをカオナビAPI が期待するリクエスト形式（に相当するXML 形式）にマッピング
5 JSON 4 でマッピングしたXML 形式のリクエスト用データをカオナビAPI が期待するJSON 形式に変換
6 REST 1 で用意したアクセストークンを使い、5 をリクエストボディとしてカオナビAPI を実行
Salesforce コネクタ
パラメータ設定を楽に行うために、まず最初に3 の「TeamSpirit の「月別勤怠一覧」レポートを実行してデータを取得」するSalesforce コネクタを設定しておきます。その他カテゴリから「Salesforce コネクタ」を選択し、フローキャンバスへ配置します。
接続 でTeamSpirit の接続情報を作成します。ここで作成した接続情報はTeamSpirit への接続で使うSalesforce コネクタで共有することができます。
この記事では、TeamSpirit のレポートを実行して勤怠データを取得します。
TeamSpirit はSalesforce プラットフォーム上で提供されるアプリケーションです。Salesforce プラットフォームのカスタムレポートは、CData Salesforce Driver で用意されている「GetCustomReport」ストアドプロシージャを利用することで取得することができます。この記事ではこのストアドプロシージャを利用してTeamSpirit からデータを取得します。
アクションを「Execute Stored Procedure」に設定し、ストアドプロシージャに「GetCustomReport」を選択します。
期待したデータが取得できるかを確認するために「サンプルデータを表示」から、控えておいたレポートのSalesforce Id を指定して、テスト実行してみましょう。
期待のデータ（月別勤怠一覧レポートのデータ）が取得できることが確認できました。
コネクタの設定を保存します。
GetCustomReport ストアドプロシージャのreportFilter
この記事では、このコネクタで実行するGetCustomReport ストアドプロシージャへのパラメータとして、後述のScript コネクタで以下のような値を生成し、ストアドプロシージャへマッピングして指定しています。
WHERE teamspirit__AtkEmpMonth__c.teamspirit__YearMonthS__c = '2022/09'
この記事では、月別勤怠一覧レポートの「勤怠月度（teamspirit__AtkEmpMonth__c.teamspirit__YearMonthS__c）」をフィルタ条件として指定しました。
取得対象とするレポートの構成（フィルタ条件として指定したい列のオブジェクトや項目名など）については、Workbench を使って以下のように確認することができます。
/services/data//analytics/reports/<レポートのSalesforce ID>/describe
Script コネクタ
次に「カオナビAPI で利用するアクセストークンの取得」と「Salesforce コネクタのGetCustomReport ストアドプロシージャに指定するパラメータを発行」するScript コネクタを設定します。コアカテゴリから「Script コネクタ」を選択し、フローキャンバスへ配置します。
スクリプト欄で「カオナビAPI で利用するアクセストークンの取得」と「Salesforce コネクタのGetCustomReport ストアドプロシージャに指定するパラメータを発行（出力）」するための記述をします。
カオナビAPI 用のアクセストークンは、コネクタで処理するデータとは別に後続のコネクタへ連携したいので、フローを流れるメッセージのヘッダとして設定しています。ストアドプロシージャへのパラメータ情報は、フローを流れるメッセージのペイロード（後続のコネクタへ渡されるメッセージのデータそのもの）として出力します。
CData Arc のメッセージに関する仕組みと概要についてはこちらも参考にしてください。
ストアドプロシージャのパラメータ情報には、reportId の他に、年月でフィルタするためのフィルタ条件を指定しました。
{月別勤怠一覧レポートのSalesforce Id}
WHERE teamspirit__AtkEmpMonth__c.teamspirit__YearMonthS__c = '2022/09'
ここは少し複雑にみえるかも知れませんが、ArcScript の機能を活用すれば、複雑度の高い業務フローの自動化も検討することができ、API 固有の仕様などにも柔軟に対応することができます。
この記事では詳しく触れませんが、ArcScript に興味を持って頂いた方はこちらのナレッジベースもぜひ参考にしてください。
このコネクタからのアウトプットは以下のようなメッセージが出力されます。
-
{月別勤怠一覧レポートのSalesforce Id}
WHERE teamspirit__AtkEmpMonth__c.teamspirit__YearMonthS__c = '2022/09'
メッセージヘッダには、アクセストークンが設定されています。
XMLMap(1) コネクタ
次に「Script コネクタで生成・出力したストアドプロシージャのパラメータ情報」を「Salesforce コネクタのGetCustomReport ストアドプロシージャにパラメータとしてマッピング」するXMLMap コネクタを設定します。コアカテゴリから「XMLMap コネクタ」を選択し、フローキャンバスへ配置します。
Script コネクタから、XMLMap コネクタへ。XMLMap コネクタからSalesforce コネクタへフローをつなぎます。
フローをつないだことで、入力のスキーマ構造が確定しているSalesforce コネクタについては、XMLMap のデスティネーションファイルにスキーマが自動的に認識されます。ソースとなるScript コネクタについては設定時点ではスキーマ構造が分かりませんので、スキーマ情報として以下のようなXML ファイルを用意してアップロードすることで指定します。
マッピングは、同名の項目を持つ場合、自動的にマッピングが設定されます。今回は全ての項目を同名にしてありますので、マッピング設定はこれで完了です。
XMLMap(2) コネクタ
次に「Salesforce コネクタで取得したレポートの勤怠データ」を「カオナビAPI が期待するレスポンス形式（に相当するXML 形式）にマッピング」するXMLMap コネクタを設定します。コアカテゴリから「XMLMap コネクタ」を選択し、フローキャンバスへ配置します。Salesforce コネクタから、XMLMap コネクタへフローをつなぎます。
ソースとなるSalesforce コネクタではGetCustomReport ストアドプロシージャを実行しますが、ストアドプロシージャからの出力は実行するレポートの構造に依存します（設定時点ではスキーマ構造が分かりません）。
そのため、Salesforce コネクタから出力されるレポートデータの構造について、スキーマ情報として以下のようなXML ファイルを用意してアップロードすることで指定します。
<社員ID_上長_氏名 />
<最終打刻日 />
<休日深夜法内_時 />
<平日深夜法外_時 />
<限度超過時間_時 />
<社員ID_社員コード />
<平日深夜法内残業_時 />
<平均出社時刻_時 />
<社員ID_部署ID_部署コード />
<過不足時間_時 />
<所定出勤日数 />
<休日出勤日数 />
<出社打刻率 />
<勤務時間外私用外出回数_削除予定_ />
<早退回数 />
<休日日中法内_時 />
<社員ID_部署ID_親部署ID_部署コード />
<法定休日出勤日数 />
<法定時間外残業_時 />
<平日日中法内残業_時 />
<平日日中法内所定_時 />
<平日日中法外_時 />
<退社打刻率 />
<実労働時間_時 />
<勤務時間内私用外出時間_時 />
<無給休暇日数 />
<深夜労働時間_時 />
<社員ID_部署ID_親部署ID_勤怠部署名 />
<時間単位有休取得時間_時 />
<遅刻回数 />
<勤務時間外私用外出時間_時_削除予定_ />
<打刻率 />
<退社打刻回数 />
<代休取得日数 />
<最終出社打刻日 />
<私用外出回数_削除予定_ />
<控除早退時間_時 />
<社員ID_社員名 />
<割増労働時間_時 />
<控除遅刻時間_時 />
<勤怠月度 />
<総労働時間_時 />
<休憩時間_時 />
<休日深夜法外_時 />
<祝日出勤日数 />
<遅刻時間_時 />
<勤務時間内私用外出回数 />
<残業時間_時 />
<有休取得日数 />
<出社打刻回数 />
<早退時間_時 />
<所定労働時間_時 />
<社員ID_上長_従業員番号 />
<休日日中法外_時 />
<平日深夜法内所定_時 />
<６０時間超残業_時 />
<公用外出時間_時 />
<法定休日日中_時 />
<法定休日深夜_時 />
<最終退社打刻日 />
<平均退社時刻_時 />
<計画付与有休取得日数 />
<社員ID_部署ID_勤怠部署名 />
<月の法定労働時間_時 />
<控除私用外出時間_時 />
<限度超過回数 />
<控除時間_時 />
<法定時間内残業_時 />
<実出勤日数 />
デスティネーションファイルには、カオナビAPI が期待するレスポンス形式（に相当するXML 形式）を以下のようなXML ファイルを用意してアップロードすることで指定します。この記事では複数レコード形式のシートに新規レコードとして登録します。API としては「
シート情報 レコード追加」です。シートはカスタムフィールドで構成されており、それぞれの項目はid で識別されます。
スキーマファイルにはXMLMap コネクタでマッピングすべき内容が識別しやすいように「{社員番号}」のように記述しました。
{社員番号}
5550
{所定時間}}
5551
{時間外時間}}
5552
{出勤日数}
5553
{休日出勤}
5554
{有給日数}
5555
{欠勤日数}
5556
{期間}
対象とするシートの使用可能なレイアウト設定（それぞれの項目のId がいくつであるか）は、「
シート情報レイアウト設定 取得API」で確認できます。シートに含まれるカスタムフィールドのId について、シート情報レイアウト設定 取得API をPostman で実行して取得しました。
構造を示すスキーマファイルでは「{社員番号}」のように記述していますが、実際にAPI 実行されるときの値はマッピングによりストアドプロシージャの実行結果（レポートのデータ）で上書きされます。
TeamSpirit のレポートから取得されたデータを、宛先にあるそれぞれのvalues にマッピングします。
yyyy/MM 形式で取得できる「勤怠月度」を「期間」にMM 形式で設定するために、式エディタでArc のフォーマッタを使って以下のように設定しています。
[xpath(勤怠月度) | regexreplace('^.*\/', '')]
フォーマッタは、Arc 組込みのスクリプトであるArcScript に用意されている関数に相当する機構です。文字列、日付、算術演算など、値の編集や加工をサポートする機能が豊富に提供されています。
JSON コネクタ
次に「XMLMap の出力結果をJSON に変換」するJSON コネクタを設定します。コアカテゴリから「JSON コネクタ」を選択し、フローキャンバスへ配置します。設定はデフォルトのままで利用します。
XMLMap コネクタから、JSON コネクタへフローをつなぎます。
REST コネクタ
最後に「Script コネクタで取得したアクセストークンを使い、JSON 変換した勤怠データをリクエストボディとしてカオナビAPI を実行」するREST コネクタを設定します。コアカテゴリから「REST コネクタ」を選択し、フローキャンバスへ配置します。
この記事では「
シート情報 レコード追加」API を実行します。API の詳細についてはカオナビのAPI ドキュメントを参考にしてください。
メソッドをPOST に、URL に「シート情報 レコード追加」のエンドポイントを指定します。シートId は控えていたシートId を指定してください。
ヘッダーに「Kaonavi-Token」として「Script コネクタで取得してメッセージヘッダに設定したアクセストークン」を指定します。
ボディはフローで渡されたJSON ファイルになるので、Content Type に「JSON（application/json）」を設定します。
ヘッダーでメッセージヘッダ値を示すArcScript を利用するため、高度な設定で「ヘッダー内のArcScript を許可」します。
JSON コネクタから、REST コネクタへフローをつなぎます。
これで「TeamSpirit で入力・記録された勤怠情報を、月次単位に、カオナビへ従業員（タレント）別に勤怠記録として登録する」フローが出来上がりました。
連携フローの実行
作成したフローを実行して確認してみましょう。
起点となるScript コネクタからフローを実行してみます。アウトプットタブから「受信」を実行します。
REST コネクタのインプットタブを確認すると、TeamSpirit の勤怠データを、カオナビの「シート情報 レコード追加」API へリクエストできていることが確認できました。
カオナビ連携結果の確認
kaonavi API v2 によるデータの登録や更新の多くは、非同期で行われます。この記事で実行している「シート情報 レコード追加」API も実行は非同期です。REST コネクタの実行では、レコード追加するタスクが登録できたことは確認できますが、レコード追加が成功したかは、その時点では分かりません。
この記事では、非同期タスクの実行結果の確認は、カオナビの「公開API v2 情報 - 実行結果」で行いました。連携フローから登録したタスクが無事に成功していることが確認出来ました。
カオナビAPI には登録したタスク進捗状況を取得するAPI もありますので、登録タスクの実行結果をフローで判定したい、と言う場合は、登録後にタスク進捗状況をAPI で取得して、status で判断するフローを構成することで実現できると思います。関心のある方はぜひ試してみてください。
連携フローの自動実行
CData Arc ではフローを定期実行するスケジューラ機能を持っています。今回のシナリオであれば、フローの起点となるCData コネクタの「オートメーション」タブで設定することができます。例えば、月に一度、毎月1日の12:00に定期実行する場合は、このように設定します。
この記事で紹介したフロー（テンプレート）
この記事で作成したフローについては、
こちら からテンプレートとして使える arcflow がダウンロードできます。
ダウンロードしたarcflow は「ワークスペースをインポート」やフローデザイナーにドラッグ&ドロップで登録できます。こちらのテンプレートを利用する時は、各コネクタでの接続情報などを、お使いの環境に併せて編集してください。
おわりに
勤怠データを利用するときの粒度や内容は様々だと思いますが、この記事では外部連携で求められることが多い従業員単位の月次データを連携するシナリオを試してみました。
CData Arc はシンプルで拡張性の高いコアフレームワークに、豊富なMFT・EDI・エンタープライズコネクタを備えたパワフルな製品です。CData Drivers との組み合わせで250を超えるアプリケーションへの連携を実現できます。必要な連携を低価格からはじめられる事も大きな特長です。
皆さんのつなぎたいシナリオでぜひ CData Arc を試してみてください。
製品を試していただく中で何かご不明な点があれば、テクニカルサポートへお気軽にお問い合わせください。
この記事では CData Arc™ 2022 - 22.0.8285.0 を利用しています。
関連コンテンツ
