This document is meant as an SDK reference for developers that will be integrating DBXL Web Services with their InfoPath forms or any other application. The attached document describes all of the methods in each of the web services. This document is also included in the DBXL v2.2 installer.
Web Services with Ex Suffix
There are two versions of some of the web services, one of which has an “Ex” suffix. These “Ex” APIs differ from their “non-Ex” counterparts only in the way errors are handled. Methods defined in the “Ex” pages return a SoapException when an error occurs. This allows InfoPath’s internal mechanism to detect the error and display an error message. The “non-Ex” methods return a StatusInfo object with a Status node, of value true or false, and error messages. Calling the non-Ex methods requires form logic to check the Success indicator and handle any errors.
DbxlSampleDocumentService
This web service provides identical functionality to the DbxlDocumentService web service, except that everything that it returns is derived from the sampledata.xml file present for the form template of the Document Type queried. This is necessary for InfoPath to derive a schema for the form when there are no documents in the Document Type. Also, when there are documents with varying schemas in a particular Document Type (which is considered bad practice), InfoPath cannot derive a schema for the Content node, regardless.
References to this web service are automatically redirected to DbxlDocumentService whenever a form is published in DAT. This way, you can develop a form with the Sample Data, but when it is deployed it will use the actual data.
QdabraDBXL Processing Instruction
When resubmitting a Document that has already been assigned a Document ID, the QdabraDBXL Processing Instruction must be present in the XML. DBXL uses this PI to determine whether the Document being submitted is new or existing. If it finds the PI with the attributes specified correctly, then it will move the old version of that Document to the archives, and then insert the new Document.
Use the following example to construct the QdbraDBXL PI. The docid and doctype values should come from those defined in the DBXL Admin Tool.
<?QdabraDBXL docid="_int_" doctype="_doc_type_name_" name="_meta_data_" author="_meta_data_" description="_meta_data_" ?>
The codeless means to handle the insertion of the QdabraDBXL PI is to open the corresponding Document via Document Linking and Loading. When opening a Document from the web service, the QdabraDBXL PI is automatically injected.
It is recommended that you copy-paste the examples below into Visual Studio, as they will be much easier to read in an actual coding environment. These samples were created using Visual Studio 2005 and InfoPath 2003.
Using a Secondary Data Connection setup to Receive Data
The most common way to interact with the DBXL web services is to receive data from them. The following code sample shows the most common way to do this with code.
// Retrieve a handle to the secondary data connection. The string passed to GetDOM()
// is the name as for the data connection as defined in the InfoPath Designer.
IXMLDOMDocument3 domGetDocumentsByType = (IXMLDOMDocument3)thisXDocument.GetDOM("GetDocumentsByType");
// Setup the namespaces for the secondary data connection. For more information, see
// this HowTo: http://www.infopathdev.com/blogs/matt/archive/2006/02/02/Setup-Namespaces-for-a-Secondary-Data-Source.aspx
domGetDocumentsByType.setProperty(
"SelectionNamespaces",
" xmlns:my=\"http://schemas.microsoft.com/office/infopath/2003/myXSD/2007-02-01T19-18-48\" "
+ " xmlns:dfs=\"http://schemas.microsoft.com/office/infopath/2003/dataFormSolution\" "
+ " xmlns:ns4=\"http://qdabra.com/webservices/\" ");
// Change the value of a parameter
domGetDocumentsByType.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:GetDocumentsByType/ns4:docTypeName").text = "PT_Timecard";
// Query the web service, which will use the new parameter value as defined above
WebServiceAdapter2 wsaGetDocumentsByType = (WebServiceAdapter2)thisXDocument.DataAdapters["GetDocumentsByType"];
wsaGetDocumentsByType.Query();
// Make sure the method invocation was successful
string success = domGetDocumentsByType.selectSingleNode("/dfs:myFields/dfs:dataFields/ns4:GetDocumentsByTypeResponse/ns4:GetDocumentsByTypeResult/ns4:Success").text;
if (success != "true")
throw new Exception("Call to GetDocumentsByType failed.");
// Get values from the returned set
string docId = domGetDocumentsByType.selectSingleNode("/dfs:myFields/dfs:dataFields/ns4:GetDocumentsByTypeResponse/ns4:docInfos/ns4:DocumentInfo/ns4:DocID").text;
Calling SubmitDocument setup as a Receive Data Connection
There are two ways to submit documents into DBXL. The way that is documented in the Getting Started and other documents is to add a secondary data connection that is setup to Submit Data, but there will be situations (such as creating a catalog-type form) where you will want to programmatically work with the SubmitDocument web method. If you setup this web method as a "submit data" connection then it is very difficult to work with in code. The below code sample demonstrates how to use a SubmitDocument data connection as a "receive data" connection. The XML that is assigned to the xml parameter is trivial in this example, but when developing forms it will contain the entire XML of the form to be submitted. If it is a new document, it will not have the QdabraDBXL Processing Instructions, but if it is an update of a form that already has a Document ID, then the QdabraDBXL PI should be added to the top of the submitted XML.
// Retrieve a handle to the secondary data connection.
IXMLDOMDocument3 domSubmitDocument = (IXMLDOMDocument3)thisXDocument.GetDOM("SubmitDocument");
// Setup namespaces
domSubmitDocument.setProperty(
"SelectionNamespaces",
" xmlns:my=\"http://schemas.microsoft.com/office/infopath/2003/myXSD/2007-02-01T19-18-48\" "
+ " xmlns:dfs=\"http://schemas.microsoft.com/office/infopath/2003/dataFormSolution\" "
+ " xmlns:ns4=\"http://qdabra.com/webservices/\" ");
// Alter the query parameter values
domSubmitDocument.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:SubmitDocument/ns4:docTypeName") .text = "PT_Timecard";
domSubmitDocument.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:SubmitDocument/ns4:xml").text = "<?QdabraDBXL docId=’3’ ?><Root><a>hello</a><b><c>1</c><c>2</c></b></Root>";
domSubmitDocument.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:SubmitDocument/ns4:name").text = "Matt";
domSubmitDocument.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:SubmitDocument/ns4:author").text = "Matt";
domSubmitDocument.selectSingleNode("/dfs:myFields/dfs:queryFields/ns4:SubmitDocument/ns4:description").text = "Latest timecard.";
// Query the web service
WebServiceAdapter2 wsaSubmitDocument = (WebServiceAdapter2)thisXDocument.DataAdapters["SubmitDocument"];
wsaSubmitDocument.Query();
Working with a Secondary Data Connection setup to Submit Data
When a secondary data connection is set up to submit data, the object model only supports a limited amount of access. The submission process can be initiated, and then the results can be viewed, but other than that there is not much else available.
// Submit the data connection as defined in the Data Connection wizard
WebServiceAdapter2 wsaSubmit = (WebServiceAdapter2)thisXDocument.DataAdapters["Submit"];
wsaSubmit.Submit();
// Inspect what was returned by the submit
IXMLDOMDocument2 domSubmitOutput = (IXMLDOMDocument2)thisXDocument.CreateDOM();
domSubmitOutput.async = false;
domSubmitOutput.validateOnParse = false;
domSubmitOutput.loadXML(wsaSubmit.OutputLocation.xml);
domSubmitOutput.setProperty( "SelectionNamespaces",
" xmlns:dfs=\"http://schemas.microsoft.com/office/infopath/2003/dataFormSolution\" "
+ " xmlns:ns4=\"http://qdabra.com/webservices/\" ");
string submitSuccess = domSubmitOutput.selectSingleNode( "/dfs:dataFields/ns4:SubmitDocumentResponse/ns4:SubmitDocumentResult/ns4:Success").text;
thisXDocument.UI.Alert( submitSuccess );
Adding Exception Handling when Working with Ex methods
When using the Ex web methods, adding exception handling will allow you to handle exceptions gracefully when they are returned from the web service.
// Submit the data connection as defined in the Data Connection wizard
WebServiceAdapter2 wsaSubmit = (WebServiceAdapter2)thisXDocument.DataAdapters["SubmitEx"];
try
{
wsaSubmit.Submit();
}
catch (Exception ex)
{
thisXDocument.UI.Alert("SubmitEx method failed. " + ex.Message);
}
Client-side Injection of the QdabraDBXL Processing Instruction
The normal scenario when working with DBXL enabled forms is to open the form template, fill out the form, submit to DBXL, and then immediately close the form. If updates need to be made, the form is reopened from the web service (which injects the QdabraDBXL PI), edited, and then resubmitted. However, it is not always desirable to close the form after initial submission, and then reopen. To remedy this, you can inject the QdabraDBXL PI on the client with code. When doing this, it is best practice to also set the dirty flag to false immediately after a successful submission to the web service so that the user is not confused when they try to close the form and are prompted to save their form, even though it has been successfully saved to the DBXL web service.
1. Open the template.xml file for the form template you are developing.
2. At the very top of the XML, insert a blank QdabraDBXL PI between the other PIs and the root node of the form.
<?xml version="1.0" encoding="UTF-8"?>
<?mso-infoPathSolution name="urn:schemas-microsoft-com:office:infopath:ProjectTracker_Timecard:-myXSD-2006-06-09T06-04-22" href="manifest.xsf" mce_href="manifest.xsf" solutionVersion="1.0.0.881" productVersion="11.0.6565" PIVersion="1.0.0.0" ?>
<?mso-application progid="InfoPath.Document"?>
<?QdabraDBXL?>
<my:Timecard><!-- omitted --></my:Timecard>
3. In the code that handles the submission of the form to the web service, add code that updates the PI of the current form to include the docId.
WebServiceAdapter2 wsAdapter = (WebServiceAdapter2)thisXDocument.DataAdapters["SubmitDocument"];
wsAdapter.Submit();
string docId = wsAdapter.OutputLocation.selectSingleNode("//ns2:docId").text;
thisXDocument.DOM.selectSingleNode(String.Format("/processing-instruction()[local-name(.) = '{0}']", "QdabraDBXL")).text = String.Format(" docid=\"{0}\"", docId);
// Make sure the user does not see the save dialog when closing the form
thisXDocument.SetDirty(false);