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.
Customer Data Cloud accelerator offers some operations to be used by the user when working on a project, these are described next:
This operation will get 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.
This operation will recursively delete the src directory and execute the init operation.
This 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
This operation will run the build command and then process the files, for each site and each feature, that exist on build directory and send its data to the Cloud Data Customer console, using its REST API.
This operation will start a local development server. This server will execute the content of the cdc-accelerator/preview directory to render the content of the build directory. This will allow local development manual testing before deploying the data to the Customer Data Cloud's console
This operation will execute the unit tests implemented for each feature implemented on Customer Data Cloud accelerator
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 this operation the schema related data is obtained from a site and stored on different files on directory src/<partner-name>/Sites/<site-domain>/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 this 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 this 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 this 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 this operation the Policies are obtained from a site and stored on different files on directory src/<partner-name>/Sites/<site-domain>/Policies.
The files are called policies.json, which contains the policies policy-related data.
During this 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 this 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 this 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 webSdk data.
During this operation the webSdk related data is obtained from a site and stored on a different file on the directory src/<partner-name>/Sites/<site-domain>/WebSdk.
The files are called webSdk.json, which contains the data webSdk related data;
During this operation the WebSdk directory, of all sites that are configured on the configuration file, will be refreshed with the webSdk 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 this operation the webSdk 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 this operation the webSdk files are read from the build directory and it's 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 this operation the web screen sets related data is obtained from a site and stored on different files on directory src/<partner-name>/Sites/<site-domain>/WebScreenSets.
A subdirectory is created for each web screen set with the same name as the web screen set. The files are called .js, which contains the javascript code of the web screen set; .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 this 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 this 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 want to customize the css code, instead of changing the .default.css, he should create a new file .custom.css and during the build operation these files will be merged into a single file called .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 .js.
During this 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 site's email templates related data.
During this operation the email templates related data is obtained from a site and stored in different files in directory src/<partner-name>/Sites/<site-domain>/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 this 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 this 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/<partner-name>/Sites/<site-domain>/EmailTemplates/<templateName> 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 this 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.
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.
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 exapnd automatically to show the pretended resource.
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. 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.
Describe filter format