Variables and parameters

Variables store values relevant to either an integration job or a user session’s context. Variables are either built-in platform variables or model variables.

Parameters are supplied to named queries or search forms to filter records using a condition.

Built-in platform variables

Built-in platform variables are available by default. They contain details regarding the load or batch being processed, as well as information about the user that is connected or performing an operation.

The table below lists built-in variables.

Variable name Definition

V_BATCHID

ID of the batch running the integration job. This variable is not available in expressions used outside the certification process, such as enrichers or validations triggered in steppers.

V_DATALOCATION

Name of the deployment data location.

V_LOADID

ID of the external load that has submitted the integration job. This variable is not available in expressions used outside the certification process, such as enrichers or validations triggered in steppers.

V_SERVER_BASE_URL

Base URL of the Semarchy xDM server, as configured by the administrator.

V_USERNAME

For the certification process, name of the user who has submitted the integration job. For a user data session, name of the connected user.

V_USER_ROLES

Comma-separated list of roles of the connected user. Note that this variable only returns user roles that have corresponding roles declared in Semarchy xDM (in the Administration view, under the Roles node.). For the Tomcat application server specifically, all roles are returned, including those with no corresponding role declared.

V_USER_ADDRESS

User’s address, configured by the user in their profile.

V_USER_CITY

User’s city, configured by the user in their profile.

V_USER_COMPANY_NAME

User’s company, configured by the user in their profile.

V_USER_COUNTRY

User’s country, configured by the user in their profile. This variable uses the ISO 3166-1 alpha-2 country code format (e.g., US: United States of America, FR: France).

V_USER_DECIMAL_SEPARATOR

User’s preferred decimal separator, configured by the user in their profile.

V_USER_DEPARTMENT

User’s department, configured by the user in their profile.

V_USER_EMAIL

User’s email, configured by the user in their profile.

V_USER_FIRSTNAME

User’s first name, configured by the user in their profile.

V_USER_JOB_TITLE

User’s job title, configured by the user in their profile.

V_USER_LANGUAGE

User’s language tag, configured by the user in their profile. This variable uses IETF BCP 47 language tag format (e.g., en: English, fr_FR: French - France).

V_USER_LASTNAME

User’s last name, configured by the user in their profile.

V_USER_POSTAL_CODE

User’s postal code, configured by the user in their profile.

V_USER_PRIMARY_PHONE

User’s primary phone, configured by the user in their profile.

V_USER_SECONDARY_PHONE

User’s secondary phone, configured by the user in their profile.

V_USER_THOUSAND_SEPARATOR

User’s preferred thousand separator, configured by the user in their profile.

V_USER_TIMEZONE

User’s timezone, configured by the user in their profile. The time zone is one of the TZ Database time zones (e.g., America/New_York, Europe/Paris). Note that the timezone has a fallback value to Etc/GMT.

Model variables are used with the following syntax: :<variable_name> (e.g., :V_USER_LASTNAME).

Model variables

Variables are values specific to a user session or an executed job. They are either set via a job parameter (for jobs) or retrieved from remote servers (declared as variable value providers) when the user initiates their session.

Variables can be used in SemQL filters and expressions during design and run-time.

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 sourced from variable value providers are refreshed when a user accesses xDM. In the context of a job, variables are refreshed as if the user initiating the job had accessed xDM.

Use platform variables to retrieve and store corporate user email from LDAP

Using the built-in platform variables V_USERNAME, it is possible to query the corporate LDAP directory (through a variable value provider definition) and retrieve the email of the logged-in user. Subsequently, this value can be stored in a model variable named CORPORATE_USER_EMAIL.

For more information about model variables, see Model variables for more information.

Model variables are used with the following syntax: :<variable_name> (e.g., :CORPORATE_USER_EMAIL).

Search parameters

Search parameters store values entered into a search form and submitted to the associated search condition. They are exclusive to the respective search form’s condition.

Parameters are used via their defined binding, using the following syntax: :<binding_name> (e.g., :SEARCHED_NAME).

When editing the SemQL condition of a search form, the available search parameters are listed in the Variables section of the SemQL editor.

Named queries parameters

Query parameters store the values transmitted to a request made to a named query. They are accessed via their binding name, similar to search parameters.