Skill Assignments - Aggregated

Skills are employee attributes that work alongside certifications to allow the system to assign the most qualified person to do a job.

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.