Process - Standard service tasks in Identity Manager
This article includes updates for Smart ID 23.10.5.
Process: Assert Uniqueness Task
Description
Use this task to run a search configuration and trigger an ErrorBoundaryEvent with error code "uniquenessTestFailed" if a uniqueness criteria is not met. The event might cause a different process flow.
Configuration
To use this task, configure the following delegate expression in your service task:
${assertUniquenessParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
searchConfigName | Defines the search configuration that should be used to count objects. During process execution the user must have the permission to execute the search configuration. It is possible to use a search configuration that searches over multiple levels. | ||
minCount | - | The minimum number of objects that should be found. If the search finds less than minCount objects, the action will trigger an ErrorBoundaryEvent with error code "uniquenessTestFailed". Although neither minCount nor maxCount are mandatory, at least one of them must be specified. | |
maxCount | - | The maximum number of objects that should be found. If the search finds more than maxCount objects, the action will trigger an ErrorBoundaryEvent with error code "uniquenessTestFailed". Although neither minCount nor maxCount are mandatory, at least one of them must be specified. | |
resultVariableName | - | resultCount (used if nothing is specified) | Specifies where the number of found objects will be stored in the data map. The value is stored whether the condition is met or not. If no resultVariableName is specified, 'resultCount' is used as a default name. |
<Datapool_Field> | - | For configuring search fields, add a parameter for each search field. The name of the parameter should be the full name of the datapool field. The value has to contain the filter condition and value, separated by a colon symbol. For example:
If the underlying data source of the search configuration does not allow to query just the number of result objects, only as less objects as possible are fetched, but enough to find violations of minCount or maxCount. If the number of found objects equals to the upper limit, that was searched for, it is not possible to decide whether there are more objects. In such cases a hint is logged in debug mode: "The search has been restricted to 2 object(s) for performance reasons, but there might exist more objects". For more information, see <Datapool_Field> under Process: Execute Search Task. |
Process: Build ZIP file with binary data from search result
Description
Use this task to load pack binary data objects into a ZIP file. A CoreObjectDescriptor is needed (loaded in a service task before) to have a list with core objects which contain the binary data fields. Different binaries belonging to one core object can be packed together into one ZIP file (for example photo and signature). Reference-fields can also be added into zip, if they represent a binaryData (like softtoken).
Configuration
To use this task, configure the following delegate expression in your service task:
${buildZipFileFromBinariesParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
resultVariableNameZipFile | Fieldname in the datamap where the builded zipFile is written to. | ||
resultVariableNameZipName | - | Fieldname in the datamap where the name of the zipFile is written to. | |
zipfileName |
| Example value:
| How the zipFile shall be named. fileExtension like '.zip' is needed. |
coreObjectDescriptorList | coreObjectDescriptor which contains a list of CoreObjects with binaryData | ||
<name of the zipFile-Entry> | (minimum 1) | <name of binaryField to save into zipFIle> Example value:
|
|
Process: Copy Values of LoggedIn User to Process Map
Description
Use this task to copy information about the currently logged in user to the process data map. Since the parameters are optional, only those parameters where a value is provided are copied to the process data map.
Configuration
To use this task, configure the following delegate expression in your service task:
${copyValuesOfLoggedInUserToProcessMapParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
userNameOutputField | - | userinfoUsername | The output field of the datamap which will contain the user name. |
userFullNameOutputField | - | userinfoUserFullName | The output field of the datamap which will contain the user's full name. |
userIdOutputField | - | userinfoUserid | The output field of the datamap which will contain the user id. |
userIpAdressOutputField | - | userinfoIpAddress | The output field of the datamap which will contain the user's IP address. |
userAuthProfileTypeOutputField | - | userinfoAuthprofileType | The output field of the datamap which will contain the users AuthProfileType (Enum is passed). |
userExplorerInstanceIdOutputField | - | userinfoExplorerInstanceId | The output field of the datamap which will contain the user's explorer instance ID if logged in through explorer. |
userUsspInstanceIdOutputField | - | userinfoUsspInstanceId | The output field of the datamap which will contain the user's Smart ID Self-Service instance ID if logged in through Smart ID Self-Service. |
userRolesOutputField | - | userinfoUserRoles | The output field of the datamap which will contain the user's assigned roles as a list. This is not meant to be used for the GUI and may result in issues. Use this, for example, in gateways like this:
|
userSamlTokenIDOutputField | - | userinfoSamlTokenID | The output field of the datamap which will contain the user's SAML Token ID. |
userSamlIssueInstantOutputField | - | userinfoSamlIssueInstant | The output field of the datamap which will contain the user's SAML IssueInstant. |
userLocaleOutputField | - | userinfoLocale | The output field of the datamap which will contain the user's selected Locale. |
Process: Delete Secret Field
Description
Use this task to delete a secret field from secret field store and clear the reference to it.
Configuration
To use this task, configure the following delegate expression in your service task:
${deleteSecretField}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
referenceField | The field to be deleted in secret field store. |
Process: Execute script
Description
Use this task to execute a script and put the result variables to the process map.
Configuration
To use this task, configure the following delegate expression in your service task:
${executeScriptTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
scriptName | The name of the script. |
Process: Execute Search Task
Description
Use this task to run a search configuration and put the result to the map as core object descriptor list or as the complete object.
Searches in external datapools, such as LDAP, SCIM or JDBC, need to be based on a CoreTemplate.
If the number of search results is equal to or more than maxCount this is logged in the Tomcat log file.
A process variable executeSearchResultCount
will hold the number of the found entities.
Configuration
To use this task, configure the following delegate expression in your service task:
${executeSearchParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
searchConfigName | - | Defines the search configuration that should be used to count objects. During process execution the user must have the permission to execute the search configuration. It is possible to use a search configuration that searches over multiple levels. Note: The binary data fields will not be loaded into the process map unless the search configuration has at least one binary data field in the result columns. | |
maxCount | The maximum number of objects that should be found. | ||
resultVariableName | - |
| Specifies the name of a variable of the data map, where the CoreObjectDescriptorList of the found objects is stored. |
copyValuesOfFirstResult | - | Valid values:
| This parameter decides whether the first found object is put completely to the map (true) or if the CoreObjectDescriptorList is put to the map (false). If set to true, resultVariableName will be ignored. maxCount will be ignored too and set to 1. |
fullResultListField | - | <variableName> | Variable in which the full search result will be stored inside the process map. Will be ignored if it is empty. |
TargetPrefix | - | <Prefix> Example: Manager_ | If the found objects fields should be added to the process map with a special prefix. It replaces the <Datapool_>, which is otherwise at this position. With this function, conflicting entries can be avoided. Example: Instead of "Person_Email" the data map will get an additional entry: "Manager_Email". |
sortColumn | - | <ColumnName> Example: FirstName | This parameter is the column name of the dataset, which is taken to order the search result. |
sortOrder | - | Valid values:
| Combo box to select if the search result is ordered ascending or descending. Default is ascending. |
<Datapool_Field> | - | <CONDITION>:<value> Examples:
Valid CONDITIONS:
|
You can also use the conjunctions AND and OR. For example: |
searchUniqueId | - | <value> Example: ${<Datapool>_Id} | It is the Unique ID (<Datapool>_Id) used to store records in the underlying database. The value can be a literal or a JUEL expression. This filter always uses equals to identify the record. In case of a related search, this is used to identify the Source Object. |
resultUniqueId | - | <value> Example: ${<Datapool>_Id} | It is the Unique ID (<Datapool>_Id) used to store records in the underlying database. The value can be a literal or a JUEL expression. This filter always uses equals to identify the record. In case of a related search, this is used to identify the Result Object. |
Process: Find Next Possible States
This action works only in context with batch orders.
Description
Use this task to find the next possible/valid states to a given core object state. If the multiple selected core objects (in a batch order) do have different states (for example active, inactive), an ErrorBoundaryEvent will be triggered.
Configuration
To use this task, configure the following delegate expression in your service task:
${findNextPossibleStates}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
dataPoolName | The datapool name of the underlying batch order. | ||
resturnField | The name of the variable containing all the possible states (which were found). |
The task can be defined as follows:
<bean id="findNextPossibleStatesAction" class="de.vps.act.processexecution.state.FindNextPossibleStatesAction">
<property name="coreTemplateProvider" ref="coreTemplateProvider"/>
<property name="stateGraphDefinitionManager" ref="stateGraphDefinitionManager"/>
<property name="coreObjectDAO" ref="coreObjectDAO"/>
</bean>
<bean id="findNextPossibleStates" parent="parameterizedTask">
<property name="action" ref="findNextPossibleStatesAction" />
</bean>
Process: Load Entity
Description
Use this task to load an entity into the process map.
Given a datapool, a field, the field's value and optionally a core template, the matching entity will be loaded. If more than one entity matches, no entities will be added to the process map. A process variable loadEntityResultCount
will hold the number of the found entities. Any value other than 1 can be considered an error.
Configuration
To use this task, configure the following delegate expression in your service task:
${loadEntityParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
EntityDataPool | Person | The name of the entity's datapool. | |
EntityAttribute | The attribute of the entity that must match a certain value. | ||
EntityAttributeValue | ${Person_Email} or ${user.Person_Email} | The value that EntityAttribute must match. Most of the time, an expression will be used here. Also special expressions like ${user.*} are possible, to use values from the authenticated User or from system.properties (${sysprop.*} | |
EntityCoreObject | The core template of the entity. This limits the search to objects of this core template. | ||
EntityCoreObjectIdField | coreObjectId | The field in which the CoreObjectId is added in the process map. | |
EntityCoreObjectDescField | coreObjectDescriptor | The field in which the CoreObjectDescriptor is added in the process map. | |
EntityRolesField | roles | The field in which the roles of the object is added in the process map. | |
ExclusiveLoadFields | FirstName,LastName,Email | If not the complete dataset should be loaded, only the ones defined here are loaded/added in the process map. | |
TargetPrefix | Manager_ | If the found objects fields should be added to the process map with a special prefix. It replaces the <Datapool_>, which is otherwise at this position. With this function, conflicting entries can be avoided. Example: Instead of "Person_Email" the data map will get an additional entry: "Manager_Email". |
Process: Load Entity on Certificate Attribute
Description
This task expects a certificate in the process map and loads an entity from the DB, based on a value of the certificate. You configure what kind of entity (Person, Server etc) and which certificate field should match which field of the entity. A case insensitive search is performed. If exactly one entity is found, it will be added to the process map. If more that one entity is found, no entities will be added to the process map. A process variable loadCertificateMatchingEntityResultCount will hold the number of the found entities. Any value other than 1 can be considered an error.
This task can be used to establish an objectRelation between the certificate and an entity.
Configuration
To use this task, configure the following delegate expression in your service task:
${loadCertificateMatchingEntityParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Note: Values are case sensitive.
Parameter | Mandatory | Value | Description |
---|---|---|---|
certificateDataPoolName | Certificate | The name of the certificate's datapool. | |
certificateDataFieldName | Data | The name of the field of the certificate's datapool that holds the binary certificate. | |
certificateAttribute | Example value:
| The field of the certificate whose value must match the entity. SAN values are prefixed with "SAN_". Possible values: any one of de.nexus.pkiutils.certificate.DNs or any one of de.nexus.pkiutils.certificate.SANs. Currently that allows the following possibilities: DN_C, DN_CN, DN_DNQ, DN_E, DN_L, DN_O, DN_OU, DN_SN, DN_ST, DN_UID, DN_STREET, DN_INITIALS, DN_POSTAL_ADDRESS, DN_POSTAL_CODE, DN_TELEPHONE_NUMBER, DN_TITLE, DN_SURNAME, DN_GIVENNAME, SAN_EMAIL, SAN_UPN, SAN_DNS, SAN_IP, SAN_URI, SAN_GUID, SAN_RID. | |
entityDataPoolName | Person | The datapool of the entity to loadCertificateMatchingEntityParameterizedTask | |
entityDataPoolFieldName | The name of the field of the entity's datapool that must match the certificate's field value. | ||
entityCoreTemplateName | - | Person | The core template of the entity. This limits the search to objects of this core template. |
Process: Load values of SystemProperties into process map
Description
Use this task to load one or more values of SystemProperties, which are configured in the Admin tab in Identity Manager, into fields of the process map.
Configuration
To use this task, configure the following delegate expression in your service task:
${loadSystemPropertyIntoProcessmapParametrizedTask}
The following parameters can be configured in Identity Manager Admin, they can be added with the '+'-button, each row sets one system property into the target field:
Parameter | Mandatory | Value | Description |
---|---|---|---|
targetFieldName | Name of systemProperty to load | Combination of target field and system property. A system property is defined of <contextid>.<propertyName>. |
Process: Log something in the log file
Description
Use this task to log something in the logfile. The results will not be visible to an end user.
Configuration
To use this task, configure the following delegate expression in your service task:
${loggingParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
loggerName | Any String, but typically a java package optionally followed by a class name. Example values:
| In the log4j configuration, defined loggers have a name, typically a package name or a class, however any String is valid. This attribute specifies to which logger this task will write. You can use this to route the log message to a file, the console or any other appender. | |
loglevel | Valid values:
| Use this to describe the severity of the log entry. It will appear in the logfile. Loggers and/or appenders typically ignore entries under a configurable threshold. | |
message | Any String or JUEL expression. Example values:
| The message that will be logged. You can use Expression Language and methods from the String API. Expressions will be evaluated against the process map. | |
ignoreKeyNotFound | Valid values:
| If this is set to true, expressions from the message that can't be resolved to a key in the process map will be ignored. If it is set to false, an exception will be thrown. |
Process: Put process instance ID in data map
Description
Use this task to put the process instance ID of the current process in a variable of the data map.
Configuration
To use this task, configure the following delegate expression in your service task:
${putProcessInstanceIdInDatamapParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
OutputVariableName | Specifies the name of a variable of the data map, in which the process instance ID should be put. |
Process: Remove Entity from data map
Description
Use this task to remove an entity from the process map. Given a name of a datapool, all fields from the datamap will be removed. If the given name does not match a datapool, no fields will be removed.
Configuration
To use this task, configure the following delegate expression in your service task:
${removeEntityFromDatamapParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
EntityDatapoolName | The name of the entity's datapool. |
Process: Removing Variable
Description
Use this task to remove a variable from the data map of the process.
Configuration
To use this task, configure the following delegate expression in your service task:
${variableRemovingParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
variableName | The name of the variable, which should be removed from the process map |
To remove more than one variable, add lines to the list and set the parameter value to a higher number.
Example:
Parameter | Value |
---|---|
variableName | Datapool_Field1 |
variableName2 | Datapool_Field2 |
variableName3 | Datapool_Field3 |
... | ... |
Process: Secret Fields comparator service task
Description
Use this task to compare two secret fields. If they are equal, the service task will return true, otherwise, false. The comparator is case sensitive, so only exact matches will return true. Note that blank values are not considered valid.
Passing secret fields directly into the data map is a security issue, so the service task will only expect UIDs of valid, already stored, secret fields.
Configuration
To use this task, configure the following delegate expression in your service task:
${compareSecretsParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
firstSecretFieldName | String value | UID of the first secret field | |
secondSecretFieldName | String value | UID of the second secret field | |
resultFieldName | String value Default value: secretsAreEqual | The name of the variable in the processMap that will contain the result of the comparison. |
Process: Set Value of Variable in Process Map
Description
Use this task to set a variable to a desired value, including an empty string or null.
Configuration
To use this task, configure the following delegate expression in your service task:
${setValueOfVariableInProcessMapParameterizedTask}
The following parameters can be configured in PRIME Designer:
Parameter | Mandatory | Value | Description |
---|---|---|---|
variableName | The name of the variable whose value should change in the process map | ||
variableValue | - | The new value for the variable. It may contain JUEL expressions like ${Person_FirstName}. | |
setToNull | - | Valid values:
| If set to true, the variable's value will be set to null. |
setToEmptyString | - | Valid values:
| If set to true, the variable's value will be set to an empty string. |
Be sure to configure exactly only one of variableValue, setToNull and setToEmptyString. Otherwise an Exception is thrown.
JUEL expressions
Unresolvable JUEL expressions in variableValue are ignored by default.
If you want an exception to be thrown instead, add the following bean definitions to your custom-beans.xml:
<bean id="keyNotFoundThrowingSpelResolver" class="de.vps.act.juel.SpelExpressionResolver">
<constructor-arg name="expressionPrefix" value="${" />
<constructor-arg name="expressionSuffix" value="}" />
<constructor-arg name="keyNotFoundSafe" value="false" />
</bean>
<bean id="setValueOfVariableInProcessMapParameterizedAction" class="de.vps.act.action.datamap.modification.SetValueOfVariableInProcessMapParameterizedAction">
<property name="juelExpressionResolver" ref="keyNotFoundThrowingSpelResolver" />
</bean>
Process: Search the newest Encryption Certificate
Description
Use this task to execute a searchConfig and search in a list of X509-certificates for the newest Encryption Certificate.
If one is found it is saved in the database (if it`s not existing already under the configured core template name) and loaded into the processMap as CoreObjectDescriptor.
If the certificate is found in the database but under a different core template name, a second entry will be saved under the configured core template name.
This task is useful, for example, when a field of a LDAP-datapool contains a (multi-value binary) list of certificates.
Configuration
To use this task, configure the following delegate expression in your service task:
${searchNewestEncCertParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
searchConfigName | Select in drop-down list | The searchConfig, which is executed to search the list of X509-Certificates | |
encCertResultCoreTemplate | Select in drop-down list | The name of a CoreTemplate to store the found encryptionCertificate in the Database, if it does not already exist with this CoreTemplate name. The name must be based on CertificateDAO-dataPool If the certificate already exists with a different CoreTemplate name, a second entry will be saved with the encCertResultCoreTemplate. It is recommended to use these additional entries only temporarily and remove them after use. | |
encCertResultDescriptorName | String value | The name of the variable in the processMap where the found encryptionCert is put as CoreObjectDescriptor | |
X509ListFieldInSearchResult | String value | The field in the result of the searchConfig with the list of certificates. This field should be a multi-value binary field in the datapool (LDAP-datapool). | |
<Datapool_Field> | - | Additional Filter-Field for the searchConfig, added with '+'-Button For more information, see <Datapool_Field> under Process: Execute Search Task. |
Process: Set Variables in Process Map
Description
Use this task to set a variable to a desired value, including an empty string or null.
Configuration
To use this task, configure the following delegate expression in your service task:
${setVariablesParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
setEmptyAsNull | Valid values:
| Defines if a variable without a value should stay empty or null. | |
<variableName> | - | <variableValue> | The name and value of the variable. It can be also a combination of expressions that gets resolved from current values of the process map. Example:
|
<variableName2> | - | <variableValue2> | |
... | - | ... | Fill in as many variables as needed. |
Process: Validate a value in the Process Map against a regular expression
Description
Use this task to validate a value in the process data map against a regular expression. The result is saved as true/false in the process data map.
Configuration
To use this task, configure the following delegate expression in your service task:
${validateFieldWithRegexParameterizedTask}
The following parameters can be configured in Identity Manager Admin:
Parameter | Mandatory | Value | Description |
---|---|---|---|
variableName | Example value:
| Field in the process data map whose value (or list of values) is checked with the regular expression. | |
resultVariableName | Example value:
| Field in the process data map where the result of the validation is saved as Boolean ("true" when regex matches, "false" if not). | |
regex | Example value:
| The regular expression, which the field value must match. | |
variableMustExist | - | Valid values (Boolean):
| If true, validation fails if map has no entry for the variable described in variableName. |
delimiter | - | Example values:
| Can be defined if the value in variableName contains a list which is separated with a delimiter. For example: "value1; value2; value3" If delimiter is defined, the value is treated as a list of multiple values, and every value is validated. |
trim | - | Valid values (Boolean):
| If true, any whitespace before and after the value in variableName is removed before validation. Example:
|
caseSensitive | - | Valid values (Boolean):
| If true, the validation does differentiate between lowercase and uppercase characters. |