kaonavi（メンバー）

kaonavi（メンバー）を業務アセットとして接続すると、kaonaviのタレント（人材情報）をYESODから管理できます。接続に必要な準備と、接続後の挙動を説明します。

概要

kaonaviには「メンバー」と「ユーザー」という2つの概念があります。どちらもYESODから操作できますが、業務アセットは別々です。

観点	メンバー	ユーザー
位置づけ	kaonaviで管理するタレント（人材情報）	kaonaviの利用者
kaonaviへのアクセス	アクセスには使いません。パスワードも持ちません	kaonaviの利用者としてアクセスするための認証情報を持ちます
主に持つ情報	氏名・性別・生年月日などのプロフィール情報や、役職などの情報	プロフィールや役職などの情報は持ちません
できること	人材情報として参照・更新されます	kaonaviの利用者としてアクセスし、「メンバー」の一覧を閲覧できます

メンバーは「社員番号」が指定必須で、ほかのメンバーと重複できません。メールアドレスは重複できます。

メンバーの属性の1つに「退職日」があります。日付を指定し、現在の日時がその日付を過ぎると退職者という扱いになり、kaonavi内の各所で「退職者」というラベルが表示されます。

この記事は、メンバーを管理する業務アセットの説明です。ユーザーを管理する業務アセットはkaonavi（ユーザー）を参照してください。

参照先	リンク
設定画面	公開API v2 情報
公式ヘルプ	（v2）各種詳細を確認する
APIドキュメント	kaonavi API v2

管理できること

機能	対応
アカウント作成	○
グループ付与	—
ロール付与	—
アプリ	—
グループプッシュ	—

接続方式は標準コネクタです。管理できるのは、kaonaviのメンバーの有無と「同期する項目」で設定した属性の値です。

業務アセット固有の特徴

ほかの業務アセットと特に異なる点は、次の6つです。

削除タスクを実行すると、対象のメンバーに退職日が設定され、退職者という扱いに変わります。 メンバーの情報は削除されず、kaonavi上に残ります。
パスワードを持ちません。 kaonaviのメンバーは、kaonaviの利用者としてアクセスするためのものではないため、パスワードは発行されません。
入社日・退職日は「同期する項目」の設定が必須です。 デフォルトのマッピングが無く、未設定のままではタスクが失敗します。
タスクの実行に時間がかかります。 kaonaviのAPIは呼び出してから完了するまでに時間がかかります。所要時間は早い場合で約10秒、遅い場合で1〜2分です（kaonavi側の負荷状況によって変わります）。
一括実行に対応しています。 「タスク一覧」で複数件のアカウント作成タスク、または複数件のアカウント削除タスクを選んでまとめて完了できます。選んだすべてのタスクが、1〜2回のAPIの呼び出しにまとめて実行されます。1件ずつ実行するより、全体の所要時間を短くできます。
APIには初期状態ではメンバー情報を操作する権限がありません。 kaonaviの管理画面で権限を与えてください（次節）。

事前に必要なもの

kaonaviの管理画面で「公開API v2 情報」を操作できるアカウント
「公開API v2 情報」で確認できるConsumer KeyとConsumer Secret
メンバー情報の操作権限（下記の手順で許可します）

メンバー情報の操作を許可する

API経由でのシートの取得・更新・登録・削除は制御されているため、kaonaviの管理画面で実行を許可します。kaonavi側での作業です。

kaonaviの管理画面で「公開API v2 情報」を開きます。
「操作対象の管理」を開きます。「APIv2 情報操作対象の管理」が表示されます。
「メンバー情報（基本情報・兼務情報）」の「取得」「更新」「登録」「削除」の4項目にチェックを入れます。
「設定保存」をクリックします。

kaonaviの「APIv2 情報操作対象の管理」。「メンバー情報（基本情報・兼務情報）」の4つのチェックボックスにチェックが入っている

接続に使う情報

入力項目	入力する内容
「Consumer Key」	kaonaviの「公開API v2 情報」で確認したConsumer Key
「Consumer Secret」	kaonaviの「公開API v2 情報」で確認したConsumer Secret

どちらもAPIの呼び出しに必要な値です。第三者へ共有せず、安全な場所で管理してください。

接続する

「業務アセット」画面から「SaaS接続」画面を開くまでの手順は、業務アセットを追加するを参照してください。

「SaaS接続」画面で「kaonavi（メンバー）」を選択します。「kaonavi（メンバー）接続」画面が表示されます。
「Consumer Key」「Consumer Secret」を入力します。
「接続」ボタンをクリックします。接続に成功すると、業務アセットが作成されます。

接続画面には「管理者権限を持ったアカウントで［接続］してください。」と表示されます。

kaonavi（メンバー）の接続画面。「Consumer Key」「Consumer Secret」の入力欄と「接続」ボタンが並んでいる

アカウントの作成

YESODのメンバーに対応するkaonaviのメンバーを作成します。kaonavi上に同一の社員番号のメンバーが存在するかどうかに応じて、次のように動作します。

kaonaviの状態	動作
同一の社員番号で退職日が設定されているメンバーが存在する	そのメンバーの退職日属性を空にして、情報を更新します
同一の社員番号で退職日が設定されていないメンバーが存在する	そのメンバーの情報を更新します
同一の社員番号のメンバーが存在しない	メンバーを新規作成します

パスワードの設定はありません。kaonaviのメンバーは、kaonaviの利用者としてアクセスするためのものではないため、パスワードは発行されません。

社員番号と入社日は、アカウント作成タスクを実行する前に「同期する項目」で設定してください。設定していないと、アカウント作成タスクは失敗します。

アカウントの削除

kaonaviのメンバーの退職日属性に日付を設定します。メンバーの完全削除ではありません。 設定される日付は、「同期する項目」のuser.retired_dateが参照されます。

退職日を設定すると、kaonavi上では「退職者」というタグが付与され、退職者という扱いになります。

注意

次の場合、アカウント削除タスクは失敗します。

user.retired_dateに対するマッピングが設定されていない
user.retired_dateに対するマッピングは設定されているが、「同期のタイミング」が「アカウント作成時のみ」になっている

割当種別

割当種別はありません。メンバーの有無だけを管理できます。

同期する項目

業務アセットの「アカウント設定」にある「同期する項目」で、YESODの項目をkaonaviのメンバーの属性へ対応づけます。属性式で値を設定できる属性は次のとおりです。

注意

社員番号・入社日を指定しないと、アカウント作成タスクが失敗します。
退職日は指定したうえで「同期のタイミング」を「アカウント作成時・値の変更時」にしないと、アカウント削除タスクが失敗します。
入社日・退職日にはデフォルト値がありません。業務アセットを作成したあとに必ず設定してください。

属性の概要	属性式におけるKey	属性式を設定しないときの値	備考
社員番号（属性式の指定が必須）	`user.code`	`user.employeeNumber.size > 0 ? user.employeeNumber[0] : null`	属性式が設定されていない場合、アカウント作成タスクは失敗します。複数の会社に所属する場合、どの会社の社員番号を使うかは属性式で指定します
氏名	`user.name`	`user.familyNameLocalPreferred + " " + user.givenNameLocalPreferred`	—
フリガナ	`user.name_kana`	指定なし	—
メールアドレス	`user.mail`	`user.email`	—
入社日（属性式の指定が必須）	`user.entered_date`	指定なし	`YYYY-MM-DD`形式の文字列を指定します。設定していない場合、アカウント作成タスクは失敗します。どの会社の入社日を反映するかは、`user.joining_date["<会社のID>"]`のような属性式で指定します
退職日（属性式の指定が必須）	`user.retired_date`	指定なし	`YYYY-MM-DD`形式の文字列を指定します。設定していない場合、アカウント削除タスクは失敗します。どの会社の退職日を反映するかは、`user.leaving_date["<会社のID>"]`のような属性式で指定します。「同期のタイミング」の指定については上の注意を参照
性別	`user.gender`	指定なし	—
生年月日	`user.birthday`	指定なし	—
主務情報	`user.department.code`	指定なし	kaonaviにおける組織のIDを`user.department.code = "1000"`のように指定します
兼務情報	`user.sub_departments[].code`	指定なし	kaonaviにおける組織のIDを`user.sub_departments[0].code = "2000"`のように指定します。複数指定できます
その他カスタムフィールド	`user.custom_fields`	指定なし	上記以外の属性に値を設定するときに使います。設定できる属性は一部のみです。項目を特定するIDと値をそれぞれ指定します

主務情報・兼務情報の指定方法

主務情報・兼務情報を設定するには、「同期する項目」に次のように設定を追加します。

「同期する項目」の一覧に、主務情報のuser.department.codeと兼務情報のuser.sub_departments[].codeが並んでいる

値にはkaonaviにおける組織のIDを指定します。組織のIDはkaonaviの画面からは確認できないため、所属ツリー取得APIを実行して調べます。

1. APIトークンを取得する

kaonaviの公開API v2 情報で確認できるconsumer_keyとconsumer_secretを使って、次のように呼び出します。

リクエスト先:
POST https://api.kaonavi.jp/api/v2.0/token

リクエストヘッダー:
Authorization: Basic {{consumer_key}} {{consumer_secret}}
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

リクエストボディ:
{
  "grant_type": "client_credentials"
}

次のようなレスポンスが返ります。このaccess_tokenがAPIトークンです。

{
  "access_token": "<APIトークン>",
  "token_type": "Bearer",
  "expire_in": 3600
}

2. 組織情報を取得する

取得したAPIトークンを使って、次のように呼び出します。

リクエスト先:
GET https://api.kaonavi.jp/api/v2.0/departments

リクエストヘッダー:
Kaonavi-Token: {{APIトークン}}
Content-Type: application/json

次のようなレスポンスが返ります。このcodeフィールドが組織IDです。例では組織の一部だけを載せています。

{
  "department_data": [
    {
      "code": "1000",
      "name": "役員",
      "parent_code": null,
      "leader_member_code": "a0011",
      "order": 1,
      "memo": "○○月に新設予定"
    },
    {
      "code": "1100",
      "name": "役員人事部",
      "parent_code": "1000",
      "leader_member_code": "a0042",
      "order": 1,
      "memo": null
    },
    {
      "code": "2000",
      "name": "営業本部(salesDiv.)",
      "parent_code": null,
      "leader_member_code": "a0142",
      "order": 2,
      "memo": "テスト"
    }
  ]
}

カスタムフィールドの指定方法と制約

「その他カスタムフィールド」（user.custom_fields）では、上の表に挙げた属性以外の一部の属性を更新できます。更新できるのは基本情報と兼務情報の属性だけです。

属性をマッピングするには、次のようにIDと値の設定を追加します。

「同期する項目」の一覧。user.custom_fields[0]のidに14、values[0]に"取締役"が設定されている状態

user.custom_fields[].idには、マッピング先となるkaonaviの属性のIDを指定します。属性のIDはkaonaviの画面からは確認できないため、メンバー情報レイアウト設定取得APIを実行して調べます。
user.custom_fields[].valuesには、マッピングする値を指定します。1つしか指定しない場合も、配列の形式で指定します。

属性のIDは次の手順で調べます。APIトークンの取得手順は「主務情報・兼務情報の指定方法」と同じです。

リクエスト先:
GET https://api.kaonavi.jp/api/v2.0/member_layouts

リクエストヘッダー:
Kaonavi-Token: {{APIトークン}}
Content-Type: application/json

次のようなレスポンスが返ります。custom_fieldsに含まれるものが各属性に相当し、idフィールドが属性IDです。レスポンスは長いため、例では属性の一部だけを載せています。

{
  "custom_fields": [
    {
      "id": 11,
      "name": "採用区分",
      "required": false,
      "type": "enum",
      "max_length": 0,
      "enum": ["新卒", "中途", "派遣社員", "業務委託"]
    },
    {
      "id": 13,
      "name": "内線番号",
      "required": false,
      "type": "string",
      "max_length": 100,
      "enum": []
    },
    {
      "id": 14,
      "name": "役職",
      "required": false,
      "type": "enum",
      "max_length": 0,
      "enum": ["代表取締役", "取締役", "本部長", "部長", "課長"]
    }
  ]
}

kaonaviのAPIでは、基本情報・兼務情報とその他のシートで、更新に使うAPIと項目の調べ方が異なります。

対象	更新に使うAPI	項目の調べ方
基本情報・兼務情報	メンバー情報部分更新	メンバー情報レイアウト設定取得
その他のシート	シート情報部分更新	シート情報取得

「シート情報部分更新」で基本情報のIDを指定するとエラーになります。メンバーの登録時に指定できるのは、基本情報・兼務情報の属性だけです。

制限事項

この業務アセットで取り込まれるのは、現在日付の時点で退職していないタレント情報だけです。退職日に過去の日付が入っているタレント情報は、取り込みの対象外です。

警告

属性同期で退職日に過去の日付を反映させると、次にアカウント取り込みを実行したときにアカウントの紐付けが外れます。

概要​

管理できること​

業務アセット固有の特徴​

事前に必要なもの​

メンバー情報の操作を許可する​

接続に使う情報​

接続する​

アカウントの作成​

アカウントの削除​

割当種別​

同期する項目​

主務情報・兼務情報の指定方法​

カスタムフィールドの指定方法と制約​

制限事項​

関連ページ​

概要