Form Center


CivicEngage
®

Setup an External Integration Form

Overview

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. Log into your site
  2. Navigate to Modules > Content > Form Center
  3. Click on the Properties tab at the top.
  4. Ensure the External Integration property’s checkbox is checked.
  5. 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.To build other fields for your form, view our Create a Form article.

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.

  1. Create a short answer field for the user’s  address.
  2. Set the External Name. The external name 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.
  3. 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:
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head runat="server">
    <title></title>
    </head>
    <body>
    <input type="text" name="txtTrashCollectionDay" value="Tuesday" />
    </body>
    </html>

    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.

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 article Service URL and Data Exchange Format.

Step 5: Save & 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.

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="TrashCollectionDay.aspx.cs" Inherits="TrashCollectionDay" Debug="true"%>

<!DOCTYPE html>

<script type="text/C#" runat="server">

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);

}

</script>

<html xmlns="http://www.w3.org/1999/xhtml">

<head runat="server">

<title></title>

</head>

<body>

<form id="form1" runat="server">

<div>

<input type="text" name="txtTrashCollectionDay" value="<%=trashCollectionDay%>"

</div>

</form>

</body>

</html>




I'd Like to Request an Enhancement

0 out of 1 found this helpful

Updated:
Follow