This document describes the technical integration of Tinyclues link cartridge.
Tinyclues is the leading action-oriented customer analytics solution that helps B2C marketers make the right decisions for their omni-channel campaigns to increase revenue, improve customer experience and drive strategic outcomes. The solution uses Deep Learning to predict the best topics, audiences, and campaign plans.
This documentation will walk you through the setup of an automatic transfer of data from Salesforce Commerce Cloud (CRM, product catalogue, transactions) to Tinyclues.
BEFORE READING THIS DOCUMENTATION
Download the cartridge from the Salesforce Commerce Cloud AppExchange
Save the SFTP credentials that Tinyclues has provided you (URL & username)
Contact your Salesforce representative
Unless you have access to the Salesforce Commerce Cloud admin section, you will need to contact your Salesforce representative to complete this setup.
This Cartridge works best with the SFRA version of 4.4.1 and compatibility mode 19.10
1.2 LIMITATIONS, CONSTRAINTS
1.3 PRIVACY, PAYMENT
No credit card details are stored within SFCC using this integration.
2. INTEGRATION COMPONENTS
The Tinyclues Integration has the following cartridges:
bc_tinyclues - Business Manager extension cartridge for exporting data to Tinyclues.
2.2 ADDING THE CARTRIDGE IN SFCC UX STUDIO
To upload the cartridges into the SFCC server, you first need to add the cartridges in SFCC UX Studio. In order to do this, follow these instructions.
In UX Studio, select in the menu File > Import.
In the import dialog, select General > Existing Projects in the workspace and click on Next.
Ensure Select archive file is selected and select the compressed cartridge file by clicking on the Browse button.
Click on Finish button to import the cartridges.
Studio will now ask you if you want to link the cartridge to your active DigitalServer connection. Click on Yes or manually link the cartridge to your server by checking the project under project references in the server connection properties.
2.3 BUSINESS MANAGER CONFIGURATIONS
For the Tinyclues integration to work, the following object structures (metadata) needs to be configured in the Business Manager.
In the cartridge bundle, find jobs.xml file inside the metadata/Tinyclues-meta-import folder.
Open this jobs.xml file in any text editing application
Change all occurrences of email address “firstname.lastname@example.org” to any valid merchant email address.
Save the jobs.xml file
Compress (.zip) this file: Tinyclues-meta-import folder. This will generate the Tinyclues-meta-import.zip file.
Go to Business Manager Menu > Administration > Site Development > Site Import & Export
Under Import: Upload Archive: Ensure that the radio button with “Local” label is enabled (If not, click on the radio button to enable it).
Click on Choose File input field, select the Tinyclues-meta-import.zip file from open dialog box and click on upload button
After finishing the upload, from the Archives list, click the radio button corresponding to Tinyclues-meta-import.zip and click on Import button.
Click on OK button of the confirmation box asking, “Are you sure that you want to import the selected archive?”
2.3.2 CUSTOM SITE PREFERENCES
After the successful metadata import following attributes should have been created:
In Business Manager, navigate to the Site > Site Preferences > Custom Preferences. Custom site preference groups with the ID Tinyclues General Config will be available after the successful import of metadata. Please select it and edit the attributes as needed.
Find usage of each custom site preference field below:
SFTP Base Folder Path (ID - TinycluesFolderPath, Type - String) – This is the base folder path in the Tinyclues SFTP server to which all the exported feeds need to be uploaded. User is expected to create these folders in SFTP server. Other below mentioned sub folders will be automatically generated by relevant jobs.
Products Feed Folder Name (ID - TinycluesProductsFeed, Type - String) – Name of the folder under base folder to which products feeds need to be uploaded.
Orders Feed Folder Name (ID - TinycluesOrdersFeed, Type - String) – Name of the folder under base folder to which orders feeds need to be uploaded.
Customers Feed Folder Name (ID - TinycluesCustomersFeed, Type - String) – Name of the folder under base folder to which customers feeds need to be uploaded.
Products Active Data Feed Folder Name (ID - TinycluesProductsActiveFeed, Type - String) – Name of the folder under base folder to which products active data feeds need to be uploaded.
Customers Active Data Feed Folder Name (ID - TinycluesCustomersActiveFeed, Type - String) – Name of the folder under base folder to which customers active data feeds need to be uploaded.
Service Name (ID - TinycluesServiceName, Type - String) – Keep Tinyclues’ service object’s name here. Service object names are available at Business Manager Menu > Administration > Operations Services
SFTP Connection Type (ID - TinycluesSftpConnectionType, Type – Enum of String) – Specify SFTP connection method here. 2 possible values:
Password: Password of the SFTP account must be kept under Service Credential Object which can be found under Business Manager Menu > Administration > Operations > Services > Service Credentials
Private Key: Go to Business Manager Menu > Administration > Operations > Private Keys and Certificates. Import private key (Explained in subtitle 2.3.4). Keep Private Key Alias to refer it through the connector.
In both of the above cases SFTP host URL and SFTP Username must be kept under Service Credential Object.
9. Private Key Alias (ID – TinycluesPrivateKeyAlias, Type - String) – If the value selected for custom site preference field ‘SFTP Connection Type’ is ‘Private Key’ then enter private key alias here.
2.3.3 HOW TO GENERATE P12 PRIVATE KEY FILE FROM A PEM FILE
1. Identify the style of PEM file
Check whether the PEM file is of PKCS1 or PKCS8 style. For that run the following command in the command terminal where file resides. (Guessing that file name is id_rsa_sfcc.pem)
head -1 id_rsa_sfcc.pem && tail -1 id_rsa_sfcc.pem
You will see the following output in either of the case:
If the file is PKCS1 style
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
If the file is PKCS8 style
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
If you find your PEM file is of PKCS1 style, then convert it into PKCS8 style
2. Convert PKCS1 into PKCS8 style
Run the below command in command terminal:
openssl pkcs8 -topk8 -nocrypt -in id_rsa_sfcc.pem -out p8_id_sfcc.pem
New file will be generated with name p8_id_sfcc.pem
3. Convert PKCS8 file into .P12 file
Generate .CSR file
Run following command to generate .CSR file:
openssl req -new -days 3650 -key p8_id_sfcc.pem -out id_sfcc.csr
It will ask to enter several details like Country Name, Email Address. Enter all the details as you wish, except challenge password. It is recommended to leave the challenge password blank.
Generate .CER file
Run the following command:
openssl x509 -days 3650 -signkey p8_id_sfcc.pem -req -in id_sfcc.csr -out id_sfcc.cer
Generate .P12 private keyt file
Run the following command:
openssl pkcs12 -export -out id_sfcc.p12 -inkey p8_id_sfcc.pem -in id_sfcc.cer -certfile id_sfcc.cer
It will ask for Export Password. Leave it blank.
2.3.4. HOW TO IMPORT .P12 FILE INTO SFCC
Go to Business Manager Menu > Administrator > Operations > Private Keys and Certificates
Find the Import button on top right corner of the page and click on it
In the popup window titled as Import Private Key or Certificate click on Select button to choose the .P12 file from local system
Enter any single word as mandatory field Alias
Hit Save button
Copy this Alias text and enter in to the custom site preference field – Private Key Alias2.3.5 SFTP SERVICE OBJECT
Go to Business Manager Menu > Administrator > Operations > Services
Ensure that there is a service object namely “Tinyclues.service.sftp”
Open the credential object namely “Tinyclues.credentials.sftp”
Enter the URL and username which you received from Tinyclues as part of the SFTP credentials
Keep the correct password if the custom site preference field “SFTP Connection Type” is set as “Password”
Keep the password blank if the custom site preference field “SFTP Connection Type” is set as “Private Key”
Go to Business Manager Menu > Administrator > Operations > Jobs
The following are the Tinyclues jobs: