Take a challenge

Challenge attempt

Once a challenge is started, attempt is created and can be used to track the completion results. In Opigno Enterprise API it is represented as a ChallengeAttempt object:

Parameter	Type	Description
`answers`	`[ChallengeQuestionAnswer]`	Optional. The list of user’s answers for the challenge questions. Displaying of the answers should be enabled in the challenge; otherwise an empty list will be returned.
`challenge`	`Challenge`	Required. The related `Challenge` object.
`completedOn`	`Int`	Optional. A timestamp when the attempt has been completed. Will be empty if the attempt is still in progress.
`correctAnswersNumber`	`Int`	Required. The general number of correct answers provided by the user in the current challenge attempt.
`cta`	`[Cta]`	Optional. The list of available Call To Action objects for the challenge attempt.
`higherThanScorePercentage`	`Int`	Optional. The relative user score. Returns the percentage that represents the number of challenge participants with the lower score than the was earned in the current attempt. Will be empty if the attempt is not finished yet or if the ranking displaying is not enabled in the related challenge. For example, if the returned value is 75, it means that the score earned in the attempt is higher than the score in 75% of attempts for this challenge.
`id`	`ID`	Required. The challenge attempt ID.
`progress`	`Int`	Required. The attempt progress. Shows the percentage of the already answered questions.
`rank`	`Int`	Optional. The attempt rank in the related challenge. Will be empty if the attempt is still in progress, OR if ranking displaying is disabled in the challenge.
`score`	`Float`	Required. The total number of points that is earned by the related API user for the challenge.
`timeSpent`	`Int`	Optional. The time (in seconds) that the user spent answering the related challenge questions.

Challenge attempt CTA

The list of available CTAs can differ depending on the attempt status.

Action ID	Description	Corresponding mutation/query
`NEXT_CHALLENGE_QUESTION`	Allows to get the next challenge question. Available if the attempt is still in progress.	`getChallengeNextQuestion`
`VIEW_CHALLENGE_RESULTS`	Allows to view a challenge results. Available when the challenge attempt is completed.	`getChallengeResult`

Create a challenge attempt

A challenge can be started by the current API user if the following conditions are met:

The user context is associated with an authenticated scope;
The challenge is available for the current API user’s hierarchy level;
The requested challenge is published and ongoing (the current date should be between start and end dates);
A challenge cannot be restarted. If another attempt for the current API user exists, an error will be returned.

If a challenge can be taken by the current API user, CTA CREATE_CHALLENGE_ATTEMPT will be returned in the corresponding Challenge object. To start a challenge, execute the createChallengeAttempt mutation:

mutation createChallengeAttempt {
  createChallengeAttempt(challengeId: 1) {
    errors
    response {
      id
      cta {
        actionId
        title
        arguments {
          key
          value
        }
      }
    }
  }
}

{
  "data": {
    "createChallengeAttempt": {
      "errors": [],
      "response": {
        "id": "14",
        "cta": [
          {
            "actionId": "NEXT_CHALLENGE_QUESTION",
            "title": "Next question",
            "arguments": [
              {
                "key": "challengeId",
                "value": "1"
              }
            ]
          }
        ]
      }
    }
  }
}

Challenge question

A challenge question is represented in Opigno Enterprise API by ChallengeQuestion object:

Parameter	Type	Description
`answerAlternatives`	`[KeyValuePair]`	Required. The list of the available answer alternatives; ordered according to the question settings in the backoffice.
`domain`	`TaxonomyTerm`	Required. A domain taxonomy term the question relates to.
`id`	`ID`	Required. The question ID.
`image`	`MediaImage`	Optional. The question illustrative image (if added in the backoffice).
`question`	`String`	Required. The question description. Can contain an HTML markup.
`timeLimit`	`Int`	Required. A max time (in seconds) for a user to provide an answer for the question.
`title`	`String`	Required. The question title.

Get next question

Once a challenge started and attempt created, challenge questions are available for the user and can be retrieved one by one, by execution of getNextChallengeQuestion query. In case if the randomization enabled for a challenge, questions will be returned in a random order.

Unlike training activities, challenge questions will be returned not as iframe, but as a ChallengeQuestion object. The question form should and the answer submission should be implemented on the frontend.

Here is an example of the query execution:

query getChallengeNextQuestion {
  getChallengeNextQuestion(challengeId: 1) {
    id
    title
    question
    answerAlternatives {
      key
      value
    }
    image {
      alt
      title
      url
    }
    timeLimit
  }
}

{
  "data": {
    "getChallengeNextQuestion": {
      "id": "4",
      "title": "Select the correct answer",
      "question": "What is the capital of Switzerland?",
      "answerAlternatives": [
        {
          "key": "ucqGu5UP",
          "value": "Geneva"
        },
        {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        {
          "key": "u1WrLxkW",
          "value": "Zurich"
        },
        {
          "key": "tVruIvyD",
          "value": "Basel"
        },
        {
          "key": "kor2EIrI",
          "value": "Lausanne"
        }
      ],
      "image": null,
      "timeLimit": 30
    }
  }
}

Submit the answer

To submit a challenge answer, execute the saveChallengeQuestionAnswer mutation. It has one argument - answerData:

Parameter	Type	Description
`challengeId`	`ID`	Required. ID of the related challenge.
`questionId`	`ID`	Required. ID of the question that is being answered.
`answerKey`	`ID`	Optional. The key of the selected answer alternative. If empty, the question will be considered as skipped.
`timeSpent`	`Int`	Required. The time that was spent to provide the answer. If the time spent is greater than the limit that is set in the question settings, the question will be considered as skipped.

Here is an example of the mutation execution:

mutation saveChallengeQuestionAnswer {
  saveChallengeQuestionAnswer(answerData: {challengeId: 1, questionId: 4, answerKey: 'q8NPVbBJ', timeSpent: 8}) {
    errors
    response {
      givenAnswer {
        key
        value
      }
      correctAnswer {
        key
        value
      }
      isCorrect
      score
      attempt {
        cta {
          actionId
        }
      }
    }
  }
}

{
  "data": {
    "saveChallengeQuestionAnswer": {
      "errors": [],
      "response": {
        "givenAnswer": {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        "correctAnswer":  {
          "key": "q8NPVbBJ",
          "value": "Bern"
        },
        "isCorrect": true,
        "score": 10,
        "attempt": {
          "cta": [
            {
              "actionId": "NEXT_CHALLENGE_QUESTION"
            }
          ]
        }
      }
    }
  }
}

After the successful execution of the mutation, ChallengeQuestionAnswer object will be returned. When the answer for the last question is submitted, a challenge attempt will be automatically closed, and the user will be able to check their results.

`ChallengeQuestionAnswer` object

A question answer is represented in Opigno Enterprise API as a ChallengeQuestionAnswer object:

Parameter	Type	Description
`attempt`	`ChallengeAttempt`	Required. The related challenge attempt.
`correctAnswer`	`KeyValuePair`	Required. The correct answer.
`givenAnswer`	`KeyValuePair`	Optional. The given answer.
`id`	`ID`	Required. The answer ID.
`isCorrect`	`Boolean`	Required. A marker that indicates if the provided answer is correct or not.
`question`	`ChallengeQuestion`	Required. The related question.
`score`	`Float`	Required. The number of points that the user got for the answer.
`timeSpent`	`Int`	Required. The time (in seconds) that is spent by the user to provide an answer for the related question.

Authentication

Understand the authentication requirements and how to properly authenticate your requests.

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Take a challenge

Challenge attempt

Challenge attempt CTA

Create a challenge attempt

Challenge question

Get next question

Submit the answer

`ChallengeQuestionAnswer` object

Authentication

​Challenge attempt

​Challenge attempt CTA

​Create a challenge attempt

​Challenge question

​Get next question

​Submit the answer

​ChallengeQuestionAnswer object

​Related Features

Authentication

Challenge attempt

Challenge attempt CTA

Create a challenge attempt

Challenge question

Get next question

Submit the answer

`ChallengeQuestionAnswer` object

Related Features