Setting up Document Grounding for Build Workzone Advanced
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-grounding-setup-guide/ba-p/13739501
Document types supported for SAP Build Workzone, 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 Work Zone Advanced
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 Work Zone Advanced
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 → 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 Setup for Document Grounding, If Unified Joule Already Exists: Adding Document Grounding to an existing Joule setup
Navigate to your Subaccount.
Go to Entitlements → Add.
Search for and add Document Grounding.
4.b Setup for Document Grounding, If Setting Up Unified Joule for the First Time: Adding Document Grounding during a new Joule setup
Create a new Subaccount.
In the Subaccount Overview page, enable Cloud Foundry.
After Cloud Foundry is enabled, return to the Overview page and create a new space.
Navigate to Trust Configuration → Establish Trust to set up trust with Cloud Identity Services (CIS/IAS).
Go to Entitlements → Edit → Add Service Plans, and add service plans for both Joule and Document Grounding.
From your Global Account, open Boosters → select Setting Up Joule Booster → click Start.
Choose your subaccount and proceed through the steps by selecting Next Step. You do not need to select any products, as this is a new setup without existing integrations.
After completion of Step 4.a OR 4.b proceed to create a Destination
4.c 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 BWZ Advanced -> 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.d 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.e 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 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 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
Ask Joule questions related to your Work Zone 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
Setting up Document Grounding for Build Workzone AdvancedDocument 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-grounding-setup-guide/ba-p/13739501Document types supported for SAP Build Workzone, 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 StepsStep 1: Enable Document Grounding capabilities in SAP Build Work Zone, Advanced EditionStep 2: Enable Document Grounding for Workspaces & Sub-Workspaces in Work Zone AdvancedStep 3: Explore Content Locations — Blogs, Wikis, and Documents for GroundingStep 4: Use an Existing Joule Subaccount or Create a New One to Set Up Document GroundingStep 5: Create Certificate and RSA Key FilesStep 6: Run cURL commands to setup Document Grounding pipelinesStep 7: Verify and Test JouleStep 8: Appendix Step 1: Enable Document Grounding capabilities in SAP Build Work Zone, Advanced EditionNavigate 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: dgkey123456OAuth Client Secret: dgsecretabcdefNavigate to Administration Console → Feature Enablement → FeaturesEnable 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 Work Zone AdvancedWorkspaces 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 SaveNote: 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 → Administration Console → Workspaces. Step 3: Explore Content Locations — Blogs, Wikis, and Documents for GroundingDocuments 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 GroundingDocument 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 Setup for Document Grounding, If Unified Joule Already Exists: Adding Document Grounding to an existing Joule setupNavigate to your Subaccount.Go to Entitlements → Add.Search for and add Document Grounding. 4.b Setup for Document Grounding, If Setting Up Unified Joule for the First Time: Adding Document Grounding during a new Joule setupCreate a new Subaccount.In the Subaccount Overview page, enable Cloud Foundry.After Cloud Foundry is enabled, return to the Overview page and create a new space.Navigate to Trust Configuration → Establish Trust to set up trust with Cloud Identity Services (CIS/IAS).Go to Entitlements → Edit → Add Service Plans, and add service plans for both Joule and Document Grounding.From your Global Account, open Boosters → select Setting Up Joule Booster → click Start.Choose your subaccount and proceed through the steps by selecting Next Step. You do not need to select any products, as this is a new setup without existing integrations. After completion of Step 4.a OR 4.b proceed to create a Destination 4.c Create DestinationIn your Joule Subaccount, navigate to Destinations → Create → From Scratch. Enter a Name for the destination. Add the values provided belowName: HGDGBWZ924 (You can have any name)PropertyValueURLThe URL is https://<DWS URL>/api/v1/dg-pipeline/metadataCheck DWS URL in the BWZ Advanced -> Admin Console -> OverviewE.g: https://abcdef.eu10-1.dws.workzone.ondemand.com/api/v1/dg-pipeline/metadataTypeHTTPProxy TypeInternetAuthenticationOAuth2ClientCredentialsClient IDEnter the value of the OAuth client Key from BWZ Advanced created in Step 1OAuth Client Key: dgkey123456Client SecretEnter the value of the OAuth client Secret from BWZ Advanced created in Step 1OAuth Client Secret: dgsecretabcdefToken Service URL TypeDedicatedToken Service URLEnter your <DWS URL>/api/v1/auth/tokenE.g: https://abcdef.eu10-1.dws.workzone.ondemand.com/api/v1/auth/tokenCheck DWS URL in the BWZ Advanced -> Admin Console -> OverviewAdditional Properties(Click New Property and manually add these properties to the destination)HTML5.DynamicDestinationtrueSetXForwardedHeadersfalseHTML5.SetXForwardedHeadersfalse4.d Create Document Grounding Service InstanceIn your Joule Subaccount, go to Service Marketplace → Document Grounding → Create.Select Runtime Environment: OtherEnter an Instance Name: for example, groundingcliClick CreateCreate a Service Binding for the Document Grounding InstanceIn your Subaccount, navigate to Instances & Subscriptions → InstancesSelect your Document Grounding Service Instance, then proceed to “Create Service Binding”Enter a Binding Name, for example: groundingkey, and click CreateCopy the mTLS Document Grounding Service Binding URL (MTLS URL) for later use.E.g: https://mtls.rage.c-1111.kyma.ondemand.com4.e Create Cloud Identity Services InstanceIn your Subaccount, navigate to Services → Service Marketplace → Cloud Identity Services → Create.Plan: applicationRuntime Environment: OtherInstance Name: groundingCISThen 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 → InstancesSelect 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 FilesYou’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:clientidauthorization_endpointThen, update the authorization_endpoint by replacing /oauth2/authorize with /oauth2/tokenE.g: clientid: aaa-bbb-ccc-ddd-eeeE.g: authorization_endpoint: https://abc2wxyz.accounts.ondemand.com/oauth2/tokenCopy 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 belowSave the two certificates into a single file and save it as a .crt file.Example: DocumentGrounding.crtSave the RSA private key as a .key file.Example: DocumentGrounding.key Step 6: Run cURL commands to setup Document Grounding pipelinesIn 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 content and the Document Grounding service.6.a Install Bruno and Create a CollectionInstall Bruno: Download and install the Bruno API Client.Open Bruno and click Create CollectionProvide 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.comDocument Grounding Service Binding URL (mTLS): mtls.rage.c-1111.kyma.ondemand.comIn Bruno, perform the following steps:Select your collection (DGcollection).Go to Client Certificates.For the Domain, enter your IAS URL — abc2wxyz.accounts.ondemand.comSelect 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.comCertificate File: DocumentGrounding.crtKey File: DocumentGrounding.keyClick Add to save the configuration.6.b Create a Bearer TokenIn 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 TokenURL: Your CIS URL followed by /oauth2/tokenExample: https://abc2wxyz.accounts.ondemand.com/oauth2/tokenClick Create.Add Parametersclient_id: (from your Cloud Identity Services binding file cisSK.json) Example: aaa-bbb-ccc-ddd-eeegrant_type: client_credentialsAdd Headerscontent-type: application/x-www-form-urlencodedaccept: application/jsonChange 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 PipelineIn Bruno, click New Request under your DGcollection.Method: POSTURL: Your mTLS URL from the Document Grounding Service Binding, followed by /pipeline/api/v1/pipelineExample: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipelineClick Create.Add Headerscontent-type: application/jsonAuthorization: Bearer <your_access_token>Example: Bearer eyJqa3UiOiJ…………….odHRwczovL2F6cjJpeAdd BodyChange 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 requestIf 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 workspace. Copy the pipelineId from the response (E.g: pipelineId: aa11-bb22-cc33-dd44) Setup CompleteYour 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 JouleNow 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/jouleBefore 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 Work Zone 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: AppendixAfter 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 PipelinesUse 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 PipelinesEnter the MTLS URL followed by /pipeline/api/v1/pipelineE.g: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipelineAdd headers, save, and click → (Send😞 You will see all existing pipelinesaccept: application/jsonAuthorization: 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 token8.b. Delete a PipelineUse 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-dd44Add headers, save, and click → (Send):content-type: application/jsonAuthorization: Bearer <access_token>Once executed, the pipeline with the given ID will be deleted successfully8.c. Trigger a PipelineUse 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 PipelineEnter your mTLS URL followed by /pipeline/api/v1/pipeline/triggerExample: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/triggerAdd Body{
“pipelineId”: “aa11-bb22-cc33-dd44”,
“metadataOnly”: false
}Add Headers, save, and click → (Send):accept: application/jsonAuthorization: Bearer <access_token>Once executed, the pipeline will start executing.8.d. Check Pipeline Execution/Grounding Status of the documentsTo 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>/documentsExample: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/documentsAdd Headers, save, and click → (Send):accept: application/jsonAuthorization: Bearer <access_token>8.e. Check Pipeline Status & Total executionsReplicate 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 executionsExample: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/statusExample: https://mtls.rage.c-1111.kyma.ondemand.com/pipeline/api/v1/pipeline/aa11-bb22-cc33-dd44/executions Read More Technology Blog Posts by SAP articles
#SAP
#SAPTechnologyblog
![How to fix janky legacy codebases with Abbey Perini [Podcast #196]](https://i3.ytimg.com/vi/rgt5GPFgryI/hqdefault.jpg)
