Leveraging Item Type Action Form Policies

In EmpowerID, the configuration and customization of user interface forms are managed through "Item Type Action Form Policies." These policies, utilizing JavaScript Object Notation (JSON), enable the creation of tailored forms corresponding to various user actions and item types. This article provides an overview of these policies, illustrating their operation and integration into the EmpowerID environment.

Introduction to Item Type Action Form Policies

Item Type Action Form Policies in EmpowerID are designed to streamline creating and modifying user interface forms. These policies use JSON to construct forms specific to actions and item types.

Detailed Operation of Item Type Action Form Policies

EmpowerID streamlines the creation and modification of UI forms through these policies. They utilize JSON to define the layout, elements, and overall functionality of the forms that appear when users interact with various item types, also known as "resource types."

For example, when someone needs to edit a person's attributes within EmpowerID:

The action executed is "Edit."
The related item type is "Person."
The applied policy is the "Edit Person Item Type Action Form Policy."

This structured approach ensures that forms are relevant to the task and integrated seamlessly into the user's workflow, improving the overall user experience and operational workflow.

Understanding the JSON Structure

Item Type Action Form Policies in EmpowerID leverage a structured, row-based layout within their JSON configuration, enabling the meticulous organization of form components. This approach facilitates a clear and logical assembly of the forms, allowing for customization that aligns with specific organizational needs. The configuration details include:

Rows and Width: These parameters establish how elements are grouped together and determine their relative sizes within the form, ensuring a balanced and intuitive layout.
Field Definitions: These settings dictate the behavior and appearance of various form elements such as text inputs, dropdowns, and trees, defined by attributes like fieldType, fieldName, and apiUrl. This level of control ensures that each element functions as intended, contributing to the overall effectiveness of the form.
Custom Attributes: Enhancements and modifications to form interaction are made possible through attributes such as localeKey, required, and disabled. These properties allow for personalizing the user's interaction with the form, ensuring it meets user and organizational requirements.

Having established the foundational understanding of the JSON structure utilized in Item Type Action Form Policies, we now transition to a more detailed examination of the components that make these forms function effectively.

Supported Form Element Types

As we delve deeper into the mechanics of EmpowerID forms, we encounter a variety of form elements, each governed by specific JSON attributes:

Text: The Text field represents a simple input for textual data, which is essential for capturing user input, such as names or descriptions.
- JSON: {"fieldType": "text"}
Dropdown: This feature facilitates the selection of a single item from a predefined list, thereby improving form navigation and ensuring more accurate choices.
- JSON: {"fieldType": "dropdown"}, Additional JSON: {"apiUrl": "/api/fetchOptions"}
Multi-Select Dropdown: This feature enables users to make multiple selections within a dropdown, enhancing the flexibility of the form.
- JSON: {"fieldType": "multiSelectedDropdown"}, Additional JSON: {"apiUrl": "/api/fetchOptions"}
Tree: This feature allows for hierarchical selections, which is crucial for organizing intricate datasets like Business Roles and Locations.
- JSON: {"fieldType": "tree"}, Additional JSON: {"apiUrl": "/api/fetchTree"}

JSON Attribute Descriptions

To fully leverage these elements, understanding their distinct JSON attributes is vital:

Row: Structurally organizes a section of the form horizontally, ensuring logical flow and user comprehension.
width: Manages each element's space within a row, crucial for maintaining form balance and readability.
localeKey: Serves for text localization and labeling, enhancing the form's accessibility and user-friendliness.
fieldName: Identifies the data property associated with a form element, linking form fields directly to underlying data structures.
fieldNameLabel: Specifies the person's property used to display the initially selected option label for a tree element.
fieldType: Dictates the type of element deployed (e.g., text, dropdown, tree), defining the nature of user interaction.
apiUrl: Points to the external data source for elements requiring external information, such as dropdowns or trees.
required, disabled: Flags that indicate whether an element is mandatory or inactive, guiding user interaction and form completeness.
dataAttributes: Specifies attributes used as value and label for options when fetched via the apiUrl, applicable primarily to tree and dropdown elements.

Example: The Edit Person Form

Illustrating these principles, the "Edit Person" form within Resource Admin showcases how Item Type Action Form Policies are applied. This form, customized through JSON configurations applied to the policy, exemplifies EmpowerID's dynamic interface capabilities.

A specific JSON configuration defines the underlying structure of this form. This configuration includes two primary objects: dynamicFields and accessDetails. The JSON format uses nesting and arrays to delineate the appearance and data management of the "Edit Person" form. The JSON code below demonstrates how the two objects construct the form.

dynamicFields: This portion defines the layout and content of the form. Here's a snippet showcasing the configuration for the first row of the form:

{

	"dynamicFields": {
		"Row1": [{
					"width": 50,
					"localeKey": "Role",
					"fieldName": "primaryOrgRoleId",
					"fieldNameLabel": "primaryOrgRoleName",
					"fieldType": "tree",
					"apiUrl": "/api/lookups/businessrolestree",
					"fieldPlaceHolder": "SelectRole",
					"dataAttributes": {
						"value": "id",
						"label": "title"
					},
					"required": true,
                    "disabled":true
				},
				{
					"width": 50,
					"localeKey": "Location",
					"fieldName": "primaryOrgZoneId",
					"fieldNameLabel": "primaryOrgZoneName",
					"fieldType": "tree",
					"apiUrl": "/api/lookups/businesslocationstree",
					"fieldPlaceHolder": "SelectLocation",
					"dataAttributes": {
						"value": "id",
						"label": "title"
					},
					"required": true
				}
			],...

In this example, Row1 contains fields related to "Role" and "Location," each allocated half the row's width.

Additionally, each element within a row can be further divided into subcolumns, as demonstrated by the second row.

"Row2": [
                {
                    "width": 50,
                    "required": true,
                    "subColumn": [
                        {
                            "width": 70,
                            "localeKey": "FirstName",
                            "fieldName": "firstName",
                            "fieldType": "text"
                        },
                        {
                            "width": 30,
                            "localeKey": "Infix",
                            "fieldName": "title",
                            "fieldType": "text"
                        }
                    ]
                }
		]

In this example snippet, Row2 contains two fields related to "First Name" and "Title," allocated half the row's width, with 70% of the half allocated to the First Name and 30% of the half allocated to the Title.

accessDetails Object: This section is comprised of key/value pairs used to return all applications the person has access to:

"accessDetails": {
  "apiEndPoint": "/api/applications",
  "friendlyName": "Applications",
  "type": "Application"
}

Practical Tips for Customization

When customizing, keep the user experience in mind to maintain form functionality and user-friendliness. Detailed instructions for altering existing Item Type Action Form Policies can be found in the "Customizing Item Type Action Form Policies" section. By understanding the JSON layout and the functions of its various components, administrators can effectively tailor the "Edit Person" form and others like it to meet the unique needs of their organization while ensuring a seamless user experience.

ctical Tips for Customization

When customizing, keep the user experience in mind to maintain form functionality and user-friendliness. Detailed instructions for altering existing Item Type Action Form Policies can be found in the "Customizing Item Type Action Form Policies" section.

By understanding the JSON layout and the functions of its various components, administrators can effectively tailor the "Edit Person" form and others like it to meet the unique needs of their organization while ensuring a seamless user experience.