Web Services API Guide: Workforce Management Classic Web Services

Time Classic APIs

With UKG Pro’s Web Services, you can leverage your UKG ProTime Classic data for solving business application and integration needs. We provide two sets of web services for you to use with the Time Classic feature of UKG Pro Workforce Management Classic:

• Import APIs: Enable you to import data into Time Classic.
• Export APIs: Enable you to extract data from Time Classic.

This document describes how to use the Workforce Management Classic Web Services and is intended for individuals who are familiar with software development processes and Web Services technologies.

Authentication

Authenticate your API requests by providing a bearer token obtained from our Identity service. In order to authenticate, you must know your tenant alias, clientid, and secret.

• Flow Type: Client Credentials

URLs for U.S.

• Test: https://welcome-test.ultipro.com/signin/oauth2/t/ta/access_token
• Production: https://welcome.ultipro.com/signin/oauth2/t/ta/access_token

URLs for Canada

• Test: https://welcome-test.ultipro.ca/signin/oauth2/t/ta/access_token
• Production: https://welcome.ultipro.ca/signin/oauth2/t/ta/access_token

Where ta = Tenant Alias

• HTTP Method: POST

Header

Body

Response

• 200 OK with access token and expires_in (unit of time in seconds the token is valid for). This access token must be passed in an Authorization header for all subsequent API calls.

HTTP Header Name

Note: For assistance obtaining a token from Identity, open a support case via the UKG Community.

Root URL

Use the following root URLs for subsequent calls:

• https://wfm-gateway1.ultipro.com — Atlanta data center
• https://wfm-gateway2.ultipro.com — Las Vegas data center
• https://wfm-gateway.ultipro.ca — Toronto data center

If you are uncertain which data center you are assigned to, contact UKG for assistance.

Import APIs

Workforce Management Classic supports the importing of timesheet data through REST endpoints. Data can be imported as raw punches, paired punches, or time edits (entries). Data is appended to the timesheet day, and existing data is not removed.

Punch Import

The Punch Import API imports raw time punches. Employees are identified by either a badge number or a combination of their employee number and component company ID. These time punches are assigned to the timesheet when the punch processing job runs.

• URL: /time/v1/ta/import/punches
• HTTP Method: POST

Request Body:

{
  "coId": "E97P1",
  "employeeNumber": "777004551",
  "type": "EMPLOYEE_NUMBER",
  "punchType": "PUNCH",
  "timestamp": "2019-04-02T09:30-0400",
  "customLmValues": [{
    "laborMetricCode": "CAMPAIGN",
    "lmCustomValueType": "choice",
    "customChoiceCode": "PROMO"
  }]
}

Parameters:

Note:

• If type is “BADGE,” then badge is required.
• If type is “EMPLOYEE_NUMBER,” then coId and employeeNumber are required.
• If lmCustomValueType is "decimal," then decimal is required.
• If lmCustomValueType is "int," then integer is required.
• If lmCustomValueType is "text," then text is required.
• If lmCustomValueType is "choice," then customChoiceCode is required.

Punch Pairs Import

The Punch Pairs Import API imports time punches that have been paired by the external system and assigned to a date. Employees are identified by either a badge number or a combination of their employee number and component company ID. A pair of punches is expressed as IN/OUT times for work, breaks, and meals.

• URL: /time/v1/ta/import/punch-pairs
• HTTP Method: POST

Request Body:

{
  "coId": "E97P1",
  "employeeNumber": "777004551",
  "type": "EMPLOYEE_NUMBER",
  "date": "2019-04-02",
  "punchPairs": [{
    "startTime": "2019-04-02T09:30-0400",
    "endTime": "2019-04-02T11:30-0400",
    "punchPairType": "BREAK"
  }]
}

Parameters:

Note:

• If type is “BADGE,” then badge is required.
• If type is “EMPLOYEE_NUMBER,” then coId and employeeNumber are required.
• If lmCustomValueType is "decimal," then decimal is required.
• If lmCustomValueType is "int," then integer is required.
• If lmCustomValueType is "text," then text is required.
• If lmCustomValueType is "choice," then customChoiceCode is required.

Timesheet Edit Import

Entries to the timesheet other than punch data are recorded as "edits." The Timesheet Edit Import API imports these entries to the timesheet. Edits can be imported as duration edits, hourly time edits, currency edits, or numeric edits. For currency and numeric edits, the time code specified must be set with the proper data type in the time code setup.

• URL: /time/v1/ta/import/timesheet-edits
• HTTP Method: POST

Request Body:

{
  "coId": "E97P1",
  "employeeNumber": "777004551",
  "type": "EMPLOYEE_NUMBER",
  "date": "2019-04-02",
  "rejectDuplicates": false,
  "edits": [{
    "editType": "CURRENCY_EDIT",
    "value": 100.00,
    "timeCode": "OT",
    "payType": "S",
    "job": "Developer",
    "location": "NY",
    "project": "Project X"
  }]
}

Parameters:

Schedule Import

The Schedule Import API loads employee information by day and supports multiple shifts, where the shift is a defined period of the day. The API accepts imported data for time periods that can be edited. Employees can be identified by either a badge number assigned for the schedule date, or by their employee number and company ID combination.

URL:/time/v1/ta/import/schedule
HTTP Method: POST

Request Body

{
    "coId": "E97P1",
    "employeeNumber": "777004551",
    "type": "EMPLOYEE_NUMBER",
    "date": "2019-04-02",
    "scheduleTimes": [
        {
            "customLmValues": [
                {
                    "laborMetricCode": "CAMPAIGN",
                    "lmCustomValueType": "choice",
                    "customChoiceCode": "PROMO"
                }
            ],
            "startTime": "2019-04-02T09:30-0400",
            "endTime": "2019-04-02T11:30-0400"
        }
    ]
}

Parameters

Note:

• If type is “BADGE,” then badge is required. If type is “EMPLOYEE_NUMBER,” then coId and employeeNumber are required.
• If lmCustomValueType is "decimal," then decimal is required. If lmCustomValueType is "int," then integer is required. If lmCustomValueType is "text," then text is required. If lmCustomValueType is "choice," then customChoiceCode is required.

Time Classic Export APIs

Time Classic export APIs export data from a timesheet grouped by an employee’s timesheet day. Requests for an export must include a start and end date for exporting. The export can optionally be filtered by pay group. Three time exports are available:

• Timesheet Punches – Exports the punches grouped by timesheet day.
• Timesheet Details – Exports the calculated details grouped by timesheet day.
• Timesheet Day – Combines the Timesheet Punches export and the Timesheet Details export.

This workflow shows the sequence of calls to get the export data.

Data Export – Request Export

Data exports are started by posting a request to export data. An identifier is returned while the export data processes asynchronously.

URL:/time/v1/reporting/data-export
HTTP Method:POST

Request Body

{
    "type": "TIMESHEET_DAY",
    "fromDate": "2019-02-01",
    "toDate": "2019-02-01"
}

Parameters

Data Export – GET

After obtaining an export identifier, the export data cannot be obtained until processing has completed. Periodic calls to this endpoint can be done until the Status field reads "COMPLETE." It is recommended that the calls to this API be limited to once per minute for each export request until processing has completed.

URL: /time/v1/reporting/data-export/{id}

HTTP Method:GET

Parameters

Data Export – GET Export Data

Once processing is complete, the export data is available. Data is available by paging starting at 1. By default, the page size is 30 and the page number is 1. The page size maximum is 1,000.

URL:/time/v1/reporting/data-export/{id}/details
HTTP Method:GET

Parameters

Labor Metric APIs

Labor metric APIs import and export custom labor metrics and labor metric groups.

Labor Metric - Import Custom Choice

The Labor Metric Custom Choice Import API loads choices for Custom Labor Metrics. Choices may optionally include a start and end date to specify their active date range(s).

URL:/time/v1/ta/labor-metrics/custom-choices

HTTP Method: POST

Request Body

{
    "laborMetricCode": "CAMPAIGN",
    "updateChoiceDescription": false,
    "customChoices": [
        {
            "code": "custom1",
            "description": "custom description"
        },
        {
            "code": "custom2",
            "description": "custom description2",
            "startDate": "2020-01-01"
        },
        {
            "code": "custom3",
            "description": "custom description3",
            "startDate": "2020-02-01",
            "endDate": "2020-02-07"
        }
    ]
}

Parameters

Labor Metric - Export All

This API returns details for all labor metrics. Custom Labor Metrics may include the corresponding labor metric choices. Refer to the Labor Metric Export Choices API to explicitly return choices for a given labor metric.

URL: /time/v1/ta/labor-metrics
HTTP Method:GET

Parameters

Response Body

{
    "_embedded": {
        "resources": [
            {
                "id": "11e6e98d-aff8-b048-97d3-fb846d88d4c3",
                "code": "ORGLVL1",
                "name": "Region",
                "nameKey": "domain.orgLevel1.entity",
                "valueTypeNameKey": "domain.laborMetric.valueType.choice",
                "choices": []
            },
            {
                "id": "11e6e98d-aff8-b049-97d3-fb846d88d4c3",
                "code": "ORGLVL2",
                "name": "Division",
                "nameKey": "domain.orgLevel2.entity",
                "valueTypeNameKey": "domain.laborMetric.valueType.choice",
                "choices": []
            },
            { 
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/?page=1&per_page=30"
        },
        "first": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/?page=1&per_page=30"
        },
        "last": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/?page=1&per_page=30"
        }
    },
    "page": {
        "size": 30,
        "totalElements": 10,
        "totalPages": 1,
        "number": 1
    }
}

Labor Metric - Export

This API returns details for the specified labor metric ID. Custom Labor Metrics may include the corresponding labor metric choices. Refer to the Labor Metric Export Choices API to explicitly return choices for a given labor metric.

URL: /time/v1/ta/labor-metrics/{id}
HTTP Method:GET

Parameters

Response Body

{
    "id": "11e83904-4784-f1ca-b6f6-6c96cfdd4b6d",
    "code": "CAMPAIGN",
    "name": "Campaign",
    "nameKey": "domain.lm.campaign.entity",
    "valueTypeNameKey": "domain.laborMetric.valueType.choice",
    "choices": [
        {
            "id": "11e83904-4784-f2ec-b6f6-6c96cfdd4b6d",
            "code": "BLOGGER",
            "description": "Blogger Outreach"
        },
        {
            "id": "11e83904-4784-f314-b6f6-6c96cfdd4b6d",
            "code": "BRAND",
            "description": "Brand Identity"
        }
    ]
}

Labor Metric – Export Choices

This API returns labor metric choices for the given labor metric ID.

URL: /time/v1/ta/labor-metrics/{id}/choices
HTTP Method: GET

Parameters

Response Body

{
    "_embedded": {
        "resources": [
            {
                "id": "11e6f2ce-0a0a-4ac6-8eb5-7b24ea73ba86",
                "code": "NORTH",
                "description": "North"
            },
            {
                "id": "11e6f2ce-0a0a-4ac7-8eb5-7b24ea73ba86",
                "code": "SOUTH",
                "description": "South"
            },
            {
                "id": "11e6f2ce-0a0a-71d8-8eb5-7b24ea73ba86",
                "code": "EAST",
                "description": "East"
            },
            {
                "id": "11e6f2ce-0a0a-e709-8eb5-7b24ea73ba86",
                "code": "WEST",
                "description": "West"
            },
            {
                "id": "11e6f2ce-0a0b-0e1a-8eb5-7b24ea73ba86",
                "code": "NW",
                "description": "North West"
            },
            {
                "id": "11e6f2ce-0a0b-0e1b-8eb5-7b24ea73ba86",
                "code": "NE",
                "description": "North East"
            },
            {
                "id": "11e6f2ce-0a0b-0e1c-8eb5-7b24ea73ba86",
                "code": "SE",
                "description": "South East"
            },
            {
                "id": "11e6f2ce-0a0b-0e1d-8eb5-7b24ea73ba86",
                "code": "SW",
                "description": "South West"
            },
            {
                "id": "11e6f2ce-0a0b-352e-8eb5-7b24ea73ba86",
                "code": "MW",
                "description": "MidWest"
            },
            {
                "id": "11ea44ad-5ffe-da96-883a-e76a814c2b40",
                "code": "SCRY",
                "description": "SCRY"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/11e6e98d-aff8-b048-97d3-fb846d88d4c3/choices?page=1&per_page=30"
        },
        "first": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/11e6e98d-aff8-b048-97d3-fb846d88d4c3/choices?page=1&per_page=30"
        },
        "last": {
            "href": "http://localhost:18080/time/v1/ta/labor-metrics/11e6e98d-aff8-b048-97d3-fb846d88d4c3/choices?page=1&per_page=30"
        }
    },
    "page": {
        "size": 30,
        "totalElements": 10,
        "totalPages": 1,
        "number": 1
    }
}

Labor Metric Group APIs

Labor Metric Group APIs handle the creation, retrieval, updating, and deletion of labor metric groups, as well as managing cascade/links within these groups.

Labor Metric Group – Export All

This API returns details for all labor metric groups.

• cascadeType: Specifies the cascade type, which may be OFF, CASCADING, or LINKING.
• cascadeOrder: Specifies the order of labor metric codes for cascade/links (only applicable for cascadeType of LINKING/CASCADING).
• laborMetrics: Specifies the available labor metric choices for a given labor metric within the group.
  • includeAllChoices: Whether all choices may be used as cascade/links for the associated labor metric within the group. Default is false.
  • availableChoices: A list of specific choice IDs that may be used as cascade/links for the associated labor metric within the group. Refer to the Labor Metric Choices API for a list of valid choice IDs.

URL:/time/v1/ta/labor-metric-groups
HTTP Method:GET

Parameters

Response Body

{
    "_embedded": {
        "resources": [
            {
                "id": "11e83904-4784-f468-b6f6-6c96cfdd4b6d",
                "name": "Sample Labor Metric Group",
                "cascadeType": "OFF",
                "cascadeOrder": []
            },
            {
                "id": "11e83904-4784-f4c2-b6f6-6c96cfdd4b6d",
                "name": "Linking Labor Metric Group",
                "cascadeType": "LINKING",
                "cascadeOrder": [
                    "LOCATION",
                    "ORGLVL1",
                    "PROJECT"
                ]
            }
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost/time/v1/ta/labor-metric-groups?page=1&per_page=0"
        },
        "first": {
            "href": "http://localhost/time/v1/ta/labor-metric-groups?page=1&per_page=0"
        },
        "last": {
            "href": "http://localhost/time/v1/ta/labor-metric-groups?page=1&per_page=0"
        }
    },
    "page": {
        "size": 2,
        "totalElements": 2,
        "totalPages": 1,
        "number": 1
    }
}

Labor Metric Group – Export

This API returns details for the specified labor metric group.

• cascadeType: May either be OFF, CASCADING, or LINKING.
• cascadeOrder: Specifies the order of labor metric codes for cascade/links (only applicable for cascadeType of LINKING/CASCADING).
• laborMetrics: Specifies the available labor metric choices for a given labor metric within the group.
  • includeAllChoices: Whether all choices may be used as cascade/links for the associated labor metric within the group. Default is false.
  • availableChoices: A list of specific choice IDs that may be used as cascade/links for the associated labor metric within the group. Refer to the Labor Metric Choices API for a list of valid choice IDs.

URL:/time/v1/ta/labor-metric-groups/{id}
HTTP Method:GET

Parameters

Response Body

{
    "id": "11e83904-4784-f4c2-b6f6-6c96cfdd4b6d",
    "name": "Linking Labor Metric Group",
    "cascadeType": "LINKING",
    "cascadeOrder": [
        "LOCATION",
        "ORGLVL1",
        "PROJECT"
    ],
    "laborMetrics": {
        "LOCATION": {
            "includeAllChoices": true
        },
        "PROJECT": {
            "availableChoices": [
                "11e6f2ce-0a08-9d0c-8eb5-7b24ea73ba86",
                "11e6f2ce-0a08-9d0d-8eb5-7b24ea73ba86",
                "11e6f2ce-0a08-75fa-8eb5-7b24ea73ba86",
                "11e6f2ce-0a08-9d0b-8eb5-7b24ea73ba86"
            ]
        },
        "ORGLVL1": {
            "includeAllChoices": true
        }
    }
}

Labor Metric Group – Import

This API creates a new labor metric group.

URL: /time/v1/ta/labor-metric-groups

HTTP Method: POST

Parameters

Response

201 Created with the identifier for the new labor metric group.

Labor Metric Group – Update

This API updates the specified labor metric group.

URL: /time/v1/ta/labor-metric-groups/{id}
HTTP Method: PATCH

Parameters

Labor Metric Group – Delete

This API deletes the specified labor metric group and its associated cascades/links.

URL: /time/v1/ta/labor-metric-groups/{id}

HTTP Method: DELETE

Parameters

Labor Metric Group Cascade/Links – Export

This API returns the cascade/link paths for the specified group in cascade order. This API is only applicable for cascade types of LINKING/CASCADING.

URL: /time/v1/ta/labor-metric-groups/{id}/mappings
HTTP Method: GET

Parameters

Response Body

[
    [
        "11e6f2ce-0a05-1a8d-8eb5-7b24ea73ba86",
        "11e6f2ce-0a07-b2a8-8eb5-7b24ea73ba86",
        "11e83904-4784-f3f0-b6f6-6c96cfdd4b6d"
    ],
    [
        "11e6f2ce-0a05-1a8d-8eb5-7b24ea73ba86",
        "11e6f2ce-0a07-b2a8-8eb5-7b24ea73ba86",
        "11e83904-4784-f2ec-b6f6-6c96cfdd4b6d"
    ],
    [
        "11e6f2ce-0a05-1a8d-8eb5-7b24ea73ba86",
        "11e6f2ce-0a07-b2a8-8eb5-7b24ea73ba86",
        "11e83904-4784-f3be-b6f6-6c96cfdd4b6d"
    ],
    [
        "11e6f2ce-0a05-1a8d-8eb5-7b24ea73ba86",
        "11e6f2ce-0a08-c420-8eb5-7b24ea73ba86",
        "11e83904-4784-f2ec-b6f6-6c96cfdd4b6d"
    ],
    [
        "11e6f2ce-0a05-1a8d-8eb5-7b24ea73ba86",
        "11e6f2ce-0a08-c420-8eb5-7b24ea73ba86",
        "11e83904-4784-f418-b6f6-6c96cfdd4b6d"
    ]
]

Note: This sample response might represent the following cascade/link web configuration, where each nested array represents a full path of choice IDs.

Example Configuration:

• Location: Edit Location(s) FLLOC - Florida
• Project: Edit Project(s) PROJ3 – Project 3
• Campaign: Edit Campaign(s) DELIVERY – Delivery Service, BLOGGER – Blogger Outreach, ONLINE – Online Menu, PROJ11 – Project 11

Labor Metric Group Cascade/Links – Import

This API adds the cascade/link paths for the specified group. Refer to the format and example in the Labor Metric Group Cascade/Links - Export section.

URL: /time/v1/ta/labor-metric-groups/{id}/mappings
HTTP Method:PATCH

Parameters

Request Body

[
    [
        "37e260bf-ea0b-4bb7-9592-5ba01069c75a",
        "4a8f2eb7-fb33-46ee-a558-013f300e76d7",
        "ccf42522-95a2-47c1-a96d-396169bfe5a7"
    ],
    [
        "37e260bf-ea0b-4bb7-9592-5ba01069c75a",
        "15687b14-4a01-4071-b5d9-1575755a6dad"
    ]
]

Note: This sample request might represent the following cascade/link web configuration.

Labor Metric Group Cascade/Links – Delete

This API deletes all cascades/links for the specified group.

URL: /time/v1/ta/labor-metric-groups/{id}/mappings
HTTP Method: DELETE

Parameters