SAP Build Process Automation

1// Trigger a Build Process Automation workflow via REST API
2// POST /public/workflow/rest/v1/workflow-instances
3// Auth: OAuth2 client credentials (Build PA service instance binding)
4
5const axios = require('axios')
6
7async function triggerPOApprovalWorkflow(poData) {
8  // 1. Obtain an OAuth2 access token from XSUAA
9  const tokenResponse = await axios.post(
10    `${process.env.XSUAA_URL}/oauth/token`,
11    new URLSearchParams({
12      grant_type: 'client_credentials',
13      client_id: process.env.BPA_CLIENT_ID,
14      client_secret: process.env.BPA_CLIENT_SECRET,
15    }),
16    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
17  )
18  const accessToken = tokenResponse.data.access_token
19
20  // 2. Trigger the workflow instance
21  const response = await axios.post(
22    `${process.env.BPA_API_URL}/public/workflow/rest/v1/workflow-instances`,
23    {
24      // Process definition ID — set in Build PA designer
25      definitionId: 'po-approval-workflow',
26
27      // Context payload — available as process variables in the workflow
28      context: {
29        purchaseOrderId: poData.id,
30        purchaseOrderNumber: poData.number,
31        amount: poData.totalAmount,
32        currency: poData.currency,
33        costCenter: poData.costCenter,
34        vendorName: poData.vendorName,
35        requestorEmail: poData.requestorEmail,
36        requestorName: poData.requestorName,
37        // ISO 8601 deadline for the entire process
38        processDeadline: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000).toISOString(),
39      },
40    },
41    {
42      headers: {
43        Authorization: `Bearer ${accessToken}`,
44        'Content-Type': 'application/json',
45      },
46    }
47  )
48
49  // Returns { id, definitionId, status, startedAt, ... }
50  return response.data
51}
52
53module.exports = { triggerPOApprovalWorkflow }

1// SAP Build Process Automation — Business Rules
2// Decision table structure (represented as configuration data)
3// Defined visually in the Rules Editor; exported as rule service descriptor
4
5// ── Decision Table: PO Approval Routing ─────────────────────────────────────
6// Rule Service ID: po-approval-routing
7// Input parameters:  amount (Number), currency (String), costCenter (String)
8// Output parameters: approvalLevel (String), autoApprove (Boolean)
9
10// Rule table rows (evaluated top-to-bottom, first match wins):
11//
12// | amount    | currency | costCenter   | approvalLevel | autoApprove |
13// |-----------|----------|--------------|---------------|-------------|
14// | <= 1000   | EUR      | *            | "NONE"        | true        |
15// | <= 5000   | EUR      | *            | "MANAGER"     | false       |
16// | <= 25000  | EUR      | CC-FINANCE   | "MANAGER"     | false       |
17// | <= 25000  | EUR      | *            | "CFO"         | false       |
18// | > 25000   | EUR      | *            | "BOARD"       | false       |
19// | *         | USD      | *            | "CFO"         | false       |
20
21// ── Invoking the Rule Service from a Process ─────────────────────────────────
22// In the Process Editor, add a "Decision" step and configure:
23//   Rule Service: po-approval-routing
24//   Input mapping:
25//     amount     → process variable: context.amount
26//     currency   → process variable: context.currency
27//     costCenter → process variable: context.costCenter
28//   Output mapping:
29//     approvalLevel → process variable: routing.approvalLevel
30//     autoApprove   → process variable: routing.autoApprove
31
32// ── Calling the Rule Service via REST API ────────────────────────────────────
33// POST /rest/v2/rule-services/po-approval-routing/versions/1.0.0
34{
35  "RuleServices": [
36    {
37      "__name__": "po-approval-routing",
38      "__type__": "RuleService",
39      "amount": 12000,
40      "currency": "EUR",
41      "costCenter": "CC-1234"
42    }
43  ]
44}
45// Response:
46// {
47//   "Result": [{ "approvalLevel": "CFO", "autoApprove": false }]
48// }

1# SAP S/4HANA Business Events — subscription for Build PA trigger
2# Configured in: SAP S/4HANA Cloud → Settings → Event Topics
3
4# Step 1: Create a channel in SAP Event Broker / SAP Event Mesh on BTP
5#   Channel type: SAP S/4HANA Cloud Private / Public Edition
6
7# Step 2: Subscribe to S/4HANA business event topics
8#   Topic pattern (public cloud): sap/s4/beh/purchaserequisition/v1/PurchaseRequisition/Created/v1
9#   Topic pattern (private cloud): sap/s4/beh/<namespace>/PurchaseRequisition/Created/v1
10
11# Step 3: Configure Build PA Event Trigger
12#   Trigger type: Event
13#   Queue name:   BPA_PO_APPROVAL_QUEUE
14#   Event topic:  sap/s4/beh/purchaserequisition/v1/PurchaseRequisition/Created/v1
15
16# ── Example S/4HANA Business Event Payload ───────────────────────────────────
17# {
18#   "specversion": "1.0",
19#   "type": "sap.s4.beh.purchaserequisition.v1.PurchaseRequisition.Created.v1",
20#   "source": "/default/sap.s4.beh/PROD",
21#   "id": "6c2ef5d3-7a4b-4f9e-b123-a1b2c3d4e5f6",
22#   "time": "2025-06-04T10:30:00Z",
23#   "datacontenttype": "application/json",
24#   "data": {
25#     "PurchaseRequisition": "0010001234",
26#     "PurchaseRequisitionType": "NB"
27#   }
28# }
29
30# Step 4: Map event payload to process context variables in Build PA designer
31#   data.PurchaseRequisition  → context.purchaseRequisitionId
32#   data.PurchaseRequisitionType → context.docType
33
34# ── Outbound S/4HANA API Call (from process action step) ─────────────────────
35# Configure a BTP Destination for S/4HANA in Build PA action:
36#   Destination name: S4HANA_CLOUD_PP
37#   Service:          SAP S/4HANA Cloud
38#   Auth:             OAuth2SAMLBearerAssertion (principal propagation)
39#   OData endpoint:   /sap/opu/odata4/sap/api_purchaserequisition_2/srvd_a2x/
40#                     sap/api_purchaserequisition_2/0001/A_PurchaseRequisition

1// SAP CAP — Trigger Build Process Automation from a CAP service event handler
2// Pattern: after a purchase order is confirmed, initiate the approval workflow
3
4const cds = require('@sap/cds')
5
6module.exports = cds.service.impl(async function () {
7  const { PurchaseOrders } = this.entities
8
9  // ── After a new PO is submitted, trigger the approval workflow ──────────────
10  this.after('submitForApproval', PurchaseOrders, async (result, req) => {
11    const po = result
12
13    // Retrieve the Build PA destination (configured in BTP Destination Service)
14    const bpa = await cds.connect.to('BUILD_PROCESS_AUTOMATION')
15
16    try {
17      const instance = await bpa.send({
18        method: 'POST',
19        path: '/public/workflow/rest/v1/workflow-instances',
20        data: {
21          definitionId: 'po-approval-workflow',
22          context: {
23            purchaseOrderId: po.ID,
24            purchaseOrderNumber: po.externalNumber,
25            amount: po.totalAmount,
26            currency: po.currency,
27            costCenter: po.costCenter,
28            vendorName: po.vendor_Name,
29            requestorEmail: req.user.id,
30            requestorName: req.user.attr?.name ?? req.user.id,
31          },
32        },
33      })
34
35      // Store the workflow instance ID on the PO for status tracking
36      await UPDATE(PurchaseOrders, po.ID).with({
37        workflowInstanceId: instance.id,
38        approvalStatus: 'PENDING',
39      })
40
41      req.info(`Approval workflow started: ${instance.id}`)
42    } catch (err) {
43      // Log but do not fail the CAP request — workflow start is async
44      req.warn(`Could not start approval workflow: ${err.message}`)
45    }
46  })
47
48  // ── Webhook: receive workflow completion callback ───────────────────────────
49  // Register a Build PA webhook pointing to this CAP service endpoint
50  // POST /odata/v4/procurement/receiveApprovalResult
51  this.on('receiveApprovalResult', async (req) => {
52    const { purchaseOrderId, decision, decidedBy, comment } = req.data
53
54    await UPDATE(PurchaseOrders, purchaseOrderId).with({
55      approvalStatus: decision === 'APPROVED' ? 'APPROVED' : 'REJECTED',
56      approvedBy: decidedBy,
57      approvalComment: comment,
58      approvalDate: new Date().toISOString(),
59    })
60
61    return { status: 'acknowledged' }
62  })
63})