Certification Assignments

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

Retrieve available certifications

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

[
    {
        "id": 1,
        "name": "Ground Staff Services",
        "abbreviation": "GSS",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 2,
        "name": "Project Management",
        "abbreviation": "Proj",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 3,
        "name": "Quality Management",
        "abbreviation": "Qua",
        "active": true,
        "deleted": false,
        "version": 1
    },
    {
        "id": 4,
        "name": "Server Platform",
        "abbreviation": "Ser",
        "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 certifications within personAssignments to define the certifications to assign
uses effectiveDate and expirationDate to define the effective date and the expiration date of the assignment

Note: Unlike many assignments, expiration date is required.

Example request

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "certifications": {
        "assignments": [
          {
            "certification": {
              "id": 1,
              "qualifier": "3D Basics"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-07-19",
            "expirationDate": "2022-10-31"
          }
        ]
      }
    }
  }
]

Example response

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "certifications": {
        "assignments": [
          {
            "certification": {
              "id": 1,
              "qualifier": "3D Basics"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-07-19",
            "expirationDate": "2022-10-31"
          }
        ]
      }
    }
  }
]

Note: If the expiration date for a certification occurs in the past, the returned certifications object will not contain that certification. If the expiration dates for all assigned certifications occur in the past, the certifications object will be empty.

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

Example response

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

[
  {
    "personIdentity": {
      "personNumber": "20190"
    },
    "personAssignments": {
      "certifications": {
        "assignments": [
          {
            "certification": {
              "id": 1,
              "qualifier": "3D Basics"
            },
            "proficiencyLevel": {
              "id": -1,
              "qualifier": "ANY"
            },
            "effectiveDate": "2021-07-19",
            "expirationDate": "2022-10-31"
          }
        ]
      }
    }
  }
]

Delete assignments

You can delete, or unassign, certification 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": {
            "certifications": {
                "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": {
      "certifications": {
        "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.