1. Oracle Global Human Resources Cloud REST APIREST API for Oracle Fusion Cloud HCM
  2. Use Cases
  3. Talent Management
  4. Manage Check-In Documents

Manage Check-In Documents

You can use the Check-Ins Rest Service to create, update, and retrieve check-in documents. This use case discusses these scenarios:
  • Creating check-in documents
  • Creating responses to questions in questionnaires of the check-in document
  • Updating a check-in document
  • Retrieving check-in documents
A typical application flow for Managing Check-Ins scenario is as follows:
  1. You configure performance review periods.
  2. You configure questionnaire templates, questionnaires, and questions
  3. You configure check-in templates
  4. You specify the eligibility criteria on the check-in template so employees and managers can create check-in documents using these check-in templates
  5. You use the check-ins rest service to upload the check-in documents to Oracle HCM Cloud.

If you are using third-party application to create check-in documents and want to check-in documents in Oracle HCM Cloud, you can use the Check-Ins rest service to bulk upload check-in documents.

This use case discusses the following scenarios:

  • Create check-in documents.
  • Create responses to questions in questionnaires.
  • Retrieve check-in document details.

Create Check-In Documents

Create Responses to Questions

When creating a check-in document, the client application executes a POST operation on the URL for the Check-Ins REST resource. The check-in document for the employee is then available in Oracle HCM Cloud. For example, Jen creates a check-in document, 2018 Quarter 1 Check-In using the 2018 Check-In template. This creates a new record in Oracle HCM Cloud.

To create a check-in document for a worker, ensure that you have the following details:
  • Person ID or Person Number
  • Manager ID or Manager Number
  • Assignment ID or Assignment Number
  • Review Period ID or Review Period Name
  • Check-In Template ID or Check-In Template Name
After you???ve gathered the details, do the following:
  1. By using publicWorkers API, get the information for a person, manager, and assignment details.
  2. By using the reviewPeriodsLOV, get the information on review periods.
  3. By using the checkInTemplatesLOV, get the information on check-in templates that the worker is eligible for. After you perform these tasks and get the values, you form the request payload and then create the check-in document.

Example URL

The following is the format of the resource URL.

POST

/hcmRestApi/resources/11.13.18.05/checkInDocuments

Example Request

The following is an example of the request body in JSON format.

{
            
            "PersonNumber": "8153756",
            "AssignmentNumber": "EEEE8153756",
            "DocumentName": "Test Rest DocumentV49",
            "CheckInDate": "2018-08-23",
            "ReviewPeriodName": "Mobile 2017",
            "CheckInTemplateName": "Check-In 3 (September)",
            "ManagerPersonNumber": "8153799"
             
             
    }

Example Response

{
            
"CheckInDocumentId": 300100179010708,

    "CheckInTemplateId": 300100167943392,

    "CheckInTemplateName": "Check-In Meetings",

    "ReviewPeriodId": 300100060972693,

    "ReviewPeriodName": "ZHRA-ReviewPeriod FY2015",

    "ManagerPersonId": 923460008154816,

    "ManagerPersonNumber": "ZHRA-8154816",

    "PersonId": 923460008154818,

    "PersonNumber": "ZHRA-8154818",

    "AssignmentId": 923460008154818,

    "AssignmentNumber": "EEEEZHRA-8154818",

    "DocumentName": "Test 1234_update",

    "CheckInDate": "2019-02-01",
    
}

To create responses to questions in the questionnaire of a check-in document, you must search for the check-in document by the unique identifier. After retrieving it, you can update the check-in document by adding or updating the questionnaire responses. You may want to add an attachment as a part of responding to a question.

For example, Jen wants to add responses to the questions in questionnaire. She searches for the check-in document, 2018 Quarter 1 Check-In and then creates responses. As a part of the response, she adds an attachment. Jen's manager, Mark responds to the questionnaire that is assigned to him. You may want to create responses to the questions in the manager questionnaire too.

To create responses to questions in the questionnaire of a check-in document, you must query the check-in document and then add the question responses. You have to do the following in order to create responses:
  1. Get the associated Questionnaire Codes and related objects for the newly created check-in document by using the operation./hcmRestApi/resources/11.13.18.05/checkInDocuments?expand=questionnaireResponses&q=CheckInDocumentId in (1234,1235)
  2. Retrieve Questions IDs in the worker questionnaire and manager questionnaire by using the questionnaireQuestionsLOV. /hcmRestApi/resources/11.13.18.05/questionnaireQuestionsLOV?q=QuestionnaireCode in ('sdeu23','dsds22','dsdsds').
  3. Retrieve the related responses (answers) for the single choice and multiple choice questions by using questionAnswersLOV. GET /hcmRestApi/resources/11.13.18.05/questionAnswersLOV?q=QuestionCode in ('dsds2','123232sd','122121')
  4. Create responses to questions in the worker questionnaire and manager questionnaire by using the POST operation on the questionResponses resource. (Repeat the POST operation -- one for worker questions and the other for manager questions.)
  5. Add attachments as apart of the response to question by using the POST operation on Attachments.

How to Create Responses to Questions using POST

You can get the associated questionnaire codes and questions from the check-in document.Perform the POST operation twice to questionResponses using QuestionAnswerIds and QuestionnaireQuestionIds, which you get when you performed the task in the earlier steps. Example URL

The following is the format of the resource URL.

POST

POST /checkinDocuments/<checkInDocumentId>/child/questionnaireResponses/child/<questionnaireResponseId>/child/questionResponses

Example Request

The following is an example of the request URL to be executed: 
{
    "parts": [
        {
            "id": "part1",
            "path": "/checkInDocuments/00100000000EACED00057708000110F08084C64C0000000EACED0005770800000000000000CA0000000EACED00057708000110F07EDF15FA0000000EACED00057708000110F08084BBB60000000EACED0005770800000000000000CA0000000EACED0005770800005AF310F6AA9D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000001645C423440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000EACED0005770800005AF310F6ABCD0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F5A3D440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000AACED000577040000000100000001590000000EACED0005770800005AF310F6AA9C0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F07D7840780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF44078/child/questionnaireResponses/300100111091278/child/questionResponses/",
            "operation": "create",
            "payload": {
                "QuestionnaireQuestionId": 300100111088609,
                "AnswerCLOB": "PEI+SGVsbG8gdGVzdGluZyAhPEI+",
                "responseAttachments":[{
                    "DatatypeCode" : "WEB_PAGE",
                    "Description" : "Testing NOV 28 Attachment 7",
                    "Uri" : "https://www.google.com",
                    "Url" : "https://www.google.com"
                },
                {
                    "DatatypeCode" : "WEB_PAGE",
                    "Description" : "Testing NOV 28 Attachment 8",
                    "Uri" : "https://www.google.com",
                    "Url" : "https://www.google.com"
                }]
            }
        },
        {
            "id": "part2",
            "path": "/checkInDocuments/00100000000EACED00057708000110F08084C64C0000000EACED0005770800000000000000CA0000000EACED00057708000110F07EDF15FA0000000EACED00057708000110F08084BBB60000000EACED0005770800000000000000CA0000000EACED0005770800005AF310F6AA9D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000001645C423440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000EACED0005770800005AF310F6ABCD0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F5A3D440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000AACED000577040000000100000001590000000EACED0005770800005AF310F6AA9C0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F07D7840780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF44078/child/questionnaireResponses/300100111091278/child/questionResponses/",
            "operation": "create",
            "payload": {
                "QuestionnaireQuestionId": 300100111088618,
                "AnswerCLOB": "PEI+SGVsbG8gdGVzdGluZyAhPEI+"
            }
        },
        {
            "id": "part3",
            "path": "/checkInDocuments/00100000000EACED00057708000110F08084C64C0000000EACED0005770800000000000000CA0000000EACED00057708000110F07EDF15FA0000000EACED00057708000110F08084BBB60000000EACED0005770800000000000000CA0000000EACED0005770800005AF310F6AA9D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000001645C423440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000EACED0005770800005AF310F6ABCD0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F5A3D440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000AACED000577040000000100000001590000000EACED0005770800005AF310F6AA9C0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F07D7840780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF44078/child/questionnaireResponses/300100111102999/child/questionResponses/",
            "operation": "create",
            "payload": {
                "QuestionnaireQuestionId": 300100111088618,
                "AnswerCLOB": "PEI+SGVsbG8gdGVzdGluZyAhPEI+"
            }
        },
        {
            "id": "part4",
            "path": "/checkInDocuments/00100000000EACED00057708000110F08084C64C0000000EACED0005770800000000000000CA0000000EACED00057708000110F07EDF15FA0000000EACED00057708000110F08084BBB60000000EACED0005770800000000000000CA0000000EACED0005770800005AF310F6AA9D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000001645C423440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000EACED0005770800005AF310F6ABCD0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F5A3D440780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF440780000000AACED000577040000000100000001590000000EACED0005770800005AF310F6AA9C0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B59741903000078707708000000E7F07D7840780000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800004EB9F5AEF44078/child/questionnaireResponses/300100111102999/child/questionResponses/",
            "operation": "create",
            "payload": {
                "QuestionnaireQuestionId": 300100111088609,
                "AnswerCLOB": "PEI+SGVsbG8gdGVzdGluZyAhPEI+"
            }
        }
    ]
}

Example Response

The following is an example of the response body in JSON format.

{
        "items" : [
         {
           "QuestionResponseId" : "33232344343",
           "QuestionId" : "323233434",
           "QuestionVersionNumber" : "3",
           "QuestionCode" : "Plain Text Question Code",
           "AnswerText" : "Sample Response 1",
           "QuestionAnswerId" : "null",
           "AnswerList" : "null",
           "Links" : [
                           {....},
                         ]
         },
        {
           "QuestionResponseId" : "33232344348",
           "QuestionId" : "323233437",
           "QuestionVersionNumber" : "2",
           "QuestionCode" : "Single Choice Question Code",
           "AnswerText" : "null",
           "QuestionAnswerId" : "213234332",
           "AnswerList" : "null",
           "CreatedBy" : "Meg",
           "CreationDate" : "20-Oct-2018",
           "LastUpdatedBy" : "Meg",
           "LastUpdateDate" : "20-Oct-2018",
           "Links" : [
                           {....},
                       ]
        },
        {
           "QuestionResponseId" : "33232344340",
           "QuestionId" : "323233432",
           "QuestionVersionNumber" : "3",
           "QuestionCode" : "Multiple Choice Question Code",
           "AnswerText" : "null",
           "QuestionAnswerId" : "null",
           "AnswerList" : "3002323, 23234443, 3223434343",
           "CreatedBy" : "Meg",
           "CreationDate" : "20-Oct-2018",
           "LastUpdatedBy" : "Meg",
           "LastUpdateDate" : "20-Oct-2018",
           "Links" : [
                           {.....},
                         ]
        }
     ],
    "rel" : "self",
    "href" : "{url}: {port}/<context>/checkInDocuments/<checkInDocumentId>/child/questionnaireResponses/child/3203232212121/questionResponses",
    "kind" : "collection",
    "name" : "questionResponses" }
Example URL

PATCH /checkInDocuments/<checkInDocumentId>/child/questionnaireResponses/<questionnaireResponseId>/child/questionResponses/33232344340

Example Request 
{ 
   "AnswerList" : "3002323, 23234443"
 }
 
 
Example 2 : 
PATCH /checkInDocuments/<checkInDocumentId>/child/questionnaireResponses/<questionnaireResponseId>/child/questionResponses/33232344348
 
 
Request Body : 
 
 
 {
   "QuestionAnswerId" : "213234334"
 }
 
 
Example 3 : 
PATCH /checkInDocuments/<checkInDocumentId>/child/questionnaireResponses/<questionnaireResponseId>/child/questionResponses/33232344343
 
Request Body : 
 
 
 {
   "AnswerText" : "Patch Answer Text Sample"
 }
Example Response

The response is in json format.

{
           "QuestionResponseId" : "33232344340",
           "QuestionId" : "323233432",
           "QuestionVersionNumber" : "3",
           "QuestionCode" : "Multiple Choice Question Code",
           "AnswerText" : "null",
           "AnswerSeqNumber" : "null",
           "QuestionAnswerId" : "null",
           "AnswerList" : "3002323, 23234443",
           "CreatedBy" : "Meg",
           "CreationDate" : "20-Oct-2018",
           "LastUpdatedBy" : "Meg",
           "LastUpdateDate" : "20-Oct-2018",
           "Links" : [
                           {.....},
                         ]
        }

How to Add Attachments using POST

Add attachments as apart of the response to question by using the POST operation on Attachments.

Example URL

The following is the format of the resource URL.

POST

/checkInDocuments/{id}/child/questionnaireResponses/{id}/child/questionResponses/{id}/child/responseAttachments

Example Request

The following is an example of the request body in JSON format.

{
    "DatatypeCode" : "FILE",
     "FileName" : "REST Attachment.txt",
     "ContentRepositoryFileShared" : "false",
     "Title" : "REST Attachment.txt",
      "Description" : "description",
      "FileContents" : "Base64 encoded String of attachment"
}
 
 
 
 
/*
    DatatypeCode : "FILE" for File type attachment and WEB_PAGE for url type attachment
    UploadedFileContentType : mime type of attached file (only required in case of FILE type attachment)
    FileContents : This is Base 64 encoded String of the attached file
*/

Example Response

The following is an example of the response body in JSON format.

{
    "AttachedDocumentId": 300100172964813,
    "LastUpdateDate": "2018-12-03T11:31:29.440+00:00",
    "LastUpdatedBy": "TM-MFITZIMMONS",
    "DatatypeCode": "FILE",
    "FileName": "Hello.png",
    "DmFolderPath": null,
    "Url": null,
    "CategoryName": "MISC",
    "UserName": "Miscellaneous",
    "Uri": null,
    "FileUrl": "",
    "UploadedText": null,
    "UploadedFileContentType": "image/png",
    "UploadedFileLength": 367745,
    "UploadedFileName": null,
    "ContentRepositoryFileShared": "false",
    "Title": "Hello Image",
    "Description": "Image File",
    "ErrorStatusCode": null,
    "ErrorStatusMessage": null,
    "CreatedBy": "TM-MFITZIMMONS",
    "CreationDate": "2018-12-03T11:31:29+00:00",
    "ExpirationDate": null,
    "LastUpdatedByUserName": "Meg Fitzimmons",
    "CreatedByUserName": "Meg Fitzimmons",
    "links": [
        {
            "rel": "self",
            "href": "",
            "name": "responseAttachments",
            "kind": "item"
        },
        {
            "rel": "canonical",
            "href": "",
            "name": "responseAttachments",
            "kind": "item"
        },
        {
            "rel": "parent",
            "href": "..",
            "name": "questionResponses",
            "kind": "item"
        },
        {
            "rel": "enclosure",
            "href": "..",
            "name": "FileContents",
            "kind": "other"
        }
    ]
}

Retrieve Multiple Check-In Documents

To retrieve multiple check-in documents, you can search by parameters available in the payload, such as Manager Person ID, Worker Person ID, and Review Period ID. For example, Mark wants to search for all 2018 Quarter 1 check-in documents for his direct reports. He can use his Manager Person ID to view check-in documents of his direct reports..

To retrieve check-in documents:

  1. To retrieve multiple check-in documents, you query check-in documents by using a query parameter such as Manager Person ID..

Example URL

The following is an example of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/checkInDocuments?q=ManagerPersonId=300100170556979

Example Request

The following is an example of the request body in JSON format.

/hcmRestApi/resources/11.13.18.05/checkInDocuments?q=ManagerPersonId=923460008153780

Example Response

The following is an example of the response body in JSON format.

"items": [

        {

            "CheckInDocumentId": 300100177774477,

            "CheckInTemplateId": 300100167943392,

            "CheckInTemplateName": "Check-In Meetings",

            "ReviewPeriodId": 300100083455483,

            "ReviewPeriodName": "FY 2019 Review Period",

            "ManagerPersonId": 923460008153780,

            "ManagerPersonNumber": "ZHRA-8153780",

            "PersonId": 955160008153786,

            "PersonNumber": "ZHRG-8153786",

            "AssignmentId": 955160008153786,

            "AssignmentNumber": "EEEEZHRG-8153786",

            "DocumentName": "Test123456789",

            "CheckInDate": "2019-03-04"

        },

        {

            "CheckInDocumentId": 300100177741486,

            "CheckInTemplateId": 300100167943392,

            "CheckInTemplateName": "Check-In Meetings",

            "ReviewPeriodId": 300100083455483,

            "ReviewPeriodName": "FY 2019 Review Period",

            "ManagerPersonId": 923460008153780,

            "ManagerPersonNumber": "ZHRA-8153780",

            "PersonId": 955160008153786,

            "PersonNumber": "ZHRG-8153786",

            "AssignmentId": 955160008153786,

            "AssignmentNumber": "EEEEZHRG-8153786",

            "DocumentName": "Test123",

            "CheckInDate": "2019-03-04"

        }???



]