Technical Documentation
Before any new PR is done, a test case should run following the steps described below:
- Rename src/ to _src/
$ npm run init- Delete the new src/ and rename _src/ to src/
$ npm run build- Check configurations of
cdc-accelerator.preferences-center.com/inbuild/including the imported JS files in thewebSdk.jsfile and thePreferencesCenter-Landing.jsscreen-set $ npm start- Check if features look okay in the preview and without errors in the console
$ npm run deploy- Validate if configurations on /build were correctly sent to CDC
- Check the PR build result on jenkins https://onestrike.jaas-gcp.cloud.sap.corp/job/cx-servicesautomation/job/sap-customer-data-cloud-accelerator/view/change-requests/
To start using Customer Data Cloud accelerator please do the following actions:
- Clone this github repository to a local directory
- Create a project with your preferred IDE (e.g. VSCode)
- Install all project dependencies using the command
npm install. It is assumed that you already have node and npm installed, if not please do it first - Define project configuration:
Open or create the file .env and define the value of the properties USER_KEY and SECRET_KEY. These are the credentials used to access Cloud Data Customer console. Open or create the file cdc-accelerator.json and define the sites' info that you want to work with. See configuration chapter for details.
- Execute the command
npm run update-sap-cdc-toolkitto update the code of a dependency used to interact with Customer Data Cloud. This command will add the directory cdc-accelerator/sap-cdc-toolkit inside the project with the dependency source code.
At this point you are ready to start working on the Customer Data Cloud accelerator project or on a Customer Data Cloud's customer project.
To start working on a project the first thing to do is to prepare the configuration file. The next section will explain the configuration content.
An example configuration file is provided on the project root and is called cdc-accelerator.json. Its content is a JSON object which contains three sections that will be described on the next sections. The following image shows an example of the content of the configuration file:
TODO add configurationFile.png
The source property is mandatory to be filled by the user, it contains an array of objects that are related to sites. The JSON object contained in the source array can have the following properties:
- apiKey - mandatory property, its value is a string containing the api key of the site that we want to use in the project.
- features - optional property, its value is an array of strings. Each string contains the name of the feature that we want to have available to work on the specified site. If not provided all the features will be available. If provided an empty array no features will be available.
The source section will be used by the application to know which sites data will be collected and processed on the operations init and reset.
The deploy property is mandatory to be filled by the user, it contains an array of objects that are related to sites. The JSON object contained in the deploy array can have the following properties:
- apiKey - mandatory property, its value is a string containing the api key of the site that we want to use in the project.
- features - optional property, its value is an array of strings. Each string contains the name of the feature that we want to have available to work on the specified site. If not provided all the features will be available. If provided an empty array no features will be available.
The deploy section will be used by the application to know which sites data will be updated during the operation deploy.
The cache property should not be edited by the user. It is generated by the application to store useful data that is time consuming to obtain. It contains an array of objects that are related to sites. The JSON object contained in the cache array can have the following properties:
- apiKey - its value is a string containing the api key of a site configured in the source or deploy properties.
- baseDomain - its value is a string containing the domain of the specified site.
- dataCenter - its value is a string containing the data center of the specified site.
- partnerId - its value is a number containing the partner id of the specified site.
- partnerName - its value is a string containing the partner name of the specified site.
The cache section will be used internally by the application.
Customer Data Cloud accelerator offers some operations to be used by the user when working on a project, these are described next:
The init operation will read the data from the site(s) configured on file cdc-accelerator.json.
It creates a src directory and one to many subdirectories named with the site domain. Inside the subdirectories, is also created a directory, for each feature, that will have files containing feature related data.
This feature will only work if the src directory do not exists, otherwise it will show an error, saying that data already exists and to use the reset operation to start from scratch.
These files in src directory are the ones to work with by the user.
The reset operation will recursively delete the src directory and execute the init operation.
The build operation will process the files, for each site and each feature, that exist on src directory and bundles them, in a way to be prepared to be sent to the Cloud Data Customer console. These processed files are stored in the build directory containing the same directory structure as the src directory
The deploy operation will run the build command and then process the files, for each partner, site and feature, that exist on build directory and send its data to the Cloud Data Customer console, using its REST API.
The start operation will start a local development server. This server will execute the file src/index.html, that uses the content of the cdc-accelerator/preview directory, to render the content of the build directory. This will allow local development and manual testing before deploying the data to the Customer Data Cloud's console
The test operation will execute the unit tests implemented for each feature implemented on Customer Data Cloud accelerator
Besides the npm scripts a CLI can be used to execute all operations. The CLI is used by executing the command npx cdc <operation>.
To quicky check the possible commands and options the helpcommand should be executed:
npx cdc help
The output will be something like:
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 cdc console of the sites configured
reset [options] Deletes the local folder and reads the data from the cdc console of the sites configured
build [options] Processes the local data and prepares it to be deployed to the cdc console
deploy [options] Deploys the local data to the cdc console on the sites configured
help [command] display help for command
It is possible to get help for a specific command, e.g:
npx cdc help init
The output will be something like:
Usage: npx cdc init [options]
Reads the data from the cdc console of the sites configured
Options:
-f, --feature [feature] Single feature to be executed (choices: "PermissionGroups", "EmailTemplates", "Policies", "Schema", "SmsTemplates", "WebScreenSets", "WebSdk")
-h, --help display help for command
The working directory structure can be seen on the next image:
There are two kind of features: partner features, which executes on partner level and site features, which executes on site level. The next chapter will describe the site features.
This feature allows a user to change a site's schema related data.
During the init operation the schema related data is obtained from a site and stored on different files on directory src//Sites//Schema.
The files are called data.json, which contains the data schema related data; profile.json, which contains the profile schema related data; and subscriber.json, which contains the subscriber schema related data.
The following image shows the schema related data on Customer Data Cloud console:
During the reset operation the Schema directory, of all sites that are configured on the configuration file, will be refreshed with the schema data of the sites. More detailed the Schema directory, of all sites that are configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the schema files are simply copied from the src directory to the build directory, maintaining the directory structure.
There is no need to perform any transformation on the files
During the deploy operation the schema files are read from the build directory and its content sent to Customer Data Cloud console using its REST API.
This feature allows a user to manage a site's policy-related data.
During the init operation the policies are obtained from a site and stored on different files on directory src//Sites//Policies. The files are called policies.json, which contains the policies related data.
During the reset operation the Policies directory, of all sites that are configured on the configuration file, will be refreshed with the policies data of the sites. More detailed the Policies directory, of all sites that are configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the policies files are simply copied from the src directory to the build directory, maintaining the directory structure.
There is no need to perform any transformation on the files
During the deploy operation the policies files are read from the build directory and its content sent to Customer Data Cloud console using its REST API.
This feature allows a user to manage the web SDK data.
During the init operation the web SDK related data is obtained from a site and stored on a different file on the directory src//Sites//WebSdk. The files are called webSdk.json, which contains the web SDK related data;
During the reset operation the WebSdk directory, of all sites that are configured on the configuration file, will be refreshed with the web SDK data of the sites. More detailed the WebSdk directory, of all sites that are configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the web SDK files are simply copied from the src directory to the build directory, maintaining the directory structure. There is no need to perform any transformation on the files
During the deploy operation the web SDK files are read from the build directory and its content is sent to the Costumer Data Cloud console using it's REST API.
This feature allows a user to change a site's web screen sets related data.
During the init operation the web screen sets related data is obtained from a site and stored on different files on directory src//Sites//WebScreenSets.
A subdirectory is created for each web screen set with the same name as the web screen set. The files are called <webScreenSet>.js, which contains the javascript code of the web screen set; <webScreenSet>.default.css, which contains the style sheets code of the web screen set.
The following image shows the web screen set related data on Customer Data Cloud console:
During the reset operation the WebScreenSets directory, of all sites that are configured on the configuration file, will be refreshed with the web screen set data of the sites. More detailed the WebScreenSets directory, of all sites that are configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the web screen set files that exists on the src directory are processed and bundled together in the build directory. The src directory can have several files, more than the initially created during the init operation. For example if the user wants to customize the css code, instead of changing the <webScreenSet>.default.css, he should create a new file <webScreenSet>.custom.css and during the build operation these files will be merged into a single file called <webScreenSet>.css. The same can happen with the javascript files, instead of adding lots of code into a single file, we can write the code in several modules, a file can import code from other files and during the build operation these files will be merged into a single file called <webScreenSet>.js.
During the deploy operation the web screen set files are read from the build directory and its content sent to Customer Data Cloud console using its REST API.
This feature allows a user to change a partner's permission group and acl related data.
During the init operation the permission group's related data are obtained from a partner and stored in a JSON file in the directoru src//PermissionGroups. The built-in permission groups (groups that start with the character '_') are removed, so the user can't modify those. The file is called PermissionGroups.json, which contains the permission groups related data.
During the reset operation the PermissionGroup directory, will be refreshed with the permission group set data of the partner. More detailed the PermissionGroup directory, of the partner that is configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the permission groups are simply copied from the src directory to the build directory, maintaining the directory structure. There is no need to perform any transformation on the files.
During the deploy operation the permission group files are read from the build directory and its content is sent to the selected partner console using it's REST API.
This feature allows a user to change a partner's acl related data.
During the init operation the acl related data are obtained from a partner and stored in a JSON file in the directoru src//PermissionGroups/Acl. Inside the directory ACL, the number of files will be equal to the number of acl's a partner has, except the build-in acl's, those are removed when writing to the files, so the user can't modify them. The file is called .json, each file will have the ACL for it's aclID.
Since the acl's are inserted on the directory of the permission groups, the reset used on the feature Permission Groups already refreshes the directory src//PermissionGroups so there's no need for any reset method. After the user chooses to have make a reset operation, the init is triggered on the permission group feature and the acl init is also triggered.
During the build operation the acl files are simply copied from the src directory to the build directory, maintaining the directory structure. There is no need to perform any transformation on the files.
During the deploy operation the acl files are read from the build directory and its content is sent to the selected partner console using it's REST API endpoint.
This feature allows a user to change a site's email templates related data.
During the init operation the email templates related data is obtained from a site and stored in different files in directory src//Sites//EmailTemplates. Two subdirectories are created for each email template:
- locales - will contain several subdirectories, one for each email template, each one containing one or more translation files. The filename's pattern is
<locale>.json.
The following image shows the project structure of the locales subdirectory:
- templates - will contain one or more template files. The filename's pattern is
<emailTemplateName>.html.
The following image shows the project structure of the templates subdirectory:
The following image shows the email templates related data on Customer Data Cloud console:
During the reset operation the EmailTemplates directory, of all sites that are configured on the configuration file, will be refreshed with the email templates data of the sites. More detailed the EmailTemplates directory, of all sites that are configured on the configuration file, will be deleted and then it is executed the init operation.
During the build operation the email templates files that exists on the src directory are processed and bundled together in the build directory.
Two subdirectories are processed, during the build operation, for each email template:
- locales - which contain several subdirectories, one for each email template, each one containing one or more translation files.
The locale's files contains an JSON object with all the keys translated to the language of the file.
For example:
{
"FROM": "Someone <address@domain.com>",
"SUBJECT": "Welcome",
"GREETING": "Hi",
"BYE": "Best regards",
}
This means that each occurrence of the following template message FROM, in the email template, will be replaced with the string Someone <address@domain.com> and its content stored in the directory build//Sites//EmailTemplates/ on the file <templateName>-<locale>.html. A file will be generated per each locale of the email template with its content already translated.
The following image shows the project structure of the build subdirectory and the email template files:
- templates - will contain one or more template files.
The templates' files contains an HTML string with all the email template content.
For example:
...
<td align="left"
style="font-family: Arial,sans-serif;color: #60646c;text-align: left;font-size: 15px;">
{{GREETING}}<br /><br />
{{BYE}},<br />
</td>
...
This means that each occurrence of the template message {{GREETING}}, will be replaced with the string Hi for the specific locale, in this case en.
The translation is done using the mustache dependency, for more details about the templates configuration see its documentation page.
During the deploy operation the email templates' files are read from the build directory and its content sent to Customer Data Cloud console using its REST API.
The preview mode is a feature of the accelerator tool that allows the users to see and test the changes in the local environment, without the need to deploy the data to the customer data cloud console. Currently, it supports two features: web screen sets and email templates.
To make it available execute the following command: npm run start This will start an NGINX server, that will execute the src/index.html file and performs a build operation to generate the local files stored in the build directory and then loads them in a browser window. If the src/index.html file do not exists a template file existing on src/cdc-accelerator/templates/preview/index.html will be copied to src/index.html and will be used.
To stop the server press the keyboard keys ctrl + c.
The menu can be used to navigate on the preview page. Alternatively, the user can change the url to navigate directly to a web screen set or email template and the menu will expand automatically to show the pretended resource.
The menu was implemented using the plugin bs5treeview.
The following image shows the preview menu options:
The menu contains 6 entries that will be described in the next sections.
The site selector list is populated with the data present on the configuration file cdc-accelerator.json, more specifically, in the source section. A site selector entry contains the site domain followed by the partner name. Selecting a site will reload the page to load the web screen sets and email templates from that site.
The following image shows the selector expanded:
The WebScreenSets entry can be expanded to show all the site's web screen sets. Each web screen set can also be expanded to show all of its web screens. When clicking on a web screen its content is loaded in the right side of the page and the user can interact with the web screen to test its functionality.
The following image shows the entry WebScreenSets expanded:
The EmailTemplates entry can be expanded to show all the site's email templates. Each email template can also be expanded to show all of its locales. When clicking on a locale the email template is loaded in the right side of the page, with the specific locale and the user can interact with the email template to test its functionality.
The following image shows the entry EmailTemplates expanded:
The Logout entry will logout the user from the customer data cloud console.
The Show Debug UI entry will show a bar with some debug information
The Enable Event Logger entry will enable gigya's logger. The browser console must be open the see the data.
The preview code is on directory cdc-accelerator/preview. The preview function receives a JSON object as argument, with the following properties:
- apiKey: apiKey to be used, by default it is used the apiKey from the preview URL
- origin: the name of the section in the configuration files that will be used to load the sites' apiKeys. The default value is 'deploy'
- useLocalWebSdk: boolean to decide if the web sdk file should be the local one or retrieved from the customer data cloud console. The default value is true
- useLocalScreenSets: boolean to decide if the web screen sets data to load should be the local one or retrieved from the customer data cloud console. The default value is true
- lang: The language of the web screen sets. The default value is 'en'.
- filter: Filters the content that should be presented on the preview. It's an array of JSON objects, each object is a filter for a specific apiKey.
The filter argument allows the user to filter what (s)he wants to see, if no filter is specified all the data is shown. The filter it's an array of JSON objects, each object is a filter for a specific apiKey. For example:
[{
apiKey: '1_2ABCDEFGHI345',
screens: [{ screenSetID: 'PreferencesCenter-ProfileUpdate', screenID: 'gigya-update-profile-screen' }],
emails: [ { emailID: 'codeVerification', languages: ['en'] } ]
}]
In the example above the filter contains one filter for the api key '1_2ABCDEFGHI345'. All other api keys existing in the configuration file will have no filter active. When selecting the example api key in the preview, only one web screen set and one email template will be displayed, due to the example filter configuration.
Another example of a filter configuration can be:
[{
apiKey: '1_2ABCDEFGHI345',
screens: [
{ screenSetID: 'PreferencesCenter-ProfileUpdate', screenID: 'gigya-update-profile-screen' },
{ screenSetID: 'PreferencesCenter-Landing', screenID: 'gigya-login-screen' },
],
emails: []
},
{
apiKey: '*',
emails: [{ emailID: 'doubleOptIn', languages: ['ar', 'en', 'pt-br'] } ]
}]
In the example above the filter contains two filters, one for the api key '1_2ABCDEFGHI345' and another for all other api keys existing in the configuration file, due to the '*' in the apiKey property. When selecting the api key '1_2ABCDEFGHI345' in the preview, two web screen sets and no email templates will be displayed. When selecting a different api key all web screen sets and one email template 'doubleOptIn' with the locales 'ar', 'en' and 'pt-br' will be displayed.
The preview functionality uses some core classes, like Gigya, Navigation and Configuration and feature classes, like WebScreensSets and EmailTemplates. When adding a new feature class the following methods must be implemented:
- isChanged: this function returns true if the feature needs to react to a change, false otherwise
- onChanged: this function displays the content that should be presented to the user
- getMenu: this function returns the menu data that should be presented to the user
The Gigya class requests and loads the customer data cloud Web SDK. It makes available a global object called gigya.
The Navigation class handles the URL hash and the sites to load. Each time the URL changes or a menu item is selected the Navigation class handles it.
The Configuration class reads the data from the configuration file.
The WebScreenSets class handles all the functionality regarding web screen sets. Reads the web screen set data files (javascript and css), displays the web screens sets and provides the web screen sets menu data.
The EmailTemplates class handles all the functionality regarding email templates. Reads the email templates data files, displays the email templates and provides the email templates menu data.