Imperative Extensions

Imperative extensions enable you to create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar. For example, you can't use the JSON grammar to navigate a data table where each column shows data from a different type of component with different markup.

Note: Imperative extensions are powerful because you can use the full capabilities of a programming language. However, we strongly discourage their usage except as a last resort because they violate the declarative nature of UTAM. If you use an imperative extension, you must implement and maintain it in each programming language that you use with UTAM.

Declare imperative utility code in a compose statement. A page object can reference multiple utilities.

{
    "methods": [
        {
            "name": "myMethod",
            "compose": [
                {
                    "applyExternal": {
                        "type": "utam-lst/utils/lst/relatedListContainerUtils",
                        "invoke": "cardUtility1",
                        "args": [
                            {
                                "name": "stringArg",
                                "type": "string"
                            }
                        ]
                    }
                },
                {
                    "applyExternal": {
                        "type": "utam-lst/utils/lst/relatedListContainerUtils",
                        "invoke": "cardUtility2",
                        "args": [
                            {
                                "name": "booleanArg",
                                "type": "boolean"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

An imperative extension in a compose statement has these properties:

• element (Optional.) String. A reference to the element passed as the first parameter to the utility code. The default value is self so if no element is set, we pass the page object itself. You can omit this property because you can access the elements from the page object reference passed to the utility code.
• applyExternal (Required) Object. Declares an imperative extension and has these properties:
  • type (Required) String. A reference to the executable code to import: either a Java class or a JavaScript ES module.
  • invoke (Required) String. A reference to the method name to call: a named function in JavaScript or a static method in Java.
  • args (Optional) Array. If the code needs parameters, provide them in an array. Each element of the array has these properties:
    • name (Required) String. A parameter name that is unique in the scope of the args array.
    • type (Required) String. A parameter type, which is a primitive type, locator or a function.

For examples of Java and JavaScript code implementations, see Guide: Imperative Extensions.