This document is a guide for using the BulkEditDocuments, EditAllDocuments, EditDocuments, TestAllDocuments and TestEditDocuments web methods found on the DbxlAdmin.asmx web service. These methods are intended for admin-use only and should be used with care, as one Bulk Edit operation may impact a large number of documents.
Overview
Intended Use
These methods are intended to be used by an administrator or developer who needs to make a change to a node in the XML of several documents stored within DBXL. A single call can update nodes in several documents at once without ever having to open InfoPath.
Bulk Behavior
The batch operation performs a skip-on-error iteration for the documents. If a document in the batch fails the edit for some reason (node does not exist), then an error is added to the dataFields’ return with details, and the next iteration is executed.
The Success node within dataFields only returns true if all documents were edited without error, otherwise it returns false.
The total number of changes performed is returned as an ErrorInfo node in dataFields. This count includes all changes within each document, so if you are changing a repeating node this number could be several times greater than the number of documents that are edited.
Permissions
Permissions are handled implicitly by the SetDocument method. The user who calls one of the EditDocuments methods is the user used for making comparisons for permissions purposes.
EditAllDocuments
This method performs the specified edits to all documents within the specified Document Type.
Parameters
• docTypeName – the name of the Document Type you wish to edit documents within
• xPaths – Each string passed is used to find the node(s) within each document to insert the corresponding new value into. Full freedom of axes and comparison constructs are allowed in each xPath. The number of xPath nodes must match the number of newValue nodes. An xPath may contain conditional logic so that only certain nodes are updated.
• newValues – Each string passed is inserted into the node specified by the corresponding xPath. The number of newValue nodes must match the number of xPath nodes.
FIGURE 1
Return
• Success – returns true when all documents where edited correctly, false otherwise.
• ErrorInfo – used to pass errors encountered when editing the documents, as well as returning information about the number of edits made.
• ExecutionTime – the time taken to execute the call to the web method.
TestEditAllDocuments
TestEditAllDocuments works in the same way as EditAllDocuments, but changes are not committed. The total changes are calculated and returned.
EditDocuments
This method performs the specified edits to all documents specified by the list of docIds. Generally, the documents are in the same Document Type, but this is not enforced by the web method.
Parameters
• docIds – A list of docIds to perform the edits on.
• xPaths – Each string passed is used to find the node(s) within each document to insert the corresponding new value into. Full freedom of axes and comparison constructs are allowed in each xPath. The number of xPath nodes must match the number of newValue nodes. An xPath may contain conditional logic so that only certain nodes are updated.
• newValues – Each string passed is inserted into the node specified by the corresponding xPath. The number of newValue nodes must match the number of xPath nodes.
FIGURE 2
Return
• Success – returns true when all documents where edited correctly, false otherwise.
• ErrorInfo – used to pass errors encountered when editing the documents, as well as returning information about the number of edits made.
• ExecutionTime – the time taken to execute the call to the web method.
TestEditDocuments
TestEditDocuments works in the same way as EditDocuments, but the changes are not committed. The total changes are calculated and returned.
BulkEditDocuments
This method abstracts calls to EditDocuments to allow multiple edits to be performed with one call to the web service.
Parameters
• EditDocuments – Each object passed here represents a distinct call to EditDocuments, where ID is a value simply provided for the user to distinguish between calls to the service.
FIGURE 3
Return
• Success – returns true when all documents where edited correctly, false otherwise.
• ErrorInfo – used to pass errors encountered when editing the documents, as well as returning information about the number of edits made.
• ExecutionTime – the time taken to execute the call to the web method.
Editing the DBXL MetaData Values
DBXL uses Mapping Tokens, as seen in the Documents tab of DAT. The data displayed in the catalog view of your qForm-based solution uses this same data during creation and update of a document, but the Bulk Edit Tool must perform two separate operations to maintain the two values in sync.
FIGURE 4
For example, in the default catalog view for a qForm, there is a checkbox to show the document’s descriptions. The value shown in the Documents tab of DAT and in the Catalog view of the qForm can be changed by altering the value for DBXL::Description. If you make this change, then open the document’s XML, you’ll see the value in the Description field in the form hasn’t changed. That value must be changed by modifying the value for /my:QdCatalog/my:QdForm/@my:description.
The table below shows the Xpath values for the DBXL Mapping tokens:
Note that the only comparison operation available when updating the MetaData values is testing the previous value.
Example:
xPath = DBXL::Name[ . = ‘Matt’ ]
newValue = Bob
In this example, only the name values that currently have the value of ‘Matt’ will be changed to the new value of ‘Bob’.