端到端扩展场景用例集 · CAP 应用与智能体

项目

内容

官方仓库

SAP-samples/btp-end-to-end-scenario-use-cases

业务场景

以 S/4HANA 公有云为起点的多个完整并行扩展场景

技术栈

SAP BTP、CAP、Cloud Foundry / Kyma、目标(Destination)、通信安排、事件

对应课程

CLD200、BAS400、CF400、KYM400

对应路径

第 2 条:在 SAP BTP 上构建并行扩展

为什么值得做:这是一本「菜谱」。每个用例都是一条可独立复现的端到端 链路,覆盖从 BTP 账户搭建、连通性配置,到部署,再到与 S/4HANA 公有云交互的完整过程。

动手要点:

  • 每个用例都从前提条件讲起(需要哪些服务、哪些通信安排)——请严格照做。

  • 如果连不通,先拿目标(Destination)和通信安排对照检查一遍;这是最常见的坑。

本页内容抓取自官方仓库 SAP-samples/btp-end-to-end-scenario-use-cases,共收录 37 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。

掌握 SAP BTP 上的 Clean Core:VIBE 编码与 MCP 实战之旅

在本动手练习中,您将学习开发一个基于 SAP Cloud Application Programming Model(CAP)的全栈 SAP BTP 应用、一个基于 Fiori 的应用,并使用 VIBE 编码与 MCP 对其进行扩展,然后部署到 BTP。

您将构建什么

  • 使用 CAP 为 S/4HANA Cloud 构建一个扩展应用

  • 在 SAP Business Application Studio 中使用 Cline 进行 VIBE 编码,连接 CAP MCP server 和 SAP Fiori MCP server 等工具来扩展 CAP 应用

您将扩展 Incident Management CAP 应用:向 Incidents 实体添加 Resolution Note 字段,围绕该字段实施业务规则,并编写自动化测试——整个过程都由 Cline 中的自然语言提示引导。

MCP 智能体编码的关键能力

借助 MCP 服务器进行智能体编码,可以提供理解您特定代码库与开发模式的 AI 助手,从而改变您的开发工作流:

  • 上下文感知的代码生成——CAP MCP server 让 Cline 直接访问您的 CDS 模型定义、实体关系和 CAP 文档,避免凭空臆造。

  • Fiori 感知的 UI 更新——SAP Fiori MCP server 确保按照 SAP Fiori elements 约定,把 UI 注解添加到正确位置。

  • 自然语言提示——用通俗的英文描述您想要什么;文件修改、语法和验证都由 Cline 处理。

  • 自动校验——每次修改后,Cline 都会验证 CDS 模型能否编译、服务是否正确暴露。

业务场景

在本动手练习中,您将使用 SAP Build Code 构建一个名为 Incident Management 的应用。Incident Management 应用的业务场景如下:

ACME 是一家知名的电子公司。ACME 雇佣呼叫中心支持代表来处理和管理客户事件。呼叫中心支持代表(Processor)接到现有客户的电话,并代表客户创建一个新事件。新建事件基于电话中收到的客户投诉。呼叫中心支持代表还会把与客户的通话内容添加到事件中,以备后续参考。

解决方案图

解决方案图

前提条件

  • 在 SAP Business Application Studio 中配置 Cline

练习 1:了解代码库

  1. 搭建应用

  2. 了解应用结构

练习 2:使用外部服务扩展应用

  1. 更新业务场景

  2. 扩展 Incident Management 应用

  3. 在本地运行开发者测试

练习 3:使用编码智能体扩展 Incident Management 应用

  1. 为智能体编码设置 MCP 服务器

  2. 添加 Resolution Note——字段、业务逻辑与测试

练习 4:在 SAP BTP、Cloud Foundry 运行时中部署

  1. 在 SAP BTP 中创建空间

  2. 部署到 SAP BTP、Cloud Foundry 运行时

  3. 将应用与 SAP Build Work Zone, Standard Edition 集成

总结

完成本练习后,您已经使用 MCP 服务器进行智能体编码,完成了以下工作:

  • 用一条提示就向 CAP CDS 模型添加新字段,并在 SAP Fiori elements UI 中呈现

  • 在 CAP 服务处理器中实现业务校验逻辑(状态变更时的必填字段)

  • 保护用户输入,防范 SQL 注入模式

  • 按照 OData Draft Choreography 模式编写并运行自动化 Jest 测试

为 Incident Management 应用添加 Resolution Note

在本节中,您将在 SAP Business Application Studio 中使用 Cline,为 Incident Management 应用扩展一个 Resolution Note 字段。工作分为三章:

  • 向 CDS 模型和 SAP Fiori UI 添加字段

  • 添加业务逻辑(必填校验 + SQL 注入检查)

前提条件

您已按照「为智能体编码设置 MCP 服务器」中的步骤,设置好 MCP 服务器并定义了 AGENTS.md 规则。


1:添加 Resolution Note 字段

在本章中,您将把 resolutionNote 字段添加到 CDS 模型中的 Incidents 实体,并在 SAP Fiori elements UI 中呈现它。

  1. 在 SAP Business Application Studio 中打开 Cline。

  2. 输入以下提示:

    Add a new field 'Resolution Note' to the 'Incidents' entity in the CDS model and Fiori UI using cds-mcp and fiori-mcp servers
    
  3. Cline 会使用 CAP MCP server 查询 Incidents 实体定义,并找到正确的文件位置:

  4. Cline 会更新 db/schema.cds,向 Incidents 实体添加新字段:

    entity Incidents : cuid, managed {
      customer       : Association to Customers;
      title          : String  @title : 'Title';
      urgency        : Association to Urgency default 'M';
      status         : Association to Status default 'N';
      resolutionNote : String @title : 'Resolution Note'; // newly added field
      conversation   : Composition of many {
        key ID       : UUID;
            timestamp : type of managed:createdAt;
            author    : type of managed:createdBy;
            message   : String;
      };
    }
    
  5. Cline 会更新 app/incidents/annotations.cds,把新字段添加到 UI 中:

    ...
    { 
        $Type : 'UI.DataField',
        Value : resolutionNote,
        Label : '{i18n>ResolutionNote}',
    },
    ...
    
  6. Cline 会确认这些修改,输出类似如下:

    ## Changes Made:
    1. CDS Model (db/schema.cds): Added `resolutionNote : String @title : 'Resolution Note';`
       to the Incidents entity.
    2. UI Annotations (app/incidents/annotations.cds): Added the Resolution Note field
       to the Details field group in the UI, making it visible in the incident details section.
    3. Internationalization (app/incidents/webapp/i18n/i18n.properties): Added the label
       `ResolutionNote=Resolution Note` for proper UI display.
    4. Verification: Confirmed the CDS model compiles successfully and the field is
       properly exposed through both ProcessorService and AdminService.
    
    ## Field Location in UI:
    The Resolution Note field will appear in the Details section of the incident object
    page, alongside the Status and Urgency fields.
    

[!Tip] cds-mcp 和 fiori-mcp 服务器帮助 Cline 找到相关文件以及添加新字段的正确语法。Cline 会生成工具调用以检查 Incidents 实体,并返回相关信息,例如其元素和文件位置。它还会生成工具调用以查阅 CAP 文档,获取正确的注解语法。

测试字段

  1. 在本地启动应用:

    cds watch
    
  2. 要在终端中打开服务器 URL,请点击 http://localhost:4004。

    运行测试

  3. Web 应用下有两个 URL:

    运行测试

  4. 当系统提示进行身份验证时,请使用以下凭据:

    • 用户名:alice

    • 密码:为空 / 无密码

    用户设置位于 .cdsrc.json file 中。

  5. 测试场景——创建新事件时,客户的值帮助会从 mock 服务加载数据。

    • 打开 Incident Management 应用并选择一个事件。

      运行测试

  6. 现在,Resolution Note 字段应显示在事件对象页中。

[!Note] Cline 生成的代码可能略有不同。请确保最终的 db/schema.cds 包含 resolutionNote 字段,app/incidents/annotations.cds 包含对应的 UI.DataField 条目,并且 db/data/sap.capire.incidents-Incidents.csv 中已有事件都带有 resolutionNote 值。


2:添加业务逻辑

在本章中,您将向 srv/services.js 添加两条校验:

  1. 将状态设置为 Resolved(R)或 Closed(C)时,resolutionNote 为必填

  2. resolutionNote 不得包含 SQL 注入模式

2.1:解决或关闭时必填 Resolution Note

这条校验确保用户把事件状态设置为 Resolved(R)或 Closed(C)时,必须提供解决说明(resolution note)。

  1. 在 Cline 中输入以下提示:

    I have a CAP project with an Incidents app. When someone tries to close or resolve an incident, they must provide a resolution note explaining what was done. 
    
    Add validation to prevent closing/resolving incidents without a resolution note:
    
    - If status is changed to "Resolved" or "Closed" but no resolution note is provided, show an error
    - Check if they're adding a resolution note now, or if one was already added before
    - Make sure it works with the draft system
    
    The incident has a status_code field ('R' for Resolved, 'C' for Closed) and a resolutionNote field.
    
  2. Cline 会使用 CAP MCP server 检查实体和文档:

    search_model
    Arguments
    {
      "projectPath": "/path/to/your/project",
      "name": "Incidents",
      "kind": "entity",
      "topN": 1
    }
    
    search_docs
    Arguments
    {
      "query": "before UPDATE handler service implementation Node.js req.error"
    }
    
  3. Cline 会在 onUpdate 中更新 srv/services.js,加入必填检查:

    // Mandatory resolutionNote when resolving or closing
    const newStatus = req.data.status_code;
    if (newStatus === 'R' || newStatus === 'C') { 
      const noteInRequest = req.data.resolutionNote?.trim();
      const noteInDB = noteInRequest === undefined 
        ? (await SELECT.one(req.subject, i => i.resolutionNote).where({ ID: req.data.ID }))?.resolutionNote?.trim() 
        : undefined; 
      if (!noteInRequest && !noteInDB) {
        return req.reject(400, 'A Resolution Note is required before resolving or closing an incident.'); 
      } 
    } 
    
  4. Cline 会确认:

    ## Changes Made:
    1. srv/services.js: Added a mandatory resolutionNote check inside the onUpdate handler.
       - Rejects with HTTP 400: "A Resolution Note is required before resolving or
         closing an incident."
    

[!Tip] Cline 会同时检查传入的请求负载和数据库中已有的记录。用户可以在上一次保存时设置解决说明,再在另一次更新中修改状态——这两种流程都能覆盖。

2.2:Resolution Note 的 SQL 注入检查

  1. 在 Cline 中输入以下提示:

    In the same srv/services.js, before saving the resolution note, check if it contains suspicious patterns commonly used in SQL injection attacks — things like --, ;, DROP, SELECT, INSERT, DELETE, UPDATE, UNION, ', /*, */. If any are found, reject the request with an error saying the input contains invalid characters.
    
  2. Cline 会扩展 onUpdate,把 SQL 注入检查放在必填校验之前:

    // SQL injection check on resolutionNote 
    if (req.data.resolutionNote) {
      const sqlPatterns = /--|;|'|\/\*|\*\/|\b(DROP|SELECT|INSERT|DELETE|UPDATE|UNION)\b/i;
      if (sqlPatterns.test(req.data.resolutionNote)) {
        return req.reject(400, 'Resolution Note contains invalid characters or patterns.'); 
      } 
    } 
    
  3. Cline 会确认:

    ## Changes Made:
    1. srv/services.js: Added SQL injection check inside the onUpdate handler.
       - Rejects with HTTP 400: "Resolution Note contains invalid characters or patterns."
       - The check runs before the mandatory note validation to fail fast on bad input.
    

[!Note] Cline 生成的代码可能略有不同。请确保最终的 srv/services.js 如下所示:

const cds = require('@sap/cds')

class ProcessorService extends cds.ApplicationService {
  init() {
    this.before("UPDATE", "Incidents", (req) => this.onUpdate(req));
    this.before("CREATE", "Incidents", (req) => this.changeUrgencyDueToSubject(req.data));
    return super.init();
  }

  changeUrgencyDueToSubject(data) {
    if (data) {
      const incidents = Array.isArray(data) ? data : [data];
      incidents.forEach((incident) => {
        if (incident.title?.toLowerCase().includes("urgent")) {
          incident.urgency = { code: "H", descr: "High" };
        }
      });
    }
  }

  async onUpdate(req) {
    const { status_code } = await SELECT.one(req.subject, i => i.status_code).where({ ID: req.data.ID });

    if (status_code === 'C')
      return req.reject(`Can't modify a closed incident`);

    // SQL injection check on resolutionNote
    if (req.data.resolutionNote) {
      const sqlPatterns = /--|;|'|\/\*|\*\/|\b(DROP|SELECT|INSERT|DELETE|UPDATE|UNION)\b/i;
      if (sqlPatterns.test(req.data.resolutionNote)) {
        return req.reject(400, 'Resolution Note contains invalid characters or patterns.');
      }
    }

    // Mandatory resolutionNote when resolving or closing
    const newStatus = req.data.status_code;
    if (newStatus === 'R' || newStatus === 'C') {
      const noteInRequest = req.data.resolutionNote?.trim();
      const noteInDB = noteInRequest === undefined
        ? (await SELECT.one(req.subject, i => i.resolutionNote).where({ ID: req.data.ID }))?.resolutionNote?.trim()
        : undefined;
      if (!noteInRequest && !noteInDB) {
        return req.reject(400, 'A Resolution Note is required before resolving or closing an incident.');
      }
    }
  }
}
module.exports = { ProcessorService }

测试业务逻辑

  1. 运行 cds watch,打开 http://localhost:4004。

  2. 测试必填 resolutionNote 校验:

    • 把 Status 设为 Resolved 或 Closed,Resolution Note 留空,然后选择 Save。

    • 预期错误:A Resolution Note is required before resolving or closing an incident.

  3. 测试 resolutionNote 的 SQL 注入检查:

    • 在 Resolution Note 字段输入 Fixed; DROP TABLE Incidents--,然后选择 Save。

    • 预期错误:Resolution Note contains invalid characters or patterns.

  4. 测试添加正确的 resolutionNote:

    • 输入 Issue resolved after replacing the faulty component.,把 Status 设为 Resolved,然后选择 Save。

    • 事件应保存成功。


总结

通过向 Cline 发出的三条聚焦提示,您已经:

  • 向 CDS 模型和 SAP Fiori UI 添加了 resolutionNote 字段

  • 实施了在解决或关闭事件时必填解决说明的校验

  • 保护该字段免受 SQL 注入模式影响

后续步骤:

  • 在 SAP BTP 中创建空间

为智能体编码设置 MCP 服务器

在本节中,您将在 SAP Business Application Studio 中运行的 Cline 里设置 CAP MCP server 和 SAP Fiori MCP server,并定义规则,在整个练习中指导 AI 编码助手。

什么是智能体编码?

智能体编码代表软件开发的一种范式转变:AI 智能体主动参与编码过程,超越简单的代码生成,成为协作伙伴。

智能体编码的关键特征

  1. 主动协助:AI 智能体预判开发者需求并提出改进建议

  2. 上下文感知:理解项目结构、编码标准和业务需求

  3. 工具编排:能够协调多个工具与服务来完成复杂任务

  4. 协作式工作流:作为智能结对编程伙伴与开发者并肩工作

什么是 MCP(Model Context Protocol)?

Model Context Protocol(MCP) 是一种开放标准,让 AI 模型与外部工具、数据源和服务之间能够无缝通信。它充当桥梁,使 AI 智能体能够以结构化且安全的方式与更广泛的开发生态交互。

面向 CAP 的 MCP 服务器

面向 CAP 的 MCP 服务器把 AI 智能体变成 CAP 开发专家。它提供聚焦上下文的工具,帮助 AI 智能体回答如下问题:

  • 我的项目暴露了哪些 CDS 服务,它们在哪里提供服务?

  • 这些实体是做什么的,彼此之间如何关联?

  • 在 CAP Node.js 中如何向 select 语句添加列?

  • 在 CAP Node.js 中如何注册自定义 READ 处理器?

没有面向 CAP 的 MCP 服务器时,LLM 会凭空臆造,可能发明新语法,或者为找到相关文件而进行大量文件搜索。有了 MCP 服务器,LLM 会生成工具调用来检查实体,并返回相关信息——例如其元素和文件位置。它还会生成工具调用来查阅 CAP 文档。根据这些结果,它生成正确的 CDS 代码。

SAP Fiori MCP server

SAP Fiori MCP server(@sap-ux/fiori-mcp-server)让使用 AI 编码助手的开发者能够精准且具备上下文感知地生成和调整 SAP Fiori elements 应用。

前提条件

您已在 SAP Business Application Studio 中搭建好 Incident Management 应用。

设置 MCP 服务器

要开始使用,您需要在 SAP Business Application Studio 中运行的 Cline 里,为 CAP 和 SAP Fiori 分别设置 MCP 服务器。

  1. 使用 npm 全局安装 CAP 和 SAP Fiori 的 MCP 服务器:

    npm install -g @cap-js/mcp-server @sap-ux/fiori-mcp-server
    
  2. 在 SAP Business Application Studio 中打开 Cline,在 Cline 面板中选择 MCP Servers 图标。如果左侧导航栏中看不到 Cline 图标,可以点击 ... 图标并从下拉列表中选择 Cline 来打开它。

Alt text

  1. 选择 Edit MCP Settings 打开 Cline MCP 配置,并添加以下条目:

    {
    "mcpServers": {
        "cds-mcp": {
        "autoApprove": [
            "search_model",
            "search_docs"
        ],
        "disabled": false,
        "timeout": 60,
        "type": "stdio",
        "command": "/home/user/.asdf-inst/installs/nodejs/22.13.1/bin/node",
        "args": [
            "/home/user/.node_modules_global/bin/cds-mcp"
        ],
        "env": {
            "ASDF_DIR": "/home/user/.asdf",
            "ASDF_DATA_DIR": "/home/user/.asdf-inst",
            "PATH": "/home/user/.asdf-inst/installs/nodejs/22.13.1/bin:/home/user/.node_modules_global/bin:/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
        }
        },
        "fiori-mcp": {
        "autoApprove": [
            "list_functionality",
            "execute_functionality",
            "get_functionality_details",
            "generate-fiori-ui-app",
            "list_fiori_apps",
            "search_docs"
        ],
        "timeout": 600,
        "type": "stdio",
        "command": "/home/user/.asdf-inst/installs/nodejs/22.13.1/bin/npx",
        "args": [
            "--yes",
            "@sap-ux/fiori-mcp-server@latest",
            "fiori-mcp"
        ],
        "env": {
            "ASDF_DIR": "/home/user/.asdf",
            "ASDF_DATA_DIR": "/home/user/.asdf-inst",
            "PATH": "/home/user/.asdf-inst/installs/nodejs/22.13.1/bin:/home/user/.node_modules_global/bin:/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
        }
        }
    }
    }
    
  2. 保存设置。MCP 服务器将在 Cline 的 MCP Servers 面板中显示为已连接。

  3. 通过让 Cline 列出 CAP 项目中的所有实体来测试 MCP 服务器设置,在 Cline 提示窗口中输入以下提示:

    cds-mcp list the entities of this project
    

    img.png

  4. 您还可以让 Cline 列出项目中的所有 Fiori 应用:

    fiori-mcp list the fiori apps of this project
    

为 MCP 服务器定义规则(AGENTS.md)

要让 MCP 服务器在您的开发工作流中发挥最大效用,请在项目根目录的 AGENTS.md 文件中定义规则。这有助于确保 Cline 恰当使用 MCP 服务器。

在项目根目录创建 AGENTS.md,内容如下:

# AGENTS.md

## Rules for cds-mcp
- You MUST search for CDS definitions, like entities, fields and services (which include HTTP endpoints) with cds-mcp, only if it fails you MAY read *.cds files in the project.
- You MUST search for CAP docs with cds-mcp EVERY TIME you create, modify CDS models or when using APIs or the `cds` CLI from CAP. Do NOT propose, suggest or make any changes without first checking it.
- You MUST use cds watch to start the server locally.

## Rules for creation or modification of SAP Fiori elements apps
- When asked to create an SAP Fiori elements app check whether the user input can be interpreted as an application organized into one or more pages containing table data or forms, these can be translated into a SAP Fiori elements application, else ask the user for suitable input.
- The application typically starts with a List Report page showing the data of the base entity of the application in a table. Details of a specific table row are shown in the ObjectPage.
- Each property of an entity must have a proper datatype.
- For all entities in the data model provide primary keys of type UUID.
- When creating sample data in CSV files, all primary keys and foreign keys MUST be in UUID format.
- When generating or modifying the SAP Fiori elements application on top of the CAP service use the Fiori MCP server if available.
- When attempting to modify the SAP Fiori elements application like adding columns you must not use the screen personalization but instead modify the code of the project, before this first check whether an MCP server provides a suitable function.
- When previewing the SAP Fiori elements application use the most specific script for the app in the `package.json`.

[!Tip] AGENTS.md 是对 README.md 的补充,其中包含编码智能体所需的额外上下文:构建步骤、测试和约定——这些内容可能会让 README 显得杂乱,或者与人类贡献者无关。

后续步骤

  • 添加 Resolution Note——字段、业务逻辑与测试

向数据库添加初始数据

由于我们已经有之前自动创建的 SQLite 内存数据库,现在来向其中填充一些初始数据。 在生产版本中,您只会填充不太可能变化的数据。而在本例中,我们还会加载客户和事件,这样应用一启动就有可用的测试数据。

应用启动并运行后,您可以选择使用 OData REST 接口来插入、更新或删除数据。

生成 .csv 模板

  1. 在项目根目录(即 incidents-management)中运行以下命令:

cds add data
  1. 检查输出。

Adding feature 'data'...

Creating db/data/sap.capire.incidents-Incidents.csv
Creating db/data/sap.capire.incidents-Customers.csv
Creating db/data/sap.capire.incidents-Status.csv
Creating db/data/sap.capire.incidents-Urgency.csv
Creating db/data/sap.capire.incidents-Incidents.conversation.csv
Creating db/data/sap.capire.incidents-Status.texts.csv
Creating db/data/sap.capire.incidents-Urgency.texts.csv

Successfully added features to your project.

填入初始数据

用以下内容替换生成的 .csv 模板:

  • db/data/sap.capire.incidents-Customers.csv:

    ID,firstName,lastName,email,phone
    1004155,Daniel,Watts,daniel.watts@demo.com,+44-555-123
    1004161,Stormy,Weathers,stormy.weathers@demo.com,
    1004100,Sunny,Sunshine,sunny.sunshine@demo.com,+01-555-789
    
  • db/data/sap.capire.incidents-Incidents.csv:

    ID,customer_ID,title,urgency_code,status_code
    3b23bb4b-4ac7-4a24-ac02-aa10cabd842c,1004155,Inverter not functional,H,C
    3a4ede72-244a-4f5f-8efa-b17e032d01ee,1004161,No current on a sunny day,H,N
    3ccf474c-3881-44b7-99fb-59a2a4668418,1004161,Strange noise when switching off Inverter,M,N
    3583f982-d7df-4aad-ab26-301d4a157cd7,1004100,Solar panel broken,H,I
    
  • db/data/sap.capire.incidents-Addresses.csv

    ID,customer_ID,city,postCode,streetAddress
    17e00347-dc7e-4ca9-9c5d-06ccef69f064,1004155,Rome,00164,Piazza Adriana
    d8e797d9-6507-4aaa-b43f-5d2301df5135,1004161,Munich,80809,Olympia Park
    ff13d2fa-e00f-4ee5-951c-3303f490777b,1004100,Walldorf,69190,Dietmar-Hopp-Allee
    
  • db/data/sap.capire.incidents-Incidents.conversation.csv:

    ID,up__ID,timestamp,author,message
    2b23bb4b-4ac7-4a24-ac02-aa10cabd842c,3b23bb4b-4ac7-4a24-ac02-aa10cabd842c,1995-12-17T03:24:00Z,Harry John,Can you please check if battery connections are fine?
    2b23bb4b-4ac7-4a24-ac02-aa10cabd843c,3a4ede72-244a-4f5f-8efa-b17e032d01ee,1995-12-18T04:24:00Z,Emily Elizabeth,Can you please check if there are any loose connections?
    9583f982-d7df-4aad-ab26-301d4a157cd7,3583f982-d7df-4aad-ab26-301d4a157cd7,2022-09-04T12:00:00Z,Sunny Sunshine,Please check why the solar panel is broken
    9583f982-d7df-4aad-ab26-301d4a158cd7,3ccf474c-3881-44b7-99fb-59a2a4668418,2022-09-04T13:00:00Z,Bradley Flowers,What exactly is wrong?
    
  • db/data/sap.capire.incidents-Status.csv:

    code;descr;criticality
    N;New;3
    A;Assigned;2
    I;In Process;2
    H;On Hold;3
    R;Resolved;2
    C;Closed;4
    
  • db/data/sap.capire.incidents-Urgency.csv:

    code;descr
    H;High
    M;Medium
    L;Low
    

[!Tip] 请注意,cds add data 创建了七个文件,而我们只向其中五个添加数据。xxxxx.texts.csv 文件保持为空,因为它们存放的是应用本地化并创建翻译后的文本。

配置对象页

在本节中,您将使用 SAP Fiori 页面编辑器修改 UI 中的 Incident 对象页。

前提条件

按照「配置 List Report UI」教程扩展 Fiori UI 的列表报表页

编辑页眉

  1. 确保 SAP Fiori 页面编辑器已打开。如果已关闭,请在 Application Info - incidents 标签页中选择 Open Page Map 选项。

    要打开 Application Info - incidents 标签页:

    1. 调出命令面板——View → Command Palette,或 macOS 按 Command + Shift + P / Windows 按 Ctrl + Shift + P。

    2. 选择 Fiori: Open Application Info。

  2. 在 Incident Object Page 磁贴中,点击标题旁的 Pencil 图标。

    编辑对象页

  3. 选择 Header。在 Title 下拉菜单中选择属性 title。

    选择 Title

  4. 在 Description Type 下拉菜单中选择 Property。会打开一个对话框。

    选择属性

  5. 在 Define Property 对话框中,打开 Description 字段的下拉菜单。

    • 选择 customer → name。

    • 点击 Apply。

    应用 Name

  6. 在 Icon URL 字段中输入 sap-icon://alert。

    Icon URL

添加 Overview 分区

  1. 选择 Sections。点击 Plus 图标并选择 Add Group Section。

    添加 Group Section

  2. 在 Add Group Section 对话框中:

    • 在 Label 字段中输入 Overview。

    • 点击 Globe 图标生成可翻译的文本键。点击 Apply 确认。

    • 点击 Add。

    添加 Overview 分区

添加 Details 子分区

  1. 展开 Sections → Overview → Subsections。

  2. 点击 Plus 图标。选择 Add Form Section。

    添加子分区

  3. 在 Add Form Section 弹出窗口中:

    • 在 Label 字段中输入 Details。

    • 点击 Globe 图标生成可翻译的文本键。点击 Apply 确认。

    • 点击 Add。

    添加 Details 子分区

配置字段

  1. 选择 Sections → General Information,点击 General Information 的 Label 字段中的 Globe 图标,生成可翻译的文本键。

    General information 标签

  2. 选择 Sections → General Information → Form → Fields,删除 urgency_code 和 status_code 字段。

    删除字段

  3. 选择字段 customer_ID,把标签改为 Customer,并为它生成文本键。

    Customer 字段更新标签

  4. 对于现在重命名为 Customer 的字段,点击 Edit properties for Value Help。

    Customer 属性更新

  5. 打开 Define Value Help Properties for Customer 对话框。

    • 关闭 Display as Dropdown

    • 在 Result List 下,只保留 email 列。删除 firstName、lastName 和 phone 列

    • 点击 Add Column,选择属性 name,并把该列上移到 email 列之前

    • 点击 Apply 确认更改

    Customer 属性更新

  6. 对于字段 Title,点击 Move Up 图标,把它放到分区中 Customer 字段之前。

    字段定位

  7. 把 General Information 分区拖放到 Overview → Subsections 节点中,正好放在 Details 子分区之上。

    Customer 属性更新

  8. 展开 Sections → Overview → Subsections → Details → Form → Fields。点击 Plus 图标并选择 Add Basic Fields。

    添加 Basic Fields

  9. 在 Add Basic Fields 对话框中

    • 打开 Fields 下拉菜单,选择 status_code、urgency_code。

    • 点击 Add。

    Add Basic Fields 弹出窗口

请注意,当您使用 Page Map 配置字段(例如添加标签、Text/TextArrangement 或值帮助配置)时,相应的 CDS 注解会生成在属性级别。由于我们已经配置并添加了 status_code 和 urgency_code 字段到列表报表表格,这些注解在 UI 其他部分显示它们时会被自动复用。您可以直接从 Page Map 访问属性注解。

  1. 点击字段 Status。把鼠标指针移到属性 Text 上,点击 Edit in source code 图标。这会在单独的标签页中打开字段 Status 对应的 CDS 注解。

字段属性注解

添加 Conversation 分区

现在再向对象页添加一个分区,用表格显示与事件相关的对话。

  1. 导航到 Sections,点击 Plus 图标。

  2. 选择 Add Table Section。出现一个对话框。

    添加 Table 分区

  3. 在 Add Table Section 对话框中:

    • 在 Label 字段中输入 Conversation。

    • 点击 Globe 图标生成可翻译的文本键。

    • 在 Source Value 下拉菜单中选择 conversation,然后选择 Add。

    添加 Conversation 标签

配置列

  1. 展开 Conversation → Table → Columns,点击 Plus 图标添加列。

  2. 选择 Add Basic Columns。出现一个对话框。

    添加 Conversation 列

  3. 在 Add Basic Columns 对话框中:

    • 打开 Columns 下拉菜单。方面组合 conversation 的所有属性都会列出,正如 Incidents 实体在文件 ./db/schema.cds 中内联定义的那样。

    • 选择 author、message 和 timestamp。

    • 点击 Add。

    Add Basic Columns 弹出窗口

  4. 现在修改所添加字段的默认标签。对于 CreatedBy、message 和 CreatedOn 各列:

    • 在 Label 字段中,分别把值改为 Author、Message 和 Date。

    • 按 Enter 确认修改。

    • 在 Label 字段中选择 Globe 图标,生成可翻译的文本键。

    更新列标签

配置表格并检查结果

  1. 对于 Table,在 Type 下拉菜单中选择 ResponsiveTable。

    响应式表格

  2. 在 Creation Mode: Name 下拉菜单中选择 Inline。这样,创建操作会在表格中新增一行,而不是导航到新的对象条目页。

    表格创建模式

  3. 完整的对象页如下所示:

    完整的 List Object Page

后续步骤

添加测试用例

创建数据实体

Joule 是一个 AI 副驾驶,可以把应用的数据模型生成为 CDS(Core Data Services)实体。不过,由于每次触发提示生成的模型可能略有不同,我们提供预定义的 CDS 数据模型。采用结构化的人工方式可以确保练习的一致性。请按照分步教程手动创建 CDS 实体,而不要依赖 AI 生成的代码。

前提条件

您已按照「创建全栈应用」中的步骤创建了项目。

添加领域模型

  1. 在 SAP Business Application Studio 中,选择 Project Explorer。

    project-explorer

  2. 展开 db 文件夹。选择创建新文件的图标,文件名填入 schema.cds。

    create-schema

  3. 把以下 schema 复制到 schema.cds 文件。

using { cuid, managed, sap.common.CodeList } from '@sap/cds/common';
namespace sap.capire.incidents; 

/**
* Incidents created by Customers.
*/
entity Incidents : cuid, managed {  
customer     : Association to Customers;
title        : String  @title : 'Title';
urgency        : Association to Urgency default 'M';
status         : Association to Status default 'N';
conversation  : Composition of many {
    key ID    : UUID;
    timestamp : type of managed:createdAt;
    author    : type of managed:createdBy;
    message   : String;
};
}

/**
* Customers entitled to create support Incidents.
*/
entity Customers : managed { 
key ID        : String;
firstName     : String;
lastName      : String;
name          : String = firstName ||' '|| lastName;
email         : EMailAddress;
phone         : PhoneNumber;
incidents     : Association to many Incidents on incidents.customer = $self;
creditCardNo  : String(16) @assert.format: '^[1-9]\d{15}$';
addresses     : Composition of many Addresses on addresses.customer = $self;
}

entity Addresses : cuid, managed {
customer      : Association to Customers;
city          : String;
postCode      : String;
streetAddress : String;
}

entity Status : CodeList {
key code: String enum {
    new = 'N';
    assigned = 'A'; 
    in_process = 'I'; 
    on_hold = 'H'; 
    resolved = 'R'; 
    closed = 'C'; 
};
criticality : Integer;
}

entity Urgency : CodeList {
key code: String enum {
    high = 'H';
    medium = 'M'; 
    low = 'L'; 
};
}

type EMailAddress : String;
type PhoneNumber : String;

[!Note] 这个 CDS 文件定义了 Incident Management 应用的数据模型。模型包括:

Incidents:表示客户提交的支持工单。

Customers:存储客户详细信息,把客户与其事件和地址关联起来。

Addresses:存储客户地址。

Status:定义事件可能处于的各种状态,如 New(N)、In Process(I)等。

Urgency:定义事件的不同紧急级别:High(H)、Medium(M)和 Low(L)。

模型涵盖的关键 CAP 特性

使用 managed 和 cuid:确保自动时间戳和基于 UUID 的主键。

关联与组合:

  1. Customers ↔ Incidents(一对多)

  2. Customers ↔ Addresses(一对多)

  3. Incidents ↔ Status 与 Urgency(提供默认值)

校验: 使用正则表达式强制信用卡号格式。

嵌套组合: 每个事件维护一份带时间戳和作者的聊天日志。

  1. 在编辑器中导航到 Storyboard,确保 Data Models 部分已更新为 schema.cds 文件中提到的实体。

    schema-storyboard

后续步骤

添加示例数据

创建全栈应用

本节说明如何访问 SAP Build 大厅,并使用 SAP Build Code 创建全栈应用。

Joule 提示旨在生成在由 Joule 驱动的 SAP Build Code 中成功开发全栈应用所需的完整代码。这些提示经过专门设计,与动手教程流程保持一致,确保每一步都能按顺序顺畅执行。

  1. 打开 SAP Build 大厅。

  2. 在 Create 下拉菜单中点击 Create。

    build lobby

  3. 在 Create Project 对话框中,在 Objective 下点击 Application 磁贴,然后选择 Next。

    build application

  4. 在 Category 下选择 Full-Stack 磁贴,然后点击 Next。

    build code

  5. 在 Type 下,选择开发配置为 Full-Stack Node.JS,然后点击 Next。

    full-stack-app

  6. 在 Name 标签页下,执行以下操作:

    1. 把名称输入为 Incidents<your-initials><unique-random-number>。例如,如果您的名字是 John Doe,项目名可以是 Incidentsjd12(12 是某个随机数)。

      注意: 项目名称必须唯一,以便在部署时识别您的项目,同时避免重复错误。

    2. 让 Full_Stack 作为默认开发空间。

    3. 点击 Review。

      project details

[!Note] 如果 UI 显示 Dev space 带有 New 选项,您可以选择现有的 Dev Space,而不必新建。 project details

  1. 在 Summary 页面中,检查前面步骤中给出的 Objective、Category、Type 和 name,然后点击 Create。

    project-created

  2. 等待项目创建完成。创建完成后,点击项目,会在新标签页中打开。

    project-created

后续步骤

创建数据实体

创建 Cloud Foundry 空间

  1. 在浏览器中打开 SAP BTP Cockpit 控制台。

  2. 在 Overview 中可以看到 Spaces 表格。在该表格右上角选择 Create Space。

    click-create-space

  3. 在 Create Space 弹出窗口中,执行以下操作:

    • 在 Create Space 字段中输入 <your-initials><unique-random-number>。例如,如果您的名字是 John Doe,空间名可以是 jd12(12 是唯一随机数)。

      注意: 名称应唯一,以便在部署时识别您的空间,同时避免重复错误。

    • 保持默认分配的角色。

    • 点击 Create。

    click-create-space

  4. 将会显示 Space created successfully 的弹出消息。您也可以验证空间是否已创建。

后续步骤

  • 部署到 SAP BTP、Cloud Foundry 运行时

使用 Joule 添加业务逻辑

在本节中,借助 Joule,您将在上一节生成的 ProcessorService 服务中,为创建和更新事件生成业务逻辑。

前提条件

您已按照「添加 CDS 服务」中的步骤创建 CDS 服务。

ProcessorService 的业务逻辑

  1. 导航到 Storyboard。

    自定义逻辑

  2. 在 Services 部分,选择 ProcessorService 下的 Incidents 实体,然后选择 Add Logic。

    自定义逻辑

  3. 出现 Application Logic Editor。

根据主题更改紧急级别

使用 Joule,我们将定义一个事件处理器:如果标题包含 "urgent" 一词,就自动把事件的紧急级别设为 High('H')。changeUrgencyDueToSubject 函数在 ProcessorService.Incidents 实体的 CREATE 或 UPDATE 操作之前触发。

  1. 在 Application Logic Editor 中,把 Name 字段的值改为 changeUrgencyDueToSubject,然后选择 Add。

    自定义逻辑

  2. 在 Phase 区域选择 Before,在 Standard Event 中选择 Create 和 Update。

    自定义逻辑

    这段逻辑会在创建或更新特定事件之前自动执行。

  3. 选择 Open Code Editor > Application Logic。

    自定义逻辑

  4. 这会打开 Joule,为 changeUrgencyDueToSubject 创建逻辑。

    自定义逻辑

    在 Joule 提示中,/cap-app-logic 用于为已创建的服务生成自定义后端逻辑。Joule 生成代码后,#srv/code/changeUrgencyDueToSubject.js 指明要把生成的代码填入哪个文件。

  5. Joule 提示会预填 /cap-app-logic #srv/code/changeUrgencyDueToSubject.js。在预填命令之后,使用以下提示创建业务逻辑。

    Check the title of the incident is having urgent keyword and update the urgency_code field to High.
    Ensure the data is array or wrap in an array.
    Do not generate unused variables.
    
  6. 选择 Send 图标。

    自定义逻辑

  7. Joule 返回代码后,检查实现并接受它。

    自定义逻辑

[!Note] Joule 为此后端逻辑生成的代码可能不同。请确保最终的 #srv/code/changeUrgencyDueToSubject.js 文件如下所示:

module.exports = async function(request) {
    const { Incidents } = cds.entities;
    
    // 确保数据是数组,或将其包装为数组
    const data = Array.isArray(request.data) ? request.data : [request.data];

    for (const incident of data) {
        if (incident.title && incident.title.toLowerCase().includes('urgent')) {
        incident.urgency_code = 'H'; // 将紧急度设为 High(高)
        }
    }
}

后续步骤

使用 Joule 创建 SAP Fiori UI

使用 Joule 添加业务逻辑

在本节中,借助 Joule,您将在上一节生成的 ProcessorService 服务中,为创建和更新事件生成业务逻辑。

前提条件

您已按照「添加 CDS 服务」中的步骤创建 CDS 服务。

ProcessorService 的业务逻辑

  1. 导航到 Storyboard。

    自定义逻辑

  2. 在 Services 部分,选择 ProcessorService 下的 Incidents 实体,然后选择 Add Logic。

    自定义逻辑

  3. 出现 Application Logic Editor。

1:根据主题更改紧急级别

使用 Joule,我们将定义一个事件处理器:如果标题包含 "urgent" 一词,就自动把事件的紧急级别设为 High('H')。changeUrgencyDueToSubject 函数在 ProcessorService.Incidents 实体的 CREATE 或 UPDATE 操作之前触发。

  1. 在 Application Logic Editor 中,把 Name 字段的值改为 changeUrgencyDueToSubject,然后选择 Add。

    自定义逻辑

  2. 在 Phase 区域选择 Before,在 Standard Event 中选择 Create 和 Update。

    自定义逻辑

    这段逻辑会在创建或更新特定事件之前自动执行。

  3. 选择 Open Code Editor > Application Logic。

    自定义逻辑

  4. 这会打开 Joule,为 changeUrgencyDueToSubject 创建逻辑。

    自定义逻辑

    在 Joule 提示中,/cap-app-logic 用于为已创建的服务生成自定义后端逻辑。Joule 生成代码后,#srv/code/changeUrgencyDueToSubject.js 指明要把生成的代码填入哪个文件。

  5. Joule 提示会预填 /cap-app-logic #srv/code/changeUrgencyDueToSubject.js。在预填命令之后,使用以下提示创建业务逻辑。

    Check the title of the incident is having urgent keyword and update the urgency_code field to High.
    Ensure the data is array or wrap in an array.
    Do not generate unused variables.
    
  6. 选择 Send 图标。

    自定义逻辑

  7. Joule 返回代码后,检查实现并接受它。

    自定义逻辑

[!Note] Joule 为此后端逻辑生成的代码可能不同。请确保最终的 #srv/code/changeUrgencyDueToSubject.js 文件如下所示:

module.exports = async function(request) {
    const { Incidents } = cds.entities;
    
    // 确保数据是数组,或将其包装为数组
    const data = Array.isArray(request.data) ? request.data : [request.data];

    for (const incident of data) {
        if (incident.title && incident.title.toLowerCase().includes('urgent')) {
        incident.urgency_code = 'H'; // 将紧急度设为 High(高)
        }
    }
}

2:防止更新已关闭的事件

此事件处理器阻止更新已经关闭的事件(status_code = 'C')。该函数在 ProcessorService.Incidents 的 UPDATE 操作之前运行,确保校验在数据库更新之前进行。

  1. 回到 Application Logic Editor,选择 +。

    自定义逻辑

  2. 把 Name 字段的值改为 onUpdate,然后选择 Add。

    自定义逻辑

  3. 在 Phase 区域选择 Before,在 Standard Event 中选择 Update。

    自定义逻辑

    这段逻辑会在更新特定事件之前自动执行。

  4. 选择 Open Code Editor > Application Logic。

    自定义逻辑

  5. 这会打开 Joule,为 onUpdate 创建逻辑。

    自定义逻辑

    在 Joule 提示中,/cap-app-logic 用于为已创建的服务生成自定义后端逻辑。Joule 生成代码后,#srv/code/onUpdate.js 指明要把生成的代码填入哪个文件。

  6. Joule 提示会预填 /cap-app-logic #srv/code/onUpdate.js。在预填命令之后,使用以下提示创建业务逻辑。

    For already closed incident, check if the status_code is 'C' and reject the request with 'cannot modify the closed incident'. 
    Do not generate unused variables.
    
  7. 选择 Send 图标。

    自定义逻辑

  8. Joule 返回代码后,检查实现并接受它。

    自定义逻辑

[!Note] Joule 为此后端逻辑生成的代码可能不同。请确保最终的 #srv/code/onUpdate.js 文件如下所示:

module.exports = async function(request) {
    const { Incidents } = cds.entities;
    const { ID } = request.data;

    if (!ID) return; // Ensure ID is provided

    const incident = await SELECT.one.from(Incidents).where({ ID });

    if (incident && incident.status_code === 'C') {
        request.reject(400, 'Cannot modify the closed incident');
    }
}

后续步骤

使用 Joule 创建 SAP Fiori UI

将应用部署到 SAP BTP、Cloud Foundry 运行时

本节说明如何把应用部署到 SAP BTP、Cloud Foundry 运行时。

前提条件

  1. 打开 app → incident-managmenent → webapp → manifest.json,在 "sap.app" 下的 dataSources 对象之后复制以下 crossNavigation 对象的代码片段

    "sap.app": {
        .....
        "crossNavigation": {
            "inbounds": {
                "intent1": {
                "signature": {
                    "parameters": {},
                    "additionalParameters": "allowed"
                    },
                "semanticObject": "Incidents",
                "action": "display"
                }
            }
        }
        ....
    

[!Note] 当您通过 Build Workzone 访问应用时,需要此代码片段才能使应用可访问且可点击。

deploy-cf

[!Note] 要在 SAP BTP Cockpit 中唯一标识已部署的应用,请对应用的 UI 模块做以下修改。

  1. UI 应用名可以是 incidentmanagement<your-initials><unique-random-number>。例如,如果您的名字是 John Doe,项目名可以是 incidentmanagementjd12(12 是某个随机数)。

    1. 在 app -> incident-management -> webapp 下,把以下文件中的 incidentmanagement 替换为新名称。

      • Component.js deploy-cf

      • index.html deploy-cf

      • manifest.json deploy-cf

    2. 在 app -> incident-management -> ui5.yaml 下,把 incidentmanagement 替换为新名称。 deploy-cf

[!Note] 请执行「全部查找并替换」,把 incidentmanagement 替换为 incidentmanagementjd12。

部署应用

在 SAP Business Application Studio 中的最后一步是把应用部署到 SAP BTP、Cloud Foundry 运行时。此过程还会自动创建目标(Destination),使其他工具(如 SAP Build Apps)能够使用 ODATA 服务。

  1. 安装 Fiori 应用的依赖:

    cd app/incidents && npm install
    
  2. 回到根目录,构建 Multi-Target Application(MTA)归档:

    cd ../.. && mbt build
    

[!Note] mbt build 命令会把 CAP 服务、Fiori 应用和所有配置打包为可部署的 .mtar 归档。请确保项目根目录中存在 mta.yaml 文件。

  1. 在 BAS 中按 Ctrl + Shift + P(Windows 用户)或 Cmd + Shift + P(Mac 用户)打开控制面板,搜索 cf login。选择该命令以启动部署过程。

    deploy-cf

  2. 部署过程中会弹出一个新页面,要求您登录 Cloud Foundry。请按以下步骤操作:

    1. 在 Enter Cloud Foundry Endpoint 字段中,输入 SAP BTP Cockpit 中的 API Endpoint。

    [!Note] Cloud Foundry Endpoint 可从 SAP BTP Cockpit 获取。 deploy-cf

    1. 选择 SSO Passcode 作为身份验证方式。

      deploy-cf

    2. 选择 Open a new browser page to generate your SSO passcode,以登录 SAP BTP 中的子账户,这会在新浏览器中打开。

    3. 找到 Enter the origin key pesworkshops-platform 文本框,点击 Sign in with alternative identity provider。

    deploy-cf

[!Note] 选择 Sign in with alternative identity provider 时,如果提示您登录,请输入用户名和密码。 如果您已使用 Default Identity 登录,可以选择使用默认身份提供商登录。

  1. 选择 Copy 图标获取临时身份验证码。

deploy-cf

  1. 把复制的代码粘贴到 Cloud Foundry 登录页面的 Enter your SSO Passcode 字段中。

  2. 选择 Sign In。

deploy-cf

  1. 在 Cloud Foundry Target 部分执行以下操作:

    1. 在 Select Cloud Foundry Organization 下拉菜单中选择对应的 Org 名称。

    2. 在 Select Cloud Foundry Space 下拉菜单中选择前提条件步骤中创建的开发空间。

    3. 选择 Apply。

      deploy-cf

  2. 把 .mtar 归档部署到 Cloud Foundry:

    cf deploy mta_archives/<your-app-name>.mtar
    

    [!Tip] .mtar 文件在 mbt build 步骤之后生成于 mta_archives/ 文件夹中。把 <your-app-name> 替换为构建完成后终端中显示的实际文件名。

  3. 检查终端中是否已启动任务。

deploy-cf

  1. 在终端中检查部署进度。

  2. 部署完成后,应用会启动并记录日志,您可以看到 Overview URL。

    deploy-cf

分配用户角色

创建角色集合并添加角色

  1. 打开 SAP BTP cockpit,导航到您的子账户。

  2. 选择 Security > Role Collections。

    deploy-cf

  3. 在 Search 字段中输入项目名。例如项目名为 Incidentsjd12,选择 incidentsjd12-Support-dev。

    deploy-cf

  4. 选择 Edit。

    请确保 Roles 标签页中已列出 Support 角色。

    deploy-cf

  5. 在 Users 标签页中:

    1. 在 ID 字段中输入用户名,并从建议中选择您的用户名。

    2. 在 Identity Provider 下拉菜单中选择 ...accounts.ondemand.com(business users)。

    注意: 请确保选择带有 (application users) 的身份提供商。

    deploy-cf

  6. 选择 Save。

后续步骤

  • 与 SAP Build Work Zone 集成

e2e-testing

测试 Incident Management 应用

前提条件

按照「与 SAP Build Work Zone 集成」中的步骤,把应用与 SAP Build Work Zone 集成

[!NOTE] 这里的 UI 截图来自未经任何增强的基础 SAP Fiori UI 应用。如果您已按照 Enhance UI 教程操作,截图会略有不同。**

验证自定义逻辑 1

如果标题中出现 urgent 关键字,就把 Urgency 从 Low/Medium 更新为 High。

  1. 选择 Create 创建新事件。

    testing

  2. 填写事件详细信息:

    1. 在 Customer ID 下拉菜单中选择一个客户。

      testing

    2. 在 Title 字段中输入 Urgent issue。

    3. urgency_code 和 status_code 字段保持不动。

    4. 选择 Create。

      testing

  3. 事件创建后,您会看到 urgency_code 字段自动从 M(Medium)变为 H(High)。

    testing

验证自定义逻辑 2

无法更新已关闭的事件。

  1. 关闭其中一个事件。

  2. status_code 变为 C(Closed)。选择 Edit。

    testing

  3. 修改 Title 字段中的值,然后选择 Save。

  4. 系统会抛出错误:cannot modify the closed incident。

    testing

清理 Cloud Foundry 空间

  1. 回到 Dev 空间,打开终端并输入以下命令。然后从命令输出中获取 mta_id。

        cf mtas
    

    testing

    注意: 运行 cf mtas 命令以获取 MTA ID。

  2. 要取消部署应用,请使用以下命令:

        cf undeploy <mta_id> --delete-service-keys --delete-services
    

    如果系统要求确认,请输入 y。

    testing

    注意: mta_id 与第 1 步获取的相同。

使用 Joule 添加示例数据

前提条件

您已按照「创建实体」中的步骤创建数据模型。

添加示例数据

上一步已定义数据实体。现在使用 Joule 创建一些可用于应用本地测试的示例数据。

  1. 选择 Joule 图标。在文本框中开始输入 /cap,然后选择 /cap-gen-data。

    gen-data

    注意: 默认情况下,文本框中应显示 /cap-gen-data #db/schema.cds。

    cap-gen-data

  2. Joule 提示会预填 /cap-gen-data #db/schema.cds。粘贴以下提示以生成示例数据。

Ensure the generated sample data: Follows the given data format with appropriate relationships between entities.
Includes realistic values for fields such as email, phone numbers, and messages. 
Uses meaningful incident titles and messages that reflect real-world support cases. Covers various urgency levels and statuses. 
For codelists entities like Status and Urgency follow the example as: code - N, criticality - 1, descr - New.
Do not generate name column. The data should be structured in CSV format, maintaining consistency with SAP CAP standards.
  1. 选择 Send 图标。

    data-gen-prompt

  2. Joule 会按照所提供的 schema 生成包含示例数据的 .csv 文件列表。选择 Accept。

    accept-gen-data

  3. 所有生成的 .csv 文件都会保存到项目的 test/data 文件夹中。

    validate-gen-data

[!Note] 如果您想了解如何手动配置数据,请参阅「添加初始数据」

后续步骤

添加 CDS 服务

扩展 Fiori UI

在本章中,我们将使用 SAP Fiori Tooling 扩展/定制生成的 Fiori UI。

前提条件

您已使用「使用 Joule 创建 UI」创建了基础 UI 应用

添加筛选字段

  1. 导航到 Storyboard。

  2. 在 UI Applications 部分,点击 UI 应用 incidentmanagement,然后选择 Open in Page Map

    自定义逻辑

  3. incidents 应用的页面映射会在 SAP Build code 中的新标签页打开。您会看到页面映射右侧的属性。可以编辑这些属性来更新应用的 UI。

    Page Map 属性

    如果 Application Info - incidents 标签页已关闭:

    1. 调出命令面板——View → Command Palette,或 macOS 按 Command + Shift + P / Windows 按 Ctrl + Shift + P。

    2. 选择 Fiori: Open Application Info。

  4. 在 List Report 磁贴中,点击标题旁的 Pencil 图标。页面编辑器会打开。

    List Report 页面配置

  5. 在页面编辑器的 Filter Bar 部分,选择 Filter Fields,然后点击 Plus 图标添加筛选字段。接着在下拉菜单中选择 Add Filter Fields。

    添加筛选字段

  6. 在 Add Filter Fields 对话框中:

    • 在 Filter Field 下拉菜单中勾选 status_code 和 urgency_code 复选框。

    • 点击 Add。应用会更新并显示新的筛选器。

    已添加新筛选器

    这就是定义哪些属性作为搜索字段暴露在列表上方页眉栏中的方式。

编辑筛选字段

  1. 选择筛选字段 urgency_code。在 Label 字段中把值改为 Urgency。

    更新筛选标签

  2. 点击 Globe 图标生成可翻译的文本键,然后点击 Apply。

    生成可翻译文本键

    筛选标签是文本字符串。最好更新它们,使其符合国际化(i18n)标准。

    在 CAP 文档的 Where to Place Text Bundles? 中详细了解后端部分的国际化如何工作。

  3. 选择 status_code 筛选器。在 Label 字段中把值改为 Status。

  4. 点击 Globe 图标生成可翻译的文本键,然后点击 Apply。

    目前两个筛选器的值帮助在打开时都显示对应的代码值。我们希望改为显示描述性文本。

    值帮助显示类型

  5. 对于 Status 和 Urgency 两个筛选器,在 Display Type 下拉菜单中选择 Value Help。会出现一个对话框。

    值帮助显示类型

  6. 在 Define Value Help Properties for Urgency/Status 对话框中:

    • 打开 Value Description Property 字段的下拉菜单,选择 descr

    • 打开 Text Arrangement 的下拉菜单,选择 Text Only

    • 选择 Apply

    值描述属性

  7. 切回应用预览浏览器标签页,打开筛选字段。它们现在显示描述性文本,而不是代码值。

编辑列

在 List Report 中,可以看到表格列的标题显示为 customer_ID、urgency_code 和 status_code。此外,列值显示的是标识符和代码值。我们希望改为显示描述性值。

重新排列列

先来重新排列列的顺序。

  1. 选择列 Title,点击 ^ 把该列上移到列表顶部。

  2. 选择列 status_code,点击 ^ 把它放到列 urgency_code 之前。

    重新排列列

  3. 选择 Title 列。Label 字段包含字符串 Title,这是在应用生成期间自动设置的。点击 Label 字段中的 Globe 图标,为它生成可翻译的文本键,并应用更改。

  4. 对于 customer_ID、status_code 和 urgency_code 各列:

    • 在 Label 字段中,分别把值改为 Customer、Status 和 Urgency。

    • 在 Label 字段中选择 Globe 图标,生成可翻译的文本键。

    更新列

  5. 现在为 Customer、Status 和 Urgency 列配置显示文本和文本排列,以便显示描述性文本而不是标识符/代码。

    • 选择列 Customer

    • 点击属性 Text 的下拉框,选择条目 customer/name

    • 点击现在已激活的属性 Text Arrangement 的下拉框,选择 Text Only

      Customer 列

  6. 为 Status(选择 status/descr)和 Urgency(选择 urgency/descr)列选择文本属性,并把 Text Arrangement 也设为 Text Only

  7. 切回应用预览查看效果。

配置表格

启动应用时,用户默认需要按 Go 按钮才能触发查询。
这样可以在执行查询之前定义筛选器。
可以更改默认行为,使应用启动时立即 触发查询。

  1. 在页面编辑器左侧窗格中选择 Table。在 Initial Load 下拉菜单中选择 Enabled,以自动加载数据。

    启用数据自动加载

为 UI 上显示的状态信息提供关键性颜色(criticality color)被视为最佳实践。

  1. 选择 Table → Columns → Status。在 Criticality 下拉菜单中选择 status/criticality。

    添加状态关键性

检查结果

  1. Incident Management 应用的列表页应如下所示:

    Incident Management 应用的列表页

  2. 返回页面编辑器,在左上角选择 Page Map。这会带您回到 incidents 应用的概览。

    返回页面映射

后续步骤

配置对象页

fiori-ui-session

使用 Joule 创建 SAP Fiori UI

本节说明如何使用 Joule 提示创建 UI 应用。

前提条件

您已按照「使用 Joule 创建后端逻辑」中的步骤创建自定义逻辑。

生成 SAP Fiori UI

  1. 在 Joule 中开始输入 /fiori,从建议中选择 /fiori-gen-cap-ui。

    fiori-ui

  2. 使用以下提示创建用户界面。

    Create an SAP Fiori application named incidents with List report page as the template.
    Data source is local CAP application and use incidents entity of ProcessorService as the main odata Service.
    Table should be responsive.
    

    该提示要求 Joule 以 List report 作为 SAP Fiori 模板创建 SAP Fiori 应用。由于可能存在多个服务,需要说明希望与 UI 应用映射的服务。在本例中,ProcessorService 是 OData 服务,incidents 是其中的主实体。

  3. Joule 会响应 files generated successfully。

    ui-generated-msg

[!Note] 如果您想使用 SAP Fiori Elements 模板手动创建 SAP Fiori 应用 请遵循「使用 SAP Fiori Elements 模板生成 UI」

  1. Joule 使用 SAP Fiori Elements 中的 List Report 模板创建 SAP Fiori 应用,数据源为本地 CAP 服务

  2. 转到 Explorer。在 app 文件夹中检查是否生成了以下文件夹结构。

    fiori-ui

  3. 选择 Run and Debug 启动应用。

    run-app

  4. 应用启动并在新标签页中打开。选择 SAP Fiori 应用磁贴查看用户界面。

    open-app

  5. 列表报表页会在新标签页中打开。选择 Go 查看事件列表。

    list-report-page

  6. 选择其中一个事件。会显示事件详细信息。

    object-page

后续步骤

端到端测试

fiori-ui

使用 Joule 创建 SAP Fiori UI

本节说明如何使用 Joule 提示创建 UI 应用。

前提条件

您已按照「使用 Joule 创建后端逻辑」中的步骤创建自定义逻辑。

生成 SAP Fiori UI

  1. 在 Joule 中开始输入 /fiori,从建议中选择 /fiori-gen-cap-ui。

    fiori-ui

  2. 使用以下提示创建用户界面。

    Create an SAP Fiori application named incidents with List report page as the template.
    Data source is local CAP application and use incidents entity of ProcessorService as the main odata Service.
    Table should be responsive.
    

    该提示要求 Joule 以 List report 作为 SAP Fiori 模板创建 SAP Fiori 应用。由于可能存在多个服务,需要说明希望与 UI 应用映射的服务。在本例中,ProcessorService 是 OData 服务,incidents 是其中的主实体。

  3. Joule 会响应 files generated successfully。

    ui-generated-msg

[!Note] 如果您想使用 SAP Fiori Elements 模板手动创建 SAP Fiori 应用 请遵循「使用 SAP Fiori Elements 模板生成 UI」

  1. Joule 使用 SAP Fiori Elements 中的 List Report 模板创建 SAP Fiori 应用,数据源为本地 CAP 服务

  2. 转到 Explorer。在 app 文件夹中检查是否生成了以下文件夹结构。

    fiori-ui

  3. 选择 Run and Debug 启动应用。

    run-app

  4. 应用启动并在新标签页中打开。选择 SAP Fiori 应用磁贴查看用户界面。

    open-app

  5. 列表报表页会在新标签页中打开。选择 Go 查看事件列表。

    list-report-page

  6. 选择其中一个事件。会显示事件详细信息。

    object-page

  7. 要停止正在运行的应用,选择屏幕顶部的 Disconnect 图标。

    停止预览

后续步骤

要增强用户界面,请遵循「扩展 SAP Fiori UI」中的步骤。

否则,您可以继续执行「添加测试用例」

使用 Joule 添加 CDS 服务

本节说明如何使用 Joule 生成 CDS 服务。

前提条件

您已按照「增强示例数据」中的步骤增强示例数据。

添加服务

  1. 选择 Joule 图标。在 Joule 提示中开始输入 /cap-edit,从建议中选择 /cap-edit-model 以创建服务。

    edit-model

    注意: 默认情况下,文本框中应显示 /cap-edit-model。

  2. Joule 提示会预填 /cap-edit-model。粘贴以下提示以生成服务:

    Add 1 service named 'ProcessorService' with projection on the entities 'Incidents' and 'Customers'.
    Add additional service named 'AdminService' with projection on the entities 'Incidents' and 'Customers'.
    Make ProcessorService only accessible by the user with 'Support' role.
    Similarly, make AdminService to be only accessible by the user with 'Admin' role.
    Remove path parameters and other extra services.
    Enable draft editing for Incidents entity of ProcessorService using annotation.
    Make Customers entity of ProcessorService as readonly.
    
  3. 选择 Send 图标。

    cap-edit-model-prompt

  4. 选择 Accept。

    cap-accept-service

[!Tip]

  • CDS 服务定义把数据库 schema(schema.cds)中的实体作为服务层的一部分暴露出来,并带有基于角色的服务访问控制。

  • 模块化服务定义——服务(ProcessorService 和 AdminService)允许对数据进行受控访问。

  • 基于角色的访问 - ProcessorService → 支持人员可以管理事件和客户。 - AdminService → 管理员用户拥有完全访问权限。

  • 基于实体的投影——原始数据库实体不会直接暴露,只暴露投影版本。这允许定制、筛选或限制对某些字段的访问(如果将来需要)。 CAP 中的 OData 草稿启用允许用户在最终提交之前保存进行中的数据。这在 SAP Fiori 应用中特别有用,因为用户可能分多步输入数据,并希望避免丢失更改。

  1. 在项目资源管理器中打开 service.cds,验证生成的服务。

    validate-gen-service

  2. 转到 Storyboard。在 Services 部分,确保已创建 ProcessorService 和 AdminService。

    validate-edit-model

[!Note] Joule 为服务生成的代码可能不同。请确保最终的 srv/service.cds 文件如下所示:

using { sap.capire.incidents as my } from '../db/schema.cds';

@requires: 'Support'
service ProcessorService {

    @odata.draft.enabled
    entity Incidents as projection on my.Incidents;

    @readonly
    entity Customers as projection on my.Customers;
}

@requires: 'admin'
service AdminService {
    entity Customers as projection on my.Customers;

    entity Incidents as projection on my.Incidents;
}

后续步骤

使用 Joule 添加业务逻辑

使用 SAP Fiori Elements 模板生成 UI

  1. 选择汉堡菜单,然后选择 View → Command Palette。

    您也可以使用以下组合键快速调出命令面板:

    • macOS:Command + Shift + P

    • Windows:Ctrl + Shift + P

  2. 在字段中输入 Fiori: Open Application Generator,并从列表中选择该条目。

  3. 在 Template Selection 中选择 List Report Page 模板磁贴。然后选择 Next。

    V4 模板

  4. 在 Data Source and Service Selection 步骤中:

    • 在 Data source 下拉菜单中选择 Use a Local CAP Project。

    • 在 Choose your CAP project 下拉菜单中选择 incident-management 项目。

    • 在 OData service 下拉菜单中选择 ProcessorService (Node.js)。

    • 选择 Next。

      CAPpro

  5. 在 Entity Selection 步骤中:

    • 在 Main entity 下拉菜单中选择 Incidents。

    • Navigation entity 保持为 none。

    • 保持选中 Yes,以自动添加表格列。

    • Table Type 保持为 Responsive。

    • 选择 Next。

      实体选择

  6. 在 Project Attributes 步骤中:

    • 在 Module name 字段中输入 incidents。

    • 在 Application title 字段中输入 Incident-Management。

    • 在 Application namespace 字段中输入 ns。

    • 其他所有设置保持默认值,然后选择 Finish。

      项目名称

现在应用已生成,几秒钟后您就能在 incident-management 项目的 app 文件夹中看到应用的 incidents 文件夹。其中包含 webapp 文件夹,以及 SAPUI5 应用典型的 Component.js 文件。

将应用与 SAP Build Work Zone, Standard Edition 集成

本教程介绍如何订阅 SAP Build Work Zone, standard edition。

前提条件

按照「部署到 SAP BTP、Cloud Foundry 运行时」把应用部署到 SAP BTP、Cloud Foundry 并进行测试

更新内容

  1. 打开 SAP Build Work Zone。

  2. 在左侧导航栏中点击 Channel Manager。

  3. 选择刷新图标以获取更新后的内容。

    WorkZone1

将应用添加到 Content Explorer

  1. 在左侧菜单中选择 Content Manager 图标,然后选择 Content Explorer 按钮。

    WorkZone1

  2. 选择带有您子域名(subdomain)的 HTML5 Apps 磁贴。

    WorkZone1

  3. 在条目表格中勾选应用 Incidents,然后选择 Add 按钮。

[!Note] 点击勾选标记时,请确保选择的是您所创建的 ID 对应的应用

WorkZone1

创建组

  1. 回到 Content Manager,选择 Create → Group。

    WorkZone1

  2. 添加标题 Incident Management Group <your-initials><unique-random-number>。例如,标题可以是 Incident Management Group JD12。

  3. 在 Assignment Status 中,使用滑块把 Incident-Management 应用分配到该组。

[!Note] 点击滑块时,请确保选择的是您所创建的 ID 对应的应用

  1. 选择 Save。

    WorkZone1

将应用添加到 Everyone 角色

  1. 回到 Content Manager,选择角色 Everyone 并选择 Edit。

    WorkZone1

  2. 在 Assignment Status 中,使用滑块把 Incident-Management 应用分配到该角色。

  3. 选择 Save。

    WorkZone1

创建站点

  1. 导航到 Site Directory,选择 Create Site。

    WorkZone1

  2. 把站点名称输入为 Incident Management Site <your-initials><unique-random-number>,然后选择 Create。

    WorkZone1

  3. 现在会跳转到您创建的站点。

测试站点

  1. 导航到 Site Directory,找到您的站点。

    WorkZone1

  2. 选择 Go to site。

    WorkZone1

  3. 从启动页选择 Incident Management 应用。

    WorkZone1

    您应该能看到列表报表页。

    WorkZone1

后续步骤

按照「端到端测试应用」中的步骤端到端地测试流程。

lobby-subaccount

通过子账户访问 Build Code

  1. 导航到全局账户。点击 Account Explorer,点击 Subaccounts。选择您的子账户。

    btp GA

  2. 展开 Services,点击 Instances and Subscriptions。选择 Subscriptions 标签页,然后点击 SAP Build Code 打开 Build Code 大厅。

    btp subaccount

前提条件

您应该拥有

  • SAP BTP 全局账户

  • SAP S/4HANA 公有云系统

SAP BTP 上所需的权利

服务 / 订阅

套餐

实例数

SAP Build Code

standard

1

SAP Business Application Studio

build-code

1

SAP Build Work Zone, standard edition

standard

1

SAP HANA Cloud

tools

1

SAP HANA Cloud

hana

1

Connectivity Service

lite

1

SAP HANA Schemas & HDI Containers

hdi-shared

1

Destination Service

lite

1

HTML5 Application Repository Service

app-host

1

Application Logging Service

lite

1

Authorization and Trust Management Service

application

1

Cloud Foundry Runtime

Runtime

1 GB

SAP S/4HANA Cloud Extensibility

api-access

1

参见 权利与配额(Entitlements and Quotas)。

  • 添加 SAP S/4HANA Cloud Extensibility 权利时,请在 Service Details: SAP S/4HANA Cloud Extensibility 下拉菜单中选择相应的系统。

  • 在复选框中勾选 Available Plans 下的 api-access,并添加服务计划。

设置 SAP Build Code

  1. 下一步是在 SAP BTP 中设置 SAP Build Code

在 SAP BTP 中设置 SAP Build Code

前提条件

您应该拥有试用版或企业版 SAP BTP 全局账户。如果没有,请在 SAP BTP Trial 上获取账户

运行 SAP Build Code Booster

  1. 在 SAP BTP cockpit 中访问您的全局账户。它可以是试用版或企业版账户。

  2. 导航到试用版全局账户

    btp GA

  3. 点击 booster,选择 build code 以创建 Build Code 订阅。

    booster

  4. 运行 booster 后,在弹出窗口中选择 Navigate to Subaccount。

    successful booster

通过子账户访问 Build Code

  1. 导航到全局账户。点击 Account Explorer,点击 Subaccounts。选择您的子账户。

    btp GA

  2. 展开 Services,点击 Instances and Subscriptions。选择 Subscriptions 标签页,然后点击 SAP Build Code 打开 Build Code 大厅。

    btp subaccount

在 SAP Business Application Studio 中配置 Cline

在本节中,您将使用 SAP AI Core 作为 API 提供方,在 SAP Business Application Studio 中配置 Cline AI 编码助手。

步骤

第 1 步:导航到 Services and Instances

  1. 在 SAP BTP cockpit 中导航到 Services > Instances and Subscriptions。

  2. 选择 SAP Business Application Studio 打开它。

    导航到 Services and Instances

第 2 步:创建开发空间

  1. 选择 Create Dev Space。

    创建开发空间

第 3 步:配置开发空间

  1. 为开发空间输入名称。

  2. 在功能部分选择 Full Stack Cloud Application。

  3. 选择 Create dev Space。

    配置开发空间

第 4 步:打开开发空间

  1. 开发空间状态变为 Running 后,选择它即可打开。

    打开开发空间

第 5 步:安装 Cline 扩展

  1. Business Application Studio 工作区打开后,在左侧导航窗格中选择 Extensions 图标。

  2. 在扩展市场中搜索 Cline。

  3. 选择 Install 安装 Cline 扩展。

    安装 Cline 扩展

第 6 步:打开 Cline

  1. Cline 安装完成后,从左侧导航窗格中选择它。

    打开 Cline

第 7 步:选择 API Key 选项

  1. 选择 Bring your own API key,然后选择 Continue。

    选择 API Key 选项

第 8 步:选择 SAP AI Core 作为 API 提供方

  1. 在 API 提供方搜索字段中搜索并选择 SAP AI Core。

  2. 输入 SAP AI Core 的 API 密钥凭据。

  3. 从可用选项中选择 claude-sonnet-4 模型。

  4. 选择 Continue 完成 Cline 配置。

    选择 SAP AI Core

后续步骤:

  • 搭建应用

testcase

使用 Joule 添加测试用例

本节说明如何使用 Joule 提示创建几个测试用例。

前提条件

按照「使用 Joule 创建 SAP Fiori UI」中的步骤,使用 Joule 提示创建 UI 应用。

添加测试用例

  1. 导航到 Storyboard。

    Testcase

  2. 在 Services 部分,选择 ProcessorService 下的 Incidents 实体,然后选择 Add Logic。

    Testcase

  3. 出现 Application Logic Editor。

  4. 在 Application Logic Editor 中,把 Name 字段的值改为 incidents-test,然后选择 Add。

    Testcase

  5. 在 Phase 区域选择 After,在 Standard Event 中选择 Read。

    Testcase

  6. 选择 Open Code Editor -> Unit Test。

    Testcase

  7. Build Code 默认未启用测试环境。在弹出的窗口中点击 yes 以启用。

    confirm-test-env

  8. 这会打开 Joule,用于创建测试用例。

    Testcase

[!Note] 如果 Joule 提示中有 /cap-app-logic,请删除该提示,并输入 /cap-unit-test,因为 /cap-unit-test 用于为已创建的服务编写测试用例。

  1. Joule 提示会带有 /cap-unit-test #tests/code/test-incidents-test.js。在预填命令之后,使用以下提示创建测试用例。

    Test case to read all the incidents, and check only if the status code is 200. OData endpoint is /odata/v4/processor/Incidents
    
  2. 选择 Send 图标。

    Testcase

  3. Joule 返回代码后,检查并接受实现。

[!Note] 用于添加测试用例的 /cap-unit-test 提示仍在开发中。如果生成的代码有错误,请用以下代码片段替换,以测试 Incidents 实体的 READ 调用

module.exports = async function(GET, POST, PATCH, DELETE, expect) {
  // Send a GET request to the OData endpoint for Incidents
  const response = await GET('/odata/v4/processor/Incidents');

  // Assert that the response status code is 200
  expect(response.status).to.equal(200);
};

测试应用

  1. 点击汉堡图标打开终端,然后点击 Terminal -> New Terminal。

    Testcase

  2. 安装 CAP 测试插件

     npm add -D @cap-js/cds-test
    

这是一个包含 CAP Node.js 应用测试工具的库

  1. 要测试应用,请在终端中运行以下命令:

        npm run test
    

    Testcase

恭喜!您已成功完成本练习。

验证自定义逻辑场景:

如果标题中出现 urgent 关键字,就把 Urgency 从 Low/Medium 更新为 High。

  1. 点击 Create 创建新事件。

    testing

  2. 创建事件时执行以下操作:

    • 通过点击值帮助选择任意一个客户。

      testing

    • 把标题设为 Urgent issue

    • 保持 urgency_code 和 status_code 为默认值。

    • 点击 Create。

      testing

  3. 事件创建后,您会观察到 urgency_code 自动从 M(Medium)变为 H(High)。

    testing

恭喜!您已成功完成本练习。

了解 Incident Management 应用结构

概述

Incident Management 应用是使用 SAP Cloud Application Programming Model(CAP)构建的全栈 SAP BTP 应用。它充当支持工单系统,呼叫中心代表可以管理具有不同紧急级别和状态的客户事件。

业务场景

ACME Electronics 使用此应用管理客户支持事件:

  • 呼叫中心支持代表(Processor)接听客户电话

  • 他们代表客户创建新事件

  • 事件从创建到解决会经历各种状态

  • 每个事件都会维护对话历史

  • 业务规则强制数据完整性和工作流约束

解决方案图

解决方案图

项目结构

incidents-app/
├── package.json              # Project configuration and dependencies
├── mta.yaml                 # Multi-target application descriptor
├── xs-security.json         # Security configuration
├── db/                      # Database layer
│   ├── schema.cds          # Data model definitions
│   ├── data/               # Sample data (CSV files)
│   └── src/                # Database artifacts
├── srv/                     # Service layer
│   ├── services.cds        # Service definitions
│   └── services.js         # Service implementation (business logic)
├── app/                     # UI layer
│   ├── services.cds        # UI service bindings
│   ├── launchpage.html     # Application launchpad
│   └── incidents/          # Fiori Elements app
│       ├── annotations.cds # UI annotations
│       ├── webapp/         # UI5 application
│       └── package.json    # UI app configuration
└── tests/                   # Test suite
    └── test.js             # Jest-based API tests

数据模型(数据库层)

核心实体

1. Incidents 实体

表示支持工单的主实体:

entity Incidents : cuid, managed {  
    customer       : Association to Customers;
    title          : String  @title : 'Title';
    urgency        : Association to Urgency default 'M';
    status         : Association to Status default 'N';
    resolutionNote : String  @title : 'Resolution Note';
    conversation   : Composition of many {
        key ID    : UUID;
        timestamp : type of managed:createdAt;
        author    : type of managed:createdBy;
        message   : String;
    };
}

关键特性:

  • CUID:通用唯一标识符

  • Managed:自动审计字段(createdAt、createdBy、modifiedAt、modifiedBy)

  • 关联:链接到 Customer、Status 和 Urgency 实体

  • 组合:嵌入的对话历史

  • Resolution Note:用于记录事件解决情况的字段

2. Customers 实体

表示可以创建事件的客户:

entity Customers : managed { 
    key ID        : String;
    firstName     : String;
    lastName      : String;
    name          : String = firstName ||' '|| lastName;  // Calculated field
    email         : EMailAddress;
    phone         : PhoneNumber;
    incidents     : Association to many Incidents on incidents.customer = $self;
    creditCardNo  : String(16) @assert.format: '^[1-9]\d{15}$';  // Validation
    addresses     : Composition of many Addresses on addresses.customer = $self;
}

关键特性:

  • 计算字段:全名由名字和姓氏派生

  • 校验:使用正则表达式校验信用卡格式

  • 关联:与事件的一对多关系

  • 组合:嵌入的地址

3. 代码列表实体

Status 实体:

entity Status : CodeList {
    key code: String enum {
        new = 'N';           // New incident
        assigned = 'A';      // Assigned to processor
        in_process = 'I';    // Being worked on
        on_hold = 'H';       // Temporarily paused
        resolved = 'R';      // Solution provided
        closed = 'C';        // Incident closed
    };
    criticality : Integer;   // For UI color coding
}

Urgency 实体:

entity Urgency : CodeList {
    key code: String enum {
        high = 'H';          // High priority
        medium = 'M';        // Medium priority (default)
        low = 'L';           // Low priority
    };
}

服务层

ProcessorService

支持人员的首选服务:

service ProcessorService {
    entity Incidents as projection on my.Incidents;
    @readonly
    entity Customers as projection on my.Customers;
}

annotate ProcessorService.Incidents with @odata.draft.enabled;
annotate ProcessorService with @(requires: 'support');

关键特性:

  • 草稿支持:为事件编辑启用草稿模式

  • 授权:需要 'support' 角色

  • 只读 Customers:Processor 可以查看但不能修改客户数据

AdminService

面向系统管理员的管理服务:

service AdminService {
    entity Customers as projection on my.Customers;
    entity Incidents as projection on my.Incidents;
}

annotate AdminService with @(requires: 'admin');

关键特性:

  • 完全访问:对所有实体拥有完整的 CRUD 操作

  • 授权:需要 'admin' 角色

业务逻辑实现

服务实现(services.js)包含自定义业务规则:

1. 自动分配紧急级别
changeUrgencyDueToSubject(data) {
    if (data) {
        const incidents = Array.isArray(data) ? data : [data];
        incidents.forEach((incident) => {
            if (incident.title?.toLowerCase().includes("urgent")) {
                incident.urgency = { code: "H", descr: "High" };
            }
        });
    }
}
2. 已关闭事件保护
async onUpdate (req) {
    const { status_code } = await SELECT.one(req.subject, i => i.status_code).where({ID: req.data.ID})
    if (status_code === 'C')
        return req.reject(`Can't modify a closed incident`)
}

UI 层(Fiori Elements)

应用结构

UI 使用 SAP Fiori Elements 构建,提供:

  • List Report:所有事件的概览,支持筛选和排序

  • Object Page:单个事件的详细视图

  • 草稿模式:允许编辑并支持保存/放弃功能

UI 注解

annotations.cds 文件定义了 UI 结构:

List Report 配置
UI.LineItem : [
    { $Type : 'UI.DataField', Value : ID, Label : '{i18n>Title}' },
    { $Type : 'UI.DataField', Label : '{i18n>Customer}', Value : customer_ID },
    { $Type : 'UI.DataField', Label : 'Status', Value : status_code, Criticality : status.criticality },
    { $Type : 'UI.DataField', Label : '{i18n>Urgency}', Value : urgency_code }
]
Object Page 布局
UI.Facets : [
    {
        $Type : 'UI.CollectionFacet',
        Label : '{i18n>Overview}',
        Facets : [
            { $Type : 'UI.ReferenceFacet', Label : '{i18n>GeneralInformation}', Target : '@UI.FieldGroup#GeneratedGroup' },
            { $Type : 'UI.ReferenceFacet', Label : '{i18n>Details}', Target : '@UI.FieldGroup#i18nDetails' }
        ]
    },
    { $Type : 'UI.ReferenceFacet', Label : '{i18n>Conversation}', Target : 'conversation/@UI.LineItem#i18nConversation' }
]

值帮助配置

带值帮助的客户选择:

customer @(
    Common.ValueList : {
        CollectionPath : 'Customers',
        Parameters : [
            { $Type : 'Common.ValueListParameterInOut', LocalDataProperty : customer_ID, ValueListProperty : 'ID' },
            { $Type : 'Common.ValueListParameterDisplayOnly', ValueListProperty : 'name' },
            { $Type : 'Common.ValueListParameterDisplayOnly', ValueListProperty : 'email' }
        ]
    }
)

测试策略

测试结构

应用包含全面的基于 Jest 的测试(tests/test.js):

1. 实体测试
  • 验证从 ProcessorService 检索数据

  • 检查实体关系和数据完整性

  • 测试 OData expand 操作

2. 草稿编排测试
  • 创建事件草稿

  • 测试草稿激活

  • 验证业务逻辑执行

  • 测试草稿删除

3. 业务逻辑测试
  • 根据标题自动分配紧急级别

  • 防止修改已关闭事件

  • 状态转换校验

示例测试用例

it('+ Activate the draft & check Urgency code as H using custom logic', async () => {
    const response = await POST(
        `/odata/v4/processor/Incidents(ID=${draftId},IsActiveEntity=false)/ProcessorService.draftActivate`
    )
    expect(response.status).to.eql(201)
    expect(response.data.urgency_code).to.eql('H')  // Validates business rule
})

配置与依赖

关键依赖

{
    "@sap/cds": "^9",           // CAP framework
    "express": "^4",            // Web server
    "@cap-js/hana": "^2",       // HANA database support
    "@sap/xssec": "^4",         // Security library
    "@cap-js/sqlite": "^2"      // SQLite for development
}

环境配置

"cds": {
    "requires": {
        "[development]": {
            "auth": { "kind": "mocked" }  // Mock authentication for development
        },
        "[production]": {
            "db": "hana",                 // HANA database in production
            "auth": "xsuaa"               // XSUAA authentication
        }
    }
}

安全模型

基于角色的访问控制

  • Support 角色:访问 ProcessorService 以管理事件

  • Admin 角色:完全访问 AdminService 以进行系统管理

  • Mock 用户:Alice 和 Bob,用于开发的支持角色

身份验证

  • 开发:使用预定义用户进行模拟身份验证

  • 生产:基于 XSUAA 的身份验证,具备完善的用户管理

部署架构

多目标应用(MTA)

mta.yaml 文件定义了:

  • 数据库模块:把 schema 部署到 HANA

  • 服务模块:部署 CAP 应用

  • UI 模块:部署 Fiori 应用

  • Approuter:路由与身份验证

Cloud Foundry 服务

  • HANA Database:持久化数据存储

  • XSUAA:身份验证与授权

  • Destination Service:外部服务连通性

  • HTML5 Runtime:托管 UI 应用

已实施的最佳实践

1. 数据建模

  • 使用 managed 方面实现审计跟踪

  • 恰当的关联与组合关系

  • 使用断言进行输入校验

  • 为派生数据使用计算字段

2. 服务设计

  • 服务之间清晰地分离关注点

  • 恰当的授权注解

  • 为复杂编辑场景启用草稿

  • 在适当的地方使用只读投影

3. UI 设计

  • 一致使用 i18n 进行国际化

  • 恰当的字段分组与方面组织

  • 为复杂选择提供值帮助

  • 用关键性指示器可视化状态

4. 测试

  • 全面的 API 测试

  • 草稿编排验证

  • 业务逻辑验证

  • 错误场景测试

这个事件管理应用展示了使用 CAP 的现代 SAP BTP 开发实践,为企业级支持工单管理系统提供了坚实基础。

后续步骤

  • 更新业务场景

引言

SAP BTP 应用需要连接 SAP 系统来获取和处理数据。

您可以在 SAP Business Accelerator Hub 中找到完成扩展场景所需的、由 SAP 系统暴露的 API。 SAP BTP Connectivity 允许 SAP BTP 应用安全地访问运行在互联网或本地环境中的 API。 要允许运行在 SAP BTP 上的应用使用 SAP S/4HANA Cloud API,您需要创建 SAP S/4HANA Cloud Extensibility 服务的服务实例。

业务场景

在本教程中,我们将把 SAP S/4HANA Public Cloud Business Partner API 集成到 Incident Management 应用。

Incident Management 应用帮助呼叫中心支持代表处理和管理客户事件。支持代表(processor)接到现有客户的电话,并代表客户创建一个新事件。

当 processor 创建新事件时,必须把事件分配给相应的客户。选择客户的选项会以值帮助的形式提供,值帮助中的客户列表来自 SAP S/4HANA Public Cloud 系统。

解决方案图

解决方案图

后续步骤

扩展 Incident Management 应用

为生产环境准备项目

使用场景

要使用 SAP S/4HANA Cloud Extensibility 服务访问 Business Partner API,您需要一些额外配置。

前提条件

您已设置与 SAP S/4HANA Cloud 系统的连接。参见「配置 SAP S/4HANA Cloud 与 SAP BTP 之间的连通性」。

为 SAP S/4HANA Cloud Extensibility 添加权利

  1. 导航到要添加权利的子账户。

  2. 选择 Entitlements,然后选择 Edit。

    entitlements

  3. 选择 Add Service Plans。

  4. 搜索 SAP S/4HANA Cloud Extensibility Service,从下拉菜单中选择系统,选择服务计划 api-access,然后选择 Add 1 Service Plan。

    create-new-file

  5. 选择 Save。

为 SAP S/4HANA Cloud Extensibility 创建服务实例

  1. 在子账户中导航到 Instances and Subscriptions。

  2. 选择 Create,在下拉菜单中搜索并选择 SAP S/4HANA Cloud Extensibility。

  3. 选择在权利步骤中添加的服务计划。

  4. 选择运行时环境(例如 Cloud Foundry)。

  5. 提供有意义的实例名称,然后选择 Next。 create-instance

  6. 复制以下内容并粘贴到实例参数中。

    {
        "systemName": "<SYSTEM_NAME>",
        "communicationArrangement": {
            "communicationArrangementName": "<COMM_NAME>",
            "scenarioId": "SAP_COM_0008",
            "inboundAuthentication": "BasicAuthentication",
            "outboundAuthentication": "BasicAuthentication",
            "outboundServices": [
                {
                    "name": "Replicate Customers from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Suppliers from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Company Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Workplace Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Personal Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner - Replicate from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner Relationship - Replicate from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner - Send Confirmation from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "BP Relationship - Send Confirmation from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                }
            ],
            "communicationSystem": {
                "communicationSystemHostname": "default.com",
                "outboundCommunicationUser": {
                    "username": "DefaultUser",
                    "password": "DefaultPassword"
                }
            }
        }
    }
    
  • 输入您注册的 SAP S/4HANA Cloud 系统名称,我们已在本动手练习的 SAP Business Technology Platform(BTP)账户中注册了该系统。

  • 对于 communicationArrangementName,请为您通信安排输入一个便于识别的名称(例如 INCIDENT_MANAGEMENT_0008)。

更多信息,参见 Communication Arrangement JSON/YAML File - Properties。

  1. 选择 Create。

使用 SAP S/4HANA Cloud 后端在 Cloud Foundry 上部署并运行应用

使用场景

使用 MTA 构建文件把项目部署到 Cloud Foundry。

前提条件

在本地测试 Incident Management 应用

内容

在本节中,您将使用 SAP S/4HANA Cloud 扩展服务的设置来扩展现有的 MTA 构建文件。

部署应用

  1. 导航到 Task Explorer,运行 Enable Discovery and Deploy。

    deploy-cf

[!Note] 请确保您已在之前的练习中登录 Cloud Foundry

  1. 部署成功后,终端中会收到确认消息

    deploy-mtar-success

在访问应用之前,请确保您已在之前的练习中分配应用角色。

请确保在之前的练习中已完成与 SAP Build Workzone 的集成,以便在启动页中访问应用。

后续步骤

测试端到端流程

获取 Business Partner API

SAP Business Accelerator Hub 是 SAP 托管的 Web 应用,您可以在其中发现、探索和测试构建扩展或流程集成所需的 SAP 及合作伙伴 API(Application Programming Interfaces)。

在 SAP Business Accelerator Hub 中,您可以找到完成扩展场景所需的 API。

在我们的场景中,我们使用 SAP S/4HANA Cloud 的 Business Partner API。

下载 Business Partner API

  1. 在 SAP Business Accelerator Hub 中,转到 Business Partner API (A2X)。

  2. 在 API Resources 中选择 API Specification。

  3. 从文件列表中下载 EDMX 文件。后续章节会用到此文件。

    下载 API

后续

扩展 Incident Management 应用

扩展 Incident Management 应用

  1. 要添加服务,请执行以下操作:

    • 点击 Service Center(如下方截图中的左侧导航)

    • 把 Select a Provider 设为 SAP SYSTEM

    • 选择 Service incidents-api-access。

      service-center

  2. 输入服务路径 /sap/opu/odata/sap/API_BUSINESS_PARTNER,然后选择 connect。

    service-url

  3. 选择 Add to CAP Project。

    add-cap

[!Note] 如果 UI 提示选择项目,请选择您之前用 Incidents<Initial><Uniquid> 创建的项目名。然后点击 Add。 add-cap

  1. 修改部分实体之间关系的条件。打开 srv/external/incidents_api_access.cds。搜索实体 A_BusinessPartner。向下滚动到 to_BusinessPartnerAddress 部分,用以下内容替换:

    to_BusinessPartnerAddress : Composition of many incidents_api_access.A_BusinessPartnerAddress on to_BusinessPartnerAddress.BusinessPartner = BusinessPartner;
    

    add-cap

  2. 搜索实体 A_BusinessPartnerAddress。向下滚动到 to_EmailAddress 部分,用以下内容替换电子邮件地址的关联。

    to_EmailAddress : Composition of many incidents_api_access.A_AddressEmailAddress on to_EmailAddress.AddressID = AddressID;
    
  3. 滚动到实体 A_BusinessPartnerAddress 下的 to_PhoneNumber 部分,用以下内容替换电话号码的关联。

    to_PhoneNumber : Composition of many incidents_api_access.A_AddressPhoneNumber on to_PhoneNumber.AddressID = AddressID;
    

    add-cap

  4. 在 srv 文件夹中创建新文件 remote.cds。

    create-new-file

  5. 把以下代码片段复制到新建的 remote.cds 文件中:

    using { incidents_api_access as S4 } from './external/incidents_api_access';
    
    service RemoteService {
      entity BusinessPartner as projection on S4.A_BusinessPartner {
        key BusinessPartner as ID,
        BusinessPartnerName as name,
        to_BusinessPartnerAddress as addresses
      }
      entity BusinessPartnerAddress as projection on S4.A_BusinessPartnerAddress {
                BusinessPartner as ID,
                AddressID as addressId,
                to_EmailAddress as email,
                to_PhoneNumber as phoneNumber
      }
      entity EmailAddress as projection on S4.A_AddressEmailAddress {
          key AddressID as addressId,
          EmailAddress as email
      }
    
      entity PhoneNumber as projection on S4.A_AddressPhoneNumber {
          key AddressID as addressId,
          PhoneNumber as phone
      }
    }
    
  6. 为读取和保存 business partner 添加一些业务逻辑。

    • 打开 srv/service.js 文件。

    • 确保 init 方法被设为 async:

      async init() {
        this.before("UPDATE", "Incidents", (req) => this.onUpdate(req));
        this.before(["CREATE", "UPDATE"], "Incidents", (req) => this.changeUrgencyDueToSubject(req.data));
      
        return super.init();
      }
      
    • 在 init() 方法中为 Customers 的 READ 添加自定义处理器:

      this.on('READ', 'Customers', (req) => this.onCustomerRead(req));
      
    • 在 init 方法之后添加自定义处理器实现:

      此处理器从远程 S/4HANA Business Partner 服务读取客户数据,并为应用中的 Customers 值帮助准备数据:

      • 它转发传入的读取请求,并记录查询以便排查问题。

      • 它使用 $top 和 $skip 应用分页(默认值分别为 100 和 0)。

      • 它使用 expand 读取 BusinessPartner 记录,包括嵌套的地址电子邮件数据。

      • 它把远程响应映射为包含 ID、name 和 email 的简化结构。

      • UI 值帮助将正确显示 BusinessPartner 的总条目数。

      async onCustomerRead(req) {
        console.log('>> delegating to S4 service...', req.query);
        const top = parseInt(req._queryOptions?.$top) || 100;
        const skip = parseInt(req._queryOptions?.$skip) || 0;
        
        const { BusinessPartner } = this.remoteService.entities;
      
        // Expands are required as the runtime does not support path expressions for remote services
        let result = await this.S4bupa.run(SELECT.from(BusinessPartner, bp => {
          bp('*'),
            bp.addresses(address => {
              address('email'),
                address.email(emails => {
                  emails('email');
                });
            })
        }).limit(top, skip));
        
        result = result.map((bp) => ({
          ID: bp.ID,
          name: bp.name,
          email: bp.addresses[0]?.email[0]?.email
        }));
      
        // Explicitly set $count so the values show up in the value help in the UI
        result.$count = 1000;
        console.log("after result", result);
        return result;
      }  
        
      
    • 为事件的 CREATE、UPDATE、DELETE 添加自定义处理器。把以下代码片段添加到 init 方法中:

      this.on(['CREATE','UPDATE'], 'Incidents', (req, next) => this.onCustomerCache(req, next));
      this.S4bupa = await cds.connect.to('incidents_api_access');
      this.remoteService = await cds.connect.to('RemoteService');
      
    • 在上一步创建的 onCustomerRead 方法之后添加自定义处理器:

      当事件被创建或更新并带有客户引用时,此处理器会让本地 Customers 实体保持同步。在主事件操作完成后,它从远程 S/4HANA 服务读取所选的 Business Partner(包括电子邮件和电话),把嵌套响应映射为扁平字段,然后在本地数据库中更新插入(upsert)客户。

      这样,事件流程对用户保持不变,而客户详细信息会在后台本地缓存,供后续使用。

      async onCustomerCache(req, next) {
        const { Customers } = this.entities;
        const newCustomerId = req.data.customer_ID;
        const result = await next();
        const { BusinessPartner } = this.remoteService.entities;
        if (newCustomerId && (newCustomerId !== "") && ((req.event == "CREATE") || (req.event == "UPDATE"))) {
          console.log('>> CREATE or UPDATE customer!');
      
          // Expands are required as the runtime does not support path expressions for remote services
          const customer = await this.S4bupa.run(SELECT.one(BusinessPartner, bp => {
            bp('*'),
              bp.addresses(address => {
                address('email', 'phoneNumber'),
                  address.email(emails => {
                    emails('email')
                  }),
                  address.phoneNumber(phoneNumber => {
                    phoneNumber('phone')
                  })
              })
          }).where({ ID: newCustomerId }));
                                                                                        
          if(customer) {
            customer.email = customer.addresses[0]?.email[0]?.email;
            customer.phone = customer.addresses[0]?.phoneNumber[0]?.phone;
            delete customer.addresses;
            delete customer.name;
            await UPSERT.into(Customers).entries(customer);
          }
        }
        return result;
        }
      

结果

您已将 Business Partner API 集成到项目中,并添加了从后端系统读取数据的业务逻辑。新建或变更的客户数据将存储在应用数据库中。

后续步骤

  • 在本地运行开发者测试

为生产环境准备项目

使用场景

要使用 SAP S/4HANA Cloud Extensibility 服务访问 Business Partner API,您需要一些额外配置。

前提条件

您已设置与 SAP S/4HANA Cloud 系统的连接。参见「配置 SAP S/4HANA Cloud 与 SAP BTP 之间的连通性」。

内容

  1. 在项目根文件夹中创建新文件 bupa.json。

    create-new-file

  2. 把以下内容复制到上一步创建的 bupa.json 文件中。

    {
        "systemName": "<SYSTEM_NAME>",
        "communicationArrangement": {
            "communicationArrangementName": "<COMM_NAME>",
            "scenarioId": "SAP_COM_0008",
            "inboundAuthentication": "BasicAuthentication",
            "outboundAuthentication": "BasicAuthentication",
            "outboundServices": [
                {
                    "name": "Replicate Customers from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Suppliers from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Company Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Workplace Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Replicate Personal Addresses from S/4 System to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner - Replicate from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner Relationship - Replicate from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "Business Partner - Send Confirmation from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                },
                {
                    "name": "BP Relationship - Send Confirmation from SAP S/4HANA Cloud to Client",
                    "isServiceActive": false
                }
            ],
            "communicationSystem": {
                "communicationSystemHostname": "default.com",
                "outboundCommunicationUser": {
                    "username": "DefaultUser",
                    "password": "DefaultPassword"
                }
            }
        }
    }
    
  • 输入 pes-workshop-s4hana-cloud 作为您注册的 SAP S/4HANA Cloud 系统的 systemName,我们已为本动手练习在 SAP Business Technology Platform(BTP)账户中注册了该系统。

  • 对于 communicationArrangementName,请为您通信安排输入一个便于识别的名称(例如 INCIDENT_MANAGEMENT_0008)。

更多信息,参见 Communication Arrangement JSON/YAML File - Properties。

后续步骤

使用 SAP S/4HANA Cloud 部署到 SAP BTP Cloud Foundry 运行时

使用 SAP Destination 服务连接远程服务(SAP BTP、Cloud Foundry 运行时与 SAP S/4HANA Cloud)

  1. 获取 Business Partner API

  2. 扩展 Incident Management 应用

  3. 使用 mock 数据运行开发者测试

  4. 为生产环境准备应用

  5. 使用 SAP S/4HANA Cloud 部署到 SAP BTP Cloud Foundry 运行时

  6. 端到端测试流程

前提条件

  1. 按照基础练习开发 Incident Management 应用。

  2. 把 Incident Management 应用部署到 Cloud Foundry 运行时:

    • SAP BTP、Cloud Foundry 运行时:在 SAP BTP、Cloud Foundry 运行时中部署全栈 CAP 应用。

  3. 运行以下命令取消部署应用:

    • SAP BTP、Cloud Foundry 运行时:cf undeploy <YOUR_MTA_ID> --delete-services

  4. 为本动手练习,我们已在 SAP Business Technology Platform(BTP)中设置好「注册 SAP S/4HANA Cloud 系统」。

系统与账户

  • SAP S/4HANA Cloud 系统

所需的额外权利

将远程服务集成到所开发的 CAP 应用,需要在 SAP BTP cockpit 中具备以下额外权利和配额:

服务

套餐

实例数

SAP S/4HANA Cloud Extensibility

api-access

1

参见 权利与配额(Entitlements and Quotas)。

  • 添加 SAP S/4HANA Cloud Extensibility 权利时,请在 Service Details: SAP S/4HANA Cloud Extensibility 下拉菜单中选择相应的系统。

  • 在复选框中勾选 Available Plans 下的 api-access,并添加服务计划。

配置 SAP S/4HANA Cloud 与 SAP BTP 之间的连通性

引言

您可以使用 SAP BTP 扩展标准 SAP 解决方案,而不影响其性能和核心流程。构建扩展应用时,您还可以受益于 SAP BTP 与被扩展 SAP 解决方案之间集成的自动化。

SAP BTP 提供了扩展 SAP 解决方案、开发事件驱动扩展和应用的标准方式。此框架包括:

  • 为 SAP 解决方案提供简化、标准化且统一的扩展性与配置。

  • 每个客户一个集中目录,存放所有已连接 SAP 系统的数据,例如 API、事件、凭据等。您可以跨端到端业务流程享用业务服务和可操作事件。

SAP S/4HANA Cloud 支持与 SAP BTP 的自动集成

使用场景

要使用服务绑定连接 SAP S/4HANA Cloud 系统,您必须在 SAP Business Technology Platform(BTP)账户中注册该系统。

前提条件

您需要一个对 SAP BTP 全局账户和 SAP S/4HANA Cloud 系统具有管理员访问权限的用户。

SAP Business Technology Platform

  1. 在 SAP BTP cockpit 中打开您的全局账户,选择 System Landscape。

  2. 在 System Landscape 屏幕中,选择 Systems,然后选择 Add System。

    注册系统

  3. 在 Register System 对话框中,为您要连接的 SAP S/4HANA Cloud 系统输入名称。

  • 建议:使用能唯一标识该系统的名称,例如系统 ID。

  • 示例:S/4HANA Cloud DEV System

  1. 在 Type 下拉列表中选择 SAP S/4HANA Cloud。

  2. 选择 Add。

    选择 Add

  3. 配置通信流。在 Communication Scenario Groups 下拉菜单中选择 All Communication Scenarios。

    approve

  4. 选择 Get Token。 SAP BTP 会生成一个集成令牌,使 SAP S/4HANA Cloud 系统管理员可以从您的 SAP S/4HANA Cloud 系统配置与 SAP BTP 的集成。

    获取令牌

  5. 复制生成的令牌并关闭对话框。 后续步骤中会用到该令牌。

SAP S/4HANA Cloud

  1. 登录您的 SAP S/4HANA Cloud 租户。

  2. 导航到 Home -> Communication Management 标签页,选择 Maintain Extensions on SAP BTP 磁贴。

    Maintain

  3. 在 Maintain Extensions on SAP BTP 屏幕的 Integration 部分,选择 New。

    New

  4. 在 Integration Token 字段中,粘贴之前在 SAP BTP Cockpit 中生成并复制的集成令牌。

    粘贴

  5. 为您的系统集成令牌输入描述。

  • 建议:使用您在 SAP BTP cockpit 中生成令牌时输入的相同名称。

  • 示例:S/4HANA Cloud 系统名称

  1. 选择 Save。

  • 表格中会为您的系统显示一个新条目,状态为 Enabling。

  • 等待几秒钟。

  • 自动集成完成后,系统集成状态会变为 Enabled。

  • SAP BTP 一侧也会发生同样的变化。您会看到该系统显示为 Registered——可能需要刷新后才能看到。

    Registered

另请参见:在 SAP BTP 全局账户中注册 SAP S/4HANA Cloud 系统。

端到端测试流程

运行并测试应用

  1. 在浏览器中打开 SAP Build Work Zone。

  2. 在 Site Directory 下找到您之前创建的站点。

    launchpad

  3. 通过启动页访问您的应用。

    测试应用

  4. 创建新事件时,客户的值帮助会从集成的远程服务加载数据。

    • 选择 Create

      运行测试

    • 设置 Title、Customer、Status 和 Urgency。

    • Customer 的值帮助会从远程服务器获取数据。

    • 创建一条对话。

    • 选择 Create 保存设置。

      运行测试

[!Note] 如果您还没有完成增强 Fiori UI 章节,创建对话不会在 UI 中显示。

恭喜!

您已成功完成本练习!

在本地测试 Incident Management 应用

场景

为提高开发速度,在本地环境中运行和测试实现会很有帮助。在本节中,您将学习如何在本地测试 Incident Management 应用。

内容

为新实体创建 Mock 数据

  1. 如果您使用 Cloud Foundry 开发,请打开 Business Application Studio;如果使用 Kyma 开发,请打开 Visual Studio Code。

  2. 导航到 Incident Management 应用代码库,在 srv/external 文件夹中创建新文件夹 data。

  3. 创建新文件 incidents_api_access-A_BusinessPartner.csv,并向其中添加以下数据

    BusinessPartner;FirstName;LastName;BusinessPartnerName;BusinessPartnerIsBlocked;
    1004155;Daniel;Watts;Daniel Watts;false
    1004161;Stormy;Weathers;Stormy Weathers;false
    1004100;Sunny;Sunshine;Sunny Sunshine;true
    
  4. 创建新文件 incidents_api_access-A_BusinessPartnerAddress.csv,并向其中添加以下数据

    BusinessPartner;AddressID;
    1004155;123
    1004161;345
    1004100;456
    
  5. 创建新文件 incidents_api_access-A_AddressEmailAddress.csv,并向其中添加以下数据

    AddressID;EmailAddress;Person;OrdinalNumber
    123;test@demo.com;Williams;123
    345;testjohn@demo.com;Smith;222
    456;testhencry@demo.com;johnson;333
    
  6. 创建新文件 incidents_api_access-A_AddressPhoneNumber.csv,并向其中添加以下数据

    AddressID;PhoneNumber;Person;OrdinalNumber
    123;+44-555-123;Daniel;123
    345;+01-555-688;Stormy;222
    456;+01-555-789;Sunny;333
    

    mock 数据

运行 Incident Management 应用

  1. 构建应用。

    npm i
    
  2. 在本地运行 mock 服务器。

    cds mock incidents_api_access
    
  3. 在终端中应看到以下输出

    [cds] - connect using bindings from: { registry: '~/.cds-services.json' }
    [cds] - connect to db > sqlite { url: ':memory:' }
       > init from db/data/sap.capire.incidents-Urgency.csv 
       > init from db/data/sap.capire.incidents-Status.csv 
       > init from db/data/sap.capire.incidents-Incidents.csv 
       > init from db/data/sap.capire.incidents-Customers.csv 
       > init from db/data/sap.capire.incidents-Conversations.csv 
       > init from srv/external/data/incidents_api_access-A_BusinessPartnerAddress.csv 
       > init from srv/external/data/incidents_api_access-A_BusinessPartner.csv 
       > init from srv/external/data/incidents_api_access-A_AddressPhoneNumber.csv 
       > init from srv/external/data/incidents_api_access-A_AddressEmailAddress.csv  
    

    如果 incidents_api_access 没有出现,请删除 .cds-services.json 文件——它位于用户根文件夹中(例如:/home/user/.cds-services.json)

  4. 打开新终端并运行 cds watch。这会启动应用并连接到正在运行的 mock 服务。

  5. 要在终端中打开服务器 URL,请点击 http://localhost:4004。

    运行测试

  6. Web 应用下有两个 URL:

    运行测试

  7. 当系统提示进行身份验证时,请使用以下凭据:

    • 用户名:alice

    • 密码:为空 / 无密码

    用户设置位于 .cdsrc.json file 中。

  8. 测试场景——创建新事件时,客户的值帮助会从 mock 服务加载数据。

    • 打开 Incident Management 应用。

      运行测试

    • 选择 Create。

      运行测试

    • 设置 Title、Customer、Status 和 Urgency。

    • Customer 的值帮助会从 mock 服务器获取数据。

    • 创建一条对话。

    • 选择 Create 保存设置。

      运行测试

总结

使用 mock 服务器,您可以轻松地在本地环境中测试实现。更多细节参见 Local Mocking 文档。

后续步骤

  • 为智能体编码设置 MCP 服务器