Work with Form Data Model work-with-form-data-model
Form Data Model editor provides an intuitive user interface and tools for editing and configuring a form data model. Using the editor, you can add and configure data model objects, properties, and services from associated data sources in the form data model. In addition, it lets you create data model objects and properties without data sources and bind them with respective data model objects and properties later. You can also generate and edit sample data for data model object properties that you can use to prefill Adaptive Forms while previewing. You can test data model objects and services configured in a Form Data Model to ensure it is properly integrated with data sources.
If you are new to Forms data integration and have not configured a data source or created a form data model, see the following topics:
Read on for details about various tasks and configurations you can perform using the Form Data Model editor.
Add data model objects and services add-data-model-objects-and-services
If you created a Form Data Model with 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:
-
Log into the Experience Manager author instance, navigate to Forms > Data Integrations, and open the Form Data Model in which you want to add data model objects.
-
In the Data Sources pane, expand data sources to view available data model objects and services.
-
Select data model objects and services you want to add to the Form Data Model and select Add Selected.
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
note note NOTE 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 displays data model services
note note NOTE In addition to data model objects and services, OData service metadata document includes navigation properties that define association between two data model objects. For more information, see Working with navigation properties of OData services. -
Select Save to save the form model object.
note note NOTE You can invoke services that you configured 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.
Create data model objects and child properties create-data-model-objects-and-child-properties
Create data model objects create-data-model-objects
While you can add data model objects from configured data sources, you can also create data model objects or entities without data sources. It is helpful especially if you have not configured data sources in the form data model.
To create a data model object without data sources:
-
Log into the Experience Manager author instance, navigate to Forms > Data Integrations, and open the Form Data Model in which you want to create a data model object or entity.
-
Select Create Entity.
-
In the Create data Model dialog, specify a name for the data model object and select Add. A data model object is added to the form data model. The newly added data model object is not bound to a data source and does not have any properties as shown in the following image.
Next, you can add child properties in unbound data model objects.
Add child properties child-properties
Form Data Model editor lets you create child properties in a data model object. The property when created is not bound to any property in a data source. You can later bind the child property with another property in the containing data model object.
To create a child property:
-
In a form data model, select a data model object and select Create Child Property.
-
In the Create Child Property dialog, specify a name and data type for the property in the Name and Type fields, respectively. You can optionally specify a title and description for the property.
-
Enable Computed if the property is a computed property. The value of a computed property is evaluated based on a rule or an expression. For more information, see Edit properties.
-
If the data model object is bound to a data source, the added child property is automatically bound to the property of the parent data model object with the same name and data type.
To manually bind a child property with a data model object property, select the browse icon next to the Bind Reference field. The Select Object dialog lists all properties from the parent data model object. Select a property to bind with and select the tick icon. You can only select a property of the same data type as the child property.
-
Select Done to save the child property and select Save to save the form data model… The child property is now added to the data model object.
After you have created data model objects and properties, you can continue to create Adaptive Forms based on the form data model. Later, when you have data sources available and configured, you can bind the Form Data Model with data sources. The binding automatically gets updated in associated Adaptive Forms . For more information about creating Adaptive Forms using form data model, see Use form data model.
Bind data model objects and properties bind-data-model-objects-and-properties
When the data sources you want to integrate with the Form Data Model are available, you can add them to the Form Data Model as described in Update data sources. Then, do the following to bind the unbound data model objects and properties:
-
In the form data model, select the unbound data source that you want to bind with a data source.
-
Select Edit Properties.
-
In the Edit Properties pane, select the browse icon next to the Binding field. It opens the Select Object dialog that lists data sources added in the form data model.
-
Expand the data sources tree and select a data model object to bind with and select the tick icon.
-
Select Done to save the properties and then select Save to save the form data model. The data model object is now bound with a data source. Notice the data model object is no longer marked Unbound.
Configure services configure-services
To read and write data for a data model object, do the following to configure read and write services:
-
Select the check box at the top of a data model object to select it and select Edit Properties.
Edit properties to configure read and write services for a data model object
The Edit Properties dialog opens.
Edit Properties dialog
note note NOTE 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 data source 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 also appears separately in the Data Model Objects tab. Therefore, you 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 the Top-Level Object property.
-
Select Read and Write services for the selected data model objects. The arguments for the services appear.
Read and write services configured for employee data source
-
Select for the read service argument to bind the argument to a User Profile Attribute, Request Attribute, or Literal value and specify the binding value.
-
Select Done to save the argument, Done to save the properties, and then Save to save the form data model.
Bind Read service arguments bindargument
Bind Read service argument to a User Profile Attribute, Request Attribute, or Literal value based on a binding value. The value is passed to the service as an argument to fetch details associated with the specified value from the data source.
Literal value literal-value
Select Literal from the Binding To drop-down menu and enter a value in the Binding Value field. The details associated with the value are retrieved from the data source. Use this option to retrieve details associated with a static value.
In this example, the details associated with 4367655678, as the value for the mobilenum
argument, are retrieved from the data source. The associated details if you pass the value for a mobile number argument can include properties such as customer name, customer address, and city.
User Profile Attribute user-profile-attribute
Select User Profile Attribute from the Binding To drop-down menu and enter the attribute name in the Binding Value field. The details of the user logged in to the Experience Manager instance are retrieved from the data source based on the attribute name.
The attribute name specified in the Binding Value field must include the complete binding path till the attribute name for the user. Open the following URL to access the user details on CRXDE:
https://[server-name]:[port]/crx/de/index.jsp#/home/users/
In this example, specify profile.empid
in the Binding Value field for the grios
user.
The id
argument takes the value of the empid
attribute of the user profile and pass it as an argument to the Read service. It reads and return values of associated properties from the employee data model object for the empid
associated with the logged in user.
Request Attribute request-attribute
Use the request attribute to retrieve the associated properties from the data source.
-
Select Request Attribute from the Binding To drop-down menu and enter the attribute name in the Binding Value field.
-
Create an overlay for the head.jsp. To create the overlay, open CRX DE and copy the
https://<server-name>:<port number>/crx/de/index.jsp#/libs/fd/af/components/page2/afStaticTemplatePage/head.jsp
file tohttps://<server-name>:<port number>/crx/de/index.jsp#/apps/fd/af/components/page2/afStaticTemplatePage/head.jsp
note note NOTE - If you use a static template, overlay the head.jsp at:
/libs/fd/af/components/page2/afStaticTemplatePage/head.jsp
- If you use an editable template, overlay the aftemplatedpage.jsp at:
/libs/fd/af/components/page2/aftemplatedpage/aftemplatedpage.jsp
- If you use a static template, overlay the head.jsp at:
-
Set paramMap for the request attribute. For example, include the following code in the .jsp file in the apps folder:
code language-javascript <%Map paraMap = new HashMap(); paraMap.put("<request_attribute>",request.getParameter("<request_attribute>")); request.setAttribute("paramMap",paraMap);
For example, use the below code to retrieve value of petid from data source:
code language-javascript <%Map paraMap = new HashMap(); paraMap.put("petId",request.getParameter("petId")); request.setAttribute("paramMap",paraMap);%>
The details are retrieved from the data source based on the attribute name specified in the request.
For example, specifying attribute as petid=100
in the request retrieves properties associated to the attribute value from the data source.
Add associations 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.
To add an association:
-
Select the check box at the top of a data model object to select it and select Add Association. The Add Association dialog opens.
note note NOTE 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 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, theEmployeeid
argument must be bound to theid
property of the Employee data model object to fetch the associated dependents details from the Dependents data model object.Updated argument and binding
Select Done to save the argument.
-
Select Done to save the association and then Save to save the form data model.
-
Repeat the steps to create more associations as required.
Edit properties properties
You can edit properties of data model objects, their properties, and services added in the form data model.
To edit properties:
-
Select the check box next to a data model object, a property, or a service in the form data model.
-
Select 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
-
-
Select Done to save properties and then Save to save the form data model.
Create computed properties computed
A computed property is the one whose value is computed based on a rule or an expression. Using a rule, you can set the value of a computed property to a literal string, a number, result of a mathematical expression, or the value of another property in the form data model.
For example, you can create a computed property FullName whose value is a result of concatenation the existing FirstName and LastName properties. To do so:
-
Create a new property with the name
FullName
whose data type is String. -
Enable Computed and select Done to create the property.
The FullName computed property gets created. Notice the icon next to the property to depict a computed property.
-
Select the FullName property and select Edit Rule. A rule editor window opens.
-
In the rule editor window, select Create. A Set Value rule window opens.
From the Select Option drop-down, select Mathematical Expression. Other available options are Form Data Model Object and String.
-
In the mathematical expression, Select FirstName and LastName in first and second objects, respectively. Select plus as the operator.
Select Done and then select Close to close the rule editor window. The rule looks similar to the following.
-
On the form data model, select Save. The computed property is configured.
Work with navigation properties of OData services work-with-navigation-properties-of-odata-services
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="https://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<script/>
<edmx:DataServices>
<Schema xmlns="https://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.
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.
Generate and edit sample data sample
Form Data Model editor lets you generate sample data for all data model object properties, including computed properties, in a form data model. It is a set of random values that comply with the data type configured for each property. You can also edit and save data, which is retained even if you regenerate the sample data.
Do the following to generate and edit sample data:
-
Open a Form Data Model and select Edit Sample Data. It generates and displays the sample data in Edit Sample Data window.
-
In Edit Sample Data window, edit data, as required, and select Save.
Test data model objects and services 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:
-
Select a data model object or a service in the Form Data Model and select Test Model Object or Test Service, respectively.
The Test Form Data Model window opens.
-
In the Test Form Data Model window, select the data model object or service to test from the Input pane.
-
Specify an argument value in the test code and select Test. A successful test returns the output in the Output pane.
Similarly, you can test other data model objects and services in the form data model.
Automated validation of input data automated-validation-of-input-data
The Form Data Model validates data received as input while invoking DermisBridge API (based on validation criteria available in form data model). The validation is based on the ValidationOptions
flag set in the query object that is used to invoke the API.
The flag can be set to any of the following values:
- FULL: FDM performs the validation based on all constraints
- OFF: No validation
- BASIC: FDM performs the validation based on ‘required’ and ‘nullable’ constraints
If no value is set for the ValidationOptions
flag, BASIC validation is performed on the input data.
The following is an example of setting the validation flag to FULL:
operationOptions.setValidationOptions(ValidationOptions.FULL);
If the value does not match the data type defined for the attribute, the DermisBridge API displays an exception irrespective of the value of the
ValidationOptions
flag. If the log level is set to Debug, an error is logged to the error.log file.The Form Data Model validates input data based on a list of data type constraints. The list of constraints for input data can vary based on the data source.
The following table lists the constraints for input data based on the data source:
In this example, the input data is validated based on maximum, minimum, and required constraints defined in the Swagger file. The input data meets the validation criteria only if Order Id is present and its value is from 1–10.
parameters: [
{
name: "orderId",
in: "path",
description: "ID of pet that must be fetched",
required: true,
type: "integer",
maximum: 10,
minimum: 1,
format: "int64"
}
]
An exception is displayed if the input data does not meet the validation criteria. If the log level is set to Debug, an error is logged to the error.log file. For example,
21.01.2019 17:26:37.411 *ERROR* com.adobe.aem.dermis.core.validation.JsonSchemaValidator {"errorCode":"AEM-FDM-001-044","errorMessage":"Input validations failed during operation execution.","violations":{"/orderId":["numeric instance is greater than the required maximum (maximum: 10, found: 16)"]}}
Next steps next-steps
You have a working Form Data Model that is now ready for use in Adaptive Forms workflows. For more information, see Use form data model.