Form Center External Integration

Form Center External Integration Introduction The CivicPlus Form Center module can integrate with external systems using web requests to send and rece...
Author: Louise Greer
2 downloads 2 Views 687KB Size
Form Center External Integration Introduction The CivicPlus Form Center module can integrate with external systems using web requests to send and receive information to and from an external server. This functionality is useful if you would like to use Form Center to capture user input, and send that information to an external database. This functionality can also be used to retrieve additional information from an external source, and display that information on the form while the user is filling it out. There are two methods for interacting with an external system through Form Center: 



External Integration: The External Integration command is a two-way communication protocol, which requires that the user filling out the form to click an additional button on the form. When the user clicks this button, Form Center will send all fields he or she has filled out to a remote server, and use the information received from the external server to populate other fields on the user’s form. This is done without a page refresh. An example application of the external integration command is to retrieve water billing information based on a custom ID the user enters into the form. External Submission: This is a one-way communication protocol (Form Center will send information only), whereby the user submits the form as normal, and Form Center sends the fields he or she filled out to the external web service. When the user submits the form, he or she sees the standard form center confirmation page. An example application of the external submission command would be sending the information used for a licensing application to an internal or third party system.

Setting up an External Integration Form This section describes how to set up a simple external integration form, which will ask the user for their address, and return their trash collection day. First, we will ensure that the external integration features are enabled. Next we will create a simple form to collect the user’s address, and send this information to an external web service.

Step 1:

Ensure the External Integration features are enabled in Form Center

To enable the external integration options in Form Center, perform the following: 1. Go to www.yourwebsite.com/Admin/FormCenter and click on the Properties tab. 2. Ensure the External Integration property’s checkbox is checked. 3. Click the Save Changes button.

Step 2:

Create a new form in Form Center

No special steps are needed to create a form that uses the External Integration field. Simply browse to the desired category and click the New Form button.

Step 3:

Add input fields to the form

For this example we will add a short answer field where the user can input their address, and another short answer field that will display the trash collection day and time. Create a short answer field for the user ’s address

External Name The external name (highlighted in above figure) is the identifier for the field that Form Center will send to the external server. A field’s external name must match whatever name external web service is expecting. For this example, we assume that the external service will use the following code to retrieve the address the user entered: string address = Request.Form[“txtAddress”];

Because the external server expects the field name to be txtAddress, we enter this value in the External Name field for the address short answer. There is no hard requirement that you change this value, Form Center will auto-generate an external name for each field. The auto-generated external names will be e_1, e_2, e_3… As long as the external server or web page is programmed to expect these field names, the external integration command will work. However, we recommend that you put a meaningful value into the external name field, such as txtAddress, txtFirstName, txtLastName, etc. Create a short answer field to display the user ’s trash collection day We will create another short answer field that will display the user’s trash collection day when he or she clicks the external integration button (which we will add to the form later).

Again, we have created another short answer field and entered txtTrashCollectionDay into the external name property. Whatever value the server sends back for txtTrashCollectionDay will be placed into the field when the user clicks the external integration button. In this case we assume that the external web server will return the following HTML block:

When the form center form receives this HTML block from the external server, it will place the value “Tuesday” into the short answer field named txtTrashCollectionDay.

Step 4:

Add the External Integration Command Button to the form

The external integration command button creates a button on the form, which, when clicked, will send all information the user has filled out on the form to the external server, and populate empty fields with the values received from the external server. To add an external integration command button to the form, drag the “External Integration” from the list of field types onto the form canvas as shown:

After dragging the external integration item onto the form canvas we will enter the appropriate configuration into the external integration button.

The Service URL property contains the configuration for the external server. The Service URL property contains two parts, each enclosed in braces. The first part contains the protocol to use when communicating with the server. The second contains the web address of the web service or web page to use when connecting to the external service. {http}{www.mysite.com/TrashCollectionDay.aspx}

In the above example, the protocol being used is http, which instructs form center to send the information as a standard HTTP POST request, and expect an HTML document in response. A full description of the Service URL configuration can be found in in the section titled Service URL and Data Exchange Format , found at the end of this document.

Step 5:

Save and Publish the Form

Often, for an external integration form, the external integration command button takes place of the typical “Submit” button (although this does not have to be the case). In the case of our sample form, we will hide the standard “Submit” button by changing the form’s submit option from Submit to Print.

After making this change, click the Save and Publish button.

Step 6:

Create the External Integration Web Page

The external integration web page is a custom web page created on your system, which receives requests from an external integration form, and returns either an XML or HTTP response. The external integration web page can be created using any programming language, or hosted on any web server. The only requirement is that it can receive an HTTP POST and return either an XML document or an HTML document. For our example, we will create an external integration web page using a simple ASP.NET Web Forms page. We will call the web page TrashCollectionDay.aspx, and it will contain the following code. public string trashCollectionDay = ""; protected override void OnLoad(EventArgs e) { // Get the address the user entered into the Form Center form (NOTE: // This is passed as a POST parameter, not a querystring parameter. string address = Request.Form["txtAddress"]; if (address == null) address = String.Empty; if (address.Contains("Main St")) { trashCollectionDay = "Monday"; } else if (address.Contains("First St")) { trashCollectionDay = "Tuesday"; } else if (address.Contains("Second St")) {

trashCollectionDay = "Wednesday"; } else { trashCollectionDay = "Unable to find collection day"; } base.OnLoad(e); }

Suggest Documents