Customer Data Cloud Accelerator

About The Project

The SAP Customer Data Cloud accelerator is local development environment for SAP Customer Data Cloud.

It enables the use of all modern tools, including modern JavaScript and real source control. It provides code separation, enabling unit tests and quality checks.

Getting Started

To get started it is necessary to have git and node.js installed on the local machine.

1. Setup a CDC project

Execute the following commands:

# Create a new project
npm init

# Install @sap_oss/sap-customer-data-cloud-accelerator as a development dependency of the new project
npm install --save-dev @sap_oss/sap-customer-data-cloud-accelerator

# Setup a new CDC project with dependencies configuration files
npx cdc setup

2. Project Configuration

2.1 User Credentials

Edit the file .env in the project directory and add your credentials:

USER_KEY="ex: XXXXXXXX"
SECRET_KEY="ex: XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

2.2 Configuration file

Edit the file cdc-accelerator.json in the project directory and add the source site or sites you want to get the initial configuration from and sites to deploy to:

{
  "source": [
      { "apiKey": "XXXXXXXXXX" },
      { "apiKey": "YYYYYYYYYY" }
  ],
  "deploy": [
      { "apiKey": "XXXXXXXXXX" },
      { "apiKey": "YYYYYYYYYY" }
  ]
}

3. Usage

3.1 Get initial configuration from the source API Key(s)

npm run init

3.2 Start local development server

npm run start

Navigate to http://localhost:3000/ to see the preview.

The preview mode is a feature that allows the user to see and test the changes in the local environment, without the need to deploy the data to the SAP CDC console.

3.3 Run tests (optional)

npm run test

Runs any existing jest tests in the project.

3.4 Deploy the local data to the SAP CDC console

npm run deploy

Congratulations! You have successfully initialized and deployed a SAP Customer Data Cloud accelerator project.

Advanced Usage

Replace existing files with the code from the origin API Key(s)

It's similar to init, but replaces the contents of src/.

npm run reset

Get help about using the cli

This command will show all possible commands and options that the user can do.

npx cdc help

Example output:

Usage: npx cdc [options] [command]

A development environment for SAP Customer Data Cloud that enables the use of modern tools, such as JavaScript and source control.

Options:
  -V, --version     output the version number
  -h, --help        display help for command

Commands:
  start             Launch local server for testing using the preview functionality
  setup             Setup a new project after this dependency is installed
  init [options]    Reads the data from the SAP CDC console of the sites configured
  reset [options]   Deletes the local folder and reads the data from the SAP CDC console of the sites configured
  build [options]   Processes the local data and prepares it to be deployed to the SAP CDC console
  deploy [options]  Deploys the local data to the SAP CDC console on the sites configured
  help [command]    display help for command

Configuration

Feature Configuration

The Customer Data Cloud Accelerator allows reading, working locally and deploying data from the following features:

• Web SDK: WebSdk (Example Code)

• Web ScreenSets: WebScreenSets (Example Code)

• E-mail Templates: EmailTemplates (Example Code)

• SMS Templates: SmsTemplates (Example Code)

• Policies: Policies (Example Code)

• Schema: Schema (Example Code)

• Permission Groups: PermissionGroups (Example Code)

How to configure the use of features on the file cdc-accelerator.json

On the cdc-accelerator.json file, there are two mandatory properties that the user has to fill, the source and deploy. They both will have an array of objects that will contain the apiKeys that are related to the sites that we want to use in the project and optionally it will have the features, for example:

{
    "source": [
        {
            "apiKey": "1_QWERTYUIOPASDFGHJKLZXCVBNM",
            "features": ["Schema", "PermissionGroups", "WebSdk"]
        }
    ]
}

Example Code

An empty array will mean no feature will be available, for example:

{
    "source": [
        {
            "apiKey": "1_QWERTYUIOPASDFGHJKLZXCVBNM",
            "features": []
        }
    ]
}

How to use the feature-specific commands

Using the feature-specific command lets the user run a specific feature instead of running all of them when doing an operation (init, reset, build, deploy). To use them, simply write on the terminal

npm run <operation> -- -f <featureName>

For example:

npm run init -- -f Schema

In this example the user is only going to run the feature Schema when running the operation init, the feature name can be replaced by any other feature (Email Templates, WebScreenSet, PermissionGroup, WebSdk...). To show all the possible commands, the user can write simply

Features

WebSdk

You can separate the WebSdk into different files and use the import and export statements to organize the code. Using code segregation enables the use of unit tests and quality checks.

Example Code

webSdk.js

export default {
    // A comma-delimited list of provider names to enable.
    enabledProviders: '*',

    // Define the language of Gigya's user interface and error message.
    lang: 'en',

    // Bind globally to events.
    customEventMap: './customEventMap/customEventMap.js',

    // Custom global methods
    utils: './utils/utils.js',

    // Custom variables
    customPaths: './customPaths/customPaths.js',
}

customEventMap/customEventMap.js

export default {
    eventMap: [
        {
            events: '*',
            args: [
                function (e) {
                    return e
                },
            ],
            method: function (e) {
                if (e.fullEventName === 'login') {
                    // Handle login event here.
                } else if (e.fullEventName === 'logout') {
                    // Handle logout event here.
                    // console.log('here');
                }
            },
        },
    ],
}

utils/utils.js

export default {
    // Custom global methods
    customMethod: function () {
        // Custom method code
    },
}

customPaths/customPaths.js

export default {
    pathRedirectLogin: '/login',
    pathRedirectLogout: '/',
}

WebScreenSets

Using code segregation enables the use of unit tests and quality checks.

Example Code

WebScreenSets JavaScript

You can separate the WebScreenSets JavaScript code into different files and use the import and export statements to organize the code.

Default-RegistrationLogin.js

import customFunctionalityOnAfterScreenLoad from '.customFunctionalityOnAfterScreenLoad.js'

export default {
    onError: function (event) {},

    onBeforeValidation: function (event) {},

    onBeforeSubmit: function (event) {},

    onSubmit: function (event) {},

    onAfterSubmit: function (event) {},

    onBeforeScreenLoad: function (event) {},

    onAfterScreenLoad: function (event) {
        customFunctionalityOnAfterScreenLoad.exampleMethod()
    },

    onFieldChanged: function (event) {},

    onHide: function (event) {},
}

customFunctionalityOnAfterScreenLoad.js

import config from 'utils/config'

export default {
    pathRedirectLogin: config.get('customPaths.pathRedirectLogin', '/login'),
    pathRedirectLogout: config.get('customPaths.pathRedirectLogout', '/'),

    profileUpdateScreen: 'gigya-update-profile-screen',
    classLogoutButton: 'button-logout',

    exampleMethod: function () {
        const logoutButton = document.querySelector(`.${this.classLogoutButton}`)
        console.log({ logoutButton, pathRedirectLogout: this.pathRedirectLogout })
    },
    ...
}

utils/config.js

Utility function to get a value from the WebSdk.

export default {
    get(configName, defaultValue) {
        try {
            const properties = configName.split('.')
            return properties.reduce((acc, prop) => acc[prop] || defaultValue, gigya.thisScript.globalConf)
        } catch (e) {
            return defaultValue
        }
    },
}

WebScreenSets CSS

The CSS is separated into different files:

• default.css - The default CSS from SAP CDC.
• custom.css - The file to write all the custom CSS.

It's helpful to keep these files separate to avoid conflicts and to make it easier to maintain the code.

Example Code

Preview

The preview mode is a feature that allows the user to see and test the changes in the local environment, without the need to deploy the data to the customer data cloud console.

Example Code

How to use filters on preview

The filter is applied on the "src/index.html" file, that will filter the screens that the user will choose to see by using the apiKeys that are configured on the configuration file cdc-accelerator.json, for example:

[{
    apiKey: '1_2ABCDEFGHI345',
    screens: [{ screenSetID: 'PreferencesCenter-ProfileUpdate', screenID: 'gigya-update-profile-screen' }],
    emails: [ { emailID: 'codeVerification', languages: ['en'] } ]
}]

Using the filter on more than one apiKey

[{
    apiKey: '1_2ABCDEFGHI345',
    screens: [
        { screenSetID: 'PreferencesCenter-ProfileUpdate', screenID: 'gigya-update-profile-screen' },
        { screenSetID: 'PreferencesCenter-Landing', screenID: 'gigya-login-screen' },
    ],
    emails: []
},
{
    apiKey: '1_3AS9DJAKSLA12',
    emails: [{ emailID: 'doubleOptIn', languages: ['ar', 'en', 'pt-br'] }]
}]

Adding the filter to all the ApiKeys that do not have already a specific filter

[{
    apiKey: '*',
    emails: [{ emailID: 'doubleOptIn', languages: ['ar', 'en', 'pt-br'] } ]
}]

Using different options of preview

Using the different options of the preview will enable the user to control what he wants to see or filter.

• <origin>: Retrieves the settings available on the source or deploy inside the cdc-accelerator.json.

• <useLocalWebSdk>: Uses the local webSdk.js code that is inside the build/ directory.

• <useLocalScreenSets>: Uses the local screensets.js code that is inside the build/ directory.

• <filter>: Defines what was configured above, including specific apiKeys and screens/email.

• <lang>: Defines the language of the screen-sets, which can be changed according to user preference.

preview({
    origin: 'source',
    useLocalWebSdk: true,
    useLocalScreenSets: true,
    filter,
    lang: 'en',
})

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2023 SAP SE or an SAP affiliate company and sap-customer-data-cloud-accelerator contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.