CSV連携

概要

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

ファイル仕様

デリミタ

, (半角カンマ)

文字コード

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

電話番号1

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

電話番号2

同上

03-xxxx-xxxx

ext

内線番号

30文字以下の文字列

100

fax1

Fax1

同上

03-xxxx-xxxx

fax2

Fax2

同上

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,…​.

付録

自動連携サンプル

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