Skip to main content

​
Sync your OA system with DingTalk Contacts

​
Prerequisites

Complete the Create an app process.

​
Step 1: Obtain the app credential

  1. Select the target app and go to the app details page. Click Basic Information > Credentials and Basic Information.
  2. Obtain the Client ID and Client Secret.

​
Step 2: Add API permissions

Click Development Configuration > Manage permissions. Enter qyapi_manage_addresslist in the permission search box and request the permission.

​
Step 3: Obtain the access token of the app

​
Important

  • For differences between Server APIs, see the comparison between the legacy Server API and the new Server API.
  • To download the Server API SDK, see Server SDK download.
Use the Client ID and Client Secret obtained in Step 1 to obtain the access_token of the internal app. 
public void getAccessToken() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
        OapiGettokenRequest req = new OapiGettokenRequest();
        req.setAppkey("dingxxxxxxxxxhgn");
        req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
        req.setHttpMethod("GET");
        OapiGettokenResponse rsp = client.execute(req);
        System.out.println(rsp.getBody());
    }

​
Step 4: Contacts sync workflow

  1. Sync DingTalk Contacts to the OA system contacts: The key to this sync is that any change in DingTalk Contacts must trigger a corresponding action in the OA system contacts.
    1. First, refer to the Get all employees in an organization document to import the current DingTalk Organization Structure into the OA system contacts.
    2. Use the event subscription feature provided by DingTalk and subscribe to contacts events. Changes in DingTalk Contacts will trigger corresponding callback events. For the format of contacts event push messages, see Contacts.
    3. The OA system receives and processes the contacts events pushed by DingTalk, and updates the OA system contacts accordingly.
  2. Sync OA system contacts updates to DingTalk Contacts: When information in the OA system contacts changes, sync the updates to DingTalk Contacts to keep them consistent.
    1. When a department is created in the OA system contacts, call the Create department API to create the same department tier and department name in the DingTalk Client-side based on the department tier and name in the OA system. 
       public void deptCreate() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/department/create");
        OapiV2DepartmentCreateRequest req = new OapiV2DepartmentCreateRequest();
        req.setParentId(1L);
        req.setOuterDept(true);
        req.setHideDept(false);
        req.setCreateDeptGroup(true);
        req.setOrder(1L);
        req.setName("1019 Department Test");
        req.setSourceIdentifier("1019 Department Test");
        req.setOuterPermitUsers("manager7675,01472825524039877041");
        req.setOuterDeptOnlySelf(true);
        OapiV2DepartmentCreateResponse rsp = client.execute(req, getAccessToken());
        System.out.println(rsp.getBody());
    }

​
Note

The department ID in DingTalk Contacts is automatically generated and cannot be set manually. When syncing contacts updates, use the department name as the identifier when syncing to DingTalk, and save the corresponding DingTalk Contacts department ID for later use. 2. Add roles to the OA system contacts based on the role information in the OA system.
  1. Call the Server API Add a role group to create role group information. 
    public void addRoleGroup() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/role/add_role_group");
        OapiRoleAddrolegroupRequest req = new OapiRoleAddrolegroupRequest();
        req.setName("1019 Test Role Group");
        OapiRoleAddrolegroupResponse rsp = client.execute(req, getAccessToken());
        System.out.println(rsp.getBody());
    }
  2. Call the Server API Create role to create role information for the organization. 
      public void addRole() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/role/add_role");
        OapiRoleAddRoleRequest req = new OapiRoleAddRoleRequest();
        req.setRoleName("1019 Test Role");
        req.setGroupId(3168010875L);
        OapiRoleAddRoleResponse rsp = client.execute(req, getAccessToken());
        System.out.println(rsp.getBody());
    }
  3. Call the Create user API to add employees from each department in the OA system to the corresponding departments in DingTalk. During this step, you can also assign role information to the employee. 
    public void createUser() throws ApiException {
        DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/create");
        OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
        req.setUserid("manger7666");
        req.setName("1009 Test User");
        req.setSeniorMode(false);
        req.setMobile("152****3025");
        req.setTitle("Technical Director");
        req.setEmail("test***@xx.com");
        req.setOrgEmail("test***@xxx.com");
        req.setOrgEmailType("profession");
        ArrayList<OapiV2UserCreateRequest.DeptTitle> deptTitles = new ArrayList<>();
        OapiV2UserCreateRequest.DeptTitle deptTitle = new OapiV2UserCreateRequest.DeptTitle();
        deptTitle.setDeptId(724960197L);
        deptTitle.setTitle("Senior Technical Director");
        deptTitles.add(deptTitle);
        req.setDeptTitleList(deptTitles);
        req.setHideMobile(false);
        req.setTelephone("010-8xxxxx6-2345");
        req.setJobNumber("202210190001");
        req.setHiredDate(1666143772000L);
        req.setWorkPlace("Alibaba Center****");
        req.setRemark("Remarks");
        req.setDeptIdList("724960197");
        List<OapiV2UserCreateRequest.DeptOrder> deptOrderList = new ArrayList<OapiV2UserCreateRequest.DeptOrder>();
        OapiV2UserCreateRequest.DeptOrder deptOrder = new OapiV2UserCreateRequest.DeptOrder();
        deptOrder.setDeptId(724960197L);
        deptOrder.setOrder(1L);
        deptOrderList.add(deptOrder);
        req.setDeptOrderList(deptOrderList);
        req.setExtension("{\"Hobby\":\"[Hobby](http://test.com?userid=#userid#&corpid=#corpid#)\"}");
        req.setManagerUserid("manager7675");
        req.setLoginEmail("test****@xxx.com");
        OapiV2UserCreateResponse rsp = client.execute(req, getAccessToken());
        System.out.println(rsp.getBody());
    }