# SailPoint UKG Pro Core HCM Connector Documentation > UKG Pro Core HCM Connector Documentation # Documentation # Connecting SailPoint and UKG Pro Core HCM To connect SailPoint with UKG Pro Core HCM, 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](). 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](). - **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]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 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](). 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. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](). 4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default. - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system. - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source. 8. Select **Save**. ## Connection Settings Provide the information required to connect to the UKG Pro Core HCM managed system. > [!NOTE] > > At this time, the connector only supports [Basic Authentication]() to authenticate connections to UKG Pro Core HCM with REST APIs. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() 1. Enter the UKG Pro Core HCM API's **Base URL** used to connect to the Core module of the UKG Pro source. For example: ```text https://xyz.ultipro.com ``` > **Note** > > The UKG Pro Core HCM source only supports the UKG Pro Core HCM module. 2. Select **Basic Authentication** for the **Authentication Type**, and provide the supporting authentication credentials. 1. **Service Account Username** - The UKG Pro Core HCM web service account user with required permissions 2. **Service Account Password** - The password for the UKG Pro Core HCM service account 3. **Customer API Key** - The Customer API Key assigned in the UKG Pro Core HCM system 3. Select **Save**. ## Aggregation Settings Configure optional settings to define which accounts the connector fetches during aggregation processes. You can configure account filters based on employee status and hire and termination dates. Configure the aggregation timeout and the number of records fetched during a single page. Lastly, you can enable Delta Aggregation. Configure your aggregation settings as required, then select **Save**. For more information about Aggregation, refer to [Loading Account Data](). ### Filter Settings Configure the filters to define the scope of account aggregation. > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() #### Employee Statuses to Aggregate The connector aggregates only Active employees by default. Enter any additional employee status values to include in aggregation along with Active in the Employee Statuses to Aggregate field. Press Enter on your keyboard to add the status to the list of employee statuses to include. You can only add the following employee statuses: - Leave of absence - On strike - Released/laid off - Suspended > [!NOTE] > > **Notes** > > - Terminated is not a valid status value for this list. To aggregate Terminated employees, use [Aggregate Terminated Employees](<#aggregate-terminated-employees>). > - The status values entered will be treated as case-insensitive. However, SailPoint recommends that you enter the status values in their correct case as they are configured in the `enabledEmployeeStatus` parameter. > [!IMPORTANT] > > The Active status should not be removed as that's the default aggregation status. If you remove it, account aggregation will fail with validation error. #### Aggregate Future Hires Enable **Aggregate Future Employees** to aggregate future employees ahead of their hire date. Then in the **Future Offset** field, enter the number of days in advance of their hire date to aggregate future employees. Leave the field blank to aggregate all future employees regardless of their hire date. #### Aggregate Terminated Employees Enable **Aggregate Terminated Employees** to include terminated employees in aggregation. Then in the **Termination Offset** field, enter the number of days in the past you want to aggregate terminated employees. Leave the field blank to aggregate all terminated employees regardless of their termination date. ### Additional Settings Configure additional settings which define how the aggregation process runs. > [!NOTE] > > **Screenshot** > > [![Additional Settings]()]() #### Aggregation Timeout Enter the **Aggregation Timeout** duration in seconds. When the connector receives no response from the managed system for the configured duration, the aggregation fails. #### Page Size In the **Page Size** field, enter the number of records to aggregate in a single page when iterating over large datasets. The default value is 200 records and the maximum value is 200 records. ### Delta Aggregation Enable **Delta Aggregation** to aggregate new accounts or accounts that have changed since the last aggregation process. ## Provisioning Settings Configure optional settings related to provisioning operations. The configurations made in the **Provisioning Settings** tab apply to all provisioning operations. The provisioning tab provides options for you to enter the API country code settings. You can also set the approval rule used for business approval processes. For information on the available provisioning policy attributes, refer to [Provisioning Employee Attributes](). > [!NOTE] > > **Screenshot** > > [![Provisioning Settings]()]() ### Country Code Settings To set the country code settings: 1. In the **Home Phone Country Code** field, enter the UKG API country code associated with the employees' home phone attribute values. For example, you can enter `CAN` for Canada or `IND` for India. The default setting is `USA`. 2. In the **Work Phone Country Code** field, enter the UKG API country code associated with the employees' work phone attribute values. For example, you can enter `CAN` for Canada or `IND` for India. The default setting is `USA`. 3. Select **Save**. ### Approval Rule Settings To set the approval rule: 1. In the **Approval Rule** dropdown menu, select one of the following as required: - **Bypass Approval** - Do not route transactions through approval, and force updates. - **Standard** - Follow the standard configured workflow. 2. Select **Save**. ## Additional Configuration Parameters Add the following entries or modify the existing entries using the REST API. > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ### enabledEmployeeStatus String parameter which defines the available employee account statuses. This parameter is a comma-separated list of employee statuses. The employees that have a status from this list will be considered enabled in SailPoint. If the status is any other value, the identity account is considered disabled. The default value for this parameter is `Active,Leave of absence,On strike`. ```text ``` > [!NOTE] > > The values in this list are not case-sensitive. However, SailPoint recommends that you enter the status values and use them as if they are case-sensitive. ### conUKGProApiRetrySleepTimeSeconds If the connector encounters a `Too Many Requests` error (HTTP response status code 429) while establishing an API connection, the connector will pause for the duration (in seconds) configured in this parameter before reattempting to establish an API connection. > [!NOTE] > > If the `Retry-after` response header is available, the connector will read the value from there. The default value is `5`, so the connector pauses for five seconds if it encounters a Too Many Requests error, then makes another attempt at establishing the connection with the API. ```text ``` ### conUKGProApiRetryMaxAttempts If the connector encounters a `Too Many Requests` error (HTTP response status code 429) while establishing an API connection, the connector will reattempt to establish an API connection. This parameter defines how many times the connector should attempt the connection before the connection fails. The default value is `3`, so the connector attempts to establish an API connection three times. If the third attempt fails, the connection fails. ```text ``` ### retryableErrorCodes If the connector encounters the specified error status codes `[409, 504]` during account aggregation, the connector will perform a retry as configured in this source configuration attribute. ## 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]() in the SailPoint SaaS documentation. # Integrating SailPoint with UKG Pro Core HCM > [!NOTE] > > **Integration** > > This is an integration and requires additional licensing or subscriptions to utilize it. For more information, contact your customer success manager. This document is designed to give specific information about the requirements and field definitions needed to get a working instance of a UKG Pro Core HCM source in SailPoint. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features SailPoint UKG Pro Core HCM Connector supports the following features: #### Account Management - Aggregate UKG Pro Core HCM employee records - Delta aggregation to sync changes from UKG Pro Core HCM - Additional schema attribute support - Aggregation of records based on future hire, terminations, and various employment status - Update account provisioning #### Additional Supported Features - Support for aggregation and update of custom user defined attributes - Support for aggregation of platform configuration attributes ## Supported Managed Systems The UKG Pro Core HCM connector supports the following versions of the UKG Pro Core HCM API: - UKG Pro Core HCM API version 1 - UKG Pro Core HCM API version 2 for Platform Configuration Fields Data API > [!NOTE] > > The UKG Pro Core HCM connector uses the UKG Pro Core HCM's REST API, which is independent of the UKG Pro Core HCM system version. ## Prerequisites - Configure at least one virtual appliance cluster and successfully test the connection. For instructions, refer to the [Virtual Appliance Reference Guide](). - Have a UKG Pro Core HCM Web Service Account, Password, and Customer API Key for connecting to the given URL of the UKG Pro Core HCM tenant. > [!NOTE] > > For more information on UKG Pro Core HCM permissions, refer to [Required Permissions](<#required-permissions>). ## Required Permissions This section describes the permissions required for the UKG Pro Core HCM application on the UKG Pro Core HCM managed system. Permissions for authentication type: - For Basic authentication, refer to [Basic Authentication](<#basic-authentication>). ### Basic Authentication This topic provides the details of the required permissions for the Basic Authentication Type. #### Creating a Web Service Account UKG Pro APIs using Basic Authentication are only accessible with a web service account. UKG Pro users with system administrator rights can create web service accounts by going to **System Configuration \> Security \> Service Account Administration**. Like user accounts, web service accounts require a unique username, password, and granular permissions. Permissions can be granted to one or more resource or method. Go to the Service Account Administration page and add a new service account user. When you select **Save**, the password displays. > [!IMPORTANT] > > Copy the password as it will not be shown again. For more information, refer to the [UKG Developer Hub](). #### Permissions to UKG Pro Core HCM Web Service Account User Modify the Web Service User to associate the required permissions for the following UKG Pro Core HCM Web Services: | Operation | Comments | | --- | --- | | TEST CONNECTION | The service account must have the View role for the Company Configuration Integration Web Service. | | ACCOUNT AGGREGATION | The service account must have View role for the Employee Export Web Service. | | ACCOUNT AGGREGATION (for additional attributes) | To aggregate Job Configuration Details, Location Configuration Details, and Org level (½/¾) Details, the service account must have the View role for the Company Configuration Integration Web Service. To aggregate Employment Details, User Defined Field Details, and Platform Configuration Field Details, the service account must have View role for the Personnel Integration Web Service. | | PROVISIONING | The service account must have the View role for the Company Configuration Integration Web Service AND View and Add roles for the Personnel Integration Web Service. | # Provisioning ## Provisioning Employee Attributes The UKG Pro Core HCM connector can provision the employee attributes listed on this page. > [!CAUTION] > > The UKG Pro Import API writes data to the UKG workflow tables, not the UKG production tables. This means that even if the provisioning transaction is successful, the fields will be updated into workflow tables in the source. So, if you then immediately run a task that depends on the production tables being updated, it might return older data which doesn't reflect the recent changes. > > UKG Pro recommends that you call the API for employee data aggregation eight (8) times daily and no more frequently than three (3) hours between calls. For more details, refer to [Changes By Date]() in the UKG documentation. > > Note that SailPoint does not maintain this document, and it is subject to change without notice. > [!IMPORTANT] > > Employee data updates occur for the home company or the component company where the employee is actively employed. The connector fetches the employee's component company code internally then passes it to the UKG Pro Import API. If the employee has active employment in multiple component companies at a time, the most current recent employment component company data will be updated. | Attribute Name | Description | | --- | --- | | firstName | String. The employee's first name | | lastName | String. The employee's last name | | middleName | String. The employee's middle name | | preferredName | String. The employee's preferred name | | workPhone | String. The employee's work phone number. In order to update the employee's work phone, the work phone country code is required. The work phone country code can be provided as part of the provisioning plan or configured directly from the [Provisioning Settings]() tab. | | homePhone | String. The employee's home phone number. In order to update the employee's home phone, the home phone country code is required. The home phone country code can be provided as part of the provisioning plan or configured directly from the [Provisioning Settings]() tab. | | suffix | String. The employee's name suffix | | prefix | String. The employee's name prefix | | emailAddress | String. The employee's email address | | alternateEmailAddress | String. The employee's alternative email address | | personnelUDF.\\\ | String. The employee's Personnel User-Defined Field (UDF). Replace `` with the respective field name. For example, `personnelUDF.Participated in Health Screening`. For more information, refer to [Aggregate User-Defined Fields](). | | companyUDF.\\\ | String. The employee's Company User-Defined Field (UDF). Replace `` with the respective field name. For example, `companyUDF.Retention Score`. For more information, refer to [Aggregate User-Defined Fields](). | | internationalUDF.\\\ | String. The employee's International User-Defined Field (UDF). Replace `` with the respective field name. For example, `internationalUDF.country`. For more information, refer to [Aggregate User-Defined Fields](). | ## Attribute Synchronization and Target Mapping You must get the source ID before synchronizing attributes. The source ID is displayed at the end of the source's URL in your browser. The source ID is also known as the source's front-end ID for a source. For more information, refer to [Best Practices: Attribute Sync](). > [!IMPORTANT] > > Ensure that the attribute you are going to add for synchronization is added on the source schema attribute list. Additionally, ensure that the proper identity attribute is mapped with it. ### Get and Set the Attribute Synchronization Mapping Use the [Update Attribute Sync Config]() API to set the attribute. 1. Make a GET request with the following command: ```text GET /sources//attribute-sync-config ``` 2. Set the target value with the following command: ```text PUT /sources//attribute-sync-config ``` The following is an example body for the supported attribute: ```json { "attributes": [ { "enabled": true, "displayName": "att_email", "name": "email", "target": "emailAddress" }, { "enabled": true, "displayName": "UKGLastName", "name": "ukglastname", "target": "lastName" }, { "enabled": true, "displayName": "UKGFIRSTNAME", "name": "ukgfirstname", "target": "firstName" }, { "enabled": true, "displayName": "MiddleName", "name": "middlename", "target": "middleName" }, { "enabled": true, "displayName": "preferredName", "name": "preferredname", "target": "preferredName" }, { "enabled": true, "displayName": "suffix", "name": "suffix", "target": "suffix" }, { "enabled": true, "displayName": "prefix", "name": "prefix", "target": "prefix" }, { "enabled": true, "displayName": "ukgalternateEmailAddress", "name": "ukgalternateemailaddress", "target": "alternateEmailAddress" } ], "source": { "type": "SOURCE", "id": "ee2c32b5fa794cd98f702122ac649d9d", "name": null } } ``` # 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]() for more information. > - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified. The UKG Pro Core HCM connector uses the following default correlation and object configurations. The source schema is used to configure objects returned from the connector. When a connector is called, the schema is supplied to the methods on the connector interface. This connector currently supports the following objects: - Account - Objects used when building identities' link objects. > [!NOTE] > > SailPoint does not recommend changing the value of the Account ID. The connector aggregation logic is based on the provided default value of the Account ID. Refer to [Account ID](<#default-account-id>) for more information. ## 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]() for more information. ### Default Account ID SailPoint requires that certain attributes remain in your configuration. These attributes are referred to as *account IDs*. > [!CAUTION] > > Changing the attribute marked as the account ID after aggregating accounts can result in duplicate accounts being created. To avoid this, either reset the accounts on this source before editing the account ID attribute or edit the account ID attribute before aggregating accounts. > > To resolve issues caused by changing account IDs, reconfigure them to their default values. The following table lists the default account IDs for this connector: | Account ID | Schema Object Type | | --- | --- | | employeeId | Account | ### Default Account Attributes The UKG Pro Core HCM connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified. The attributes listed on this page make up the default account schema in the UKG Pro Core HCM connector. > [!NOTE] > > The UKG Pro Core HCM connector can aggregate additional attributes in addition to the ones in the default account schema. For more information, refer to [Aggregate Additional Employee Schema Attributes](<#aggregate-additional-employee-schema-attributes>). | Attribute Name | Description | | --- | --- | | employeeId | The employee's ID | | firstName | The employee's first name | | lastName | The employee's last name | | fullName | The UKG API doesn't provide the employee's full name by default. If you want to aggregate the employee's full name as a single attribute, add a new schema attribute named `fullName`. The connector code returns the employee's full name formatted based on other name attributes as follows: ` ., .` For example, consider an employee whose name attributes are as follows: `lastName` - Shrader, `suffix` - Sr., `firstName` - Scott, `middleName` - Michael. When you aggregate the `fullName` attribute, the connector returns the following: `Schrader Sr., Scott M.` | | preferredName | The employee's preferred name | | emailAddress | The employee's primary email address | | countryCode | The employee's work location country code | | languageCode | The employee's work location language code | | employeeNumber | The employee's employee number | | personId | Person ID of the person data associated with the employee | | userIntegrationKey | The employee's user integration key | | companyName | The employee's home company name | | companyId | The employee's home Company ID | | supervisorId | The employee's supervisor ID | | salaryOrHourly | Indicates the salary pay category for an employee | | fullTimeOrPartTime | Indicates the work category; full time or part time | | isActive | Boolean attribute which indicates if the employee is active in the system | | workLocationCode | The employee's work location code | | jobCode | The employee's primary job code | | projectCode | The employee's assigned project code | | orgLevel1Code | The employee's organization Level1 Code | | orgLevel2Code | The employee's organization Level2 Code | | orgLevel3Code | The employee's organization Level3 Code | | orgLevel4Code | The employee's organization Level4 Code | | middleName | The employee's middle name | | workPhone | The employee's work Phone Number | | homePhone | The employee's home Phone Number | | employeeAddress1 | The employee's work location address 1 | | employeeAddress2 | The employee's work location address 2 | | city | The employee's work location city | | state | The employee's work location state | | zipCode | The employee's work location zip code | | terminationDate | The employee's termination date | | hireDate | The employee's hire date | | supervisorName | The employee's supervisor's name | | suffix | The employee's name suffix | | prefix | The employee's name prefix | | alternateEmailAddress | An alternate email address for the employee | | gender | The employee's gender | | employeeStatus | The employee status in the system | | employeeType | Indicates the employee's employment type | | emplStatusStartDate | The effective date of the employee's last employee status | | dateInJob | The effective date in the employee's last job | | dateOfLastHire | Date on which the employee was hired | | jobGroupCode | The employee's primary job group code | | alternateJobTitle | An alternate job title for the employee | ## Aggregate Platform Configuration Fields The UKG Pro Core HCM connector can aggregate platform configuration fields related to various classes during full and delta aggregation. The connector can aggregate fields related to the following classes: - Address - Person - Employee - PhoneNumber - Employment - Location - Job - OrgLevel1 - OrgLevel2 - OrgLevel3 - OrgLevel4 - Contacts To aggregate platform configuration fields related to a specific class, add the user-defined attribute name to the UKG Pro Core HCM schema, and associate it with its class. The syntax is as follows: ```text platformConf.. ``` For example, to aggregate an `Essential` attribute under the `Employee` class, you add the following to the schema: ```text platformConf.Employee.Essential ``` > [!NOTE] > > To get a list of the platform configuration field names related to a specific class in the UKG Pro Core HCM system, add `platformConf..allFields` to the account schema. By adding this attribute to the account schema, the source returns a list of all non-null platform configuration attributes in that class and their associated keys during aggregation. Use this list as a guide to help you add the platform configuration attributes to the account schema. > [!IMPORTANT] > > If the class name is omitted (for example, `platformConf.`) the fields related to the Employment class will be aggregated. This is to support backward-compatibility with earlier released versions. SailPoint recommends that you always add the class name to the schema attribute name for better readability. ## Aggregate User-Defined Fields The UKG Pro Core HCM connector can aggregate user-defined employee fields during full and delta aggregation. The connector aggregates the user-defined fields into the account schema. ### User-Defined Personnel Fields To aggregate user-defined personnel fields, add the user-defined attributes to the UKG Pro Core HCM schema with `personnelUDF.` set as the prefix for each one. The syntax is as follows: ```text personnelUDF. ``` For example: ```text personnelUDF.Participated in Health Screening ``` > [!NOTE] > > To get a list of the user-defined personnel field names in the UKG Pro Core HCM system, add `personnelUDF.allFields` to the account schema. Adding this attribute to the account schema returns a list of all user-defined personnel attributes and their associated keys during aggregation. Use this list as a guide to help you add the user-defined personnel attributes to the account schema. ### User-Defined Company Fields To aggregate user-defined company fields, add the user-defined attributes to the UKG Pro Core HCM schema with `companyUDF.` set as the prefix for each one. The syntax is as follows: ```text companyUDF. ``` For example: ```text companyUDF.Retention Score ``` > [!NOTE] > > To get a list of the user-defined company field names in the UKG Pro Core HCM system, add `companyUDF.allFields` to the account schema. Adding this attribute to the account schema returns a list of all user-defined company attributes and their associated keys during aggregation. Use this list as a guide to help you add the user-defined company attributes to the account schema. ### User-Defined International Attributes To aggregate user-defined international fields, add the user-defined attributes to the UKG Pro Core HCM schema with `internationalUDF.` set as the prefix for each one. The syntax is as follows: ```text internationalUDF. ``` For example: ```text internationalUDF.country ``` > [!NOTE] > > To get a list of the user-defined international field names in the UKG Pro Core HCM system, add `internationalUDF.allFields` to the account schema. Adding this attribute to the account schema returns a list of all user-defined international attributes and their associated keys during aggregation. Use this list as a guide to help you add the user-defined international attributes to the account schema. ## Aggregate Additional Employee Schema Attributes Aggregate additional, predefined employee attributes from the UKG Pro Core HCM connector. After aggregation, these attributes are added to the default employee schema attributes in the connector's account schema. The additional attributes you can aggregate are related to an employee's primary job configuration, organizational level, and location. The connector can aggregate properly configured attributes from the UKG Pro Core HCM schema. ### Primary Job Functions To aggregate an employee's primary job related details, create a primary job function attribute in the UKG Pro Core HCM schema by adding the attribute name with `job.` as the prefix. The syntax is as follows: ```text job. ``` The following primary job related functions are supported: > [!NOTE] > > The prefix and user-defined schema attribute name are case-sensitive. | Serial Number | Job Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 1 | jobCode | `job.jobCode` | string | | 2 | countryCode | `job.countryCode` | string | | 3 | title | `job.title` | string | | 4 | isActive | `job.isActive` | Boolean | | 5 | jobFamilyCode | `job.jobFamilyCode` | string | | 6 | longDescription | `job.longDescription` | string | | 7 | jobEEOCategory | `job.jobEEOCategory` | string | | 8 | jobGroup | `job.jobGroup` | string | | 9 | flsaTypeCode | `job.flsaTypeCode` | string | ### Organization Level To aggregate an employee's organization level (½/¾) details, create an organization level attribute in the UKG Pro Core HCM schema by adding the attribute name with `orgLevel.` as the prefix. Replace `` with the employee's actual organizational level. The syntax is as follows: ```text orgLevel. ``` For example: ```text orgLevel1.lastYearBudgetSalary orgLevel3.longDescription ``` The following organization level related attributes are supported: > [!NOTE] > > The prefix and user-defined schema attribute name are case-sensitive. | Serial Number | Organization Level Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 1 | budgetGroup | `orgLevel.budgetGroup` | string | | 2 | code | `orgLevel.code` | string | | 3 | currentYearBudgetFTE | `orgLevel.currentYearBudgetFTE` | string | | 4 | currentYearBudgetSalary | `orgLevel.currentYearBudgetSalary` | string | | 5 | description | `orgLevel.description` | string | | 6 | glSegment | `orgLevel.glSegment` | string | | 7 | isActive | `orgLevel.isActive` | Boolean | | 8 | lastYearBudgetSalary | `orgLevel.lastYearBudgetSalary` | string | | 9 | level | `orgLevel.level` | string | | 10 | levelDescription | `orgLevel.levelDescription` | string | | 11 | reportingCategory | `orgLevel.reportingCategory` | string | ### Work Location To aggregate an employee's work location details, create work location attributes in the UKG Pro Core HCM schema by adding the attribute name with `workLocation.` as the prefix. The syntax is as follows: ```text workLocation. ``` The following work location related attributes are supported: > [!NOTE] > > The prefix and user-defined schema attribute name are case-sensitive. | Serial Number | Work Location Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 1 | locationCode | `workLocation.locationCode` | string | | 2 | description | `workLocation.description` | string | | 3 | isActive | `workLocation.isActive` | Boolean | | 4 | addressLine1 | `workLocation.addressLine1` | string | | 5 | addressLine2 | `workLocation.addressLine2` | string | | 6 | city | `workLocation.city` | string | | 7 | state | `workLocation.state` | string | | 8 | zipOrPostalCode | `workLocation.zipOrPostalCode` | string | | 9 | countryCode | `workLocation.countryCode` | string | | 10 | locationGLSegment | `workLocation.locationGLSegment` | string | ### Employment To aggregate an employee's employment details, create employment related attributes in the UKG Pro Core HCM schema by adding the attribute name with `employmentDetails.` as the prefix. The syntax is as follows: ```text employmentDetails. ``` The following employment related attributes are supported: > [!NOTE] > > The prefix and employment schema attribute name are case-sensitive. | Serial Number | Employment Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 1 | leaveReasonCode | `employmentDetails.leaveReasonCode` | string | | 2 | leaveReasonDescription | `employmentDetails.leaveReasonDescription` | string | | 3 | companyCode | `employmentDetails.companyCode` | string | | 4 | workPhoneExtension | `employmentDetails.workPhoneExtension` | string | | 5 | workPhoneCountry | `employmentDetails.workPhoneCountry` | string | | 6 | jobChangeReasonCode | `employmentDetails.jobChangeReasonCode` | string | | 7 | supervisorFirstName | `employmentDetails.supervisorFirstName` | string | | 8 | supervisorLastName | `employmentDetails.supervisorLastName` | string | | 9 | isMultipleJob | `employmentDetails.isMultipleJob` | string | | 10 | termReason | `employmentDetails.termReason` | string | | 11 | terminationReasonDescription | `employmentDetails.terminationReasonDescription` | string | ### Additional Employment Attributes The following additional `employmentDetails.*` attributes are available in this VA-based connector: | Serial Number | Employment Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 12 | hireSource | `employmentDetails.hireSource` | string | | 13 | companyName | `employmentDetails.companyName` | string | | 14 | employeeID | `employmentDetails.employeeID` | string | | 15 | jobDescription | `employmentDetails.jobDescription` | string | | 16 | primaryJobCode | `employmentDetails.primaryJobCode` | string | | 17 | lastHireDate | `employmentDetails.lastHireDate` | string | | 18 | fullTimeOrPartTimeCode | `employmentDetails.fullTimeOrPartTimeCode` | string | | 19 | primaryWorkLocationCode | `employmentDetails.primaryWorkLocationCode` | string | | 20 | languageCode | `employmentDetails.languageCode` | string | | 21 | primaryProjectCode | `employmentDetails.primaryProjectCode` | string | | 22 | workPhoneNumber | `employmentDetails.workPhoneNumber` | string | | 23 | dateInJob | `employmentDetails.dateInJob` | string | | 24 | dateLastWorked | `employmentDetails.dateLastWorked` | string | | 25 | dateOfBenefitSeniority | `employmentDetails.dateOfBenefitSeniority` | string | | 26 | dateOfSeniority | `employmentDetails.dateOfSeniority` | string | | 27 | employeeTypeCode | `employmentDetails.employeeTypeCode` | string | | 28 | employeeNumber | `employmentDetails.employeeNumber` | string | | 29 | jobTitle | `employmentDetails.jobTitle` | string | | 30 | supervisorID | `employmentDetails.supervisorID` | string | | 31 | dateOfEarlyRetirement | `employmentDetails.dateOfEarlyRetirement` | string | | 32 | dateOfRetirement | `employmentDetails.dateOfRetirement` | string | | 33 | dateOfSuspension | `employmentDetails.dateOfSuspension` | string | | 34 | dateOfTermination | `employmentDetails.dateOfTermination` | string | | 35 | jobGroupCode | `employmentDetails.jobGroupCode` | string | | 36 | okToRehire | `employmentDetails.okToRehire` | string | | 37 | positionCode | `employmentDetails.positionCode` | string | | 38 | termType | `employmentDetails.termType` | string | | 39 | supervisorEmployeeNumber | `employmentDetails.supervisorEmployeeNumber` | string | | 40 | supervisorCOID | `employmentDetails.supervisorCOID` | string | | 41 | supervisorCompanyCode | `employmentDetails.supervisorCompanyCode` | string | ### Employment Job History To aggregate an employee's employment job history details, create employment job history related attributes in the UKG Pro Core HCM schema by adding the attribute name with `employmentJobHistoryDetails.` as the prefix. The syntax is as follows: ```text employmentJobHistoryDetails. ``` The following employment related attributes are supported: | Serial Number | Employment Job History Detail | Corresponding User-Defined Schema Attribute | Type | | --- | --- | --- | --- | | 1 | isJobChange | `employmentJobHistoryDetails.isJobChange` | Boolean | | 2 | fullTimeOrPartTime | `employmentJobHistoryDetails.fullTimeOrPartTime` | string | | 3 | isOrgchange | `employmentJobHistoryDetails.isOrgchange` | Boolean | | 4 | isOutsideGuidelines | `employmentJobHistoryDetails.isOutsideGuidelines` | Boolean | | 5 | isOutsideRange | `employmentJobHistoryDetails.isOutsideRange` | Boolean | | 6 | isSystem | `employmentJobHistoryDetails.isSystem` | Boolean | | 7 | isTransfer | `employmentJobHistoryDetails.isTransfer` | Boolean | | 8 | jobDescription | `employmentJobHistoryDetails.jobDescription` | string | | 9 | jobEffectiveDate | `employmentJobHistoryDetails.jobEffectiveDate` | string | | 10 | jobGroupCode | `employmentJobHistoryDetails.jobGroupCode` | string | | 11 | locationCode | `employmentJobHistoryDetails.locationCode` | string | | 12 | orgLevel1Code | `employmentJobHistoryDetails.orgLevel1Code` | string | | 13 | orgLevel2Code | `employmentJobHistoryDetails.orgLevel2Code` | string | | 14 | orgLevel3Code | `employmentJobHistoryDetails.orgLevel3Code` | string | | 15 | orgLevel4Code | `employmentJobHistoryDetails.orgLevel4Code` | string | | 16 | piecePayRate | `employmentJobHistoryDetails.piecePayRate` | string | | 17 | positionCode | `employmentJobHistoryDetails.positionCode` | string | | 18 | reasonCode | `employmentJobHistoryDetails.reasonCode` | string | | 19 | shiftCode | `employmentJobHistoryDetails.shiftCode` | string | | 20 | shiftGroupCode | `employmentJobHistoryDetails.shiftGroupCode` | string | | 21 | supervisorNameFirst | `employmentJobHistoryDetails.supervisorNameFirst` | string | | 22 | supervisorNameLast | `employmentJobHistoryDetails.supervisorNameLast` | string | | 23 | supervisorNameSuffix | `employmentJobHistoryDetails.supervisorNameSuffix` | string | | 24 | supervisorNotInList | `employmentJobHistoryDetails.supervisorNotInList` | Boolean | | 25 | systemId | `employmentJobHistoryDetails.systemId` | string | | 26 | integrationEffectiveDate | `employmentJobHistoryDetails.integrationEffectiveDate` | string | | 27 | projectCode | `employmentJobHistoryDetails.projectCode` | string | | 28 | jobTitle | `employmentJobHistoryDetails.jobTitle` | string | # Migrate VA-based Source to a SaaS Source Some sources that are connected to virtual appliance (VA) clusters can be migrated to SaaS connections. This ensures data (users and entitlements) remain intact and can maintains your source configurations like access profiles, roles, password settings, and correlation configurations when switching from a VA cluster to a SaaS connection. To migrate a source from a VA-based source to a SaaS source, you will provide configuration details on a draft version of the source before publishing the source. > [!NOTE] > > - You must have an Admin or Source Admin user level to migrate a source. A draft version of the source is created. As your migration process is in progress the live source will continue to work as it is. For more information on the UKG Pro Core HCM SaaS connector, refer to the [UKG Pro Core HCM SaaS Supported Features](). ## Important Considerations Before Migrating - You do not need to edit additional configurations (other than connection credentials) to migrate the source. - If your source migration is in progress, please do not make any configuration changes to your live source as those can be overwritten once you apply the migration your draft version. - Once you've gone ahead with your migration, it can't be rolled back. Your source is permanently migrated to a SaaS source. - Any preview operations or configuration changes on the draft source will not impact the live source until you apply the migration. ## Migrating Sources To migrate your source, complete the following: 1. Go to **Admin \> Connections \> Sources**. 2. Select or edit the VA-based source you want to migrate. 3. Open the source configuration, and select **Migrate to SaaS**. 4. When prompted, select **Continue**. A draft version of the source is created. The live source will continue to work. 5. Select **Connection Settings**. 6. Re-enter encrypted configuration details. For example, you might need to re-enter the Client Secret, Password, Refresh Token, Personal Access Token (PAT), or Certificates to migrate from the VA cluster to the SaaS connection. > **Important** > > Avoid editing the other configuration options in the draft source. 7. Select **Review and Test**. 8. Select **Test Connection**. 9. (Optional) Select **Accounts**. If you successfully tested your connection in **Review and Test**, you can select **Preview** to display a subset of accounts from the application that will be mapped to SailPoint identities. This can help ensure you are accurately connecting identity data from the application with SailPoint identities. 10. (Optional) Select **Entitlements**. If you successfully tested your connection in **Review and Test** and your source type supports entitlement type configuration, you can select **Preview** to view a preview of entitlements using the current configuration settings. 11. When you've finished reviewing your changes and successfully tested your connection, select **Apply Migration**. Your changes will be applied to the live source and the draft source will be deleted. ## Viewing Source Migration Status You can view the status and creation date of draft sources. 1. Go to **Admin \> Connections \> Sources \> Source Migration Status**. 2. Select **Source Migration Status**. 3. To view or edit the draft source, select **Actions** ![]() **\> Preview** on the draft source. 4. To delete the draft source, select **Actions** ![]() **\> Delete** on the draft source. # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Update operations fail with "transaction status is queued" message Attempts to provision update operations fail with a message similar to the following: ```text [openconnector.ConnectorException: Update operation for NAMEADDRESS failed. Error messages are [Transaction status is Queued. It has been staged to staging table but has not yet been sent to the import plug-in].] ``` **Resolution** - Increase the poll timeout value. The poll timeout value is in seconds. The default value is `10` seconds. Add the following entry into the source XML using the REST APIs: **Attribute** - `conProvResultPollTimeout` **Value** - `` > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ## An error occurs while querying the UKG Pro Core HCM server While provisioning employee attribute updates, you may see the following error message: ```text [ InvalidResponseException ] [ Possible suggestions ] An error occurred while querying the UKG Pro Core HCM server. Make sure the connection parameters are valid and correct. [ Error details ] ] ``` **Resolution** - Ensure that the URL value uses HTTPS. The UKG Pro import API doesn't support HTTP protocol. ## Requests are denied due insufficient authorization During any transactions, you see the following error message: ```text [ InvalidRequestException ] [ Possible suggestions ] You don't have authorization to view this page. [ Error details ] Authorization has been denied for this request. ``` **Resolution** - Ensure that the service account has the correct permissions. For more information, refer to [Required Permissions]().