Technical Documentation
It is a Chrome extension for the SAP Customer Data Cloud console. The design language is the same used in the SAP Customer Data Cloud console, to decrease learning time and to facilitate the add-ons integration in the existing UI.
Site Deployer: Easily create big and complex site structures with patterns based on existing best practices instead of creating sites one by one manually.
Copy Configuration Extended: The same functionality of "Copy Configuration" but with a "1 to many" approach, adding missing functionalities (copy Site Policies, Social Providers, E-mail Templates).
Export / Import E-mail Templates: Export and import e-mail templates in bulk, reducing human error and increasing productivity
Export / Import SMS Templates: Export and import SMS templates in bulk, reducing human error and increasing productivity
Site deployer integration with Copy Configuration: Integration with “Copy Configuration Extended” using a “Main Template” to deploy sites with custom configurations.
Use the Chrome Extension manifest file "/public/manifest.json" to update the "/build/manifest.json" file with the generated script files from "static/js" and "static/css".
All functions used to inject the containers and buttons to the SAP Customer Data Cloud Console DOM, as well as managing the browser navigation.
Functions necessary to inject the menu buttons into the SAP Customer Data Cloud Console DOM, as well show them and hide them when depending on the state of the app.
Functions necessary to inject the main container for the React app.
Functions that watch the browser URL hash and show correct containers based on that information, so that the user can not only use the menu buttons but also the back and forward buttons of the browser.
Functions necessary to inject the placeholder for the menu button on the top bar. The button and popup are injected in React, on the src/App.js file by the element "<CredentialsPopoverButton/>".
The entry point for the React componentes.
This is the root component to site deployment. It defines the entire page layout and contains all necessary input fields and handler functions to create a site structure from a template (Create) or manually (Add Parent Site) and buttons to submit it (Save) or clean the structure (Cancel). In this component, the required fields are also checked:
- Create button will only be enabled when a Site Domain is set, when a Site Structure is selected and when at least one Data Center is selected.
- Save button will only be enabled when all parent and child sites have a Site Domain set and a Data Center selected.
The data center selection was implemented using a MultiComboBox whose values are populated from the dataCenters global state property.
The supported data centers are specified in the dataCenters.json file.
Different data centers are supported on different consoles:
- the console console.gigya.com supports all of them
- the console console.eu2.gigya.com only supports the EU data center
- the console console.cn1.gigya.com only supports the CN data center
The Site Structure selection was implemented using a Dropdown whose values are loaded from the file src/redux/siteStructures/siteStructures.json into the Redux siteStructuresSlice that exposes them.
This component is embedded into the Site Deployer component and consists of a Table that is populated with both Parent and Child row components.
This component contains the fields that are needed to define a Parent Site in the structure and also the necessary functions to update them, to add Child Sites and to delete the Parent Site with its Child Sites. To implement these last two features an ActionSheet was introduced:
This component is used in the sites-table-parent-row component to show/hide its Child Site list using Arrow Buttons:
This component contains the fields that are needed to define a Child Site in the structure and also the necessary functions to update them and to delete the Child Site. To implement this feature an ActionSheet was also used:
Used to manage application’s Site Deployer global state and export functions (reducers) to update it. Also exports the function sitesAsyncThunk where the call to SiteManager create function is performed. The global state consists in:
- A Sites array, the structure that stores the page input values;
- An isLoading boolean property, used to monitor when the creation process is getting executed and show or hide a BusyIndicator accordingly;
- An Error array, that is used to store error messages when they occur;
- A showSuccessDialog boolean property, used to detect when Site Deployment creation occurred without errors and show a success message dialog.
Used to store and expose application’s Data Centers global state. The global state consists in:
- A Data Centers array, loaded with the configured data centers stored in the file src/redux/dataCenters/dataCenters.json and filtered by the correspondent Gigya console present in the current hostname.
Used to store and expose application’s Site Structures global state. The global state consists in:
- A Site Structures array, loaded with the configured site structures stored in the file src/redux/siteStructures/siteStructures.json.
Used to manage application’s Credentials global state and export functions (reducers) to update it. Also exports the function updateCredentialsAsync that triggers (from the useEffect hook) the update of the state credentials object properties. The global state consists in:
- The Credentials object, that consists of two properties - user key and secret key;
- An isPopUpOpen boolean property, used to detect if the credentials pop up is open for manual credentials input.
Used to manage application’s Email templates global state and export functions (reducers) to update it. Also exports the functions getEmailTemplatesArrayBuffer and sendEmailTemplatesArrayBuffer (called in email-templates-component.jsx and in emails-import-popup.component.jsx respectively) where the call to EmailManager export and import functions are performed. The global state consists in:
- An exportFile property, to store the file that is exported from the EmailManager export function;
- An isLoading boolean property, used to monitor when the creation process is getting executed and show or hide a BusyIndicator accordingly;
- An errors array, used to store import or export errors if the occur;
- An isImportPopupOpen boolean property, used to control the emails-import-popup.component.jsx open/close functionality;
- A showSuccessDialog boolean property, used to control the show success dialog on import.
Used to manage application’s SMS templates global state and export functions (reducers) to update it. Also exports the functions getSmsTemplatesArrayBuffer and sendSmsTemplatesArrayBuffer (called in sms-templates-component.jsx and in sms-import-popup.component.jsx respectively) where the call to SmsManager export and import functions are performed. The global state consists in:
- An exportFile property, to store the file that is exported from the SmsManager export function;
- An isLoading boolean property, used to monitor when the creation process is getting executed and show or hide a BusyIndicator accordingly;
- An errors array, used to store import or export errors if the occur;
- An isImportPopupOpen boolean property, used to control the sms-import-popup.component.jsx open/close functionality;
- A showSuccessDialog boolean property, used to control the show success dialog on import.
Used to manage application’s version information as global state. Exports the function checkNewVersion, used to update the version information from the back-end. When a new version is detected, a badge is displayed on the credentials popover button and a message is displayed on the credentials popup.
Used to manage application’s copy configuration extended information as global state and export functions (reducers) to update it. Also exports the functions below that are called in the copyConfigurationExtended component:
- getConfigurations and setConfigurations, where ConfiManager getConfigurations and copy functions are performed;
- getAvailableTargetSites, where siteFinderPaginated getFirstPage and getNextPage functions are performed;
- getCurrentSiteInformation and getTargetSiteInformation, where ConfigManager getSiteInformation function is performed.
The global state consists in:
- A currentSiteApiKey property, that is initialised from the current api key present in the URL when the component loads;
- A configurations array, used to populate the configuration trees and update their checkboxes state;
- An errors array, used to store errors that may occur while getting or copying the configurations;
- An apiCardError, used to store errors related to the getTargetSiteInformation requests;
- An isLoading boolean property, used to monitor when the creation process is getting executed and show or hide a BusyIndicator accordingly;
- A targetSites array, used to store the site api keys to where the configurations should get copied;
- A showSuccessMessage boolean property, used to control the show success dialog on copy;
- An availableTargetSites array, used to store the list with the information of the available target sites used in input suggestions;
- A currentSiteInformation object, that is used to store the api key and base domain of the current site;
- An isTargetInfoLoading boolean property, used to monitor if the the request to obtain information about a target site is getting performed.
Used to manage applications's import accounts information as a global stae and export functions (reducers) to update it. Also exports the functions below that are called in the importAccounts component:
- getConfigurationTree, setConfigurations, where importAccounts getConfigurationTree and export options are performed;
The global state consists in:
- A currentSiteApiKey property, that is initialised from the current api key present in the URL when the component loads;
- A configurations array, used to populate the configuration trees and update their checkboxes state;
- A parent node, used to get the node hier in the tree hierarchy;
- An errors array, used to store errors that may occur while getting or copying the configurations;
- An isLoading boolean property, used to monitor when the creation process is getting executed;
- A showSuccessMessage boolean property, used to control the show success dialog on exporting;
- A currentSiteInformation object, that is used to store the api key and base domain of the current site;
- A selectedConfiguration array, used to populate the configuration tree and update their checkboxes statate from the search input;
Used to manage application’s site deployer copy configuration information as global state and export functions (reducers) to update it. Also exports the functions below that are called in the copyConfigurationDialog component:
- getSourceSiteInformation, where ConfigManager getSiteInformation function is performed;
- getSourceSiteConfigurations, where ConfiManager getConfigurations function is performed.
The global state consists in:
- A sitesConfigurations array, used to populate the configuration trees and update their checkboxes state;
- An isLoading boolean property, used to monitor when the getSourceSiteConfigurations function is getting executed and show or hide a BusyIndicator accordingly;
- An isSourceInfoLoading boolean property, used to monitor when the getSourceSiteInformation function is getting executed and show or hide a BusyIndicator accordingly;
- An errors array, used to store errors that may occur while getting the configurations;
- An apiCardError, used to store errors related to the getSourceSiteInformation requests;
- A siteId string, used to store the id of the site associated to the current configuration setting;
- An edit boolean property, used to identify if the copyConfigurationDialog is being executed in edit mode (i.e., changing an already set configuration);
- An isCopyConfigurationDialogOpen boolean property, used to identify when the copyConfigurationDialog is open or not;
- A sourceSiteAdded boolean property, used to flag when a new source site is selected.
Used to manage application’s target site tooltip icon information as global state and export functions (reducers) to update it. The global state consists in an isMouseOverIcon boolean property, used to trigger the display of the information popover.
Used to configure the reducers exported from all *Slice.js files into the React Redux engine.
This component is used to quickly inform the user that an error occurred on a specific Site Deployment creation. It is shown in an additional table column in both sites-table-parent-row and sites-table-child-row components:
On button click, a ResponsivePopover is shown with the error message details:
This component is used to show in detail each error that occurred when the user tried to perform a Site Deployment creation:
Used to show a list of message-list-item components with multiple error messages corresponding to all errors that occurred for all Site Deployments. If error with different severities occurred, it is possible to filter the list by severity type.
This component is used to show a success message when Site Deployment creation was successful in the Site Deployer component. After clicking "Ok", a redirect to the Site Selector page is performed.
It is also used to show when Email and SMS templates are imported without errors. For Email Templates, the count of the imported templates is also calculated and part of the message:
In the Email Templates tab and in the SMS Templates tab, it is also used to display Import and Export Errors:
When only some Email templates were imported, the count of the imported templates is also calculated and part of the message:
This component is used to display HTML validation erros when importing HTML Email Templates. The user still has the option to continue the import anyway:
This component is used to define the Email templates Export All and Import All buttons that are injected into the standard SAP Customer Data Cloud Email Templates page.
This component is used to define the SMS templates Export All and Import All buttons that are injected into the standard SAP Customer Data Cloud Email Templates page.
In this component, it was implemented the popup used to select a zip file containing the HTML email templates to import, open when the Import All button is clicked:
In this component, it was implemented the popup used to select a zip file containing the HTML SMS templates to import, open when the Import All button is clicked:
This component is used to display an error message when the user is performing an action that requires its credentials but these are empty. It consists of a wrapper for the dialog-message-dialog.component.jsx specifically parametrised to show this particular error case.
This component is used to show a confirmation Popup when the rollback action failed and some sites that were created need to be manually removed. The popup locks the screen until the user checks the acceptance Checkbox which will enable the Confirm button. On checking the Checkbox, the site list is automatically copied to the clipboard with a Toast getting shown informing that that action was performed.
This is the Copy Configuration Extended page main component. It consists of a container for displaying the current site information and an input to search for the target api keys, a container to display the configuration tree and their checkboxes and a bar with the Save and Cancel buttons. Also makes available to the user a checkbox to select or unselect all configuration checkboxes and a button to unselect all links and credentials' configuration, more specifically Social Identities, some email links and some policies' links:
This component is used to recursively display a configuration tree and its branches. It is used in the site-configurations.component.jsx.
This component is used to display all configuration trees for a given site. It was meant to be re-used in both copy-configuration-extended.component,jsx and copy-configuration-dialog.component.jsx.
This component is used to allow the search for sites. It was meant to be re-used in both copy-configuration-extended.component,jsx and copy-configuration-dialog.component.jsx. In the first component, the input is used to search for target sites to where the source configurations will be copied to. In the second component, the input is used to search for the source site, from where the configurations are going to be copied from to the new site that will be created.
Since the list of available target sites may not always be updated with recently created sites, this component was introduced to display an icon with a pop over when hovered on, to inform the user about that. It is re-used in both copy-configuration-extended.component,jsx and copy-configuration-dialog.component.jsx.
This component is used to display the list of target-api-key-item.components.js. It is re-used in both copy-configuration-extended.component,jsx and copy-configuration-dialog.component.jsx.
This component is used to display the details of each site obtained with the search-sites-input.component.jsx.
To integrate the copy configuration feature with the site deployer feature, this component was introduced. It allows the user to select a source site and its configurations so they can be copied to the new site when it is created. It is called in the sites-copy-configuration-button-pannel.component.jsx.
src/components/sites-copy-configuration-button-pannel/sites-copy-configuration-button-pannel.component.jsx
To integrate the copy configuration feature with the site deployer feature, this component was introduced. It makes available three new buttons on the sites-table-parent-row.component.jsx and on sites-table-child-row.component.jsx to open the copy-configuration-dialog.component.jsx to create or edit the new sites configurations, and another to dismiss the configurations from the site.
This component was implemented to allow the definition of new values for Dataflows variables when these are copied both in copy-configuration-extended.component.jsx and in copy-configuration-dialog.component.jsx. This component is rendered in the configuration-tree.component.jsx, when the configuration tree contains a node for a root configuration with at least one of its branches containing an array called "variables" and has its checkbox checked.
This is the Import Accounts page main CompositionEvent. It consists of a container for displaying the schemas, preferences and communications information, an input to search those configurations and a dropdown container to select the account type. Inside the Schema nodes ( profile, data, internal) there are dropdowns to select the property the schema will have when exporting. It also has a button to export the selected configurations and a dialog to show the success message after exporting.
This component is used to recursively display a configuration tree and its branches. It is used in the import-accounts-configuration-tree.component.jsx.
This component is used to allow the search for specific configurations.
This component is used to change the property of the parent node and the children node.
cypress/component/componentSiteDeployerTests.cy.js
Cypress file with Site Deployer component tests implementation.
cypress/e2e/siteDeployerTests.cy.js
Cypress file with Site Deployer end-to-end tests implementation.
cypress/e2e/e2eFullTesting.cy.js
This cypress file is used to demonstrate all the features that were built. To run this file, first you will need to comment the line 'excludeSpecPattern : ['cypress/e2e/e2e_full_testing.cy.js'] ' that is in located on the file cypress.config.js on the root of project.
This will enable you to run the cypress spec when you run the command npm run cypress:open
The next step is adding your gigya credentials on the .env file.
The credentials will be used to log-in on gigya when you run the tests. After the credentials are inserted on gigya during the test, there will be the need to insert an authentication code that will be send to the user that matches the credentials, this is required to continue the testing.
The flow that will be tested in this file is: Creating a Site using Site Deployer:
Exporting and importing templates from Email Templates:
Exporting and importing templates from SMS Templates:
Lastly, deleting the site that was created for testing purposes
cypress/e2e/emailTemplatesTests.cy.js
Cypress file with Email templates end-to-end tests implementation.
cypress/e2e/smsTemplatesTests.cy.js
Cypress file with SMS templates end-to-end tests implementation.
cypress/e2e/copyConfigifurationExtendedTests.cy.js
Cypress file with copy configuration extended tests implementation.
File where the react-18next (https://react.i18next.com/) internationalisation library is configured
File that stores the key-value pairs for the english translated strings, used as the default idiom.
These are all the automated tests that are in the file e2e_full_testing.cy.js:
Site Deployer:
- Single parent site Creation with the name e2e_testing
- Validate if it was a success
Email Templates:
- Exporting and importing the default email templates
- Validate if the import was successful
- Importing email templates with more languages on Account Deletion Confirmation *Validate if the import was successful and validate if the new languages were imported correctly
SMS Templates:
- Exporting and importing the default SMS templates
- Validate if the import was successful
- Importing SMS templates with more languages on OTP
- Validate if the import was successful and validate if the new languages were imported correctly
The services layer is decoupled from the UI layer and contains the business logic of the different services. It is also responsible for interacting with the Gigya's rest API server.
The prettier is responsible for formatting the code that is inside the UI Builder, on the Javascript tab. There is two buttons that split the functionality of the prettier service. When the user is on the UI Builder tab there is a button that is named "Prettify All Screen-Sets’ Javascript.", when the user presses that button the Javascript inside all the Screen-Sets will be formatted, showing a success popUp with a list of all the screen-sets that contain javascript and were prettified. When the user enters a specific screen-set the button will change it's name to "Prettify Javascript", and when clicked it will format only the Javascript inside that screen-set. If there is no Javascript on this screen-set, a popUp will show the user that there were no changes in the Javascript.
The PrettierFormatter class is responsible for formatting the code inside a screen-set using prettier.
It has a public method that receives all the screen-sets given the apikey the site the user is currently, and if the user is inside a screen-set, the method will also receive the screen-set he is currently in.
The site deployer service is responsible for handling the site-related features, e.g. site creation, site removal, and site configuration.
The Site Manager class is the service facade, that serves all the calls from the UI.
It has a public method "create" that creates an entire site hierarchy. This method receives, as an argument, an object with a json payload explained in the next section.
It returns a list of responses, one for each site creation. Each response list item is a gigya's response, for more details see gigya's documentation for admin.createSite endpoint.
The Site Manager will try to create all the sites' hierarchies, provided in the argument, but if one site creation fails the request stops and all the sites that were already created will be deleted.
Each response contains a boolean attribute called "deleted" that will have the value true if the correspondent site was rollbacked and deleted and false otherwise.
Each response also contains a string attribute called "siteUiId" that will contains the request id, so each response can be linked to each request and a string attribute called "endpoint" that will have the gigya's endpoint name that was called, so similar responses can be linked to the each operation.
The json payload contains an array of sites to be created and some authentication/identification attributes: partner id is the identifier of the partner where the sites will be created; the userKey and secret are the data used to perform the authentication to use the gigya's rest API. These attributes are mandatory.
Each sites array instance contains the information of the parent site (baseDomain, description, dataCenter and tempId) and also a list of child sites, each one containing the same information as the parent site. All these attributes are mandatory to be provided, except description and tempId.
The attribute tempId is a request id generated by the UI, it will be used to link a response to each request. The data center attribute can have one of the following values: au1 (Australia), eu1 (Europe) and *us1 *(United States).
The delete functionality receives a list of the target sites' identifiers to be deleted.
For each target site, will be retrieved his configuration to get his data center and site members using gigya admin.getSiteConfig, then using his data center will be called gigya endpoint *admin.deleteSite for the first time to get the delete token and a second time to delete the site. *The site members are deleted first and then the parent site.
Will be returned a list of responses for each attempt to delete a site.
The Site class performs an operation on a site, e.g creation or removal and returns the operation response to the "Site Manager" to group and track for each request.
The Site Configurator class configures a site, e.g. connects a child site to a parent site to create a site hierarchy or get site's configurations.
The client module is responsible to use the gigya's rest API. All the requests are made using this module. It corresponds to the yellow box on the architecture diagram.
The email templates service is responsible to export all the email templates and create a zip file for the user to download.
The zip file will have a directory for each email template that will contain an html file for each template language. If an email template is not created for any language an empty directory is created inside the zip file, during the export, to make it easy for an user to import several new templates, the user just needs to add one or more html files inside that empty directory.
The following image shows an example of the content of the zip file:
The email templates service is also responsible for importing all the email templates from a zip file uploaded by the user.
Additionally, the email templates are validated to the check if they are syntactically well-formed, during the import.
A common use case for this service is when a user needs to change or add a sentence in several template files for a specific language, it can export all the templates, unzip them, find and replace the sentence on the files of the language, zip the root directory and import the zip file; instead of using the UI to navigate to each template, find the sentence to change, change it and then save it.
The Email Manager class is the service facade, that serves all the calls from the UI.
It has a public method "export" that exports all email templates of a site. This method receives, as an argument, an api key that references a site.
It returns a rejected promise with the gigya server response in case of an error or otherwise a zip stream of data containing all the templates.
The zip stream contains a directory for each email template; each directory contains an html file for each language supported by the template. When exporting all the templates will be exported, there is no option to export partial content.
It has a public method "import" that imports all email templates of a site. This method receives, as an argument, an api key that references a site and a zip file content.
It returns a rejected promise with the errors related with the import of the email templates, or a list of the gigya server response for each email template imported. The user will have the option to proceed with the import even in the presence of syntactic errors on the templates or to cancel the operation to fix the "errors".
It has a public method "validateEmailTemplates" that parses the email templates searching for syntactic errors. It returns a rejected promise with the parsing errors of the email templates, or a resolved promise indicating no errors.
When importing, the templates inside the zip file will be imported, existing templates that are not in the zip file will not be modified. To delete a template language it's necessary to add an empty language file inside the imported zip.
The EmailTemplateNameTranslator class translates the templates internal names, used by gigya, to the names that can be seen in the UI, to allow the user to easily identify them. The templates' internal names are translated to the following names:
It also translates the template's name, that can be seen in the UI, to the template's internal name used by gigya.
The Email class is the gigya client to get and set all the email templates of a site.
The ZipManager class is responsible to compress/uncompress the email templates language files into/from zip format.
The XmlValidator class is responsible to validate the xml/html syntax of the email templates.
The SMS templates service is responsible to export and import all the SMS templates of a site.
When exporting all the templates will be exported, there is no option to export partial content.
When exporting will be created a zip file for the user to download. The zip file will have a directory for each SMS template that will contain a txt file for each template language. If an SMS template is not created for any language an empty directory is created inside the zip file, during the export, to make it easy for an user to import several new templates, the user just needs to add one or more txt files inside that empty directory.
The following image shows an example of the content of the zip file:
<ri:attachment ri:filename="image2022-12-23_11-6-50.png"/>
When importing, all the templates inside the zip file will be imported, and existing templates that are not in the zip file will be removed.
The SMS Manager class is the service facade, that serves all the calls from the UI.
It has a public method "export" that exports all SMS templates of a site. This method receives, as an argument, an api key that references a site.
It returns a rejected promise with the gigya server response in case of an error or otherwise a zip stream of data containing all the templates.
The zip stream contains a directory for each template group: Two Factor Authentication (tfa) and One Time Password (otp); each directory contains another directory for each template subgroup: Global Default Content and Country Specific Content; Each template subgroup directory contains a txt file for each language supported by the template.
The files have the following name pattern:
- language_code - is the code of the language, e.g: 'en', 'de'
- .default - is optional in the pattern, when appears on the file name it means that language will be chosen as the default language for the template group. Note: One file per template sub-group must be selected as the default language. E.g. 'en.default.txt'
It has a public method "import" that imports all SMS templates of a site at once. This method receives, as an argument, an api key that references a site and a zip file content.
It returns a promise with the gigya server response.
The SMS class is the gigya client to get and set all the SMS templates of a site.
The copy configuration extended service is an extension to the already existing gygia's copy configuration feature. It copies the same data and more.
The ConfigManager class is the service facade, that serves all the calls from the UI.
This class can copy several properties from a source site to a list of destination sites. The user can select which properties to copy. It contains a list of configuration classes that know how to copy several site's properties.
It has a public method "getConfiguration" that reads the "copiable" properties from the source site and returns a structure with the existing properties. This structure is used by the UI to draw the checkboxes tree, to allow the user to choose which properties wants to copy. It has a public method "copy" that calls the configuration classes to copy the properties they are responsible for, for each destination api key. This method also receives as an argument a structure with the properties selected by the user in the checkboxes tree, only those properties will be copied by the configuration classes.
It has a public method "getSiteInformation" that retrieves the information of a site according to gygia's endpoint admin.getSiteConfig.
The Schema class handles the copy of the schema related data. It copies the properties of the following objects:
- dataSchema - all properties, except the property subType.
- profileSchema - all properties, except any allowNull and any dynamicSchema. Also is not copied the properties fields.gender.format and fields.lastLoginLocation.coordinates.*.type.
- subscriptionsSchema - all properties
- internalSchema - all properties
- addressesSchema - all properties
It has a public method "copy" that copies the schema data for a destination api key. This method receives an argument that can filter the data to be copied.
The ScreenSet class handles the copy of the screen sets related data. It copies the following properties of a screen set:
- screenSetID
- html
- css
- javascript
- translations
- metadata
It has a public method "copy" that copies the screen set data for a destination api key. This method receives an argument that can filter the data to be copied.
The Policy class handles the copy of the policies related data. It copies the properties of the following objects:
- registration
- gigyaPlugins
- accountOptions
- passwordComplexity
- emailVerification
- emailNotifications
- passwordReset
- profilePhoto
- security - except the properties accountLockout, captcha and ipLockout
- twoFactorAuth
- federation
It has a public method "copy" that copies the policies data for a destination api key. This method receives an argument that can filter the data to be copied.
The Social class handles the copy of all social identities related data.
It has a public method "copy" that copies the social identities data for a destination api key. This method receives an argument that can filter the data to be copied.
The EmailConfiguration class handles the copy of the email templates related data. It copies the properties of the following objects:
- codeVerification
- emailNotifications
- emailVerification
- magicLink
- preferencesCenter
- doubleOptIn
- passwordReset
- twoFactorAuth - except providers property when copying for a child site
- impossibleTraveler
It has a public method "copy" that copies the email templates' data, one by one, for a destination api key. This method receives an argument that can filter the data to be copied.
The SmsConfiguration class handles the copy of the SMS templates related data. It has a public method "copy" that copies the SMS templates' data, in one step, for a destination api key. This method receives an argument that can filter the data to be copied.
The WebSdk class handles the copy of the web SDK related data. It has a public method "copy" that copies the web SDK data for a destination api key. This method receives an argument that can filter the data to be copied.
The ConsentConfiguration class handles the copy of the consent statements and the legal statements related data. It has a public method "copy" that copies the consents data, one by one, for a destination api key. This method receives an argument that can filter the data to be copied.
When copying the consent statement to a parent site all the data is copied; but when copying the consent to a child site only the property isActive can be copied if the consent already exists on its parent site otherwise a warning will be returned because it's not possible to change consents on a child site if it do not exists on its parent.
When copying the legal statement to a parent site all the data is copied, except the statements with the status Historic; no legal statements are copied to child sites.
The Communication class handles the copy of the channels and topics related data.
It has a public method "copy" that copies the communication data, one by one, for a destination api key. This method receives an argument that can filter the data to be copied.
When copying the channels to a parent site all the data is copied; no channels are copied to a child site.
When copying the topics to a parent site all the data is copied, but when copying the topics to a child site no data is copied.
The Webhook class handles the copy of the webhooks related data. It has a public method "copy" that copies the webhook's data, one by one, for a destination api key. This method receives an argument that can filter the webhooks to be copied.
The Extension class handles the copy of the extensions related data.
It has a public method "copy" that copies the extension's data, one by one, for a destination api key. This method receives an argument that can filter the extensions to be copied.
When copying an extension to a parent site all the data is copied; but when copying an extension to a child site only the properties enabled and extensionFuncUrl can be copied.
The Dataflow class handles the copy of the dataflows related data.
It has a public method "copy" that copies the dataflow's data (published and draft), one by one, for a destination api key. This method receives an argument that can filter the dataflows to be copied and, optionally, for each dataflow a list of pairs containing a variable name and value.
This feature supports the existence of variables in a dataflow. Any name that appears in the source site dataflow, between the symbols '{{' and '}}', will be treated as a variable.
During the copy, when a variable is detected its placeholder is replaced with the variable's value. It's possible to copy a dataflow template to several destination sites and each one will have its specific values.
The Rba class handles the copy of the rule based authentication related data.
It has a public method "copy" that copies the rule based authentication data, for a destination api key that corresponds to a parent site. It is not possible to copy rule based authentication data to a child site. This data is composed by 3 parts:
- Account Takeover Protection - Obtained from the method accounts.rba.riskAssessment.getConfig
- Unknown Location Notification - Obtained from the method accounts.getPolicies, it is used the property security.sendUnknownLocationNotification of the response
- RBA Rules and Settings - Obtained from the method accounts.rba.getPolicy
The copy is done sending a separate request for each data part. This method receives an argument that can filter the rule based authentication data to be copied.
The RecaptchaConfiguration class is responsible for managing the copying of reCAPTCHA-related data between sites.
The copy method is designed to copy reCAPTCHA configurations from one site (parent site) to another.
The data copied is divided into three main parts:
- reCAPTCHA Configuration:
- This part of the data is obtained using the admin.captcha.getConfig method. The configuration defines how reCAPTCHA is enabled and set up on the parent site.
- Security and Registration Policies:
- These policies are retrieved using the accounts.getPolicies method. Specifically, the method retrieves security configurations such as CAPTCHA enforcement during registration and security questions.
- Risk Providers Configuration:
- This data is obtained using the admin.riskProviders.getConfig method. It deals with providers that assess the security risks associated with the site, allowing the configuration of external providers for enhanced risk assessment.
Each of these data parts is copied separately to the target site via individual API requests.
Example of Copy Operations:
- reCAPTCHA Config: The reCAPTCHA settings (like API keys, secret, and configuration details) are copied from the source site to the destination using admin.captcha.setConfig.
- Security Policies: Policies related to CAPTCHA enforcement and other registration-related security settings are set on the target site using accounts.setPolicies.
- Risk Providers: Configuration for risk providers (such as external services that evaluate risk) is copied using admin.riskProviders.setConfig.
The Info class reads all the "copiable" properties of a site. It has a public method "get" that calls all the configuration classes to read the "copiable" properties they are responsible for and returns a structure with the existing properties. This structure will be used by the UI to generate the configurations checkboxes tree.
The SiteFinderPaginated service is responsible to get all the sites the user have access to. The user can have access to a big number of sites, so this service will get them in pages, a portion of data each time.
It has a public method "getFirstPage" that will read all the partners the user have access to and returns the first page of data. It has a public method "getNextPage" that will read the next page of data. This method should be called successively until it returns undefined, which means all the data was read.
The service will keep track of the data already returned to know how to read the next page.
The Tracker module is responsible for collecting anonymous usage data. It uses the @sap_oss/automated-usage-tracking-tool library to track various features within the application.
-
Tracker Initialization: The tracker is initialized based on the environment variables specified in the
.envfile. -
Consent Confirmation: Upon loading the application, a consent confirmation is requested from the user. This is done with the
requestConsentConfirmationmethod. The tracker will show a message requesting consent, where the user needs to press a button to confirm. -
Usage Tracking: The tracker provides a
trackUsagemethod, which is used throughout the app to track the usage of specific features.
-
/src/lib/tracker.js: Contains the core logic to integrate the automated usage tracking tool, including initialization, consent confirmation request, and usage tracking functions. -
/src/App.js: The initial call for consent confirmation is included in the App component. -
Usage Throughout the Application: Calls to the
trackUsagefunction are used in various components to track feature usage. -
.release-it.json: TheREACT_APP_RELEASE_BUILD=truevariable was added to the release-it configuration to enable API key switching during the build phase.
The trackUsage function is used throughout different parts of the code to track feature usage. Ensure it is called as shown in the example below:
import { trackUsage } from './lib/tracker';
// ... in some feature file
await trackUsage({ featureName: <your-feature-name> });Because the tracker is initialized based on the environment settings, it requires API keys and data center configurations specified in the .env file. The application reads different keys and data centers based on whether it is in production or development mode.
In addition, the API keys and data center required for the tracker will be changed automatically when releasing a new version. The release script will set a build-time environment variable (REACT_APP_RELEASE_BUILD), which will automatically use the production API key and data center for the build. Other builds, where this environment variable is not set, will use the development API key and data center.
Create or update the .env file with the following variables for the configurations:
# Configuration for Development
REACT_APP_TRACKER_API_KEY_DEV=<your-development-api-key>
REACT_APP_TRACKER_DATA_CENTER_DEV=<your-development-data-center>
# Configuration for Production
REACT_APP_TRACKER_API_KEY_PROD=<your-production-api-key>
REACT_APP_TRACKER_DATA_CENTER_PROD=<your-production-data-center>
To release a new application version was decided that, as pre-requisite, the code should be committed on the dev branch, then do a PR so that the main branch is updated with the latest changes. The first step is to remove the main branch protection to allow the release to go through, to do that:
- Click on the "Settings" option next to the "Insights".
- Go to the "Branches" option and edit the "main" branch
- Check the option "Require a pull request before merging" and verify that it's not checked.
- Save the changes
To start the release process the user should have a GITHUB_TOKEN, to create one follow these steps (if the user already has one he can skip the step):
- Go to your github.com account
- Click on the account avatar and go to the "Settings" option
- Click on the last option "Developer Settings"
- Click on the "Personal access tokens" and choose "Tokens (classic)"
- Select the "Generate new token" dropBox and select the "Generate new token (classic)" option
- Select the expiration date of the token and select the "repo" checkBox then hit the "Generate Token" button
- Copy the Github token and open a terminal window to write "export GITHUB_TOKEN=<GITHUB_TOKEN>" if you are using a windows OS change the export to set so that the command is like this "set GITHUB_TOKEN=<GITHUB_TOKEN>"
- To check if the GITHUB_TOKEN is properly set write on the terminal window "echo $GITHUB_TOKEN"
After you check that the GITHUB_TOKEN is properly set, checkout the main branch and execute the following command:
npm run release -- <version>
Where <version> can have one of the following values:
- major - it will increment the version to the next major version. E.g. if the current version has the value "1.2.3", using this argument will change the version to "2.0.0"
- minor - it will increment the version to the next minor version. E.g. if the current version has the value "1.2.3", using this argument will change the version to "1.3.0"
- patch - it will increment the version to the next patch version. E.g. if the current version has the value "1.2.3", using this argument will change the version to "1.2.4"
- "5.6.7" - it will set the version to the number provided.
The release process will perform the following steps:
- execute eslint code analysis
- execute unit tests
- set the new version on package.json, package-lock.json and manifest files
- execute a new build
- zip the build folder
- commit the changes on git hub
- create a git hub tag with the version as name
- push the data to the git hub
- create a release on the git hub and upload the release assets
If a step fails, for example due to a unit test not passing, the process stops and all the changes are reverted. If the process executes successfully should be seen a message on the terminal window like the following one:
echo Successfully released sap-customer-data-cloud-toolkit v1.0.1 to cx-servicesautomation/cdc-tools-chrome-extension.
Additionally, the new release should appear on https://github.com/SAP/sap-customer-data-cloud-toolkit/releases/
Note Because the "release" npm script interacts with the git hub, it expects the user to have an environment variable
GITHUB_TOKENset with the token that the user uses to access the github. The token needs to have the "repo" permissions only. E.g. export GITHUB_TOKEN="<token_value>"
The steps below describe how to download and install the SAP Customer Data Cloud toolkit Chrome extension.
-
Navigate to the releases page to download the latest release: https://github.com/SAP/sap-customer-data-cloud-toolkit/releases/
-
Expand the
Assetsand click sap-customer-data-cloud-toolkit-<version>.zip to download the file
- Unzip the sap-customer-data-cloud-toolkit-<version>.zip file
- Navigate to Google Chrome extensions chrome://extensions/
- Enable the
Developer modeby clicking the switch in the top right of the window
- If you are already using the SAP Customer Data Cloud toolkit chrome extension then click the
Removebutton; otherwise, ignore this step
- Click the
Load unpackedbutton in top left of the window
- Go to the sap-customer-data-cloud-toolkit-<version>.zip file in the step 3 and select the
builddirectory to load the extension
-
Navigate to https://console.gigya.com/ and login, then check if the SAP Customer Data Cloud toolkit Chrome extension was loaded successfully
-
Check if all the features are working properly
-
See if the usage tracker is working and is saved on localStorage.
12.To check, inspect the gigya page, click on the "Application" tab then go to the "LocalStorage" dropbox and click on "https://console.gigya.com" option and see if the "usageTracker" is saved.