REST API for Oracle Fusion Cloud HCM

Manage Questionnaires

Your organization may have a requirement to publish a simple questionnaire for gathering feedback from employees at the end of specific assignments or on the usage of a new system roll-out, and use the received feedback to plan process improvements.

You can use the questionnaire functionality in Oracle HCM Cloud to set up such questionnaires and gather responses using the questions, questionnaires, and questionnaireparticipants REST APIs to store them in Oracle HCM Cloud.

These REST APIs let you perform the following actions. Let's discuss the scenarios briefly.

Set up questions for any subscriber.
Set up questionnaires for any subscriber.
Review questionnaires and questions for any subscriber.
Post responses received from a logged in user. This is applicable only for a questionnaire with a General Surveys subscriber.
Review posted responses when the appropriate person security profile is set up.

Note: Publishing the survey to specific employees is done externally and isn't within the scope of these APIs.

The user interface to publish the questionnaire and collect individual inputs from employees (Customer UI Layer) is external to Oracle HCM Cloud. The APIs described here allow setting up the questionnaires and posting the responses to store them in Oracle HCM Cloud.

General surveys workflow fron Oracle HCM Cloud to the Customer UI Layer.

Prerequisite

Administrators must first set up a questionnaire template in Oracle HCM Cloud. They can then use the REST APIs to create questions, set up a questionnaire and add questions, and review employee responses.

For instructions on setting up a questionnaire template, see the topic How You Configure Questionnaire Templates in the Workforce Profiles chapter of the Implementing Global Human Resources guide.

Example

Let's consider this example to see how these REST APIs work.

Shan Cilic is an administrator who's setting up a simple survey to gather feedback from employees in his department and understand their work preferences better. He first sets up a simple questionnaire template, Work_Prefer_Template, in Oracle HCM Cloud. He then uses the REST APIs to create questions, set up a questionnaire, and review employee responses.

Set Up Questions

Shan wants to set up these two types of questions using REST APIs. He will be adding these questions to the questionnaire that he's going to create later.

Single-choice question
Plain-text question

To set up the questions:

Perform a POST operation on the questions resource by providing the question details in the request body.
Verify the details returned in the response.

Single Choice Question

Here's an example for a single-choice question.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/questions

Example Request

Here's an example of the request body in JSON format.

{

    "QuestionCode": "WORK_PREFERENCE_CHOICE",
    "QuestionText": "Choose your work location preference?",
    "Status": "A",
    "SubscriberName": "General Surveys",
    "FolderName": "General Surveys",
    "PrivacyFlag": false,
    "QuestionType": "1CHOICE",
    "ResponseType": "SINGLE_CHOICE_LIST",
    "answers": [
        {
            "AnswerCode":"WFH",
            "LongAnswerText": "Work From Home (Remote)",
            "SequenceNumber": 100
        },
        {
            "AnswerCode":"WFO",
            "LongAnswerText": "Work From Office",
            "SequenceNumber": 200
        },
        {
            "AnswerCode":"6040",
            "LongAnswerText": "3 days Office; 2 days Remote",
            "SequenceNumber": 300
        },
        {
            "AnswerCode":"2-3-WFH",
            "LongAnswerText": "2 days Office; 3 days Remote",
            "SequenceNumber": 400
        }
    ]
}

Example Response

Here's an example of the response body in JSON format.

{
    "QuestionId": 300100551594584,
    "QuestionCode": "WORK_PREFERENCE_CHOICE",
    "QuestionText": "Choose your work location preference?",
    "VersionNumber": 1,
    "SubscriberName": "General Surveys",
    "FolderId": 31,
    "Status": "A",
    "QuestionType": "1CHOICE",
    "ResponseTypeId": 2,
    "ResponseType": "SINGLE_CHOICE_LIST",
    "PrivacyFlag": false,
    "ResponseMinimumLength": null,
    "ResponseMaximumLength": null,
    "MinimumResponses": null,
    "MaximumResponses": null,
    "Editor": null,
    "ResponseOrder": null,
    "SampleSize": null,
    "MaximumPossibleScore": null,
    "ClassificationCode": "MANUAL_PRESCREEN",
    "CandidateCode": "BOTH",
    "ControllingQuestionId": null,
    "ControllingQuestionCode": null,
    "ControllingAnswerId": null,
    "ControllingAnswerCode": null,
    "MinimumThresholdScore": null,
    "MaximumThresholdScore": null,
    "MaximumDate": null,
    "MinimumDate": null,
    "answers": [
        {
            "QuestionAnswerId": 300100551594585,
            "AnswerCode": "WFH",
            "CorrectFlag": false,
            "Score": null,
            "ShortAnswerText": null,
            "LongAnswerText": "Work From Home (Remote)",
            "SequenceNumber": 100,
            "links": [
                {...
                   }
            ]
        },
        {
            "QuestionAnswerId": 300100551594586,
            "AnswerCode": "WFO",
            "CorrectFlag": false,
            "Score": null,
            "ShortAnswerText": null,
            "LongAnswerText": "Work From Office",
            "SequenceNumber": 200,
            "links": [
                {...
                   }
            ]
        },
        {
            "QuestionAnswerId": 300100551594587,
            "AnswerCode": "6040",
            "CorrectFlag": false,
            "Score": null,
            "ShortAnswerText": null,
            "LongAnswerText": "3 days Office; 2 days Remote",
            "SequenceNumber": 300,
            "links": [
                {...
                   }
            ]
        },
        {
            "QuestionAnswerId": 300100551594588,
            "AnswerCode": "2-3-WFH",
            "CorrectFlag": false,
            "Score": null,
            "ShortAnswerText": null,
            "LongAnswerText": "2 days Office; 3 days Remote",
            "SequenceNumber": 400,
            "links": [
                {...
                   }
            ]
}

Plain Text Question

Here's an example for a plain text question.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/questions

Example Request

Here's an example of the request body in JSON format.

{
    "QuestionCode": "REMOTE_EXPERIENCE",
    "QuestionText": "Share your experience of our IT tools and support when working remotely, if you have worked remotely before.",
    "Status": "A",
    "ScoredFlag": false,
    "SubscriberName": "General Surveys",
    "FolderName": "General Surveys",
    "PrivacyFlag": false,
    "QuestionType": "TEXT",
    "ResponseType": "PLAIN_TEXT"
}

Example Response

Here's an example of the response body in JSON format.

{
    "QuestionId": 300100551594581,
    "QuestionCode": "REMOTE_EXPERIENCE",
    "QuestionText": "Share your experience of our IT tools and support when working remotely, if you have worked remotely before.",
    "VersionNumber": 1,
    "SubscriberName": "General Surveys",
    "FolderId": 31,
    "Status": "A",
    "QuestionType": "TEXT",
    "ResponseTypeId": 1,
    "ResponseType": "PLAIN_TEXT",
    "PrivacyFlag": false,
    "ResponseMinimumLength": null,
    "ResponseMaximumLength": null,
    "MinimumResponses": null,
    "MaximumResponses": null,
    "Editor": null,
    "ResponseOrder": null,
    "SampleSize": null,
    "MaximumPossibleScore": null,
    "ClassificationCode": "MANUAL_PRESCREEN",
    "CandidateCode": "BOTH",
    "ControllingQuestionId": null,
    "ControllingQuestionCode": null,
    "ControllingAnswerId": null,
    "ControllingAnswerCode": null,
    "MinimumThresholdScore": null,
    "MaximumThresholdScore": null,
    "MaximumDate": null,
    "MinimumDate": null,
    "links": [
        {...
           }
    ]
}

Set Up a Questionnaire

Shan now sets up a questionnaire using the questions that he created above. He uses the Work_Prefer_Template questionnaire template created earlier as a base for the questionnaire.

To set up a questionnaire:

Perform a POST operation on the questionnaires resource by providing the questionnaire details in the request body.
Verify the details returned in the response.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/questionnaires

Example Request

Here's an example of the request body in JSON format.

{
    "QuestionnaireName": "Work Preference Survey",
    "QuestionnaireCode": "work_pref_survey_01",
    "Description": "Employee Work Preference questionnaire.",
    "VersionNumber": 1,
    "SubscriberCode": "GSVY",
    "QuestionnaireTemplateCode": "Work_Prefer_Template",
    "FolderName": "General Surveys",
    "PrivacyFlag": false,
    "SectionPresentation": "N",
    "SectionOrder": "S",
    "Status": "A",
    "sections": [
        {
            "SectionSequenceNumber": 100,
            "SectionName": "Section 1",
            "Description": "First Section",
            "QuestionOrder": "V",
            "ResponseOrder": "V",
            "questions": [
                {
                    "QuestionCode": "WORK_PREFERENCE_CHOICE",
                    "VersionNumber": 1
                },
                {
                    "QuestionCode": "REMOTE_EXPERIENCE",
                    "VersionNumber": 1
                }
            ]
        }
    ]
}

Example Response

Here's an example of the response body in JSON format.

{
    "QuestionnaireId": 300100562894476,
    "QuestionnaireName": "Work Preference Survey",
    "QuestionnaireCode": "work_pref_survey_01",
    "VersionNumber": 1,
    "VersionDescription": null,
    "SubscriberId": 15,
    "FolderId": 31,
    "ScoreQuestionnaireFlag": false,
    "Status": "A",
    "Editor": null,
    "InUse": "N",
    "CalculationRule": "SUM",
    "SectionOrder": "S",
    "SectionPresentation": "N",
    "QuestionnaireTemplateId": 300100562877048,
    "sections": [
        {
            "SectionId": 300100562894477,
            "SectionName": "Section 1",
            "SectionSequenceNumber": 100,
            "QuestionOrder": "V",
            "ResponseOrder": "V",
            "Mandatory": "N",
            "RandomSampleSize": null,
            "questions": [
                {
                    "QuestionnaireQuestionId": 300100562894478,
                    "QuestionId": 300100562878913,
                    "QuestionCode": "WORK_PREFERENCE_CHOICE",
                    "VersionNumber": 1,
                    "QuestionType": "1CHOICE",
                    "ResponseType": null,
                    "MandatoryFlag": false,
                    "ResponseOrder": null,
                    "SampleSize": null,
                    "ControllingQuestionId": null,
                    "ControllingQuestionCode": null,
                    "ControllingAnswerId": null,
                    "ControllingAnswerCode": null,
                    "MaximumPossibleScore": null,
                    "MaximumThresholdScore": null,
                    "MinimumThresholdScore": null,
                    "SequenceNumber": 10192,
                    "Status": "A",
                    "ResponseMaximumLength": null,
                    "ResponseMinimumLength": null,
                    "MaximumResponses": null,
                    "MinimumResponses": null,
                    "links": [
                        {
                           ...}
                    ]
                },
                {
                    "QuestionnaireQuestionId": 300100562894479,
                    "QuestionId": 300100562878978,
                    "QuestionCode": "REMOTE_EXPERIENCE",
                    "VersionNumber": 1,
                    "QuestionType": "TEXT",
                    "ResponseType": null,
                    "MandatoryFlag": false,
                    "ResponseOrder": null,
                    "SampleSize": null,
                    "ControllingQuestionId": null,
                    "ControllingQuestionCode": null,
                    "ControllingAnswerId": null,
                    "ControllingAnswerCode": null,
                    "MaximumPossibleScore": null,
                    "MaximumThresholdScore": null,
                    "MinimumThresholdScore": null,
                    "SequenceNumber": 20384,
                    "Status": "A",
                    "ResponseMaximumLength": null,
                    "ResponseMinimumLength": null,
                    "MaximumResponses": null,
                    "MinimumResponses": null,
                    "links": [
                        {...
                             }
                    ]
    ]
}

Review a Questionnaire

Shan then reviews the questionnaire that he set up.

To review the questionnaire:

Perform a GET operation on the questionnaires resource, using a query parameter such as QuestionnaireCode to query the data.
Verify the questionnaire details returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/questionnaires?q=QuestionnaireCode=work_pref_survey_01;VersionNumber=1&fields=*

Example Response

Here's an example of the response body in JSON format.

{
    "items": [
        {
            "QuestionnaireId": 300100562894476,
            "QuestionnaireName": "Work Preference Survey",
            "QuestionnaireCode": "work_pref_survey_01",
            "Description": "Employee Work Preference questionnaire.",
            "VersionNumber": 1,
            "VersionDescription": null,
            "SubscriberId": 15,
            "SubscriberCode": "GSVY",
            "SubscriberName": "General Surveys",
            "FolderId": 31,
            "FolderName": "General Surveys",
            "ScoreQuestionnaireFlag": false,
            "Status": "A",
            "StatusMeaning": "Active",
            "Editor": null,
            "EditorPersonNumber": null,
            "InUse": "N",
            "InUseMeaning": "No",
            "PrivacyFlag": false,
            "PrivacyMeaning": "Public",
            "CalculationRule": "SUM",
            "CalculationRuleMeaning": "Sum",
            "InstructionText": null,
            "SectionOrder": "S",
            "SectionOrderMeaning": "Sequential",
            "SectionPresentation": "N",
            "SectionPresentationMeaning": "No Sections",
            "MaximumPossibleScore": null,
            "LatestVersionFlag": true,
            "QuestionnaireTemplateId": 300100562877048,
            "QuestionnaireTemplateCode": "Work_Prefer_Template",
            "QuestionnaireTemplateName": "Work_Prefer_Template",
            "CreatedBy": "SCILIC",
            "CreationDate": "2021-11-29T06:07:08+00:00",
            "LastUpdatedBy": "SCILIC",
            "LastUpdateDate": "2021-11-29T06:07:08.764+00:00",
            "links": [
               {...
                   }
            ]
}

Post Responses to a Questionnaire

Shan publishes the survey questionnaire link to specific employees who then provide their responses using the customer UI layer. He then posts these responses from the UI layer to Oracle HCM Cloud.

To post the responses to Oracle HCM Cloud:

Perform a POST operation on the questionnaireParticipants resource using the responses provided by the employee.
Verify the employee response details returned in the response. Responses are recorded for the logged in user or the employee performing this operation.

Note:

Text responses are provided in a base-64 encoded format.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/questionnaireParticipants

Example Request

Here's an example of the request body in JSON format.

{
    "QuestionnaireCode": "work_pref_survey_01",
    "ParticipantNumber": "5",
    "SubscriberCode": "GSVY",
    "questionnaireResponses": [
        {
            "QuestionnaireVersionNumber": 1,
            "Status": "S",
            "questionResponses": [
                {
                    "QuestionCode": "REMOTE_EXPERIENCE",
                    "AnswerLargeObject": "Tm90IGFmZmVjdGVkIHdpdGggY292aWQ="
                },
                {
                    "QuestionCode": "WORK_PREFERENCE_CHOICE",
                    "AnswerCode": "6040"
                }
            ]
        }
    ]
}

Example Response

Here's an example of the response body in JSON format.

{
    "QuestionnaireParticipantId": 300100562920300,
    "QuestionnaireId": 300100562894476,
    "QuestionnaireCode": "work_pref_survey_01",
    "QuestionnaireName": "Work Preference Survey",
    "ParticipantType": "PERSON",
    "ParticipantId": "5",
    "ParticipantName": "Walker, Mr. Kenneth (Ken)",
    "ParticipantNumber": "5",
    "SubscriberId": 15,
    "Status": "I",
    "questionnaireResponses": [
        {
            "QuestionnaireResponseId": 300100562920301,
            "QuestionnaireVersionNumber": 1,
            "AttemptNumber": 1,
            "Status": "S",
            "SubmittedDateTime": "2021-11-29",
            "TotalScore": 0,
            "LatestAttemptFlag": true,
            "questionResponses": [
                {
                    "QuestionResponseId": 300100562920302,
                    "QuestionnaireQuestionId": 300100562894479,
                    "QuestionCode": "REMOTE_EXPERIENCE",
                    "QuestionText": "Share your experience of our IT tools and support when working remotely, if you have worked remotely before.",
                    "QuestionAnswerId": null,
                    "AnswerCode": null,
                    "AnswerList": null,
                    "AnswerCodeList": null,
                    "Score": null,
                    "ChoiceCodeList": null,
                    "links": [
                        {
                           ...}
                    ]
                },
                {
                    "QuestionResponseId": 300100562920303,
                    "QuestionnaireQuestionId": 300100562894478,
                    "QuestionCode": "WORK_PREFERENCE_CHOICE",
                    "QuestionText": "Choose your work location preference?",
                    "QuestionAnswerId": 300100562878976,
                    "AnswerCode": "6040",
                    "AnswerList": "300100562878976;",
                    "AnswerCodeList": "6040;",
                    "Score": null,
                    "ChoiceCodeList": null,
                    "links": [
                        {
                          ...}
                    ]
            ]
}

Review Posted Responses

Shan now reviews the posted responses for the employees that he has access to. Note that responses are secure and can only be accessed by users who have the appropriate person security profile.

To review the posted responses:

Perform a GET operation on the questionnaireParticipants resource, using a query parameter such as QuestionnaireCode to query the data.
Verify the employee response details returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/questionnaireParticipants?q=QuestionnaireCode=work_pref_survey_01

Example Response

Here's an example of the response body in JSON format.

{
    "items": [
        {
            "QuestionnaireParticipantId": 300100562920300,
            "QuestionnaireId": 300100562894476,
            "QuestionnaireCode": "work_pref_survey_01",
            "QuestionnaireName": "Work Preference Survey",
            "ParticipantType": "PERSON",
            "ParticipantId": "5",
            "ParticipantName": "Walker, Mr. Kenneth (Ken)",
            "ParticipantNumber": "5",
            "SubscriberId": 15,
            "Status": "I",
            "links": [
                {
                  ...}
            ]
        }
}