Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
nageshcaparthy
Product and Topic Expert
Product and Topic Expert
31,639
  • SAP Managed Tags:

We are excited to introduce the latest update to our SAP AI capabilities and add a new feature to our SAP Business. While we have been working on SAP Business AI and the Joule copilot service, there is always a question: Can we have more 😊? Well, this is a fair ask, and this is where SAP has been focusing.

Here we come with the new capability of RAG via the Document Grounding service, which can be activated across your LOB services where Joule is supported. I will touch on each of these topics and discuss how to set it up.

What is Document Grounding?

While Large Language Models (LLMs) excel at understanding and generating human-like text, they often lack the specificity and context of business data. To unleash the potential for LLMs, in particular, in conversational use cases, providing the right context to ground LLMs in business reality is essential to make the generated answers relevant (factually correct), reliable (based on up-to-date information), and responsible (trace factual errors to the corresponding data source). We use the Retrieval-Augmented Generation (RAG) technique to optimize the output of a large language model with information that is use-case-specific and not available as a training data source for LLMs.

AI-assisted document grounding lets SAP customers use their own specific unstructured or semi-structured documents to provide answers to user questions in Joule. Customers can connect their document repositories via a Microsoft SharePoint site.

Let us look at the details.

Pro Tip: Always refer to the official SAP Help Page for the latest updates on the setup process.

This blog post is a series of Joule setup guides. In case you are following this, please refer to my previous blogs:

SAP BusinessAI – Overview for all !!! 

[SAP BTP Onboarding Series] Joule – Getting Started with Joule and SAP SuccessFactors

[SAP BTP Onboarding Series] Joule with SFSF – Common Setup Issues

Joule for SAP S/4HANA Cloud Private Edition - A Comprehensive Setup Guide

Pre-requisites:

  • Active Joule setup. In case you are trying to activate Joule, you can refer to this official page for a list of Generally Available Joule integration scenarios
  • Microsoft SharePoint Administrator Access which is your Data Repository
  • SAP BTP Administrator and Subaccount Administrator
  • AI Units SKU – 8018592
  • GitBash CLI / Bruno (recommend) for Windows and MAC default terminal should work for cURL commands
  • Cloud Foundry and Space should be created in your SAP BTP Subaccount based on Joule + LOB scenarios

A quick check on Document Grounding Support

  • Grounding is supported by up to 2,000 documents
  • Document type: 
    • HTML (Static)
    • JPEG
    • JPG
    • Microsoft Word
    • PDF
    • PNG
    • TIFF
  • Document Content: Plain Text (Tables and images embedded in documents aren’t currently supported.)
  • Language: English and other languages from the Documents 
  • Content Refresh: SharePoint content is updated once every day, meaning any changes to the PDF or Word files in the SharePoint location, the content is refreshed once every day approximately at the time of pipeline setup and we do not have manual refresh at this time
  • MS SharePoint: You can select a required Folder in your SharePoint

Commercials & Pricing:

This link provides information on how Document Grounding is charged and the Estimator Tool. For additional terms and conditions, refer to the AI Services and AI Unit supplemental terms and conditions.

Technical Architecture

nageshcaparthy_0-1732004755901.png

Image 0

Setup Process (as per LOB):

  1. Setup your Subaccount with required Entitlements (Grounding Service will be visible in your BTP Global Account if you have the license for AI Units)
  2. Validate the Cloud Identity setup with your LOB and use the same Cloud Identity to Establish Trust with your Subaccount
  3. Setup Joule using the booster and complete the work zone setup if you are using the full functionalities of the Joule Base version
  4. Use the LOB Role-Based Permissions to grant Joule Access (if any)
  5. Complete the Job Sync in Cloud Identity (if any)

Let us take a look at the Activation Process for Document Grounding :

6. Prepare SharePoint Integration (optional)

6.1 Create SharePoint Site (you can re-use an existing site if you have one, and grant access to specific folders)

6.2 Create a Group and a Technical User (existing can be reused but should not have “2FA for this user”)

6.3 Register an Application, Generate a Client Secret, & Expose the application using web API

6.4 Validate the SharePoint access with the Technical User

7. Activate Grounding Service in BTP Subaccount & Create a Service Key

7.1 Configure User Authentication

  • Create a Cloud Identity Service Instance and a Service Key
  • Copy / Edit the Certificate values to support *.crt and *.key values
  • Create Destination in SAP BTP Subaccount

8. Run a cURL command for POST and GET using Bruno API Client

9. Joule Testing

================================================================================

We continue from step 6, assuming that the Joule service is activated and you have followed the previous blogs.

To run this setup, you will need the following Values: Please capture the details as we proceed through the setup process. 

  • Microsoft Entra Tenant ID (Image1)
  • MS SharePoint Site Name (Image 5)
  • MS SharePoint Technical User + Password (Image 11)
  • MS Entra Application ClientID (Image 16)
  • MS Entra Certificates and Secrets – Value (Image 21)

================================================================================

6. Prepare SharePoint Integration (optional)

We shall look at the details that are required from Microsoft SharePoint. To work on the following setup, you need to be a SharePoint Administrator and have access to Identity Services Admin. In my case, I am using the default Microsoft’s Entra ID cloud-based identity and access management platform.

As a first step, log in to your Microsoft Entra, click on Overview, and copy the Tenant ID. We will be using this value later.

nageshcaparthy_1-1728382293944.png

 Image 1

6.1 Create a SharePoint Site

I guess this is one of the simple tasks, you can either use the existing Site or Create a New Site.  Log in to your MS 365 SharePoint, and Click on Create Site.

nageshcaparthy_2-1728382525831.png

Image 2

Select a Template as per your choice, I have selected Standard Communication.

nageshcaparthy_3-1728382554071.png

Image 3

Click on Use Template.

nageshcaparthy_4-1728382597504.png

Image 4

Give a Site Name that can help you recognize the Site for your Business/Scenario. I have entered the following details:

Site Name: Document Grounding

Site Description: Document Grounding for Joule

The site address is auto-generated, once you check the details, click on Next.

nageshcaparthy_5-1728382669778.png

Image 5

Select the Language as English (Note only English is supported at this time), and Click on Create Site.

nageshcaparthy_0-1728383329958.png

Image 6

Once the site is created, please navigate to Documents and upload the PDFs or Microsoft Word files.

nageshcaparthy_1-1728383371122.png

Image 7

6.2 Create a Group and a Technical User

As part of our Document Grounding process, we will need a Technical User who will be used as a general login to create the pipelines and share the documents with our Services and this User should be in a Group.

We shall create a new Group and then a Technical User. Note that if you have an existing Group and it can be reused, you may skip creating the new Group.  

Login to Microsoft Entra, Expand Groups -> Click on All Groups -> and then click on New Group.

nageshcaparthy_2-1728383414949.png

Image 8

Provide a Group Name, select Microsoft Entra Roles that can be assigned to the group, and click on Create.

Group Name: Document Grounding for Joule.

nageshcaparthy_3-1728383531967.png

Image 9

Now let us add an admin user to the groups with authorizations. To do that, expand the Users section, click on All Users, and click Create New User.

nageshcaparthy_4-1728383572553.png

Image 10

Enter the User principal name, and Display Name, copy the values, and then click on Next.

User ID for Data Pipeline: documentgrounding@abc.onmicrosoft.com

Password: ABCDEFGH

Tip: Make a note of all the details in a notepad, we will need the details later.

nageshcaparthy_5-1728383609685.png

Image 11

In the Assignments section, please select the Group Document Grounding for Joule” that we created and click on Next: Review + Create.

nageshcaparthy_6-1728383671968.pngImage 12

Please validate the details and Click on Create.

nageshcaparthy_7-1728383724866.png

Image 13

6.3 Register an Application, Generate a Client Secret, & Expose the application using web API

In this step, we are going to register the application, which will help us define access to applications using Client ID and Client Secret.

Expand the section Applications, click on App registration, and click on New Registration.  

nageshcaparthy_8-1728383803462.png

Image 14

Enter the Name and select the option “Accounts in this organization directory only” (you may select other options based on your setup) and click on Register.

Tip: Make a note of all the details in a notepad, we may need the details later.

nageshcaparthy_9-1728383844403.png

Image 15

Once the application is created, copy the Application (client) ID. We will use it later to create the BTP Destination.  

nageshcaparthy_10-1728383924363.png

Image 16

Now, let us use API Permission to generate a Client ID and Secret. Select the Registered app from the previous step, “document-grounding-joule-app,” click on API Permissions, Click on Add a Permission, and under Microsoft APIs, click on Microsoft Graph.

nageshcaparthy_11-1728384030622.png

Image 17

Select the option Delegated permissions, and in the Search box – look for “sites” and in the search results, select the option Sites.Read.All and Click on Add permissions.

nageshcaparthy_12-1728384070137.png

Image 18

If you see a pop-up Grant admin consent confirmation, click on Yes. Next, click on Grant Admin consent for MSFT.  You should be able to see the sites added as shown below.

nageshcaparthy_13-1728384141791.png

Image 19

Now that the application has been granted permission, we shall generate a Client ID and Secret for it. Within the “DocumentGrounding Joule” application, click on Certificates & Secrets, click on Client Secrets, enter a Description, and click on Add.

Description: BTP Destination for Document Grounding (on behalf of User)

Expires: select the maximum

Tip: Please ensure you track the Dates. After the expiry, we will need to recreate/renew and update the new value in the BTP Subaccount.

nageshcaparthy_14-1728384244929.png

Image 20

Once the Client secrets are created, please copy the Value, as we will use it in BTP Destinations.  

nageshcaparthy_15-1728384298585.png

Image 21

6.4 Validate the SharePoint access with the Technical User

As a final step, we need to validate the Technical user access to the SharePoint that we have created. So, I will be using the values that I have.  

Site Link: https://xxx.sharepoint.com/sites/DocumentGrounding

Entra Tech User ID for Data Pipeline: documentgrounding@abcd.onmicrosoft.com

Password: ABCDEFGH

Once you log in to this SharePoint Site with the user documentgrounding@abcd.onmicrosoft.com, you may be asked to create a new password. Please go ahead and create a new password and ensure that you remember it. You should now be automatically allowed to log in to the Site. In case of any authorization issues, please use login with your credentials, click on Site Access at the top right, and add the user as required. In my case, I have added the user with full Control.

nageshcaparthy_16-1728384404492.png

Image 22

Once the user site access is granted, please validate the login with the new password. If the user has access to the site we are all good with the Site setup.

7. Activate Grounding Service in BTP Subaccount & Create a Service Key

7.1 Configure User Authentication

This is the process of activating the Grounding service in your BTP Subaccount and creating the required service key.

a. Activate Grounding Service in BTP Subaccount & Create a Service Key

This is the first step in activating your Document Grounding service. Please note that this requires Joule to be set up and working in your LOB.

If you have the AI Unit SKU 8018592, the service should be added to your SAP BTP Global Account. The service entitlement “Document Grounding” should be visible in the Entitlement -> Service Assignment section.

Assign this entitlement to your subaccount where you have configured the Joule for SuccessFactors system. Navigate to your subaccount, click on Entitlements -> Click on Edit -> Click on Add Service Plan -> search for Document Grounding, and select the plan “data-manager” and Save the settings.

nageshcaparthy_0-1728384674788.png

Image 23

To activate the Document Grounding service, in your subaccount, click on Service Marketplace -> click on Document Grounding -> click on Create.

nageshcaparthy_1-1728384709673.png

Image 24

The service for Document Grounding -> Plan is data-manager auto-selected. Select the disclaimer “I understand that enabling a service might result in costs, depending on the plan selected” and enter the Instance Name that can help you relate the service that you are activating. In my case, I have given “groundingcli”; please make a note of this, as we will be using it later. Enter the values and click on Create.

nageshcaparthy_2-1728384802141.png

Image 25

nageshcaparthy_0-1732004113071.png In case the Document Grounding fails with the above Cloud Foundry runtime environment, delete the service that failed, and please select the option "Other" from the drop-down and create a new instance, as both services deliver the same functionality. 

You should be able to see the instance once the service is created. Click on the instance, and in the ‘groundingcli’ screen -> in the Service Keys (if you have selected Runtime Environment as "Others" do this with "Service Binding") section -> click on Create.

nageshcaparthy_3-1728384846467.png

Image 26

Enter the Service Key Name (Service Binding Name in case of "Others" runtime environment) -> In my case, I have entered the value “groundingkey” and Click on Create.

nageshcaparthy_4-1728384880098.png

Image 27

Once the Service Key is created, click on the 3 dots and click on View.

nageshcaparthy_5-1728384938200.png

Image 28

Copy the value displayed in the “groundingkey” URL. We need this value for our next steps.

nageshcaparthy_6-1728385018149.png

Image 29

b. Create a Cloud Identity Service Instance and a Service Key

As part of the next step, we need to create a new subscription with our SAP Cloud Identity Services. Within the same Subaccount, navigate to Service Marketplace -> click on Cloud Identity Services -> click on Create and select the Plan as application, the Runtime Environment and Space should be selected automatically, if not please select the correct details and fill in the “Instance Name” -> “groundingCIS” in my case and click on Next.

nageshcaparthy_7-1728385078409.png

Image 30

nageshcaparthy_0-1732004113071.png In case the Cloud Identity Services fails with the above Cloud Foundry runtime environment, delete the service that failed, and please select the option "Other" from the drop-down and create a new instance, as both services deliver the same functionality. 

In the parameters page, please enter the following values, where <doc-grounding-instance-name> value is from Image 25 – “groundingcli” and click on Next.

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

nageshcaparthy_8-1728385233826.png

Image 31

Review the details and click on Create.

nageshcaparthy_9-1728385282084.png

Image 32

Once the service is created, we need to create a Service Key using the Cloud Identity Service Instance that we created now. Click on the right arrow of groundingCIS to create a new Service Key.

nageshcaparthy_10-1728385316292.png

Image 33

Enter the Service Key Name (Service Binding Name in case of "Others" runtime environment) as shown below and, please specify the JSON value as mentioned below.

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

nageshcaparthy_11-1728385462665.png

Image 34

Click on Create once the values are entered. Now click on the Right Arrow of groundingCIS or click on the 3 dots and choose view the Service Key - cisSK file that we created now.

nageshcaparthy_12-1728385498372.png

Image 35

Here, please ensure to copy the values of “clientid” and “authorization_endpoint” and then I recommend downloading this file.  

nageshcaparthy_13-1728385559375.png

Image 36

c. Copy / Edit the Certificate values to support *.crt and *.key values

Once you download the file cisSK.txt, please use an editor to open it. In my case, I have used Notepad++. Here please observe that we have 2 certificates where everything starts with -----BEGIN CERTIFICATE------ & one KEY File which starts with -------BEGIN RSA PRIVATE KEY----. You also see a \n (new line) character at multiple places, which needs a small cleanup activity. I recommend using Notepad++ for this cleanup activity or any editor that you have, or if you have “sed” commands (MacBook), you can use the commands to clean it up, follow the official help guide, or if you are using Notepad++ continue below.

nageshcaparthy_14-1728385679878.png

Image 37

Let's work on the ----BEGIN CERTIFICATE ----- section.  Copy the text until ----END CERTIFICATE---. If you observe closely, we should be able to see two certificates with Begin and End.

Once you have copied the values to the new text file, please do CRTL+F to Find and select Replace, enter the value in Find what – “\n”, enter the value for Replace with “,” (a comma) and ensure you have Wrap Around, Search Mode as Normal and then click on Replace All.

nageshcaparthy_15-1728385797699.png

Image 38

Once you click on Replace All, the editor will replace \n with “,”(comma). Now, click on the Swap Find and Replace, under Search Mode select the option Extended, and then click on Replace All.

nageshcaparthy_16-1728385828959.png

Image 39

The text will be formatted in a new line without the \n and “,”(commas), please review it.

nageshcaparthy_17-1728385859081.png

Image 40

Please save this file as .crt. In my case, I have used “doc-grounding.crt”.

The same cleanup process needs to be followed for -------BEGIN RSA PRIVATE KEY----, please go back to your cisSK.txt file and copy only the values starting with -------BEGIN RSA PRIVATE KEY---- and -----END RSA PRIVATE KEY-----. Please follow the clean-up activity, as we did before, and save this file as .key, in my case I have used “doc-grounding.key”.

nageshcaparthy_18-1728385896777.png

Image 41

Once the certificate and key files are ready, please move them to a folder. This helps us to generate both the files, .crt and .key files required to run the cURL commands.

d. Create Destination in SAP BTP Subaccount

We need to create a destination in the subaccount to create access and enable connectivity to Microsoft SharePoint using the APIs and technical user that we created.

Within your SAP BTP Subaccount, expand on Connections -> click on Destination -> click on Create Destination and enter the following details:

 

Field

Value

Name

<NAME_OF_DESTINATION>

Type

HTTP

URL

https://graph.microsoft.com

Proxy Type

Internet

Authentication

OAuth2Password

User

The technical user that you've created in Microsoft Entra ID (Image 11)

Password

The password that you've created in Microsoft Entra ID (Image 11)

Client ID

Microsoft Entra ID Application credentials (Image 16)

Client Secret

Microsoft Entra ID Application credentials (Image 21)

Token Service URL

https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token, where <TENANT_ID> is the token service URL of Microsoft  Entra ID (Image 1)

In the additional properties, click on Add, enter the following values:

scope : https://graph.microsoft.com/.default

The details should be as shown below; once you enter the details, please Click on Save.

nageshcaparthy_19-1728386362274.png

Image 42

You may click on Check Connection for a quick test, and if all the setup is fine we see the result below.

nageshcaparthy_0-1728386724876.png

Image 43

8. Run a cURL command for POST and GET using Bruno API Client

We run these cURL commands to get an access token to our Grounding pipelines and set up an authentication.

Note: If you are using a GitHub Bash or Mac System, you can run them directly in the terminal. In the case of Windows, you can either try with Postman Client or Bruno.

In this demo, I am going to use Bruno – an Opensource API Client.

8.1 Add Certificates to DocumentGrounding Collection

Open your Bruno client, click on the 3 dots, and click on Collections -> Create Collection. We are going to create a collection to get bearer tokens, display pipelines, create pipelines, and delete pipelines.

nageshcaparthy_1-1728386918770.png

Image 44

Give your collection a name and save it in a path of your choice. Once the collection is created, mouse over it, Click on the three dots, and choose Settings -> click on Client Certificates.

Here, you will need two URLs: one to help us generate a Bearer Token and another to generate Document Grounding pipelines.

  • Cloud Identity Services URL
  • MTLs RAGE URL which is generated while creating your Service Key in your subaccount (Image 29)

Enter the Domain value with one of the URLs, add the .crt and .key files, click on add, and repeat the same for the other URL and add it. The process is as shown below:

nageshcaparthy_2-1728387246784.png

Image 45

8.2 Get Bearer Token

Mouse over to the DocumentGrounding collection, click on 3 dots, and select New Request. Here we need the URL to generate the Bearer Token, so the URL should be a combination of the following:

Type: HTTP

Name: Get Bearer Token

URL: https://<<CloudIdentityService>>/oauth2/token

The URL example:

https://abcdefgh.accounts.ondemand.com/oauth2/token

nageshcaparthy_3-1728387355054.png

Image 46

Once you enter the values, click on Create. Now, in the entry, enter the following values in the values in Params and Headers, Save it, and Run the request.

Params:
client_id: ClientIDValue_from_GroundingCIS (Image 36)
grant_type: client_credentials

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

You should be able to see the Bearer Token as shown below.

Note: The URL will be updated once you add the Params value in Bruno.

nageshcaparthy_4-1728387523013.png

Image 47

Make a note of this Access Token value, which will be used for the next step.

8.3 Get All Pipelines

We are going to create a new GET request to check if the Bearer token is working and to check the pipeline values. If you run it for the first time, you should get a null value.

You can mouse over to the DocumentGrounding collection, click on the three dots, select New Request, select the following details, and click on Create.

Type: HTTP
Name: Get all Pipelines
URL Type: Get
URL Value: The MTLS URL (image 28)
Eg: https://mtls.rage.c-6d4c6e4.kyma.ondemand.com/pipeline/api/v1/pipeline 

nageshcaparthy_5-1728387648277.png

Image 48

Once you enter the details click on Create. Now click on Headers, and add the following details.

Authorization: Bearer <<token value>>
accept: application/json

Save the value, and Run the request. You should be able to see a null value as shown below.

nageshcaparthy_6-1728387690875.png

Image 49

This confirms the pipeline is reachable.

8.4 Set Up Content Ingestion – Create a Pipeline

Mouse over to DocumentGrounding, click on the three dots, and select New Request. Enter the following details:

Name: Create a Pipeline
URL Type: POST
URL Value: The MTLS URL (image 28)
Eg: https://mtls.rage.c-6d4c6e4.kyma.ondemand.com/pipeline/api/v1/pipeline 

nageshcaparthy_7-1728387765812.png

Image 50

Once you enter the details click on Create. In the new entry, please enter the Body and Header details as shown below.

Navigate to Body, create a new entry type JSON, and enter the following details:

{
"type": "MSSharePoint",
"configuration": {
"destination": "<<BTP_DocumentGrounding_Destination_Name>>",
"sharePoint": {
"site": {
"name": "<<sharepoint_name>>"
}
}
}
}

The value should be like this.

nageshcaparthy_8-1728387821772.png

Image 51

Note: By default, the data pipeline will read data from the MS SharePoint site name you provide. If you want to give access to a specific folder of your SharePoint, you can use the following folder path. You can refer to the official help page here, I have added a sample scenario below.

Note: You should have the "/" along with the folder name.  Any changes to the format, the pipeline may get created, but it may be empty and Joule may not answer your questions. Please verify using the Get all Pipelines to validate.  

nageshcaparthy_0-1728562857291.png

Image 52

Now click on Headers and enter the following values.

Authorization: Bearer <<Token_Value>>
content-type: application/json

Save the settings and click on run. You should see a New Pipeline generated like this.

nageshcaparthy_10-1728388057161.png

Image 53

You can go back to Get a Pipeline and check if you can find the same pipeline ID along with the defined path.

8.5 Delete a pipeline

Note: Executing the delete option is not required unless you want to delete the full pipeline. This will clear the entire SharePoint and the Folders that you have selected. 

Select the type as Delete for deletion, you can enter the details for Headers as shown below, maintain the MTLS URL, and enter the Pipeline ID you want to delete. Once you run this, the pipeline will be deleted.

nageshcaparthy_1-1728563154944.png

Image 53a

9. Joule Testing

Once you complete your setup, please note that only the initial load of uploaded PDFs will be read immediately. Any documents added later will have to wait for the standard “scheduler/scheduled” time in the SAP system to refresh the data pipelines for FAQ support.

Here are some of the initial test results:

  • Looking for Co-Pay information on Medical Insurance:

nageshcaparthy_0-1728388326282.png

Image 54

  • Checking eligibility for any medical surgery:

nageshcaparthy_1-1728388355899.png

Image 55

  • Checking escalation process:

nageshcaparthy_2-1728388413268.png

Image 56

  • Verify the data from the uploaded Word file.

nageshcaparthy_3-1728388445298.png

Image 57

Happy Learning!!!

For support issues on the setup process, please create a ticket using the CA-ML-RAGE.

If you need any support during the setup you can reach us at SAP_AI_RIG@sap.com.

Special thanks to the entire Document Grounding Team and AI Team for contributing to this blog. 

Regards,

Nagesh

Common Setup Issues:

  1. Error 401 – while running the get command with Bearer Token.

This could happen for various reasons, and one of the reasons is documented below. In a few cases, we have observed that your Tenant OpenID Connect Configuration is using the legacy setting without the value “https://” in the URL. To find more information, you can visit the link here, or follow the steps below:

nageshcaparthy_0-1733752286658.png Before making the changes, please ensure to read the details. This may impact the other system setup due to URL changes. Please ensure to validate before making the changes as the changes are not reversable. You can also refer to 3191108 - There was an error when authenticating against the external identity provider: Invalid iss...

nageshcaparthy_4-1728388515065.png

 

Go to your SAP Cloud Identity Services ->Click on Applications & Resources -> Under Single Sign On -> choose the OpenID Connect Configuration list item -> in the Issuer the URL value should be “https://<Cloud Identity Service URL>”, in case the https:// is missing, please click on the drop-down and select the same value with https:// (if it’s *.ondemand.com please same the value with *.ondemand.com) and save the settings.

nageshcaparthy_5-1728388548974.png

Once you save this value, please run the Get CURL command and try it.

2. You have a message: “code":500,"message":"Microsoft Graph API error: Request failed with status code 401”

This could happen if you have missed the setup on “Granting admin consent for MSFT”, please ensure you go back to the User that you have created, API Permissions, and click on Grant admin consent for MSFT and ensure you see the status as shown below.

nageshcaparthy_6-1728388598434.png

 

Appendix (only for MacBook Terminal)
If you plan to use a MacBook and run using the terminal:

Get Bearer Token:

curl \
--request POST \
--url <adjusted_authorization_endpoint> \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'client_id=<clientid>' \
--data 'grant_type=client_credentials' \
--cert <file_with_certificate> \
--key <file_with_key>

Where,

Placeholder

Description

<adjusted_authorization_endpoint>

The "authorization_endpoint"

<clientid>

The "clientid" value that you obtained from

<file_with_certificate>

The doc-grounding.crt file, adjusted with the line breaks

<file_with_key>

The doc-grounding.key file, adjusted with the line breaks

curl --request POST --url https://aclxxsnax.accounts.ondemand.com/oauth2/token --header 'accept: application/json' --header 'content-type: application/x-www-form-urlencoded' --data 'client_id=452e75c9-ee1a-4964-xxxx-exx92be79690' --data 'grant_type=client_credentials' --cert doc-grounding.crt --key doc-grounding.key

Once you run this command, we receive a Bearer token which expires in 3600 seconds or 1 hr.

The response will be in a similar format as shown below:
{
"access_token":"eyJq........LI-L8KsOQV593dmtPU1g",
"token_type":"Bearer",
"expires_in":3600
}

nageshcaparthy_7-1728388680416.png

Please copy the Bearer token as we will need it for our next steps.
Now, we shall continue with the pipeline with the GET command, to call the document grounding endpoints. Use the syntax:
curl \
--request GET \
--url '<url>/pipeline/api/v1/pipeline' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <access_token>' \
--cert <file_with_certificate> \
--key <file_with_key>

Placeholder

Description

<url>

The service key URL (MTLS)

<file_with_certificate>

The doc-grounding.crt file adjusted with the line breaks

<file_with_key>

The doc-grounding.key file adjusted with the line breaks

In my case, I have the following format:

curl --request GET --url 'https://mtls.rage.a5601b3.kyma.ondemand.com/pipeline/api/v1/pipeline' --header 'accept: application/json' --header 'Authorization: Bearer eyJqa3UiO<<<short version of bearer token>>3heagq4mbLyYBg' --cert doc-grounding.crt --key doc-grounding.key

nageshcaparthy_8-1728388721789.png

Once you run the command, you should receive a response with an empty list [] since the pipeline hasn’t been created yet.

Set up Content Ingestion

The last and final step is to set up a content ingestion which will help us to push the SharePoint documents to the Document Grounding pipelines which will further use the LLMs for training and support the end user queries while using Joule.
Use the following cURL command and remember if you get a 401 – unauthorized, it could the bearer token just got expired. Please use the Post command and run the following command with the bearer token.
Syntax:
curl \
--request POST \
--url '<url>/pipeline/api/v1/pipeline' \
--header 'Authorization: Bearer <access_token>' \
--header 'content-type: application/json' \
--data '{"type": "MSSharePoint","configuration": {"destination": "<NAME_OF_DESTINATION>","sharePoint": {"site": {"name": "<NAME_OF_SHAREPOINT_SITE>"}}}}' \
--cert <file_with_certificate> \
--key <file_with_key>

I have used the following command:

curl --request POST --url 'https://mtls.rage.a5601b3.kyma.ondemand.com/pipeline/api/v1/pipeline' --header 'Authorization: Bearer eyJqa3UiOiJod<<<Shortversion>>>xjoI4npWdgq4mbLyYBg' --header 'content-type: application/json' --data '{"type": "MSSharePoint","configuration": {"destination": "joule-sfsf-data-pipeline","sharePoint": {"site": {"name": "DocumentGrounding"}}}}' --cert doc-grounding.crt --key doc-grounding.key


Once you run the command successfully, you should be able to see the response as shown in the image.
Response: { "pipelineId":"4cfd0478-29ea-45c2-bc40-d3817621744e" }

nageshcaparthy_9-1728388766415.png

This confirms that the setup has been completed using the terminal approach, and we are now ready to query the Joule service with the Documents that are uploaded in SharePoint.

21 Comments
SrivathsaDixit
Product and Topic Expert
Product and Topic Expert
0 Kudos

Great content..much detailed and helpful..thanks!

StevenLiu刘家骥
Product and Topic Expert
Product and Topic Expert
0 Kudos

Thanks for the very detailed walkthrough! Quite helpful.

One clarification:

" Document Content: Plain Text (tables and images are not supported)"

Doe it mean it can't extract info from tables and images? Or does it mean the uploaded documents should not contain tables and images otherwise an error pops up?

nageshcaparthy
Product and Topic Expert
Product and Topic Expert

Thanks, Steven. I appreciate the feedback. 

The document may have the tables and images, but our pipelines do not read the data. If you ask questions, it will respond that it cannot find the requested data. 

Regards,

Nagesh

Akshay_Srinath
Associate
Associate
0 Kudos

Thanks for the detailed explanation. It's really helpful.

I can't seem to find the service for Joule and document grounding in any of the Cost estimators. Why is this? 

nageshcaparthy
Product and Topic Expert
Product and Topic Expert

Hi Akshay, 

Joule and AI Units require separate contracts as they are not part of CPEA/BTPA. You can check the price list here:

https://www.sap.com/about/agreements/policies/cloud-service-specifications.html?sort=latest_desc&sea... 

ferreiracelio
Explorer
0 Kudos

Hello @nageshcaparthy  excellent post. 

Please could you confirm if it only works with a Joule in the SFSF or can I setup with a Joule connected with S/4HANA Private Cloud? 

Thanks 

niranjanbk1
Discoverer
0 Kudos

Hi Nagesh,

How about Microsoft Power point files (PPT) and excel , can Joule consume those documents?

 

Niranjan 

nageshcaparthy
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi Niranjan, 

In the current release we are only supporting PDF and Word documents. Other formats are in the roadmap. 

Regards,

Nagesh

nageshcaparthy
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi @ferreiracelio,

Yes, this should work with SAP S/4HANA Private cloud also. 

Regards,

Nagesh

 

tongzheng
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi Nagesh,

Very thorough and timely article on the technical details of the Document Grounding service! As for the vector embeddings generated from the customer documents, are they stored in HANA Vector DB in customer's own BTP tenant or vectors from multiple customers are stored in a shared backend HANA system?

Regards, Tong

xiaohong_ding
Associate
Associate
0 Kudos

Hi Nagesh,

Thanks a lot for this step by step guide.

But we are in "SAP SE" tenant, not have the permission to create user and application.

Do you know if there is any guidance in such case.

Thanks,

Xiaohong

MarcoN
Newcomer
0 Kudos

Hi Nagesh,

In our Group, we have many cases where policies only apply to certain employee groups or companies. For example, one policy only applies to tariff employees and a different policy applies to managers. Or a policy is only valid for a specific company in a country. Are there best practices for how the documents should be designed so that every employee always receives the answer that is really relevant to them?

Thanks a lot,
Marco

nageshcaparthy
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi @MarcoN 

Yes, this is a common request we hear from all customers, and it has been a priority to deliver this from the product side. In the current release, Joule can only talk to common documents shared with Grounding pipelines. 

Regards,

Nagesh

nageshcaparthy
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi @tongzheng,

The Vector DB is not at the customer BTP Account; it's a tenant managed by the product team, created during the service creation. These tenants has tenant isolation and security in place.

Regards,

Nagesh

shaileshnaik
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hello Nagesh,

Thanks for the blog.

Same here, I am have the sharepoint site in SAP SE tenant, if this approach will work?

Since SAP SE doesn't support Client Secret any more.

Regards,
Shailesh

Raju_
Discoverer
0 Kudos

Hello Shailesh, 

Thank you for the amazing blog. Based on the architecture diagram it might be possible to call Documentgrounding service directly from custom application ( which is already connected to LLM ) . am i right?

If so any idea where can we find documentation on this? because for now all documentations points to using either Joule or Generative AI hub ( orchestration ) to connect with documentgrounding. but missing direct calling of this service. 

Thank you in advance. 

Regards

tiwariy
Advisor
Advisor
0 Kudos

Hi,

I understand that there is BTP destination for graph URL. But if i want to consume it directly in Joule using functions by providing system-alias as BTP destination for retrieval APIs like search. How can we create BTP destination for retrieval API? I tried using OauthClientCredential with mTLS but it is not working and giving error as "Failure reason: "Could not check at the moment. Please try again later"Screenshot 2025-01-06 at 1.31.47 PM.png

Kindly help regarding this.

regards,

jaideepshetty
Participant
0 Kudos

Hi @nageshcaparthy ,

The step 8.3 to GET all pipelines works perfectly and returns null value, but when i proceed with step 8.4 for Content Ingestion, I am encountered with the following error. I have verified the SharePoint name and Destination multiple times, also tried with changing the name of SharePoint and using that in the query. Nothing seems to be resolving the issue. Have you or your team encountered this error?

jaideepshetty_0-1738082492813.png

This can be marked as closed.

Solution: It is to be noted that you should use 'Oauth2ClientCredentials' connection in your destination object if your customer uses different identity provider between SF and SharePoint.(Ex: OKTA is the authenticator for accessing SharePoint). If you try content ingestion with 'Oauth2Password' connection type. you will face the error above.

 

krishnakumar_nagarajan01
Product and Topic Expert
Product and Topic Expert

there is an existing SAP sharepoint with documents loaded. can we use the same site to integrate for document routing?

Also how should we get access to below for SAP User ID. 

  1. Need access to entra.microsoft.com
  2. Need access to create /register application within entra.
  3. Need access to create technical users/groups

 

Marcin
Explorer
0 Kudos

Great insights Nagesh. When it comes to licensing metric, does record refers practically to plain text document in 1:1 ratio (1 record = 1 document)?

ColinMR
Newcomer
0 Kudos

Hi,

Great blog - I've skimmed it, but not had time to read and appreciate everything.

I have a question about document grounding across a number of business units, with different document repositories.

Suppose we have polices relating to x, y and z.

At a Group level policies Gx, Gy & Gz are in repository Rep_G

At subsidiary unit A we have policy Ax in Rep_A superceding Gx

At subsidiary unit B we have policy Bx and Bz in Rep_B superceding Gx and Gz

Subsidiary unit C has no local policies

 

So for employees in A:   Ax, Gy and Gz apply

So for employees in B:   Bx, Gy and Bz apply

So for employees in C:  Gx, Gy and Gz apply

 

How would this be set up so Joule & document grounding so appropriate policies apply?