Joule - Document Grounding with SAP Build Work Zon...

KumarG9 · ‎2025 Nov 07

Setting up Document Grounding for SAP Build Work Zone, advanced edition

Document grounding (SAP’s implementation of RAG) is a foundational Joule capability which can provide more comprehensive responses by drawing from business documents located in SAP and third-party repositories.

Grounding is a service designed to handle data-related tasks, such as grounding and retrieval, using vector databases. It provides specialized data retrieval through these databases, grounding the retrieval process with your own external and context-relevant data. Grounding combines generative AI capabilities with the ability to use real-time, precise data to improve decision-making and business operations for specific AI-driven business solutions.

Grounding converts user provided documents into vector representations which are stored as a database. The indexing pipeline preprocesses unstructured and semi structured data into chunks and embeddings and the retrieval pipeline takes incoming user queries and converts them into vector representations. The query vectors are used to search the database and retrieval relevant information.

Prerequisites: Before triggering the setup process, make sure that you’ve purchased the AI Unit SKU (8019164) OR AI Units SKU - 8018592. After you’ve done so, the entitlements for document grounding are automatically added to your global account. Validate if you can see the entitlement "Document Grounding" in Global Account -> Service Assignment area.

Document Grounding now supports two authentication mechanisms. Please check the Configure Access from SAP BTP before you start your setup.

This blog focuses on setting up Document Grounding with SAP Build Work Zone, advanced edition. If you need to setup Document Grounding for Microsoft Sharepoint, please refer to this blog written by Nagesh: https://community.sap.com/t5/technology-blog-posts-by-sap/joule-getting-started-with-document-ground...

Document types supported for SAP Build Work Zone, advanced edition: Blog posts, DOCX, JPEG, JPG, JSON, Knowledge base articles, PDF, PNG, PPTX, TIFF, TXT, Wiki pages (https://help.sap.com/docs/joule/integrating-joule-with-sap/set-up-document-grounding)

Setup Steps

Step 1: Enable Document Grounding capabilities in SAP Build Work Zone, advanced Edition

Step 2: Enable Document Grounding for Workspaces & Sub-Workspaces in SAP Build Work Zone, advanced Edition

Step 3: Explore Content Locations — Blogs, Wikis, and Documents for Grounding

Step 4: Use an Existing Joule Subaccount or Create a New One to Set Up Document Grounding

Step 5: Create Certificate and RSA Key Files

Step 6: Run cURL commands to setup Document Grounding pipelines

Step 7: Verify and Test Joule

Step 8: Appendix

Step 1: Enable Document Grounding capabilities in SAP Build Work Zone, advanced Edition

Navigate to SAP Build Work Zone, advanced Edition → App Finder → Administration Console.

In the Administration Console, go to External Integrations → OAuth Clients, and click Add OAuth Client.

Enter a Name and an Integration URL for the OAuth client.

Note: The Integration URL is not validated, so you can enter any placeholder value.

After saving the OAuth Client, click View to display the Client Key and Client Secret.
Copy these values. You will need them later during the integration setup.

OAuth Client Key: dgkey123456

OAuth Client Secret: dgsecretabcdef

Navigate to Administration Console → Feature Enablement → Features
Enable the Document Grounding Integration feature, and then select the OAuth Client you created in the previous step.

From the Administration Console → Overview page, copy the DWS URL.
For example: https://abcdef.eu10-1.dws.workzone.ondemand.com

Step 2: Enable Document Grounding for Workspaces & Sub-Workspaces in SAP Build Work Zone, advanced Edition

Workspaces and Sub-Workspaces both need to be enabled for Document Grounding. Selecting only the "Workspace" does not automatically enable Document Grounding in "Sub-Workspaces"

Navigate to SAP Build Work Zone, advanced Edition → Workspaces → New Workspace, and select Public Workspace.

Note: Document Grounding is supported only for Public Workspaces. If you have an existing Private Workspace, you can convert it to a Public Workspace from the Workspace Admin Settings.

In the workspace, navigate to Workspace Admin Settings → Edit Workspace.

Select the checkbox for Document Grounding to enable grounding for the workspace and then click Save

Note: If your setup includes a Sub-Workspace, make sure to enable Document Grounding there as well.
Enabling it at the main Workspace level does not automatically activate it for any Sub-Workspaces.

You can also manage Document Grounding across all workspaces by navigating to SAP Build Work Zone, advanced Edition → Administration Console → Workspaces.

Step 3: Explore Content Locations — Blogs, Wikis, and Documents for Grounding

Documents in SAP Build Work Zone, advanced edition can be uploaded as individual files or referenced from other content areas such as Blogs, Wikis, and Knowledge Base articles.
In these cases, the entire page or article is treated as grounding content. All such sources are indexed and leveraged by Joule to provide accurate, context-aware responses based on your organization’s information.

3.a Content / Files:
In your workspace, go to Content to view existing files or upload new documents that will be used for document grounding.

3.b Knowledge Base:
In your workspace, go to Knowledge Base to create and manage knowledge base articles that can be used for document grounding.

3.c Blog or Wiki:
In the Content area, click Create to add a new Blog or Wiki page. These pages will be indexed and used as grounding content.

Step 4: Use an Existing Joule Subaccount or Create a New One to Set Up Document Grounding

Document Grounding must be configured in the same subaccount where Joule (or Unified Joule) is enabled.
Select the subaccount where Joule is already set up and verify that it is hosted in a supported region.

AWS: ap10 – Australia (Sydney), ap11 – Asia Pacific (Singapore), eu10 – Europe (Frankfurt), eu11 – Europe (Frankfurt, EU Access), jp10 – Japan (Tokyo), us10 – US East (VA)
Google Cloud: ap30 – Australia (Sydney), eu30 – Europe (Frankfurt), us30 – US Central (IA)
Microsoft Azure: ap20 – Australia (Sydney), eu20 – Europe (Netherlands), us21 – US East (VA)

For the latest list of supported regions, refer to the official documentation: Supported Regions for Document Grounding

4.a Scenarios for Setting Up Document Grounding

Depending on how SAP Build Work Zone is configured in relation to your Joule formation, there are four possible setup paths. As mentioned earlier, the Document Grounding service must always be added to the Joule subaccount.
However, depending on your environment, SAP Build Work Zone, advanced edition may be deployed in the same subaccount or in a different one.
The following options outline the supported configurations.

4.a.1 – Unified Joule Already Exists with SAP Build Work Zone, standard Edition

You already have Joule configured, and SAP Build Work Zone, standard Edition is part of the same Joule formation.
In this case:

Joule remains integrated with SAP Build Work Zone, standard Edition (the Joule icon will only appear there).
You can still use SAP Build Work Zone, advanced edition for Document Grounding, but it won’t display the Joule icon because only one system instance can be part of a Joule formation.

Steps

Navigate to your Joule subaccount in BTP Cockpit.
Go to Entitlements → Add.
Search for and add the “Document Grounding” service plan.

4.a.2 – Unified Joule Already Exists with SAP Build Work Zone, advanced edition

You already have Joule set up and integrated with SAP Build Work Zone, advanced Edition.
In this scenario, you can directly enable Document Grounding in the same subaccount.

Steps

Navigate to your Joule subaccount.
Go to Entitlements → Add.
Search for and add the “Document Grounding” service plan.

Reference (optional): For more details on Setting up Unified Joule for scenarios 4.a.3 and 4.a.4 below you can refer to the SAP Community Blog:
Joule End-to-End Setup Guide for All Lines of Business – Unified Approach

4.a.3 – Setting Up Unified Joule for the First Time and Connecting an Existing SAP Build Work Zone, advanced edition

You are enabling Unified Joule for the first time and want to use an existing SAP Build Work Zone, advanced Edition that resides in a different subaccount.
In this setup, the Joule subaccount will host Joule and Document Grounding services only—no Work Zone Standard—while your existing Work Zone Advanced Edition will be linked to Joule during the booster configuration.

Steps

Create a new subaccount in your global account to host Joule.
Navigate to Trust Configuration → Establish Trust and set up trust with Cloud Identity Services (CIS / IAS).
Go to Entitlements → Edit → Add Service Plans, and add:

Joule
Document Grounding

From your Global Account, open Boosters → Set Up Joule, and click Start.
When prompted, select your new Joule subaccount and proceed through the booster steps.
In the booster flow, choose to connect your existing SAP Build Work Zone Advanced Edition tenant to the Joule formation.
Complete the booster to finish the configuration. Once successful, Joule will be active in the Joule subaccount and integrated with your existing Work Zone Advanced Edition tenant.

4.a.4 – Setting Up Unified Joule for the First Time (SAP Build Work Zone, advanced edition in the Same Joule Subaccount)

You are setting up Unified Joule for the first time and intend to deploy SAP Build Work Zone, advanced Edition directly within the same Joule subaccount (rather than linking an existing external Work Zone tenant).
This configuration keeps all related services — Joule, Document Grounding, and Work Zone Advanced — together in one managed environment.

Steps

Create a new subaccount in your BTP Cockpit to host Joule and Work Zone Advanced.
Navigate to Trust Configuration → Establish Trust, and set up trust with Cloud Identity Services (CIS / IAS).
Go to Entitlements → Edit → Add Service Plans, and add the following:

Joule
SAP Build Work Zone – Advanced Edition
(add both advanced and advanced (application) service plans)
Document Grounding

From your Global Account, open Boosters → Get Started with SAP Build Work Zone, advanced Edition, and complete the booster to provision the Work Zone Advanced tenant.
Refer to the official help documentation for detailed guidance:
Onboarding to SAP Build Work Zone Advanced Edition
After Work Zone Advanced is successfully provisioned, open Boosters → Set Up Joule, and click Start.
Select your newly created subaccount and proceed through the Joule booster steps.
When prompted, choose SAP Build Work Zone, advanced Edition to integrate it with Joule.

Optional Steps

If you would like to enable Joule in SAP Build Work Zone, advanced edition, refer to the following blog for detailed guidance:
🔗 Joule is Now Integrated into SAP Build Work Zone, Advanced Edition

If you would like to enable Joule in SAP Build Work Zone, standard edition, follow the steps described in this blog:
🔗 Activate Joule with SAP Build Work Zone and SAP Mobile Start

After completion of Step 4.a.1 or 4.a.2 or 4.a.3 or 4.a.4 proceed to create a Destination

4.b Create Destination

In your Joule Subaccount, navigate to Destinations → Create → From Scratch. Enter a Name for the destination. Add the values provided below

Name: HGDGBWZ924 (You can have any name)

Property	Value
URL	The URL is https://<DWS URL>/api/v1/dg-pipeline/metadata Check DWS URL in the SAP Build Work Zone, advanced edition -> Admin Console -> Overview E.g: https://abcdef.eu10-1.dws.workzone.ondemand.com/api/v1/dg-pipeline/metadata
Type	HTTP
Proxy Type	Internet
Authentication	OAuth2ClientCredentials
Client ID	Enter the value of the OAuth client Key from BWZ Advanced created in Step 1 OAuth Client Key: dgkey123456
Client Secret	Enter the value of the OAuth client Secret from BWZ Advanced created in Step 1 OAuth Client Secret: dgsecretabcdef
Token Service URL Type	Dedicated
Token Service URL	Enter your <DWS URL>/api/v1/auth/token E.g: https://abcdef.eu10-1.dws.workzone.ondemand.com/api/v1/auth/token Check DWS URL in the BWZ Advanced -> Admin Console -> Overview
Additional Properties	(Click New Property and manually add these properties to the destination)
HTML5.DynamicDestination	true
SetXForwardedHeaders	false
HTML5.SetXForwardedHeaders	false

4.c Create Document Grounding Service Instance

In your Joule Subaccount, go to Service Marketplace → Document Grounding → Create.

Select Runtime Environment: Other
Enter an Instance Name: for example, groundingcli
Click Create

Create a Service Binding for the Document Grounding Instance

In your Subaccount, navigate to Instances & Subscriptions → Instances
Select your Document Grounding Service Instance, then proceed to "Create Service Binding"

Enter a Binding Name, for example: groundingkey, and click Create

Copy the mTLS Document Grounding Service Binding URL (MTLS URL) for later use.

E.g: https://mtls.rage.c-1111.kyma.ondemand.com

4.d Create Cloud Identity Services Instance

In your Subaccount, navigate to Services → Service Marketplace → Cloud Identity Services → Create.

Plan: application
Runtime Environment: Other
Instance Name: groundingCIS

Then click Next (do not click Create yet).

In the Parameters section, enter the following JSON — replacing <doc-grounding-instance-name> with the Document Grounding Service Instance Name you created earlier (E.g: groundingcli) — and then click Create.

{
   "consumed-services":[
      {
         "service-instance-name":"<doc-grounding-instance-name>"
      }
   ]
}

In your Subaccount, navigate to Instances & Subscriptions → Instances
Select your Cloud Identity Services Instance, then proceed to "Create Service Binding"

Enter a Service Binding Name, for example: cisSK, and provide the following parameters. Then click Create

{
    "credential-type": "X509_GENERATED",
    "validity": 365,
    "validity-type": "DAYS"
}

Download the Service Binding file for the Cloud Identity Services instance.

Step 5: Create Certificate and RSA Key Files

You’ll now create two files required for secure communication between Document Grounding and Cloud Identity Services (CIS).

Open the CIS Service Binding file and copy the following values:

clientid
authorization_endpoint

Then, update the authorization_endpoint by replacing /oauth2/authorize with /oauth2/token

E.g: clientid: aaa-bbb-ccc-ddd-eee

E.g: authorization_endpoint: https://abc2wxyz.accounts.ondemand.com/oauth2/token

Copy the certificates (there are 2 certificates) from the CIS Service Binding file (Starting with "----BEGIN CERTIFICATE---- to ----End CERTIFICATE----" and RSA key (Starting with ----BEGIN RSA PRIVATE KEY---- to ----END RSA PRIVATE KEY----) to VSCode (or Notepad++)

In VSCode press Ctrl+H and enter "\n" in Find and "," in Replace. Select "Match Case" and click "Replace all"

After that enter "," in Find and "\n" in Replace. Select "Match Case" and "Use Regular Expression" and click "Replace all"

You will see "2 Certificates" and "1 RSA Key" similar to the screenshot below

Save the two certificates into a single file and save it as a .crt file.
Example: DocumentGrounding.crt
Save the RSA private key as a .key file.
Example: DocumentGrounding.key

Step 6: Run cURL commands to setup Document Grounding pipelines

In this step, you’ll use Bruno (or any API client such as Postman) to execute cURL commands that create and configure Document Grounding pipelines in your Joule subaccount.
These pipelines establish the connection between SAP Build Work Zone, advanced edition content and the Document Grounding service.

6.a Install Bruno and Create a Collection

Install Bruno: Download and install the Bruno API Client.

Open Bruno and click Create Collection

Provide a Name for the collection, for example: DGcollection, choose a Location to save it, and click Create.

Before proceeding, ensure you have the following two URLs ready:

IAS URL (of Joule Subaccount): https://abc2wxyz.accounts.ondemand.com
Document Grounding Service Binding URL (mTLS): mtls.rage.c-1111.kyma.ondemand.com

In Bruno, perform the following steps:

Select your collection (DGcollection).
Go to Client Certificates.
For the Domain, enter your IAS URL — abc2wxyz.accounts.ondemand.com
Select the Certificate File (DocumentGrounding.crt) and the Key File (DocumentGrounding.key).
Click Add to save the configuration.

Repeat the same process for the Document Grounding Service Binding URL:

Domain: mtls.rage.c-1111.kyma.ondemand.com
Certificate File: DocumentGrounding.crt
Key File: DocumentGrounding.key

Click Add to save the configuration.

6.b Create a Bearer Token

In this step, you’ll generate an OAuth 2.0 bearer token to authenticate subsequent API calls for creating Document Grounding pipelines.

In Bruno, select your collection (DGcollection).
Click New Request and enter:
- Name: Get Bearer Token
- URL: Your CIS URL followed by /oauth2/token
  Example: https://abc2wxyz.accounts.ondemand.com/oauth2/token
Click Create.

Add Parameters

client_id: (from your Cloud Identity Services binding file cisSK.json) Example: aaa-bbb-ccc-ddd-eee
grant_type: client_credentials

Add Headers

content-type: application/x-www-form-urlencoded
accept: application/json

Change the method from GET to POST, click Save, then click the → (Send) button.

You will receive a response similar to the example below.
Copy the access_token, as it will be used in the next step to create the Document Grounding Pipeline

{
  "access_token": "xyzxyzxyzxyzxyzxyzxyz",
  "token_type": "Bearer",
  "expires_in": 3600
}

💡Tip: The bearer token is temporary — it expires after the duration shown in expires_in (in seconds).
You’ll need to generate a new access token each time you perform Document Grounding operations in the future (for example, to create, update, or refresh pipelines)

6.c Create a Pipeline

In Bruno, click New Request under your DGcollection.

Method: POST
URL: Your mTLS URL from the Document Grounding Service Binding, followed by /pipeline/api/v1/pipeline
Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline
Click Create.

Add Headers

content-type: application/json
Authorization: Bearer <your_access_token>
Example: Bearer eyJqa3UiOiJ…………….odHRwczovL2F6cjJpe

Add Body

Change the Body type to JSON and paste the following:
The destination is the name of the "Destination" created in your Joule subaccount" (Step 4.c)

{
  "type": "WorkZone",
  "metadata": {
    "destination": "HGDGBWZ924"
  }
}

Click Save, then click → (Send) to execute the request

If the request is successful, the response will display a pipelineId.
This confirms that the Document Grounding Pipeline has been successfully created and linked to your SAP Build Work Zone, advanced edition workspace. Copy the pipelineId from the response (E.g: pipelineId: aa11-bb22-cc33-dd44)

Setup Complete

Your Document Grounding setup is now complete.
All configurations between SAP Build Work Zone, advanced edition, Joule, and Document Grounding have been successfully established.

Beyond the initial setup, you can perform additional operations using Bruno or cURL, such as:

Get all pipelines – retrieve a list of existing Document Grounding pipelines.
Delete a pipeline – remove an inactive or obsolete pipeline.
Trigger a pipeline – manually refresh or re-index workspace content.

These advanced operations will be detailed in the Appendix section in the end.

Step 7: Verify and Test Joule

Now that the setup is complete, it’s time to test Joule. If you already have Unified Joule set up, you can launch Joule directly from the application. (E.g: Successfactors, Ariba, S/4 Private Cloud, IBP etc.)

If this is a new setup, launch Joule by navigating to Subaccounts → Instances & Subscriptions → Joule Instance, click the instance name to open it, and when you see “The service is up and running,” copy the URL and append /joule — for example: https://rigunifiedjoule-test-sge254ddd.eu10.sapdas.cloud.sap/joule

Before launching Joule, create a Role Collection under Subaccount → Security → Role Collections, add the end_user role, assign the role collection to your user in Subaccount → Security → Users.

Ask Joule questions related to your SAP Build Work Zone, advanced edition content (files, wikis, blogs, or knowledge base articles) that were included in the grounding configuration. If everything is working correctly, Joule should return context-aware answers derived from your organization’s grounded documents.

Step 8: Appendix

After completing the setup, you can manage and maintain your Document Grounding pipelines using additional API operations in Bruno or cURL. These include viewing all existing pipelines, deleting or re-creating a pipeline, manually triggering executions, and checking their status.

8.a. Get All Pipelines

Use a GET request to retrieve all existing Document Grounding pipelines in your Joule subaccount. This allows you to verify which pipelines are active and view their associated destinations.

In Bruno: Select your collection (DGcollection) → click New Request → name it Get All Pipelines
Enter the MTLS URL followed by /pipeline/api/v1/pipeline
E.g: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline

Add headers, save, and click → (Send😞 You will see all existing pipelines
accept: application/json
Authorization: Bearer <access_token>

Note: You need to get a new Bearer token if the previous token is expired. Check step 6.2 to get a new Bearer token

8.b. Delete a Pipeline

Use a DELETE request with the specific pipelineId to remove a pipeline that’s no longer needed or was incorrectly configured.

In Bruno: Select your collection (DGcollection) → click New Request → name it Delete Pipeline.

Enter your mTLS URL followed by /pipeline/api/v1/pipeline/<pipelineId>
Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44

Add headers, save, and click → (Send):
content-type: application/json
Authorization: Bearer <access_token>
Once executed, the pipeline with the given ID will be deleted successfully

8.c. Trigger a Pipeline

Use a POST request to manually trigger a pipeline execution. This can reindex or update metadata for all grounded documents in the selected pipeline.

In Bruno: Select your collection (DGcollection) → click New Request → name it Trigger Pipeline
Enter your mTLS URL followed by /pipeline/api/v1/pipeline/trigger
Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/trigger

Add Body

{
  "pipelineId": "aa11-bb22-cc33-dd44",
  "metadataOnly": false
}

Add Headers, save, and click → (Send):
accept: application/json
Authorization: Bearer <access_token>

Once executed, the pipeline will start executing.

8.d. Check Pipeline Execution/Grounding Status of the documents

To check status of individual documents (files, wiki, knowledge article etc.)

In Bruno: Select your collection (DGcollection) → click New Request → name it Check Grounding Status.
URL: https://<your-mtls-url>/pipeline/api/v1/pipeline/<PipelineID>/documents
Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/documents

Add Headers, save, and click → (Send):
accept: application/json
Authorization: Bearer <access_token>

8.e. Check Pipeline Status & Total executions

Replicate steps from 8.d and use "status" and "executions" instead of "documents" in the URL. You will get final status or total number of executions of the pipeline

URL: https://<your-mtls-url>/pipeline/api/v1/pipeline/<PipelineID>/status OR executions

Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/status
Example: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/executions