README.md

Sample SAP Customer Data Cloud Extension

Scenario

This example includes a Kyma serverless function, cdc-extension, that is exposed as a SAP Customer Data Cloud extension endpoint, and demonstrates how to:

• Create an SAP Customer Data Cloud extension endpoint using a Kyma serverless function
• Deploy a Kyma serverless function and an API Rule using the Kubernetes command-line tool
• Alternately, deploy a Kyma serverless function and an API Rule using the Kyma Console User Interface
• Explore api.sap.com and try out REST API calls using a sandbox environment
• Use the SAP Data Quality Management microservice for location data to cleanse addresses

Notes:

• All the functionality presented here are subject to change and may be changed by SAP at any time for any reason without notice.
• For demonstration, this example uses an API Key to authenticate requests to SAP Data Quality Management. In a real-world scenario, either OAuth 2.0 or Client Certificate Authentication are to be used.

Solution Architecture

Sequence Diagram

Suggested introductory readings

• What is an SAP Customer Data Cloud Extension?
• An Introduction to SAP Customer Data Cloud Extensions (video)
• What is Kyma Environment?
• What is a Kyma Serverless Function?
• What is a Kyma API Rule?
• Project Kyma Documentation
• Administration and Operations in the Kyma Environment

Pre-requisites

• Provision SAP Customer Data Cloud from Gigya and setup an SAP Customer Data Cloud site.
• Get a Free Account on SAP BTP Trial*
• Enable SAP BTP, Kyma Runtime.
• Download and install the Kubernetes Command Line Tool.
• Test the kubectl installation.
• Download the Kyma Runtime kubeconfig.
• Create your api.sap.com account.

Deployment steps

1. Go to the kyma-runtime-extension-samples repository and clone it. This repository contains a collection of Kyma sample applications including this example (in the cdc-extension subfolder). Download the code by choosing the green Code button, and then choosing one of the options to download the code locally. Alternately, you can also run the following command using your command-line interface within your desired folder location:

   git clone https://github.com/SAP-samples/kyma-runtime-extension-samples`

   Note: The source code of this example is in the cdc-extension subfolder of this repository.

2. Update the values of the following environment variables in the ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml file: CDC_API_KEY, SAP_API_HUB_API_KEY, PUBLIC_KEY_KID, PUBLIC_KEY_N and PUBLIC_KEY_E

   • CDC_API_KEY - This is the API Key of the SAP Customer Data Cloud site and can be got from the SAP Customer Data Cloud console.
   • SAP_API_HUB_API_KEY - This is the API Key of SAP API Business Hub. Login to api.sap.com. Then, go to your profile settings and click on Show API Key to get the value for this variable.

   Go to "https://accounts.`SAP_Customer_Data_Cloud_Data_Center`/accounts.getJWTPublicKey?apiKey=`Your_SAP_Customer_Data_Cloud_Site_API_Key`".

   Find your SAP Customer Data Cloud Data Center. Replace SAP_Customer_Data_Cloud_Data_Center with your Data Center (For example, the US Data Center is us1.gigya.com). Replace Your_SAP_Customer_Data_Cloud_Site_API_Key with your SAP Customer Data Cloud site's API Key.

   The response JSON body will also include the following fields: kid, n and e

   • PUBLIC_KEY_KID - This is the value of the kid field in the response above.
   • PUBLIC_KEY_N - This is the value of the n field in the response above.
   • PUBLIC_KEY_E - This is the value of the e field in the response above.

3. Create a Kubernetes namespace with the name cdc.

   kubectl create namespace cdc`

   Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig

   Alternately, use the Kyma Console User Interface to create a new namespace

   • Open the Kyma console and click on Add new namespace. Enter its name as cdc and click the Create button.

4. Create/update Kubernetes resources of the cdc-extension serverless function.

   kubectl apply -f ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml
   kubectl apply -f ./kyma-runtime-extension-samples/cdc-extension/k8s/api-rule.yaml

   Note: As a prerequisite, please follow the steps listed in the following tutorial: Download the Kyma Runtime kubeconfig

   The resources are represented as declarative YAML objects. Applying the resources will perfom the following steps:

   • Deploy the Kyma serverless function
   • Expose the serverless function using a Kyma API Rule that will serve as the SAP Customer Data Cloud Extension endpoint

   Alternately, deploy the Kyma serverless function and API Rule using the Kyma Console User Interface:

   • Open the Kyma console and select the cdc namespace.
   • Click on Workloads. Then, click on Deploy new workload and select Upload YAML.
   • Then, click on Browse to select the following YAML file, and click on Deploy: ./kyma-runtime-extension-samples/cdc-extension/k8s/function.yaml
   • Repeat the above steps and select the following YAML file. Then, click on Deploy: ./kyma-runtime-extension-samples/cdc-extension/k8s/api-rule.yaml

5. Go to the Kyma Console -> cdc namespace -> Discovery & Network -> API Rules. Copy the host URL of the cdc-extension API Rule.

6. Then, go to the SAP Customer Data Cloud Console. Select your site and click on Extensions -> Add.

7. Enter any Name, select the API as accounts.setAccountInfo (OnBeforeSetAccountInfo), enter any Description, paste the host URL from step 5 above and click on Advanced. Then, enter the Timeout as 1000 ms, select the Fallback Policy as FailOnAnyError and click Save.

8. In the SAP Customer Data Cloud Console, select your site and click on Schema in the left menu under Registration-as-a-Service.

9. Set the following schema fields to be Required and select Write Access as clientModify for all of them. Then, click Save Changes.

   • profile.address
   • profile.city
   • profile.state
   • profile.zip
   • profile.country

10. In the SAP Customer Data Cloud Console, select your site and click on Screen-Sets in the left menu under Registration-as-a-Service.

11. Click on the Default-RegistrationLogin screen-set.

12. Select the Registration Completion screen from the dropdown.

13. Add four Textbox components and one Dropdown component to the SAP Customer Data Cloud Registration Completion screen and map them to the following fields.

    • profile.address
    • profile.city
    • profile.state
    • profile.zip
    • profile.country

Steps to test the solution

1. Register an account in your SAP Customer Data Cloud site.

   Note: This can also be done by previewing the registration screen of the Default-RegistrationLogin screen-set in the SAP Customer Data Cloud console.

2. The Registration Completion screen will be displayed. Enter an invalid address and click the Submit button. An error message will be returned.

3. Fix the address and click the Submit button. The form should be processed successfully.

4. View the details of the account that was registered in the Identity Access screen of the SAP Customer Data Cloud console. It can be observed that the address of the user has been cleansed.

Troubleshooting steps

Check the logs of your Kubernetes pods

• To see the logs of a specific function, open the function in the Kyma console (Go to Workloads > Functions > cdc-extension) and you will see the logs in an expandable window at the bottom of the page.

• Alternately, go to Workloads > Pods in the Kyma Console (within the cdc namespace) to see the list of all running pods. Then, click on the three dots to the right of the running pod of the cdc-extension function, and click on Show Logs to see the logs of the pod.

• Or use the following kubectl to get the list of pods running in the cdc namespace.

  kubectl get pods -n cdc

• Then, to see the logs of any of the pods, use the following syntax:

  kubectl logs <pod-name> -n <namespace-name>

  Example:

  kubectl logs cdc-extension-65khj-58b6d69cd9-l7dgs -n cdc