Skill Assignments - Aggregated

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 skills and then assign, verify, update, and delete a person's skill assignments.

Retrieve available skills

Call GET /v1/scheduling/skills to retrieve a list of all available skills. The response returned will resemble the example below.

[
    {
        "id": 1,
        "name": "Commercial awareness",
        "abbreviation": "ComAw",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 2,
        "name": "Communication",
        "abbreviation": "Comm",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 3,
        "name": "Confidence",
        "abbreviation": "Conf",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 4,
        "name": "Leadership",
        "abbreviation": "Lead",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 5,
        "name": "Organisation",
        "abbreviation": "Org",
        "active": true,
        "deleted": false,
        "version": 1
    }
]

Create or update assignments

The create or update request:

uses personIdentity to identify the person using their person number
uses skills within personAssignments to define the skills to assign
uses effectiveDate to define the effective date of the assignment

Example request

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "skills": {
        "assignments": [
          {
            "skill": {
              "id": 10,
              "qualifier": "Commercial awareness"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-08-31",
            "active": true
          }
        ],
        "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": {
      "skills": {
        "assignments": [
          {
            "skill": {
              "id": 10,
              "qualifier": "Commercial awareness"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-08-31",
            "active": true
          }
        ]
      }
    }
  }
]

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": [
      "skills"
    ]
  }
}

Example response

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "skills": {
        "assignments": [
          {
            "skill": {
              "id": 10,
              "qualifier": "Commercial awareness"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-08-31",
            "active": true
          }
        ]
      }
    }
  }
]

Delete assignments

You can delete, or unassign, skill assignments. To delete our example's skill assignments, call POST /v1/commons/persons/assignments/multi_upsert using the unAssignExisting property. Note that the skills continue to be returned in the response but with the active property now returning a false value.

Example request

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

[
    {
        "personIdentity": {
            "personNumber": "20190"
        },
        "personAssignments": {
            "skills": {
                "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": {
      "skills": {
        "assignments": [
          {
            "skill": {
              "id": 10,
              "qualifier": "Commercial awareness"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-08-31",
            "active": false
          }
        ]
      }
    }
  }
]

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.