# SailPoint Ivanti Cherwell Connector Documentation

> Ivanti Cherwell Connector Documentation

# Documentation

# Connecting SailPoint and Ivanti Cherwell

To connect SailPoint with Ivanti Cherwell, perform the following tasks:

## Adding the Source in SailPoint

To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs.

> [!IMPORTANT]
>
> By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration.

**To configure a new source:**

1. Sign in to SailPoint.
2. Go to **Admin \> Connections \> Sources**.
3. Select **Create New**.
4. Search for the connector by entering the name in the search box, and then select **Configure**.
5. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters.
6. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters.
7. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](<https://documentation.sailpoint.com/saas/help/sources/index.html#assigning-a-source-owner>).
8. Under **Connection Type**, select **Direct Connection** or **Flat File**.

   - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
   - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable.
9. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source.
10. (Optional) Select a governance group to grant its members [source](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#source-sub-admin-user-level>) or [role](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#role-sub-admin-user-level>) sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](<https://documentation.sailpoint.com/saas/help/common/users/governance_groups.html>).
11. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](<https://documentation.sailpoint.com/saas/help/setup/identity_profiles.html>).
12. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there.

## Connection Settings

Provide the information required for the connector to connect and interact with the source.

1. Enter the **Base URL** of the Ivanti Cherwell instance that you are integrating with. For example, `https://CSMSiteName.cherwell.com`
2. The **Authentication Type** is default selected as OAuth2.
3. Select your **Grant Type**:

   > **Password**
   >
   > Select the **Grant Type** as Password.
   >
   > > **Screenshot**
   > >
   > > [![Connection Settings - Password Grant Type](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/connection_settings_password.png>)](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/connection_settings_password.png>)
   >
   > 1. Enter the **Token URL** for URL for generating access token. For example, `https://CSMSiteName.cherwell.com/CherwellAPI/token`.
   > 2. Enter **Client ID** for OAuth2 authentication.
   > 3. Enter **Client Secret** for OAuth2 authentication.
   > 4. Enter the **Username** with Service Account username.
   > 5. Enter **Password** with Service Account user password.

   > **Refresh Token**
   >
   > Select the **Grant Type** as **Refresh Token**.
   >
   > > **Screenshot**
   > >
   > > [![Connection Settings - Refresh Token Grant Type](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/connection_settings_refresh_token.png>)](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/connection_settings_refresh_token.png>)
   >
   > 1. Enter the **Token URL** for URL for generating access token. For example, `https://CSMSiteName.cherwell.com/CherwellAPI/token`.
   > 2. Enter the **Client ID** for OAuth2 authentication.
   > 3. Enter a valid **Refresh Token**.
4. Select **Save**.

## Aggregation Settings

For more information about aggregation, refer to [Loading Account Data](<https://documentation.sailpoint.com/saas/help/accounts/loading_data.html>).

### Filter Settings

Configure the following filter parameters on the aggregation settings page.

> [!NOTE]
>
> **Screenshot**
>
> [![Aggregation Filter Settings](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/aggregation_filter_settings.png>)](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/aggregation_filter_settings.png>)

1. Select the **Account Login ID Type** to set the scope of login ids included in account aggregation processes. For example, `Internal`
2. Select the **Managed Account Type** to manage the type of account. For example, `Users`

### Customer Account Disable Status

> [!NOTE]
>
> **Screenshot**
>
> [![Customer Account Disable Status](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/customer_disable_status.png>)](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/img/customer_disable_status.png>)

1. Enter the Ivanti Cherwell customer account statuses which indicates a Disable status to the connector.

   > **Note**
   >
   > Whenever you define Ivanti Cherwell Customer status in the application, only those defined statuses will be set as disabled and remaining as Enabled. For more information, refer to [Disable Status Mapping](<https://documentation.sailpoint.com/connectors/ivanti_cherwell/va/help/status_mapping.html>).
2. Select **Save**.

## Review and Test

Perform a test to confirm the connection to SailPoint.

1. Go to **Review and Test**.
2. Confirm that the entries in each field are correct.

   If you note any mistakes, return to the section and make corrections.
3. Select **Test Connection**.

## SailPoint Application Onboarding

SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface.

For more information, refer to [Application Onboarding](<https://documentation.sailpoint.com/saas/help/ai/app_onboarding/index.html>) in the SailPoint SaaS documentation.

# Integrating SailPoint with Ivanti Cherwell

The Ivanti Cherwell connector offers seamless connectivity to the Cherwell ITSM solution, enabling aggregation and provisioning of two distinct Cherwell user types: 'users' &amp; 'customers'. This integration enables robust user access management and governance in the Cherwell System.

This document is designed to give specific information about the requirements and field definitions needed to getting a working instance of an Ivanti Cherwell source.

> [!NOTE]
>
> To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes](<https://community.sailpoint.com/release-notes/saas>) page.

## Supported Features

The Ivanti Cherwell connector supports the following features:

### Account Management

| Supported Features | User | Customer |
| --- | --- | --- |
| Account Aggregation | Yes | Yes |
| Refresh Account | Yes | Yes |
| Create Account | Yes | Yes |
| Update Account | Yes | Yes |
| Delete Account | Yes | Yes |
| Unlock Account | Yes | No |
| Enable/Disable Account | No | Yes |
| Change Password | Yes | No |
| Add Entitlement | Yes | No |
| Remove Entitlement | No | No |

### Account Group Management

Manages Cherwell Security Groups as Account-Group

- Aggregation, Refresh

## Supported Managed Systems

The Ivanti Cherwell connector supports the following managed systems:

- Cherwell Service Management (cloud) version 2023.1.1
- Cherwell Service Management (cloud) version 10.4.0

## Prerequisites

- Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
- The user should have valid Ivanti Cherwell instance with Admin access to have client\_id generated. For more information, refer to [Obtaining API Client IDs](<https://help.cherwell.com/bundle/cherwell_rest_api_2023_1_help_only/page/content/system_administration/rest_api/csm_rest_obtaining_client_ids.html>).
- Know the authentication option (OAuth 2.0 Authentication) to use for SailPoint to authenticate.
- SailPoint Ivanti Cherwell Connector uses rotating Refresh Tokens authentication from Cherwell. Ensure after the first utilization of the refresh token for a test connection with the connector, you save the new Refresh Token.

### Minimum Permissions Required

Security Group assigned to the service account requires View, Add, Edit and Delete permissions on the following Business Objects:

- Customer
- UserInfo

# Provisioning

The Ivanti Cherwell connector supports provisioning, allowing you to create and manage accounts and entitlements in Ivanti Cherwell directly from SailPoint.

**Prerequisite:** Your system is configured for provisioning.

When SailPoint provisions new accounts to the source, it uses the attributes on the **Create Account** page as instructions or a template for what to include in the account. This page is also referred to as the *provisioning policy*.

When new access is granted on a source where a user does not already have an account, SailPoint automatically includes account creation in the provisioning. This applies whether provisioning is started from an access request or from an automated role or lifecycle state assignment.

For direct-connect sources, SailPoint automatically creates the account from this configuration. If the source is not configured as a direct-connect source, SailPoint creates and assigns a provisioning task to the source owner and includes the values for the source owner to use in manually creating the account.

> [!IMPORTANT]
>
> This section describes the default **Create Account** configuration. SailPoint recommends that you work with Services to define a provisioning configuration specific to your company's needs. Be sure to verify large changes to the provisioning policy before implementation. Failure to do so might cause provisioning to fail.

## Default Create Account Attributes

| Account Attribute | Type | Generator | Description | Applicable to User/Customer |
| --- | --- | --- | --- | --- |
| accountType | String | Static | The account type of the User | Select either User/Customer |
| loginId | String | Identity Attribute - SailPoint User Name (uid) | The login ID of the User | User |
| password | String | Generator | The password of the User | User |
| Email | String | Identity Attribute - Work Email (email) | The email of the User/Customer | Both |
| FirstName | String | Identity Attribute - First Name (firstname) | The first name of the User/Customer | Both |
| LastName | String | Identity Attribute - Last Name (lastname) | The last name of the User/Customer | Both |
| FullName | String | Identity Attribute - Display Name (displayName) | The full name of the User/Customer | Both |
| Manager | String | Disable | The name of the manager of the User/Customer | Both |

> [!IMPORTANT]
>
> By default, the **accountType** is selected for the User. To use the **accountType** for Customer, it is recommended you must disable **loginId** and **password**.

# Schema Reference

The application schema is used to configure the objects returned from a connector.

> [!NOTE]
>
> - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.
> - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified.

The Ivanti Cherwell connector uses the following default correlation and object configurations.

## Default Correlation Configuration

Before you aggregate accounts from this source, you can map account attributes with their corresponding identity attributes based on your requirements.

You can customize the correlation configuration. Refer to [Assigning Source Accounts to Identities](<https://documentation.sailpoint.com/saas/help/accounts/correlation.html>) for more information.

When you first create the Ivanti Cherwell source, the default correlation mapping is:

| Account Attribute | Operation | Identity Attribute |
| --- | --- | --- |
| Email | Equals | Work Email (email) |
| FullName | Equals | Name (name) |

## Default Account Schema

Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location.

The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.

### Default Account Attributes

The Ivanti Cherwell connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified.

| Attribute Name | Description |
| --- | --- |
| RecID | The user's unique record ID |
| busObId | Ivanti Cherwell Business Object ID |
| busObRecId | Ivanti Cherwell Business Object Record ID |
| busObPublicId | Ivanti Cherwell Business Object Public ID |
| publicId | The user's Public ID |
| displayName | The user's display name |
| shortDisplayName | A shortened version of the user's display name |
| accountLocked | Indicates if the user account is locked |
| createDateTime | The date and time a user account was created |
| lastPasswordResetDate | The date the user's password was last reset |
| lastResetDateTime | The date the user was last reset |
| passwordNeverExpires | Indicates if the user's password expires |
| userCannotChangePassword | Indicates if the user cannot change their password |
| userMustResetPasswordAtNextLogin | Indicates if the user must change their password at the next login |
| ldapRequired | Indicates if the user account requires LDAP |
| CreatedBy | The name of the user who created the record |
| CreatedByID | The record ID of the user who created the record |
| LastModifiedDateTime | The date and time of the user account was last modified |
| LastModBy | The name of the user who modified the record |
| LastModifiedByID | The record ID of the user who modified the record |
| LastModByID | The record ID of the customer who last modified the record |
| LastModDateTime | The date and time a customer account was last modified |
| FullName | The user's full name. This is a display attribute. |
| NamePrefix | The user's prefix. For example, Mr. or Mrs. |
| NameSuffix | The user's suffix. For exampe, Jr. or Sr. |
| FirstName | The user's first name |
| MiddleName | The user's middle name |
| MiddleInitial | The user's middle initial |
| LastName | The user's last name |
| Status | The customer's status |
| Lastlogon | The date and time of the customer's last logon session |
| SiteID | The customer's site ID |
| SiteName | The customer's site name |
| StatusID | The customer's status ID |
| Department | The user's department |
| Phone | The user's phone number |
| PhoneType | The user's phone type |
| Email | The user's email address |
| AlternateEmailAddress | The customer's alternate email address |
| SecondaryEmail | The customer's secondary email address |
| CellPhone | The user's phone number |
| Mobile | The customer's mobile number |
| Manager | The user's manager's name |
| DefaultTeamName | The user's default team's name |
| DefaultTeamID | The user's default team's ID |
| LastModTimeStamp | The date and time of the last time the record was modified |
| Office | The user's office address |
| Title | The customer's title ID |
| EmployeeID | The user's employee ID |
| EmployeeStatus | The customer's employee status |
| SAMAccountName | The user's SAM account name |
| ManagerEmail | The user's manager's email address |
| StartDate | The user's vacation start date |
| EndDate | The user's vacation end date |
| PostalCodeZip | The user's postal code |
| HomePhone | The user's home phone number |
| PhoneDN | The customer's phone DN |
| MobileDN | The customer's mobile DN |
| Address | The user's street address |
| City | The user's city |
| Country | The user's country |
| CountryCode | The user's country code |
| ProvinceStateName | The user's Province/State |
| WebSite | The Website of the user |
| OwnedBy | The name of the customer's owner |
| OwnedByTeam | The team name of the customer's owner |
| LocationID | The customer's location ID |
| LanguageLocale | The user's language locale |
| LanguageName | The user's language name |
| TimeZoneOffset | The user's time zone offset |
| ManagerID | The user's manager ID |
| securityGroupId | The name of the security group that the user belongs |
| accountType | The user's account type |

## Default Entitlement Attributes

Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements](<https://documentation.sailpoint.com/saas/help/access/entitlements.html>) for more information.

> [!CAUTION]
>
> Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations.

### Default Security Group Attributes

The Ivanti Cherwell connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups.

| Attribute Name | Description |
| --- | --- |
| groupId | Unique Group ID of the Security Group |
| description | The description of a Security Group |
| groupName | The display name for a security group. This is a display attribute. |

# Disable Status Mapping

If any changes required in the mapping, change the default values in Status Mapping as mentioned in the following table:

| Ivanti Cherwell Customer Status | Identity Security Cloud Status |
| --- | --- |
| Active | Enabled |
| New | Enabled |
| Prehire | Enabled |
| Disabled | Disabled |
| Terminated | Disabled |