Tutorial: Create form data model tutorial-create-form-data-model
This tutorial is a step in the Create Your First Adaptive Form series. Adobe recommends that you follow the series in chronological sequence to understand, perform, and demonstrate the complete tutorial use case.
About the tutorial about-the-tutorial
AEM Forms data integration module lets you create a form data model from disparate backend data sources such as AEM user profile, RESTful web services, SOAP-based web services, OData services, and relational databases. You can configure data model objects and services in a form data model and associate it with an adaptive form. Adaptive form fields are bound to data model object properties. The services enable you to prefill the adaptive form and write submitted form data back to the data model object.
For more information about form data integration and form data model, see AEM Forms Data Integration.
This tutorial walks you through the steps to prepare, create, configure, and associate a form data model with an adaptive form. At the end of this tutorial, you will be able to:
The form data model will look similar to the following:
A. Configured data sources B. Data source schemas C. Available services D. Data model objects E. Configured services
Prerequisites prerequisites
Before you begin, ensure that you have the following:
- MySQL database with sample data as stated in the Prerequisites section of Create your first adaptive form
- OSGi bundle for MySQL JDBC driver as explained in Bundling the JDBC Database Driver
- Adaptive form as explained in the first tutorial Create an adaptive form
Step 1: Configure MySQL database as data source config-database
You can configure different types of data sources to create a form data model. For this tutorial, you configure the MySQL database that you configured and populated with sample data. For information about other supported data sources and how to configure them, see AEM Forms Data Integration.
Do the following to configure your MySQL database:
-
Install JDBC driver for MySQL database as an OSGi bundle:
-
Download MySQL JDBC Driver OSGi Bundle from
http://www.java2s.com/ref/jar/download-orgosgiservicejdbc100jar-file.html. -
Log in to AEM Forms Author Instance as an administrator and go to AEM web console bundles. The default URL is https://localhost:4502/system/console/bundles.
-
Select Install/Update. An Upload / Install Bundles dialog appears.
-
Select Choose File to browse and select the MySQL JDBC driver OSGi bundle. Select Start Bundle and Refresh Packages, and select Install or Update. Ensure that the Oracle Corporation’s JDBC Driver for MySQL is active. The driver is installed.
-
-
Configure MySQL database as a data source:
-
Go to AEM web console at https://localhost:4502/system/console/configMgr.
-
Locate Apache Sling Connection Pooled DataSource configuration. Select to open the configuration in edit mode.
-
In the configuration dialog, specify the following details:
- Datasource name: You can specify any name. For example, specify WeRetailMySQL.
- DataSource service property name: Specify name of the service property containing the DataSource name. It is specified while registering the data source instance as OSGi service. For example, datasource.name.
- JDBC driver class: Specify Java™ class name of the JDBC driver. For MySQL database, specify com.mysql.jdbc.Driver.
- JDBC connection URI: Specify connection URL of the database. For MySQL database running on port 3306 and schema
weretail, the URL is:jdbc:mysql://'server':3306/weretail?autoReconnect=true&useUnicode=true&characterEncoding=utf-8
note note NOTE When the MySQL database is behind a firewall, then database hostname is not a Public DNS. IP address of the database must be added in the /etc/hosts file of the AEM host machine. - Username: Username of the database. It is required to enable JDBC driver to establish a connection with the database.
- Password: Password of the database. It is required to enable JDBC driver to establish a connection with the database.
note note NOTE AEM Forms does not support NT Authentication for MySQL. Go to AEM web console at https://localhost:4502/system/console/configMgr and search “Apache Sling Connection Pooled Datasource”. For “JDBC connection URI” property, set the value of “integratedSecurity” as False and use created username and password for connecting with MySQL database. -
Test on Borrow: Enable the Test on Borrow option.
-
Test on Return: Enable the Test on Return option.
-
Validation Query: Specify a SQL SELECT query to validate connections from the pool. The query must return at least one row. For example, select * from customerdetails.
-
Transaction Isolation: Set the value to READ_COMMITTED.
Leave other properties with default values and select Save.
A configuration similar to the following is created.
-
Step 2: Create form data model create-fdm
AEM Forms provides an intuitive user interface to create a form data model from configured data sources. You can use multiple data sources in a form data model. For this use case, you can use the configured MySQL data source.
Do the following to create form data model:
-
In AEM author instance, navigate to Forms > Data Integrations.
-
Select Create > Form Data Model.
-
In the Create Form Data Model dialog, specify a name for the form data model. For example, customer-shipping-billing-details. Select Next.
-
The select datasource screen lists all configured data sources. Select WeRetailMySQL data source and select Create.
The customer-shipping-billing-details form data model is created.
Step 3: Configure form data model config-fdm
Configuring form data model involves:
- adding data model object and services
- configuring read and write services for data model objects
Do the following to configure the form data model:
-
On AEM author instance, navigate to Forms > Data Integrations. The default URL is https://localhost:4502/aem/forms.html/content/dam/formsanddocuments-fdm.
-
The customer-shipping-billing-details form data model you created earlier is listed here. Open it in edit mode.
The selected data source WeRetailMySQL is configured in the form data model.
-
Expand the WeRailMySQL data source tree. Select the following data model objects and services from weretail > customerdetails schema so you can form data model:
-
Data model objects:
- id
- name
- shippingAddress
- city
- state
- zipcode
-
Services:
- get
- update
Select Add Selected to add selected data model objects and services to the form data model.
note note NOTE The default get, update, and insert services for JDBC datasources are provided out-of-the-box with form data model . -
-
Configure read and write services for the data model object.
-
Select the customerdetails data model object and select Edit Properties.
-
Select get from the Read Service drop-down. The id argument, which is the primary key in the customerdetails data model object is added automatically. Select
-
Similarly, select update as the Write Service. The customerdetails object is added as an argument automatically. The argument is configured as follows.
Add and configure the id argument as follows.
-
Select Done to save the data model object properties. Then, select Save to save the form data model.
The get and update services are added as default services for the data model object.
-
-
Go to the Services tab and configure get and update services.
-
Select the get service and select Edit Properties. The properties dialog opens.
-
Specify the following in the Edit Properties dialog:
-
Title: Specify title of the service. For example: Retrieve Shipping Address.
-
Description: Specify description containing detailed functioning of the service. For example:
This service retrieves the shipping address and other customer details from the MySQL database
-
Output Model Object: Select schema containing customer data. For example:
customerdetail schema
-
Return array: Disable the Return array option.
-
Arguments: Select argument named ID.
Select Done. Service to retrieve customer details from the MySQL database is configured.
-
-
Select the update service and select Edit Properties. The properties dialog opens.
-
Specify the following in the Edit Properties dialog:
-
Title: Specify title of the service. For example, Update Shipping Address.
-
Description: Specify description containing detailed functioning of the service. For example:
This service updates shipping address and related fields in MySQL database
-
Input Model Object: Select schema containing customer data. For example:
customerdetail schema
-
Output type: Select BOOLEAN.
-
Arguments: Select argument name ID and customerdetails.
Select Done. The update service to update customer details in the MySQL database is configured.
-
-
The data model object and services in the form data model are configured. You can now test the form data model.
Step 4: Test form data model test-fdm
You can test the data model object and services to verify that the form data model is configured properly.
Do the following to run the test:
-
Go to the Model tab, select the customerdetails data model object, and select Test Model Object.
-
In the Test Model/Service window, select Read model object from the Select Model/Service drop-down.
-
In the customerdetails section, specify a value for the id argument that exists in the configured MySQL database and select Test.
The customer details associated with the specified id are fetched and displayed in the Output section as shown below.
-
Similarly, you can test the Write model object and services.
In the following example, the update service successfully updates the address details for the id 7102715 in the database.
Now, if you test the read model service again for id 7107215, it fetches and displays the updated customer details as shown below.
