Referencing a Form Model

Form models can be accessed by rules and scripts within workflows or forms within workflows using the $() parsing tokens, for example, $(identityModel.name). When variables are referenced with this syntax, the ScriptPreParser expands the short hand path references into the proper MapUtil.get() reference. This notation can be used in scripts run from fields, variables, steps, transitions or step actions. The script can explicitly specify the full path to the variable in the model, for example, $(identityModel.name), or it can reference the variable directly when a modelBasePath has been defined, for example $(name).

Note: In order to set a basePath in a form, an argument named modelBasePath (defined as Rule.MODEL_BASE_PATH) must be set declaring the path to be used for all the expanded variables in the form. For example, <Arg name='modelBasePath' value='identityModel'/>. The modelBasePath does not have to be specified at the top level; for example, it can point to a list or map within the top-level map such as <Arg name='modelBasePath' value='identityModel.links[AD]'/> (this is the map representing the user's AD account link).

Note: This $() notation can only be used for retrieving values from the model; it cannot be used to set or change values in the model.

Use the following syntax rules when writing references within the scripts:

  • A dollar sign with parentheses [$()] is used as the parsing token to indicate what contents should be expanded. For example, $(foo.bar).

  • Double quotes are valid when enclosing spaces within the variable: $(foo."bar baz"). However an expansion token within a quoted string is not processed: "$(not.expanded)"

  • Brackets can be used within a variable to access elements in a list: $(foo.bar[baz=bingo].buzz) $(foo.bar[baz="path with spaces"].buzz)

  • When the modelBasePath is set to a sub-map or list within the model, the forward slash escape character (/) can be used to jump to the root of the basePath. This escape character must be the first character after the expansion token. If basePath is set to 'identityModel.links[AD]' and the desired reference is for identityModel.firstname the variable would be written as $(/firstname) which would be converted to IIQ.tools.MapUtil.get(identityModel, "firstname"). Otherwise $(firstname) is converted to IIQ.tools.MapUtil.get(identityModel, "links[AD].firstname")

  • If no basePath is set and the variable only contains a single word, no expansion occurs and a warning is written to the log indicating a possible error condition.

The following are all valid:

No base path:

  • $(foo.bar) —> IIQ.tools.MapUtil.get(foo, "bar")

  • $(foo."bar baz") —> IIQ.tools.MapUtil.get(foo, "\"bar baz\"")

  • $(foo.bar[baz="path with spaces"].buzz)—> IIQ.tools.MapUtil.get(foo, "bar[baz=\"path with spaces\"].buzz")

Base path = ‘foo’

  • $(foo.bar) —> IIQ.tools.MapUtil.get(foo, "bar") (assuming basePath is set to 'foo'. This respects the basePath and does not try to find a "foo" attribute within the "foo" map)

  • $(bar)—> IIQ.tools.MapUtil.get(foo, "bar") (assuming basePath is set to 'foo')

Base path = ‘foo.bar[AD]’

  • $(baz)—> IIQ.tools.MapUtil.get(foo, "bar[AD].baz") (assuming basePath is set to 'foo.bar[AD]')

  • $(/baz)—> IIQ.tools.MapUtil.get(foo, "baz") (assuming basePath is set to 'foo.bar[AD]')