Populus Forms API Documentation
Date: 31-Jan-2012
The Populus API is designed to allow external programmers to have access to certain functions and areas of the Populus CMS. Currently this only covers a limited area of the forms section. This document aims to explain how to access and use the API. The API is written in ASP.NET 4, using the Windows Communication Framework (WCF). It is accessible through the normal means for a WCF service, though it is expected that most requests will be SOAP based.
To get the metadata, the following URLs formats apply:
- http://<domain>/API/Forms.svc/mex (For .NET applications)
http://<domain>/API/Forms.svc?wdsl (For other applications)
Functions
Overview
- Explanation of Common Features/Parameters
- APIKey
- formCode
- Forms
- StoreSubmission
Detailed Descriptions
Explanation of Common Features/Parameters
Currently there are two common parameters:
APIKey
This is the access key for the AP. It will need to be provided for each function in order to gain access. This will be provided for you.
formCode
This is the code that identifies the form you wish to submit to. It is unique for each form. This will be provided for you. Forms
StoreSubmission
Parameters (Input): APIKey, formCode, formResults Return Value: XML String APIKey and formCode are explained above. The formResult is a XML string of the form results. The expected structure of this is as below, but varies per form depending on the requirements. You should request a list of the questions, question types, answer IDs (and content) and question IDs from the client.You must build a well formed XML string.
Sample XML structure:
<answers>
<answer>
<question id="3">
<value>1</value>
</question>
<question id="4">
<value>1</value>
<value>7</value>
</question>
<question id="2">
<value>2</value>
</question>
<question id="5">
<value>My Answer</value>
<value>For a freeform field</value>
<value>Haikus are easy</value>
<value>But sometimes they don’t make sense</value>
<value>Refrigerator</value>
</question>
<question id="1">
<value desc="title">Mrs</value>
<value desc="firstname">Jane</value>
<value desc="lastname">Blogs</value>
<value desc="organisation">GoCorp</value>
<value desc="email">jane@gocorp.com</value>
<value desc="mobile">0411333565</value>
<value desc="landlineHM">0299423523</value>
<value desc="landlineWK">0299426432</value>
<value desc="membershipNo">123</value>
<value desc="street">123 Smith Street</value>
<value desc="town/suburb">Sydney</value>
<value desc="state">NSW</value>
<value desc="postcode">2000</value>
<value desc="country">Australia</value>
</question>
<question id="6">
<value>30/10/1990</value>
</question>
</answer>
</answers>
</root>
In the example above, the following questions were defined in the form:
- Radio button (ID 3)
- Multi-select (ID 4)
- Dropdown list (ID 2)
- Freeform with 5 requested values (ID 5)
- Contact Detail with all possible fields (ID 1)
- Historic Date field (ID 6)
Notes:
- Multiple <answer></answer> tags can be included within in the <answers></answers>. All must be valid in order for any to save.
- The order of <question></question> tags is not important, neither is the order of <value></value> tags.
- Each <question> must have a valid id, and each <value> must have a valid desc.
- The historic date field must be prior to the current date, and in the format d/mm/yyyy (e.g. 2/1/2000, 22/12/1942, 23/06/1983)
- For question types Radio button, Multi-Select and Dropdown list – the XML output should contain the answer ID of the corresponding question on the populus form rather than the question text.
On response, if all answers have passed validation, the API will return:
<root>
<answers>
<answer answerset="10385" uniquecode="ABC123XY">Form completed.</answer>
</answers>
</root>
Note: The unique code will only be returned if it is enabled as part of the populus form setup.
On an error, the service will return:
<root>
<answers>
<answer>
<error questionid="3">Value is incorrect (5).</error>
<error questionid="1"> incorrect landline (hm) number 211122233.</error>
<error questionid="1"> incorrect landline (wk) number 298765432.</error>
</answer>
</answers>
</root>
If the error is specific to a question, the ID will be returned as an attribute (questionid).
Examples
Examples are available for PHP and ASP.NET below in Related Resources.
Development Guide
Development will vary from language to language. The general steps to use the API should be as follows: - Acquire API URL, API Key, Form Code, and a list of questions with IDs.
- Design form (HTML or otherwise; if developing in PHP5 or ASP.NET, examples are available.)
- On submit, validate the information, then construct the XML structure and submit to the API location with the API Key and Form Code.
- Get the returned result and check for errors, display if any.
- If successfully submitted and required return the unique code to the user.
