Form Center | Service URLs & Data Exchange Formats

The Service URL property of the External Integration field determines how data is sent between the CivicPlus Form Center Module and an external server.

Previous Step: External Integration Forms

Service URL Configuration

The service URL has the following format:

{Communication Type}{Web Service URL}

The communication type can be XML, JSON, or HTTP; the details of each communication method are described later in this article. The table provides some examples of Service URL values:

XML Documents

The first method to send and receive data is by using an XML document to both send and receive the data. Using this method, the Form Center creates an XML document and sends it to the external server.

Sample XML Request

The following request would be sent out using the above form, filling out the required fields, and sending a POST request using XML to http://externalingtrationservice.azurewebsites.net/api/bill/water:

[email protected] N Main StManhattanKS66502

Your Web Central site will send the request setting the following headers

• Content-Type: application/xml

• Accept: application/xml

Sample XML Response

Sending the previous request would result in a response that looks as follows:

5/12/201684.67

The returned document should have the same format as above, with returned fields that match the names set in the External Integration fields on your form, except for the root element. The Municipal Websites Central solution will skip this element regardless of its value, and will only take its child elements.

Any field included in the received XML document will be used to populate the form fields, even if the form fields already have data in them. For example, if the user types in “[email protected]” for the email address and clicks the external submission button and the received JSON object has “[email protected]” for the EmailAddress node in the XML document, the text in the EmailAddress field will be replaced. Any fields not included in the XML document are not modified.

Checkboxes with Multiple Values Selected

If the form has a checkbox field, all values selected by the user are sent in a comma-separated list, as shown below. This format will also apply to JSON and HTML requests.

101 N. MainRed,Blue,Green

JSON Objects

The second method to send and receive data is by using JSON objects to both send and receive the data. Using this method, the Form Center creates a JSON object and sends it to the external server.

Sample JSON Request

The following request would be sent out using the above form, filling out the required fields, and sending a POST request using JSON to http://externalingtrationservice.azurewebsites.net/api/bill/water:

{"EmailAddress": "[email protected]","Address1": "100 N Main St","Address2": "","City": "Manhattan","State": "KS","Zip": "66502","DueDate": "5/10/2016","Amount": "24.67"}

Your Municipal Websites Central website will send the request setting the following headers

• Content-Type: application/json

• Accept: application/json

Sample JSON Response

Sending the previous request would result in a response that looks as follows:

{"DueDate": "5/2/2016","Amount": "54.15"}

The returned document should have the same format as above, with returned fields that match the names set in the External Integration fields on your form. Any field included in the received JSON object will be used to populate the form fields, even if the form fields already have data in them. For example, if the user types in “[email protected]” for the email address and clicks the external submission button, and the received JSON object has “[email protected]” for the EmailAddress node in the JSON object, the text in the EmailAddress field will be replaced. Any fields not included in the JSON object are not modified.

HTTP / HTML Documents

The final method to send and receive data is by using a standard HTTP POST request. The form data is sent as a standard HTTP post, and the expected result is an HTML document format that contains the result fields placed inside standard HTML input tags.

Sample HTTP / HTML Request

The following request would be sent out using the above form, filling out the required fields, and sending a POST request using HTML to http://externalingtrationservice.azurewebsites.net/api/bill/water:

EmailAddress=demo%40civicplus.com&Address1=100+N+Main+St&Address2=&City=Manhattan&State=KS&Zip=66502&DueDate=&Amount=

Your Web Central site will send the request setting the following header:

• Content-Type: application/x-www-form-urlencoded

Sample HTTP / HTML Response

Sending the previous request would result in a response that looks as follows:

The returned document should have the same format as above, with returned fields that match the names set in the External Integration fields on your form. Any field included in the received HTML document will be used to populate the form fields, even if the form fields already have data in them. For example, if the user types in “[email protected]” for the email address and clicks the external submission button, and the received HTML document has “[email protected]” for the EmailAddress node in the JSON object, the text in the EmailAddress field will be replaced. Any fields not included in the HTML document are not modified.

Next Step: External Integration Web Pages