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.

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 or update assignments

The create or update 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/assignments/multi_upsert with the following request payload.

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

Example response

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

[
    {
        "personIdentity": {
            "personNumber": "20190"
        },
        "personAssignments": {
            "employmentTerms": {
                "assignments": []
            }
        }
    }
]

Verify assignments

You can use the bulk multi-read operation to verify assignments for multiple people at once.

Example request

To verify, call POST /v1/commons/persons/assignments/multi_read with the following request payload.

{
  "where": {
    "employees": {
      "key": "personNumber",
      "values": [
        "20190"
      ]
    },
    "personAssignments": [
      "employmentTerms"
    ]
  }
}

Example response

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "employmentTerms": {
        "assignments": [
          {
            "employmentTerm": {
              "id": 55,
              "qualifier": "Administrative Employees"
            },
            "effectiveDate": "2020-06-25",
            "expirationDate": "2022-06-25"
          }
        ]
      }
    }
  }
]

Delete assignments

You can delete, or unassign, assignments. To delete our example's assignments, call POST /v1/commons/persons/assignments/multi_upsert using the unAssignExisting property.

Example request

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

[
    {
        "personIdentity": {
            "personNumber": "20190"
        },
        "personAssignments": {
            "employmentTerms": {
                "unAssignExisting":true
            }
        }
    }
]

Example response

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "employmentTerms": {
        "assignments": []
      }
    }
  }
]

Note: You can verify that the assignments were deleted by calling POST /v1/commons/persons/assignments/multi_read with a request payload specifying all of the affected person identities.