When customizing the user interface, you must verify that the correct input is passed to the APIs you use. The primary way to retrieve data or perform updates in the user interface is through APIs. Making sure the right input is passed to these APIs is an important task for user interface customizations.
The application provides various mechanisms for passing input to APIs through the user interface. Which mechanisms you should use, and in what combination, depends on the type of screen and type of API being called.
This section describes the features and advantages of the following mechanisms for passing data to APIs:
- Input namespace
- Entity key
- Dynamic attributes
Sometimes the input expected to be passed to an API is not available through an input namespace or entity key. In these cases, using dynamic attributes may be applicable.
All API resources configured in the Resource Hierarchy tree have an input field whose purpose is to provide the ability to specify dynamic attributes. The value for this field should be a valid XML structure using elements and attributes. The XML structure specified here must match the exact input XML structure accepted by the called API.
One of the most common examples of using dynamic attributes is when a specific inner panel that must call multiple APIs to retrieve all the data that it needs to display. For example, an inner panel of a detail view of the order entity might require calling the getOrderDetails() (the standard detail API), and the getCommonCodeList() API to retrieve data for some combo box on the screen. Since common codes are stored at the rule set level, it is mandatory to make sure the correct rule set for that order is passed as input to the getCommonCodeList() API. The getOrderDetails() API, given the correct output template, returns the rule set key for the order. This rule set key can be passed to the getCommonCodeList() API by referring to the output of the getOrderDetails() API as a dynamic attribute in the input XML of the getCommonCodeList() API.
For example, the getOrderDetails() API returns:
<Order OrderHeaderKey="…" OrderNo="…" RulesetKey="…"/>
The Input field of the API resource definition for getCommonCodeList() , should be:
<CommonCode CodeType="ORDER_TYPE" RulesetKey="xml:/Order/@RulesetKey"/>
Notice that the value of the RulesetKey attribute is set to an XML binding that refers to the output of the getOrderDetails() function. The exact same rules of XML binding that apply when binding inputs inside of a JSP also apply when using dynamic attributes. This example also shows another way dynamic attributes can be used. The CodeType attribute is also specified in the input field in the API resource definition. Here, the value of the attribute is simply set to the static value “ORDER_TYPE”. This attribute and value are always passed to this API when it is called. Non-changing input values can be specified in this way.
Another possible value that you can use for a dynamic attribute for an API defined under a detail view is any attribute of the current entity key XML. This is useful when the input to pass to an API does not have the same XML structure of the entity key XML that has been formed in the detail screen. The XML for the current entity is available in a special namespace called SelectionKeyName.
The different mechanisms for specifying API input can be combined. For example, it may be necessary to pass the entity key and some dynamic attribute to an API configured under a detail view action. Since passing the entity key happens automatically, you can still specify an Input under that API with the correct XML structure. Note that the XML structure of the key should match the XML structure of the input field. There are other special namespaces available for use in dynamic attributes.
Frequently detail screens have API calling actions that only require the primary key of the current entity to be passed as the input.
When a detail view is brought up in the user interface, there is always at least one entity key passed to the detail view. This entity key consists of an XML structure containing the attributes that uniquely identify that entity. For example, the entity key of the order entity always contains an attribute for order header key. This entity key is automatically passed to the detail API of that entity. When this type of action is configured on a detail view, no other steps are required to ensure the right input is passed to the API.
In many cases, data from fields on the UI must be passed directly to the API. A simple example is any detail screen with editable input fields. These fields must be passed to a save API in order to update the entered data in the application’s database. This save API takes a specific XML structure as input. The fields on the detail screen should have XML binding that matches the input to the API.
In the Resource Hierarchy tree, the Input Namespace field in the action resource should be set appropriately to verify that the correct data from the console is passed to the save API.
Since all of the input fields on the screen have XML bindings for the input to the same API, they all have the same XML root element name in the binding. This root element name of the XML bindings is known as the namespace of that input field. Therefore, when that save action is invoked on the user interface, an XML is formed from all of the input fields containing the namespace specified for that action in the Resource Hierarchy tree. This XML is then passed to the API configured under that save action.
Another place where input namespace is frequently used is for user interface screens that have search criteria. The search criteria is passed to list APIs to fetch the data based on the search criteria entered. All the search criteria fields should have XML binding matching the input to the list API. The root element name of this XML is the namespace that should be specified for the list view that is shown when the user runs the search.