Employment Term Assignments

A contract schedule is a schedule that is associated with an employment term. An employee using that employment term has been contracted to work the amount of hours in the contract schedule.

You can assign, update, delete, and retrieve details about employment term assignments using operations against the /v1/commons/persons/employment_terms resource.

Prerequisites

A person's person ID is the same as the personKey and employee ID, and is not the same as the person number.

The person in this example has a person ID of 100 and a person number of 20190.

Example

In this example, we retrieve a list of available employment terms and then assign, verify, update, and delete a person's employment term assignments.

Retrieve available employment terms

Call GET /v1/timekeeping/setup/employment_terms to retrieve a list of all available employment terms. The response returned will resemble the example below.

[
  {
    "allowsInheritance": false,
    "isActive": true,
    "name": "Administrative Employees",
    "id": 2,
    "processType": "ENFORCE_END_DATE",
    "versions": {
      "employmentTermVersion": [
        {
          "accrualProfile": {
            "id": 16,
            "qualifier": "Massachusetts Earned",
            "name": "Massachusetts Earned"
          },
          "endDate": "3000-01-01",
          "holidayProfile": {
            "id": 34,
            "qualifier": "Massachusetts State Employees",
            "name": "Massachusetts State Employees"
          },
          "payRule": {
            "id": 8,
            "qualifier": "US FLSA Weekly",
            "name": "US FLSA Weekly"
          },
          "startDate": "2015-01-01"
        }
      ]
    }
  },
  {
    "allowsInheritance": false,
    "isActive": true,
    "name": "All European Contract Periods",
    "id": 4,
    "processType": "ENFORCE_END_DATE",
    "versions": {
      "employmentTermVersion": [
        {
          "endDate": "3000-01-01",
          "startDate": "2015-01-01",
          "workHours": {
            "workHourDef": [
              {
                "datePattern": "Daily",
                "payCode": {
                  "id": 664,
                  "qualifier": "Daily Contract Tracking",
                  "name": "Daily Contract Tracking"
                },
                "targetAmountType": "CONTRACT_SCHEDULE_AMOUNT",
                "useContractShift": true,
                "useInGenie": true
              },
              {
                "datePattern": "Weekly",
                "payCode": {
                  "id": 164,
                  "qualifier": "Weekly Contract Tracking",
                  "name": "Weekly Contract Tracking"
                },
                "targetAmountType": "CONTRACT_SCHEDULE_AMOUNT",
                "useContractShift": true,
                "useInGenie": true
              },
              {
                "datePattern": "Months from January 1st",
                "payCode": {
                  "id": 153,
                  "qualifier": "Monthly Contract Tracking",
                  "name": "Monthly Contract Tracking"
                },
                "targetAmountType": "CONTRACT_SCHEDULE_AMOUNT",
                "useContractShift": true,
                "useInGenie": true
              },
              {
                "datePattern": "Quarterly",
                "payCode": {
                  "id": 303,
                  "qualifier": "Quarterly Contract Tracking",
                  "name": "Quarterly Contract Tracking"
                },
                "targetAmountType": "CONTRACT_SCHEDULE_AMOUNT",
                "useContractShift": true,
                "useInGenie": true
              },
              {
                "datePattern": "Yearly",
                "payCode": {
                  "id": 226,
                  "qualifier": "Yearly Contract Tracking",
                  "name": "Yearly Contract Tracking"
                },
                "targetAmountType": "CONTRACT_SCHEDULE_AMOUNT",
                "useContractShift": true,
                "useInGenie": true
              }
            ]
          }
        }
      ]
    }
  },
  ...
]

The example response above is truncated due to excessive length. Note that you can pass the query parameter all_details=false to reduce the size of the response body for this call and return only the ID, name, and Persistent ID of each employment term.

Create the assignment

The create request:

uses personIdentity to identify the person using their person number
uses the assignments array to define the employee tags to assign
uses effectiveDate and expirationDate to define the effective date and the expiration date of the assignment

Example request

Call POST /v1/commons/persons/employment_terms with the following request payload.

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "effectiveDate": "2020-02-20",
      "employmentTerm": {
        "qualifier": "Administrative Employees"
      },
      "expirationDate": "2020-06-25"
    }
  ]
}

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
    "personIdentity": {
        "personNumber": "20190",
        "personKey": 100
    },
    "assignments": [
        {
            "employmentTerm": {
                "id": 2,
                "qualifier": "Administrative Employees"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-06-25"
        }
    ]
}

Verify the assignment

To verify, you can call GET /v1/commons/persons/employment_terms?person_number={personNumber} or GET /v1/commons/persons/employment_terms/{personKey}.

Calling GET /v1/commons/persons/employment_terms?person_number=20190 or GET /v1/commons/persons/employment_terms/100 returns:

{
    "personIdentity": {
        "personNumber": "20190",
        "personKey": 100
    },
    "assignments": [
        {
            "employmentTerm": {
                "id": 2,
                "qualifier": "Administrative Employees"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-06-25"
        }
    ]
}

Update the assignment

To update the person's employment term assignments, call PUT /v1/commons/persons/employment_terms with the following request payload.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "effectiveDate": "2020-02-20",
      "employmentTerm": {
        "qualifier": "Administrative Employees"
      },
      "expirationDate": "2020-06-25"
    },
    {
      "effectiveDate": "2020-03-20",
      "employmentTerm": {
        "qualifier": "All European Contract Periods"
      },
      "expirationDate": "2020-07-30"
    }
  ]
}

Example response

{
    "personIdentity": {
        "personNumber": "20190",
        "personKey": 100
    },
    "assignments": [
        {
            "employmentTerm": {
                "id": 2,
                "qualifier": "Administrative Employees"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-03-20"
        },
        {
            "employmentTerm": {
                "id": 4,
                "qualifier": "All European Contract Periods"
            },
            "effectiveDate": "2020-03-20",
            "expirationDate": "2020-07-30"
        }
    ]
}

Delete an assignment

To delete an employment term assignment associated with a person, call POST /v1/commons/persons/employment_terms/apply_delete with the following request payload. In this example, we delete the All European Contract Periods employment term. The Administrative Employees employment term remains assigned to the employee.

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "effectiveDate": "2020-03-20",
      "employmentTerm": {
        "qualifier": "All European Contract Periods"
      },
      "expirationDate": "2020-07-30"
    }
  ]
}

The system returns HTTP status 204 with an empty response body.