Webservice: SOAP implementation

Structure

Protocol

Server

API Key

Formdesk uses the following namespaces:

Formdesk uses namespaces only to prefix ellement attributes. The default namespace is urn:formdesk:attributes and so the default attribute prefix fd:.

Note that these namespaces and prefixes are not required when a method accepts XML input (like the Params input parameter).

Some methods, like FormResultsAdd or FilesRemove, accept a kind of recordset as input. Because the status of each 'record' can be different, Formdesk adds a status attribute (rs:status) to the 'record' element itself. When the status code is different than 200 a message attribute (rs:message) is also included.
These attributes, status and message, are prefixed with rs: to avoid attribute name conflicts.

Custom Namespaces

All methods which accept XML data as input will output this same XML. This gives you the ability to add your own attributes to 'record' elements, like for instance your own database id. Because these attributes are still present in the output XML you are able to link back to your database.

To avoid attribute name conflicts it is strongly advisable to use your own namespace and prefix to specify additional attributes.

It is very important to note that each parameter specified in the method definition is required. Leaving out a parameter can result in an error message. If you don't need a parameter, like the Params parameter, you can just pass an empty string.

The Params parameter, of many methods, is a special xml formatted string. The basic structure is described below.

Basic structure of the Params XML format

NOTE that the xmlns namespace and fd: attribute prefix may be ommitted. The dt attribute may also be ommitted. When the dt attribute is ommitted Formdesk treats the parameter value as of type string.

Important notice when using SoapUI

SoapUI is an excellent webservice testsuite. More infomation about SoapUI.

Normally, SOAP is used to remove the code burden from the developer and allows you to use a webservice like any other object in the development environment. SoapUI is a tool to explore and test a webservice presenting you the raw XML request en reponse messages. The only difficulty is that you have to understand the code behind the SOAP protocol. At least so you are able to integrate the parameters into a soap request.

The parameter formatting Formdesk uses is mostly XML while the code behind the SOAP request also consist of XML. The main reason for this way of parameter formatting is the flexibility in expanding the functionality of methods without the need of the connecting party (you) to rewrite the software. A drawback we are experiencing when you are using SoapUI to test the webservice is that this parameter formatting can be a bit confusing.

Below is an example of a SoapUI request for the FormResultsGet method:

The first parameter FormName is strait forward. You just replace the question mark with the name of the form.

The second parameter Params however, could be a bit confusing. Params is the name of this parameter and has nothing to do with the params root node of the parameter content string as described in the section Basic structure of the Params XML format above.

A second thing to notice is that the content of a parameter has to be encoded or placed in a CDATA xml node.

Below is a complete example of the SoapUI request for the FormResultsGet method:

Basic structure of the XML result value

Example of an extended structure of the XML result

Methods which accept a kind of recordset, like for instance FormResultsAdd or FilesRemove, return a status code on a record/xmlnode itself. This is because the operation on one record can succeed and another for instance fails with code 404.5 'Result entry not found'.

Only when the rs:status code is different then 200, indicating an error, the rs:message attribute is present. To avoid a name conflict these status attributes use the rs: prefix and the xmlns:rs namespace attribute is added to the root element.

See the list of possible Status Codes.

• You firstly use the www.formdesk.com webservice URL in the call to the Connect method.
• Formdesk responses with information to connect to the correct Formdesk server. In this example your account resides on the fd8.formdesk.com server.
• Secondly you change the webservice URL to point to fd8.formdesk.com and call the FormResultsGet method.
• Formdesk responses with a list of the completed result entry id's of the specified form with a download status of new or changed.
• For each id in the list:
  • Call the FormResultGet method to get the result entry details.
  • Call the FormResultProcessed method to mark the download status of the result entry as processed.

The urlsoap is the most important element. This value contains the complete webservice URL to the server on which your account resides.

The timezone specifies the timezone in which the date(time) values are returned. You can use the datetime_in_gmt or id_tzi parameters to override this timezone setting. You can use the ListGet() method to find out a specific timezone id which can be used with the id_tzi input parameter.

This method can be used for Single SignOn purpose where users can access their Formdesk account or visitors can access a form without the need to enter their username and password.

• The user is surfing the intranet and clicks on a link to view the results of a form.
• The intranet server receives the request from the client and requests Formdesk to open a session for that user.
• Formdesk starts a session and returns a redirect URL.
• The intranet server returns a redirect response to the client.
• The client redirects the user to Formdesk.
• The user now has access to Formdesk.

All data parameters are optional. The only requirement is that the query based upon the given search parameters result in only one user or visitor.
When a form identification is passed (form_name or form_id) Formdesk only queries the visitor accounts. Otherwise Formdesk queries the supervisor account and the sub-user accounts.

The URL can be used to redirect the user to Formdesk.

This method can be used to push form data to Formdesk whithout the need of passing the data using URL parameters. The data is parked temporarily and a ticked is returned. When a valid ticket is passed to a form Formdesk will prefill the form using the parked data.

Formdesk can only prefill fields of which the identifier is found as parameter name.
NOTE that unlike the URL parameter names the parameter names (identifiers) here are without the def_ prefix.

The ticket value is a string of 32 characters (GUID) which can be used as parameter of a request to a form.
https://www.formdesk.com/yourdomain/yourform?ticket=abaf6bbf8dc74221aa49fe25d6841040. Formdesk will then use the parked parameters as form field values.
Note that you can use parked or ticket as parameter name.

• Use the Connect method to determine the correct Formdesk server to make the Api calls.
• Formdesk responses with information to connect to the correct Formdesk server.
• Call the FormResultsGet method like: FormResultsGet('form1', '').
• Formdesk responses with the completed (status DONE) result entry id's of form1 with a sync status of new or changed.
• Call the FormResultGet method to get the result entry details.
• Call the FormResultProcessed method to mark the sync status of these result entries as processed.
• From the Formdesk response you can determine if all or which result entries have been processed succesfully.

• Simply synchonize result entries.
• Use parameters and/or pre-defined filters to select form results based on search and/or pre-defined criteria.

The result elements contain only one child element. The name of this child element (_fd_id) matches the same element in the result of a call to the method FormResultGet.

Example:

• Save the xsd:schema node xml to a file, for instance results.xsd
• Replace the value of the xsi:noNamespaceSchemaLocation attribute (%schema%) on the results node with schema filename
• Save the results node xml to a file, for instance results.xml
• Now you can open the results.xml file in MS Excel

• Synchonize form results.

The result child elements prefixed with _fd_ are Formdesk system fields. See System Fields table for the possible fields included in the result xml.

Each question in a Formdesk form has a so called identifier. This identifier also represents a child element in the xml result xml. NOTE that all xml element names are in lowercase.

When the form contains one or more form upload elements a files element is included with the uploaded files belonging to the result entry. When the parameter include_files is passed and true the content will be included within the file elements. To avoid very large soap responses and possible buffer limitations, it is best practice to take the fd:url attribute from a file element and load the file contents with a simple http request. The fd:url attribute value contains the complete URL to the file including a sid parameter. The sid parameter contains a session id which is valid for 24 hours. After that time the URL can not be used anymore.

Example:

• Save the xsd:schema node xml to a file, for instance results.xsd
• Replace the value of the xsi:noNamespaceSchemaLocation attribute (%schema%) on the results node with schema filename
• Save the results node xml to a file, for instance results.xml
• Now you can open the results.xml file in MS Excel

There is no required data. An empty result node will just result in an empty result entry in the database. Only when the result entry is maintainable by the visitor the visitor data must be identifiable to match an existing visitor or to create a new visitor. A result node with only a _fd_usrid node will result in an empty result entry linked to the specified visitor.

When a form is maintainable the visitor data can also be updated and/or added along with the result data. Visitor data consists of the following xml elements:

• _fd_usrid - Visitor id (optional and only to specify an existing visitor)
• _fd_user - Visitor name (required when no _fd_usrid is provided or the visitor does not exist)
• _fd_email - Visitor email address (required when no _fd_usrid is provided or the visitor does not exist)
• _fd_usrnm - Login Username (optional, if not present Formdesk used the _fd_user value)
• _fd_psswrd - Login Password (optional, if not present Formdesk creates a password of 10 random characters)

The resulting xml contains only the result entry system data. See the list of system fields for the possible fields.

Added result entries are not counted as submissions. However, they are included in the stored results count.
Posible error status codes for this operation are: 404.2, 404.4, 409.4, 409.6. See the list of status codes for the description.

Same data as the FormResultAdd method.

Same result as the FormResultAdd method.
Updated result entries are not counted as submissions.

This method also supports the Microsoft .Net Framework DataSet DiffGram format.
For instance you could use the FormResultGet method, load the result into a DataSet, change some values and pass the resulting DiffGram as input parameter to the FormResultUpdate method.

View the method Example2 of the gettingstarted.cs file for an example on how to use a DiffGram.

VisitorAdd

• The name and email data is required.

When the username is ommitted or the data is empty Formdesk will use the email address instead.
When the password is ommitted or the data is empty Formdesk will generate a random password of 10 characters.

VisitorUpdate

• Only the id data is required.

When the username is passed but the data is empty Formdesk will use the email address instead.
When the password is passed but the data is empty Formdesk will generate a new random password of 10 characters.

This method also supports the Microsoft .Net Framework DataSet DiffGram format.
For instance you could use the VisitorsGet method, load the results into a DataSet, change some values and pass the resulting DiffGram as input parameter to the VisitorsUpdate method.

View the method Example2 of the gettingstarted.cs file for an example on how to get a DiffGram from the changes.

The result of updating using a DiffGram is just like the normal result.

• A zip file, formdesk-php-soap-example.zip, containing PHP examples
• A PDF document, Formdesk-API-form-import.pdf, containing Form import XML structure