Use Expressions in JumpCloud

When exporting user accounts from JumpCloud to an external destination directory, like Active Directory or Google Workspace, using expression language (Expr) allows you to transform and manipulate user data into a specific format. This goes beyond simple one-to-one attribute mapping ensuring you have the precise data you want and need for your organization.

Prerequisites

• Basic understanding of attribute mapping concepts
• Familiarity with the Expr expression language

Important Considerations

• Implementation - the specific syntax and supported functions for expressions can vary slightly between different directories. Always refer to the external directory's documentation
• Testing - it's crucial to test your attribute mappings and expressions thoroughly to ensure that user data is being transformed and mapped correctly. Be aware of potential errors, such as mismatched data types, accessing null or non-existent attributes or using incorrect function arguments
• Simplicity - while 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

Overview

What are Expressions?

The primary use of an Expr language in attribute mapping is defining how data from a source (like a JSON object from an API call) is transformed and mapped to a destination (like a user object in an external database). The core of an Expr expression is a statement that assigns a source field's value to a destination field, i.e., source_field_path = destination_field.

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
• Security - ensures programs do not access unrelated memory or introduce memory vulnerabilities
• Terminating - prevents infinite loops

How do I create an Expression?

By understanding the basics, you can effectively use Expr to create expressions for dynamic and flexible attribute mapping. Consult the Expr documentation for more information.

Configuring Expressions

To add an Expression

1. Log in to the JumpCloud Admin Portal.
2. Go to DIRECTORY INTEGRATIONS > Active Directory/Cloud Directories.
3. Select YOUR INTEGRATION from the list and select the Attribute Mappings tab and click Edit. The Optional Mappings table will open.
4. Scroll to the bottom of the table, click +Add Attribute and then select Expression.
5. Enter the expression in the JumpCloud Attribute field
6. From the <Directory> Attribute dropdown, select the corresponding (destination) attribute.
7. Repeat these steps for additional attributes.
8. Click Preview Mappings to review the User Schema.

Expressions Examples

When mapping user attributes, define how data from a source object (like an API response) should be assigned to a destination object (like a user profile) by using different types of expressions:

Direct Mapping - the simplest expression when you assign a source attribute's value to a destination attribute using an operator:

• source.email_address - source attribute
• user.email - destination attribute

• user.email - destination attribute
• source.contact_info.first_name - source attribute

Conditional Logic - use a ternary operator (? :) to set a value based on a condition:

1. Assigning a role:

• user.role - destination attribute
• = - assignment operator that tells the system to assign the value on the right side of the equals sign to the field on the left
• source.is_admin - conditional check. It accesses the value of the is_admin field from the source data. This is typically a boolean value (true or false)
• ? - operator that introduces the ternary conditional or if/then/else statement. It checks the value of the preceding condition (source.is_admin)
• 'administrator' - "true" value. If the source.is_admin field is true, the string 'administrator' is assigned to user.role
• : - separates the true and false values
• 'standard_user' - "false" value. If the source.is_admin field is false, the string 'standard_user' is assigned to user.role

2. Setting a status based on a numeric code:

• user.status - destination attribute
• = - assignment operator that tells the system to assign the value on the right side of the equals sign to the field on the left
• source.user_status_code == 1 - conditional check. It compares the value of the user_status_code field from the source data to the number 1. The == is a comparison operator that returns a boolean (true or false)
• ? - operator initiates the ternary conditional or if/then/else statement. It evaluates the preceding condition
• 'active' - "true" value. If source.user_status_code is equal to 1, the string 'active' is assigned to user.status
• : - separates the true and false values
• 'inactive' - "false" value. If source.user_status_code is anything other than 1, the string 'inactive' is assigned to user.status

Data Transformation - expressions use built-in functions to manipulate data:

1. String Functions - combine or format text:

• user.fullName - destination attribute
• = - assignment operator that tells the system to assign the value on the right side of the equals sign to the field on the left
• source.firstName - first source field. It accesses the value of the firstName field from the source data, which is an object often named source or api_data
• + - concatenation operator. In this context, it's a string operator that joins the two strings on either side of it
• ' ' - string literal . It represents a single space character, which is inserted between the first and last names
• source.lastName - second source field. It accesses the value of the lastName field from the source data

• user.username - destination attribute
• = - assignment operator that tells the system to assign the value on the right side of the equals sign to the field on the left
• to_lower (...) - function that converts a string to all lowercase characters ensuring all usernames are stored in a consistent format
• source.login_id - source attribute. It's the original value, which in this case is a user's login ID, coming from the source system

Type Conversion - change a value's data type:

• user.hireDate - destination attribute
• = - assignment operator that tells the system to assign the value on the right side of the equals sign to the field on the left
• to_date(...) - built-in function in the expression language that takes a value—in this case, a timestamp—and converts it into a date object. This is essential for systems that don't recognize raw numeric timestamps as valid dates
• source.hire_date_timestamp - source attribute. It's the original value, which is a timestamp (a large number representing the seconds or milliseconds since a specific date, like January 1, 1970)

Array/List Access - pull a single item from a list:

• user.primaryGroup - destination attribute
• = - assignment operator, which sets the value of the destination attribute
• source.groups - source attribute
• [0] - index operator. In most programming languages, including Expr, [0] refers to the very first item in a list or array because lists are "zero-indexed"

Handling Missing Data - use the coalescing operator (??) to provide a default value if a source field is null or doesn't exist:

• user.department - destination attribute
• = - assignment operator, which sets the value of the destination attribute
• source.department - source attribute
• ?? - coalescing operator that checks if the value on its left (source.department) is null or empty
• 'Unassigned'- default value. If the coalescing operator finds that source.department is null or empty, it uses this string instead

• user.phone - destination attribute
• = - assignment operator, which sets the value of the destination attribute (user.phone field)
• source.mobile_number - primary source field. The expression first attempts to get the value from here
• ?? - coalescing operator. It checks if the value on its left (source.mobile_number) is null or empty
• source.home_phone - fallback source field. If the coalescing operator finds that source.mobile_number is null or empty, it uses the value of source.home_phone instead