Visualizzazione del contenuto dell'aiuto per la versione :
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.
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
Nota:
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:
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.
-
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
Nota:
Ensure that you encrypt sensitive information like passwords before configuring the data source. To encrypt:
- Go to http://[server]:[port]/system/console/crypto.
- 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.
You can configure AEM user profile using User Profile Connector configuration in AEM Web Console. Do the following:
-
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
Nota:
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.
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:
-
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.
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:
-
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.
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:
-
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.
Nota:
You must select OAuth 2.0 authentication type to connect with Microsoft Dynamics services using OData endpoint as the service root.
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.
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.
D. Services
Content area where data model object operations or services added appear.
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.
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:
-
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 displays added data model objects
Nota:
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.
Services tab displays data model services
Nota:
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.
-
Nota:
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.
To read and write data for a data model object, do the following to configure read and write services:
-
Edit properties to configure read and write services for a data model object
Edit Properties dialog
Nota:
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.
-
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.
-
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.
Nota:
You can add, edit, or delete arguments for read and write services only for JDBC data sources.
Binding the id argument to empid attribute of AEM User Profile
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.
Nota:
Predefined associations in a JDBC data source are not retained in the form data model. You must create them manually.
-
Select the check box at the top of a data model object to select it and tap Add Association. The Add Association dialog opens.
Nota:
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.
Add Association dialog
-
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.
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.
Updated argument and binding
Nota:
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.
You can edit properties of data model objects, their properties, and services added in the form data model.
To edit properties:
-
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 dialog for a get service
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.
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:
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.
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:
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.
Nota:
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.
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.
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.
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.
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:
to open the Properties browser for the component.
and navigate to select the binary property you added in the form data model. Configure other properties, as appropriate.
to save the properties. The attachment field is now bound to the binary property of the form data model.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.
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.
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.
Nota:
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).
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.
I post su Twitter™ e Facebook non sono coperti dai termini di Creative Commons.