Supported Transformers
This section will explore the various methods available for transforming data within the data source. Following a brief description of each transformer, you will find a practical example showcasing the usage of each one.
Convert XML to JSON
Let's begin by clarifying the distinction between JSON and XML.
JSON (JavaScript Object Notation) is a lightweight, language-independent data interchange format. It is derived from JavaScript and is easy to comprehend and generate.
On the other hand, XML (Extensible Markup Language) is a text-based format used to represent structured information. It finds applications in various domains, such as documents, data, configurations, books, transactions, invoices, etc.
Now, let's consider a scenario where you have a data source containing product information stored in an XML file. Your objective is to utilize an API to generate emails based on this data source.
<?xml version="1.0" encoding="UTF-8"?>
<info>
<offers>
<offer>
<date>2022-10-05</date>
<brand>SAMSUNG</brand>
</offer>
<offer>
<date>2022-10-06</date>
<brand>LG</brand>
</offer>
</offers>
<labels>
<title>Hello, Dear customer!</title>
<messages>
<welcome>How are you</welcome>
</messages>
</labels>
</info>
Since the system exclusively operates in JSON format, it becomes imperative to convert the data. In this scenario, we recommend employing a transformer that facilitates converting from XML to JSON format.
{
"type":"xml_json", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2" // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
}
Search for JSON element by selector
JSON can often contain a vast amount of data that can be challenging to visually locate. To address this issue, we have developed a transformer specifically designed to assist in searching for specific elements within the JSON structure. This transformer enables the usage of selectors to locate desired elements and generate an array containing those elements.
{
"type":"json_path", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"config":{
"rules":[ // The filtering ruleset.
{
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"path":"$..gender[?(@.code == 'F')]..type" // Selector: Specifies the location of the desired elements within the JSON object.
}
]
}
}
The rules for constructing selectors are found at the following link.
Filtering data
We provide three types of transformers to help you locate the relevant information:
- Filtering based on the date.
- Filtering based on text with a constant value.
- Filtering based on text with a dynamic value sourced from another data source.
Let's explore each of them in detail.
Filtering based on the date
This transformer lets you display and sort information based on date and source. By employing different filtering rules, you can obtain an array of information specific to today, upcoming days or even exclude a particular date.
Note: To utilize this transformer, it is essential to provide the exact time in the format: yyyy-MM-dd'T'HH:mm:ss.
{
"type":"date_condition", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"format":"yyyy-MM-dd'T'HH:mm:ss", // The date format used in the data source.
"field":"fieldName", // Filtering Field Name: The name of the field used for performing filtering.
"filterType":"AND", // Optional: Combination of filtering rules application. Variants include "AND" and "OR". The default value is "AND".
"rules":[ // The filtering ruleset.
{
"condition":"EQUALS", // Filtering Rule: Available variants include "GREATER", "GREATER_EQUALS", "EQUALS", "NOT_EQUALS", "LESS", and "LESS_EQUALS".
"value":"2017-12-16T04:00:00", // Filter Value: Instead of an absolute value, you can use the word "TODAY" to indicate the use of the current date ("today"). Time is considered in the UTC zone.
"daysToAdd":1, // Optional: Number of days to add to the filter value.
"minutesToAdd":240 // Optional: Number of minutes to add to the filter value.
}
]
}
}
Good to know
If your system does not, for some reason, display time with minutes and seconds, you can first add them using the
values_mappertransformer and then return to the filtering.
Filtering based on text with a constant value
If you wish to display data based on text, you can utilize this transformer. Specify a specific value and the source to be used for filtering (please note that the system is case-sensitive, so input the value names exactly as they appear). The data can be sourced from various sources and may incorporate additional conditions using different rules.
{
"type":"string_condition", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"sourсe2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"field":"fieldName", // Filtering Field Name: The name of the field used for performing filtering.
"filterType":"AND", // Optional: Combination Method for Filtering Rules. Available variants include "AND" and "OR". The default method is "AND".
"rules":[
{
"condition":"CONTAINS", // Filtering Rule: Available variants include "GREATER", "GREATER_EQUALS", "EQUALS", "NOT_EQUALS", "LESS", and "LESS_EQUALS".
"value":"filterValue" // Filter Value: The value used for filtering.
}
]
}
}
Filtering based on text with a dynamic value sourced from another data source
This transformer is invaluable as it filters data from diverse sources and presents it within email messages according to configuration rules.
We encourage you to exercise your creativity when formulating rules. For example, you can merge data from two sources, and in case the system fails to locate the required variables, it can employ an alternative filter type (such as "OR" instead of "AND") to display alternative data.
{
"type":"string_condition", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"sourсe2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"field":"fieldName", // Filtering Field Name: The name of the field used for performing filtering.
"filterType":"AND", // Optional: Combination Method for Filtering Rules. Available variants include "AND" and "OR". The default method is "AND".
"rules":[
{
"condition":"CONTAINS", // Filtering Rule: Available variants include "GREATER", "GREATER_EQUALS", "EQUALS", "NOT_EQUALS", "LESS", and "LESS_EQUALS".
"sourceValue":{ // External Source Filter Value Description: This section describes the value of a filter that is sourced from another external data source.
"source":"source3", // Data Source Name: The name of the data source.
"field":"brands", // Filtering Field Name: The name of the field used for filtering.
"strict":false, // Optional: Handling Empty Source Data for Filter Value. Use "true" to exclude the data when there is no value in the source, or "false" to retain the data. The default behavior is "false".
"filterType":"OR" // Optional: Handling Filtering Rules for Filter Value Array. Use "AND" for a strict match (all elements must match), "OR" for at least one match from the array. The default behavior is "AND".
}
}
]
}
}
Joining data
This transformer has the capability to merge data from multiple sources into a unified format and display it within an email template. You can customize the solution according to the source data and utilize the additional parameter "unique" as a configuration option.
{
"type":"join_sources", // The transformer type.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"sources":[ // Data Source Join Set: The set of data source names to be joined together.
"source1",
"source2",
"source3"
],
"unique":"false" // Optional: Unique Data Flag. Set to "true" to retain only unique data. The default value is "false".
}
}
Trimming data
To control the number of product cards displayed in your email message or adjust their starting position, you can employ the "trim" transformer with a suitable configuration. This allows you to specify the desired trimming settings for your requirements.
{
"type":"trim", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"offset":2, // Optional: Offset from the first element. The default offset is "0".
"limit":3 // Optional: Number of Items to Retain. If left empty, all items are used by default.
}
}
Adding new fields to the data source
By utilizing the "values mapper" transformer, you have the capability to introduce new variables to the existing data. This transformer facilitates the process of mapping and assigning values to these additional variables.
{
"type":"values_mapper", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"rules":[ // Ruleset for Adding New Fields.
{
"fieldName":"newFieldName", // New Field Name: The name of the new field to be added.
"value":"text ${someField} ${dealCategory}", // Field Value: The value of the field. If you wish to reference the value of an existing variable, it should be enclosed in ${...} syntax.
"valuePatterns":[ // Optional: Additional Variable Section for Value Composition. This section enables the creation of additional variables to construct the field value.
{
"name":"dealCategory", // Additional Temporary Variable Name: The name of the additional temporary variable.
"path":"categories.category[0].content" // Selector: The path that allows accessing the value for the variable. Refer to the following link for rules and guidelines on forming selectors: https://github.com/json-path/JsonPath.
}
]
}
]
}
}
Here's a simple example: Suppose we wish to include both the date and time in a field where only the date is currently present. To accomplish this, we need to first establish a data source from which we can retrieve the required information. Then, we can create a rule that updates the value in the field with the appropriate variable, incorporating the date and time.
{
"type":"values_mapper",
"source":"Offers",
"outputSource":"Offers with date time",
"config":{
"rules":[
{
"fieldName":"datetime",
"value":"${date}T00:00:00"
}
]
}
}
Sorting data
The information within the email message can be sorted based on the configuration. The Stripo API offers two methods for sorting information:
- Sorting by a fixed (constant) value.
- Sorting by a dynamic value sourced from another data source.
Let's delve deeper into these sorting options.
Sorting by a fixed (constant) value
In this scenario, you need to specify the field name of the sorting object as a constant, followed by the corresponding values in the desired order.
{
"type":"sorting", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"field":"fieldName", // Sorting Field Name: The name of the field by which the sorting will occur.
"value":[ // Sorting Value Array: The array of values to be sorted by.
"b1",
"b2"
]
}
}
Sorting by a dynamic value sourced from another data source
With this transformer, you have the ability to incorporate various dynamic variables from the initial data source or multiple sources. In the configuration, you must specify the appropriate field and its corresponding value.
{
"type":"sorting", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"field":"fieldName", // Sorting Field Name: The name of the field by which the sorting will occur.
"sourceValue":{ // External Source Filter Value Description: This section describes the value of a filter that is sourced from another external data source.
"source":"source3", // Data Source Name: The name of the data source.
"field":"brands" // Filter Value Field Name: The name of the field to extract the value from for the filter.
}
}
}
SRT transformer
By employing this type of transformer, we gain the capability to construct our own logic for presenting data within templates. Two examples demonstrate this in the Advanced email generation section.
{
"type":"srt", // The transformer type.
"source":"sourсe1", // Optional: Initial data source name. If left empty, the first one will be used by default.
"outputSource":"source2", // Optional: Destination source name for writing modified data. If not specified, the results will be written in the initial source by default.
"config":{
"name":"some_config" // SRT Rule Name: The name of the SRT rules stored in the database. Please refer to the description of REST API methods to learn how to create an SRT rule with configurations.
}
}
The transformer includes its own conditional rules for SRT configuration, enabling you to repeat certain variables in email messages or begin displaying them from the second or third iteration. You can comprehensively examine these rules in the Supported Rules for SRT section of the documentation.
Example for all transformers used in the request body of the method to generate an email message
Initial Parameters: We have two data sources containing product cards. One of them is a link, while the other is in the standard JSON format. Our objective is to transform one of the sources into JSON format initially.
In the final outcome, we anticipate the email message to display sorted data (sorted by the name of the monitors) in one section and a welcome message in another section. Additionally, we desire to limit the number of cards to a maximum of 10, with the first card specifically featuring the name "SAMSUNG Odyssey G8".
Refer to the provided example code to observe a real-world implementation of the aforementioned logic. You can navigate to the relevant documentation section by clicking on any transformer type mentioned in the transformers section, which will redirect you to the appropriate area with detailed explanations.
{
"dataSources":[
{
"name":"Info",
"type":"LINK",
"value":"https://rf.stripocdn.email/content/materials/samples/srt/email_generation_data.xml"
},
{
"name":"TermsAndConditions",
"type":"RAW",
"value":"<p style=\"text-align: center; font-weight: 600; background-color: red\">This is terms and conditions section</p>"
},
{
"name":"Products",
"type":"RAW",
"value":[
{
"url":"https://www.amazon.com/Sceptre-E248W-19203R-Monitor-Speakers-Metallic/dp/B0773ZY26F/ref=lp_16225007011_1_6",
"p_name":"Sceptre 24 Professional LED Monitor",
"p_image":"https://m.media-amazon.com/images/I/71rXSVqET9L._AC_SX679_.jpg",
"p_price":"$120",
"p_old_price":"$137"
},
{
"url":"https://www.amazon.com/SAMSUNG-Computer-FreeSync-Advanced-LC24F396FHNXZA/dp/B079K3MXWF/ref=sr_1_2?qid=1654090668&rnid=16225007011&s=computers-intl-ship&sr=1-2",
"p_name":"CF396 Computer Monitor",
"p_image":"https://m.media-amazon.com/images/I/91ubktnbNVL._AC_SX679_.jpg",
"p_price":"$150",
"p_old_price":"$175"
},
{
"url":"https://www.amazon.com/SAMSUNG-32-inch-Odyssey-G7-Monitor/dp/B088HHZBGJ/ref=sr_1_6?qid=1654090668&rnid=16225007011&s=computers-intl-ship&sr=1-6&th=1",
"p_name":"SAMSUNG Odyssey G7",
"p_image":"https://m.media-amazon.com/images/I/61Y8YS+rAKL._AC_SX679_.jpg",
"p_price":"$529",
"p_old_price":"$687"
},
... // Add as many data objects as necessary in this location.
{
"url":"https://www.amazon.com/SAMSUNG-32-inch-Odyssey-G7-Monitor/dp/B088HHZBGJ/ref=sr_1_6?qid=1654090668&rnid=16225007011&s=computers-intl-ship&sr=1-6&th=1",
"p_name":"SAMSUNG Odyssey G9",
"p_image":"https://m.media-amazon.com/images/I/61Y8YS+rAKL._AC_SX679_.jpg",
"p_price":"$529",
"p_old_price":"$687"
}
]
}
],
"transformers":[
{
"type":"xml_json",
"source":"Info",
"outputSource":"Info. JSON"
},
{
"type":"json_path",
"source":"Info. JSON",
"config":{
"rules":[
{
"outputSource":"Offers",
"path":"$..info.offers.offer[0:]"
},
{
"outputSource":"Labels",
"path":"$..info.labels"
}
]
}
},
{
"type":"values_mapper",
"source":"Labels",
"outputSource":"Title",
"config":{
"rules":[
{
"fieldName":"Title",
"value":"${title} ${welcomeMessage}?",
"valuePatterns":[
{
"name":"welcomeMessage",
"path":"messages.welcome"
}
]
}
]
}
},
{
"type":"values_mapper",
"source":"Offers",
"outputSource":"Offers with date time",
"config":{
"rules":[
{
"fieldName":"datetime",
"value":"${date}T00:00:00"
}
]
}
},
{
"type":"date_condition",
"source":"Offers with date time",
"outputSource":"Offer of the selected datetime",
"config":{
"format":"yyyy-MM-dd'T'HH:mm:ss",
"field":"datetime",
"filterType":"AND",
"rules":[
{
"condition":"EQUALS",
"value":"2022-10-05T00:00:00",
"daysToAdd":0,
"minutesToAdd":0
}
]
}
},
{
"type":"string_condition",
"source":"Products",
"outputSource":"Products of brands",
"config":{
"field":"p_name",
"filterType":"AND",
"rules":[
{
"condition":"CONTAINS",
"sourceValue":{
"source":"Offer of the selected datetime",
"field":"brand",
"strict":true,
"filterType":"OR"
}
}
]
}
},
{
"type":"sorting",
"source":"Products of brands",
"config":{
"field":"p_name",
"value":[
"SAMSUNG Odyssey G8"
]
}
},
{
"type":"join_sources",
"outputSource":"Products area data",
"config":{
"sources":[
"Title",
"Products of brands"
],
"unique":"false"
}
},
{
"type":"trim",
"source":"Products area data",
"config":{
"limit":10
}
},
{
"type":"srt",
"source":"Products area data",
"config":{
"name":"SRT_example"
}
}
],
"composers":[
{
"type":"canonical",
"source":"Products area data",
"templateArea":"products-area"
},
{
"type":"plain",
"source":"TermsAndConditions",
"templateArea":"terms-area"
}
],
"templateId":"1494761",
"emailId":"4205552",
"emailName":"SRT_example"
}
Updated over 1 year ago