Chapter 2 - Values and nodes

These eight commands read and change the data in your form: set or read a field, add, copy, move or delete nodes, fill a repeating table from another table, and sort a table. They are the commands you will use most often. 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:Status
  my:Total
  my:Expenses
    my:Expense            (repeating)
      my:Date
      my:Category
      my:Amount
      my:Approved

2.1 SetValue

Sets the value of one field, or of every field that an XPath selects. Use it instead of a plain Set a field value action when you need a filtered path in a repeating group, a field in another data source, or a nil value.

Syntax

SetValue /xpath=<XPath> [/dsname=<data source>] /value=<text> | /blank=true | /nil=true

Result: empty on success.

Examples

SetValue /xpath=/my:myFields/my:Status /value=Approved
SetValue /xpath=/my:myFields/my:Expenses/my:Expense[my:Category='Travel']/my:Approved /value=true
SetValue /xpath=/my:myFields/my:Expenses/my:Expense/my:Date /nil=true

The second example sets Approved on every Travel row at once; the third clears every date in the table correctly.

Notes

• You must give one of /value, /blank or /nil; otherwise the command fails with A value should be specified when not setting blank or nil.
• If the XPath selects nothing, the command fails with Error: No nodes were found using the specified XPath. Nothing is changed.
• To take the new value from another field at run time, use /value-xpath= (see Chapter 1).

Related: GetValue, Delete.

2.2 GetValue

Reads a value and returns it in Result. It can also evaluate an XPath expression (count, sum, concat and so on), and in its multi-row form it writes a computed value into every row of a repeating group.

Syntax

GetValue /xpath=<XPath> [/dsname=<data source>] [/default=<text>]
GetValue /eval=true /xpath=<expression> [/xpathsrc=<XPath>]
GetValue /xpath=<XPath> /reldest=<relative XPath> [/append=true]                 (multi-row, copy)
GetValue /eval=true /xpathsrc=<rows> /xpath=<expression> /reldest=<relative XPath> (multi-row, compute)

Result: the value (single mode), or the number of rows processed (multi-row mode).

Examples

GetValue /xpath=/my:myFields/my:Status /default=Draft
GetValue /eval=true /xpath=count(/my:myFields/my:Expenses/my:Expense)
GetValue /eval=true /xpath=sum(/my:myFields/my:Expenses/my:Expense/my:Amount)
GetValue /eval=true /xpathsrc=/my:myFields/my:Expenses/my:Expense /xpath=concat(my:Category, ': ', my:Amount) /reldest=my:Approved

The last example evaluates the expression once per expense row and writes each row's result into that row's own field.

Notes

• /default covers an empty field only. If the node does not exist at all, single mode fails with Failed to select field. The command description in the Command Builder says otherwise; the behavior above is what the engine does.
• With /eval=true the expression is wrapped in string(), so the result is always text. A number comes back as, for example, 1250 or NaN.
• In multi-row mode every source node must have the /reldest field, or the command fails with Failed to select the destination node. after updating the rows before it.
• /xpathnode, /contextnode and /append are only valid with /reldest.

Related: SetValue.

2.3 Copy

Copies nodes, with everything inside them, to a new place in the same or another data source. The source stays where it is.

Syntax

Copy /sourcepath=<XPath> /destpath=<XPath> [/sourceds=<data source>] [/destds=<data source>] [/location=lastChild|firstChild|before|after]

Result: empty on success.

Examples

Copy /sourcepath=/my:myFields/my:Expenses/my:Expense[1] /destpath=/my:myFields/my:Expenses
Copy /sourcepath=/my:myFields/my:Expenses/my:Expense[my:Category='Travel'] /destpath=/my:myFields/my:Expenses/my:Expense[1] /location=before

The first example duplicates the first row at the end of the table, including its current values. The second copies every Travel row to the top of the table, keeping their order.

Notes

• When several nodes are copied, the first goes to /location and each following one is placed directly after the previous copy, so the original order is kept.
• The copy keeps the source's element names. Copying a row from a secondary data source (for example a SharePoint or SQL query) into the main data source creates nodes with the secondary data source's names, which do not match your schema. Use CopyTable for that.
• Errors: Failed to select the source node., Failed to select the destination node., Invalid location value. Allowed values are firstChild, lastChild, before and after.

Related: Move, CopyTable, Insert.

2.4 Move

Works exactly like Copy, with the same parameters, but removes each source node after it has been placed. Use it to reorder rows or to move a group to another part of the form.

Syntax

Move /sourcepath=<XPath> /destpath=<XPath> [/sourceds=<data source>] [/destds=<data source>] [/location=lastChild|firstChild|before|after]

Result: empty on success.

Example

Move /sourcepath=/my:myFields/my:Expenses/my:Expense[last()] /destpath=/my:myFields/my:Expenses/my:Expense[1] /location=before

Moves the last row to the top.

Notes

• The source node is deleted right after its copy is inserted. If the deletion fails, the command stops with An error occurred trying to delete the node being moved. and the node exists in both places.
• Do not let /destpath point inside the node you are moving.

Related: Copy, SortTable.

2.5 Insert

Adds new, empty rows to a repeating group or table, in any view. Unlike Copy, the new row is built from the template's default data (the same row you get when a user clicks Insert item), not from an existing row.

Syntax

Insert /parent=<XPath> /child=<relative name> | /xpathsrc=<XPath> [/dsname=<data source>] [/posn=<n>|last] [/count=<n>] [/before=<relative XPath>] [/firstparentonly=true|false]

Result: the number of rows inserted. Success is false if no row was inserted.

Examples

Insert /parent=/my:myFields/my:Expenses /child=my:Expense /count=3
Insert /parent=/my:myFields/my:Expenses /child=my:Expense /posn=1

The first adds three empty rows at the end; the second adds one at the top.

Nested tables: to add a receipt to the second expense only, the parent has a filter, so give the row's full unfiltered path in /xpathsrc:

Insert /parent=/my:myFields/my:Expenses/my:Expense[2]/my:Receipts /xpathsrc=/my:myFields/my:Expenses/my:Expense/my:Receipts/my:Receipt

Notes

• New rows carry the default values defined in the template. To fill them, follow Insert with SetValue, for example on my:Expense[last()].
• Errors: You must include either /child or /xpathsrc., The child parameter value should not start with a slash., Failed to determine the node to insert. You may need to use /xpathsrc, Failed to select the parent node., Position must be "last" or a positive integer., Count must be a positive integer.

Related: Copy, Delete.

2.6 Delete

Deletes every node that an XPath selects: a field, a group, or rows of a repeating table.

Syntax

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

Result: empty on success.

Examples

Delete /xpath=/my:myFields/my:Expenses/my:Expense[my:Amount='']
Delete /xpath=/my:myFields/my:Expenses/my:Expense[position() > 1]

The first removes rows with no amount; the second keeps only the first row.

Notes

• If nothing matches, the command reports Success false with Could not locate field to delete. For a clean-up step that may find nothing (for example deleting blank rows), this is expected and can be ignored.
• Deleting a required, non-repeating field makes the form data invalid. Delete rows and optional groups only.

Related: Insert, SetValue.

2.7 CopyTable

Copies rows from one table to another, typically from a query data source (SharePoint list, SQL, web service) into a repeating table in the main data source. Each destination row is built from the template's default data and then filled from the matching source row.

Syntax

CopyTable /tablesrc=<XPath> /rowsrc=<relative XPath> /tabledest=<XPath> /rowdest=<relative XPath> [/dsnamesrc=<data source>] [/dsnamedest=<data source>] [/empty=true] [/xpathdest=<XPath>]

Result: the number of rows copied.

Example

Fill the expense table from a SharePoint list query named ExpenseItems, replacing what is there:

CopyTable /dsnamesrc=ExpenseItems /tablesrc=/dfs:myFields/dfs:dataFields /rowsrc=d:SharePointListItem_RW /tabledest=/my:myFields/my:Expenses /rowdest=my:Expense /empty=true

Notes

• Fields are matched by position, not by name. The first field of the source row goes into the first field of the destination row, the second into the second, and so on. Attributes are matched the same way. Make the query return exactly the destination's fields, in the destination's order.
• Source and destination rows must have the same number of fields and attributes (xsi:nil attributes are ignored), or the command fails with The table row of the source and destination must contain the same number of elements and attributes.
• Rows must be flat: a row that contains a group fails with Copy Table does not work with tables containing groups. Rich text fields are fine. For nested data, use Insert and then SetValue.
• All rows are prepared before any is added, so an error part-way leaves the destination unchanged.

Related: Copy, Insert.

2.8 SortTable

Sorts the rows of a repeating table by one or more fields.

Syntax

SortTable /row=<XPath> /compare=<relative XPath>[,<relative XPath>...] [/order=asc|desc[,...]] [/type=text|number[,...]] [/dsname=<data source>]

Result: empty on success.

Examples

SortTable /row=/my:myFields/my:Expenses/my:Expense /compare=my:Amount /order=desc /type=number
SortTable /row=/my:myFields/my:Expenses/my:Expense /compare=my:Category,my:Date /order=asc,desc /type=text,text

The second sorts by category, and within a category by newest date first.

Notes

• With several compare fields, give /order and /type for each one, even when they are the default. /compare=a,b alone fails with Parameter count mismatch for compare, order, and type parameters., because the defaults count as one value.
• Because commas separate the fields, a compare XPath cannot itself contain a comma (for example concat(a, b)).
• text compares character by character: upper case sorts before lower case, and 10 sorts before 9. Use number for amounts. Dates stored as YYYY-MM-DD sort correctly as text.
• With number, empty or non-numeric values do not sort reliably. Fill them, or sort by text.
• The rows' parent group is rewritten with the sorted rows. Keep the repeating rows alone in their group; any other field in the same group would be removed.
• A table with fewer than two rows is left as it is.

Related: Move.

Back to the Command Index.