定制空间站邀请、设置权限的通讯录界面

在一些大型和中型企业中，私有化部署后，邀请功能的默认设置通常只允许邀请外部人员，例如通过输入邮箱生成邀请链接。然而，在这些企业中，随意邀请外部人员是不可行的，因为它们通常依赖于自己的身份管理系统，如 SAML 或 Active Directory。

这些企业希望在点击邀请界面后，能够读取特定账号的信息，以便手动选择用户加入他们的工作空间。这样做可以有效限制外部用户的访问，确保企业的安全和数据保障，从而确保所有账号均为内部员工。

大概使用效果如下：

1. 当用户点击「邀请加入空间站」之后，会触发这个定制的邀请界面（由你自定义的成员结构）；
2. 当用户点击「设置权限」- 「邀请」之后，会触发这个定制的邀请界面；

流程如下:

这种方式，也保证你们企业内部的数据完全，在 Bika.ai 不会侵入到你们通讯录架构，就能实现安全的空间站邀请和设置权限。Bika 不存在说“主动抓取”企业的通讯录的这个行为，这是不合规的。

具体的通讯录渲染，将交给你的 Callback API 去控制，确保数据安全，和扩展性、灵活性。

你甚至可以在 callback 中，控制邀请加入的，只能是自己的部门范围。

具体你应该怎么做？

第一步是注册一个 Outgoing Webhook，这个 outgoing webhook 会进行拦截。拦截后，需邀请成员。

注册地址: help/zh-CN/guide/self-hosted/site-admin-open-api/注册 outgoing-webhooks

// 注册请求体示例
{
  "name": "组织回调API",
  "callbackURL": "https://your.domain.com/api/v1/org",
  "description": "邀请组织回调API, 获取第三方组织架构信息",
  "eventType": "ON_MEMBER_INVITE"
}

注册完成后，每次服务器与客户端交互时，点击 UI 界面时，系统会判断是否存在需要注册的钩子。如果存在，系统就会拦截请求，并向Outgoing Webhook注册的地址请求真实的通讯录数据。

你需要写一个用于 callback 的 server，以下以 express 代码为例子。

const express = require('express');
const app = express();
const port = 3000;

const data = {
    pagination: {
      pageNo: 1,
      pageSize: 50,
      total: 200,  
    }
    data: [
        {
            id: "meb5Y3Ax763TDySo0lju6sXK",
            name: "小明",
            type: "Member",
            avatar: "https://s1.bika.ai/avatar/0c4e2f8b-1a5d-4a7b-9c6d-0f3e1f2a5b8b.png",
            email: "xiaoming@bika.ai"
        },
        {
            id: "mebqvbWkZ7alyCpdqgBFxj5F",
            name: "张三",
            type: "Member",
            avatar: "",
            email: "zhangshan@bika.ai"
        },
        {
            id: "temcaKvFFrXhb8rxZzlwcEN3",
            name: "测试小组",
            type: "Team",
            parentId: "rootIUhGCOrBkpEwNtCY8gIbk",
            memberCount: 1
        },
        {
            id: "temcaDKFFrXhb8rxZzlwsEN9",
            name: "运营小组",
            type: "Team",
            parentId: "rootIUhGCOrBkpEwNtCY8gIbk",
            memberCount: 6
        },
        {
            id: "rolxxxxxxxxx",
            name: "群组: 小明 & 张三",
            type: "Role",
            parentId: "rootIUhGCOrBkpEwNtCY8gIbk",
            memberCount: 2
        },        
    ]
};

app.get('/api/v1/org', (req, res) => {

    // 可选, 通过用户和appId 校验身份和它所在租户 
    //const { userId } = req.headers;
    //if (!userId) {
    //    return res.status(401).json({ error: 'Unauthorized: Missing userId or appId in headers' });
    //} 

    const { keyword = '', pageSize = 10, pageNo = 1 } = req.query;

    const filteredData = data.data.filter(item =>
        item.name.includes(keyword) || (item.email && item.email.includes(keyword))
    );

    const startIndex = (pageNo - 1) * pageSize;
    const paginatedData = filteredData.slice(startIndex, startIndex + parseInt(pageSize));

    res.json({
        data: paginatedData,
        pagination: {
           pageNo: parseInt(pageNo),
           pageSize: parseInt(pageSize),
           total: filteredData.length
        }
    });
});

app.listen(port, () => {
    console.log(`Server is running on http://localhost:${port}`);
});

你们的服务器在完成特定操作后返回的数据，将用于渲染 UI 界面。

Bika 获取 Webhook 格式示例:

const fetch = require('node-fetch');

// 请求的 URL（根据实际情况修改）
const url = 'https://your.domain.com/api/v1/org'; // 替换为实际的接口地址

// 构造带有查询参数的 URL
const queryParams = new URLSearchParams({
  type: 'Team',  // 查询组织人员时传 Team , 查询角色时传 Role
  teamId: '',    // (可选)查询子部门ID, 为空时从根部门开始查
  keyword: '',
  pageNo: 1,
  pageSize: 50
});
const finalUrl = `${url}?${queryParams.toString()}`;

// 设置请求头，包含 openUserId
const headers = {
  'userId': '你的_userId_值' // 替换为实际的 UserId 值
  'spaceId': 'xxxx'
};

// 发起 GET 请求（根据实际接口需求调整请求方法）
fetch(finalUrl, {
  method: 'GET',
  headers: headers
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json(); // 假设响应是 JSON 格式
})
.then(data => {
  console.log('请求成功，返回数据：', data);
})
.catch(error => {
  console.error('请求出错：', error);
});

需要注意的是，最终获取的数据需要满足以下 schema，以便进行回调注册接口：

Schema 如下，供参考：

import { UnitVOSchema, type UnitVO } from '@bika.ai/types';

interface DataItem {
    id: string;
    name: string;
    type: "Member" | "Team" | "Role";
    avatar?: string;
    email?: string;        //可选, 仅type为Member生效 
    parentId?: string;     //所属小组Id 
    memberCount?: number;  //可选, 仅type为Team和Role生效 
} 

interface Pagination {
    pageNo: number;
    pageSize: number;
    total: number; 
}

interface ResponseSchema {
    pagination Pagination;
    data: DataItem[];
}

最终的通讯录界面大致如下：这个特定的通讯录界面与邀请通讯录界面相似，但其中的数据是通过外部企业的账号体系获取的。

点击确认邀请或设置权限逻辑代码

如何定制出一个对应的一个通讯录设置界面？那接下来这个你在上面之后就是会读取到你们组织内部 SAML 的那种特质的那些通讯录了，点击「确认」，会执行另一个 Do Member outgoing webhook 的回调。

// 注册请求体示例
{
  "name": "邀请组织回调API",
  "callbackURL": "https://your.domain.com/api/v1/member/invite",
  "description": "邀请组织回调API, 获取第三方组织架构信息",
  "eventType": "DO_MEMBER_INVITE",
  
}

在这个 callback 之后，Bika 不会做任何的邀请加入空间站和设置权限的具体行为，仅仅进行一个callback。

curl -X POST "https://your.domain.com/api/v1/invite" \
   --header 'Content-Type: application/json'
   --data '{
     "spaceId": "spcXxx124",
     "userIds": [ "meb5Y3Ax763TDySo0lju6sXK", "mebqvbWkZ7alyCpdqgBFxj5F" ], 
     "teamIds": [ "temcaDKFFrXhb8rxZzlwsEN9" ],
     "roleIds":  ["rolxxxxxx"],
     "nodeId": ""    // 绑定节点Id, 设置权限时生效
   }'

在 callback 中，你需要执行 site-admin OpenAPI，进行「加入空间站」和「设置权限」的 API 调用。

通常「设置权限」，会触发「邀请加入空间站」+「新建角色」+「设置角色权限」。

系统创建角色组后, 如更新群组成员和名称时, 调用 site-admin OpenAPI 同步即可。

总结 & 自检清单

为了接入定制的组织界面，我们这里总结一下需要做的事情：

Bika.ai已经提供了:

1. 提供outgoing webhook ON_MEMBER_INVITE(获取定制组织架构) 和 DO_MEMBER_INVITE (确认邀请触发) 。
2. 定制UI界面显示组织架构。
3. openAPI 提供了三个接口: 创建角色、更新角色和 添加角色权限。

你需要：

1. 按结构定义提供组织架构接口。
2. 点击确认邀请时,调用 site-admin OpenAPI接口 「邀请加入空间站」

确认授权时,调用 site-admin OpenAPI 接口 「邀请加入空间站」+「新建角色」+「设置角色权限」 。

1. 角色(群组)更新, 调用 site-admin OpenAPI 同步。

• 突破习惯养成困境：从普通追踪到自动化助力
• 突破习惯养成困境：从普通追踪到自动化助力——法律案件追踪与账单管理模板的独特价值
• 突破习惯养成困境：从普通追踪到自动化助力
• 突破习惯养成困境：从普通追踪到自动化助力
• 突破习惯养成困境：从普通追踪到自动化助力