Integrate with Rippling

Automatically provision, update and deprovision users in JumpCloud from Rippling using the Identity Management integration. Leverage this integration to centralize user lifecycle and identity management in JumpCloud based on user data coming from Rippling. Save time and avoid mistakes, as well as potential security risks, related to manually creating and updating users.

Add options to use existing connector or create new one.

Configuring the Identity Management Integration

To generate a Rippling API Token

1. Log in to Rippling as an admin for your organization.
2. Select Tools >Developer.
3. Navigate to API Tokens.
4. Click Create API Token.
5. Enter a clear, descriptive name (e.g., JumpCloud Integration)
6. Click Continue.
7. Specify the specific permissions (scopes) you want to give based on the data you want to import from Rippling to JumpCloud: 

• companies.read
• departments.read
• employment-types.read
• job-codes.read
• job-dimensions.read
• legal-entities.read
• levels.read
• teams.read
• users.read
• work-locations.read
• workers.read
• workers.sensitive.personal.read

7. Click Save.
8. Copy the API Token and store it securely. 

To create a new custom application in JumpCloud

1. Log in to the JumpCloud Admin Portal.

2. Go to User Management > HR Directories.
3. Select Create Custom Application
4. Click Next
5. Select Import users from this app (Identity Management) if you don’t want users to log in to Rippling with their  JumpCloud credentials or 
6. Click Next
7. Enter the name for your integration in the Display Label field
8. Optionally, if you don’t want the integration to show for your users, you can uncheck the Show this application in User Portal option.
9. Click Save Application
10. Click Configure Application

To configure the custom API import integration

1. Expand Configuration settings
2. Select Custom API Import for API Type
3. Select or enter the following:
   • Use mTLS: Leave unchecked
   • Authentication method: Select Bearer Token
   • Base URL: Enter https://rest.ripplingapis.com
   • Enter the API Token generated in the previous section
   • Endpoint configuration:
     • Resource location: results
     • Endpoint path: /workers
   • Pagination:
     • Pagination Type: Cursor-based
     • Cursor Count Parameter: limit
     • Cursor Field Parameter: cursor
     • Cursor Field JSON Path: next_link
4. Check the box for Cursor field is a link 
5. Click Test Connection to verify credentials and the configuration.
6. If the connection test was successful, the Attribute Mapping section will be displayed. 
7. Update Endpoint path to /workers?expand=user,manager,employment_type,department,legal_entity,custom_fields to have more complete user information included in the sync.

User Schema Attribute Mapping

1. Expand the Attribute Mapping section
2. Update the first section of the User Schema Attribute Mapping section:
   • Unique id: id
   • User Status status
   • Inactive Status Values: INIT, HIRED, TERMINATED

Mapping Table

Use the example response from the List Workers endpoint in the Rippling API documentation to determine which attributes you want to map. Some suggestions are provided in the table below. 

Required Mappings

JumpCloud Attribute	Service Provider Attribute	Notes
Company Email	work_email
Username	work_email	There is logic that automatically extracts everything before the ‘@’ in the email address and sets that as the username

Optional Mappings

JumpCloud Attribute	Service Provider Attribute	Notes
Display Name	{{ or .user.name.preferred_given_name .user.name.given_name }} {{ or .user.name.preferred_family_name .user.name.family_name }}
First Name (suggested)	{{ or .user.name.preferred_given_name .user.name.given_name }}	Expression that will store the person’s preferred given (first) name if populated. Otherwise, it will store the person’s legal first name.  To use an expression, click the more option at the end of the field (the stacked ellipses) and select “Add Expression”
Last Name (suggested)	{{ or .user.name.preferred_family_name .user.name.family_name }}	Expression that will store the person’s preferred family (last) name if it is populated. Otherwise, it will store the person’s legal family (last) name. To use an expression, click the more option at the end of the field (the stacked ellipses) and select “Add Expression”
Middle Name	user.name.middle_name
Alternate Email (suggested)	personal_email
Location (suggested)	location.type
Manager Email (suggested)	manager.work_email
Employee Identifier (suggested)	number
Employee Type (suggested)	employment_type.label
Job Title (suggested)	title
Work Phone	{{range .user.phone_numbers}}{{if (eq .type “WORK”)}}{{ .value}}{{end}}{{end}}	Expression that searches the phone_numbers array in the user object for the work phone number and stores it if populated.
Company (suggested)	{{ or .legal_entity.company.doing_business_as_name .legal_entity.company.legal_name}}	Add Expression OR type the name of your company
Department (suggested)	department.name
Work Cell Phone	{{range .user.phone_numbers}}{{if (eq .type “MOBILE”)}}{{ .value}}{{end}}{{end}}	Expression that searches the phone_numbers array in the user object for the mobile phone number and stores it if populated.
Work Country	country
Home State	{{range .user.addresses}}{{if (eq .type “HOME”)}}{{ .region}}{{end}}{{end}}	Expression that searches the addresses array in the user object for the region value of user’s home address and stores it if populated.
Home City	{{range .user.addresses}}{{if (eq .type “HOME”)}}{{ .locality}}{{end}}{{end}}	Expression that searches the addresses array in the user object for the locality value of user’s home address and stores it if populated.
Home Country	{{range .user.addresses}}{{if (eq .type “HOME”)}}{{ .country}}{{end}}{{end}}	Expression that searches the addresses array in the user object for the country value of user’s home address and stores it if populated.
Home Street Address	{{range .user.addresses}}{{if (eq .type “HOME”)}}{{ .street_address}}{{end}}{{end}}	Expression that searches the addresses array in the user object for the street address value of user’s home address and stores it if populated.
Home Postal Code	{{range .user.addresses}}{{if (eq .type “HOME”)}}{{ .postal_code}}{{end}}{{end}}	Expression that searches the addresses array in the user object for the postal code value of user’s home address and stores it if populated.

Expressions

You can use expressions to manipulate the information before storing it in JumpCloud. Read Use Expressions in Custom API Import Integrations to learn more about expressions.  

To preview Mappings 

Use this option to see the values being returned from Rippling and what values will be set in JumpCloud. 

1. Click Preview Mappings
2. Add query parameters supported by Rippling to return certain records and click Update Preview.
   • For example, enter filter=work_email+eq+'your.name@company.com' to do the preview for a specific user
3. Click Close
4. Edit the mappings as needed
5. Repeat these steps until the results meet your requirements

To activate the Integration

Once you are satisfied with the attribute mappings, click Activate. 

Importing Users

To verify the Integration

Perform a filtered manual import

1. Expand the Import Users section 
2. Check the box for Apply advanced filters on import (optional)
   • If you want to test by importing a specific users, append the following to the value in the Import Filter field: filter=work_email+eq+'your.name@company.com'
     • Replacing the example email address with the actual email address of the user you want to import.
     • Reference the List Workers API documentation for a complete list of filters you can use. 
3. Click Start Manual Import
4. Select the last option View and select specific new users to import (updates not supported)
5. Click Continue
6. Select a new user to import
7. Click Import
8. Verify the user was imported and had all the attributes you mapped
9. Follow the steps above and choose the other import options to do manual bulk imports

Perform a filtered scheduled import

Once you are comfortable with how the integration is working, you can enable the scheduled sync. 

1. Expand the Import Users section 
2. If you haven’t already, add the import filters
   • If you want to test by importing a specific users, append the following to the value in the Import Filter field: filter=work_email+eq+'your.name@company.com' to bring in a specific user
     • Replacing the example email address with the actual email address of the user you want to import
     • Reference the List Workers API documentation for a complete list of filters you can use
3. Toggle the Schedule hourly imports of users and user updates from SAML2.0 (disabled) to enable hourly imports.
4. If you want to receive an email every time the import runs, check the box for Receive summary email after each scheduled import:
   • If you prefer not to get so many emails, the import results can be accessed by clicking the Import Results link, from the Scheduled User Import Errors (past 24 hours) widget on the Home Page, or in Directory Insights

Importing New Users and Updates

To import users with the JumpCloud Admin Portal

1. Create a new application or select it from the Configured Applications list.
2. Select the Identity Management tab and expand the Import Users section.
   
3. There are several settings available for importing users from your custom application to JumpCloud.

Configuring User Import Settings

1. Allow reactivation of users on update for manual and scheduled imports - results in the user state changing from Suspended to Active in JumpCloud when a user is terminated in the SP.
2. Apply Advanced Filters on import (optional) - see your SP's API documentation for available filters.
3. Start Manual Import - kicks off the process flow for doing an immediate and one-time import of users from the SP to JumpCloud. 
4. Import Results - takes you to Directory Insights for User Imports.
5. Scheduled Imports (hourly) - disabled by default for all new connectors. The first scheduled import will start within an hour after the new connector is saved. Scheduled imports will then run at the same time every hour as the initial scheduled import.

6. Receive summary email after each scheduled import -results in user import complete emails being sent after each hourly import.

Starting a manual user import

1. Expand the Import Users section and click Start Manual Import.
2. Select one of the following options: 
   • Import new users and user updates
   • Only import new users
   • Only import user updates
   • View and select specific new users to import (updates not supported)

3. Click Continue.
4. If you selected the View and select specific new users to import (updates not supported).
   • Select the users you want to import.

5. The count of users to be imported will show at the bottom left hand of the list. If this is correct, click Import. 
6. Review the information in the results modal.
7. Click one of the tiles to navigate to the Users page, User Groups page, or Device Groups page or close the modal.​

8. You will receive a User Import Complete email with a summary of the import results and a link for downloading a copy of the import results.
9. You can now connect users to all their JumpCloud resources. Learn more in the Authorize Users to an SSO App and Connect New Users to Resources articles.

To import users with the JumpCloud API

1. Get the application ID for your integration. There are 2 ways:
   • Retrieve the application ID from the JumpCloud Admin Portal:
     • Log in to JumpCloud Admin Portal.
     • Go to USER AUTHENTICATION > SSO Applications.
     • Open your custom application by clicking on it.
     • Note the ID from the URL which is just before “/details”: https://console.jumpcloud.com/#/sso/{222220da1f777fbe7502cde}/details
   • Retrieve the application ID by making a GET /applications request:

curl command example:   

2. To do a manual import, make a POST /applications/{application_id}/import/jobs request using the application ID from the preceding steps.

curl command example for importing new users and user updates with reactivation of users allowed:

curl command example for importing only user updates:

3. To run scheduled hourly imports:

curl command that allows reactivation, sends an advanced import filter, and sends the user import complete email after the hourly sync occurs:

Updating the Custom API Connector

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications and open the Rippling application by clicking on it from the list.
3. Select the Identity Management tab.
4. Make the desired changes in the Configuration Settings section.
5. Click Update.

Removing the Integration

To deactivate the IdM Integration

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Search for the application that you’d like to deactivate and click to open the configuration window. 
4. Click Actions, Deactivate IdM and then click confirm.

To deactivate the SSO Integration or Bookmark

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Search for the application that you’d like to deactivate and click to open its details panel. 
4. Select the SSO or Bookmark tab.
5. Scroll to the bottom of the configuration.
6. Click Deactivate SSO or Deactivate Bookmark. 
7. Click save. 
8. If successful, you will receive a confirmation message.

To delete the application

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Search for the application that you’d like to delete.
4. Check the box next to the application to select it.
5. Click Delete.
6. Enter the number of the applications you are deleting
7. Click Delete Application.
8. If successful, you will see an application deletion confirmation notification.

Troubleshooting