> For AI agents: the complete documentation index is available at /resource/ucidm/docs/on-premise/dev/llms.txt, the full documentation bundle is available at /resource/ucidm/docs/on-premise/dev/llms-full.txt.

# 取り込み CSV の仕様 \{#csv-spec}

[CSV 一括取込画面](/resource/ucidm/docs/on-premise/dev/administration/ucidm-ui/admin.md#csv)でアップロードする CSV ファイルの仕様について説明します。

## ファイル形式 \{#file-format}

- 文字エンコーディングは **UTF-8 固定**です。BOM 付きの UTF-8 でも取り込めます（BOM は読み込み時に除去されます）。
  - Excel で編集した CSV を保存する場合は「CSV UTF-8（コンマ区切り）」を選択してください。Shift_JIS で保存された CSV は取り込めません。
- 1 行目はヘッダー行（カラム名の行）とし、2 行目以降を 1 レコードとして処理します。
- 値にカンマやダブルクォート、改行を含める場合は、CSV の一般的な作法どおりダブルクォートで値を囲みます。
  - 値の前後の空白と改行は取り除かれます。値の途中の改行はそのまま登録されます。

## カラム名（ヘッダー）の仕様 \{#header}

- カラム名は LDAP の属性名を指定します。**大文字と小文字は区別しません**（`userPassword` と `userpassword` は同じ扱いです）。
- **カラムの並び順は問いません。**
- 同じ属性を指す**カラムが複数存在する場合はバリデーションエラー**になります。
- リソースタイプがユーザーの場合は `username`、グループの場合は `groupname` カラムが**必須**です。これらがエントリーを特定するためのキーになります。
- 属性値が入っていないカラム（空文字）はスキップされます。ただし、登録・属性変更の対象となる属性が 1 つもない場合はバリデーションエラーになります。

### 特別なカラム \{#special-columns}

| カラム名           | 対象   | 説明                                                                                                                                             |
| :------------- | :--- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`     | ユーザー | ユーザー名。ユーザーを特定するキーとして使用します（必須）。                                                                                                                 |
| `groupname`    | グループ | グループ名。グループを特定するキーとして使用します（必須）。                                                                                                                 |
| `password`     | ユーザー | パスワード。連携元が OpenLDAP か Active Directory かに応じて `userPassword` または `unicodePwd` に置き換えて登録されます。                                                     |
| `objectClass`  | 両方   | 登録時に付与する objectClass。カラムがない場合は[初期値](/resource/ucidm/docs/on-premise/dev/administration/ucidm-ui/admin.md#preset-setting)の objectClass が使用されます。 |
| `parentDN`     | 両方   | 登録するエントリーの配置先を指定します（登録時のみ有効）。                                                                                                                  |
| `ucidmGroups`  | ユーザー | 所属させるグループを `groupname` で指定します。                                                                                                                 |
| `ucidmMembers` | グループ | 所属させるメンバーを `username` で指定します。                                                                                                                  |

- `parentDN` には、ベースの suffix から見た相対的な DN を指定します。ベースの suffix が `dc=example,dc=com` のとき、`parentDN` に `ou=Users` を指定すると `ou=Users,dc=example,dc=com` にエントリーを登録します。値が空の場合はベースの suffix（`dc=example,dc=com`）に登録します。
  - `parentDN` は**登録時のみ**参照されるカラムです。属性変更で DN を移動することはできません。
- `ucidmGroups` / `ucidmMembers` は、UCIDM が用意している特別なカラムです。グループのメンバー情報は、システム設定の `groupMemberAttribute`（`memberUid` / `member` / `uniqueMember` など）に対応する属性へ内部的に変換されて反映されます。DN 形式のメンバー値を使う設定かどうかも、この設定に従って自動的に判定されます。管理者が `groupMemberAttribute` の属性名を意識する必要はありません。

### 重複エラーになるカラムの組み合わせ \{#duplicated-columns}

同じ意味を持つカラムを同時に指定すると、どちらを優先すべきか決められないためエラーになります。

| 同時に指定できないカラム                                             |
| :------------------------------------------------------- |
| `password` と `userPassword` / `unicodePwd`               |
| `ucidmMembers` と `memberUid` / `member` / `uniqueMember` |

## 値の書き方 \{#values}

### 複数値（マルチバリュー）を指定する \{#multi-value}

1 つの属性に複数の値をセットするときは、カンマ区切りの文字列で表します。値全体をダブルクォートで囲む必要があります。

```csv
username,description,ucidmGroups
user01,説明,"mygroup1,mygroup2"
```

上記の場合、`user01` は `mygroup1` と `mygroup2` の 2 つのグループに所属します。

### 値としてカンマを使用する \{#comma}

カンマ区切りは複数値の区切り文字として解釈されるため、カンマそのものを値として使いたい場合は `%{comma}` と記述します。`%{comma}` は CSV の読み込み処理の中で `,` に置き換えられて登録／更新されます。

```csv
username,description
user01,"OSSTech%{comma} Inc."
```

上記は `description` に `OSSTech, Inc.` という 1 つの値をセットします。

- UCIDM のテンプレートと記法を統一するため、`%` を特別な文字として扱っています。
- `parentDN` はカンマを含む DN を指定するカラムであるため、`%{comma}` に置き換える必要はありません（`ou=Sub,ou=Users` のようにそのまま記述します）。

### パスワードを自動生成する \{#password-generation}

`password` カラムには、値として以下のキーワードを指定できます。キーワードの大文字・小文字は区別しません。

| 値           | 説明                                                      |
| :---------- | :------------------------------------------------------ |
| `%{random}` | パスワードポリシーを満たすランダムなパスワードを生成して登録します。                      |
| `%{temp}`   | 一時パスワードを発行します。連携元 LDAP にはパスワードが書き込まれず、次回ログイン時に変更を要求します。 |

- 生成されたパスワードは、生成パスワード取得ページから取得できます。
- 一時パスワードを発行した場合も、CSV 取込履歴の操作種別は「パスワード変更」と表示されます。

### uidNumber / gidNumber の自動割り当て \{#auto-number}

`uidNumber`（ユーザー）、`gidNumber`（グループ）のカラムの値が空の場合、割り当て可能な番号が自動的にセットされます。

- 自動割り当てを行うには、[属性定義](/resource/ucidm/docs/on-premise/dev/administration/ucidm-ui/admin.md#management-attributes-setting)で対象属性の「複数の値を許可する」が**オフ**である必要があります。
- 多値として設定されている場合、自動割り当ては行われません。

## 操作種別ごとの仕様（ユーザー） \{#user}

ユーザーを特定するカラム名は `username` です。

### 登録（add） \{#user-add}

連携元 LDAP に対してユーザー登録を行います。

- 既に存在するユーザーを指定した場合はエラーになります。
- [初期値](/resource/ucidm/docs/on-premise/dev/administration/ucidm-ui/admin.md#preset-setting)の設定がある属性においても、属性の値を CSV で指定した場合、CSV ファイルでの値が使われます。
- `parentDN` カラムに値がある場合は `parentDN` + ベースの suffix で DN を生成し、値が空の場合はベースの suffix のみで DN を生成します。
- `password` カラムの値は、連携元が OpenLDAP か Active Directory かに応じて `userPassword` または `unicodePwd` に置き換えて登録されます。`%{random}` / `%{temp}` も使用できます。
- `ucidmGroups` カラムには所属させるグループの `groupname` を指定します。
  - 指定したグループが存在しない場合はエラーになります。
  - 既に所属しているグループがある場合、その所属情報は削除され、CSV で指定した所属情報に上書きされます。
- 値が空のカラムはスキップされます。登録対象の属性が 1 つもない場合はバリデーションエラーになります。

サンプル：

```csv
username,cn,sn,givenName,mail,uidNumber,parentDN,password,ucidmGroups
user01,Taro Yamada,Yamada,Taro,user01@example.com,,ou=Users,%{random},"mygroup1,mygroup2"
user02,Hanako Suzuki,Suzuki,Hanako,user02@example.com,,ou=Users,%{temp},mygroup1
user03,Jiro Sato,Sato,Jiro,user03@example.com,10003,,P@ssw0rd001,
```

- `user01` はランダムパスワードが生成され、`mygroup1` と `mygroup2` に所属します。
- `user02` は一時パスワードが発行され、初回ログイン時にパスワード変更が要求されます。
- `user03` は `uidNumber` を明示的に指定し、`parentDN` が空なのでベースの suffix 直下に登録されます。

### 属性変更（attributesUpdate） \{#user-attributes-update}

連携元 LDAP に対してユーザーの属性更新を行います。

- 存在しないユーザーを指定した場合はエラーになります。
- カラム名は `属性名.add` / `属性名.replace` / `属性名.delete` / `属性名.deleteAll` のいずれか、または `属性名`（`replace` 扱い）である必要があります。値が空文字の場合は何も行いません。

| カラム名の書式         | 動作                                              |
| :-------------- | :---------------------------------------------- |
| `属性名`           | `属性名.replace` と同じ扱いになります。                       |
| `属性名.add`       | 既存の属性値に対して、指定した値を追加します。                         |
| `属性名.replace`   | 既存の属性値を、指定した値で上書きします。                           |
| `属性名.delete`    | 指定した値を削除します。                                    |
| `属性名.deleteAll` | 値が `TRUE` の場合はその属性の値を全て削除します。`TRUE` 以外はスキップします。 |

- `ucidmGroups` カラムには所属させるグループの `groupname` を指定します。指定したグループが存在しない場合はエラーになります。
  - `ucidmGroups.add`：既にメンバーとして登録されている場合はエラーになります。
  - `ucidmGroups.replace`：既に所属しているグループのメンバー情報を削除し、指定したグループのメンバーとして登録します。
  - `ucidmGroups.delete`：指定したグループのメンバーとして存在しない場合はエラーになります。
  - `ucidmGroups.deleteAll`：値が `TRUE` の場合、対象ユーザーの所属グループのメンバー情報を全て削除します。
- `password` カラムには `%{random}` / `%{temp}` を指定できます。

サンプル：

```csv
username,mail.replace,telephoneNumber.add,description.deleteAll,ucidmGroups.add
user01,user01-new@example.com,03-0000-0001,,mygroup3
user02,,03-0000-0002,TRUE,
```

- `user01` は `mail` を上書き、`telephoneNumber` を追加、`mygroup3` に追加所属します。
- `user02` は `telephoneNumber` を追加し、`description` の値を全て削除します。`mail` は空文字なので変更されません。

### 削除（delete） \{#user-delete}

連携元 LDAP に対してユーザー削除を行います。

- 存在しないユーザーを指定した場合はエラーになります。
- `username` 以外のカラムの値は参照しません。
- ユーザーの削除にあわせて、所属していたグループのメンバー情報も削除されます。

サンプル：

```csv
username
user01
user02
```

### パスワード変更（passwordUpdate） \{#user-password-update}

連携元 LDAP に対してユーザーのパスワード更新を行います。

- 存在しないユーザーを指定した場合はエラーになります。
- `username` と `password` 以外のカラムの値は参照しません。
- `password` の値が空の場合はパスワードを更新しません。
- `%{random}` / `%{temp}` を指定できます。一時パスワードを発行した場合も、CSV 取込履歴の操作種別は「パスワード変更」と表示されます。
- `userPassword` や `unicodePwd`、`password` に代わるカスタム属性をパスワード属性として使用している場合は、パスワード変更ではなく[属性変更（attributesUpdate）](#user-attributes-update)で行ってください。

サンプル：

```csv
username,password
user01,%{random}
user02,%{temp}
user03,P@ssw0rd002
```

## 操作種別ごとの仕様（グループ） \{#group}

グループを特定するカラム名は `groupname` です。

### 登録（add） \{#group-add}

連携元 LDAP に対してグループ登録を行います。

- 既に存在するグループを指定した場合はエラーになります。
- [初期値](/resource/ucidm/docs/on-premise/dev/administration/ucidm-ui/admin.md#preset-setting)の設定がある属性においても、属性の値を CSV で指定した場合、CSV ファイルでの値が使われます。
- `parentDN` カラムに値がある場合は `parentDN` + ベースの suffix で DN を生成し、値が空の場合はベースの suffix のみで DN を生成します。
- `ucidmMembers` カラムにはメンバーとするユーザーの `username` を指定します。
  - 指定したユーザーが存在しない場合はエラーになります。
- 値が空のカラムはスキップされます。登録対象の属性が 1 つもない場合はバリデーションエラーになります。

サンプル：

```csv
groupname,description,gidNumber,parentDN,ucidmMembers
mygroup1,開発チーム,,ou=Groups,"user01,user02"
mygroup2,営業チーム,20002,ou=Groups,user03
```

- `mygroup1` は `gidNumber` が空なので自動割り当てが行われ、`user01` と `user02` がメンバーとして登録されます。

### 属性変更（attributesUpdate） \{#group-attributes-update}

連携元 LDAP に対してグループの属性更新を行います。

- 存在しないグループを指定した場合はエラーになります。
- カラム名の書式と動作は[ユーザーの属性変更](#user-attributes-update)と同じです。
- `ucidmMembers` カラムにはメンバーとするユーザーの `username` を指定します。指定したユーザーが存在しない場合はエラーになります。
  - `ucidmMembers.add`：既にメンバーとして登録されている場合はエラーになります。
  - `ucidmMembers.replace`：既に登録されているメンバーを削除し、指定したメンバーを登録します。存在しないユーザーが含まれている場合はエラーになります。
  - `ucidmMembers.delete`：メンバーとして存在しない場合はエラーになります。
  - `ucidmMembers.deleteAll`：値が `TRUE` の場合、メンバー情報を全て削除します。

サンプル：

```csv
groupname,description.replace,ucidmMembers.add,ucidmMembers.delete
mygroup1,開発チーム（第一）,user04,user02
mygroup2,,,user03
```

- `mygroup1` は説明を上書きし、`user04` をメンバーに追加、`user02` をメンバーから削除します。

### 削除（delete） \{#group-delete}

連携元 LDAP に対してグループ削除を行います。

- 存在しないグループを指定した場合はエラーになります。
- `groupname` 以外のカラムの値は参照しません。

サンプル：

```csv
groupname
mygroup1
mygroup2
```