Untitled :: アカウントマスタ連携ガイド

概要

CSVファイルを利用したアカウントマスタ連携について記載します。CSVファイルを利用することで一括でユーザ・グループ情報を連携することができます。

連携に失敗した場合、連携方式に関わらず、連携(送信)した各CSVファイルの変更内容は全て取り消されます。再連携する場合、連携に必要なCSVファイルは全て連携(送信)するようにしてください。
各CSVファイルのカラムは予告なく追加、削除、順番等の変更が実施される場合があります。CSVファイルを読み込む必要がある場合(自動連携を構築する場合等)にカラム順番に異存しないようにする等、変更を念頭においた処理をご検討ください。

連携方式

手動連携

管理画面アカウントマスタ連携 CSV連携 CSV入力 から手動でアカウントマスタ連携を実施することができます。詳細は SmartDB システム管理者ガイドを参照してください。

自動連携

WebAPIを利用することで、自動連携を実現することができます。WebAPIを利用する際のポイントについて以下に記載します。利用可能なAPIについては WebAPI一覧を参照してください。

CSVファイルの送信

CSVファイルの送信はJSON形式としてAPIのリクエストボディに含める必要があります。

フォーマットはData URIスキームとなります。(例) data:text/csv;base64,xxxxx…..

非同期処理

CSV連携は非同期処理となります。POST api/v1/accountMasters を利用してCSVファイルを送信後、GET api/v1/accountMasters を利用して、連携状態を確認することができます。

連携状態サンプル

{
    "status": "doing",
    "errors": null,
    "created_by": {
        "mid": 1000000,
        "name": "システム管理者"
    },
    "updated_by": {
        "mid": 1000011,
        "name": "SmartDB管理者"
    },
    "created_at": "2020-06-19T14:54:40+09:00",
    "updated_at": "2020-09-10T17:34:52+09:00"
}

クリーニング処理

連携中の障害等により、CSV連携が実行できない状態になってしまった場合、クリーニング処理を実行することで問題が改善する可能性があります。CSV連携が実行できないような問題が発生した場合は、クリーニング処理を実行して問題が改善するかどうか確認してください。

実行例

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer XXXXXXXXXXX" https://xxxx.smartdb.jp/api/v1/accountMasters/clean

CSV定義

CSV連携には連携内容により、3種類のCSVファイルがあります。各CSVファイルを組み合わせることで、柔軟な一括連携を実施することができます。各CSVファイル定義をよく確認し、アカウントマスタ連携を実施してください。

ファイル仕様

デリミタ	, (半角カンマ)
文字コード	UTF-8
ヘッダー	有り

デリミタ

, (半角カンマ)

文字コード

UTF-8

ヘッダー

有り

ユーザ情報（users.csv）

ユーザの追加、ユーザ情報の更新を実施するためのCSVファイルです。

CSVファイルに記載されたユーザのみ追加・更新の対象となります。
ユーザ追加時に所属情報（group_members.csv）で所属を指定しない場合、そのユーザのプライマリ所属は自動的にTOP組織となります。また、自動的にTOP組織が設定された場合においても、1グループに所属可能なユーザ数は5000件となります。

users.csv
必須	カラム名	説明	フォーマット	例
○	namespace	名前空間（任意の文字列）	半角英数-_ ・ sys, insuite, smartdbは予約語のため、使用することはできません。	JinjiSystem
○	id	ユーザの識別キー（名前空間内で一意な識別子）	半角英数-_	1000011
○	type	ユーザ種別 1: 一般	1桁の数値	1
○	login_id	ログインID（メールアドレス）	100文字以下の文字列 ※テストドメインとして@test.smartdb.jpを利用することができます。	xxx@example.com
○	last_name(ja)	姓（日本語）	40文字以下の文字列	ドリーム
	middle_name(ja)	ミドルネーム（日本語)	20文字以下の文字列	アーツ
○	first_name(ja)	名（日本語）	40文字以下の文字列	太郎
	title_name(ja)	敬称（日本語）	100文字以下の文字列	サー
	title_name_pos(ja)	敬称（日本語）位置 0: 後 1: 前	1桁の数値	1
	note(ja)	メモ（日本語）	500文字以下の文字列
	last_name(en)	姓（英語）	40文字以下の文字列	Dream
	middle_name(en)	ミドルネーム（英語）	20文字以下の文字列	Arts
	first_name(en)	名（英語）	40文字以下の文字列	Taro
	title_name(en)	敬称（英語）	400文字以下の文字列	Sir
	title_name_pos(en)	敬称（英語）位置 0: 後 1: 前	1桁の数値	1
	note(en)	メモ（英語）	500文字以下の文字列
	last_name(zh)	姓（中国語)	40文字以下の文字列
	middle_name(zh)	ミドルネーム（中国語）	20文字以下の文字列
	first_name(zh)	名（中国語）	40文字以下の文字列
	title_name(zh)	敬称（中国語）	400文字以下の文字列
	title_name_pos(zh)	敬称（中国語）位置 0: 後 1: 前	1桁の数値
	note(zh)	メモ（中国語）	500文字以下の文字列
○	last_kana	姓（かな）	40文字以下の文字列	どりーむ
	middle_kana	ミドルネーム（かな）	20文字以下の文字列	あーつ
○	first_kana	名（かな）	40文字以下の文字列	たろう
	title	役職	400文字以下の文字列	部長
○	sort_level	ソート	9桁以下の数値	10
	tel1	電話番号１	30文字以下の文字列・利用できる文字列は以下の通りです。 ○ 半角英大文字 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z ○ 半角英小文字 a b c d e f g h i j k l m n o p q r s t u v w x y z ○ 半角数字 0 1 2 3 4 5 6 7 8 9 ○ 半角記号 # * ( ) - + . ・先頭に以下の文字を指定することはできません。 ( ) - . ・末尾に以下の文字を指定することはできません。 ( ) - + .	03-xxxx-xxxx
	tel2	電話番号２	同上	03-xxxx-xxxx
	ext	内線番号	30文字以下の文字列	100
	fax1	Fax１	同上	03-xxxx-xxxx
	fax2	Fax２	同上	03-xxxx-xxxx
	mobile_phone	携帯電話	同上	090-xxxx-xxxx
	mobile_address	携帯アドレス	100文字以下の文字列・文字列には『@』及び『@以後一つ以上のピリオド』を含める必要があります。	example@docomo.ne.jp
	other_email1	その他メールアドレス1	同上	www@example.net
	other_email2	その他メールアドレス2	同上	yyy@example.jp
○	lang	言語	2文字の文字列・ja, en, zhのいずれかの文字列	ja
	url	ホームページURL	100文字以下の文字列	https://www.example.com
	expire_date	アカウント有効期限	YYYY/MM/DDフォーマットの文字列 ※ 過去の日付を設定することはできません。
○	time_zone	タイムゾーン	+ or - から始まる4桁の数値 ※ 合計5文字	+0900
	emp_id	社員番号	400文字以下の文字列	12
	work_style	ワークスタイル	1〜6	ワークスタイルを示す番号 1: 未分類 2: 正社員 3: 休職者 4: 内定者 5: 出向者 6: 契約社員
	photo_url	顔写真がダウンロードできるURL	HTTP or HTTPS から始まる文字列	http://example.com/1.png（エクスポート時は空文字列）
	admin	管理権限 0: なし 1: あり(システム管理者となる)	1桁の数値	1
	del	削除フラグ 1:ログイン不能ユーザに変更 0: 一般ユーザに変更	1桁の数値	1
	info_01	業務情報01	250文字以下の文字列
	info_02	業務情報02	同上
	info_03	業務情報03	同上
	info_04	業務情報04	同上
	info_05	業務情報05	同上
	info_06	業務情報06	同上
	info_07	業務情報07	同上
	info_08	業務情報08	同上
	info_09	業務情報09	同上
	info_10	業務情報10	同上
	prof_01	個人情報01	同上
	prof_02	個人情報02	同上
	prof_03	個人情報03	同上
	prof_04	個人情報04	同上
	prof_05	個人情報05	同上
	prof_06	個人情報06	同上
	prof_07	個人情報07	同上
	prof_08	個人情報08	同上
	prof_09	個人情報09	同上
	prof_10	個人情報10	同上
	sens_01	非公開情報01	同上
	sens_02	非公開情報02	同上
	sens_03	非公開情報03	同上
	sens_04	非公開情報04	同上
	sens_05	非公開情報05	同上
	sens_06	非公開情報06	同上
	sens_07	非公開情報07	同上
	sens_08	非公開情報08	同上
	sens_09	非公開情報09	同上
	sens_10	非公開情報10	同上
	mid(read only)	SmartDB内部のユーザ識別子（編集不可）	参照専用。値の変更不可	1000011
	primary_gname(read only)	プライマリ所属組織の名称（編集不可）	同上	組織A

namespace と id は合計して91文字以下にする必要があります。
日本語、英語、中国語、かなに存在する姓・ミドルネーム・名は合計して98文字（姓とミドルネーム、ミドルネームと名の間に含まれるスペースを足して100文字）以下にする必要があります。
ログイン不能ユーザに対して削除フラグ(del=0)を指定した場合は、一般ユーザに変更されます。
削除フラグが設定されている場合、アカウント有効期限の設定はできません。
mid(read only)、primary_gname(read only)については、CSV出力時に付加される参照用のカラムとなります。CSV入力においては不要なカラムとなります。CSV入力時に存在している場合、該当カラムは処理の対象とならず、カラムが存在していないものとして扱われます。
管理権限(admin=1)が指定されている場合、削除フラグ(del=1)を指定することはできません。
管理権限の詳細は SmartDB システム管理者ガイドを参照してください。
last_kana、middle_kana、first_kanaにカタカナ(全角or半角)を指定した場合、ひらがな(全角)に変換されて登録(更新)されます。
CSV ファイルに work_style カラム(列)がある場合、 work_style の情報を空(未入力)の状態で登録(更新)ができません。

サンプル

namespace,id,type,login_id,last_name(ja),middle_name(ja),first_name(ja),title_name(ja),title_name_pos(ja),note(ja),last_name(en),middle_name(en),first_name(en),title_name(en),title_name_pos(en),note(en),last_name(zh),middle_name(zh),first_name(zh),title_name(zh),title_name_pos(zh),note(zh),last_kana,middle_kana,first_kana,title,sort_level,tel1,tel2,ext,fax1,fax2,mobile_phone,mobile_address,other_email1,other_email2,lang,url,expire_date,time_zone,emp_id,work_style,photo_url,admin,del,info_01,info_02,info_03,info_04,info_05,info_06,info_07,info_08,info_09,info_10,prof_01,prof_02,prof_03,prof_04,prof_05,prof_06,prof_07,prof_08,prof_09,prof_10,sens_01,sens_02,sens_03,sens_04,sens_05,sens_06,sens_07,sens_08,sens_09,sens_10,mid(read only),primary_gname(read only)
JinjiSystem,1000013,1,example@example.com,姓（日）,ミドル（日）,名（日）,タイトル（日）,1,メモ（日）,姓（英）,ミドル（英）,名（英）,タイトル（英）,1,メモ（英）,姓（中）,ミドル（中）,名（中）,タイトル（中）,1,メモ（中）,せい,みどる,めい,"役,職",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,ja,http://example.com,expire,+0900,emp,1,,0,0,業務情報01,業務情報02,業務情報03,業務情報04,業務情報05,業務情報06,業務情報07,業務情報08,業務情報09,業務情報10,個人情報01,個人情報02,個人情報03,個人情報04,個人情報05,個人情報06,個人情報07,個人情報08,個人情報09,個人情報10,非公開情報01,非公開情報02,非公開情報03,非公開情報04,非公開情報05,非公開情報06,非公開情報07,非公開情報08,非公開情報09,非公開情報10,1000013,営業部

グループ情報（groups.csv）

グループの追加、グループ情報の更新を実施するためのCSVファイルです。

CSVファイルに記載されたグループのみ追加・更新の対象となります。

groups.csv
必須	カラム名	説明	フォーマット	例
○	namespace	名前空間（任意の文字列）	半角英数-_ ・ sys, insuite, smartdbは予約語のため、使用することはできません。	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
○	grade	役職グレード※役職グループのみ	8桁以下の数値	10
○	permit	所属ユーザ・グループの公開※プロジェクトのみ 0: プロジェクト以外 1: 公開する 2: 所属ユーザ・グループ以外には公開しない	1桁の数値	0
○	path	親組織パス	・ /から始まり、namespaceとidの間に#が含まれます。・存在しない親組織の設定はできません。	/sys#2000000（例はTOP組織配下）
	del	削除フラグ 1:廃止組織に変更 0:組織に変更	1桁の数値	1
	text_00	拡張項目00	1000文字以下の文字列
	text_01	拡張項目01	同上
	text_02	拡張項目02	同上
	text_03	拡張項目03	同上
	text_04	拡張項目04	同上
	text_05	拡張項目05	同上
	text_06	拡張項目06	同上
	text_07	拡張項目07	同上
	text_08	拡張項目08	同上
	text_09	拡張項目09	同上
	gid(read only)	SmartDB内部のグループ識別子（編集不可）	参照専用。値の変更不可	2000011
	parent_name(read only)	親組織の名称（編集不可）	同上	営業本部

namespace と id は合計して91文字以下にする必要があります。
一部の項目はグループ種別によって必須項目ではない場合があります。
- permit はグループ種別: プロジェクトの場合のみ必須項目となります。
- path はトップレベル組織（ TOP 組織）の場合不要です
path に廃止組織を設定することはできません。
廃止組織に対して削除フラグ(del=0)を指定した場合は、組織に変更されます。
削除フラグ(del=1 or 0)を指定する場合は、指定した配下の組織も削除フラグ(del=1 or 0)を指定する必要があります。
親グループがループするなど、組織階層に不整合がある場合はエラーになります。
gradeカラムは廃止されました。互換性のため、既存のCSVファイルにgradeカラムが存在している場合も、今まで通り連携することができます。
gid(read only)、parent_name(read only)については、CSV出力時に付加される参照用のカラムとなります。CSV入力においては不要なカラムとなります。CSV入力時に存在している場合、該当カラムは処理の対象とならず、カラムが存在していないものとして扱われます。

サンプル

namespace,id,group_type,name(ja),name(en),name(zh),kana,sort_level,permit,path,del
JinjiSystem,2000011,1,組織1,soshiki1,中組織1,そしき1,10,0,/sys#2000000,0
JinjiSystem,2000012,2,プロジェクト1,project1,中プロジェクト1,ぷろじぇくと1,10,1,/sys#2000000/JinjiSystem#2000011,0

所属情報（group_members.csv）

ユーザの所属情報を追加するためのCSVファイルです。

1つのグループに所属可能なユーザ数はプライマリ所属、セカンダリ所属などの所属タイプごとに5000件です。5000件を超えた所属を指定した場合はエラーとなります。

ユーザ情報（users.csv）、グループ情報（groups.csv）と異なり、記載のない所属情報は削除されます。必要な所属情報は全件記載するようにご注意ください。
ユーザにはプライマリ所属組織が指定する必要があります。新規ユーザのプライマリ所属組織が未指定の場合は自動的にTOP組織が設定されます。
あるユーザの所属情報が1行も記載されていない場合、一般ユーザはエラーになりますが、ログイン不能ユーザはスキップされ所属情報が更新されません。

group_members.csv
必須	カラム名	説明	例
○	namespace	名前空間（任意の文字列：半角英数-_）	JinjiSystem
○	id	所属ユーザの識別キー（名前空間内で一意な識別子）	1000012
○	group_namespace	対象グループの名前空間（任意の文字列：半角英数-_）	JinjiSystem
○	group_id	対象グループ識別キー（名前空間内で一意な識別子）	2000002
○	attr	所属タイプ（下記のいずれかを指定） primaryMember: 組織プライマリ所属ユーザ、プロジェクト所属ユーザ secondaryMember: セカンダリ所属ユーザ primaryMemberGroup: 所属グループ ※1 groupManager: グループ管理者 superiorPrincipal(leader ※2): 上長 superiorProxy(leaderAgent ※2): 上長代行 ※1 プロジェクトの所属グループとして、組織が指定された場合。 ※2 旧所属タイプの名称。旧名称も継続して利用可能。	primaryMember

サンプル

namespace,id,group_namespace,group_id,attr,
JinjiSystem,1000102,JinjiSystem,2000011,primaryMember,
JinjiSystem,1000102,JinjiSystem,2000011,secondaryMember,
JinjiSystem,1000102,JinjiSystem,2000012,superiorPrincipal,
JinjiSystem,1000103,JinjiSystem,2000012,primaryMember,
JinjiSystem,1000103,JinjiSystem,2000012,superiorProxy,
JinjiSystem,2000111,JinjiSystem,2000012,primaryMemberGroup,
JinjiSystem,2000113,JinjiSystem,2000012,primaryMemberGroup,
JinjiSystem,1000103,JinjiSystem,2000013,superiorProxy,

各項目に入力される文字列は大文字・小文字が区別されます。
プライマリ所属ユーザとセカンダリ所属ユーザには同じユーザを指定することはできません。

組織ロール情報（group_roles.csv）

組織の組織ロール情報を設定するためのCSVファイルです。

CSVファイルに記載された組織及び、組織ロールのみ更新の対象となります。
プロジェクトに組織ロールを設定することはできません。

group_roles.csv
必須	キー	説明	フォーマット	例
○	namespace	名前空間（任意の文字列）	半角英数-_	JinjiSystem
○	id	組織の識別キー（名前空間内で一意な識別子）	文字列半角英数-_	g000000
	groupRole1	組織ロール1として設定するユーザ	ユーザのnamespaceとidを「#」で結合し、namespace#idの形式で設定する。複数設定する場合は設定値を""で囲み、「,」をデリミタとして、"namespace#id,namespace#id"の形式で設定する	"JinjiSystem#u0001,JinjiSystem#u0002"
	groupRole2	組織ロール2として設定するユーザ	同上	同上
	groupRole3	組織ロール3として設定するユーザ	同上	同上
	groupRole4	組織ロール4として設定するユーザ	同上	同上
	groupRole5	組織ロール5として設定するユーザ	同上	同上
	groupRole6	組織ロール6として設定するユーザ	同上	同上
	groupRole7	組織ロール7として設定するユーザ	同上	同上
	groupRole8	組織ロール8として設定するユーザ	同上	同上
	gid(read only)	SmartDB内部の識別子（編集不可）	2から始まる7桁の数字	2000011
	name(read only)	組織名（編集不可）	100文字以下の文字列	営業部
	parent_name(read only)	親組織名（編集不可）	100文字以下の文字列	営業本部

サンプル

namespace,id,groupRole1,groupRole2,groupRole3,groupRole4,groupRole5,groupRole6,groupRole7,groupRole8,gid(read only),name(read only),parent_name(read only)
JinjiSystem,g000001,"JinjiSystem#u000001,JinjiSystem#u000002",JinjiSystem#u000003,,,,,,,2000011,営業部,営業本部
JinjiSystem,g000002,JinjiSystem#u000004,JinjiSystem#u000005,JinjiSystem#u000006,,,,,,2000011,営業部,営業本部

groupRole1からgroupRole8の各組織ロールに設定可能なユーザ条件は以下の通りです。
1. 一般ユーザ及びログイン不能ユーザを設定することができます。
2. 最大10ユーザまで設定することができます。
3. 設定対象の組織に所属している必要はありません。
4. コラボレータを設定することはできません。
組織ロールを削除する場合は、各組織ロールに対して空のカラムを設定する必要があります。
- (例) groupRole2を削除する場合 JinjiSystem,g000001,JinjiSystem#u000001,,JinjiSystem#u000004,….

付録

自動連携サンプル

自動連携のための連携サンプルを公開しています。詳細はアカウントマスタ連携サンプルを参照してください。