Skip to main content

​
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:
ParameterTypeDescription
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.
challengeChallengeRequired. The related Challenge object.
completedOnIntOptional. A timestamp when the attempt has been completed. Will be empty if the attempt is still in progress.
correctAnswersNumberIntRequired. 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.
higherThanScorePercentageIntOptional. 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.
idIDRequired. The challenge attempt ID.
progressIntRequired. The attempt progress. Shows the percentage of the already answered questions.
rankIntOptional. 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.
scoreFloatRequired. The total number of points that is earned by the related API user for the challenge.
timeSpentIntOptional. 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 IDDescriptionCorresponding mutation/query
NEXT_CHALLENGE_QUESTIONAllows to get the next challenge question. Available if the attempt is still in progress.getChallengeNextQuestion
VIEW_CHALLENGE_RESULTSAllows 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:
  1. The user context is associated with an authenticated scope;
  2. The challenge is available for the current API user’s hierarchy level;
  3. The requested challenge is published and ongoing (the current date should be between start and end dates);
  4. 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
        }
      }
    }
  }
}

​
Challenge question

A challenge question is represented in Opigno Enterprise API by ChallengeQuestion object:
ParameterTypeDescription
answerAlternatives[KeyValuePair]Required. The list of the available answer alternatives; ordered according to the question settings in the backoffice.
domainTaxonomyTermRequired. A domain taxonomy term the question relates to.
idIDRequired. The question ID.
imageMediaImageOptional. The question illustrative image (if added in the backoffice).
questionStringRequired. The question description. Can contain an HTML markup.
timeLimitIntRequired. A max time (in seconds) for a user to provide an answer for the question.
titleStringRequired. 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 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
  }
}

​
Submit answer

To submit a challenge answer, execute the saveChallengeQuestionAnswer mutation. It has one argument - answerData:
ParameterTypeDescription
challengeIdIDRequired. ID of the related challenge.
questionIdIDRequired. ID of the question that is being answered.
answerKeyIDOptional. The key of the selected answer alternative. If empty, the question will be considered as skipped.
timeSpentIntRequired. 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({challengeId: 1, questionId: 4, answerKey: 'q8NPVbBJ', timeSpent: 8}) {
    errors
    response {
      givenAnswer
      correctAnswer
      isCorrect
      score
      attempt {
        cta {
          actionId
        }
      }
    }
  }
}
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.

Authentication

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