Configure data sources

AEM Forms Data Integration lets you configure and connect to disparate data sources. The following types are supported out-of-the-box. However, with little customization, you can integrate other data sources as well.

• Relational databases - MySQL, Microsoft SQL Server, IBM DB2, Oracle RDBMS, postgreSQL, and Sybase
• AEM user profile
• RESTful web services
• SOAP-based web services
• OData services

Data integration supports OAuth2.0(Authorization Code, Client Credentials), Basic Authentication, and API Key authentication types out-of-the-box, and allows implementing custom authentication for accessing web services. While RESTful, SOAP-based, and OData services are configured in AEM Cloud Services, JDBC for relational databases and connector for AEM user profile are configured in AEM web console.

Configure relational database

You can configure relational databases using AEM Web Console Configuration. Do the following:

1. Go to AEM web console at https://server:host/system/console/configMgr.

2. Look for Apache Sling Connection Pooled DataSource configuration. Tap to open the configuration in edit mode.

3. In the configuration dialog, specify the details for the database you want to configure, such as:

   • Name of the data source
   • Data source service property that stores the data source name
   • Java class name for the JDBC driver
   • JDBC connection URI
   • Username and password to establish connection with the JDBC driver
   NOTE

   Ensure that you encrypt sensitive information like passwords before configuring the data source. To encrypt:

   1. Go to https://‘[server]:[port]’/system/console/crypto.
   2. In the Plain Text field, specify the password or any string to encrypt and tap Protect.

   The encrypted text appears in the Protected Text field that you can specify in the configuration.

4. Enable Test on Borrow or Test on Return to specify that the objects are validated before being borrowed or returned from and to the pool, respectively.

5. Specify a SQL SELECT query in the Validation Query field to validate connections from the pool. The query must return at least one row. Based on your database, specify one of the following:

   • SELECT 1 (MySQL and MS SQL)
   • SELECT 1 from dual (Oracle)

6. Tap Save to save the configuration.

   NOTE

   If your Forms Data Model contains an object that is a reserved keyword for your relational database, it can lead to data addition, updation, or retrieval issues. So, avoid using such objects in your Form Data Model.

Configure AEM user profile

You can configure AEM user profile using User Profile Connector configuration in AEM Web Console. Do the following:

1. Go to AEM web console at https://'[server]:[port]'system/console/configMgr.

2. Look for AEM Forms Data Integrations - User Profile Connector Configuration and tap to open the configuration in edit mode.

3. In the User Profile Connector Configuration dialog, you can add, remove, or update user profile properties. The specified properties are available for use in form data model. Use the following format to specify user profile properties:

   name=[property_name_with_location_in_user_profile],type=[property_type]

   Examples:

   • name=profile/phoneNumber,type=string
   • name=profile/empLocation/*/city,type=string
   NOTE

   The * in the above example denotes all nodes under the profile/empLocation/ node in AEM user profile in CRXDE structure. It means that the form data model can access the city property of type string present in any node under the profile/empLocation/ node. However, the nodes that contain the specified property must follow a consistent structure.

4. Tap Save to save the configuration.

Configure folder for cloud service configurations

All cloud service configurations in AEM are consolidated in the /conf folder in AEM repository. By default, the conf folder contains the global folder where you can create cloud service configurations. However, you need to manually enable it for cloud configurations. You can also create additional folders in conf to create and organize cloud service configurations.

To configure the folder for cloud service configurations:

1. Go to Tools > General > Configuration Browser.

   • See the Configuration Browser documentation for more information.

2. Do the following to enable the global folder for cloud configurations or skip this step to create and configure another folder for cloud service configurations.

   1. In the Configuration Browser, select the global folder and tap Properties.

   2. In the Configuration Properties dialog, enable Cloud Configurations.

   3. Tap Save & Close to save the configuration and exit the dialog.

3. In the Configuration Browser, tap Create.

4. In the Create Configuration dialog, specify a title for the folder and enable Cloud Configurations.

5. Tap Create to create the folder enabled for cloud service configurations.

Configure RESTful web services

RESTful web service can be described using Swagger specifications in JSON or YAML format in a Swagger definition file. To configure RESTful web service in AEM cloud services, ensure that you have either the Swagger file on your file system or the URL where the file is hosted.

Do the following to configure RESTful services:

1. Go to Tools > Cloud Services > Data Sources. Tap to select the folder where you want to create a cloud configuration.

   See Configure folder for cloud service configurations for information about creating and configuring a folder for cloud service configurations.

2. Tap Create to open the Create Data Source Configuration wizard. Specify a name and optionally a title for the configuration, select RESTful Service from the Service Type drop-down, optionally browse and select a thumbnail image for the configuration, and tap Next.

3. Specify the following details for the RESTful service:

   • Select URL or File from the Swagger Source drop-down, and accordingly specify the Swagger URL to the Swagger definition file or upload the Swagger file from your local file system.

   • Based on the Swagger Source input, the following fields are pre-populated with values:

     • Scheme: The transfer protocols used by the REST API. The number of scheme types that display in the drop-down list depend on the schemes defined in the Swagger source.
     • Host: The domain name or IP address of the host that serves the REST API. It is a mandatory field.
     • Base Path: The URL prefix for all API paths. It is an optional field.
       If necessary, edit the pre-populated values for these fields.

   • Select the authentication type — None, OAuth2.0(Authorization Code, Client Credentials), Basic Authentication, API Key, Custom Authentication, or Mutual Authentication — to access the RESTful service, and accordingly provide details for authentication.

   If you select API Key as the authentication type, specify the value for the API key. The API key can be sent as a request header or as a query parameter. Select one of these options from the Location drop-down list and specify the name of the header or the query parameter in the Parameter Name field accordingly.

   If you select Mutual Authentication as the authentication type, see Certificate-based mutual authentication for RESTful and SOAP web services.

4. Tap Create to create the cloud configuration for the RESTful service.

Form data model HTTP client configuration to optimize performance

Experience Manager Forms form data model when integrating with RESTful web services as the data source includes HTTP client configurations for performance optimization.
Perform the following steps to configure the form data model HTTP client:

1. Log in to Experience Manager Forms Author Instance as an administrator and go to Experience Manager web console bundles. The default URL is https://localhost:4502/system/console/configMgr.

2. Tap Form Data Model Http Client Configuration for REST data source.

3. In the Form Data Model Http Client Configuration for REST data source dialog:

   • Specify the maximum number of permitted connections between form data model and RESTful web services in the Connection limit in total field. The default value is 20 connections.

   • Specify the maximum number of permitted connections for each route in the Connection limit on per route basis field. The default value is 2 connections.

   • Specify the duration, for which a persistent HTTP connection is kept alive, in the Keep alive field. The default value is 15 seconds.

   • Specify the duration, for which the Experience Manager Forms server waits for a connection to establish, in the Connection timeout field. The default value is 10 seconds.

   • Specify the maximum time period for inactivity between two data packets in the Socket timeout field. The default value is 30 seconds.

Configure SOAP web services

SOAP-based web services are described using Web Services Description Language (WSDL) specifications. To configure SOAP-based web service in AEM cloud services, ensure that you have the WSDL URL for the web service, and do the following:

1. Go to Tools > Cloud Services > Data Sources. Tap to select the folder where you want to create a cloud configuration.

   See Configure folder for cloud service configurations for information about creating and configuring a folder for cloud service configurations.

2. Tap Create to open the Create Data Source Configuration wizard. Specify a name and optionally a title for the configuration, select SOAP Web Service from the Service Type drop-down, optionally browse and select a thumbnail image for the configuration, and tap Next.

3. Specify the following for the SOAP web service:

   • WSDL URL for the web service.

   • Service Endpoint. Specify a value in this field to override the service endpoint mentioned in WSDL.

   • Select the authentication type — None, OAuth2.0(Authorization Code, Client Credentials), Basic Authentication, Custom Authentication, X509 Token, or Mutual Authentication — to access the SOAP service, and accordingly provide the details for authentication.

     If you select X509 Token as the Authentication type, configure the X509 certificate. For more information, see Set up certificates.
     Specify the KeyStore alias for the X509 certificate in the Key Alias field. Specify the time, in seconds, until the authentication request remains valid, in the Time To Live field. Optionally, select to sign the message body or timestamp header or both.

     If you select Mutual Authentication as the authentication type, see Certificate-based mutual authentication for RESTful and SOAP web services.

4. Tap Create to create the cloud configuration for the SOAP web service.

Configure OData services

An OData service is identified by its service root URL. To configure an OData service in AEM cloud services, ensure that you have service root URL for the service, and do the following:

1. Go to Tools > Cloud Services > Data Sources. Tap to select the folder where you want to create a cloud configuration.

   See Configure folder for cloud service configurations for information about creating and configuring a folder for cloud service configurations.

2. Tap Create to open the Create Data Source Configuration wizard. Specify a name and optionally a title for the configuration, select OData Service from the Service Type drop-down, optionally browse and select a thumbnail image for the configuration, and tap Next.

3. Specify the following details for the OData service:

   • Service Root URL for the OData service to be configured.
   • Select the authentication type — None, OAuth2.0(Authorization Code, Client Credentials), Basic Authentication, or Custom Authentication — to access the OData service, and accordingly provide the details for authentication.
   NOTE

   You must select OAuth 2.0 authentication type to connect with Microsoft Dynamics services using OData endpoint as the service root.

4. Tap Create to create the cloud configuration for the OData service.

Certificate-based mutual authentication for RESTful and SOAP web services

When you enable mutual authentication for form data model, both the data source and AEM Server running form data model authenticate each other’s identity before sharing any data. You can use mutual authentication for REST and SOAP based connections (data sources). To configure mutual authentication for a form data model on your AEM Forms environment:

1. Upload the private key (certificate) to AEM Forms server. To upload the private key:
   1. Login to your AEM Forms server as an administrator.
   2. Navigate to Tools > Security > Users. Select the fd-cloudservice user and tap Properties.
   3. Open the Keystore tab, expand the Add Private Key from KeyStore file option, upload the KeyStore File, specify the aliases, passwords, and tap Submit. The Certificate is uploaded. The private key alias is mentioned in the certificate and set while creating the certificate.
2. Upload trust certificate to Global Trust Store. To upload the certificate:
   1. Navigate to Tools > Security > Trust Store.
   2. Expand the Add Certificate from CER file option, tap Select Certificate File, upload the certificate, and tap Submit.
3. Configure SOAP or RESTful web services as the data source and select Mutual authentication as the authentication type. If you configure multiple self-signed certificates for fd-cloudservice user, specify the Key Alias name for the certificate.

Next steps

You have configured the data sources. Next you can create a form data model or if you have already created a form data model without a data source, you can associate it with the data sources you configured. See Create form data model for details.