api.md

Scrum Game API

Table of Contents

• Query
• Mutation
• Objects
  • Assignment
  • AssignmentCompletedFeedback
  • AssignmentMutation
  • CodeAssignmentGradingMetadata
  • CodeAssignmentMetadata
  • Exercise
  • ExerciseGrading
  • ExternalAssignment
  • ExternalCourse
  • Grading
  • ManualMappingInstance
  • PaginationInfo
  • StudentMapping
  • Subexercise
  • SubexerciseGrading
  • UnfinishedGrading
• Inputs
  • CreateAssignmentInput
  • CreateExerciseInput
  • CreateSubexerciseInput
  • DateTimeFilter
  • ExerciseCompletedInput
  • IntFilter
  • LogAssignmentCompletedInput
  • Pagination
  • StringFilter
  • StudentMappingInput
  • SubexerciseCompletedInput
  • UpdateAssignmentInput
  • UpdateExerciseInput
  • UpdateSubexerciseInput
• Enums
  • AssignmentType
  • SortDirection
• Scalars
  • Boolean
  • Date
  • DateTime
  • Float
  • Int
  • LocalTime
  • String
  • Time
  • UUID
  • Url

Query

Field	Argument	Type	Description
findAssignmentsByAssessmentIds		[Assignment]!	Get assignment by assessment ID. If any of the assessment IDs are not found, the corresponding assignment will be null. 🔒 The user must be enrolled in the course the assignments belong to to access them. Otherwise null is returned for an assignment if the user has no access to it.
assessmentIds		[UUID!]!
getGradingsForAssignment		[Grading!]!	Get all gradings for one assignment 🔒 The user must be an admin in the course the assignment belongs to to access them. Otherwise null is returned for an assignment if the user has no access to it.
assessmentId		UUID!
getExternalAssignments		[ExternalAssignment!]!	Gets all the available external exercises. CourseId is the id of the course the user is currently working in. 🔒 The user must be an admin in the course. Otherwise null is returned.
courseId		UUID!
getExternalCodeAssignments		[String!]!	Gets all the available external code exercises. CourseId is the id of the course the user is currently working in. 🔒 The user must be an admin in the course. Otherwise null is returned.
courseId		UUID!
getExternalCourse		ExternalCourse	Get the corresponding external course for the given courseId. CourseId is the id of the course the user is currently working in. 🔒 The user must be an admin in the course. Otherwise null is returned.
courseId		UUID!
getManualMappingInstances		[ManualMappingInstance]!	Gets all manual student mappings, i.e. all students where the backend could not map to a meitrex user. 🔒 The user must be an admin in the course. Otherwise null is returned.
courseId		UUID!

Mutation

Mutations for the assignment service. Provides mutations for creating, updating, and deleting assignments.

Field	Argument	Type	Description
_internal_noauth_createAssignment		Assignment!	Creates a new assignment. Mutation is only accessible internally within the system by other services and the gateway. ⚠️ This mutation is only accessible internally in the system and allows the caller to create assignments without any permissions check and should not be called without any validation of the caller's permissions. ⚠️
courseId		UUID!
assessmentId		UUID!
input		CreateAssignmentInput!
updateAssignment		Assignment!	Update top-level fields of an assignment. 🔒 The user must be an admin in the course the assignment belongs to.
assessmentId		UUID!
input		UpdateAssignmentInput!
mutateAssignment		AssignmentMutation!	Modify an assignment. 🔒 The user must be an admin in the course the assignment is in to perform this action.
assessmentId		UUID!
logAssignmentCompleted		AssignmentCompletedFeedback!	Logs that a user's assignment score has been imported, i.e. the user has completed the assignment. 🔒 The user must be a tutor in the course the assignment is in to perform this action.
input		LogAssignmentCompletedInput!
saveStudentMappings		[String]!	Saves mappings of meitrex users to external students. Used to deal with ManualMappingInstances. Returns list of all deleted ManualMappingInstance ids. Returns null if connection to UserService failed. 🔒 The user must be an admin in the course to perform this action.
courseId		UUID!
studentMappingInputs		[StudentMappingInput!]!
syncAssignmentsForCourse		Boolean!	Fetches assignment info from external code assessment provider for the given course
courseId		UUID!

Objects

Assignment

An assignment is an external source of tasks, which can be imported. This includes exercise sheets and physical tests.

Field	Argument	Type	Description
assessmentId		UUID!	Identifier of the assignment, same as the identifier of the assessment.
courseId		UUID!	Id of the course this assignment belongs to.
exercises		[Exercise!]	List of exercises making up the assignment. Optional for CODE_ASSIGNMENT since GH Classroom does not provide exercises.
date		DateTime	The date at which the assignment had to be handed in (optional).
totalCredits		Float	Number of total credits in the assignment.
assignmentType		AssignmentType!	Type of the assignment, e.g. exercise sheet or physical test.
description		String	Description of the assignment (optional).
requiredPercentage		Float	The required percentage to pass the assignment. A value between 0 and 1. Defaults to 0.5. (optional)
externalId		String	The id of the exercise sheet in an external system like TMS. (optional) This is needed for mapping grading data to assignments.
codeAssignmentMetadata		CodeAssignmentMetadata	CodeAssignmentMetadata contains metadata for the external code assignment.

AssignmentCompletedFeedback

Feedback data when "logAssignmentCompleted" is called.

Field	Argument	Type	Description
success		Boolean!	Whether the assignment was passed or not.
correctness		Float!	The percentage of achieved credits compared to total credits.

AssignmentMutation

Field	Argument	Type	Description
assessmentId		UUID!	ID of the assignment that is being modified.
createExercise		Exercise!	Creates a new exercise. Throws an error if the assignment does not exist.
input		CreateExerciseInput!
updateExercise		Exercise!	Updates an exercise. Throws an error if the exercise does not exist.
input		UpdateExerciseInput!
deleteExercise		UUID!	Deletes the exercise with the specified ID. Throws an error if the exercise does not exist.
itemId		UUID!
createSubexercise		Subexercise!	Creates a new subexercise. Throws an error if the assignment does not exist.
input		CreateSubexerciseInput!
updateSubexercise		Subexercise!	Updates a subexercise. Throws an error if the subexercise does not exist.
input		UpdateSubexerciseInput!
deleteSubexercise		UUID!	Deletes the subexercise with the specified ID. Throws an error if the subexercise does not exist.
itemId		UUID!

CodeAssignmentGradingMetadata

Field	Argument	Type	Description
repoLink		String	The repository link of for the external code assignment.
status		String	The pipeline status of the corresponding repository.
feedbackTableHtml		String	The Github worfklow run log table HTML of the corresponding repository.

CodeAssignmentMetadata

Field	Argument	Type	Description
assignmentLink		String	Link to the GitHub Classroom or equivalent (optional, CODE_ASSIGNMENT only).
invitationLink		String	Invitation link for students to join the assignment (optional, CODE_ASSIGNMENT only).
readmeHtml		String	README content in HTML format for the assignment (optional, CODE_ASSIGNMENT only).

Exercise

Field	Argument	Type	Description
itemId		UUID!	Unique identifier of the exercise and the id of the corresponding item
totalExerciseCredits		Float!	The amount of credits that can be earned on this exercise including all sub-exercises.
subexercises		[Subexercise!]!	Sub-exercises making up the exercise, i.e. parts a),b),c),...
number		String	The number of the exercise on the exercise sheet, may be something such as 2 (optional).
tutorFeedback		String	Feedback given by a tutor on the exercise (optional).

ExerciseGrading

Field	Argument	Type	Description
itemId		UUID!	ID of the exercise.
studentId		UUID!	ID of the student the exercise-grading belongs to.
achievedCredits		Float!	The absolute number of achieved credits on the exercise.
subexerciseGradings		[SubexerciseGrading]!	List of subexercise-gradings for each subexercise in the exercise. Can be empty, if there are no subexercises within the exercise.

ExternalAssignment

An external Assignment such as the ones from TMS. These are needed for mapping Meitrex Assignments to external ones for importing gradings.

Field	Argument	Type	Description
externalId		String!
sheetNo		Float!

ExternalCourse

Field	Argument	Type	Description
courseTitle		String!	The name of the course.
url		String!	The url to the course.
organizationName		String!	The Github organization name the classroom belongs to.

Grading

A grading contains a user's achieved credits on an assignment and its exercises and subexercises.

Field	Argument	Type	Description
assessmentId		UUID!	ID of the assignment.
studentId		UUID!	ID of the student the grading belongs to.
date		DateTime	The date and time of when the tutor corrected the assignment.
achievedCredits		Float	The absolute number of achieved credits on the assignment.
codeAssignmentGradingMetadata		CodeAssignmentGradingMetadata	CodeAssignmentGradingMetadata contains metadata for the external code assignment grading.
exerciseGradings		[ExerciseGrading!]	List of exercise-gradings for each exercise in the assignment. Can be empty, if there are no exercises within the assignment.

ManualMappingInstance

An object to represent a student where the backend could not automatically map the external student to a meitrex user.

Field	Argument	Type	Description
externalStudentId		String!	Student Id in external system like TMS
externalStudentInfo		String!	JSON Object containing all available information on the external student.

PaginationInfo

Return type for information about paginated results.

Field	Argument	Type	Description
page		Int!	The current page number.
size		Int!	The number of elements per page.
totalElements		Int!	The total number of elements across all pages.
totalPages		Int!	The total number of pages.
hasNext		Boolean!	Whether there is a next page.

StudentMapping

Field	Argument	Type	Description
meitrexStudentId		UUID!	Student Id in Meitrex
externalStudentId		String!	Student Id in external system like TMS

Subexercise

Field	Argument	Type	Description
itemId		UUID!	Unique identifier of the exercise and the id of the corresponding item
totalSubexerciseCredits		Float!	The amount of credits that can be earned on this sub-exercise.
number		String	The number of the exercise on the exercise sheet, may be something such as 2b (optional).
tutorFeedback		String	Feedback given by a tutor on the exercise (optional).

SubexerciseGrading

Field	Argument	Type	Description
itemId		UUID!	ID of the subexercise.
studentId		UUID!	ID of the student the subexercise-grading belongs to.
achievedCredits		Float!	The absolute number of achieved credits on the subexercise.

UnfinishedGrading

An Unfinished Grading is created, when importing and parsing gradings from external systems like TMS goes wrong because the student id has to be mapped manually. After an admin mapped ids manually, these unfinished gradings will be tried again.

Field	Argument	Type	Description
externalStudentId		String!	Student Id in external system like TMS
assignmentId		UUID!	Assignment/HandIn id in MEITREX
gradingJson		String!	JSON representation of the grading
numberOfTries		Int!	The number of times importing and parsing was tried. Might be useful for detecting and manually deleting broken gradings.

Inputs

CreateAssignmentInput

Field		Type	Description
totalCredits		Float	Number of total credits in the assignment. Optional for CODE_ASSIGNMENT. Can be set later when grades are available.
exercises		[CreateExerciseInput!]	List of exercises in this Assignment Optional for CODE_ASSIGNMENT since GH Classroom does not provide exercises.
assignmentType		AssignmentType!	Type of the assignment, e.g. exercise sheet or physical test.
date		DateTime	The date at which the assignment had to be handed in (optional).
description		String	Description of the assignment (optional).
requiredPercentage		Float	The required percentage to pass the assignment. A value between 0 and 1. Defaults to 0.5. (optional)
externalId		String	The id of the exercise sheet in an external system like TMS. (optional) This is needed for mapping grading data to assignments.

CreateExerciseInput

Field		Type	Description
itemId		UUID!	the id of the item the exercise belongs to
totalExerciseCredits		Float!	The amount of credits that can be earned on this exercise including all sub-exercises. (Positive or zero)
subexercises		[CreateSubexerciseInput!]!	Sub-exercises making up the exercise, i.e. parts a),b),c),...
number		String	The number of the exercise on the exercise sheet, may be something such as 2 (optional).

CreateSubexerciseInput

Field		Type	Description
itemId		UUID!	the id of the item the subexercise belongs to
parentExerciseId		UUID!	the id of the exercise this subexercise belongs to
totalSubexerciseCredits		Float!	The amount of credits that can be earned on this sub-exercise. (Positive or zero)
number		String	The number of the exercise on the exercise sheet, may be something such as 2b (optional).

DateTimeFilter

Filter for date values. If multiple filters are specified, they are combined with AND.

Field		Type	Description
after		DateTime	If specified, filters for dates after the specified value.
before		DateTime	If specified, filters for dates before the specified value.

ExerciseCompletedInput

Field		Type	Description
itemId		UUID!	ID of the exercise.
achievedCredits		Float!	The absolute number of achieved credits.
completedSubexercises		[SubexerciseCompletedInput]!	List of subexercises that were completed in the exercise. Can be empty, if there are no subexercises within the exercise.

IntFilter

Filter for integer values. If multiple filters are specified, they are combined with AND.

Field		Type	Description
equals		Int	An integer value to match exactly.
greaterThan		Int	If specified, filters for values greater than to the specified value.
lessThan		Int	If specified, filters for values less than to the specified value.

LogAssignmentCompletedInput

Field		Type	Description
assessmentId		UUID!	ID of the assignment.
achievedCredits		Float!	The absolute number of achieved credits.
completedExercises		[ExerciseCompletedInput]!	List of exercises that were completed in the assignment. Can be empty, if there are no exercises within the assignment.

Pagination

Specifies the page size and page number for paginated results.

Field		Type	Description
page		Int!	The page number, starting at 0. If not specified, the default value is 0. For values greater than 0, the page size must be specified. If this value is larger than the number of pages, an empty page is returned.
size		Int!	The number of elements per page.

StringFilter

Filter for string values. If multiple filters are specified, they are combined with AND.

Field		Type	Description
equals		String	A string value to match exactly.
contains		String	A string value that must be contained in the field that is being filtered.
ignoreCase		Boolean!	If true, the filter is case-insensitive.

StudentMappingInput

Field		Type	Description
meitrexStudentId		UUID!	Student Id in Meitrex
externalStudentId		String!	Student Id in external system like TMS

SubexerciseCompletedInput

Field		Type	Description
itemId		UUID!	ID of the subexercise.
achievedCredits		Float!	The absolute number of achieved credits.

UpdateAssignmentInput

Field		Type	Description
requiredPercentage		Float

UpdateExerciseInput

Field		Type	Description
itemId		UUID!	Id of the exercise to update.
totalExerciseCredits		Float!	The amount of credits that can be earned on this exercise including all sub-exercises. (Positive or zero)
subexercises		[CreateSubexerciseInput!]!	Sub-exercises making up the exercise, i.e. parts a),b),c),...
number		String	The number of the exercise on the exercise sheet, may be something such as 2 (optional).

UpdateSubexerciseInput

Field		Type	Description
itemId		UUID!	Id of the subexercise to update.
totalSubexerciseCredits		Float!	The amount of credits that can be earned on this sub-exercise. (Positive or zero)
number		String	The number of the exercise on the exercise sheet, may be something such as 2b (optional).

Enums

AssignmentType

The type of assignment.

Value	Description
EXERCISE_SHEET
PHYSICAL_TEST
CODE_ASSIGNMENT

SortDirection

Specifies the sort direction, either ascending or descending.

Value	Description
ASC
DESC

Scalars

Boolean

The Boolean scalar type represents true or false.

Date

DateTime

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

LocalTime

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Time

UUID

Url