Model Variables

Overview

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

The 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 at design and run-time.

SemQL provides a set of built-in variables that contain information about the load or batch being processed or about the user connected or performing the operations. For example, the user name, its roles, the email or phone number he has entered in his profile.
Refer to Built-in Platform Variables for the list of all these variables.

Create Model Variables

Before creating a model variable, make sure that the Variable Value Provider from which you want to retrieve the 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, check 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: The name of the base object entry (or possibly the root) relative to which the search is to be performed. For example: dc=myCompany.
  - Filter: Criteria to use for selecting elements within the scope. For more information about LDAP filters, see LDAP Search Filter Syntax.
  - Attribute: The 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 (search just the object specified in the Base DN), Single Level (search entries immediately below the base DN), or Whole Subtree (the entire subtree starting at the base DN).
Click Finish to close the wizard. The Model Variable editor opens.
Press CTRL+S 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 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.

Refer to Built-in Platform Variables for the list of built-in 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 can be used:

In user sessions: They are set when the user accesses an application, using a variable value provider. In this context, variables are used to parameterize the user experience (for example, in filters restricting the user privileges).
In integration jobs: In an integration job, a variable value is usually set using a job parameter. If no job parameter is set, the value is set using the variable value provider. In this context, variables are used to parameterize the job execution (for example, in an enricher’s filter expression to prevent the enricher from processing any record depending on the value).

Model Variable 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,
Etc.

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 his own record in the Employee master data:

In the model, create a variable called CurrentUserEmail, refreshed from the LDAP directory attribute email 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 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.