Chapter 8 - SharePoint

These twelve commands connect a form to SharePoint: submit the form to a form library, write its data to one or more lists and read changes back, upload attachments and pictures to a document library, delete files, create folders, look up a list's GUID, read a user's profile, and work with managed metadata (term sets). 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:Title
  my:RequestId            (attribute qRulesLastModified)
  my:FolderPath
  my:Items
    my:Item               (repeating)
      my:ItemId           (attribute qRulesLastModified)
      my:Description
      my:Amount
  my:Attachments
    my:Attachment         (repeating; file attachment with attributes qRulesFilename, qRulesLink)

8.1 SubmitToSharePoint

Submits the form's XML (or the XML of another data source) to a SharePoint form library through a library submit data connection. Use it instead of a plain Submit using a data connection action when you want to choose the folder or the overwrite behavior at run time.

Syntax

SubmitToSharePoint /dssubmit=<data connection> [/dsname=<data source>] [/url=<folder URL>] [/overwrite=true|false]

Result: empty on success.

Example

SubmitToSharePoint /dssubmit=SharePoint Library Submit /overwrite=true

Submits the main data source through the connection SharePoint Library Submit, replacing an existing file of the same name.

Notes

• The connection must be a SharePoint library submit connection. Any other connection type fails with Invalid connection type for dssubmit.
• Everything else about the submit (library, file name) comes from the data connection's own settings.

Related: SaveToSharePoint, CreateSharePointFolder.

8.2 SubmitToSharePointList

Writes form data to one or more SharePoint lists, following a mapping file that says which form field goes to which list column. It creates new list items, updates items it created before, can upload attachments to the items, and can fill child lists from repeating groups with the parent item's ID. Use it together with RefreshSharePointListItems to read later list edits back into the form.

Syntax

SubmitToSharePointList [/mapping=<data source>] [/mappingName=<name>] [/id=<relative XPath>] [/dsname=<any value>] [/xpath=<relative XPath>] [/clear=true|false] [/submit=<data connection>]

Result: empty. Success is false when any list submit, attachment upload or item deletion failed.

The mapping file

The mapping file is an XML file, created with the Qdabra InfoPath to SharePoint List mapping tool and added to the template as an XML data source (named mapping unless you pass /mapping). It contains one Mappings element per list. The engine reads these parts:

Examples

SubmitToSharePointList
SubmitToSharePointList /mappingName=Requests /dsname=AddAttachment

The first submits every mapping in the mapping data source. The second submits only the Requests mapping and its child mappings, and also uploads the files in the field marked as attachment to the new or updated list items.

Notes

• New or update. A row whose ID field is empty or not a number becomes a new list item. After the submit, the new item's ID is written into the ID field, so the next submit updates the same item. If the ID field has an attribute whose name starts with qRulesLastModified, it receives the item's modified time; RefreshSharePointListItems needs it.
• Child lists. Child mappings run after their parent, once per submitted parent row. A field marked IsParentId receives the parent row's list item ID.
• Field types. Rich text fields are sent as HTML. Date fields must be valid dates or empty, otherwise the command fails with Could not submit to list, invalid date: value. Person fields send the account IDs of every person in the field. A mapped field that is not found in a row sends no value.
• Deletes. qRules keeps a record of the items it knows about in the mapping data source (SharePointItems), created the first time RefreshSharePointListItems runs and updated by later submits. When a recorded ID is no longer in the form, that list item is deleted from the list. Removing a row from the form and submitting again therefore removes the list item.
• ID field. If an ID path is known but none of the mapped rows has that field, the command fails with Failed to select node for SharePoint List Id: path.
• Attachments are uploaded only when /dsname is given and an attachment field is known (from /xpath or the mapping). They also need an ID path, or the command fails with Adding attachments requires specifying the ID either in the mapping or the command. Each attachment field must have the attributes qRulesFilename and qRulesLink, otherwise Error: The required attributes are missing: 'qRulesFilename' and 'qRulesLink'. After the upload these attributes receive the file name and the attachment's URL.
• /mappingName, like the mapping names inside the file, is case-sensitive, and must name a top-level mapping: Mapping name name was explicitly specified, but it has a parent mapping. Only top-level mappings can be explicitly specified as a parameter value. A name that is not found fails with Failed to get mapping. Can't find mapping node for mapping name name.; a data source without any mapping fails with Failed to get mapping.
• /mappingName and /uniqueName are written in mixed case and must be typed exactly so. /mappingname= fails with Unexpected parameter(s).
• A list error is reported as Errors encountered: Encountered error when submitting to list list: message, several errors separated by ;. A failed delete appears as Error deleting item with ID n: message.
• /submit names a connection that must exist (Error: The specified data connection is not present: name), but the submit itself does not use it.
• To submit the same template to another site, change SharePointListURL in the mapping data source before the command runs. The Dynamic Data Connections XTP has a rule for this, see FormsDesigner User Manual, Chapter 7.

Related: RefreshSharePointListItems, GetListGuid.

8.3 RefreshSharePointListItems

Compares the list items that SubmitToSharePointList created with their current state in SharePoint, and reports or copies back what has changed since, including items that were deleted from the list. It uses the same mapping file.

Syntax

RefreshSharePointListItems [/mode=report|update] [/mapping=<data source>] [/mappingName=<name>]

Result: a report, with the entries separated by ;, for example Report for mapping: Requests;Item 12 does not match;Item 15 is no longer present in SharePoint List.. Success is false if a mapping could not be refreshed; the reasons are in Error, separated by |.

Examples

RefreshSharePointListItems
RefreshSharePointListItems /mode=update /mappingName=Requests

The first reports which items changed in SharePoint. The second copies those changes into the form for the Requests mapping and its child mappings.

Notes

• The ID field needs a qRulesLastModified attribute. Add a text attribute whose name starts with qRulesLastModified to the ID field. SubmitToSharePointList stores the item's modified time there, and Refresh treats an item as changed when the list's Modified time is newer. Without the attribute the command fails with Unable to find qRulesLastModified attribute.
• If no row has the ID field, the command fails with Failed to select node for SharePoint List Id: path. This also happens when the mapped repeating group has no rows yet.
• A mapping without an ID field is skipped with the report entry Skipping mapping "name". No ID XPath specified.
• Report entries: Item n does not match, Item n is no longer present in SharePoint List., All items match., n matching items found., and Warning: The field 'column' was not found in the list.
• In update mode, changed fields are overwritten with the list values and qRulesLastModified is updated. The ID field itself is never changed. Lookup columns return the lookup ID; yes/no columns return true or false; dates return an XML date-time.
• In update mode, an item deleted from the list removes its row from the form (repeating mappings). For a non-repeating mapping only the ID field is cleared, with the entry Delete not available for non-repeating items. Id field has been cleared.
• Rich text columns are not refreshed. A person column stops the refresh of that mapping with Failed to refresh list items: Refreshing person columns is not currently supported.
• If SharePoint returns none of the items, the error is Failed to refresh list items: No list items to refresh. Verify parameters are correct.
• /xpathsrc without /mappingName fails with Must include /mappingName if using /xpathsrc. The mapping name errors are the same as for SubmitToSharePointList.

Related: SubmitToSharePointList.

8.4 SaveToSharePoint

Uploads the files in file attachment or picture fields to a SharePoint document library, and puts the uploaded file's name and URL on the field. Use it to keep large attachments out of the form XML.

Syntax

SaveToSharePoint /url=<library or folder URL> /xpath=<XPath> [/dsname=<data source>] [/name=<file name> | /namexpath=<relative XPath>] [/uniquename=true|false] [/overwrite=true|false] [/clear=true|false]

Result: the number of files uploaded. Success is false when no file was uploaded, for example because every field was empty.

Examples

SaveToSharePoint /url=https://contoso.sharepoint.com/sites/HR/Receipts /xpath=/my:myFields/my:Attachments/my:Attachment
SaveToSharePoint /url=https://contoso.sharepoint.com/sites/HR/Receipts /xpath=/my:myFields/my:Attachments/my:Attachment /uniquename=false /overwrite=true

The first uploads every attachment under a unique name and clears the fields. The second keeps the users' original file names and replaces files that already exist.

Notes

• Each field needs the attributes qRulesFilename and qRulesLink (attribute names starting with those words), even when it is empty. Otherwise the command fails with Error: The required attributes are missing: 'qRulesFilename' and 'qRulesLink'. After the upload qRulesFilename holds the original file name and qRulesLink the URL of the saved file, so the form keeps a link to the file after the field is cleared.
• Empty fields are skipped.
• If the XPath selects nothing, the command fails with Error: No nodes were found using the specified XPath. If /namexpath finds no field, it fails with Invalid file name node XPath.
• With a fixed name (/name, /namexpath or /uniquename=false) and no /overwrite, the command first checks whether the file exists and stops with Failed to save to SharePoint. URL = 'url'. The file already exists. /name gives every file the same name, so with several files use /namexpath.
• An upload error stops the command with Failed to save to SharePoint. URL = 'url'. message. Files uploaded before the error stay saved, and their fields are already cleared.
• The file name is adjusted to a valid SharePoint file name before the upload.

Related: DeleteFromSharePoint, CreateSharePointFolder, SubmitToSharePointList.

8.5 DeleteFromSharePoint

Deletes a file from SharePoint by its URL, for example a file that SaveToSharePoint uploaded earlier and the user has removed.

Syntax

DeleteFromSharePoint /url=<file URL>

Result: empty on success.

Example

DeleteFromSharePoint /url-xpath=/my:myFields/my:Attachments/my:Attachment[1]/@my:qRulesLink

Deletes the file whose URL SaveToSharePoint stored on the first attachment field.

Notes

• If the URL comes from an empty field, the command fails with URL cannot be blank.
• The deletion cannot be undone from the form.

Related: SaveToSharePoint.

8.6 CreateSharePointFolder

Creates a folder, or a path of nested folders, in a SharePoint library or list. Folders that already exist are reused, so it is safe to run before every save.

Syntax

CreateSharePointFolder /name=<folder path> /siteurl=<site URL> /library=<library name> [/type=folder]
CreateSharePointFolder /name=<folder path> /definitionsrc=<data source> /definitionname=<name> [/siteurl=<site URL>] [/library=<library name>]

Result: empty on success.

Examples

CreateSharePointFolder /siteurl=https://contoso.sharepoint.com/sites/HR /library=Receipts /name=2026/October
CreateSharePointFolder /siteurl=https://contoso.sharepoint.com/sites/HR /library=Receipts /name-xpath=/my:myFields/my:FolderPath

The first creates 2026 (if needed) and October inside it. The second takes the path from a field.

A definition file lets several commands share the site and library. Add it as an XML data source; parameters given in the command override its values:

<Definitions>
  <Definition name="Receipts" type="Folder">
    <Properties siteUrl="https://contoso.sharepoint.com/sites/HR" library="Receipts" />
  </Definition>
</Definitions>

CreateSharePointFolder /definitionsrc=FolderDefinitions /definitionname=Receipts /name-xpath=/my:myFields/my:FolderPath

Notes

• Only folders can be created. /type=DocumentSet fails with Invalid definition type: 'DocumentSet'.
• The path must not start with / (Path cannot start with "/".) or contain /../ (Path cannot contain "/../".). Empty segments, such as a trailing /, are ignored.
• Missing site or library: Site url must be specified either as a parameter or in the document set definition., Library name must be specified either as a parameter or in the document set definition.
• Definition errors: /definitionsrc and /definitionname must both be specified if either is specified., Definition not found: 'name', Definition type unspecified. (the type attribute is missing).

Related: SaveToSharePoint, SubmitToSharePoint.

8.7 GetListGuid

Returns the GUID of a SharePoint list from its name. Use it when a connection or command needs the list ID and you only know the list title.

Syntax

GetListGuid /listname=<list name> /siteurl=<site URL> | /dsname=<data connection>

Result: the list's GUID.

Examples

GetListGuid /siteurl=https://contoso.sharepoint.com/sites/HR /listname=Leave Requests
GetListGuid /dsname=GetListItems /listname=Leave Requests

Notes

• Without /siteurl or /dsname the command fails with Either /dsname or /siteurl must be specified. A /dsname connection that does not exist fails with Error: The specified data connection is not present: name.
• With /dsname, the connection URL must end in _vti_bin/Lists.asmx written exactly in that case; otherwise the site URL is not derived correctly. Use /siteurl when in doubt.
• If the list is not found, the command fails with Failed to get GUID for list: message.

Related: SubmitToSharePointList.

8.8 GetUserProfileByName

Reads a user's profile from SharePoint and puts it into a GetUserProfileByName SOAP data connection, as a list of name/value pairs. Use it to pre-fill the requester's name, e-mail or department, or to find the user's manager. FormsDesigner User Manual, Chapter 6 walks through the designer side.

Syntax

GetUserProfileByName [/dsname=<data source>] [/user=<account name>] [/source=default|siteusers|profiles] [/properties=<name>;<name>...]

Result: empty. On success, Error may hold a warning (see Notes).

What the data source receives

The data source's dataFields content is replaced with GetUserProfileByNameResponse > GetUserProfileByNameResult > PropertyData, one PropertyData per property, sorted by name, each with a Name and a Values > ValueData > Value. With /source=siteusers the properties are:

Examples

GetUserProfileByName /source=siteusers
GetUserProfileByName /source=profiles /properties=Manager;Office
GetUserProfileByName /user-xpath=/my:myFields/my:ManagerAccount /dsname=ManagerProfile

The first loads the current user's profile. The third loads another user's profile (for example the manager's account name from a first call) into a second connection.

To copy a property into a field, use Set a field value with the Value whose PropertyData has the right Name, for example .../tns:Value[../../../tns:Name = "PreferredName"]. The prefix depends on your template.

Notes

• Run it when the form opens on QdabraRules > finishedLoading (see Chapter 1), then copy the values with Set a field value actions after the command.
• If the current user is unknown and /user is not given: Please specify a /user value.
• An invalid source fails with Invalid /source value: 'value'.
• A lookup error fails with Failed to retrieve data for the specified user. Error: message.
• The data source must have a dataFields group, otherwise The data source schema is invalid for use with GetUserProfileByName.
• With /source=profiles, if the extra properties cannot be read, the command still succeeds with the basic profile and leaves this warning in Error: An error occurred while retrieving extra properties. This may be due to insufficient app permissions. Consider using the /source=siteusers parameter. Error: message.
• Manager comes back as an account name. To show the manager's name or e-mail, run the command again with /user set to that account.

Related: SetValue, GetValue.

8.9 GetTermPath

Returns the full path of a managed metadata term, for example Products;Hardware;Laptops, from term data that GetTermSets has already loaded.

Syntax

GetTermPath /termId=<term GUID> [/pathsep=<separator>]

Result: the term's path, from the top-level term down to the term itself. A top-level term returns just its label.

Example

GetTermPath /termId-xpath=/my:myFields/my:ProductTermId /pathsep=/

Returns, for example, Products/Hardware/Laptops.

Notes

• The term is looked up in the data source QdabraRules_TermSets, in the part filled by GetTermSets. Run GetTermSets first, with its default destination.
• /termId must be typed in this mixed case; /termid= fails with Unexpected parameter(s).
• If the term is not in the loaded data, the command fails.

Related: GetTermSets, GetTermsByLabel.

8.10 GetTermSetIds

Finds the term sets used by the managed metadata columns of a list or library, and writes their IDs into the query fields of a GetTermSets connection to the SharePoint TaxonomyClientService. It is the first step before GetTermSets.

Syntax

GetTermSetIds [/list=<list name>] [/dsnamesrc=<data connection>] [/dsnamedest=<data source>]

Result: empty on success.

Example

GetTermSetIds /list=Products

Notes

• The /dsnamesrc connection's URL must contain _vti_bin/Lists.asmx (any case); the site URL is the part before it.
• The command fills the query fields sharedServiceIds, termSetIds, clientVersions and clientTimeStamps, one entry per distinct term set, and sets lcid to 1033 if it is empty.
• If the list has no managed metadata columns or its schema cannot be read, the command fails with Unable to parse schema for the list:name or SharePoint's error.

Related: GetTermSets.

8.11 GetTermSets

Loads the terms of the term sets named in a GetTermSets connection's query fields (usually filled by GetTermSetIds) and stores them in the QdabraRules_TermSets data source, where drop-downs and GetTermPath can use them.

Syntax

GetTermSets [/dsnamesrc=<data connection>] [/dsnamedest=<data source>]

Result: empty on success.

Example

GetTermSetIds /list=Products
GetTermSets

Run as two actions in one rule: the first finds the term sets of the Products list, the second loads their terms.

Notes

• The terms are written under QdabraRulesTermSets/GetTermSets (namespace http://qdabra.com/schemas/qrules/taxonomy/) as Container > TermStore, one TermStore per term set. In each, TS is the term set (@a9 ID, @a12 name) and each T is a term: @a9 is the term ID, LS/TL/@a32 the label and TMS/TM/@a40 the parent path.
• The connection's URL must contain /_vti_bin/TaxonomyClientService.asmx (any case); the site URL is the part before it.
• If the termSetIds query field is empty: Cannot execute query. No TermSet ids were found. If it holds no IDs: Cannot execute query. No TermSet IDs are present. If SharePoint returns no terms: GetTermSets returned no result.
• If lcid is empty, 1033 (English) is used.
• The description in the Command Builder says this command takes no parameters; /dsnamesrc and /dsnamedest are accepted as described above.

Related: GetTermSetIds, GetTermPath, GetTermsByLabel.

8.12 GetTermsByLabel

Searches managed metadata for terms whose label matches a search text, and stores the matching terms in the QdabraRules_TermSets data source. Use it for a type-ahead or search box over a term store.

Syntax

GetTermsByLabel [/dsnamesrc=<data connection>] [/dsnamedest=<data source>]

Result: empty on success.

Example

Set the connection's label query field from the user's search box, then run:

GetTermsByLabel

Notes

• The results are written under QdabraRulesTermSets/GetTermsByLabel in the same Container > TermStore format as GetTermSets.
• If label is empty, the command fails with Cannot execute query search text is required.
• If lcid is empty, 1033 (English) is used. The connection's URL must contain /_vti_bin/TaxonomyClientService.asmx.
• GetTermPath reads only the GetTermSets part, not these results.
• The description in the Command Builder says this command takes no parameters; /dsnamesrc and /dsnamedest are accepted as described above.

Related: GetTermSets.

Back to the Command Index.