SAP Joule

1# SAP Joule Booster — BTP CLI commands for programmatic setup
2# Alternative to the Cockpit UI wizard (useful for scripted deployments)
3
4# 1. Install and authenticate the BTP CLI
5btp login --url https://cli.btp.cloud.sap
6
7# 2. List available boosters in your global account
8btp list accounts/booster
9
10# 3. Execute the Joule S/4HANA integration booster
11#    This creates all required BTP destinations and service instances
12btp execute accounts/booster   --name "Integrate SAP Joule with SAP S/4HANA"   --subaccount <subaccount-id>   --parameters '{
13    "s4hanaSystemId": "S4H",
14    "s4hanaHost": "https://<your-s4hana>.s4hana.ondemand.com",
15    "iasHost": "https://<your-tenant>.accounts.ondemand.com",
16    "createDestinations": true
17  }'
18
19# 4. Verify created destinations
20btp list services/instance --subaccount <subaccount-id>
21
22# 5. Check Joule service subscription
23btp get services/subscription   --subaccount <subaccount-id>   --name "joule"
24
25# Expected destinations created by booster:
26# - JOULE_S4HANA_BACKEND     (HTTP + OAuth2SAMLBearerAssertion)
27# - JOULE_IAS_TENANT         (HTTP + ClientCertificate)
28# - SAP_AI_RUNTIME_CORE      (HTTP + OAuth2ClientCredentials → AI Core)
29# - SAP_GENERATIVE_AI_HUB    (HTTP + OAuth2ClientCredentials → Gen AI Hub)
30
31# 6. Verify Joule panel appears in Fiori Launchpad
32# Navigate to S/4HANA Fiori launchpad → confirm Joule button in header

1// Joule Studio — Custom Skill implementation
2// Built with SAP Build Code; deployed to BTP as a Joule extension
3// Consumes only released OData V4 APIs — no direct database access
4
5import type { JouleSkill, JouleIntent, JouleContext, SkillResponse } from '@sap/joule-sdk'
6
7export default class PurchaseOrderStatusSkill implements JouleSkill {
8  // ── Skill descriptor (registered in Joule Studio) ─────────────────────────
9  static descriptor = {
10    id: 'com.company.procurement.po-status',
11    displayName: 'Purchase Order Status',
12    description:
13      'Returns the current status, open quantity, and delivery date for a purchase order. ' +
14      'Triggered by intents such as "show me PO 4500012345" or "what is the delivery status of my order".',
15    supportedIntents: ['purchaseOrderStatus', 'deliveryStatus', 'orderBlocks'],
16    requiredScopes: ['PurchaseOrder.Read'],
17  }
18
19  async execute(intent: JouleIntent, ctx: JouleContext): Promise<SkillResponse> {
20    // ── Extract entities from the user utterance ────────────────────────────
21    const poNumber = intent.entities.purchaseOrderNumber
22      ?? intent.entities.orderNumber
23      ?? ctx.sessionContext?.lastMentionedPO
24
25    if (!poNumber) {
26      return ctx.clarify('Which purchase order number would you like to check?')
27    }
28
29    // ── Call S/4HANA OData V4 API via released API (principal propagation) ──
30    const [header, items] = await Promise.all([
31      ctx.callApi({
32        destination: 'S4HANA_CLOUD',
33        path: '/sap/opu/odata4/sap/api_purchaseorder_2/srvd_a2x/sap/api_purchaseorder_2/0001/A_PurchaseOrder',
34        params: {
35          '$filter': `PurchaseOrder eq '${poNumber}'`,
36          '$select': 'PurchaseOrder,Supplier,DocumentDate,PurchaseOrderStatus,PaymentTerms,TotalNetOrderAmount,TransactionCurrency',
37        },
38      }),
39      ctx.callApi({
40        destination: 'S4HANA_CLOUD',
41        path: '/sap/opu/odata4/sap/api_purchaseorder_2/srvd_a2x/sap/api_purchaseorder_2/0001/A_PurchaseOrderItem',
42        params: {
43          '$filter': `PurchaseOrder eq '${poNumber}'`,
44          '$select': 'PurchaseOrderItem,Material,PurchaseOrderItemText,OrderQuantity,OpenQuantity,DeliveryDate,GoodsReceiptStatus',
45        },
46      }),
47    ])
48
49    if (!header.value?.length) {
50      return ctx.respond({ type: 'text', text: `Purchase order ${poNumber} was not found, or you do not have access to it.` })
51    }
52
53    const po = header.value[0]
54
55    // ── Build structured card response ─────────────────────────────────────
56    return ctx.respond({
57      type: 'card',
58      title: `Purchase Order ${poNumber}`,
59      subtitle: `Supplier: ${po.Supplier} · Status: ${po.PurchaseOrderStatus}`,
60      properties: [
61        { label: 'Document Date', value: po.DocumentDate },
62        { label: 'Net Value', value: `${po.TotalNetOrderAmount} ${po.TransactionCurrency}` },
63        { label: 'Payment Terms', value: po.PaymentTerms },
64      ],
65      table: {
66        columns: ['Item', 'Material', 'Description', 'Ordered', 'Open', 'Delivery Date', 'GR Status'],
67        rows: items.value.map(item => [
68          item.PurchaseOrderItem,
69          item.Material,
70          item.PurchaseOrderItemText,
71          item.OrderQuantity,
72          item.OpenQuantity,
73          item.DeliveryDate,
74          item.GoodsReceiptStatus,
75        ]),
76      },
77      actions: [
78        {
79          label: 'Open in Fiori',
80          deepLink: `/sap/bc/ui2/flp#PurchaseOrder-displayFactSheet?PurchaseOrder=${poNumber}`,
81        },
82        {
83          label: 'Change PO',
84          deepLink: `/sap/bc/ui2/flp#PurchaseOrder-maintain?PurchaseOrder=${poNumber}`,
85        },
86      ],
87    })
88  }
89}

1{
2  "xsappname": "my-joule-extension",
3  "tenant-mode": "dedicated",
4  "description": "XSUAA descriptor for a custom Joule skill extension",
5  "scopes": [
6    {
7      "name": "$XSAPPNAME.PurchaseOrder.Read",
8      "description": "Read access to Purchase Orders via Joule skill",
9      "grant-as-authority-to-apps": ["joule"]
10    },
11    {
12      "name": "$XSAPPNAME.SalesOrder.Read",
13      "description": "Read access to Sales Orders via Joule skill",
14      "grant-as-authority-to-apps": ["joule"]
15    }
16  ],
17  "role-templates": [
18    {
19      "name": "JouleSkillUser",
20      "description": "Users who can invoke custom Joule skills",
21      "scope-references": [
22        "$XSAPPNAME.PurchaseOrder.Read",
23        "$XSAPPNAME.SalesOrder.Read"
24      ]
25    }
26  ],
27  "role-collections": [
28    {
29      "name": "CustomJouleSkillUser",
30      "description": "Assigned to all users who should have access to custom Joule skills",
31      "role-template-references": [
32        "$XSAPPNAME.JouleSkillUser"
33      ]
34    }
35  ],
36  "oauth2-configuration": {
37    "token-validity": 3600,
38    "redirect-uris": ["https://<joule-studio-host>/callback"],
39    "credential-types": ["binding-secret"]
40  }
41}

1// SAP Datasphere — Joule AI Copilot integration (Roadmap — not yet GA)
2// When available, allows natural language data exploration in Datasphere
3
4// ── Current GA capability: SAC Smart Predict (separate from Joule) ────────────
5// The following represents the announced Joule integration direction
6
7// Joule in Datasphere (Roadmap) — expected natural language queries:
8// User: "Show me total revenue by region for Q1 2025"
9// Joule: generates a SAC Story or Datasphere analytic view
10//        based on the authorised data entities
11
12// ── Current GA: Datasphere Python SDK for programmatic data access ────────────
13// This is a current capability — NOT Joule, but shows the data layer
14
15const { HanaClient } = require('@sap/hana-client')
16const { DatasphereClient } = require('@sap/datasphere-client')
17
18async function queryRevenueByRegion(client, options = {}) {
19  const { year = 2025, quarter = 'Q1' } = options
20
21  // Datasphere exposes data via OData V4 and SQL
22  // Authorisation enforced by Datasphere data access controls
23  const result = await client.query(`
24    SELECT
25      REGION,
26      SUM(NET_REVENUE) AS TOTAL_REVENUE,
27      CURRENCY
28    FROM "FINANCE"."REVENUE_BY_REGION_VIEW"
29    WHERE FISCAL_YEAR = '${year}'
30      AND FISCAL_QUARTER = '${quarter}'
31    GROUP BY REGION, CURRENCY
32    ORDER BY TOTAL_REVENUE DESC
33  `)
34
35  return result.rows
36}
37
38// ── Joule integration with Datasphere (when available via roadmap) ────────────
39// Expected: Joule skill registered in Datasphere tenant
40// User asks: "What is the revenue breakdown for Q1 2025?"
41// Joule maps intent → Datasphere OData entity → returns card response
42// All data access governed by Datasphere data access controls