Chapter 9 - DBXL

These commands connect a form to Qdabra DBXL: submit the form, or parts of it, as DBXL documents, save pictures and attachments out to DBXL, repoint DBXL data connections and set their user keys, create assignment (QdFlow) documents, load a stored DBXL document into the form, and manage the processing instructions in which DBXL keeps a document's DocID. 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:DocID
  my:Title
  my:Requester
  my:Photos
    my:Photo              (repeating, picture or file attachment field)
  my:Orders
    my:Order              (repeating)
      my:OrderDocID
      my:OrderTitle

and these DBXL web service data connections (query connections, each with its own secondary data source of the same name):

SubmitToDBXL         DBXL SubmitDocument method
SubmitWithKey        DBXL SubmitDocumentWithKey method
GetDocument          DBXL GetDocument method
GetDocumentVersion   DBXL GetDocumentVersion method

9.1 SubmitToDbxl

Submits the form, another data source, or selected nodes to DBXL through a query data connection to DBXL's SubmitDocument, SubmitDocumentWithKey or SubmitDocumentAsUser web method. Use it instead of a plain submit when you need to control the doc type, name, author and description, submit only part of the form, or submit many rows as separate DBXL documents in one step.

Syntax

SubmitToDbxl /submit=<data connection> [/doctype=<doc type>] [/dsname=<data source>] [/docid=<DocID>] [/key=<document key>] [/user=<user>] [/name=<text>] [/author=<text>] [/desc=<text>] [/timeout=<seconds>]
SubmitToDbxl /submit=<data connection> /xpath=<XPath> [/doctypexpath=<relative XPath>] [/docidxpath=<relative XPath>] [/keyxpath=<relative XPath>] [/namexpath=<relative XPath>] [/authorxpath=<relative XPath>] [/descxpath=<relative XPath>] [/resultdocidxpath=<relative XPath>] [/resultrefidxpath=<relative XPath>] [...]

Result: the DocID of the submitted document. When /xpath is used, Result is empty; use /resultdocidxpath to keep each DocID. Success is false with Did not submit any documents if no DocID came back.

Examples

SubmitToDbxl /submit=SubmitToDBXL /doctype=PurchaseRequest /name-xpath=/my:myFields/my:Title /author-xpath=/my:myFields/my:Requester /resultxpath=/my:myFields/my:DocID
SubmitToDbxl /submit=SubmitToDBXL /doctype=Order /xpath=/my:myFields/my:Orders/my:Order /namexpath=my:OrderTitle /docidxpath=my:OrderDocID /resultdocidxpath=my:OrderDocID
SubmitToDbxl /submit=SubmitWithKey /doctype=PurchaseRequest /key-xpath=/my:myFields/my:DocKey

The first submits the whole form as a PurchaseRequest document and writes the new DocID into DocID. The second submits every order row as its own Order document; a row that already has an OrderDocID updates that document, and a new row receives its DocID. The third submits with a document key taken from a field (shown here as my:DocKey; never type a real key into the rule).

Notes

• The connection's method must match the kind of submit. With /key or /keyxpath the connection must use SubmitDocumentWithKey; otherwise, with /user, SubmitDocumentAsUser; otherwise SubmitDocument. A mismatch fails with The submit adapter must use the SubmitDocumentWithKey web method when using submit keys., The submit adapter must use the SubmitDocumentAsUser web method when submitting as a specific user. or The submit adapter must use the SubmitDocument web method when not using submit keys or submitting as another user. If both /key and /user are given, the key submit is used.
• Without /xpath, the DocID is remembered in the form. After a successful submit, the submitted data source gets a QdabraDBXL processing instruction with the DocID and the doc type, name, author and description. The next SubmitToDbxl of the same form therefore updates the same DBXL document. To submit it as a new document instead, run RemoveDbxlPi first. A /docid given without /xpath is written into this processing instruction before the submit.
• With /xpath, each node is submitted as a separate document built from a copy of that node; the form's own processing instructions are not changed. When several nodes are selected, /docid and /key are ignored, so give per-row values with /docidxpath and /keyxpath, and store the returned IDs with /resultdocidxpath.
• A DocID that is empty, 0 or not a number is treated as "no DocID".
• Nodes are submitted one after another. If one fails, the command stops with DBXL's error text (or Error data unavailable / An unspecified error occurred); the nodes before it have already been submitted.
• Errors for the relative paths: Failed to select the DocType node., Failed to select the DocID node., Failed to select the Key node., Failed to select the Name node., Failed to select the Author node., Failed to select the Description node., Failed to select the Result DocID node., Failed to select the Result RefID node. If /xpath selects nothing: Error: No nodes were found using the specified XPath. If the /submit data source does not exist: Error: The specified secondary DOM is not present: name.

Related: SaveToDbxl, RemoveDbxlPi, SwapDomWithDocument.

9.2 SaveToDbxl

Saves pictures or file attachments out of the form into DBXL, one QdFile document per file, and replaces each field's content with a link to the saved file. Use it to keep large files out of the form data.

Syntax

SaveToDbxl /submit=<data connection> /xpath=<XPath> [/dsname=<data source>] [/autoopen=true] [/domainid=<domain ID>] [/qdimage=true]

Result: the number of files saved. Success is false if no file was saved (for example when every selected field is empty).

Example

SaveToDbxl /submit=SubmitToDBXL /xpath=/my:myFields/my:Photos/my:Photo /autoopen=true

Saves every photo in the table to DBXL, clears each field and leaves a link that opens the picture.

Notes

• Each field needs two attributes whose names start with qRulesFilename and qRulesLink (for example my:qRulesFilename and my:qRulesLink). Without them the command fails with Error: The required attributes are missing: 'qRulesFilename' and 'qRulesLink'.
• Each file is submitted as doc type QdFile, with the file name as the document name and the file size (for example 24310 bytes) as the description.
• After a file is saved, the field is emptied and set to nil, qRulesFilename receives the file name and qRulesLink the link. The link is built from the /submit connection's URL: everything before its last /, followed by /Documents/<DocID>/<DocID>.xml, plus ?cmd=file with /autoopen=true.
• Fields are processed one after another. If a save fails, the command stops with DBXL's error description or Unable to save out the file.; files saved before it keep their links.
• After the QdFile, the command tries to add a QdImage (with /qdimage=true) or QdAttachment document and an assignment document for the file. A failure in this step does not stop the command. Success stays true, but Error contains In order to create a QdImage document type along with the QdFile document type, the file must be attached using a picture control, not a file attachment control, and /qdimage must be set to yes. This text appears whenever /qdimage=true or a saved field holds a file attachment, so judge the outcome by Result, not by Error.
• With /qdimage=true, the QdImage document is attempted only for values stored in file attachment format; for a picture control nothing extra is created. The command description in the Command Builder says otherwise; the behavior above is what the engine does.
• If /xpath selects nothing: Error: No nodes were found using the specified XPath.

Related: SubmitToDbxl.

9.3 AdjustDbxlConnections

Repoints every DBXL data connection in the form to another DBXL server, and sets the user key of every user-key-based DBXL connection. Use it on QdabraRules > finishedLoading so that one template works against development, test and production DBXL servers, and so that no user key is stored in the template.

Syntax

AdjustDbxlConnections [/url=<DBXL base URL> | /useurlvariable=true] [/key=<user key> | /usekeyvariable=true]

Result: the number of DBXL connections that were changed.

Examples

AdjustDbxlConnections
AdjustDbxlConnections /usekeyvariable=true
AdjustDbxlConnections /url=https://dbxl-test.mycompany.com/QdabraWebService

The first takes both the URL and the user key from the DbxlUrl and DbxlUserKey environment variables, which is the recommended setup. The second puts a reference to the DbxlUserKey variable into the key fields instead of the key itself. The third only repoints the connections. Avoid typing a key into the command itself (/key=<user key>): the rule text is stored in the template, where anyone with the template can read it.

Notes

• You need a URL or a key. If neither a parameter nor an environment variable provides one, the command fails with Must specify at least one parameter relating to DBXL URL or User Key, or one of these must be available via Environment Variables.
• A parameter wins over the environment variable. /url with /useurlvariable=true fails with Cannot specify both /url and /useurlvariable parameters at the same time.; /key with /usekeyvariable=true fails with Cannot specify both /key and /usekeyvariable parameters at the same time.
• A DBXL connection is a web service connection whose SOAP action is in a Qdabra DBXL namespace. SharePoint and other connections are not touched.
• Only the base of the URL changes. The service file name is kept: with /url=https://dbxl.mycompany.com/QdabraWebService, http://server/QdabraWebService/DbxlDocumentService.asmx becomes https://dbxl.mycompany.com/QdabraWebService/DbxlDocumentService.asmx. A trailing slash in /url is optional.
• When the URL is written as the {fvEnvironmentVariable:DbxlUrl} reference, no slash is added, so the DbxlUrl variable's value must end with a slash (for example https://dbxl.mycompany.com/QdabraWebService/).
• The key is written into the query field named key of connections that use DBXL's user-key services (document and QueryDB services with user key). Connections without such a field keep their URL change only.
• A connection counts once in Result if its URL, its key or both were changed.

Related: SubmitToDbxl, SwapDomWithDocument.

9.4 AssignDocument

Creates a QdFlow assignment document in DBXL (doc type QdEmailFlow) for an existing DBXL document: who it is assigned to, its status, a comment and optional CC recipients. The command description states that it requires DBXL 2.4, and that /email and /ccEmail require DBXL 2.5 or later.

Syntax

AssignDocument /submit=<data connection> /docid=<DocID> /alias=<alias> [/name=<name>] [/email=<address>] [/status=<text>] [/comment=<text>] [/cc=<alias;alias...>] [/ccEmail=<address;address...>] [/myinfo=<data connection>]

Result: the DocID of the new QdFlow document. Success is false with Unable to determine docid of submitted document. if DBXL does not return one.

Example

AssignDocument /submit=SubmitToDBXL /docid-xpath=/my:myFields/my:DocID /alias=jsmith /name=Jane Smith /[email protected] /status=Assigned /comment=Please review

Assigns the document whose DocID is in DocID to Jane Smith with status Assigned.

Notes

• The QdFlow document records the assigning user's alias and name from the signed-in user name, and the date and time of the assignment in UTC (YYYY-MM-DD and hh:mm:ss). Its document name is Document Assignment.
• Each CC alias is stored as both the CC alias and the CC name. If /ccEmail is given, it must have as many entries as /cc, or the command fails with If providing a value for the /ccEmail parameter, you must include the same number of emails as aliases in the /cc parameter
• /myinfo must name an existing data source (Error: The specified secondary DOM is not present: name), but the assigning user is currently always taken from the signed-in user name. The command description in the Command Builder says /myinfo is used to determine the alias and name; the behavior above is what the engine does.
• DBXL's own error text is not passed on; any failed submit ends with Unable to determine docid of submitted document.

Related: SubmitToDbxl.

9.5 SwapDomWithDocument

Loads a document stored in DBXL into the open form: it runs a GetDocument (or GetDocumentVersion) connection for a DocID and replaces the main data source's content with the retrieved XML. Use it to open another DBXL document, or an earlier version of it, without leaving the form.

Syntax

SwapDomWithDocument /getdocument=<data connection> /docid=<DocID> [/version=<version>] [/upgradedocument=true]

Result: empty on success.

Examples

SwapDomWithDocument /getdocument=GetDocument /docid-xpath=/my:myFields/my:DocID
SwapDomWithDocument /getdocument=GetDocumentVersion /docid=1042 /version=3 /upgradedocument=true

The first loads the document whose DocID is in DocID. The second loads version 3 of document 1042 and upgrades it to the current template.

Notes

• Only the main data source is replaced. The root element of the form stays; its child nodes are replaced by those of the retrieved document, and root attributes that already exist in the form take the retrieved values. Attributes the form's root does not have are not added.
• After loading, the main data source's QdabraDBXL processing instruction is set to the loaded DocID and the document's name, author and description, so a following SubmitToDbxl updates the loaded document.
• /upgradedocument=true only has an effect when the template's upgrade setting is a transform; otherwise the document is loaded as it is. An upgrade error fails with An error occurred trying to upgrade the document: followed by the reason.
• Errors: Invalid document id: value, Unable to locate GetDocumentResult node, Unable to locate Success node, Unable to find Content element, Unable to locate contents of document to swap, and Errow swapping DOM: followed by the reason. If DBXL reports a failure, Error lists each DBXL error as code: description, or No specific errors were returned.

Related: SubmitToDbxl, RemoveDbxlPi.

9.6 RemoveDbxlPi

Removes the QdabraDBXL processing instruction, in which DBXL and SubmitToDbxl keep the document's DocID, doc type, name, author and description. Use it before SubmitToDbxl to save the form as a new DBXL document instead of updating the one it came from (for example a "Copy as new" button).

Syntax

RemoveDbxlPi [/dsname=<data source>]

Result: empty on success. Success is false with The specified processing instruction was not found. if the data source has no QdabraDBXL processing instruction.

Example

RemoveDbxlPi

Notes

• The command description in the Command Builder says the command takes no parameters; it does accept /dsname.
• A form that was never submitted to DBXL has no such processing instruction, so expect Success false there.

Related: SubmitToDbxl, RemovePi, InsertPi.

9.7 InsertPi

Adds a processing instruction to the top of a data source, before its root element, or replaces one that already exists.

Syntax

InsertPi /name=<PI name> /data=<text> [/update=true] [/dsname=<data source>]

Result: empty on success.

Example

InsertPi /name=QdabraDBXL /data=docid="1042" /update=true

Points the form at DBXL document 1042, so that a following SubmitToDbxl updates that document.

Notes

• Without /update=true, an existing processing instruction with the same name fails with The specified PI already exists.
• The new processing instruction is placed directly before the root element. Other errors: Error occurred trying to insert PI: followed by the reason.

Related: RemovePi, RemoveDbxlPi.

9.8 RemovePi

Removes a processing instruction, by name, from the main data source.

Syntax

RemovePi /name=<PI name>

Result: empty on success. Success is false with The specified processing instruction was not found. if there is none with that name.

Example

RemovePi /name=QdabraDBXL

Does the same as RemoveDbxlPi for the main data source.

Notes

• Works on the main data source only. For a secondary data source, only the QdabraDBXL processing instruction can be removed, with RemoveDbxlPi /dsname.
• If several processing instructions have the same name, only the first is removed.

Related: InsertPi, RemoveDbxlPi.

Back to the Command Index.