ノーコードでクラウド上のデータとの連携を実現。
詳細はこちら →
CData Arc でチームスピリット（TeamSpirit）の勤怠情報をカオナビへ連携する
こんにちは。CData Software Japan の色川です。
***
こちらは以前の同名記事を「Salesforce レポートのスキーマファイルを事前作成（CreateReportSchema）するアプローチ」で更新した記事です。以前の記事をそのまま参照したい方はこちらをごらんください。
***
労働人口の減少や働く価値観の多様化などさまざまな背景から、人材の資質や能力を効果的に活用するタレントマネジメントが注目されています。すでにタレントマネジメントをサポートするシステムやサービスを活用されている企業も多いと思います。
タレントマネジメントを有効に機能させるには、人材データベースが必要不可欠で、そこには従業員（タレント）のスキルや経験など様々なデータが必要です。基礎的な従業員（タレント）データとしては労務（勤怠に関する情報）もその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 で連携フローを作成していきましょう。このシナリオで作成する連携フローは以下のような流れになっています。
概要としては「TeamSpirit の月別勤怠一覧（レポート）から取得した勤怠データを、カオナビAPI が期待するリクエスト形式にマッピングして、REST コネクタで更新API を実行」する流れです。
Salesforce プラットフォーム上に構築されているTeamSpirit のレポートからデータを取得するための事前作業（スキーマファイル作成）などの手順を含みますが、フローの流れ自体はとてもシンプルなモノになっているかと思います。
コネクタ 内容
1 Salesforce CreateReportSchema ストアドプロシージャでスキーマファイルを生成。作成したスキーマファイルを利用してTeamSpirit の「月別勤怠一覧」レポートからデータを取得
2 XMLMap 1 で取得した勤怠データをカオナビAPI が期待するレスポンス形式（に相当するXML 形式）にマッピング
3 JSON 2 の出力結果（XML）をカオナビAPI が期待するJSON 形式に変換
4 REST 送信前イベントでアクセストークンを取得した後、3 をリクエストボディとしてカオナビAPI を実行
Salesforce コネクタ
最初に「TeamSpirit の「月別勤怠一覧」レポートをSelect で取得できるように、レポートのスキーマファイルを作成します。その他カテゴリから「Salesforce コネクタ」を選択し、フローキャンバスへ配置します。
接続 でTeamSpirit の接続情報を作成します。ここで作成した接続情報はSalesforce コネクタで共有することができます。
この記事では、TeamSpirit のレポートを実行して勤怠データを取得します。TeamSpirit はSalesforce プラットフォーム上で提供されるアプリケーションです。Salesforce プラットフォームのカスタムレポートは、CData Salesforce Driver で用意されているCreateReportSchema ストアドプロシージャを利用することで、レポートのデータ構造を定義するスキーマファイルを生成することができます。生成したスキーマファイルをLocation プロパティで指定すれば、カスタムレポートをSelect アクションで取得することができるようになります。今回はこれを利用します。
まずはSalesforce コネクタのテスト実行機能を利用して、CreateReportSchema ストアドプロシージャを実行し、スキーマファイルを生成します。アクションを「Execute Stored Procedure」に設定し、ストアドプロシージャに「CreateReportSchema」を選択します。
「サンプルデータを表示」から、以下のパラメータでテスト実行します。この記事では以下のようなパラメータで実行しました。OutputFolder などは利用される環境に併せて指定してください。
ReportName: 月別勤怠一覧
ReportId: 控えておいたレポートのSalesforce Id
OutputFolder: C:\Temp\
データを取得する操作ではないため「結果が返されませんでした」と表示されますが、OutputFolder で指定したディレクトリに「月別勤怠一覧.rsd」が生成されていることが確認できます。これでスキーマファイルの生成は完了です。
生成したスキーマファイルが格納されているディレクトリを「高度な設定 - Schema」の「Location」プロパティに指定します。
Location プロパティは、接続するデータソースの定義をカスタマイズしたり、新しいテーブルやビュー、またはストアドプロシージャでデータモデルを拡張する場合に利用するプロパティです。
これで「月別勤怠一覧レポート」のデータをSelect アクションで取得できるようになりました。
アクションを「Select」に、テーブルで「月別勤怠一覧」を選択します。
この記事では、勤怠月度を取得条件として設定しました。
取得データをフィルターする際の留意点
この記事では、UIから組み立てるSQL の条件として「勤怠月度」を指定して取得データをフィルターしていますが、この指定方法の場合、Salesforce レポートから全件取得した後、Salesforce コネクタで利用するCData Driver でフィルターさ れる形になります。
Salesforce のレポートからAPI で取得できるデータ件数には制限があるので、レポートのデータ件数が多い場合や、よりパフォーマンスよくSalesforce から取得する段階でフィルタリングしたい場合は、reportFilter でAPI の列名を指定する形でフィルターを設定してください。
reportFilter を利用したフィルターの指定については、こちらの記事を参考にしてください。
Salesforce コネクタを含むデータベース系コネクタ（Select やUpsert アクションが提供されるコネクタ）では、デフォルトでレコード単位にメッセージファイル（処理対象となるデータファイル）を出力します。この記事では、カオナビのAPI の性質上、まとめて処理したいので、バッチ出力を行う設定を施します。「高度な設定」の「最大レコード」を「-1」に設定します。
コネクタの設定を保存します。
XMLMap コネクタ
次に「Salesforce コネクタで取得したレポートの勤怠データ」を「カオナビAPI が期待するレスポンス形式（に相当するXML 形式）にマッピング」するXMLMap コネクタを設定します。コアカテゴリから「XMLMap コネクタ」を選択し、フローキャンバスへ配置します。Salesforce コネクタから、XMLMap コネクタへフローをつなぎます。
デスティネーションファイルには、カオナビAPI が期待するレスポンス形式（に相当するXML 形式）を以下のようなXML ファイルを用意してアップロードすることで指定します。この記事では複数レコード形式のシートに新規レコードとして登録します。API としては「シート情報 レコード追加」です。シートはカスタムフィールドで構成されており、それぞれの項目はid で識別されます。
スキーマファイルにはXMLMap コネクタでマッピングすべき内容が識別しやすいように「{社員番号}」のように記述しました。
<?xml version="1.0" encoding="utf-8"?>
<Items xmlns:json="http://arc.cdata.com/ns/jsonconnector"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<member_data json:array="true">
<code>{社員番号}</code>
<records json:array="true">
<custom_fields json:array="true">
<id json:type="number">5550</id>
<values json:array="true">{所定時間}}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5551</id>
<values json:array="true">{時間外時間}}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5552</id>
<values json:array="true">{出勤日数}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5553</id>
<values json:array="true">{休日出勤}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5554</id>
<values json:array="true">{有給日数}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5555</id>
<values json:array="true">{欠勤日数}</values>
</custom_fields>
<custom_fields json:array="true">
<id json:type="number">5556</id>
<values json:array="true">{期間}</values>
</custom_fields>
</records>
</member_data>
</Items>
対象とするシートの使用可能なレイアウト設定（それぞれの項目のId がいくつであるか）は、「シート情報レイアウト設定 取得API」で確認できます。シートに含まれるカスタムフィールドのId について、シート情報レイアウト設定 取得API をPostman で実行して取得しました。
構造を示すスキーマファイルでは「{社員番号}」のように記述していますが、実際にAPI 実行されるときの値はマッピングによりストアドプロシージャの実行結果（レポートのデータ）で上書きされます。
TeamSpirit のレポートから取得されたデータを、宛先にあるそれぞれのvalues にマッピングします。
yyyy/MM 形式で取得できる「勤怠月度」を「期間」にMM 形式で設定するために、式エディタでArc のフォーマッタを使って以下のように設定しています。
[xpath(勤怠月度) | regexreplace('^.*\/', '')]
フォーマッタは、Arc 組込みのスクリプトであるArcScript に用意されている関数に相当する機構です。文字列、日付、算術演算など、値の編集や加工をサポートする機能が豊富に提供されています。
JSON コネクタ
次に「XMLMap の出力結果をJSON に変換」するJSON コネクタを設定します。コアカテゴリから「JSON コネクタ」を選択し、フローキャンバスへ配置します。設定はデフォルトのままで利用します。
XMLMap コネクタから、JSON コネクタへフローをつなぎます。
REST コネクタ
最後に「送信前イベントでアクセストークンを取得した後、JSON 変換した勤怠データをリクエストボディとしてカオナビAPI を実行」するREST コネクタを設定します。コアカテゴリから「REST コネクタ」を選択し、フローキャンバスへ配置します。
カオナビAPI の利用にはアクセストークンが必要です。アクセストークンはconsumer_key とconsumer_secret を指定して、アクセストークン発行API を実行することで取得します。アクセストークンには期限があるため、この記事ではREST コネクタで「シート情報 レコード追加」API の実行前に、Arc の送信前イベント機能を利用してアクセストークンを取得して、メッセージヘッダに設定します。REST コネクタではメッセージヘッダに設定される予定の値を利用するようにプロパティ指定します。
REST コネクタの送信前イベントへ以下のスクリプトを記述します。これで処理するメッセージファイルのヘッダにaccess_token と言う属性で取得したアクセストークンが利用できるようになります。
<!-- kaonavi アクセストークンを取得して、メッセージヘッダに設定 -->
<arc:set attr="consumer_key" value="{consumer_key}" />
<arc:set attr="consumer_secret" value="{consumer_secret}" />
<arc:set attr="consumer" value="[consumer_key]:[consumer_secret]" />
<arc:set attr="consumer" value="[consumer | base64encode()]" />
<arc:set attr="http.URL" value="https://api.kaonavi.jp/api/v2.0/token" />
<arc:set attr="http.header:name#1" value="Authorization" />
<arc:set attr="http.header:value#1" value="Basic [consumer]" />
<arc:set attr="http.paramname#1" value="grant_type" />
<arc:set attr="http.paramvalue#1" value="client_credentials" />
<arc:set attr="http.contenttype" value="application/x-www-form-urlencoded;charset=UTF-8" />
<arc:set attr="http.sslcert" value="*" />
<arc:set attr="tmp.text" value="" />
<arc:call op="httpPost" in="http">
<arc:set attr="tmp.text" value="[http:content]" />
</arc:call>
<arc:call op="jsonOpen" in="tmp" out="jout">
<arc:set attr="jout.map:access_token" value="/json/access_token" />
<arc:call op="jsonDomGet" in="jout" out="result">
<arc:set attr="_message.header:access_token" value="[result.access_token]" />
</arc:call>
</arc:call>
実際の更新用API を実行します。この記事では「シート情報 レコード追加」API を実行します。「シート情報 レコード追加」API については、カオナビのAPI ドキュメントも参考にしてください。
メソッドをPOST に、URL に「シート情報 レコード追加」のエンドポイントを指定します。シートId は控えていたシートId を指定してください。
先ほどの通り、ヘッダーに「Kaonavi-Token」として「Script コネクタで取得してメッセージヘッダに設定したアクセストークン」を指定します。
ボディはフローで渡されたJSON ファイルになるので、Content Type に「JSON（application/json）」を設定します。
ヘッダーでメッセージヘッダ値を示すArcScript を利用するため、高度な設定で「ヘッダー内のArcScript を許可」します。
JSON コネクタから、REST コネクタへフローをつなぎます。
これで「TeamSpirit で入力・記録された勤怠情報を、月次単位に、カオナビへ従業員（タレント）別に勤怠記録として登録する」フローが出来上がりました。
連携フローの実行
作成したフローを実行して確認してみましょう。
起点となるSalesforce コネクタからフローを実行してみます。アウトプットタブから「受信」を実行します。
REST コネクタのインプットタブを確認すると、TeamSpirit の勤怠データを、カオナビの「シート情報 レコード追加」API へリクエストできていることが確認できました。
カオナビ連携結果の確認
kaonavi API v2 によるデータの登録や更新の多くは、非同期で行われます。この記事で実行している「シート情報 レコード追加」API も実行は非同期です。REST コネクタの実行では、レコード追加するタスクが登録できたことは確認できますが、レコード追加が成功したかは、その時点では分かりません。
この記事では、非同期タスクの実行結果の確認は、カオナビの「公開API v2 情報 - 実行結果」で行いました。連携フローから登録したタスクが無事に成功していることが確認出来ました。
カオナビAPI には登録したタスク進捗状況を取得するAPI もありますので、登録タスクの実行結果をフローで判定したい、と言う場合は、登録後にタスク進捗状況をAPI で取得して、status で判断するフローを構成することで実現できると思います。関心のある方はぜひ試してみてください。
連携フローの自動実行
CData Arc ではフローを定期実行するスケジューラ機能を持っています。今回のシナリオであれば、フローの起点となるSalesforce コネクタの「オートメーション」タブで設定することができます。例えば、月に一度、毎月1日の12:00に定期実行する場合は、このように設定します。
この記事で紹介したフロー（テンプレート）
この記事で作成したフローについては、こちら からテンプレートとして使える arcflow がダウンロードできます。
ダウンロードしたarcflow は「ワークスペースをインポート」やフローデザイナーにドラッグ&ドロップで登録できます。こちらのテンプレートを利用する時は、各コネクタでの接続情報などを、お使いの環境に併せて編集してください。
おわりに
勤怠データを利用するときの粒度や内容は様々だと思いますが、この記事では外部連携で求められることが多い従業員単位の月次データを連携するシナリオを試してみました。
CData Arc はシンプルで拡張性の高いコアフレームワークに、豊富なMFT・EDI・エンタープライズコネクタを備えたパワフルな製品です。CData Drivers との組み合わせで250を超えるアプリケーションへの連携を実現できます。必要な連携を低価格からはじめられる事も大きな特長です。
皆さんのつなぎたいシナリオでぜひ CData Arc を試してみてください。
製品を試していただく中で何かご不明な点があれば、テクニカルサポートへお気軽にお問い合わせください。