launchpad-dx-apis

Launchpad 数据模型

Launchpad 由多个应用组成，每个应用都包含工作流或数据，用于存储生命周期信息和数据模型。 Launchpad 提供 COnstellation UI，用于创建和运行这些工作流和数据。在某些场景中，我们有时可能需要通过 Launchpad 中的 Rest 服务从外部创建 Case。或者，如果工作流中的某个步骤需要由外部系统完成，则可以使用 DXAPIs。 DX APIs 被称为 Digital Experience APIs，因为它们类似于 Rest 端点，既能提供数据，也能提供视图元信息，以便你使用这些视图元数据在外部系统中显示对象。 在本技能的上下文中，我们将仅关注 DX APIS，即我们有哪些类型的 API，以及如何使用它们。

DXAPIs 类型

我们提供以下 DX APIs：

1. 在 Launchpad 上创建 Case 或 Data 对象
2. 获取对象的 Case/Data 信息
3. 对特定工作流/Case 执行操作。
4. 通过传入筛选条件获取对象列表
5. 获取应用的其他内容，例如附件。

身份验证

Launchpad 支持 OAuth 2.0 身份验证，以调用这些 DXAPIs。 要调用 DX APIs，必须在 Launchpad 的 Subscriber 环境中创建 Client Registration 规则。创建此 Client Registration 时，可以指定将使用该 Client Registration 的 Persona。 因此，使用这些凭据调用任何 DXAPI 时，该 DXAPI 的访问角色和权限将由 Client Registration 中指定的 Persona 决定。因此，创建 Client Registration 时选择合适的 Persona 非常重要，因为这将决定可以使用该 Client Registration 调用哪些 DX APIs。 外部系统或团队在继续操作前，需要向托管 Launchpad 环境的团队索取以下 4 项信息：

1. 应用 URL
2. AccessTokenURL
3. ClientID
4. Client Secret

获取这些信息后，我们就可以使用上述详细信息构建一个与 Launchpad 应用交互的系统。 AccessToken URL 可用于身份验证，而应用 URL 可用于调用 DXAPIs。

创建 Case DX API – 标量内容

当外部系统需要通过向 Launchpad 发送数据来创建新的 Case 或 Data 对象时，请使用此模式。

创建案例

方法：POST 端点：https:///dx/api/application/v2/cases 请求： 正文： { "caseTypeID": "ExpenseRequest", "content": { "ExpenseeRaisedBy":"John Doe", "Name":"个人姓名的费用申请", "Category":"差旅", "Expenses": { { "TravelType":"航空", "Amount":1000$ }, { "TravelType":"出租车" "Amount":100$ } }, "TotalAmount":1100$, "Team":"团队 A" "ReasonforExpense":"需要前往另一座城市参加会议" } } 响应： { "data": { "caseInfo": { "caseTypeID": "ExpenseRequest", "caseTypeName": "费用申请", "createTime": "2025-12-19T21:35:04.315Z", "createdBy": "SystemUser", "ID": "STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz", "businessID": "ROT-715ABE", "assignments": [ { "actions": [ { "ID": "ReviewExpenseRequest", "links": { "submit:Approve": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Approve", "rel": "self", "title": "批准", "type": "PATCH" }, "ID": "ReviewExpenseRequest", "links": { "submit:Reject": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Reject", "rel": "self", "title": "拒绝", "type": "PATCH" }, }] } "availableActions":[...] } } }

创建数据对象

方法：POST 端点：https:///dx/api/application/v2/objects 请求： 正文： { "objectTypeID": "Category", "content": { "CategoryName":"Hotel" } } { 响应：

“data”:{ "ID": "STE6Q29tbWVyY2lhbERlYWxDbG9zaW5nRnVuZGluZ19fTmV3RGVhbENsb3N1cmVfNjkzYzcwZjAyZjcyMjU0YTNlMjhkM2Qw" } }

错误：如果您无权创建案例或数据对象，则会收到 403 错误，提示您没有创建案例或数据对象的权限。因此，务必确保客户端注册中提供的 Persona 有权在应用程序中创建案例或数据对象。

如我们所见，创建案例或数据对象的请求正文非常相似，唯一的区别在于端点和要创建的对象类型。创建案例时，需要提供 caseTypeID；创建数据对象时，需要提供 objectTypeID。响应中会返回已创建案例或数据对象的 ID，可用于在其他 DXAPI 中引用该案例或数据对象。

创建请求正文中可传递的字段必须配置为案例或数据对象的允许字段。如果尝试传递未配置为允许字段的字段，API 将报错并提示数据无效。允许字段中标记为必填的字段都必须提供。此外，如果提供了不属于允许字段的字段，该字段将被忽略，不会在案例或数据对象上创建。因此，务必确保要在创建请求正文中传递的所有字段都已配置为案例或数据对象的允许字段。

创建案例 API 的响应中还会返回案例上可用的操作，可用于在创建案例后对其执行操作。例如，在上述响应中，我们有一个名为 ProvideAdditionalDetails 的操作，可用于在创建案例后将其他说明从外部系统发送到 Launchpad 应用程序。我们可以使用响应中提供的 href，通过 PATCH 请求调用该操作，并在请求正文中传递其他说明。

创建案例后，应在外部系统中的某处存储案例 ID，以供日后引用。此 ID 可用于对案例执行各种操作，例如更新案例、对案例执行操作、获取案例详情等。

使用 DX API 获取现有案例或数据对象

当外部系统需要通过向 Launchpad 发送请求来获取现有案例或数据对象的详情时，请使用此模式。可在案例或数据对象创建后获取其详情，也可在对其进行更新之前获取最新详情。

方法：GET 端点：https:///dx/api/application/v2/cases/STE6Q29tbWVyY2lhbERlYWxDbG9zaW5nRnVuZGluZ19fTmV3RGVhbENsb3N1cmVfNjkzYzcwZjAyZjcyMjU0YTNlMjhkM2Qw

注意：使用创建案例 API 响应中的 ID 请求： 响应：与创建案例 API 的响应类似，但包含案例的所有详情，可供日后引用。 { "data": { "caseInfo": { "caseTypeID": "ExpenseRequest", "caseTypeName": "费用申请", "createTime": "2025-12-19T21:35:04.315Z", "createdBy": "SystemUser", "ID": "STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz", "businessID": "ER-715ABE", "assignments": [ { "actions": [ { "ID": "ReviewExpenseRequest", "links": { "submit:Approve": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Approve", "rel": "self", "title": "批准", "type": "PATCH" }, "ID": "ReviewExpenseRequest", "links": { "submit:Reject": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Reject", "rel": "self", "title": "拒绝", "type": "PATCH" }, "open": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest", "rel": "self", "title": "获取任务操作详情", "type": "GET" } }, "name": "管理者分配前期工作", "type": "FlowAction" }, { "ID": "ChangeAssignmentGoalAndDeadline", "links": { "open": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ChangeAssignmentGoalAndDeadline", "rel": "self", "title": "获取任务操作详情", "type": "GET" } } } }}] ] "availableActions": [ { "ID": "ProvideAdditionalDetails", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/ProvideAdditionalDetails", "rel": "self", "title": "获取案件操作详情", "type": "GET" } }, "name": "编辑", "type": "Case" }, { "ID": "Edit", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/Edit", "rel": "self", "title": "获取案件操作详情", "type": "GET" } }, "name": "编辑", "type": "Case" }, { "ID": "pyChangeStage", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/pyChangeStage", "rel": "self", "title": "获取案件操作详情", "type": "GET" } }, "name": "更改阶段", "type": "Case" }, { "ID": "RestartCurrentStage", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/RestartCurrentStage", "rel": "self", "title": "获取案件操作详情", "type": "GET" } }, "name": "重新启动当前阶段", "type": "Case" }, } } } 此 API 的响应将包含 Case ID、案例的更多详细信息，以及作为 AvailableActions 的分配操作和案例操作。

分配操作

这些是完成此任务必须执行的操作。如果 Case 中有一项任务需要用户执行，那么这项任务就属于分配操作。结果是用户执行此操作时可以选择的可能结果。在 Launchpad UI 中，这些内容会显示为按钮。在上面的示例中，ReviewStep 用户可以选择批准或拒绝。因此，通过 DXAPI，用户可以决定采取哪项操作，然后在执行操作时提供字段数据。

可用操作

在 Launchpad 中，我们有一个可用操作的概念，适用于任意 Stage、Step 或 Case 级别的操作。这些都是用户可以在 Case 上执行的可选操作。执行这些操作的方式与分配操作类似，但它们并非完成任务的必需操作。这些操作可以在 Case 生命周期的任意时间执行。例如，在上面的 Case 中，我们有一个名为 ProvideAdditionalDetails 的可用操作，可用于在 Case 生命周期的任意时间提供补充信息。 此外，只要这些操作仍然可用，就可以执行任意次数。每个 Get 请求都会返回相应的操作。

错误：如果您无权访问 Case 或数据对象，则会收到 404 错误，提示找不到 Case 或数据对象。因此，务必确保客户端注册中提供的 Persona 有权访问您尝试获取的 Case 或数据对象。

在响应标头中，我们会收到一个名为 eTag 的标头，可用于后续更新 Case。此 eTag 值对每个 Case 都是唯一的，并且每次 Case 更新时都会变化。因此，每当我们要更新 Case 时，都需要在更新请求的 If-Match 标头中传递此 eTag 值，以确保更新的是 Case 的最新版本，并且没有并发更新正在进行。

使用 DX API 更新现有 Case 或数据对象

当外部系统需要通过向 Launchpad 发送数据来更新现有 Case 或数据对象时，请使用此模式。

用例 1：对只有一个结果的 Case 执行可用操作

方法：PATCH 端点：https:///dx/api/application/v2/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MGYwMmY3MjI1NGEzZTI4ZDNkNA/actions/ProvideAdditionalDetails?outcome=Submit 注意：使用 Get Case 或 Create Case 响应中的 actions:href

请求： 标头： If-Match: 1（此值来自 Get Case 响应中的 eTag 标头） 正文： { "content": { "ReasonForExpense":"主要是为了参加在另一个城市举行的会议，也需要在那里会见一些客户，因此这次出行很重要。" } }

用例 2：对 Case 执行分配操作并选择操作结果

方法：PATCH 端点：https:///dx/api/application/v2/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MGYwMmY3MjI1NGEzZTI4ZDNkNA/actions/ReviewExpenseRequest?outcome=Accept 注意：使用 Get Case 或 Create Case 响应中的 actions:href

请求： 标头： If-Match: 1（此值来自 Get Case 响应中的 eTag 标头） 正文： { "content": { "Comments":"这是一笔有效的费用，我批准这项申请。" } }

用例 3：对 Case 执行可用操作

方法：PATCH 端点：https:///dx/api/application/v2/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/Edit 注意：使用 Get Case 或 Create Case 响应中的 actions:href

请求： 标头： If-Match: 1（该值来自 Get Case 响应的 eTag 标头） 正文： { "content": { "ReasonForExpense":"主要是为了参加另一个城市的会议，同时还需要在那里会见一些客户，因此这次出行很重要。" } } 错误：如果你没有权限对 Case 或数据对象执行此操作，将收到 404 错误，提示你没有权限执行此操作。 错误：Case 上定义的任何 Case/Stage/Step 验证都会执行；如果更新请求中发送的数据不符合验证条件，将收到包含验证错误详情的 400 错误。

使用 Data DX API 获取对象列表或任意数据

当外部系统需要根据某些筛选条件获取列表，甚至获取单条记录的案例或数据对象时，可以使用此模式。我们可能没有 Launchpad 生成的案例 ID，但知道某个案例字段及其值。如果 Launchpad 提供了一个将该字段作为参数的数据页，就可以使用此模式检索数据。

方法：POST 端点：https:///dx/api/application/v2/data_views/GetTeamExpenseRequests 注意：GetTeamExpenseRequests 是用于根据团队名称获取数据的数据页名称。 请求体 { "dataViewParameters": { "TeamName": "Team A" }, "query": { "select": [ { "field": "ExpenseRaisedby" }, { "field": "CreateDateTime" }, { "field": "Team" }, { "field": "ReasonsforExpense" }, { "field": "TotalAmount" }, { "field": "Status" } ] } }

响应： { "data": [ { "@version": 2, "@class": "ExpenseRequest", "ExpenseRaisedby": "John Doe", "CreateDateTime": "2025-12-22T17:02:56.890Z", "Team": "Team A", "ReasonsforExpense": "Client meeting travel and meals", "TotalAmount": 245.75, "Status": "Pending-Approval", "ID": "EXP-REQUEST-0001" } ], "pageNumber": 1, "pageSize": 1, "fetchDateTime": "2026-03-25T21:10:41.299Z", "totalCount": 27 }

根据以上示例，当用户要求为其应用生成 DX API 时，我们可以询问其使用场景，并根据场景建议使用哪种模式，同时为该场景生成示例请求和响应。 很多时候，使用场景可能是要从外部创建案例，或对案例执行特定操作。此时，可以根据使用场景询问用户需要哪些信息来构造请求体，以及需要哪个端点，然后生成 DX API 请求和响应。

例如，要创建案例，我们需要询问用户提供案例类型、标记为 Allowed Fields 的字段，以及这些字段的值。如果用户要求特定 API，就请其提供这些值；否则，可以使用示例数据生成。

用户可能会要求为 Launchpad 应用中的所有案例生成一个 Yaml 文件，并列出每个案例的可用操作和字段。在这种情况下，可以按照上文所示格式，生成包含所有案例及其详细信息的 yaml 文件。还可以告知用户在 Launchpad 应用中的哪里可以找到生成 yaml 文件所需的信息。可以通过以下位置获取这些信息：

1. 在 Casetype 规则的 Setting 选项卡中查找 Allowed Fields。
2. 在 Case type 规则的 optional actions 中查找 Optional Actions 或 Available actions。
3. 在各阶段的每个手动步骤以及已配置的结果中查找 Assignment actions。
4. 在每个案例类型规则的 Operations 选项卡中查找数据页名称。
5. 要了解 Action 请求体中的字段详情，可以查看各操作的视图。