Skill Assignments

You can assign, update, delete, and retrieve details about skill assignments using operations against the /v1/commons/persons/skills 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 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 the assignment

The create request:

uses personId in the URL and personIdentity in the request body to identify the person using their person ID and person number, respectively
uses certification within assignments to define the certification to assign
uses effectiveDate and expirationDate to define the effective date and the expiration date of the assignment

Note: You must pass Person ID in the URL, but you may specify either a person ID or a person number in the personIdentity object. You must include all of the information above to make a successful request. Unlike many assignments, expiration date is required.

Example request

Call PUT /v1/commons/persons/skills/100 with the following request payload.

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "skill": {
        "qualifier": "Leadership"
      },
      "effectiveDate": "2020-02-20",
      "active": true
    }
  ]
}

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": [
        {
            "skill": {
                "id": 4,
                "qualifier": "Leadership"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-02-20",
            "active": true
        }
    ]
}

Verify the assignment

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

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

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "skill": {
                "id": 4,
                "qualifier": "Leadership"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-02-20",
            "active": true
        }
    ]
}

Update the assignment

To update the person's skill assignments by adding an addition skill, call PUT /v1/commons/persons/skills/100 with the following request payload.

Note that this PUT operation replaces all existing skill assignments with the request body. If you want to continue to include a person's previously assigned skills, be sure to include them in the update's request body as shown in the example below.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "skill": {
        "qualifier": "Leadership"
      },
      "effectiveDate": "2020-02-20",
      "active": true
    },
    {
      "skill": {
        "qualifier": "Communication"
      },
      "effectiveDate": "2020-04-10",
      "active": true
    }
  ]
}

Example response

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "skill": {
                "id": 2,
                "qualifier": "Communication"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-04-10",
            "active": true
        },
        {
            "skill": {
                "id": 4,
                "qualifier": "Leadership"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-02-20",
            "active": true
        }
    ]
}

Delete an assignment

To delete a skill assignment associated with a person, call POST /v1/commons/persons/skills/apply_delete and and specify the unwanted skill assignments in the request. Only skill assignments with an effective date in the future are deleted.

For our example, to remove the Communication skill, submit the following request payload.

Example request

{
  "personIdentity": {
    "personNumber": "20190"
  },
  "assignments": [
    {
      "skill": {
        "qualifier": "Communication"
      },
      "proficiencyLevel": {
        "id": -1,
        "qualifier": "ANY"
      },
      "effectiveDate": "2020-02-20",
      "active": true
    }
  ]
}

Example response

{
    "personIdentity": {
        "personKey": 100,
        "personNumber": "20190"
    },
    "assignments": [
        {
            "skill": {
                "id": 4,
                "qualifier": "Leadership"
            },
            "proficiencyLevel": {
                "id": -1,
                "qualifier": "ANY"
            },
            "effectiveDate": "2020-02-20",
            "active": true
        }
    ]
}