Employee Tag Assignments

Tags provide additional information about a shift segment or a date cell in the schedule. Depending on the configuration, a tag can specify a work rule condition that the Scheduler considers, or a tag can specify no work rule and serve only as a visual reference for the manager.

You can assign, update, delete, and retrieve details about employee tag assignments using operations against the /v1/commons/persons/employee_tags 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 assign, verify, update, and delete a person's employee tag assignments.

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/employee_tags with the following request payload.

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

Example response

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

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "employeeTag": {
                "id": 151,
                "qualifier": "EmployeeTag1"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-06-25"
        }
    ]
}

Verify the assignment

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

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

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "employeeTag": {
                "id": 151,
                "qualifier": "EmployeeTag1"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-06-25"
        }
    ]
}

Update the assignment

To update the person's employee tag assignment, call PUT /v1/commons/persons/employee_tags with the following request payload.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "effectiveDate": "2020-02-20",
      "employeeTag": {
        "qualifier": "EmployeeTag1"
      },
      "expirationDate": "2020-06-25"
    },
    {
      "effectiveDate": "2020-02-15",
      "employeeTag": {
        "qualifier": "EmployeeTag2"
      },
      "expirationDate": "2020-06-15"
    }
  ]
}

Example response

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "employeeTag": {
                "id": 152,
                "qualifier": "EmployeeTag2"
            },
            "effectiveDate": "2020-02-15",
            "expirationDate": "2020-06-15"
        },
        {
            "employeeTag": {
                "id": 151,
                "qualifier": "EmployeeTag1"
            },
            "effectiveDate": "2020-02-20",
            "expirationDate": "2020-06-25"
        }
    ]
}

Delete an assignment

To delete an employee tag assignment associated with a person, call PUT /v1/commons/persons/employee_tags with the following request payload.

{
  "personIdentity": {
    "personNumber": "20190"
  }
}

The system returns HTTP status 200 with the following response body:

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": []
}

Updated over 1 year ago