It's common to use variables in query conditions. For instance, in the above example, you'll want to query an account by name instead of using the hardcoded ffda name. The expr attribute takes an XTK expression as a parameter, and ffda is a string literal in an xtk expression.
To prevent xtk ingestions vulnerabilities, you should not concatenate strings and write code such as expr: "@name = '" + name + "'": if the value of the name parameter contains single quotes, your code will not work, but could also cause vulnerabilities.
The sdk.escapeXtk can be used to properly escape string literals in xtk expressions. The function will also surround the escaped value with single quotes.
You can use string concatenation like this. Note the lack of single quotes around the value.
{ expr: "@name=" + sdk.escapeXtk(name) }
or a template literal
`{ expr: "@name=${sdk.escapeXtk(name)}" }`
The escapeXtk function can also be used to create tagged string literals. This leads to a much shorter syntax. Note that with this syntax, only the parameter values of the template literal are escaped
sdk.escapeXtk`{ expr: "@name=${name}" }`
This can also be used to escape other data types such as timestamps
sdk.escapeXtk`{ expr: "@lastModified > = ${yesterday}" }`
will return
{ expr: "@lastModified > = #2021-07-07T10:03:33.332Z# }`
This function escapes values so that they can be used in SQL or XTK like conditions. For example a search term "term" can be escaped as follows to implement a search conditions
expr: `Lower([${xpath}]) LIKE '%${sdk.escapeForLike(term)}%'`,
In Campaign, xpaths are used to access attributes of entities. When XPaths are used in XTK expressions, there can be ambiguities, for instance, in the expression "country/@name", is "country/@name" a xpath or are we dividing the variable country by the value of the attribute @name?
Amibiguity can be resolved by "expanding" the xpath from "country/@name" to "[country/@name]". The square brackets indicate an xpath.
const expandedXPath = sdk.expandXPath(xpath); const unexpandedXPath = sdk.unexpandXPath(expandedXPath);
This function allows to convert literal values to xtk text constants, providing correct serialization. For instance, text constants will be quoted with single quotes, timestamps with the "#" character, etc.
expect(sdk.xtkConstText("Hello", "string")).toBe("'Hello'");
expect(sdk.xtkConstText(-42.3, "double")).toBe("-42.3");
expect(sdk.xtkConstText("2022-02-15T09:49:04.000Z", "datetime"))
.toBe("#2022-02-15T09:49:04.000Z#");