̽»¨´óÉñ

When provisioning user accounts to and from ̽»¨´óÉñ, like an HR integration or SaaS application, use expressions to transform user data. Expressions allow you to go beyond one-to-one attribute mapping and enable the conversion of user data into your preferred format or ensure you are getting the needed information.

Prerequisites

• Basic understanding of attribute mapping concepts
• Familiarity with the Go programming language syntax (though not required for basic usage)

Important Considerations

• SCIM Implementation - the specific syntax and supported functions for SCIM expressions can vary slightly between different identity providers and SCIM implementations. Always refer to the SP's documentation
• Testing - it's crucial to test your attribute mappings and SCIM expressions thoroughly to ensure that user data is being transformed and mapped correctly. Be aware of potential errors, such as accessing non-existent attributes or using incorrect function arguments
• Complexity - while SCIM expressions offer great flexibility, it's important to keep them as simple and maintainable as possible. Complex expressions can be difficult to troubleshoot and understand
• Security - if your data source is user-provided, sanitize input to prevent template injection vulnerabilities

Overview

What are Expressions?

Expressions are rules or formulas used to manipulate and transform user data during the provisioning process. They allow you to dynamically create or modify user attributes, such as usernames, email addresses, etc., based on specific conditions or logic.

Why use Expressions?

Expressions bring a wealth of benefits to attribute mapping, significantly enhancing the flexibility and power of user provisioning and synchronization. Some of the key advantages:

• Data transformation and manipulation - converts data between different formats and combines multiple source attributes into a single target attribute. Can also be used to extract specific parts of an attribute
• Improved efficiency - automates data manipulation and formatting tasks, streamlining user provisioning and management
• Flexibility and customization - allows tailoring of data, so the right information is being sent
• Enhanced integration capabilities - enables you to integrate with a wider range of systems, even those with complex or unique data requirements
• Simplified management and maintenance - attribute mapping rules are defined in a central location within your identity management system, making it easier to manage and maintain them. This also simplifies troubleshooting as you can examine the expressions to understand how data is being transformed and identify potential problems

How do I create an Expression?

By understanding the basics, you can effectively use Go templates to create expressions for dynamic and flexible attribute mapping tables. Go templates let you create reusable text patterns that can be plugged in to different pieces of information to create customized text outputs, like SCIM attributes. Consult the for a complete list of functions and features.

1. Actions:
   • Actions are enclosed in double curly braces {{ ... }}. They represent operations to be performed
   • Examples: {{ .FirstName }}, {{ lower .Email }}, {{ if .IsActive }}...{{ end }}
2. Data Access:
   • The dot (.) represents the current data item
   • You can access attributes using the dot notation, e.g., .AttributeName
   • For nested data, use multiple dots, e.g., .User.Address.City
   • Index access is done via the index function, like index .Array 0
3. Functions:
   • Go templates provide built-in functions for string manipulation, arithmetic, and more. Examples include:
     • lower: Converts a string to lowercase
     • upper: Converts a string to uppercase
     • split: Splits a string into a slice of strings
     • index: Accesses an element in a slice or map
     • len: Returns the length of a string, slice, or map
     • substr: Gets a substring
     • sub: subtracts two numbers
   • You can also define custom functions if needed
4. Control Structures:
   • Go templates support control structures, like if, else, range for conditional logic and iteration
     • Example: {{ if .IsAdmin }}Admin User{{ else }}Regular User{{ end }}
     • Example: {{range .Items}}{{.}}{{end}}
5. Pipelines:
   • Pipelines allow you to chain functions together
   • The output of one function becomes the input of the next
     • Example: {{ .Name | upper | substr 0 3 }} (converts the name to uppercase and then gets the first three characters)
6. String Literals:
   • Strings are enclosed in double quotes. For example "Hello"

Configuring Expressions

Workflow

1. Identify Your Data Source - in the attribute mapping table, determine the source of the data you want to map. This would typically be an attribute, a value or structured data returned in the API response.
2. Identify the Destination - in the attribute mapping table, determine in which ̽»¨´óÉñ user attribute you want the value of the expression stored.
3. Add an Expression - select the three ellipses next to the mapping for which you want to use an expression and select Add Expressions.
4. Enter the Go Template Expressions - within the target attribute columns of your table, use the {{ ... }} syntax to embed Go template expressions.
5. Reference Source Attributes - use the dot notation (.) to reference attributes from your data source. For example, .FirstName would access the "FirstName" attribute.
6. Apply Functions - use built-in Go template functions to manipulate data. For instance, {{ lower .Email }} converts the "Email" attribute to lowercase.
7. Evaluate the Template - your system or application will evaluate the Go template expressions using the provided data, generating the final attribute mapping.
8. Test and Validate - use the Preview Mapping function to verify that the attribute mapping produces the desired results.

To add an Expression

1. Log in to the .
2. Go to USER AUTHENTICATION > SSO Applications
3. Select your application from the Configured Applications list and select the Identity Management tab.
4. Go to the User Schema Attribute Mapping section.
5. Add or select the user attribute to which you would like to create an expression.
6. Click the attribute's ellipsis and then click Add Expression.
7. In the Add Expression window, enter your desired expression in the Enter Expression field.
8. Click Save.

9. If you would like to preview the new mappings, select Preview Mappings.
10. After receiving the desired results, click update and then click Save at the bottom of the page.

To edit an Expression

1. Click the ellipsis next to the user attribute to which you would like to edit the expression.
2. Click Edit Expression and enter the updated expression for the user attribute.

3. Click Save in the Edit Expression window.
4. If you you like to preview the new mappings, select Preview Mappings.
5. If you are receiving the desired results, click update and then click Save at the bottom of the page.

Using the User Schema Preview

1. At the bottom of the attribute mappings, select the Preview Mappings link.
2. The User Schema Preview window will show the translation for the first user.
3. If you would like to see a preview of a different user, add a filter that will result in that user.

4. Click Update Preview.
5. If the preview is returning the desired result, click Close.
6. Click update and then click Save at the bottom of the page.

Expression Examples

Expression: {{.preferred_name}}

Result: xyz

Explanation: Takes the value of the preferred_name field from the user record

---

Expression: {{or .preferred_name .username}}

Result: hello.world

Explanation: Using the or operation, the expression takes the user's preferred_name value, if populated, or username value. Since the user's preferred_name value is null (""), the result is "hello.world"

---

Expression: {{.first_name}} {{.last_name}}

Result: Hello World

Explanation: Takes the values of the first_name and last_name fields from the user's record, concatenates them and separates them with space.

---

Expression: {{if .is_manager}}Engineering Manager{{else}}Engineer{{end}}

Result: Engineering Manager

Explanation: Using the if condition, there are two possible results. If the user is a manager, their job title will be "Engineering Manager". If the user is not a manager, the job title would be "Engineer". Since the user's record has "is_manager": true, their job title is "Engineering Manager".

---

Expression: {{(index .eligible_paid_time_off 1).policy_name}}

Result: Paid Time Off Policy

Explanation: Using the index function, this expression retrieves the policy_name of the second eligible paid time off policy from the list of policies. (indexing typically starts at 0 so 1).policy_name refers to the second element in the policy list)

Expression: {{(index .eligible_paid_time_off 0).policy_name}}

Result: Sick Policy

Explanation: Using the index function, this expression retrieves the policy_name of the first eligible paid time off policy from a list of policies.

---

Expression: {{(index (index .jobs 0).compensations 1).rate}}

Result: 85000.00

Explanation: The expression navigates through a nested data structure:

1. index .jobs 0) accesses the first job from a list of jobs
2. .compensations 1) accesses the second compensation from the list of compensations associated with that job
3. .rate extracts the rate value from that second compensation

---

Expression: {{eq .phone .mobile}}

Result: false

Explanation: The eq function compares the "phone" and "mobile" values. Since they are not the same, the result is "false".

---

Expression: {{range .customFieldGroup.codeFields}}{{if (eq .itemID "1500091404_30")}}{{ .nameCode.codeValue }}{{end}}{{end}}

Result: Uniform Size

Explanation: The expression uses a range loop and a conditional if statement to extract a specific codeValue from a nested data structure:

1. .range .customFieldGroup.codeFields accesses each element in codeFields where the loop will execute the code within the range block, and the current element will be represented by the dot (.)
2. if (eq .itemID "1500091404_30") checks if the itemID of the current codeField is equal to the string "1500091404_30".
3. .nameCode.codeValue retrieves and outputs the value of the codeValue field