CM/Forms

Introduction

CM/Forms is a ConSol CM add-on which enables the creation of web forms. Web forms can be filled out by unregistered users and can be useful in a variety of use cases:

Web forms are managed in the menu item Forms, which is available for users with administrator permissions:

Figure 532: ConSol CM Web Client - Forms

Creating a Web Form

A web form consists of two parts:

Web forms are created in the menu item Forms of the Web Client.

Administrator permissions are required to create a web form.

Open the Forms page and click Create new custom form in the upper right corner to start the creation of the web form. The following page is opened:

Figure 533: ConSol CM Web Client - Forms: Page to create a new form

The Create new custom form page consists of two sections.

The upper section (1) contains the general form configuration with the following options:

The lower section (2) contains the form fields. It uses the form.io library. The available form components are displayed on the left and the form is displayed on the right. The form components are grouped in three categories: Basic Components, Special Components, and Layout Components.

First you have to choose whether you want to create a form consisting of a single page or a wizard consisting of several pages. This is done using the Form type drop-down list in the upper part of the section. Two values are possible:

Now you can drag-and-drop the desired components to the form on the right side. The configuration dialog for the component is opened automatically.

You can find more information in the official documentation of the form.io library (see Form Components and Layout Components).

Data Processing

There are two options for processing the data submitted in the web form:

The following figure illustrates data processing using a webhook (blue data flow) and submission recording (yellow data flow).

Figure 534: Data processing for web forms

It is possible to use both submission recording and the webhook for one web form. The acceptance of the submission depends on the selected option:

If only submission recording is used, the web form is not notified about the result of the processing performed by the task script, i.e., the user who submitted the web form will not know if his request could be processed successfully.

Publishing a Web Form

Depending on the selected publish type and the desired usage of the web form, there are different options for making the web form available.

Common use cases are:

The following figure shows a typical setup for use case 3.

Figure 535: Publishing a web form for external access embedded in a website

Note regarding publish type OWN

A custom-built application is required to serve web forms if the publish type is OWN. This application is not part of the ConSol CM distribution.

Please see section Operating ConSol CM Behind a Proxy (e.g., Apache HTTPD) of the ConSol CM Setup Manual for information about the required proxy settings.

Example: Registration Form

The following example illustrates the creation of a registration form which is published so that customers can register themselves for CM/Track.

For this example, the following configuration is assumed as a prerequisit:

The purpose of the registration form is to create contacts in the customer group DirectCustomers. Therefore, the fields of the web form have to match the customer fields in the customer data model used for this customer group.

All required fields in this customer data model must be required fields in the web form!

The following image shows the used customer data model with the relevant data fields:

Figure 536: ConSol CM Admin Tool - Customers, Data Models: Example data fields

The web form is configured as follows:

Figure 537: ConSol CM Web Client - Example web form: Customer registration

The following integration script is used for processing the data directly with the webhook:

import com.consol.cmas.intg.service.IntgServiceResponse

import groovy.json.JsonSlurper

import groovy.json.JsonOutput

 

def jsonSlurper = new JsonSlurper()

def message = jsonSlurper.parse(payload.getBytes(), "UTF-8")

def response = new IntgServiceResponse();

 

try {

// read data and create customer, the email field is used as CM/Track login and must be unique

def data = message.get('data');

def firstname = data.get('firstname');

def lastname = data.get('lastname');

def email = data.get('email');

def password = data.get('password');

def phone = data.get('phone');

def street = data.get('street');

def zip = data.get('zip');

def town = data.get('town');

def mycustomergroup = customerGroupService.getByName("DirectCustomers")

def mycustomer = new Unit("DirectCustomers",mycustomergroup);

 

mycustomer.set("DirectCustomersData.name",firstname);

mycustomer.set("DirectCustomersData.last_name",lastname);

mycustomer.set("DirectCustomersData.email",email);

mycustomer.set("DirectCustomersData.password",password);

mycustomer.set("DirectCustomersData.phone",phone);

mycustomer.set("DirectCustomersData.street",street);

mycustomer.set("DirectCustomersData.zip",zip);

mycustomer.set("DirectCustomersData.town",town);

unitService.create(mycustomer);

 

response.httpStatusCode = 200

response.body = JsonOutput.toJson(

[message: "<center>Thank you for registring. You can now log in to <a href=\"myurl/track/#/signin\">CM/Track</a>.</center>"]

)

 

} catch (Exception ex) {

response.httpStatusCode = 400

response.body = JsonOutput.toJson(

[message: "Please correct your data."]

)

}

 

return response

Code example 101: Integration script for the customer registration form

Notes

You can configure a data field either directly when creating it, or afterwards by clicking the Edit button:

Figure 538: ConSol CM Web Client - Forms: Editing the settings of a data field

There is a large number of settings you can use for a data field. Usually, you only need a few of the options. For this example, the following settings are needed.

The layout of the web form (headings, columns) is defined using the following components: