Chapter 3 - Text, XML and JSON

These fifteen commands work on the content of fields rather than on the form's structure: read or write a node as an XML string, run an XSL transform, replace text, change case, join repeating values into a list, convert between JSON and XML, encode and decode text, copy and compare rich text, create GUIDs, and encrypt fields with a password. Chapter 1 explains the command syntax, dynamic parameter values and where results go; this chapter assumes you know it.

The examples use this main data source:

my:myFields
  my:Customer
    my:Name
    my:City
  my:Tags
    my:Tag                (repeating)
  my:Description          (rich text)
  my:Revisions
    my:Revision           (repeating)
      my:Before           (rich text)
      my:After            (rich text)
      my:Changes          (rich text)
  my:Payload              (text, holds JSON or XML)
  my:DocumentId
  my:ImportFile           (file attachment)
  my:ExportFile           (file attachment)
  my:Secret
  my:Password

3.1 GetXml

Returns the XML of a node as a string, with or without the node itself. Use it to store a snapshot of a group in a text field, to pass XML to a web service, or to let the user download a data source as an XML file.

Syntax

GetXml [/xpath=<XPath>] [/dsname=<data source>] [/inner=true] [/outer=true] [/download=true] [/filename=<name>]

Result: the XML string.

Examples

GetXml /xpath=/my:myFields/my:Customer
GetXml /xpath=/my:myFields/my:Customer /inner=true
GetXml /dsname=Settings /download=true

For a customer named Contoso in Seattle, the first returns <my:Customer><my:Name>Contoso</my:Name><my:City>Seattle</my:City></my:Customer> (with namespace declarations as needed), the second returns only the two child elements, and the third downloads the whole Settings data source as Settings.xml.

Notes

• If the XPath selects nothing, the command fails with Failed to select source field.
• If the download cannot be started, the command fails with Failed to determine value.
• With /inner=true on a node that has several children, the result has several top-level elements and is not a well-formed XML document on its own. SetXml accepts it as it is.

Related: SetXml, XmlToJson, Transform.

3.2 SetXml

Replaces the content of a node with XML given as a string. It is the counterpart of GetXml: restore a snapshot, load XML returned by a web service into a group, or build nodes from a text value.

Syntax

SetXml /destpath=<XPath> /value=<XML> [/destds=<data source>] [/excludesourceroot=true]

Result: empty on success.

Examples

SetXml /destpath=/my:myFields/my:Customer /value-xpath=/my:myFields/my:Payload /excludesourceroot=true

If Payload holds a copy of the my:Customer group taken with GetXml, this puts its Name and City back into the customer group. Without /excludesourceroot=true, a second my:Customer element would be created inside the existing one.

Notes

• The existing content of the destination is removed first; the parsed XML takes its place.
• Every prefix used in the XML must be declared in the XML itself (for example xmlns:my="..."). GetXml output already includes the declarations it needs.
• If /destpath selects nothing, nothing is changed and the command still succeeds.
• If inserting fails, the error starts with Failed to set the XML to the destination node(s): followed by the reason.
• The inserted nodes are not checked against your schema. Inserting elements that the destination does not allow makes the form data invalid.

Related: GetXml, JsonToXml, Copy.

3.3 Transform

Runs an XSL transform (XSLT) on a node of any data source, or on an XML resource file, and stores the output in the form: as nodes under a destination node, as a text value, or as a file attachment. The XSLT is a resource file in the template. Use it for reshaping data that would take many rules otherwise. This command is for designers who can write XSLT.

Syntax

Transform /xsltfile=<resource file> [/sourcepath=<XPath>] [/sourceds=<data source> | /sourcefile=<resource file>] [/destpath=<XPath>] [/destds=<data source>] [/format=xml|string|base64] [/tostring=true] [/placement=replace|append|prepend] [/excluderoot=true] [/resultfilename=<name>] [/setresult=true]

Result: empty, or the transform output as text when /setresult=true.

Examples

Transform /xsltfile=BuildSummary.xsl /sourcepath=/my:myFields/my:Revisions /destpath=/my:myFields/my:Payload /format=string
Transform /xsltfile=MapOrder.xsl /sourceds=OrderService /destpath=/my:myFields/my:Customer /excluderoot=true
Transform /xsltfile=Export.xsl /destpath=/my:myFields/my:ExportFile /format=base64 /resultfilename=export.xml

The first stores the transformed revisions as text in Payload. The second maps a web service response into the customer group; the XSLT outputs a wrapper element whose children are my:Name and my:City, and /excluderoot=true drops the wrapper. The third saves the transformed main data source as an attached file export.xml in a file attachment field.

Notes

• With xml, the output nodes are inserted as the XSLT produces them. Make the XSLT output elements in your form's namespace and in the order your schema expects.
• The destination must be an element for xml output, or the command fails with The tostring argument must be 'true' when the destination node is a non-element. This includes the default /destpath of /, so give a real group or field.
• With string, append and prepend add the text to the field's current value.
• prepend into a destination that is still empty adds the nodes but then reports an error. Use replace or append when the destination may be empty.
• /format must be lower case. Any other value makes the command fail with An error occurred setting the result of the transform. after the transform has run.
• Errors: Failed to select the source node., Failed to select the destination node., /sourceds and /sourcefile cannot both be specified., resultfilename cannot be blank if format is base64, Invalid placement value: x. Allowed values are: append, prepend, replace, Error: Failed to load the specified file. followed by the reason.

Related: GetXml, SetXml.

3.4 ReplaceString

Replaces every occurrence of a text, or of a regular expression, in a field's value. In its basic form it returns the new text; with /reldest it writes the result into a field for every matching node, so one command can clean up a whole column.

Syntax

ReplaceString /xpathsrc=<XPath> /string1=<text> | /pattern=<regular expression> [/string2=<text>] [/dsnamesrc=<data source>] [/reldest=<relative XPath> [/append=true]]

Result: the new text (single mode), or the number of nodes processed (multi-node mode).

Examples

ReplaceString /xpathsrc=/my:myFields/my:Customer/my:Name /string1=Inc. /string2=Incorporated
ReplaceString /xpathsrc=/my:myFields/my:Tags/my:Tag /pattern=\s+ /string2=- /reldest=.
ReplaceString /xpathsrc=/my:myFields/my:Customer/my:City /pattern=^(\w+), (\w+)$ /string2=$2 $1

The first returns the name with "Inc." spelled out, leaving the field unchanged. The second replaces runs of white space with a hyphen in every tag, in place. The third swaps two comma-separated words.

Notes

• You must give /string1 or /pattern; otherwise the command fails with Either /string1 or /pattern must be provided.
• Matching is case-sensitive in both modes.
• In /string2, $ starts a placeholder ($1, $&). Write $$ for a literal dollar sign.
• To search for or insert text that starts or ends with spaces, pass it with /string1-xpath= or /string2-xpath= from a field (see Chapter 1).
• If /xpathsrc selects nothing, the command fails with Failed to select the source node.
• In multi-node mode, every source node must have the /reldest field. The command stops at the first one that does not, after updating the nodes before it, with Failed to replace string: Failed to select the destination node. An invalid regular expression fails with Failed to replace string: followed by the reason.

Related: SetCase, SetValue.

3.5 SetCase

Returns a field's value in upper or lower case.

Syntax

SetCase /xpathsrc=<XPath> [/dsnamesrc=<data source>] [/case=Upper|Lower]

Result: the converted text. The field itself is not changed.

Example

SetCase /xpathsrc=/my:myFields/my:Customer/my:City /case=Upper /resultxpath=/my:myFields/my:Customer/my:City

Converts the city to capitals and writes it back into the same field with /resultxpath (see Chapter 1).

Notes

• Title is offered in the Command Builder but is not supported: it fails with Title case is not supported in this version of qRules. The command description in the Command Builder says otherwise; the behavior above is what the engine does.
• Any other value fails with Invalid /case value: x, for example for upper in lower case.
• If the XPath selects nothing, the command fails with Failed to select the source node.
• The conversion follows the browser's language rules, so accented and non-Latin letters are converted as well.

Related: ReplaceString.

3.6 DelimitedList

Joins the values of a repeating field, or of a field in a repeating group, into one text with a separator between them. Use it for a summary field, an e-mail recipient list or a filter value.

Syntax

DelimitedList /xpath=<XPath> [/dsname=<data source>] [/separator=<text>] [/space=before|after|both]

Result: the joined text.

Examples

DelimitedList /xpath=/my:myFields/my:Tags/my:Tag /separator=, /space=after
DelimitedList /xpath=/my:myFields/my:Tags/my:Tag[. != '']

The first returns, for example, urgent, finance, review. The second returns urgent;finance;review and skips empty rows.

Notes

• Empty values are included, which produces doubled separators. Filter them out in the XPath, as in the second example.
• If the XPath selects nothing, the command fails with Error: No nodes were found using the specified XPath.
• An explicitly empty /separator= fails with /separator cannot be blank. Other errors: Invalid /space value: x.

Related: GetValue.

3.7 JsonToXml

Converts a JSON string to XML and puts it under a node of a data source. Use it to work with the response of a JSON web API in rules, XPath and repeating tables.

Syntax

JsonToXml /xpath=<XPath> /json=<JSON> [/dsname=<data source>]

Result: empty on success.

Example

JsonToXml /xpath=/Result /dsname=ApiResult /json-xpath=/my:myFields/my:Payload

If Payload holds {"name":"Contoso","id":5,"tags":["new","vip"]}, the Result element of the data source ApiResult becomes:

<Result type="object">
  <id type="number">5</id>
  <name type="string">Contoso</name>
  <tags type="array">
    <tagsItem type="string">new</tagsItem>
    <tagsItem type="string">vip</tagsItem>
  </tags>
</Result>

Notes

• Each JSON property becomes an element named after the key, and every element gets a type attribute: object, array, string, number or boolean. The destination element gets the type of the top-level value.
• Properties are sorted alphabetically by key, not kept in the JSON order.
• Array items are named after the array's key plus Item (tagsItem above). A top-level array produces elements named Item.
• A null value becomes an empty element with null="true".
• A key that is not a valid XML name is encoded (a space becomes _x0020_, for example first_x0020_name) and the original key is kept in a name attribute.
• The new elements have no namespace. Inside the main data source they do not match your schema, so use a destination that allows any content, typically a group in a secondary data source.
• Errors: Invalid JSON: followed by the text, Destination node must be an element. If /xpath selects nothing, the command fails without an error message.

Related: XmlToJson, SetXml.

3.8 XmlToJson

Converts a node of a data source to a JSON string. Use it to build the body of a request to a JSON web API (for example with the MakeRequest command).

Syntax

XmlToJson [/xpath=<XPath>] [/dsname=<data source>]

Result: the JSON string.

Examples

XmlToJson /xpath=/my:myFields/my:Customer
XmlToJson /xpath=/my:myFields/my:Tags

The first returns {"Name":"Contoso","City":"Seattle"}. The second fails with a duplicate key error, because the repeating Tag elements become properties with the same name (see Notes).

Notes

• An element with child elements becomes an object; each child becomes a property named after its local name, without the prefix. An element without child elements becomes a string, so numbers and booleans from ordinary form fields come out as strings.
• The type, name and null attributes written by JsonToXml are honored: type="array" turns the children into an array (their names are ignored), type="number" and type="boolean" give typed values, name sets the property name, and null="true" gives null. Other attributes are ignored. XML produced by JsonToXml therefore converts back to the same JSON (with sorted keys).
• Repeating elements under an element without type="array" fail with Objects cannot contain duplicate keys. Key found: "Tag". Convert repeating data from a group that carries type="array", for example one built with JsonToXml or Transform.
• A type="boolean" element must contain true, false, 1 or 0, or the command fails with Invalid boolean value: x. An empty number or boolean element gives null.
• If the XPath selects nothing, the command fails with Could not find any node at followed by the XPath.

Related: JsonToXml, GetXml.

3.9 Encode

Encodes or decodes text for use in a URL or in HTML.

Syntax

Encode /text=<text> [/type=url|uri|uriComponent|html] [/decode=true]

Result: the encoded or decoded text.

Examples

Encode /text-xpath=/my:myFields/my:Customer/my:Name /type=uriComponent
Encode /text-xpath=/my:myFields/my:Payload /type=html /decode=true

The first turns Smith & Sons into Smith%20%26%20Sons, safe for a query string value. The second turns <b> back into <b>.

Notes

• url and uri are the same. For a value inside a query string, use uriComponent; url would leave & and = unencoded.
• html does not encode the apostrophe, and decoding handles only &, <, > and ".
• An empty /text fails with Required parameter unspecified: text. Add a condition when the source field may be empty.
• An unknown type fails with Unknown value for /type parameter: x. Decoding a malformed % sequence fails.

Related: ConvertBase64.

3.10 ConvertBase64

Decodes a base64 value to text. It also accepts the value of a file attachment field and returns the content of the attached file as text, for example to read an attached XML, CSV or text file.

Syntax

ConvertBase64 /value=<base64> /mode=decode

Result: the decoded text.

Example

ConvertBase64 /value-xpath=/my:myFields/my:ImportFile /mode=decode /resultxpath=/my:myFields/my:Payload

Reads the file attached in ImportFile and puts its text into Payload.

Notes

• The bytes are read as UTF-8, so Japanese, Chinese and other non-ASCII text is decoded correctly.
• Any other mode fails with Invalid /mode value: x.

Related: Encode, Transform.

3.11 CopyRichText

Copies the content of a rich text field into another rich text field, keeping its formatting, in the same or another data source.

Syntax

CopyRichText /xpathsrc=<XPath> /xpathdest=<XPath> [/dsnamesrc=<data source>] [/dsnamedest=<data source>]

Result: empty on success.

Example

CopyRichText /xpathsrc=/my:myFields/my:Description /xpathdest=/my:myFields/my:Revisions/my:Revision[last()]/my:Before

Copies the current description into the Before field of the last revision row.

Notes

• A plain Set a field value action copies only the text of a rich text field. Use this command to keep the formatting.
• Errors: Failed to select the source node to copy from., Failed to select the destination node to copy to.

Related: DiffRichText, Copy.

3.12 DiffRichText

Compares two rich text values and produces a rich text "track changes" view: inserted text is wrapped in <ins> and deleted text in <del>. It can compare one pair, or one pair in every row of a repeating group.

Syntax

DiffRichText /beforepath=<XPath> /afterpath=<XPath> [/dsname=<data source>] [/addstyles=true] [/implementation=dfoverdx|tnwinc]
DiffRichText /parentpath=<XPath> /beforepath=<relative XPath> /afterpath=<relative XPath> /destpath=<relative XPath> [/dsname=<data source>] [/addstyles=true] [/implementation=dfoverdx|tnwinc]

Result: without /parentpath, the comparison as HTML text. With /parentpath, empty.

Examples

DiffRichText /parentpath=/my:myFields/my:Revisions/my:Revision /beforepath=my:Before /afterpath=my:After /destpath=my:Changes /addstyles=true
DiffRichText /parentpath=/my:myFields /beforepath=my:Revisions/my:Revision[1]/my:After /afterpath=my:Description /destpath=my:Revisions/my:Revision[1]/my:Changes

The first fills Changes in every revision row with the marked-up differences and turns on the highlight colors. The second compares one pair and writes it into one rich text field, by using the common parent as /parentpath.

Notes

• Without /parentpath, /destpath is ignored and the comparison only comes back in Result, as HTML markup in plain text. To write the comparison into a rich text field, use /parentpath as in the second example.
• The styles from /addstyles stay on the page for the rest of the session. Without them, the browser shows its default underline and strikethrough for inserted and deleted text.
• If the default engine's output does not suit your content, try /implementation=tnwinc.
• Errors: Could not find /beforepath node, Could not find /afterpath node, Could not find /destpath node, /destpath must be specified if /parentpath is., Invalid implementation value: x. If /parentpath selects nothing: Error: No nodes were found using the specified XPath.
• With /parentpath, rows before a failing row are already updated.

Related: CopyRichText.

3.13 GenerateGuid

Returns a new GUID (globally unique identifier). Use it for a unique document ID, a file name or a key for related records.

Syntax

GenerateGuid [/format=B|D|N|P]

Result: the GUID.

Examples

GenerateGuid /resultxpath=/my:myFields/my:DocumentId
GenerateGuid /format=N

The first writes a GUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx into DocumentId. The second returns the 32 digits without dashes.

Notes

• Any other format fails with /format must be one of the following: B, D, N, P.
• To create the ID only once, run the command on QdabraRules > finishedLoading with a condition that DocumentId is blank.

Related: SetValue.

3.14 Encrypt

Encrypts the content of one or more fields with a password that the user types into another field. The value is replaced by encrypted text that can only be read again with Decrypt and the same password. Text, rich text and file attachment fields can be encrypted.

Syntax

Encrypt /xpath=<XPath> /pass=<XPath> [/dsnamepass=<data source>] [/clear=true|false] [/pad=true]

Result: empty on success.

Example

Encrypt /xpath=/my:myFields/my:Secret /pass=/my:myFields/my:Password

Encrypts Secret with the password in Password, then clears Password.

Notes

• The whole content of the field is encrypted, including the formatting of rich text and the file in an attachment field.
• The encryption is done by the Qdabra Forms service. qRules does not store passwords: if the password is lost, the data cannot be recovered.
• A field is skipped with Not valid for qRules encryption. Ensure field is not blank, is not already encrypted and that you have entered a password. when it is empty, already encrypted (its value starts with qdEncrypted), or the password is empty.
• Each field is processed on its own. If some fail, Success is false and Error lists one message per failed field on separate lines; the other fields are still encrypted.
• Other errors: Cannot locate password. Please check command and retry. (the /pass XPath selects nothing), Error: No nodes were found using the specified XPath. (the /xpath selects nothing), Unable to encrypt the text.
• Encrypted text is not a valid date, number or other typed value. Encrypt text, rich text and attachment fields only.

Related: Decrypt.

3.15 Decrypt

Restores fields encrypted with Encrypt, using the same password.

Syntax

Decrypt /xpath=<XPath> /pass=<XPath> [/dsnamepass=<data source>] [/clear=true|false]

Result: empty on success.

Example

Decrypt /xpath=/my:myFields/my:Secret /pass=/my:myFields/my:Password /clear=false

Decrypts Secret and keeps the password in Password, for example to decrypt more fields with a later command.

Notes

• The decrypted content replaces the field's value, so rich text formatting and attachments come back as they were.
• Each field is processed on its own. If some fail, Success is false and Error lists one message per failed field; the other fields are still decrypted. An empty password gives Not valid for qRules encryption. Ensure field is not blank, is not already encrypted and that you have entered a password.
• When the service rejects a value without giving a reason, the error reads Unable to encrypt the text., even though the command is decrypting.
• Other errors: Cannot locate password. Please check command and retry., Error: No nodes were found using the specified XPath.

Related: Encrypt.

Back to the Command Index.