# Data Format Considerations

Keep these general considerations in mind while preparing your data.

  • Ensure your data is in CSV or JSON format. The Bulk API does not support any other format.
  • Check for and remove duplicate records in your data. Bulk API recognizes duplicates based on the primary identifier in your payload. If duplicates are found, the Bulk API will load the first instance of the duplicate and mark the remaining instances as errors.
    • For employee load, the primary identifier is the User ID or the GUID (you will make the primary identifier selection while creating the job).
    • For OU load, the primary identifier is the OU ID.
  • Ensure that at a minimum you are including the required fields for your load type. You can get the list of required fields by looking at the required array in the schema response. Here's an example:
// Schema Response: Required Fields
...
...
"required": [ "ouRefId", "ouName" ],
...
...
  • Check the field size limitations for each field in the schema response and ensure that data in all fields in your payload are within those limits.
// Schema Response: Field Size
{
    "schema": {
        "properties": {
            "ouRefId": {
                "minLength": 1,
                "maxLength": 100,
                "trim": "leftRight",
                "title": "OU ID",
                "description": "Must be a unique ID for every OU. Both alpha and numeric characters are acceptable.",
                "type": "string"
            }
            ...
        }
        ...
    }
    ...
}
  • If your data contains special characters such as accents or umlaut UTF encode your payload.
  • Use User IDs (also known as User Refs) and OU IDs (also known as OU Refs) while associating records with users and OUs respectively. Ensure that the user and OU you are associating your record with is already present in the portal, is present in your payload, or is present in another import that's part of the same job. The Bulk API can resolve dependencies between data in multiple imports that are part of the same job.
  • For enumerated fields (dropdown, radio button, checkbox, multi-checkbox) use valid values as defined in the schema. Note that the index of the integer enums and the string enums aren't a one-to-one match. For example, in the below scenario, the value "1" may not be equal to "AUD". To avoid confusion, we recommend using the string enum values.
// Schema Response: Definitions
...
...
"definitions": {
    "currency": {
        "id": "currency",
        "anyOf": [
            {
                "enum": [1, 2, 3, 4, 5, 6],
                "type": "integer"
            },
            {
                "enum": ["AUD", "EUR", "GBP", "JPY", "KRW", "USD"],
                "trim": "leftRight",
                "caseSensitive": false,
                "type": "string"
            }
        ]
    }
}
...
...
  • If you are loading data into custom fields, you will need to work with your organization's administrator to ensure that the custom field is 'available' to the user associated with your OAuth 2.0 application. 'Availability' is the means by which administrators determine which segments of the active user population (including "service accounts" associated with OAuth 2.0 applications) will have access to custom fields, learning objects, tasks, etc.
  • You can specify the format of dates in your payload using the datetime_culture field in the request body of your create job request. This way you don't have to transform date fields from your source system as long as all the fields follow the same format. Your choices for date format are:
    • en-US: Month First. If your date 1 July 2017 is written as 7/1/2017 or 07-01-2017 or 7.1.2017
    • fr-FR: Day First. If your date 1 July 2017 is written as 1/7/2017 or 01-07-2017 or 1.7.2017
    • en-GB: Year First. If your date 1 July 2017 is written as 2017/7/1 or 2017-07-01 or 2017.7.1 (Year must have 4 digits)
  • You can specify the format of numeric fields in your payload using the number_culture field in the request body of your create job request. Your choices for number format are:
    • en-US: Decimals are separated with a dot ".". For example, 1,234.56 or 1234.56
    • fr-FR: Decimals are separated with a comma ",". For example, 1 234,56 or 1234,56
    • es-ES: Decimals are separated with a comma "," AND thousands are grouped with a dot ".". For example, 1.234,56
  • If your data contains time zone fields, review the guidance around using time zone IDs instead of time zone codes, especially if your data includes ambiguous time zone codes.

# Employee Loads

For employee loads, there are some additional considerations you should keep in mind:

  • For multi-checkbox fields send multiple values separated by a semi-colon. If you are updating an existing value, be sure to send the entire set of values that must be selected. For example, for a custom OU field called "Floor", if you provided 3;4;5 in a previous load and now you provide 4;5, then the Bulk API will remove 3.
  • When creating a new employee record, we recommend that you always include a manager's User ID. Else, the employee's manager will be set to the user associated with the OAuth 2.0 application when all of the following are true:
    • The backend setting for this feature is enabled (if you are unsure about this value, reach out to your administrator. If they are unsure, have them submit a case with Global Product Support to verify).
    • The manager field value is blank, unmapped or invalid.
  • The use_default_when_missing property lets you define what the Bulk API should do if your payload contains no values for certain optional fields. If set to true, the Bulk API will use the default value an administrator has configured for such fields. If set to false, the Bulk API will ignore any fields with no values. Note the following regarding this option:
    • This option only applies to existing employee records that you are updating using the Bulk API. For new employee records, the Bulk API will always use the default value for optional fields that don't have a value or have an invalid value.
    • This option only applies if the optional field is present in your payload but has no value. If an optional field is not present in your payload, the Bulk API will not touch that field.
  • The Bulk API does not support the hierarchy and branched dropdown custom field types.
  • For standard employee relationships, if the related employee's ID is invalid, the Bulk API will return an error. For custom employee relationships, if the related employee does not exist in the system, the Bulk API will add the record but skip that relation.
  • If you don't specify a username for an employee record, the bulk API will copy the user ID to the username field.
  • For new employees, the Bulk API will set the default password as defined through a backend setting. If you are not sure about the value for this backend setting, reach out to your administrator. If they are not sure either, please have them log a ticket with Global Product Support to verify. If this backend setting has no value, the API will not set a password for the employee. In such instances, the employee will need to reset their password using the 'Forgot Password' option.
  • The Bulk API currently does not support loading data to secure custom fields and sensitive personally identifiable (SPII) fields.

# OU Loads

Organizational Units (OUs) form the administrative foundation of Cornerstone. You can think of OUs as distinct information containers that capture, store and categorize all client data within the system. Cornerstone supports several standard OU Types and also allows clients to configure custom OUs. The Bulk APIs support the standard OU types (Cost Center, Division, Grade, Legal Entity, Location, Position) as well as custom OUs.

Position OU

For the Position OU, the Bulk API does not support loading data to the Related Jobs, Roles, Responsibilities, Attributes, Competencies, and Training fields.

# Custom OUs

While fetching the schema or creating a job for custom OUs, you will need supply the type_id. Each custom OU has a unique type_id. Follow these steps to retrieve the type_id for your OU. Note that you will only need to perform these steps once during your design phase.

  1. Make a GET call to the /services/api/x/bulk-api/v1/specification endpoint. Here's a cURL example you can use. Replace {corpname} with your portal's name and replace the token in the header with your OAuth2 access token.
   curl -X GET \
    https://{corpname}.csod.com/services/api/x/bulk-api/v1/specification \
    -H 'Authorization: Bearer ZWRnZQ:550aa86a8a11779ac9677d409c12941b1bdedf12af039661fbb4735098d8fcd6'
  1. A successful response includes an OpenAPI v3 compliant specification that you can copy and paste into an editor such as https://editor.swagger.io/.
  2. Scan through the response and find the CreateJobRequest definition. Within the definition, look for the imports.items object. Within the import.items object, look for your custom OU type and note the enum for type_id. The screenshot below explains how to traverse the specification to get to the type_id for a custom OU. Once you have the type_id for your custom OU, you can use it in your request to fetch the schema and create a job.

Bulk API job request example