Behavioral Insights API Guide - help.sap.com

PUBLIC2020-11-05

Behavioral Insights API Guide

© 2

020

SAP

SE o

r an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

1 Experience Data Collector API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Getting Started with the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 API Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63.1 API Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63.2 Calling the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.3 Payload Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Field Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 PUBLICBehavioral Insights API Guide

Content

1 Experience Data Collector API

A new API is built in the Behavioral Insights (BI) application. The customer can use this API to import additional events from different source systems to the BI application. By consuming this API, customers can import different events from any other source system (for example, Qualtrics).

Behavioral Insights API GuideExperience Data Collector API PUBLIC 3

2 Getting Started with the API

This section gives you the basic information that you need to start working with the Behavioral Insights Experience Data Collector API.

Prerequisites

● The user must have the 'XperienceCollector' scope.● The CUSTOMER_ID of the incoming event must be available in the CUSTOMER_MASTER_DATA table.● There should be a mandatory entry of the new EVENT_ID with the external reference ID

(EXTERNAL_REFERENCE_ID) in the EVENT_CONFIG table.EXTERNAL_REFERENCE_ID (column name in EVENT_CONFIG table):The EXTERNAL_REFERENCE_ID contains a unique ID (for example, Survey Form ID, Form ID) from the external source system (for example, Qualtrics). The external reference ID is mapped to the EVENT_ID in the EVENT_CONFIG table. The corresponding EVENT_ID is inserted in the CUSTOMER_EVENTS table for the new incoming event from the external source system.

Authentication Mechanism

The API supports two authentication mechanisms:

1. Basic authentication2. oAuth 2.0 authentication

The API has different endpoints for the two different types of authentication mechanisms.

API URL

Follow the steps to get the API URL:

1. Open the XS CLI and login to the system with the user credentials.2. Run the following command xs apps.

This will list all the application names and the corresponding URLs of the available applications.3. Use the behavioral-insights-xperience-collector-web URL.

Endpoints of the API

There are 4 endpoints available in the API. The endpoints are as follows:

1. /XperienceCollector/basic/health/: Endpoint for basic authentication. It is a GET request and is used to get the CSRF token for making a POST call.


Getting Started with the API

2. /XperienceCollector/basic/save/: Endpoint for basic authentication. It is a POST request and is used to insert the data into the BI customer events table.

3. /XperienceCollector/oauth/health/: Endpoint for oAuth 2.0 authentication. It is a GET request and is used to get the CSRF token for making a POST call.

4. /XperienceCollector/oauth/save/: Endpoint for oAuth 2.0 authentication. It is a POST request and is used to insert the data into the BI customer events table.

Behavioral Insights API GuideGetting Started with the API PUBLIC 5

3 API Structure

3.1 API Definition

Request Headers for Different Endpoints

For each of the endpoints, the required headers are as follows:

Basic Authentication

● /XperienceCollector/basic/health/

Key Value

Authorization Basic (Username and Password)

Content-Type JSON

X-Csrf-Token fetch

● /XperienceCollector/basic/save/

Key Value


Content-Type JSON

X-Csrf-Token Token value from the GET response headers

oAuth 2.0 Authentication

● /XperienceCollector/oauth/health/

Key Value

Authorization Bearer <token>

Content-Type JSON


API Structure

Key Value

X-Csrf-Token fetch

● /XperienceCollector/oauth/save/



Content-Type JSON


Request Body Structure for the POST Call

The API supports JSON as the body format.

There are mandatory fields and some optional fields. The details are as follows:

Mandatory Fields

Field Name Description Data Type Max Length

CUSTOMER_ID Customer ID String 10

EXTERNAL_REFERENCE_ID Form ID String 20

Optional Fields


ACCOUNT_ID Account ID String 20

SUBACCOUNT_ID Subaccount ID String 20

ACCOUNT_DESCRIPTION Account description String 35

SUBACCOUNT_DESCRIPTION

Subaccount description String 35

DATE Submission date String (YYYY-MM-DD) -

TIME Submission time String (HH:MM:SS) -

VALUE Survey score Integer

TEXT1 Multiple Choice Question 1 - Text

String 200

TEXT3 Multiple Choice Question 2 - Text

String 200

TEXT4 Sentiment Question 1 - Text String 200

TEXT5 Sentiment Question 2 - Text String 200

TEXT2 Answer for Question 1 - Text String 200

Behavioral Insights API GuideAPI Structure PUBLIC 7


NUMBER1 Answer for Question 2 Integer -

NUMBER2 Sentiment Score for Sentiment Question 1

Integer -

NUMBER3 Sentiment Score for Sentiment Question 2

Integer -

3.2 Calling the API

Follow the steps below to call the API:

Basic Authentication

1. Call the API using the API URL. For fetching the API URL, see the steps in API Definition [page 6].2. Make a GET call with the /XperienceCollector/basic/health/ endpoint. This fetches the CSRF

token.3. Include the following parameters in the headers:

Key Value


Content-Type JSON

X-Csrf-Token fetch

4. In the response headers, you will get the X-Csrf-Token value.5. Update the headers with the CSRF token value and the request body with the data that needs to be

inserted. For the body structure, see the API Definition [page 6].6. Make a POST call with the /XperienceCollector/basic/save/ endpoint.

Headers for Post Call

Key Value


Content-Type JSON


oAuth 2.0 Authentication

1. Call the API using the API URL. For fetching the API URL, see the steps in API Definition [page 6].2. Generate the bearer token. For generating the bearer token, you need to know the required information

such as Username, Password, Client ID, Client Secret.1. Open the command prompt and login into the system with user credentials.


API Structure

2. Run the command xs env behavioral-insights-xperience-collector-web.This will list the information such as Client ID, Client Secret and URL.

3. Append the Access Token URL with /oauth/token.4. Select Password Credentials as the Grant Type.5. Enter BI username and password.

3. Once you get the bearer token, make a GET call to fetch the CSRF token by using the /XperienceCollector/oauth/health/ endpoint.

Header

Key Value

Authorization Bearer Token

Content-Type JSON

X-Csrf-Token fetch

4. Update the headers with the CSRF token value and the request body with the data that needs to be inserted. For the body structure, see the API Definition [page 6].

5. After getting the CSRF token, make a POST call with the /XperienceCollector/oauth/save/ endpoint.

Headers for Post Call

Key Value


Content-Type JSON


3.3 Payload Examples

Payload examples for Experience Data Collector API.

GET Requests

GET request to fetch the CSRF token (Basic Authentication)

URL: <Application-URL>/XperienceCollector/basic/health/

Headers:


Key Value


Content-Type JSON

X-Csrf-Token fetch

GET request to fetch the CSRF token (OAuth 2.0 Authentication)

URL: <Application-URL>/XperienceCollector/oauth/health/

Headers:

Key Value


Content-Type JSON

X-Csrf-Token fetch

POST Requests

POST request to insert data into CUSTOMER_EVENTS table (Basic Authentication)

URL: <Application-URL>/XperienceCollector/basic/save/

Headers:

Key Value


Content-Type JSON


POST request to insert data into CUSTOMER_EVENTS table (Basic Authentication)

URL: <Application-URL>/XperienceCollector/oauth/save/

Headers:

Key Value


Content-Type JSON



API Structure

Body for POST Call

Content-Type: JSON

Body:

Sample Code

{ "CUSTOMER_ID": <Customer ID>, "EXTERNAL_REFERENCE_ID": <External Reference ID>, "ACCOUNT_ID": <Account ID>, "SUBACCOUNT_ID": <Subaccount ID>, "ACCOUNT_DESCRIPTION": <Account Description>, "SUBACCOUNT_DESCRIPTION": <Subaccount Description>, "TEXT1": <Question 1 – Text>, "TEXT2": <Answer 1 – Text >, "TEXT3": <Question 2 – Text >, "TEXT4": <Descriptive Question 3 – Text>, "TEXT5": <Descriptive Question 4 – Text>, "NUMBER1": <Answer 2 - Number>, "NUMBER2": <Answer 3 - Number>, "NUMBER3": <Answer 4 - Number>, "TIME": <Submission Time in format HH: MM: SS>, "DATE": <Submission Date in format YYYY-MM-DD>, "VALUE": <Event Value>}


4 Field Mapping

This section provides details about mapping event table column to request payloads field.

CUSTOMER_EVENTS Column Name Request Body Fields

CUSTOMER_ID CUSTOMER_ID

ACCOUNT_ID ACCOUNT_ID

SUBACCOUNT_ID SUBACCOUNT_ID

ACCOUNT_DESCRIPTION ACCOUNT_DESCRIPTION

SUBACCOUNT_DESCRIPTION SUBACCOUNT_DESCRIPTION

EVENT_START_DATE DATE(YYYY-MM-DD) & TIME (HH: MM: SS)EVENT_START_MONTH

EVENT_VALUE VALUE

E_TEXT1 TEXT1

E_TEXT2 TEXT2

E_TEXT3 TEXT3

E_TEXT4 TEXT4

E_TEXT5 TEXT5

E_NUMBER1 NUMBER1

E_NUMBER2 NUMBER2

E_NUMBER3 NUMBER3

NoteThere is a field EXTERNAL_REFERENCE_ID in request payload which is checked with the column EXTERNAL_REFERENCE_ID in the EVENT_CONFIG table in order to retrieve the corresponding EVENT_ID. This is used while inserting a new event in the CUSTOMER_EVENTS table.


Field Mapping

5 Errors

The following errors will be thrown from the API.

Scenario Response Status Response Message

Validation of payload failure (various checks like optional/mandatory, length, type and so on)

422 (Unprocessable Entity) Validation error message generated by joi library, for example:

TIME format is incorrect

VALUE format is incorrect

NUMBER1 format is incorrect



Execution of query to find where the requested CUSTOMER_ID exists in the CUSTOMER_MASTER_DATA failed

500 (Internal Server Error) The requested CUSTOMER_ID does not exist in CUSTOMER_MASTER_DATA

The requested CUSTOMER_ID does not exist in the CUSTOMER_MASTER_DATA

422 (Unprocessable Entity) Customer ID not found. Please check the customer master data table.

Execution of query to find where the EVENT_ID for the corresponding EXTERNAL_REFERENCE_ID failed

500 (Internal Server Error) Error occurred trying to find the event ID

The EVENT_ID is not mapped with the requested EXTERNAL_REFERENCE_ID

422 (Unprocessable Entity) Event ID is not mapped to the external reference ID. Please check the event configuration table.

Failure in execution of query to insert the record in the CUSTOMER_EVENTS table

500 (Internal Server Error) Data cannot be inserted in the customer events table

Successful execution of query to insert the record in the CUSTOMER_EVENTS table

200 (Ok) Data inserted in the customer events table

Behavioral Insights API GuideErrors PUBLIC 13

Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Gender-Related LanguageWe try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.


Important Disclaimers and Legal Information

Behavioral Insights API GuideImportant Disclaimers and Legal Information PUBLIC 15

www.sap.com/contactsap

© 2020 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

https://www.sap.com/about/legal/trademark.html

Documents

Behavioral Insights API Guide - help.sap.com