毕升Office账号可以是独立的账号，也可以是通过API从集成方同步而来的账号。
同步方式主要有两种：主动调用API批量同步；在需要时（如使用集成预览、编辑文件），通过API服务被动获取并创建账号。
¶ 一、主动同步
主动同步账号的方式主要分为下面两种：调用API批量同步账号，即使用相关接口和参数进行账号同步；配置LDAP信息同步账号，即使用LDAP进行账号同步。
¶ 调用API批量同步账号
该方法是指：集成系统主动调用毕升Office账号导入API批量导入用户账号信息。可导入通讯录信息、部门信息到毕升Office系统中，已经在系统中存在的账户信息不会被导入，仅会被更新。
使用此种方式时，需要先使用root管理员身份进行授权签名的操作，将获取的Token设置到Cookie中，然后再调用相关的接口。
向http://bsd_host/apps/api/contact/dataImport发送POST请求，请求需要传递的参数格式如下：
{
"contracts": [
{
"contractId": "linkedID_contractID001",
"title": "contract001",
"creator": {
"personInfoId": "linkedID_pInfoID001",
"userId": "IMPuser001",
"title": "IMPuser001_名称",
"phone": "00000000001",
"email": "IMPuser001@xx.xx"
}
}
],
"departments": [
{
"departmentId": "linkedID_depID001",
"title": "department001",
"parentDepartmentId": "$ROOT"
}
],
"personInfos": [
{
"personInfoId": "linkedID_pInfoID001",
"userId": "IMPuser001",
"title": "IMPuser001_名称",
"phone": "00000000001",
"email": "IMPuser001@xx.xx",
"parentDepartments": [
"linkedID_contractID001",
],
"frozen": false
}
]
}
¶ 参数中各部分的说明
¶ 1.通讯录信息
参数中的contracts部分为通讯录信息。contracts信息为空时，不进行通讯录创建的操作。
- contractId：集成系统中的通讯录ID。使用当前ID的通讯录存在时，不进行通讯录的创建。
- title：通讯录名称。
- creator：通讯录的创建者信息，创建者为通讯录的管理员。
- personInfoId：请参考用户信息中的personInfoId字段。
- userId：请参考用户信息中的userId字段。
- title：请参考用户信息中的title字段。
- phone：请参考用户信息中的phone字段。
- email：请参考用户信息中的email字段。
¶ 2.部门信息
参数中的departments部分为通讯录信息。departments信息为空时，不进行部门创建的操作。
- departmentId：集成系统的部门ID。使用当前ID的部门存在时，不进行部门的创建。
- title：部门的名称。
- parentDepartmentId：部门的父级节点。值为$ROOT时，将在默认通讯录下创建子部门；值为部门ID时，将在此部门下创建子部门。父部门要先于子部门创建（导入），即在部门列表信息中，父部门的导入数据应在子部门数据的上方；值为通讯录ID时，将在此通讯录下创建子部门。
¶ 3.用户信息
参数中的personInfos部分为通讯录信息。personInfos信息为空时，不进行用户创建的操作。
- personInfoId：集成系统的用户ID，作为额外的信息保存在毕升Office系统用户中，用于关联集成系统中的用户和被导入毕升Office系统中的用户。使用当前ID的用户存在时，不进行用户的导入。
- userId：指定毕升Office系统中的用户ID，并作为用户的登录ID使用。4位以上数字或字母，可以包含半角符号，且不能与毕升Office系统中其他的用户ID重复。
- title：用户名称。
- phone：电话信息（可选参数）。需要符合电话号码的格式(11位数字)，与其他用户的电话信息重复时，数据导入将会失败。
- email：邮件信息（可选参数）。需要符合邮件的格式，与其他用户的邮件信息重复时，数据导入将会失败。
- parentDepartments：用户身份的父级节点信息。形式为字符串数组，内容可以为通讯录ID或部门ID。
- frozen：指定为true时，将会把用户更新为冻结状态。指定为false时，会将已经冻结的用户更新为正常状态，如果用户为重置密码状态则不会进行更新。
在系统中包含多个通讯录时，用户身份可能同时存在于多个通讯录的不同部门中，此时需要在parentDepartments中添加不同通讯录下的部门ID，即可在不同通讯录的部门中导入用户身份。值为$ROOT时，指示当前用户身份在默认通讯录下。
$ROOT只在系统被初始化为单租户系统时可用。
¶ 错误代码说明
- 101014 用户信息更新失败。
- 104005 通讯录创建失败。
- 104006 部门创建失败。
- 104009 更新部门的父级部门失败。
- 104011 通讯录更新失败。
- 104037、104040 获取部门或通讯录失败。请检查通讯录或部门ID；请确认父层级的部门先于子层级的部门创建；使用$ROOT时，请确保系统初始化时创建了默认通讯录（即仅在单租户系统使用）。
- 104038 用户字段检查失败。请确认用户ID，电话，邮箱的格式是否正确；请确认用户ID，电话，邮箱不与其他用户的重复。
- 104039 部门获取失败。
- 104041 用户导入失败。
- 104042 用户移动失败。
- 104043 用户节点创建失败。
- 104044 在部门中创建部门失败。
- 104045 创建用户文件失败。
- 105007 获取用户信息失败。
¶ 主动同步导入案例
导入的参数结构如下：
{
"contracts": [
{
"contractId": "linkedID_contractID001",
"title": "contract001",
"creator": {
"personInfoId": "linkedID_pInfoID001",
"userId": "IMPuser001",
"title": "IMPuser001",
"phone": "00000000001",
"email": "IMPuser001@xx.xx"
}
},
{
"contractId": "linkedID_contractID002",
"title": "contract002",
"creator": {
"personInfoId": "linkedID_pInfoID002",
"userId": "IMPuser002",
"title": "IMPuser002",
"phone": "00000000002",
"email": "IMPuser002@xx.xx"
}
}
],
"departments": [
{
"departmentId": "linkedID_depID001",
"title": "department001",
"parentDepartmentId": "$ROOT"
},
{
"departmentId": "linkedID_depID001_1",
"title": "department001_1",
"parentDepartmentId": "linkedID_depID001"
},
{
"departmentId": "linkedID_depID002",
"title": "department002",
"parentDepartmentId": "linkedID_contractID001"
}
],
"personInfos": [
{
"personInfoId": "linkedID_pInfoID001",
"userId": "IMPuser001",
"title": "IMPuser001",
"phone": "00000000001",
"email": "IMPuser001@xx.xx",
"parentDepartments": [
"linkedID_contractID002",
"linkedID_depID002"
]
},
{
"personInfoId": "linkedID_pInfoID002",
"userId": "IMPuser002",
"title": "IMPuser002",
"phone": "00000000002",
"email": "IMPuser002@xx.xx",
"parentDepartments": [
"$ROOT"
]
}
]
}
在毕升Office系统中创建的用户结构为：
¶ 配置LDAP信息同步账号
在毕升Office系统中，可以进行LDAP信息的配置，从而实现从集成方的LDAP服务中导入既存的部门、用户信息，并使用集成方LDAP服务进行用户登录验证的功能。
¶ LDAP配置说明
¶ 1. yml文件配置
ldap:
basedn: dc=company,dc=com
adminuid: admin
adminpassword: 123456
ldapurl: ldap://yourhost:389
¶ 2. 后台管理配置
LDAP设置画面如上图，其中各项目的说明如下：
- 刷新LDAP连接
点击此按钮可以刷新LDAP服务的连接。在配置yml文件中的LDAP信息后，毕升Office系统启动时会进行LDAP服务的连接。如果集成方的LDAP服务在毕升Office系统连接后，进行了重启等操作，将会导致毕升Office系统启动时的LDAP连接失效，此时需要点击此按钮进行LDAP服务连接的刷新。 - 从LDAP中导入数据
点击此按钮可以进行LDAP数据的导入，导入前请确认下方的导入信息设置无误并成功保存。详细请参考LDAP账号同步说明。 - 启用LDAP用户认证
设置为开启状态时将使用LDAP服务进行用户登录的验证，设置为关闭状态时将使用毕升Office系统（即用户名和用户设置的密码）进行用户登录的验证。详细请参考LDAP账号验证说明。 - 用户导入目标通讯录
可从下拉列表中进行选择，设置数据导入的目标通讯录。 - 使用OU作为部门结构
设置为开启状态时，将使用OU（组织单元）作为毕升Office系统中的部门结构导入；设置为关闭状态时，将仅导入LDAP服务中的用户信息。 - OU类设置
将使用设置的类名（objectClass）在LDAP服务中进行查询，获取OU的列表。默认值为top、organizationalUnit。 - OU属性对应关系
设置OU与毕升Office系统部门属性的对应关系，将使用设置的OU属性的值作为部门信息创建部门。设置为空时将不进行对应信息的导入。默认值为部门名称-ou、部门描述-description。 - 用户ID属性名称
设置LDAP服务中用户唯一ID的属性名称，将使用设置的属性值作为导入用户的用户ID。默认值为uid。 - 用户类设置
将使用设置的类名（objectClass）在LDAP服务中进行查询，获取用户的列表。默认值为top、posixAccount、inetOrgPerson。 - 用户属性对应关系
设置LDAP用户与毕升Office系统用户属性的对应关系，将使用设置的用户属性的值作为用户信息创建用户。设置为空时将不进行对应信息的导入。默认值为用户名称-displayName、用户描述-description、电话-mobile、邮箱-mail。
¶ LDAP账号同步说明
- 同步账号
点击从LDAP中导入数据按钮可以进行数据导入；进行LDAP用户认证时也可能进行数据导入(参考)。将使用设置的导入信息，将数据导入到指定的通讯录中。使用OU作为部门结构设置为开启状态时，将使用OU作为部门结构进行导入，毕升Office系统中将会创建相应的部门结构；设置为关闭状态时，仅在指定通讯录中创建相应的用户信息。
进行数据导入时，目标通讯录中既存的结构不会受到影响。
如果当前的数据中导入了部门（OU）结构，关闭使用OU作为部门结构再次进行导入时，将会移除此前从LDAP中导入的部门。 - 异常节点
如果已经导入的用户在LDAP服务中被删除，再次进行数据导入时，将会把此用户作为异常节点移动到指定通讯录的AdditionalNode部门并冻结此用户。
如果某部门结构（OU）已由LDAP服务导入至系统中，在LDAP服务中移动部门及其子用户后，此时进行数据导入时，将会在毕升Office系统中删除原有部门，并在新位置创建新部门，子用户将被移动到创建的新部门中。如果原有部门不为空，子内容中包含由毕升Office系统创建的用户或部门，则会将原有部门作为异常节点移动到AdditionalNode部门。
¶ LDAP账号验证说明
- 启用LDAP用户认证为关闭状态时，将使用毕升Office系统的用户名密码进行登录的验证。导入LDAP用户后，如果没有启用LDAP验证或验证开关由开启切换到关闭时，被导入的用户可使用系统默认密码进行登录并设置新密码。
- 启用LDAP用户认证为开启状态时，将使用LDAP服务进行登录的验证。管理员账户不使用LDAP验证。当用户在管理界面被冻结时，即使通过了LDAP验证，也不可以进行登录。如果验证成功的用户在LDAP服务中存在，但在毕升Office服务中不存在时，此时系统将会进行用户导入的处理。
¶ 导入案例
LDAP服务中的数据结构如下图所示：
设置LDAP导入所需的信息后，点击从LDAP中导入数据按钮，LDAP中的数据将会被导入至毕升Office系统中。
¶ 二、被动同步（syncUserUrl）
该方法是指集成方提供一个请求用户信息的服务地址，当毕升Office服务发现该用户信息不存在的时候，将调用该服务地址请求用户数据，并在毕升Office系统中创建账号。例如服务地址的值为http://yourhost/getUserInfo，需要获得userId为”externalUser“的用户信息时，系统将会发送GET请求至http://yourhost/getUserInfo?userid=externalUser。获取到的用户信息返回值的结构应如下：
{
"status": true,
"user": {
"userId":"externalUser",
"uname": "externalUserName",
"avatar": "http://yourhost/avatar.png",
"phone": "",
"email": "",
"department": {
"departmentId": "externalDepartmentId001",
"title": "externalDepartmentName001",
"subDepartment": {
"departmentId": "externalDepartmentId002",
"title": "externalDepartmentName002",
"subDepartment": {
"departmentId": "externalDepartmentId003",
"title": "externalDepartmentName003"
}
}
}
}
}
其中 status字段为该服务调用返回的状态。user内数据为用户的具体信息。
- userId：用户的Id。
- uname：用户的昵称。
- avatar：用户头像（可选参数）。图像文件的地址，毕升Office系统将会进行下载并同步至当前用户信息中。
- phone、email：用户联系方式（可选参数）。格式需正确且不与Office系统中既存用户的联系方式重复。
- department：用户所属的部门的结构（可选参数）。此部门对象为空时，将把用户创建在默认通讯录中；不为空时，将在默认通讯录中创建新部门，然后在新部门中创建用户。
- departmentId：集成方系统中该部门ID。
- title：部门名称。
- subDepartment：当前部门的子部门。子部门中可以嵌套部门结构，创建用户时会创建指定的部门结构，并将用户创建在最后一个子部门中。
¶ 被动同步导入案例
{
"status": true,
"user": {
"userId": "avatar",
"uname": "avatar_Name"
"avatar":"",
"phone":"",
"email":""
"department": {
"departmentId": "myDevDepartment",
"title": "研发部",
"subDepartment": {
"departmentId": "myOwnDepartment",
"title": "drive 研发小组"
}
},
}
}
以上数据样例中定义了一个用户，属于“研发部”->“office研发小组” 的部门结构。该数据结构导入之后，系统通讯录将逐层检查部门是否存在，如果不存在则将创建该部门，然后在最后的子部门下创建用户。
¶ 配置账号同步服务地址
api:
syncuserurl: ""
¶ 被动导入用户应用场景
被动导入的触发的时机为调用API获取授权签名时，系统会检测申请授权的用户id是否在系统中，如果不在将触发账号被动同步： 根据请求中的同步账号地址，或者系统配置的账号同步地址进行账号同步。具体参考获取授权签名