Model variables

Overview

Model variables contain values that are used to customize the user experience or parameterize an integration job. The values of these variables are specific to a user session or an executed job.

Model variables are set either via a job parameter (for jobs) or retrieved from external systems—declared as variable value providers—when the user opens his session. Variables can be used in SemQL filters and expressions during design and run-time.

SemQL provides a set of built-in variables that contain details regarding the load or batch being processed, as well as information about the user that is connected or performing an operation(e.g., the user’s name, roles, email, or phone number they have entered in their profile).
For the complete list of variables, see Built-in platform variables.

Create model variables

Before creating a model variable, make sure that the variable value provider from which you want to retrieve information is declared in your Semarchy xDM platform.

To create a model variable:

Right-click the Model Variables node and select Add Model Variable.
The Create New Model Variable wizard opens.
In the Create New Model Variable wizard, select the Auto Fill option, and then enter the following values:
- Name: internal name of the object.
- Variable Type: select the data type of the variable: boolean, number, or string.
- Variable Value Provider: select the variable value provider that will be queried to retrieve the values for this variable.
Click Next.
Select the Edit Expression button.
In the Variable Lookup Query dialog, enter the query to retrieve the variable value:
- For a datasource variable value provider, enter a SQL Query. You can use :V_USERNAME (connected user name) or another built-in variable as a bind variable in this query.
- For an LDAP variable value provider, enter the parameters of the LDAP search:
  - Base DN: name of the base object entry (or possibly the root) relative to which the search is to be performed (e.g., dc=myCompany).
  - Filter: criteria to use for selecting elements within the scope. For more information on LDAP filters nad the LDAP syntax, see the LDAP documentation.
  - Attribute: attribute from the returned result to set in the variable value.
  - Search Scope: the depth of the search. Possible search scope values are Base Object (searches just the object specified in the base DN), Single Level (searches entries immediately below the base DN), or Whole Subtree (searches the entire subtree starting at the base DN).
Click Finish to close the wizard.
The Model Variable editor opens.
Press Control+S (or Command+S on macOS) to save the editor.
Close the editor.

Variable lookup queries

The variable lookup query defined in a model variable retrieves information from a variable value provider.

This information can be derived from the job or connected user’s information by using built-in variables such as V_USERNAME, V_USER_ROLES, or V_BATCHID.

For example, the V_USERNAME built-in variable stores the connected user name, and can be referred to in the variable lookup queries using the following syntax:

:V_USERNAME in SQL queries. For example, the following query retrieves the COUNTRY for the connected user name from a USERINFO table.
```
SELECT COUNTRY FROM USERINFO WHERE USER=:V_USERNAME
```
{V_USERNAME} in LDAP filters. For example, the following filter selects the persons (elements with the objectClass person) for which the common name ( cn) contains the connected user name.
```
(&(objectClass=person)(cn={V_USERNAME}))
```
Similarly, you could use the V_USER_ROLES variable, which stores the comma-separated list of roles of the connected user.

For the complete list of built-in variables, see Built-in platform variables.

Lookup queries should return a single value (column) and a single result (a record). If the query returns multiple results or multiple values, only the first value of the first result is taken into account and set in the variable value.

It is not possible to use a variable in the lookup query of another variable.

Test model variables

After creating a new model variable, it is recommended to test it.

To test a model variable:

In the Model Design view, double-click the model variable.
The Model Variable editor for this variable opens.
In the editor toolbar, click the Retrieve Current Value button.
The variable value refreshed for the current session appears in the Current Value field of the editor. If the variable cannot be refreshed, an error is issued.

Use model variables

Model variables serve two primary purposes:

In user sessions: these variables are set when a user accesses an application, through a variable value provider. In this context, variables are used to parameterize the user experience, such as in filters that restrict user privileges.
In integration jobs: variables in integration jobs typically have values set using a job parameter. If no job parameter is set, the value is derived from a variable value provider. In this context, variables are used to parameterize job execution such as in an enricher’s filter expression to prevent the enricher from processing any record based on the value.

Model variables can be used, for example, in the following SemQL expressions:

User’s search filters defined when accessing the data.
Filters in business views.
Fields and column values for forms and collections.
Row-level security filters defined in the model privileges grants.
Enricher filters or expressions.

In these SemQL expressions, you can bind the model variable using the :<variable name> syntax. You can also use in these expressions the built-in :V_USERNAME bind variable.

Use a variable to customize the user experience

To create a privilege grant allowing the connected user to see only their own record in the Employee master data:

In the model, create a variable called CurrentUserEmail, refreshed from the LDAP directory Email attribute filtered with (&(objectClass=person)(cn={V_USERNAME})).
Create the privilege grant on the Employee entity, filtered with the following SemQL expression: EmailAddress=:CurrentUserEmail

The connected user will be granted these privileges only for the master data record matching this expression.

Use a variable to parameterize an enricher’s execution

To parameterize an enricher’s execution depending on a job parameter value:

In the model, create a variable called RUN_ENRICHER, refreshed from the datasource value provider, using the SELECT '0' FROM DUAL database query.
In the enricher’s filter, enter :RUN_ENRICHER = 1.

If you set a job parameter named RUN_ENRICHER to 1 for the job running this enricher, then this enricher will run. Otherwise, it will process no record.

Variable values are cached. They are retrieved when the user connects and disposed of at the end of the user session. They automatically refresh:

At regular intervals (30 minutes).
When a designer refreshes the application.
When the model is deployed.
When the user profile information is modified.

If a variable value provider configuration is modified, possible changes to variable values are taken into account only when a refresh occurs.

When a model variable is used in a job, but no corresponding job parameter is set for the job, then the variable takes its value from the variable value provider, using as the connected user the one that has started the job.