Using the Custom Attributes Field in Torii Actions

Some actions in Torii support a Custom Attributes field, which allows you to update advanced or non-standard user information in third-party applications - such as Google Workspace, Microsoft Entra ID, and others.

This article explains when and how to use this field, what to look out for, and how to avoid common mistakes.

What Is the Custom Attributes Field?

The Custom Attributes field gives you additional flexibility by allowing you to define extra user properties using key-value pairs. These are included in the API request sent to the third-party application.

You can use Custom Attributes to update data that isn’t available in the standard fields Torii provides. Examples include:

• An external employee ID
• A list of alternate emails
• Custom metadata for your organization
• Structured user objects like phone numbers or addresses

What You Should Know Before Using Custom Attributes

Anyone using this field should feel confident to do so - but there are a few important things to understand before configuring it:

✅ Understand the Third-Party App’s API

The field interacts directly with the third-party app’s API, so it's important to understand:

• What fields the API supports (e.g., phones, otherMails, externalId)
• What format the data should be in (e.g., string, list (array), or JSON object)
• Whether sending partial data might overwrite existing values

📘 Use the Third-Party API Documentation

The best way to ensure your configuration is correct is to consult the third-party app’s official API reference. A few examples:

• Google Workspace Directory API – Update User
• Microsoft Graph API – Update User

This will help you understand:

• The correct field names (used as keys)
• The expected structure and data types for each field

How to Use the Custom Attributes Field

Key-Value Format

• Key: Always a flat string (no nesting or dot notation). This is the name of the field you want to update.
• Value: Can be one of several types, depending on the API:
  • String
  • Boolean (true / false)
  • Null
  • Array
  • JSON object

Examples

Here are some examples of valid configurations using different data types:

In the Torii UI:

• Key = phones
• Value = [{"type": "work", "number": "+1 555-1234", "primary": true}, {"type": "home", "number": "+1 333-4321"}]

Things to Be Aware Of

1. Custom Attributes Override Predefined Fields

If you enter a key that already exists in the predefined fields of the action (e.g., department, address), your custom value will override the value from the predefined field. Only do this when you intentionally want to override default behavior.

2. Arrays May Overwrite Existing Data

When updating fields that expect multiple values - such as phones, addresses, or emails-you must include all values you want to preserve.

If you only send part of the array, the third-party system may delete existing data.

❌ Risky:

"phones": [{"number": "+1 555-999-0000"}]

This may remove other phone numbers already on the profile.

✅ Safer:

"phones": [
  {"type": "work", "number": "+1 555-999-0000", "primary": true},
  {"type": "home", "number": "+1 555-567-8901"}
]

🔍 How to Identify This in Third-Party API Documentation

When reviewing third-party API docs, look for indications of how updates are handled - especially whether fields are fully replaced or updated individually. Below are two examples:

From Google Workspace Directory API – Update User:

From Microsoft Graph API – Update User (field-specific behavior):

3. Personalization Tokens

If you're using personalization tokens as values (like {"displayName": " [Trigger.User.First-name] "}), they could break the JSON format and will only be identified at runtime.

For example:

If the token value is: fir"stName, your value becomes:

{"displayName": "fir"stName"}

This is invalid JSON and will cause an error at runtime, not during configuration.

Best Practices

• ✅ Use predefined fields when possible - they’re easier to manage and safer.
• ✅ Always test your custom attributes with a single user before applying to many.
• ✅ Validate the field names and structure with the third-party API documentation.
• ✅ When updating lists (like phones or emails), include the full list to avoid losing data.
• ✅ Be careful when overriding standard fields to avoid unexpected changes.

Example: Using Custom Attributes with Microsoft Entra ID

When working with Microsoft Entra ID (formerly Azure Active Directory), you can use the Custom Attributes field to update extension fields such as onPremisesExtensionAttributes.

For example, if you want to update extensionAttribute2 with a value from another system (e.g., a user's department in Okta), you can use the following configuration:

• Key: onPremisesExtensionAttributes
• Value:

  {"extensionAttribute2": "[Trigger.User.Details.Okta-Department]"}

This is a common use case for syncing metadata between systems, and Entra ID supports updating these extension attributes through the Microsoft Graph API.

Summary

The Custom Attributes field gives you advanced control over what user data is sent to third-party systems. It’s especially helpful when your organization needs to update fields that are not available in the standard Torii action.

You don’t need to be deeply technical to use it - but you do need to understand how the API expects data to be structured. When in doubt, refer to the third-party documentation or test carefully before scaling.