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.

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:

Go to Article Navigation

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:

<Root>
<EmailAddress>demo@civicplus.com</EmailAddress>
<Address1>100 N Main St</Address1>
<Address2></Address2>
<City>Manhattan</City>
<State>KS</State>
<Zip>66502</Zip>
<DueDate></DueDate>
<Amount></Amount>
</Root>

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:

<BillResponse>
<DueDate>5/12/2016</DueDate>
<Amount>84.67</Amount>
</BillResponse>

The returned document should have the same format as above, with returned fields that match the names set in the ExternalIntegration 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 “test@test.com” for the email address and clicks the external submission button and the received JSON object has “demo@civicplus.com” 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.

<Root>
<Address>101 N. Main</Address>
<FavoriteColors>Red,Blue,Green</FavoriteColors>
</Root>

Go to Article Navigation

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": "demo@civicplus.com",
"Address1": "100 N Main St",
"Address2": "",
"City": "Manhattan",
"State": "KS",
"Zip": "66502",
"DueDate": "5/10/2016",
"Amount": "24.67"
}

Your Web 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 “test@test.com” for the email address and clicks the external submission button, and the received JSON object has “demo@civicplus.com” 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.

Go to Article Navigation

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:

<html>
<body>
<input type=”text” name=”Amount” value=”24.67”/>
<input type=”text” name=”DueDate” value=”5/10/2016”/>
</body>
</html>

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 “test@test.com” for the email address and clicks the external submission button, and the received HTML document has “demo@civicplus.com” 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.

Go to Article Navigation

In-Article Glossary

Review the Municipal Websites Central's Glossary of Terms for a comprehensive explanation of the acronyms, abbreviations, and company-specific terminology. The terms located in this section are listed alphabetically:

• HTML: Hypertext Markup Language
• HTTP: Hypertext Transfer Protocol
• JSON: JavaScript Object Notation
• URL: Uniform Resource Locator
• XML: Extensible Markup Language

Go to Article Navigation