您查看的帮助内容对应的版本是:

Data Integration lets you connect disparate data sources and create form data model.
data-integeration

Enterprise infrastructures include disparate back-end systems or data sources like databases, web services, REST services, OData services, and CRM solutions. Put together, they make an information system that serves data to enterprise applications to perform day-to-day business. On the other hand, applications capture data and send it back to update data sources. 

AEM Forms applications like adaptive forms require integration with data sources to fetch data while rendering forms and documents. There are use cases when this data is fetched from disparate data sources based on user interactions with a form. On form submission, the captured data is written back to the respective data sources.

While a distributed, modular system has its own benefits, the challenge lies in integrating and creating data associations across data sources. Data integration is the key to a functional and efficient enterprise infrastructure with disparate data sources connected to applications for exchange of business data.

Introduction to AEM Forms Data Integration

AEM-forms-Data-Integeration

AEM Forms Data Integration allows you to configure and connect to disparate data sources. The following 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, and Oracle RDBMS
  • AEM user profile
  • RESTful web services
  • SOAP-based web services
  • OData services

注意:

Support for OData services in Data Integration is available with AEM Forms add-on package for AEM 6.3 Cumulative Fix Pack 1 and later versions.

It supports OAuth2.0, Basic Authentication, and API Key authentication types out-of-the-box, and allows implementing custom authentication for accessing web services.

It provides an intuitive user interface to create a unified data representation schema of business entities and services across connected data sources. The unified representation is known as a form data model, which is an extension of JSON schema. The entities in a form data model are referred to as data model objects. A form data model allows you to:

  • Access data model objects, metadata, and services from connected data sources.
  • Build associations between data model objects within and across data sources.
  • Invoke data model object services to query or write data to and from data sources.

Once you have created a form data model, you can use it in various adaptive form workflows, such as:

  • Create an adaptive form based on a form data model.
  • Prefill an adaptive form.
  • Invoke services defined in a form data model using adaptive form rules.
  • Write submitted form data to the underlying data sources.

To summarize, working with Data Integration involves:

  1. Configuring data sources
  2. Creating form data model
  3. Testing data model objects and services in form data model
  4. Using form data model in adaptive form workflows

Configure data sources

Forms Data Integration supports configuring the following data sources:

  • Relational databases - MySQL, Microsoft SQL Server, IBM DB2, and Oracle RDBMS
  • AEM user profile
  • RESTful web services
  • SOAP-based web services
  • OData 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.

See subsequent sections for details to configure these data sources.

Configure relational database

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

  1. Go to AEM web console at http://[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

    注意:

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

    1. Go to http://[server]:[port]/system/console/crypto.
    2. In the Plain Text field, specify the password or any string to encrypt and click 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.

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 http://[server]:[host]/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 will be 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

    注意:

    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 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 files ystem or the URL where the file is hosted.

Do the following to configure RESTful services:

  1. Go to Cloud Services configurations at http://[server]:[host]/libs/cq/core/content/tools/cloudservices.html and log in with administrator credentials.

  2. Look for Form Data Model under Third Party Services. If this is your first Form Data Model configuration, tap Configure Now. Otherwise, tap Show Configurations and then + icon next to Available Configurations to add another configuration.

  3. Select REST Service, specify a title for the configuration, and tap Create. The REST Service dialog opens.

  4. In the REST Service dialog, do the following:

    • (Optional) Specify the path to the thumbnail image to appear on your RESTful service configuration page.
    • Select the Swagger source, URL or File, and accordingly specify the URL to the Swagger definition file or upload the Swagger file from your local filesystem.
    • Select the authentication type — None, OAuth2.0, Basic Authentication, API Key, or Custom Authentication — to access the RESTful service, and accordingly provide the details for authentication.
  5. Tap OK to save the configuration.

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 Cloud Services configurations at http://[server]:[host]/libs/cq/core/content/tools/cloudservices.html and log in with administrator credentials.

  2. Look for Form Data Model under Third Party Services. If this is your first Form Data Model configuration, tap Configure Now. Otherwise, tap Show Configurations and then + icon next to Available Configurations to add another configuration.

  3. Select SOAP Web Services Configuration, specify a title for the configuration, and tap Create. The SOAP based Web Service dialog opens.

  4. In the SOAP based Web Service dialog, do the following:

    • (Optional) Specify the path to the thumbnail image to appear on your service configuration page.
    • Specify the WSDL URL for the web service.
    • Select the authentication type — None, OAuth2.0, Basic Authentication, or Custom Authentication — to access the SOAP service, and accordingly provide the details for authentication.
  5. Tap OK to save the configuration.

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 Cloud Services configurations at http://[server]:[host]/libs/cq/core/content/tools/cloudservices.html and log in with administrator credentials.

  2. Look for Form Data Model under Third Party Services. If this is your first Form Data Model configuration, tap Configure Now. Otherwise, tap Show Configurations and then + icon next to Available Configurations to add another configuration.

  3. Select OData Service, specify a title for the configuration, and tap Create. The OData Service dialog opens.

  4. In the OData Service dialog, do the following:

    • Specify the Service Root URL for the OData service to be configured.
    • Select the authentication type — None, OAuth2.0, Basic Authentication, or Custom Authentication — to access the OData service, and accordingly provide the details for authentication.
    • (Optional) Specify the path to the thumbnail image to appear on your OData service configuration page.

    注意:

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

  5. Tap OK to save the configuration.

Create form data model

AEM Forms provides an intuitive user interface to create a form data model from configured data sources. Do the following to create a form data model and launch the form data model editor.

  1. In AEM author instance, navigate to Forms > Data Integrations.

  2. Tap Create > Form Data Model.

  3. In the Create Form Data Model dialog, specify a name for the form data model and tap Next.

  4. The Select Datasource screen lists all configured data sources. Select the ones you want to use in the form data model and tap Create.

    On the confirmation dialog, tap Open to launch the form data model editor.

Let us review the different components of the form data model editor UI.

Form Data Model Editor
A form data model with three data sources - a RESTful service, AEM user profile, and an RDBMS

A. Data Sources

Lists all data sources that you selected while creating the form data model. You can expand each data source to view all data model objects and services in a data source.

B. Add Selected

Adds selected data model objects and services to the form data model.

C. Model

Content area where added data model objects appear.

D. Services

Content area where data model object operations or services added appear.

Area where objects and entities are added to create a model.
Area where objects and entities are added to create a model.

Working with form data model

Once you have created a form data model and added data sources, you can use the form data model editor to add data model objects and services, configure their properties, build associations between data model objects, and test the form data model and services.

Add data model objects and services

You can add data model objects and services from available data sources in the form data model. While added data model objects appear in the Model tab, added services appear in the Services tab.

To add data model objects and services:

  1. In the Data Sources pane, expand data sources to view available data model objects and services.

  2. Select data model objects and services you want to add to the form data model and tap Add Selected.

    selected-objects
    Selected data model objects and services

    The Model tab displays a graphical representation of all data model objects and their properties added to the form data model. Each data model object is represented by a box in the form data model.

    model-tab
    Model tab displays added data model objects

    注意:

    You can hold and drag data model object boxes around to organize them in the content area. All data model objects added in the form data model are grayed out in the Data Sources pane.

    The Services tab lists added services.

    services-tab
    Services tab displays data model services

    注意:

    In addition to data model objects and services, OData service metadata document includes navigation properties that define association between two data model objects. When you add an OData service datasource to a Form Data Model, there is a service available in Form Data Model for all navigation properties in a data model object. You can use this service to read the navigation properties of the corresponding data model object.

    For more information, see Working with navigation properties of OData services.

  3. Tap Save to save the form model object.

    注意:

    You can invoke the services that you configure in the Services tab of a form data model using the adaptive form rules. The configured services are available in the Invoke services action of the rule editor For more information about using these services in adaptive form rules, see Invoke Services and Set Value Of rules in rule editor.

Configure read and write services for data model objects

To read and write data for a data model object, do the following to configure read and write services:

  1. Select the check box at the top of a data model object to select it and tap Edit Properties.

    edit-properties
    Edit properties to configure read and write services for a data model object

    The Edit Properties dialog opens.

    edit-properties-2
    Edit Properties dialog

    注意:

    In addition to data model objects and services, OData service metadata document includes navigation properties that define association between two data model objects. When you add an OData service datasource to a Form Data Model, there is a service available in Form Data Model for all navigation properties in a data model object. You can use this service to read the navigation properties of the corresponding data model object. 

    For more information using the service, see Working with navigation properties of OData services.

  2. Toggle Top Level Object to specify if the data model object is a top level model object.

    Data model objects configured in a form data model are available for use in the Data Model Objects tab in the Content browser of an adaptive form based on the form data model. When you add association between two data model objects, the data model object you are associating with is nested under the data model object you are associating from in the Data Model Objects tab. If the nested data model is a top level object, it will also appear separately in the Data Model Objects tab. Therefore, you will see two entries of it, one inside and another outside the nested hierarchy, which might confuse form authors. To make the associated data model object appear only in the nested hierarchy, disable its Top Level Object property.     

  3. Select Read and Write services for the selected data model objects. The arguments for the services appear.

    read-write-services
    Read and write services configured for employee data source

  4. Tap  for the read service argument to bind the argument to a User Profile Attribute, Request Attribute, or Literal value and specify the binding value. It binds the service argument to the specified binding attribute or literal value, which is passed to the service as an argument to fetch details associated with the specified value from the data source.

    In this example, the id argument will take the value of the empid attribute of the user profile and pass it as an argument to the read service. It will read and return values of associated properties from the employee data model object for the specified empid. So, if you specify 00250 in the empid field in the form, the read service will read details of the employee with 00250 employee id. 

    In addition, you can make an argument mandatory or optional.

    注意:

    You can add, edit, or delete arguments for read and write services only for JDBC data sources.

    edit-argument
    Binding the id argument to empid attribute of AEM User Profile

  5. Tap Done to save the argument, Done to save the properties, and then Save to save the form data model.

Add associations

Typically, there are associations built between data model objects in a data source. The association can be one-to-one or one-to-many. For example, there can be multiple dependents associated with an employee. It is referred to as one-to-many association and depicted by 1:n on the line connecting associated data model objects. However, if an association returns a unique employee name for a given employee ID, it is referred to as one-to-one association.

When you add associated data model objects in a data source to a form data model, their associations are retained and displayed as connected by arrow lines. You can add associations between data model objects across disparate data sources in a form data model.

注意:

Predefined associations in a JDBC data source are not retained in the form data model. You must create them manually.

To add an association:

  1. Select the check box at the top of a data model object to select it and tap Add Association. The Add Association dialog opens.

    add-association

    注意:

    In addition to data model objects and services, OData service metadata document includes navigation properties that define association between two data model objects. You can use these navigation properties when adding associations in Form Data Model. For more information, see Working with navigation properties of OData services.

    The Add Association dialog opens.

    add-association-2
    Add Association dialog

  2. In the Add Association pane:

    • Specify a title for the association.
    • Select the association type — One to One or One to Many.
    • Select the data model object to associate with.
    • Select the read service to read data from the selected model object. The read service argument appears. Edit to change the argument, if necessary, and bind it to the property of the data model object to associate.

    In the following example, the default argument for the read service of the Dependents data model object is dependentid.

    add-association-example
    Default argument for Dependents read service is dependentid

    However, the argument must be a common property between the associating data model object, which in this example is Employeeid. Therefore, the Employeeid argument must be bound to the id property of the Employee data model object to fetch the associated dependents details from the Dependents data model object.

    add-association-example-2
    Updated argument and binding

    Tap Done to save the argument.

  3. Tap Done to save the association and then Save to save the form data model.

  4. Repeat the steps to create more associations as required.

注意:

The added association appears in the data model object box with the specified title and a line connecting the associated data model objects.

You can edit an association by selecting the checkbox against it and tap Edit Association.

Edit data model objects association

Edit properties

You can edit properties of data model objects, their properties, and services added in the form data model.

To edit properties:

  1. Select the check box next to a data model object, a property, or a service in the form data model.

  2. Tap Edit Properties. The Edit Properties pane for the selected model object, property, or service opens.

    • Data model object: Specify the read and write services and edit arguments.
    • Property: Specify the type, sub-type, and format for the property. You can also specify if the selected property is the primary key for the data model object.
    • Service: Specify the input model object, output type, and arguments for the service. For a Get service, you can specify if it is expected to return an array.

     

    edit-properties-service
    Edit Properties dialog for a get service

  3. Tap Done to save properties and then Save to save the form data model.

Update form data model with changes in data source

When you modify or update data model objects or services in a data source, the updates do not automatically reflect in the associated form data model.

You need to invalidate the cache to reflect the updates in the form data model.

JDBC data source

  1. On AEM author instance, go to http://[server]:[port]/system/console/bundles.

  2. Find and click AEM Forms Dermis Core (aem-dermis-core) bundle to open it.

  3. Stop and start the bundle to invalidate the cache.

RESTful, SOAP-based, and OData services

  1. On AEM author instance, go to Tools > Deployment > Cloud services.

  2. Click Show configurations under Form Data Model. All configured cloud services are listed.

  3. Click to open the cloud service for the updated data source.

  4. Save the cloud service configuration.

Test data model objects and services

Your form data model is configured but before putting it in use, you may want to test if the configured data model objects and services are working as expected. To test data model objects and services:

  1. Select a data model object or a service in the form data model and tap Test Model Object or Test Service, respectively.

    The Test Form Data Model window opens.

    test-data-model
  2. In the Test Form Data Model window, select the data model object or service to test from the Input pane.

  3. Specify an argument value in the test code and tap Test. A successful test returns the output in the Output pane.

    test-data-model-2

Similarly, you can test other data model objects and services in the form data model.

Use form data model in adaptive forms use cases

A form data model is an extension of JSON schema that you can use to:

  • Create adaptive forms and fragments.
  • Prefill adaptive forms.
  • Write form data back to data sources on form submission.
  • Invoke services using adaptive form rules.

Create adaptive forms and fragments

You can create adaptive forms and adaptive form fragments based on form data model. Do the following to use a form data model when creating an adaptive form or adaptive form fragment:

  1. In Form Model tab on Add Properties screen, select Form Data Model in the Select From drop-down list.

    create-af-1
  2. Tap to expand Select Form Data Model. All available form data models are listed.

    Select a from data model.

    create-af-2
  3. (Adaptive form fragments only) You can create an adaptive form fragment based on only one data model object in a form data model. Expand Form Data Model Definitions drop-down. It lists all data model objects in the specified form data model. Select a data model object from the list.

    create-af-3

Once the adaptive form or adaptive form fragment based on a form data model is created, form data model objects appear in the Data Model Objects tab of the Content browser in adaptive form editor.

注意:

For an adaptive form fragment, only the data model object selected at the time of authoring and its associated data model objects appear in the Data Model Objects tab.

data-model-objects-tab

You can drag-drop data model objects onto the adaptive form or fragment to add form fields. The added form fields retain the metadata properties and binding for data model objects. The binding ensures that the field values are updated in the corresponding data sources on form submission and prefilled when the form is rendered.

Prefill adaptive form

AEM Forms provides out-of-the-box Form Data Model Prefill Service that you can enable for adaptive forms based on a form data model. The prefill service queries data sources for data model objects in the adaptive form and prefills field values when rendering the form.

To enable the Form Data Model Prefill Service for an adaptive form, open the Adaptive Form Container properties and select Form Data Model Prefill service from the Prefill Service drop-down in the Basic accordion. Then, save the properties.

prefill-service

Write submitted form data to data sources

When a user submits a form based on a form data model, you can configure the form to write submitted data for a data model object to its data sources. To achieve this use case, AEM Forms provide Form Data Model submit action, available out-of-the-box only for adaptive forms based on a form data model. It writes submitted data for a data model object in its data source.

To configure the Form Data Model  submit action, open Adaptive Form Container properties and select Submit using Form Data Model from the Submit Action drop-down under the Submission accordion. Then, browse and select a data model object from the Name of the data model object to submit drop down. Save the properties.

On form submission, data for the configured data model object is written to the respective data source. 

data-submission

You can also submit form attachments to a data source using binary data model object property. Do the following to submit attachments to a JDBC data source:

  1. Add a data model object that includes a binary property to the form data model.

  2. In the adaptive form, drag-drop the File Attachment component from the Components browser onto the adaptive form.

  3. Tap to select the added component and tap  to open the  Properties browser for the component.

  4. In the Bind Reference field, tap  and navigate to select the binary property you added in the form data model. Configure other properties, as appropriate.

    Tap  to save the properties. The attachment field is now bound to the binary property of the form data model.

  5. In the Submission section of the Adaptive Form Container properties, enable Submit Form Attachments. It will submit the attachment in the binary property field to the data source on form submission.

Invoke data model services using rules

In an adaptive form based on a form data model, you can create rules to invoke services configured in the form data model. The Invoke Services operation in a rule lists all available services in the form data model and allows you to select input and output fields for the service. You can also use the Set Value rule type to invoke a form data model service and set the value of a field to the output returned by the service.

For example, the following rule invokes a get service that takes Employee Id as input and the values returned are populated in the corresponding Dependent Id, Last Name, First Name, and Gender fields in the form.

invoke-service

In addition, you can use the guidelib.dataIntegrationUtils.executeOperation API to write a JavaScript in the code editor for the rule editor. For API details, see API to invoke form data model service.

In OData services, navigation properties are used to define associations between two data model objects. These properties are defined on an entity type or a complex type. For example, in the following extract from the metadata file of the sample TripPin OData sample services, the person entity contains three navigation properties - Friends, BestFriend, and Trips.

For more information about navigation properties, see OData documentation.

<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<script/>
<edmx:DataServices>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.OData.Service.Sample.TrippinInMemory.Models">
<EntityType Name="Person">
<Key>
<PropertyRef Name="UserName"/>
</Key>
<Property Name="UserName" Type="Edm.String" Nullable="false"/>
<Property Name="FirstName" Type="Edm.String" Nullable="false"/>
<Property Name="LastName" Type="Edm.String"/>
<Property Name="MiddleName" Type="Edm.String"/>
<Property Name="Gender" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.PersonGender" Nullable="false"/>
<Property Name="Age" Type="Edm.Int64"/>
<Property Name="Emails" Type="Collection(Edm.String)"/>
<Property Name="AddressInfo" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location)"/>
<Property Name="HomeAddress" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Location"/>
<Property Name="FavoriteFeature" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature" Nullable="false"/>
<Property Name="Features" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Feature)" Nullable="false"/>
<NavigationProperty Name="Friends" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person)"/>
<NavigationProperty Name="BestFriend" Type="Microsoft.OData.Service.Sample.TrippinInMemory.Models.Person"/>
<NavigationProperty Name="Trips" Type="Collection(Microsoft.OData.Service.Sample.TrippinInMemory.Models.Trip)"/>
</EntityType>

When you configure an OData service in a Form Data Model, all navigation properties in an entity container are made available through a service in the Form Data Model. In this example of TripPin OData service, the three navigation properties in the Person entity container can be read using one GET LINK service in the Form Data Model. 

The following highlights the GET LINK of Person /People service in the Form Data Model, which is a combined service for the three navigation properties in the Person entity of the TripPin OData service. 

nav-prop-service

Once you add the GET LINK service to the Services tab in the Form Data Model, you can edit the properties to choose the output model object and the navigation property to use in the service. For example, the following GET LINK of Person /People service in the following example uses Trip as the output model object and the navigation property as Trips.

edit-prop-nav-prop

注意:

The values available in the Default Value field of the NavigationPropertyName argument depend on the state of the Return array? toggle button. When it is enabled, it shows navigation properties of Collection type.

In this example, you can also choose the output model object as Person and navigation property argument as Friends or BestFriend (depending on whether Return array? is enabled or disabled).

edit-prop-nav-prop2

Similarly, you can choose a GET LINK service and configure its navigation properties when adding associations in the Form Data Model. However, to be able to select a navigation property, ensure that the Binding To field is set to Literal.

add-association-nav-prop

本产品经 Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License 许可  Twitter™ 与 Facebook 中的内容不在 Creative Commons 的条款约束之下。

法律声明   |   在线隐私策略