- SAP Managed Tags
We at SAP understand that you appreciate this aspect of the Joule capability of the Document Grounding feature, which can handle most of the policy questionnaire information from your corporate documents. SAP has been listening to all our customer feedback and asks us to improve this feature to make it more reliable, incorporating roles specific to your organization. To explain further, the SAP SuccessFactors team is pleased to introduce the advanced contextualization feature, which enables Joule to answer user questions based on user context.
For example, you can classify the documents based on Company, Location, Country, Employee Type, Department, Division, Job Title, Pay Grade, Cost Center, and many more. With the detailed document tags and/or metadata, Joule will now be able to return answers from the document based on the user profile and/or context.
This blog post will focus on how to achieve this process for your existing setup. While SAP Document Grounding is a general solution that can be activated with any SAP Line of Business application, we will examine the steps in detail, understanding the prerequisites and improvements that our product team is continually working on.
Remember, this is a continuation of our first blog post, “Joule – Getting Started with Document Grounding - setup guide 1”.
Essential Things to Note:
- Metadata Management for documents via a graphical user interface is only available with SAP SuccessFactors. This approach can be applied to all documents within your company.
- We currently offer support for Microsoft SharePoint services; our product teams are looking to provide this feature to SAP Build Work Zone and ServiceNow.
Very Important:
If you are using an existing setup (OAuthClientCredentials, generic secret, and application permission type in the Microsoft entry) and have the Document Grounding service activated, please go ahead.
Your current setup lacks metadata and contextualization, and we will need to delete the existing pipeline to support the new features. The Document Grounding is metered monthly based on the predefined usage metric, which is records. Due to the monthly metering, we recommend deleting the existing pipeline at the end of the current billing month and creating a new one at the start of the following month to avoid additional charges and maintain business continuity.
Since this is a commercial topic, we would recommend that you validate your setup. If you have a smaller number of documents, and your company is okay with deleting them at any time, you may still proceed. However, please keep in mind duplicate charges only for the current month in case of mid-month changes.
As always, we recommend to look at the SAP Official help page here: Adding Metadata to Your HR Policy Documents the blog can help you to speed up the setup process.
Prerequisites:
- You will need to activate and integrate Joule, SAP Document Grounding, with SAP SuccessFactors.
- You will need access to SAP SuccessFactors Admin Access. Preferably, SFADMIN login as the proxy mechanism may not work.
- Access to SAP Business Technology Platform as Global Administrator
- Access to Microsoft ENTRA as an Administrator
- Access to your Bruno and Bruno Collections, along with Certificate and Key files, which were used during DG pipeline creation
- Tip: If your existing Bruno collections fail, please verify the validity of the certificates and regenerate the certificate and key as necessary.
- Tip: If your existing Bruno collections fail, please verify the validity of the certificates and regenerate the certificate and key as necessary.
Some of the steps that we will be doing are highlighted below:
- SAP SuccessFactors Admin Settings
- Activate Ask HR Policies
- Role-Based Permission - Assign Manage Document Grounding
- Register a new application & add the dependencies in SAP Cloud Identity Services(IAS).
- Manage OIDC OAuth Client Application in SAP SuccessFactors – Security Center
- Create App Registration for Document Grounding with Application Permission (validate your existing setup)
- Fetch the SharePoint Site ID and grant read access to the site
- Get Microsoft Token
- Create a collection to GetSiteID
- Graph Explorer
- Create a BTP Subaccount Destination
- Destination for Document Grounding Context
- Destination for Document Grounding Metadata
- Create a new Pipeline for your Metadata Document Grounding
- Configure Supported Metadata for User Data Field Mapping in SAP SuccessFactors
- Trigger the Pipeline post Metadata setup in your SAP SFSF
- Test your Policy settings
- Appendix
Let us walk you through the setup flow quickly to understand how this works:
Image 00
Once you have the prerequisites and understand the following, we will proceed with the required setup for adding Metadata to your Documents.
1. SAP SuccessFactors Admin Settings
We will first be activating the Ask HR Policies feature in the system. This is required to enable the feature and access the Manage document grounding page.
1.1 Activate Ask HR Policies
To do this, log in as SFAdmin, navigate to Admin Center, and then navigate to AI Service Administration. Activate the Ask HR Policy toggle as shown below, and ensure the activated service is saved by logging out and revisiting the site.
Image 01
Tip: You can try activating it with a proxy login to sfadmin. If the service does not allow it, we recommend logging in as sfadmin and activating the service.
1.2 Role-Based Permission Assign Manage Document Grounding
Now, let us activate the SAP SuccessFactors permission in the system to Manage Document Grounding services. This permission will enable us to map files based on your requirements, such as Company, Location, Role, Company, Employee Type, Job Title, Pay Grade, Cost Center, and many more.
To assign this role to users, navigate to Manage Permission Roles, select the group to assign the permission, and, in my case, I have opted forSFCC Super Admin. Click Next.
Image 02
Now, search for Document Grounding. You should be able to see the option under Manage AI Capabilities. Select the option ‘Manage Document Grounding,’ click on Next, and Save the settings.
Image 03
To test it, you can now log out of the system and log back in. This will allow you to refresh the roles in the system. You can now search for ‘Document Grounding’ and should see the new option ‘Manage Document Grounding’.
Image 04
2. Register a new application & add the dependencies in SAP Cloud Identity Services(IAS).
In this step, we will create a new application to support the Document Grounding setup. We will generate a new Client ID andClient Secret, which will be used in destinations and other places. To set up this application, you can log in to your SAP Cloud Identity Services used by your Joule and SAP SuccessFactors system.
Navigate to Application & Resources -> click onCreate -> and enter the following details below, and click on Create.
- Display Name: SFSF-T1-DGS (please note the name that you use, as we will be using it later. In my case, I am using SFSF; T1 is my SFSF system’s name)
- Type: SAP SuccessFactors Solution
- Protocol Type: OpenID Connect
Image 05
Now, click on Client Authentication and, in the Secret section, click Add to create new credentials.
Image 06
I am using the same name as the description, setting the expiry to ‘Never’, and selecting all the APIs listed below. Then, I click on ‘Save’.
Image 07
This will generate a new Client ID and Client Secret. Please make a note of this value using the copy button.
Note: This will not be displayed again, so please secure them as we will be using them later.
Image 08
In the application, click on ‘Provided APIs’, then click ‘Add’ and enter the values as shown below. Save the changes.
- Name: sf_technical_access (recommended to keep the same value)
- Description: For Technical Access to SF (can be free text)
Image 09
Now, click on Dependencies, then click Add. Enter the following details as shown below, and click Save.
- Dependency Name: DGS-SF-Call (mandatory to use the same name)
- Application: Select your SAP SuccessFactors system from the dropdown list (If you don’t see your SuccessFactors system, you may need to do the OIDC migration)
- API: sf_technical_access (the API name which was created in the previous step)
Image 10
3. Manage OIDC OAuth Client Application in SAP SuccessFactors – Security Center
As part of the setup, we will now need to configure the OIDC OAuth Client Application in the SAP SuccessFactors system. Please log in to your SAP SFSF system and navigate to Security Center, and click on Manage OIDC OAuth Client Application.
Image 11
Click "Register" and enter the following details.
- Application Map Name: SFSF-T1-DGS (same name as configured in the SAP Cloud Identity Services)
- Client ID: from your SAP Cloud Identity Services
- Application Type: DOCUMENT_GROUNDING (from the drop-down)
Once you enter the details, click 'Register'.
Image 12
You should be able to see the details as shown below.
Image 13
4. Create App Registration for Document Grounding with Application Permission (validate your existing setup)
As of the new release, we are currently supporting Application Permissions forMicrosoft Graph, and this is required for the Metadata with documents.
This section is required only if you have set up your Microsoft SharePoint Application registration with Delegated Permission. If you are using an existing setup, please validate it, and you may need to delete and recreate the application. You may refer to our previous blog for complete setup information.
I have highlighted some key information here. Your application should be set up with Application Permission as shown below.
Image 14
You should have the API permissions for "Sites.Read.All" or "Sites.Selected" based on your requirements and the role "User.Read.All", as shown below.
Image 15
You have generated a Client Secret value and have it saved for further setup.
Image 16
Note: Next section 5 is required only if you have selected “Sites.Selected” instead of “Sites.Read.all” permissions.
5. Fetch the SharePoint Site ID and grant read access to the site
We will now generate the Site ID for the Microsoft SharePoint that you plan to use. To do this, we will work with your BRUNO client. I have pasted the cURL commands to make it easier for you to create the required GET/POST requests.
5.1 Get Microsoft Token
In the BRUNO client, create a new collection and enter the request name as GetMicrosoftToken, and click on the from cURL option and paste the code that you see below.
Name: GetMicrosoftToken (Bearer Token)
CURL Command to Details from MS Entra:
--url https://login.microsoftonline.com/<<TENANTID>>/oauth2/v2.0/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'content-type: application/x-www-form-urlencoded' \
--data client_id=<<ClientID>> \
--data 'client_secret=<<ClientSecret>>' \
--data scope=https://graph.microsoft.com/.default \
--data grant_type=client_credentials
Once you import the cURL code, you can either modify the values before you import, or once you import the collection. You'll need to edit the highlighted values.
Image 17
You should be able to see the details as follows.
Image 18
Now we are good to trigger a call, click on the go/execute button, which will generate an access_token as shown below.
Image 19
5.2 Create a collection to GetSiteID
Collection Name: GetSiteID
--url https://graph.microsoft.com/v1.0/sites/<<Sharepoint_URI_HOST>>:/sites/<<SITE_NAME>> \
--header 'authorization: Bearer <<ACCESS TOKEN VALUE>>'
Note: The Bearer token value is the access token value that was generated in the previous collection GetSiteID.
You can modify the highlighted details before importing the cURL.
Image 20
You should be able to see the details as shown below. Now, we are ready to click on 'Go/Execute'.
Image 21
You will be able to see the value of “id”. Please copy the entire value, as we will be using it later.
Image 22
5.3 Graph Explorer
Graph Explorer is a developer tool that enables you to explore Microsoft Graph APIs. Here, we will use the developer tool to generate, set the required permissions, and grant consent for the setup process.
Please use the link below to log in with your admin role as shown below.
https://developer.microsoft.com/en-us/graph/graph-explorer
Image 23
You can click on any of the Getting Started requests shown below and edit the values as needed.
Change from GET to POST and change the URL as below:
https://graph.microsoft.com/v1.0/sites/<<value-from-BRUNO-GetSiteID-IDValue>>/permissions
Image 24
Once you modify the values above, we will need to work on the Request Body. We will now need the App Registration name from your MS Entra, as shown below.
Image 25
Use the value of the body as shown below:
"roles": ["read"],
"grantedToIdentities": [
{
"application": {
"id": "your-app-client-id",
"displayName": "Your App Name"
}
}
]
}
Image 26
Once you add the values, you can click on Modify Permissions, click on Open the permissions panel, and you should be able to see a new window.
Image 27
You can click on Consent for the option "Sites.FullControl.All"; this will open a new window.
Image 28
Select the 'Consent on behalf of your organization' option and click 'Accept'.
Image 29
You should be able to see the notification Success as shown below.
Image 30
Now, click on the Request Headers and add the key - Content-Type and value as application/json as shown below, and click on Run query.
Image 31
Look for the 'Created-201' success message, as shown below.
Image 32
This now completes the setup on Microsoft, and the required permissions are granted and created.
6. Create a BTP Subaccount Destination
We will now be creating two new destinations to establish communication between the systems.
- SFSF-T1-DG-Context-Setup
- SFSF-T1-DG-Metadata-Destination
6.1 Destination for Document Grounding Context
You can create this destination setup manually or download the attached files to this blog and modify the values. Here, I have shown the details on how to create it manually.
Please navigate to our SAP BTP Subaccount, click on Destinations, and click on Create and select From Scratch and click on Create.
Image 33
Enter the following details:
Parameter | Value |
Destination Name | SFSF-T1-DG-Context-Setup |
Type | HTTP |
Description | Free Text |
Proxy Type | Internet |
URL | Your Microsoft SharePoint URL |
Authentication | OAuth2ClientCredentials |
Client ID | Client ID from your MS Entra – Application Registration Overview section. Eg: sfsf-dg-contexual-setup overview will have the Client ID in the overview section |
Client Secret | Value – from Certificates & Secrets that we created in step 4 |
Token Service URL | Enter the value as shown below: https://login.microsoft.com/<<Microsoft-Entra-Tenant-ID>>/oauth2/v2.0/token |
Token Service URL Type | Dedicated |
Additional Properties:
Parameter | Value |
scope (all lower case) |
Your setup should be as shown below, create the settings and click on Create.
Image 34
You can click on ‘Check Connection’ to validate the setup, and you should see a success message.
Image 35
6.2 Destination for Document Grounding Metadata
You create this destination setup manually or download the files attached to the bottom of this blog and modify the values. Here, I have shown the details on how to create it manually.
Navigate to our SAP BTP Subaccount, click on Destinations, and click on Create and select From Scratch and click on Create.
Enter the following values:
Parameter | Value |
Destination Name | SFSF-T1-DG-Metadata-Destination |
Type | HTTP |
Description | Free Text |
Proxy Type | Internet |
URL | You should be entering the value from your SFSF system APIs. Syntax: https://<<SFSF-API-Domain>>/rest/foundation/intelligence/generativeai/explainpay/v1/dg-pipeline/metadata?aiUseCase=HR%20Policy%20QA Example in my case it’s from SFSF Preview: Tip: you can refer to SAP Note: 2215682 - SuccessFactors API URLs and external IPs to find your Tenant API URL based on your Data Center |
Authentication | OAuth2ClientCredentials |
Client ID | Client ID value from SAP Cloud Identity Services in step 2 |
Client Secret | Client Secret value from SAP Cloud Identity Services in step 2 |
Token Service URL | Your IAS URL, as shown below Syntax: https://<<SAP-CIS-URL>>/oauth2/token Example: https://asxxxxxozz1.accounts.cloud.sap/oauth2/token |
Token Service URL Type | Dedicated |
Additional Parameters:
Parameter | Value |
tokenService.body.resource | urn:sap:identity:application:provider:name:DGS-SF-Call |
pageSize | 50 or 100 Recommendation for SAP SuccessFactors: keep the number below 100 for better performance. Reason: This variable is required to recursively ingest all documents in chunks of mentioned number of documents while creating the pipeline |
Once you create the destination as shown below, you can click on Create.
Image 36
Finally, you should be able to see both these destinations.
Image 37
7. Create a new Pipeline for your Metadata Document Grounding
As mentioned above, you should be creating a new pipeline in case of an existing setup. In my case I had an existing pipeline which I deleted, and now creating a new pipeline. You can either look at my original blog post for Document Grounding setup or continue using the steps below, feel free to skip the steps in case not applicable. However, please note, if you are doing the metadata setup, it is mandatory to create a new pipeline.
To generate a Certificate and Key files you can look at step c. Copy / Edit the Certificate values to support *.crt and *.key values and to bearer token refer to step 8.2 Get Bearer Token, and create a pipeline you can follow the steps below.
If you have the same BRUNO collections created in the past, ensure the certificate is not expired.
You can create the collection using the following cURL and modify the highlighted values.
curl --request POST \
--url https://<<MTLS URL>>/pipeline/api/v1/pipeline \
--header 'Authorization: Bearer <<Bearer Token>>' \
--header 'content-type: application/json' \
--data '{
"type": "MSSharePoint",
"configuration": {
"destination": "SFSF-T1-DG-Context-Setup",
"sharePoint": {
"site": {
"name": "<<SITENAME>>"
}
}
},
"metadata": {
"dataRepositoryMetadata": [
{
"key": "lob",
"value": ["sfsf"]
}
],
"destination": "SFSF-T1-DG-Metadata-Destination"
}
}'
Create the BRUNO post request as shown below.
Image 38
Once the values are modified, you can execute the POST command and generate the pipeline id.
Image 39
8. Configure Supported Metadata for User Data Field Mapping in SAP SuccessFactors
Now that the pipeline is newly created, we can go ahead and set up the metadata mapping for each file based on the user context. Let’s now navigate to the SAP SuccessFactors system, navigate to Manage Document Grounding, and enter the value that was generated in step 5.2 Create a collection to Get Site Name, as shown below, along with Client ID, Client Secret, and Tenant ID from Microsoft Entra. Once the values are entered, click Connect.
Note:
- “SharePoint Site ID” supports options with both SharePoint Site ID and SharePoint URL.
- For the “Folder Path” field, only the root path is supported at this point in time “/” the entire site’s documents will be considered for the ingestion.
Image 40
You should now be able to see the mapping options. In my demo, I will demonstrate only one value: Country. I have modified all other values to 'Unable to Map' except for the Country. I have updated it to Country/Region. Now, click on Save.
Image 41
In the next page, you can click on Add Metadata, and you should be able to see all the files in your MS SharePoint.
Image 42
The image below helps you understand how the folders and file structure appear in your SAP SuccessFactors system, which are stored in your MS SharePoint.
Image 43
I am picking up the file related to English and configuring to a country. To configure it, select the files and click on Next.
Image 44
On the next page, we will need to enter the string that we need to tag. This value can be found in your Employee Profile, as shown in the image below. I am picking up the value for one of the employees, and the Country is “United States”. You can enter multiple locations based on your requirements for the documents you need, with specifics, and click ‘Add’.
Image 45
This should complete the doc metadata configuration. As next steps, you may wait for at most 24 hours to get the metadata updated in the DGS pipeline, or you may manually trigger the DGS pipeline i.e., Step 9 below.
Image 46
9. Trigger the Pipeline post Metadata setup in your SAP SFSF
This process is required when you add and/or change your metadata, as it is a manual approach at this time. Otherwise, you have to wait for at most 24 hours to get the metadata updated in the DGS pipeline.
To trigger the metadata, you can create the BRUNO collection with the help of cURL as shown below and ensure the highlighted values are modified as required.
Pipeline Name: Pipeline Trigger
--url https://<<MTLS_URI>>/pipeline/api/v1/pipeline/trigger \
--header 'Authorization: Bearer <<TOKEN_VALUE>>’ \
--header 'content-type: application/json' \
--data '{
"pipelineId": "<<PIPELINEID>>",
"metadataOnly": false
}'
Once you have the values, you can click on go/execute the collection.
Image 47
You should be able to see the success message with the timeline of last completed as shown below.
Image 48
You can also check this with GET Pipeline, as demonstrated below with the URL changes in the collections. Add the Pipeline ID followed by the value shown in the image below. You should be able to see the document indexed along with the country values.
Image 49
10. Test your Policy settings
Finally, we are at the testing stage, you may now login to the users who are from the “United States” and the file will be working only for these employees as shown below.
Image 50
If employees from other countries or regions ask the same question, it will fail with a message as shown below.
Image 51
This completes the setup process and a demo of how metadata / contextualization-based document grounding works for your employees.
Happy learning!!!
Cheers,
Nagesh Caparthy
Credits: This blog post has been written in collaboration with the SAP SuccessFactors Business AI Team (Leo Chen, Ramesha R N, Sumanth Pullagura Govinda Mani) and SAP AI Engineering Team (Sudarshan Pavanje)
11. Appendix:
If you want to configure additional metadata, follow the images below and trigger the pipeline for metadata as shown.
Image 52
Image 53
Image 54
Image 55
In case of other users looking for similar information:
Image 56
Bluesky| User | Count |
|---|---|
| 47 | |
| 22 | |
| 18 | |
| 16 | |
| 15 | |
| 14 | |
| 13 | |
| 13 | |
| 13 | |
| 13 |
