アカウントマスタ連携
概要
アカウントマスタ連携の方法について記載します。 CSV ファイル用いて、ユーザー・グループ・所属情報を一括連携できます。
連携方式
API 連携
アカウントマスタ連携 API を利用することで、自動連携を実現できます。
API を利用する際の要点を以下に記載します。
CSV ファイルの送信
CSV ファイルは JSON 形式で API のリクエストボディに含める必要があります。
Note
フォーマットは Data URI Scheme となります。
(例) data:text/csv;base64,xxxxx...
非同期処理
CSV 連携は非同期処理となります。
POST /public/api/accountlink/v1/csvを利用して CSV ファイルを送信します。GET /public/api/accountlink/v1/csv/jobs/{jobId}を利用して連携状態を確認できます。
CSV 定義
連携内容により 5 種類の CSV ファイルがあります。 各 CSV ファイルを組み合わせることで、柔軟な一括連携を実施できます。 各 CSV ファイル定義をよく確認し、アカウントマスタ連携を実施してください。
Note
- SmartDB と互換性のあるフォーマットの CSV ファイルを連携できます。
- InsuiteX への連携に不要な項目が含まれている場合は無視されます。
- SmartDB アカウントマスタ連携ガイド CSV連携
CSV ファイル仕様
| デリミタ | , (半角カンマ) |
| 文字コード | UTF-8 |
| ヘッダー | 必須 |
ユーザー情報（users.csv）
ユーザーの追加、ユーザー情報の更新を実施するための CSV ファイルです。
Important
- CSV ファイルに記載されたユーザーのみ追加・更新の対象となります。記載のないユーザーは変更されません。
- ユーザー追加時は、所属情報 (group_members.csv) にてプライマリ所属を指定してください。
- SmartDB から出力した CSV を利用する場合は、
provider_idとprovider_user_idの項目を追記する必要があります。
| 必須 | カラム名 | 説明 | フォーマット | 例 |
|---|---|---|---|---|
| ○ | namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | id | ユーザーの識別キー（名前空間内で一意な識別子） | 半角英数-_ | 1000001 |
| ○ | type | ユーザー種別 1: 一般 |
1 桁の数値 | 1 |
| ○ | login_id | ログイン ID（メールアドレス） | 100 文字以下の文字列, メールアドレス形式 | xxx@example.com |
| ○ | last_name(ja) | 姓（日本語） | 40 文字以下の文字列 | ドリーム |
| middle_name(ja) | ミドルネーム（日本語) | 20 文字以下の文字列 | アーツ | |
| ○ | first_name(ja) | 名（日本語） | 40 文字以下の文字列 | 太郎 |
| last_name(en) | 姓（英語） | 40 文字以下の文字列 | Dream | |
| middle_name(en) | ミドルネーム（英語） | 20 文字以下の文字列 | Arts | |
| first_name(en) | 名（英語） | 40 文字以下の文字列 | Taro | |
| last_name(zh) | 姓（中国語) | 40 文字以下の文字列 | ||
| middle_name(zh) | ミドルネーム（中国語） | 20 文字以下の文字列 | ||
| first_name(zh) | 名（中国語） | 40 文字以下の文字列 | ||
| ○ | last_kana | 姓（かな） | 40 文字以下の文字列 | どりーむ |
| middle_kana | ミドルネーム（かな） | 20 文字以下の文字列 | あーつ | |
| ○ | first_kana | 名（かな） | 40 文字以下の文字列 | たろう |
| title | 役職 | 400 文字以下の文字列 | 部長 | |
| ○ | sort_level | ソート | 9 桁以下の数値 | 10 |
| tel1 | 電話番号 1 | 30 文字以下の文字列 | 03-xxxx-xxxx | |
| tel2 | 電話番号 2 | 同上 | 03-xxxx-xxxx | |
| ext | 内線番号 | 同上 | 100 | |
| fax1 | FAX 番号 1 | 同上 | 03-xxxx-xxxx | |
| fax2 | FAX 番号 2 | 同上 | 03-xxxx-xxxx | |
| mobile_phone | 携帯電話 | 同上 | 090-xxxx-xxxx | |
| mobile_address | 携帯アドレス | 100 文字以下の文字列, メールアドレス形式 | xxx@example.com | |
| other_email1 | その他メールアドレス 1 | 同上 | xxx@example.com | |
| other_email2 | その他メールアドレス 2 | 同上 | xxx@example.com | |
| emp_id | 社員番号 | 400 文字以下の文字列 | 12 | |
| photo_url | 顔写真がダウンロードできる URL | URL 形式の文字列 | https://example.com/user01.png | |
| admin | 管理権限 0: なし 1: あり |
1 桁の数値 | 1 | |
| del | 削除フラグ 0: 一般ユーザーに変更 1: ログイン不能ユーザーに変更 |
1 桁の数値 | 1 | |
| provider_id | 認証プロバイダーの ID M365 SSO: microsoft.com SAML: saml.{my-saml} |
36 文字以下の文字列 | saml.my-saml | |
| provider_user_id | 認証プロバイダーにおけるユーザー ID M365 SSO: ObjectID SAML: Email |
256 文字以下の文字列 | xxx@example.com |
Note
- namespace に
sysを用いることはできません。 - namespace が
insuitexの場合、ユーザーの更新と削除のみ有効です。作成はできません。 - namespace と id は合計して 91 文字以下にする必要があります。
- 各言語・かなの姓・ミドルネーム・名は合計して 98 文字（姓とミドルネーム、ミドルネームと名の間に含まれるスペースを足して 100 文字）以下にする必要があります。
- ログイン不能ユーザーに対して削除フラグ
del=0を指定した場合は、一般ユーザーに変更されます。 - ログイン不能ユーザーの情報は更新できません。
- ログイン不能ユーザーへと更新される場合、所属情報は削除されます。
- 新規ユーザーの provider_id と provider_user_id が空文字の場合、デフォルト認証プロバイダー情報を基に設定されます。
- 既存ユーザーの provider_id と provider_user_id が空文字の場合、現在の設定を維持します。
サンプル
namespace,id,type,login_id,last_name(ja),middle_name(ja),first_name(ja),last_name(en),middle_name(en),first_name(en),last_name(zh),middle_name(zh),first_name(zh),last_kana,middle_kana,first_kana,title,sort_level,tel1,tel2,ext,fax1,fax2,mobile_phone,mobile_address,other_email1,other_email2,emp_id,photo_url,admin,del,provider_id,provider_user_id
JinjiSystem,1000001,1,xxx@example.com,姓（日）,ミドル（日）,名（日）,姓（英）,ミドル（英）,名（英）,姓（中）,ミドル（中）,名（中）,せい,みどる,めい,部長,10,111-111-1111,222-222-2222,333,555-555-5555,666-666-6666,777-7777-7777,mobile@example.com,pmail1@example.com,pmail2@example.com,emp,https://example.com/user01.png,0,0,saml.my-saml,xxx@example.com
グループ情報（groups.csv）
グループの追加、グループ情報の更新を実施するための CSV ファイルです。
Important
- CSV ファイルに記載されたグループのみ追加・更新の対象となります。記載のないグループは変更されません。
| 必須 | カラム名 | 説明 | フォーマット | 例 |
|---|---|---|---|---|
| ○ | namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | id | グループの識別キー（名前空間内で一意な識別子） | 半角英数-_ | 2000000 |
| ○ | group_type | グループ種別 1: グループ 2: プロジェクト |
1 桁の数値 | 1 |
| ○ | name(ja) | グループ名（日本語） | 100 文字以下の文字列 | 営業 |
| name(en) | グループ名（英語） | 100 文字以下の文字列 | Sales | |
| name(zh) | グループ名（中国語） | 100 文字以下の文字列 | ||
| ○ | kana | グループ名（かな） | 100 文字以下の文字列 | えいぎょう |
| ○ | sort_level | ソート | 9 桁以下の数値 | 10 |
| ○ | path | 親グループパス /から始まり、namespace と id の間に#が含まれます。存在しない親組織の設定はできません。 |
/sys#2000000（例は TOP 組織配下） | |
| del | 削除フラグ 0: 有効なグループに変更 1:廃止グループに変更 |
1 桁の数値 | 1 |
Note
- namespace に
sysを用いることはできません。 - namespace が
insuitexの場合、グループの更新と削除のみ有効です。作成はできません。 - namespace と id は合計して 91 文字以下にする必要があります。
- Top 組織配下を指定する場合
path=/sys#2000000を指定してください。 - path に存在しないグループや廃止グループは指定できません。
- 廃止グループに対して削除フラグ
del=0を指定した場合は、有効なグループに変更されます。 - 削除フラグ
del=1を指定する場合は、指定した配下のグループも削除フラグdel=1を指定する必要があります。 - 親グループがループするなど、組織階層に不整合がある場合はエラーになります。
- グループの更新時に group_type の変更はできません。
サンプル
namespace,id,group_type,name(ja),name(en),name(zh),kana,sort_level,path,del
JinjiSystem,2000011,1,グループ1,Group1,中グループ1,ぐるーぷ1,10,/sys#2000000,0
JinjiSystem,2000012,2,プロジェクト1,Project1,中プロジェクト1,ぷろじぇくと1,10,/sys#2000000/JinjiSystem#2000011,0
所属情報（group_members.csv）
ユーザーのグループ所属情報や、グループのプロジェクト所属情報を連携するための CSV ファイルです。
Caution
ユーザー情報 (users.csv)・グループ情報 (groups.csv) と異なり、記載のない所属情報は削除されます。必要な所属情報は全件記載するようにご注意ください。
| 必須 | カラム名 | 説明 | フォーマット | 例 |
|---|---|---|---|---|
| ○ | namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | id | 所属ユーザーの識別キー（名前空間内で一意な識別子） | 半角英数-_ | 1000012 |
| ○ | group_namespace | 対象グループの名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | group_id | 対象グループ識別キー（名前空間内で一意な識別子） | 半角英数-_ | 2000002 |
| ○ | attr | 所属タイプ primaryMember: プライマリ所属ユーザー secondaryMember: セカンダリ所属ユーザー primaryMemberGroup: 所属グループ (プロジェクトに対するグループの所属) |
primaryMember |
- サンプル
namespace,id,group_namespace,group_id,attr
JinjiSystem,1000102,JinjiSystem,2000011,secondaryMember
JinjiSystem,2000111,JinjiSystem,2000012,primaryMemberGroup
JinjiSystem,2000113,JinjiSystem,2000012,primaryMemberGroup
Note
- namespace に
sysを用いることはできません。 - namespace が
insuitexの場合、グループの更新と削除のみ有効です。作成はできません。 - namespace と id は合計して 91 文字以下にする必要があります。
- group_namespace と group_id は合計して 91 文字以下にする必要があります。
- ユーザーは同じグループに対してプライマリ所属とセカンダリ所属できません。
- ユーザーは複数のグループに対してプライマリ所属できません。
- ユーザーのプロジェクト所属には
attr=primaryMemberを指定してください。 - 廃止グループに所属ユーザーは追加できません。
ロール情報（roles.csv）
ロールの追加、ロール情報の更新を実施するための CSV ファイルです。
Important
- CSV ファイルに記載されたロールのみ追加・更新の対象となります。記載のないロールは変更されません。
| 必須 | カラム名 | 説明 | フォーマット | 例 |
|---|---|---|---|---|
| ○ | namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | id | ロールの識別キー（名前空間内で一意な識別子） | 半角英数-_ | role_01 |
| ○ | role_type | ロール種別 1: 役職ロール |
1 桁の数値 | 1 |
| ○ | name(ja) | ロール名（日本語） | 100 文字以下の文字列 | 本部長 |
| name(en) | ロール名（英語） | 100 文字以下の文字列 | General Manager | |
| name(zh) | ロール名（中国語） | 100 文字以下の文字列 | 部门主管 | |
| ○ | kana | ロール名（かな） | 100 文字以下の文字列 | ほんぶちょう |
| ○ | sort_level | ソート・権限レベル。値が小さいほど上位の権限レベル。 | 7 桁以下の数値 | 10 |
| ○ | del | 削除フラグ 0: 有効なロール 1:廃止ロール |
1 桁の数値 | 1 |
Note
- 役職ロールのみに対応しており、担当ロールを扱うことはできません。
- namespace に
sysを用いることはできません。 - namespace が
insuitexの場合、ロールの更新と削除のみ有効です。作成はできません。 - namespace と id は合計して 91 文字以下にする必要があります。
- 廃止ロールに対して削除フラグ
del=0を指定した場合は、有効なロールに変更されます。
サンプル
namespace,id,role_type,name(ja),name(en),name(zh),kana,sort_level,del
JinjiSystem,role_00,1,社長,President,理事长,しゃちょう,0,0
JinjiSystem,role_01,1,本部長,GM,部门主管,ほんぶちょう,10,0
ロール割り当て情報（role_assignments.csv）
ユーザーへのロール割り当て情報を連携するための CSV ファイルです。
Caution
- ロール情報 (roles.csv) と異なり、記載のない割り当て情報は削除されます。必要な割り当て情報は全件記載するようにご注意ください。
- 役職ロールのみに対応しており、担当ロールを扱うことはできません。
| 必須 | カラム名 | 説明 | フォーマット | 例 |
|---|---|---|---|---|
| ○ | user_namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | user_id | ユーザーの識別キー（名前空間内で一意な識別子） | 半角英数-_ | user_01 |
| ○ | role_namespace | 名前空間（任意の文字列） | 半角英数-_ | JinjiSystem |
| ○ | role_id | ロールの識別キー（名前空間内で一意な識別子） | 半角英数-_ | role_01 |
Note
- 役職ロールのみに対応しており、担当ロールを扱うことはできません。
- user_namespace に
sysを用いることはできません。 - namespace と id は合計して 91 文字以下にする必要があります。
- group_namespace と group_id は合計して 91 文字以下にする必要があります。
サンプル
user_namespace,user_id,role_namespace,role_id
JinjiSystem,user_01,JinjiSystem,role_01
JinjiSystem,user_01,,JinjiSystem,role_02