Map User State for Custom API Import

When you import users from an HRIS or other REST API through a Custom API Import connector, you can set each user's JumpCloud user state with an expression. State mapping replaces the older inactive-status list and lets you decide when a user is Staged, Active, or Suspended based on status fields, dates, or other values in the provider response.

Use state mapping to:

• Stage users before their start date
• Suspend users when HR marks them terminated or when a termination date is reached
• Keep active users Active without a one-size-fits-all inactive list
• Combine more than one HR field or date in a single rule

This article explains how state mapping works, how to configure it, and how to write expressions with manageUserState.

Prerequisites

• A Custom API Import connector. See Integrate with HR Directories (Custom API Import).
• Basic familiarity with EXPR attribute mapping. See Use Expressions in JumpCloud.
• Familiarity with JumpCloud user states. See Manage User States.

Important Considerations

• State mapping uses an optional State import attribute. The source type for State must be Expression.
• The expression must return one of these values: ACTIVATED, SUSPENDED, STAGED, or UNSPECIFIED.
  • ACTIVATED maps to Active.
  • SUSPENDED maps to Suspended.
  • STAGED maps to Staged.
  • UNSPECIFIED means the expression does not set a state.
• Raw HR values such as Active, Terminated, 1, or true do not map automatically. Translate them in the expression.
• Reference provider fields with providerUser., for example providerUser.status.
• On create: If the expression returns ACTIVATED or STAGED, JumpCloud creates the user in that state. If it returns SUSPENDED, JumpCloud does not create the user. The user is skipped until a later import where the expression no longer returns SUSPENDED. If it returns UNSPECIFIED, JumpCloud uses the default from Identity Management > Users > Settings > Default User State.
• On update: JumpCloud follows the expression and updates the user's state.
• After you enable state mapping for your organization, configure a State expression before you rely on import for lifecycle changes. Without a state rule, JumpCloud does not apply the legacy inactive-status list.

How State Mapping Works

JumpCloud evaluates your State expression during import. The expression reads fields from the HRIS response and returns a JumpCloud user state string.

JumpCloud recommends manageUserState for most lifecycle rules. That helper checks ordered pairs of state and condition and returns the first match. If nothing matches, it returns UNSPECIFIED unless you add a final default.

For simple two-outcome rules, you can also use a direct ternary expression. For three or more outcomes, or for date-based lifecycle rules, use manageUserState.

Configuring State Mapping

Use the optional State row in your Custom API Import attribute mappings to control lifecycle state during import. You enter an expression, preview the result for sample users, then save the connector.

Adding a State Expression

To add or edit the State mapping on your Custom API Import connector:

1. Log in to the JumpCloud Admin Portal.

Important

If your data is stored outside of the US, check which login URL you should be using depending on your region. If your organization uses LDAP, RADIUS, or requires firewall allow list configuration, the Fully Qualified Domain Names (FQDNs) will also be region specific. See JumpCloud Data Centers for the URLs, FQDNs, and IP addresses.

2. Go to Identity Management > HR Directories.
3. Select your Custom API Import connector.
4. Open the import attribute mappings.
5. Locate the State row, or add State as an optional JumpCloud attribute.
6. Set the source type to Expression.
7. Enter your expression in the expression field.
8. Click Preview Mappings and confirm the state for sample users.
9. Click Save.

note

If JumpCloud migrated your connector from Inactive Status Values, review the generated manageUserState expression and update it if you need start dates, termination dates, or other lifecycle logic.

Writing State Expressions

Build the State expression so it reads fields from the HRIS response and returns a JumpCloud user state. Most admins use manageUserState for ordered lifecycle rules. For a simple two-outcome rule, you can use a direct ternary expression instead.

Using manageUserState

manageUserState checks ordered pairs of state and condition. JumpCloud returns the first state whose condition is true.

Signature: manageUserState(state, condition, state, condition, ...)

• Put the most specific conditions first.
• Add a final pair such as "ACTIVATED", true when you want a default state.
• If no condition matches and you do not add a default, the result is UNSPECIFIED.

Using Date Helpers

Use these helpers when your rule depends on start dates, termination dates, or other calendar values. Dates use the YYYY-MM-DD format in UTC.

Function	What it does	Example
today()	Returns the current UTC date as YYYY-MM-DD	today()
dateAfter(date, reference)	Returns true when date is after reference	dateAfter(providerUser.startDate, today())
dateBefore(date, reference)	Returns true when date is before reference	dateBefore(providerUser.terminationDate, today())
onDate(date, reference)	Returns true when date is on or after reference	onDate(today(), providerUser.terminationDate)

You can also use standard EXPR operators such as in, ==, &&, ||, ? :, nullOrEmpty, and notNullOrEmpty.

Expression Examples

Use these patterns as a starting point. Change field names and values to match your HRIS response. Reference provider fields with providerUser., for example providerUser.status.

Suspending terminated or inactive users

manageUserState("SUSPENDED", providerUser.status in ["Terminated", "Inactive", "Disabled"], "ACTIVATED", true)

• If the status matches an inactive value, JumpCloud sets the user to Suspended.
• For any other status, JumpCloud sets the user to Active.

Staging users before their start date

manageUserState("STAGED", dateAfter(providerUser.startDate, today()), "ACTIVATED", true)

• If the start date is in the future, JumpCloud sets the user to Staged.
• Otherwise, JumpCloud sets the user to Active.

Suspending users on the termination date

manageUserState("SUSPENDED", onDate(today(), providerUser.terminationDate), "ACTIVATED", true)

• If today is on or after the termination date, JumpCloud sets the user to Suspended.
• Otherwise, JumpCloud sets the user to Active.

Running a full lifecycle rule

manageUserState("STAGED", dateAfter(providerUser.startDate, today()), "SUSPENDED", onDate(today(), providerUser.terminationDate) || providerUser.status in ["Terminated", "Inactive"], "ACTIVATED", true)

• If the start date is in the future, JumpCloud sets the user to Staged.
• If the termination date is reached, or the status is terminated or inactive, JumpCloud sets the user to Suspended.
• Otherwise, JumpCloud sets the user to Active.

Using a simple two-outcome rule

providerUser.status in ["Terminated", "Inactive", "Disabled"] ? "SUSPENDED" : "ACTIVATED"

Use this pattern only for short rules with two outcomes.

tip

Start from the inactive-status example. Add date conditions if your HRIS includes start or termination dates.

Verifying Your Mapping

After you save the expression, confirm that import sets the expected user state before you rely on it for production syncs.

1. Click Preview Mappings and confirm the state for users with known HR statuses and dates.
2. Import a small set of users.
3. In Identity Management > Users, confirm each user's state matches your rule.