Providing JSON data to Lexer

Short of using one of our integrations, APIs or exports of data via S3/SFTP in JSON format are the fastest ways to deploy the Lexer CDXP within your organization.

Steps to provide JSON data to Lexer

1. Determine the schema best suited to your data.
2. Export and transform the data into the provided format.
3. Determine the process for delivering the data.
   [.in]a. APIs: Read Getting started onboarding data to figure out the best solution for you.[.in]
   [.in]b. SFTP/S3: Upload using SFTP or Upload using S3.[.in]
   [.in]c. File uploader: Read File Upload API for specifics.[.in]
   [.in]d. Custom: Chat with your Lexer contact.[.in]
4. Download and validate the data prior to uploading.
5. Transfer the data.
6. Notify your Lexer contact.

File Naming

Files must be named using the following format: 

[.code]{specification_name}-{date}-{version}.json[.code]

This format consists of the following three parts:

1. Specification Name: A descriptive name for the files contents, separated by an underscore `_`.
2. Date: An ISO8601 date for the file, reflecting the contents or date of file generation.
3. Version: An optional version identifier. We recommend using versions. This allows you to easily revert to an old file if you identify any issues with the current version.

File names are case-sensitive, and may not contain special characters other than a hyphen '-', or an underscore '_'.

File Naming Examples

Let’s look at an example for commerce returns made on August 29th, 2022:

• [.code]commerce_purchases-20220829.json[.code]

In the case where a file might need to be overwritten with a newer version, you can add an additional suffix. This will update the file currently being used, while keeping the old file.
like so:

• [.code]commerce_purchases-20220829-a.json[.code]

• [.code]commerce_purchases-20220829-b.json[.code]

The higher suffix will cause the newer version to be used in place of previous versions. In these examples [.code]commerce_purchases-20220829-a.json[.code] will be ignored, and [.code]commerce_purchases-20220829-b.json[.code] used.

Alternatively, you could simply delete the [.code]commerce_purchases-20220829-a.json[.code] file entirely, although this is not the recommended option. 

Validating JSON data 

Lexer provides JSON schema files for each of the data specifications supported by the CDXP. You can download copies of each schema from the API reference page.

Profile API:

• [.in]Customer write[.in]‍
• [.in]Unify[.in]

Commerce API:

• [.in]Product entities[.in]
• [.in]Purchase events[.in]
• [.in]Return events[.in]

Marketing API:

• [.in]Email subscribe events[.in]
• [.in]Email send events[.in]
• [.in]Email open events[.in]
• [.in]Email click events[.in]‍
• [.in]Email bounce events[.in]‍
• [.in]SMS subscribe events[.in]‍
• [.in]SMS send events[.in]‍
• [.in]SMS click events[.in]

Compliance API:‍

• ‍[.in]Forget events[.in]

Export API:‍

• ‍[.in]Profile read[.in]

Once downloaded, you can use one of the validators endorsed by the JSON Schema specification listed here: validators.

Here is an example of the Python implementation of JSON Schema: Python JsonSchema

[.code]jsonschema --instance myfile.json lexer_docs_schema_profile_customer.json[.code]

This process accepts a file that contains your exported data and compares this against the schema downloaded above. The script will raise an error if your file does not comply with the schema, allowing you to address many data quality issues prior to transferring. This way your team can troubleshoot data quality issues reducing back and forth with the Lexer team. 

Need some help?

This step can be a little tricky. There are a number of errors you could run into, so please reach out to your Success Manager if you need a hand and we can help you to troubleshoot.