The content of this page describes how to use the REST service to upload completed forms to the CCA System. The REST examples assumes that the REST client is already authenticated and in possession of a valid session ID.

Please choose your preferred scripting/programming language for this demonstration in the select box below;

Active Forms ID

To get a list of names and identities of all active forms available to the REST client, a request in the format shown in the Form IDs Request code box is sent to the REST service. Observe from the body of the request that the session ID is included. The response to this request should be similar to that shown in the Form IDs Response code box.

Active Forms Definition

To retrieve the form definition of active forms, include in the request, a list of form identities as shown in the Form Defs Request block above. A successful request will return the form definitions of all forms listed in the request. An abridged example of a response to this request is shown in the Form Defs Response code block.

Active Forms Data Schema

In addition to retrieving the form definition, the JSON v4 schema/schemata that describe valid form inputs can be requested. This is done by placing a REST call to the end point shown in the Form Schemas Request code block. As with Form Defs Requests, the identities of the forms in question must be included in the request.

Data Submission Format

Submitted data that do not conform to the schema of a defined form will be rejected by the REST service. To help the developer, ccasystem.io provides a mechanism by which the expected format of form inputs can be simulated. To see this in action, click on the Manage Form -> Instance Code menu item. Select the required form. Fill the form and click the Show Code button to display what a valid submission of the form would look like. See an example in the image below.

Submit Completed Form I (Alphanumeric Form Fields)

To submit a completed form to the REST service, create a JSON object which consists of two properties i.e., sessionID and form. The form property in turn is made up of two JSON strings viz; formID and formInstance as shown in the Submission Request I code block above.

If the service accepts the form submission, then a response similar to that shown in the Submission Response I code block is returned.

Submit Completed Form II (Multimedia Form Fields)

The service allows for the submission of files with multimedia contents. How such a submission is carried out is dependent on the useAttachmentProxy parameter value returned (i.e., true or false) after a successful authentication.

If the parameter, useAttachmentProxy, is set to true, then the form multimedia field must contain the Base-64 string representation of the multimedia file. In the example shown in the Submission Request II code block the ImageField consists of two JSON properties i.e., fileName and fileObject. The fileObject property value must be set to the Base-64 string representation of the multimedia file.

Submit Completed Form III (Multimedia Form Fields)

On the other hand, if the useAttachmentProxy is set to false, then the JSON properties for the ImageField object are fileName and fileContentType. See an example in the Submission Request III code block below. The Base-64 string representation of the file should be stored until a response to this request is returned.

If the request is successful, the REST service will return a list of preassigned URLs for each of the multimedia data submitted as shown in the Submission Response III code block. This list of preassigned URLs are used to upload the files directly from the REST client to the data store as will be demonstrated shortly.

In addition to the URL list, a parameter, urlTTLSec, value is also returned. The value of this parameter indicates for how long, in seconds, for which the list of URL returned are valid for. At the expiration of this time interval, the URLs will no longer be usable.

The preassigned URL values are used to upload the Base-64 string representation of the multimedia files by employing a mechanism similar to the contents of the code block shown above. Note that a PUT method is used to upload the file.

It is important that multimedia files within the same form are given different names. If two or more files have the same name, either file will be overwritten by the most recent one.

Click here for examples on how to use the REST service to query submitted forms.