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 AdministratorAccess to Microsoft ENTRA as an AdministratorAccess to your Bruno and Bruno Collections, along with Certificate and Key files, which were used during DG pipeline creationTip: 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 SettingsActivate Ask HR PoliciesRole-Based Permission – Assign Manage Document GroundingRegister a new application & add the dependencies in SAP Cloud Identity Services(IAS).Manage OIDC OAuth Client Application in SAP SuccessFactors – Security CenterCreate App Registration for Document Grounding with Application Permission (validate your existing setup)Fetch the SharePoint Site ID and grant read access to the siteGet Microsoft Token Create a collection to GetSiteIDGraph Explorer Create a BTP Subaccount Destination Destination for Document Grounding Context Destination for Document Grounding Metadata Create a new Pipeline for your Metadata Document GroundingConfigure Supported Metadata for User Data Field Mapping in SAP SuccessFactors Trigger the Pipeline post Metadata setup in your SAP SFSFTest your Policy settingsAppendix
Let us walk you through the setup flow quickly to understand how this works:
Image 1
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 2
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 for SFCC Super Admin. Click Next.
Image 3
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 4
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 5
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 and Client 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 on Create -> 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 SolutionProtocol Type: OpenID Connect
Image 6
Now, click on Client Authentication and, in the Secret section, click Add to create new credentials.
Image 7
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 8
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 9
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 10
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 11
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 12
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 ServicesApplication Type: DOCUMENT_GROUNDING (from the drop-down)
Once you enter the details, click ‘Register’.
Image 13
You should be able to see the details as shown below.
Image 14
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 for Microsoft 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 15
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 16
You have generated a Client Secret value and have it saved for further setup.
Image 17
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:
curl –request POST –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_credentialsOnce 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 18
You should be able to see the details as follows.
Image 19
Now we are good to trigger a call, click on the go/execute button, which will generate an access_token as shown below.
Image 20
5.2 Create a collection to GetSiteID
Collection Name: GetSiteIDcurl –request GET –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 21
You should be able to see the details as shown below. Now, we are ready to click on ‘Go/Execute’.
Image 22
You will be able to see the value of “id”. Please copy the entire value, as we will be using it later.
Image 23
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 24
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 25
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 26
Use the value of the body as shown below:{ “roles”: [“read”], “grantedToIdentities”: [ { “application”: { “id”: “your-app-client-id”, “displayName”: “Your App Name” } } ] } Image 27
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 28
You can click on Consent for the option “Sites.FullControl.All”; this will open a new window.
Image 29
Select the ‘Consent on behalf of your organization’ option and click ‘Accept’.
Image 30
You should be able to see the notification Success as shown below.
Image 31
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 32
Look for the ‘Created-201′ success message, as shown below.
Image 33
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-SetupSFSF-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 34
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
Eg: https://hostname.com/sitename
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)
https://graph.microsoft.com/.default
Your setup should be as shown below. Edit the values and click on Create.
Image 35
You can click on ‘Check Connection’ to validate the setup, and you should see a success message.
Image 36
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.
Please 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://asqooozz1.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 the mentioned number of documents while creating the pipeline
Once you have edited or updated the details as shown below, you can click Create.
Image 37
Finally, you should be able to see both of these destinations.
Image 38
7. Create a new Pipeline for your Metadata Document Grounding
As mentioned above, you should create a new pipeline in case of an existing setup. In my case, I had an existing pipeline that I deleted, and I am now creating a new one. You can either refer to my original blog post for the Document Grounding setup or follow the steps below. Feel free to skip the steps if they are not applicable. However, please note that when setting up the metadata, it is mandatory to create a new pipeline.
To generate Certificate and Key files, you can refer to 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 previously created the same BRUNO collections, please make sure 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 39
Once the values are modified, you can execute the POST command and generate the pipeline id.
Image 40
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 41
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 42
Tip:
The SFSF solution supports the Work Profile fields, incl. standard ones and custom ones, i.e. in SuccessFactors go to Manage Business Configuration -> Employee Profile -> Standard -> find all the Work Profile fields, see the first screenshot below.
Standard fields – standard fields should be supported per Supported Metadata for User Data Field MappingCustom fields – Ideally all the 15 custom fields (i.e. custom01 – custom15 in the first screenshot below, with the supported data types incl. Foundation Objects, Generic Objects, Picklist, Boolean, and String) are technically supported per Supported Metadata for User Data Field Mapping, when customers enable these custom fields thru the custom HRIS Sync mappings, i.e. in SuccessFactors go to Manage Business Configuration -> Employee Central -> HRIS Sync Mappings, see the second screenshot below
In the next screen, you can click on Add Metadata, and you should be able to see all the files in your MS SharePoint.
Image 43
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 44
I am picking up the file related to English and configuring for a country. To configure it, select the files and click on Next.
Image 45
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 46
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 47
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 must wait at most 24 hours for the metadata to be updated in the DGS pipeline.
To trigger the metadata, you can create the BRUNO collection using cURL, as shown below, and ensure the highlighted values are modified as necessary.
Pipeline Name: Pipeline Triggercurl –request POST –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 ‘Go/Execute’ to run the collection.
Image 48
You should be able to see the success message with the timeline of last completed as shown below.
Image 49
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 50
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 51
If employees from other countries or regions ask the same question, it will fail with a message similar to the one shown below.
Image 52
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.
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 AdministratorAccess to Microsoft ENTRA as an AdministratorAccess to your Bruno and Bruno Collections, along with Certificate and Key files, which were used during DG pipeline creationTip: 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 SettingsActivate Ask HR PoliciesRole-Based Permission – Assign Manage Document GroundingRegister a new application & add the dependencies in SAP Cloud Identity Services(IAS).Manage OIDC OAuth Client Application in SAP SuccessFactors – Security CenterCreate App Registration for Document Grounding with Application Permission (validate your existing setup)Fetch the SharePoint Site ID and grant read access to the siteGet Microsoft Token Create a collection to GetSiteIDGraph Explorer Create a BTP Subaccount Destination Destination for Document Grounding Context Destination for Document Grounding Metadata Create a new Pipeline for your Metadata Document GroundingConfigure Supported Metadata for User Data Field Mapping in SAP SuccessFactors Trigger the Pipeline post Metadata setup in your SAP SFSFTest your Policy settingsAppendix Let us walk you through the setup flow quickly to understand how this works:Image 1 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 SettingsWe 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 PoliciesTo 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 2Tip: 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 GroundingNow, 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 for SFCC Super Admin. Click Next. Image 3Now, 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 4To 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 52. 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 and Client 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 on Create -> 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 SolutionProtocol Type: OpenID Connect Image 6Now, click on Client Authentication and, in the Secret section, click Add to create new credentials.Image 7I 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 8This 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 9In 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 10Now, 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 113. Manage OIDC OAuth Client Application in SAP SuccessFactors – Security CenterAs 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 12Click “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 ServicesApplication Type: DOCUMENT_GROUNDING (from the drop-down)Once you enter the details, click ‘Register’. Image 13You should be able to see the details as shown below.Image 144. Create App Registration for Document Grounding with Application Permission (validate your existing setup)As of the new release, we are currently supporting Application Permissions for Microsoft 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 15You 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 16You have generated a Client Secret value and have it saved for further setup.Image 17Note: 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 siteWe 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 TokenIn 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: curl –request POST –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_credentialsOnce 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 18You should be able to see the details as follows. Image 19Now we are good to trigger a call, click on the go/execute button, which will generate an access_token as shown below. Image 205.2 Create a collection to GetSiteIDCollection Name: GetSiteIDcurl –request GET –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 21You should be able to see the details as shown below. Now, we are ready to click on ‘Go/Execute’.Image 22You will be able to see the value of “id”. Please copy the entire value, as we will be using it later.Image 235.3 Graph ExplorerGraph 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-explorerImage 24You 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>>/permissionsImage 25Once 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 26Use the value of the body as shown below:{ “roles”: [“read”], “grantedToIdentities”: [ { “application”: { “id”: “your-app-client-id”, “displayName”: “Your App Name” } } ] } Image 27Once 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 28 You can click on Consent for the option “Sites.FullControl.All”; this will open a new window. Image 29Select the ‘Consent on behalf of your organization’ option and click ‘Accept’.Image 30You should be able to see the notification Success as shown below.Image 31Now, 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 32Look for the ‘Created-201’ success message, as shown below.Image 33This now completes the setup on Microsoft, and the required permissions are granted and created. 6. Create a BTP Subaccount DestinationWe will now be creating two new destinations to establish communication between the systems.SFSF-T1-DG-Context-SetupSFSF-T1-DG-Metadata-Destination 6.1 Destination for Document Grounding ContextYou 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 34Enter the following details:ParameterValueDestination NameSFSF-T1-DG-Context-SetupTypeHTTPDescriptionFree TextProxy TypeInternetURLYour Microsoft SharePoint URLEg: https://hostname.com/sitenameAuthenticationOAuth2ClientCredentialsClient IDClient ID from your MS Entra – Application Registration Overview section.Eg: sfsf-dg-contexual-setup overview will have the Client ID in the overview sectionClient SecretValue – from Certificates & Secrets that we created in step 4Token Service URLEnter the value as shown below:https://login.microsoft.com/<<Microsoft-Entra-Tenant-ID>>/oauth2/v2.0/tokenToken Service URL TypeDedicated Additional Properties:ParameterValuescope (all lower case)https://graph.microsoft.com/.defaultYour setup should be as shown below. Edit the values and click on Create.Image 35You can click on ‘Check Connection’ to validate the setup, and you should see a success message.Image 366.2 Destination for Document Grounding MetadataYou 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.Please 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: ParameterValueDestination NameSFSF-T1-DG-Metadata-DestinationTypeHTTPDescriptionFree TextProxy TypeInternetURLYou 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%20QAExample, in my case, it’s from SFSF Preview:https://api55preview.sapsf.eu/rest/foundation/intelligence/generativeai/explainpay/v1/dg-pipeline/metadata?aiUseCase=HR%20Policy%20QATip: You can refer to SAP Note: 2215682 – SuccessFactors API URLs and external IPs to find your Tenant API URL based on your Data CenterAuthenticationOAuth2ClientCredentialsClient IDClient ID value from SAP Cloud Identity Services in step 2Client SecretClient Secret value from SAP Cloud Identity Services in step 2Token Service URLYour IAS URL, as shown belowSyntax: https://<<SAP-CIS-URL>>/oauth2/tokenExample: https://asqooozz1.accounts.cloud.sap/oauth2/tokenToken Service URL TypeDedicatedAdditional Parameters: ParameterValuetokenService.body.resourceurn:sap:identity:application:provider:name:DGS-SF-CallpageSize50 or 100Recommendation for SAP SuccessFactors: keep the number below 100 for better performance.Reason: This variable is required to recursively ingest all documents in chunks of the mentioned number of documents while creating the pipelineOnce you have edited or updated the details as shown below, you can click Create.Image 37Finally, you should be able to see both of these destinations.Image 387. Create a new Pipeline for your Metadata Document GroundingAs mentioned above, you should create a new pipeline in case of an existing setup. In my case, I had an existing pipeline that I deleted, and I am now creating a new one. You can either refer to my original blog post for the Document Grounding setup or follow the steps below. Feel free to skip the steps if they are not applicable. However, please note that when setting up the metadata, it is mandatory to create a new pipeline.To generate Certificate and Key files, you can refer to 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 previously created the same BRUNO collections, please make sure 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 39Once the values are modified, you can execute the POST command and generate the pipeline id.Image 40 8. Configure Supported Metadata for User Data Field Mapping in SAP SuccessFactorsNow 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 41 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 42Tip:The SFSF solution supports the Work Profile fields, incl. standard ones and custom ones, i.e. in SuccessFactors go to Manage Business Configuration -> Employee Profile -> Standard -> find all the Work Profile fields, see the first screenshot below.Standard fields – standard fields should be supported per Supported Metadata for User Data Field MappingCustom fields – Ideally all the 15 custom fields (i.e. custom01 – custom15 in the first screenshot below, with the supported data types incl. Foundation Objects, Generic Objects, Picklist, Boolean, and String) are technically supported per Supported Metadata for User Data Field Mapping, when customers enable these custom fields thru the custom HRIS Sync mappings, i.e. in SuccessFactors go to Manage Business Configuration -> Employee Central -> HRIS Sync Mappings, see the second screenshot below In the next screen, you can click on Add Metadata, and you should be able to see all the files in your MS SharePoint.Image 43The 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 44I am picking up the file related to English and configuring for a country. To configure it, select the files and click on Next.Image 45On 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 46This 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 47 9. Trigger the Pipeline post Metadata setup in your SAP SFSFThis process is required when you add and/or change your metadata, as it is a manual approach at this time. Otherwise, you must wait at most 24 hours for the metadata to be updated in the DGS pipeline.To trigger the metadata, you can create the BRUNO collection using cURL, as shown below, and ensure the highlighted values are modified as necessary.Pipeline Name: Pipeline Triggercurl –request POST –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 ‘Go/Execute’ to run the collection.Image 48You should be able to see the success message with the timeline of last completed as shown below.Image 49You 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 5010. Test your Policy settingsFinally, 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 51 If employees from other countries or regions ask the same question, it will fail with a message similar to the one shown below.Image 52This completes the setup process and a demo of how metadata / contextualization-based document grounding works for your employees. Happy Learning!!!Cheers,Nagesh CaparthyCredits: 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. Read More Technology Blog Posts by SAP articles
#SAP
#SAPTechnologyblog
