# Buzz API — Complete Command Reference All commands are documented below. For individual command pages and navigation, see [/llms.txt](/llms.txt). ## Calling the API - **Endpoint:** issue each command as `POST https://backgroundapi.agilixbuzz.com/cmd?cmd=` (GET is accepted for read-only commands). - **Format:** send and request JSON — set `Content-Type: application/json` and `Accept: application/json`. Wrap a single command in `{"request": { ... }}`; wrap a batch in `{"requests": { "": [ ... ] }}`. - **Authentication:** every command except a few public ones (e.g. GetStatus) requires an authentication token, passed as an `Authorization: Bearer ` header. (Where a header cannot be sent, put `_token` in the XML/JSON POST body; use the `_token=` query parameter only for contexts like browser-embedded resource URLs, because URLs are recorded in logs.) API integrations should obtain tokens via [OAuth 2.0 Application Identity](https://api.agilixbuzz.com/docs/entry/Concept/OAuth.md); see [Command Usage](https://api.agilixbuzz.com/docs/entry/Concept/CommandUsage.md) for the details. - **Responses:** every response is `{"response": {"code": "OK", ...}}`; a `code` other than `OK` indicates failure (read `message`). Batch commands return a parallel `responses.response[]` list, each with its own `code`. Always check the HTTP status as well. - **Reference:** [Command Usage](https://api.agilixbuzz.com/docs/entry/Concept/CommandUsage.md) · [Entity IDs](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) · [HTTP Status Codes](https://api.agilixbuzz.com/docs/entry/Concept/HttpResponseStatusCodes.md) --- # AddGroupMembers This command adds one or more member enrollments to an existing group. ## Request **Method:** POST **Rights:** ControlCourse|UpdateCourse|SetupGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `addgroupmembers` | **Request body (JSON):** ```json { "requests": { "member": [ { "groupid": "id", "courseid": "id", "enrollmentid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `member.groupid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the group to add members to. | | `member.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Schema 4+: ID of the owning course. When present, groupid is interpreted as a string group identifier within the course data rather than a group entity ID. | | `member.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the enrollment to add to the group. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GroupEntityMembersChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityMembersChanged.md) | During the request | Once per group whose membership the request changes. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Adds two enrollments to the group with ID 204235. **URL:** `?cmd=addgroupmembers` **Request body:** ```json { "requests": { "member": [ { "groupid": "204235", "enrollmentid": "177932" }, { "groupid": "204235", "enrollmentid": "177933" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [RemoveGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/RemoveGroupMembers.md) --- # AssignItem Assigning an item to a folder changes the item’s parent and sequence to the specified values. You may assign the *itemid* item to the *folderid* item if: - The *itemid* item is one of *folderid*'s assignable items (you call ListAssignableItems to list the assignable items). - The *itemid* item has *studentcreated*=*true* and the *folderid* item has *assignallowstudentcreated*=*true*. You may not assign the *itemid* item to the *folderid* item if: - Your user does not have UpdateCourse@entityid and either the *itemid* is already assigned, or assigning the *itemid* item would assign more items to the *folderid* item than the sum of the folder's *assignableitemsrequired* and *assignableitemsoptional* attributes. - The *itemid* item has *studentcreated*=*true*, and the *folderid* item does not have *assignallowstudentcreated*=*true*. ## Request **Method:** POST **Rights:** UpdateCourse@entityid or (Participate@entityid and entityid refers to an enrollment and the current user is the enrollment's user) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `assignitem` | | `entityid` | id | Yes | ID of the entity that owns *folderid* and *itemid* items. | | `itemid` | string | Yes | Item ID of the item to assign. | | `folderid` | string | Yes | Item ID of folder to which *itemid* will be assigned. | | `sequence` | string | No | New sequence for the *itemid* item. If you do not supply a sequence, the item is assigned a sequence that places it last. | | `groupid` | string | No | Schema 4+: when entityid is a course, assigns the item within the context of the specified group, storing the assignment as a group-specific override. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemChanged.md) | During the request | Assigning an item changes it. | | [EnrollmentItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemChanged.md) | During the request | Assigning an item changes the student's copy of it. | | [EnrollmentItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemCreated.md) | During the request | Assigning an item to a specific student creates an enrollment item. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assigns item ABCD to the PRACTICE folder in the 1234 enrollment. **URL:** `?cmd=assignitem&entityid=1234&itemid=ABCD&folderid=PRACTICE` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [UnassignItem](https://api.agilixbuzz.com/docs/entry/Command/UnassignItem.md) - [ListAssignableItems](https://api.agilixbuzz.com/docs/entry/Command/ListAssignableItems.md) - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) --- # CalculateEnrollmentScenario This command calculates a rolled-up (category, period, and course) grade scenario for the specified user enrollment given the supplied input grades and grading scheme. ## Request **Method:** POST **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `calculateenrollmentscenario` | **Request body (JSON):** ```json { "requests": { "scenario": [ { "enrollmentid": "id", "gradingschemeid": "string", "zerounscored": "boolean", "grade": [ { "achieved": "double", "itemid": "string", "possible": "double" } ] } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `scenario.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of user for which to calculate grades. | | `scenario.gradingschemeid` | string | No | Identifies a grading scheme to use when calculating the scenario. Omit this attribute to use the default grading rules. | | `scenario.zerounscored` | boolean | No | Forces any unscored items to have a score of zero. | | `scenario.grade.achieved` | double | Yes | The points achieved for this item in the scenario. | | `scenario.grade.itemid` | string | Yes | The ID of the item this grade information pertains to. | | `scenario.grade.possible` | double | Yes | The points possible for this item in the scenario. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "grades": {} } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### grades This node conforms to the Grades format. ## Example This example retrieves grade calculations for the following scenario applied to the enrollment with ID 6165. **URL:** `?cmd=calculateenrollmentscenario` **Request body:** ```json { "request": { "requests": { "scenario": [ { "enrollmentid": "6165", "zerounscored": true, "grade": [ { "itemdid": "E1", "achieved": 90, "possible": 100 }, { "itemiid": "S1", "achieved": 93, "possible": 100 } ] } ] } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": { "code": "OK", "grades": { "achieved": 91.5, "possible": 100, "letter": "A", "passingscore": 0.7, "complete": 1, "seconds": 63, "items": { "item": [ { "itemid": "E1", "title": "Exam", "periodid": "0", "status": "261", "scoreddate": "xxx", "achieved": 90, "possible": 100, "letter": "A", "duedate": "2014-01-01T12:34:59Z" }, { "itemid": "S1", "title": "Sco", "periodid": "0", "status": "261", "scoreddate": "xxx", "achieved": 93, "possible": 100, "letter": "A", "duedate": "2019-01-01T12:34:59Z" } ] }, "categories": { "category": [ { "id": "1", "name": "Include", "achieved": 183, "possible": 200, "letter": "A" }, { "id": "0", "name": "Exclude", "achieved": 0, "possible": 0 } ] } } } } } } ``` ## See Also - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) --- # CheckPasswordQuality This command checks the quality of the specified password to see if it has been part of a data breach and to estimate the password's overall complexity. Currently an entropy of about 45 bits should be used for systems where security is important. A 64KB random ASCII password will have an entropy of around 300,000 bits. A 1KB random ASCII password will have an entropy of around 5,000 bits. A 100 character random ASCII password will have an entropy of around 450 bits. A 10 character random ASCII password will have an entropy of around 40 bits. ## Request **Method:** POST **Rights:** None when contextwords is supplied, and none when no domain is resolved at all. Otherwise any right on the domain whose policy supplies the context words: the domain of the user the session is acting as, or the specified domainid where the session has no domain of its own -- no user authenticated, or a token that is not connected to a session. **Request body (JSON):** ```json { "request": { "cmd": "checkpasswordquality", "password": "string", "contextwords": "string", "domainid": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `checkpasswordquality` | Yes | | | `password` | string | Yes | The password to test. | | `contextwords` | string | Yes | A comma-separated list of context words to use during the computation of the entropy. | | `domainid` | string | Yes | The id of the domain whose password policy is to be retrieved for context word inclusion, used when contextwords is not specified and the session has no domain of its own -- no user authenticated, or a token that is not connected to a session. A session that has a domain uses the domain of the user it is acting as, and this parameter is ignored. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "password": { "pwncount": "int", "entropybits": "float" } } } ``` ### password | Attribute | Type | Description | |-----------|------|-------------| | `pwncount` | int | The number of times this password has appeared in publicly available data breach password lists. | | `entropybits` | float | The estimated entropy of this password (in bits). IE. log\_2 of the number of guesses a hacker would need to make in order to get to this password. | ## Example Checks the quality of the specified password either in the context of the currently-logged-in user or outside of any context. **Request body:** ```json { "request": { "cmd": "checkpasswordquality", "password": "MyPasswordIsBetterThanYours!" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "password": { "pwncount": "0", "entropybits": "29.80" } } } ``` ## See Also - [PasswordPolicy Schema](https://api.agilixbuzz.com/docs/entry/Schema/PasswordPolicy.md) - [Login2](https://api.agilixbuzz.com/docs/entry/Command/Login2.md) - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # ClearSecondFactorAuthentication Clears 2FA (second factor authentication) settings for the specified user account, allowing the user to login without 2FA (the user will have to re-establish 2FA on the next login if 2FA is required by the domain's password policy or because of their role. ## Request **Method:** POST **Rights:** UpdateUser or self **Request body (JSON):** ```json { "request": { "cmd": "clearsecondfactorauthentication", "userid": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `clearsecondfactorauthentication` | Yes | | | `userid` | string | Yes | The ID of the user whose 2FA settings should be erased. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example clears the 2FA settings for the specified user account **Request body:** ```json { "request": { "cmd": "clearsecondfactorauthentication", "userid": "57297859" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [GetUser2](https://api.agilixbuzz.com/docs/entry/Command/GetUser2.md) - [CreateSecondFactorAuthenticationSecret](https://api.agilixbuzz.com/docs/entry/Command/CreateSecondFactorAuthenticationSecret.md) - [SetupSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/SetupSecondFactorAuthentication.md) - [SecondFactorAuthenticate](https://api.agilixbuzz.com/docs/entry/Command/SecondFactorAuthenticate.md) --- # CopyCourses This command copies one or more courses. CopyCourses automatically enrolls the calling user as the course owner unless *status* is 0 or the status is 10 and the user already has the requested rights on the course. ## Request **Method:** POST **Rights:** CreateCourse@domainid, when courseid.schema = 3 then ReadCourseFull@courseid or UpdateCourse@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `copycourses` | **Request body (JSON):** ```json { "requests": { "course": [ { "courseid": "id", "domainid": "id", "action": "(StaticCopy|DerivativeChildCopy|DerivativeSiblingCopy)", "depth": "int", "reference": "string", "status": "0|1|10", "roleid": "id", "title": "string", "type": "Continuous|Range", "startdate": "datetime", "enddate": "datetime", "days": "int", "term": "string", "indexrule": "IndexRule" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `course.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course to copy. | | `course.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain that will own the newly copied course. | | `course.action` | `(StaticCopy\|DerivativeChildCopy\|DerivativeSiblingCopy)` | No | Controls the new course's "course chaining" behavior, i.e., whether or not the destination course receives future content updates from the source course. Possible values are: - **StaticCopy** - Copy the course, but do not propogate any future changes in the source course to the destination course. - **DerivativeChildCopy** - Copy the course as a derivative of the source course. Any future changes in the source course propogate to the destination course. The source course becomes the destination course's base course, increasing the course-chain depth by one. - **DerivativeSiblingCopy** - Derives a course from the source course's immediate base course and then copies any deltas from the source course to the new course. The source course's base becomes the destination course's base, and the source course and the destination course become siblings in the course-chaining tree. This option is the most common for typical teaching scenarios: the newly copied course looks like the source course, the course-chain depth does NOT deepen, it remains small and course-load times remain optimal, and course updates flow from the base course to the derived course. The default is **StaticCopy**. See Derivative Courses for more details. | | `course.depth` | int | No | When action is **DerivativeChildCopy** this parameter controls which course the server selects as the base of the new course. It indicates how many ancestors in the source course's derivative chain to skip in order to select the base. If depth is 0, the default, the server will not skip any courses so the source course becomes the base of the new course. If depth is 1, the server skips the source course, and the base of the source course becomes the base of the new course. The server applies any deltas between the source course and its base to the new course so that the source and new course are identical. The **DerivativeSiblingCopy** action is equivalent to a depth of 1. With a depth of 2, the server skips 2 generations, and so forth. | | `course.reference` | string | No | Field reserved for any data the caller wishes to store on the new course. We recommend it be a unique reference, such as from an external SIS system. The default is empty (no reference value). | | `course.status` | `0\|1\|10` | No | EnrollmentStatus for the user in the new course. The only allowed values are **0** (None), **1** (Active), and **10** (Inactive), with 0 indicating that no owner enrollment should be created. The default is 10 (Inactive). | | `course.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the role to use to assign privileges to the owner enrollment. | | `course.title` | string | No | Title for the new course. The default is the source course's title. | | `course.type` | `Continuous\|Range` | No | The type of the new course. Range types have startdate and enddate but no days, while Continuous have days but no startdate nor enddate. The default is the source course's type. | | `course.startdate` | datetime | No | The startdate for the new course. Meaningful only when type is Range. The default is the source course's startdate. | | `course.enddate` | datetime | No | The end date for the new course. Meaningful only when type is Range. The default is the source course's enddate. | | `course.days` | int | No | The number of days a student has to complete the new course. Meaningful only when type is Continuous. The default is the source course's days. | | `course.term` | string | No | The academic term of the new course. The default is the source course's term. | | `course.indexrule` | [IndexRule](https://api.agilixbuzz.com/docs/entry/Enum/IndexRule.md) | No | An IndexRule value that controls whether this course's content is searchable with the Search2 command. The default is **0** (Nothing). | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "course": { "courseid": "id", "enrollmentid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### course | Attribute | Type | Description | |-----------|------|-------------| | `courseid` | id | ID for the new course. | | `enrollmentid` | id | *(optional)* ID for the new enrollment. This attribute is left out if the status specified was 0. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityCreated.md) | During the request | For each course copy that is created. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each content file copied into the new course. A full copy copies every content file; a derivative copy inherits its base's files and copies only the files its source course had overridden. | | [GroupItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupItemCreated.md) | During the request | For each group item copied into the destination course. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example makes a copy of the course with ID 8874 in the domain whose ID is 4378. **URL:** `?cmd=copycourses` **Request body:** ```json { "requests": { "course": [ { "domainid": "4378", "courseid": "8874" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "course": { "courseid": "6051", "enrollmentid": "6052" } } ] } } } ``` ## See Also - [Derivative Courses](https://api.agilixbuzz.com/docs/entry/Concept/CourseChaining.md) - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) --- # CopyItems This command copies one or more items from one course to another. It does not copy resources referred to by an item's Item Data, including rubric, attachment, and item-content resources. To copy them use CopyResources. ## Request **Method:** POST **Rights:** ReadCourse@sourceentityid when sourceentityid refers to a course; UpdateCourse@destinationentityid when destinationentityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `copyitems` | **Request body (JSON):** ```json { "requests": { "item": [ { "sourceentityid": "id", "sourceitemid": "string", "destinationentityid": "id", "destinationitemid": "string", "deep": "bool" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `item.sourceentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course or section that owns the item to copy. | | `item.sourceitemid` | string | Yes | ID of the item to copy. | | `item.destinationentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course or section of the new item. | | `item.destinationitemid` | string | Yes | ID of the new item. | | `item.deep` | bool | No | Indicates whether the server should copy resources, questions and other assets used by the item. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemCreated.md) | During the request | For each item created in the destination course. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | Only when the request specifies a deep copy: for each content file referenced by a copied item — attachments, templates, rubrics, question images — copied into the destination course. Items copied as links, or without deep, reference the source course's files and copy nothing. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example copies an item with ID "Assignment12" in the course whose ID is 4378 to the item with ID "Assignment13". **URL:** `?cmd=copyitems` **Request body:** ```json { "requests": { "item": [ { "sourceentityid": "4378", "sourceid": "Assignment12", "destinationentityid": "4378", "destinationid": "Assignment13" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # CopyResources This command copies one or more resources from the domain or course specified by sourceentityid to the domain or course specified by destinationentityid. ## Request **Method:** POST **Rights:** ReadDomain@sourceentityid when sourceentityid refers to a domain; ReadCourse@sourceentityid when sourceentityid refers to a course; UpdateDomain@destinationentityid when destinationentityid refers to a domain; UpdateCourse@destinationentityid when destinationentityid refers to a course. The copy requires genuine read authority on the source: read authority reachable only through self or membership access (for example a caller's own user entity or their own enrollment) does not authorize a copy. Default (unclassed) and Likert-class resources whose path starts with public/ are an exception -- they are a public standard and may be copied by anyone (resources under any other class still require the authority above). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `copyresources` | **Request body (JSON):** ```json { "requests": { "resource": [ { "sourceentityid": "id", "sourcepath": "string", "destinationentityid": "id", "destinationpath": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `resource.sourceentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of domain, course, user or enrollment that contains the resources to copy. | | `resource.sourcepath` | string | No | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Sourcepath cannot start with ‘/. Use the wildcard \* to match multiple resources in a specific folder in the hierarchy. If you omit sourcepath, CopyResources copies all resources from sourceentityid. | | `resource.destinationentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of domain, course, user or enrollment to copy the resources into. | | `resource.destinationpath` | string | No | The path in the resource hierarchy where the resources are copied to. Specify the empty string ("") to indicate the root of the resources in destinationentityid. If you omit destionationpath, CopyResources copies the resources to the same path as the source. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceChanged.md) | During the request | For each resource copied onto a destination-course path already in use. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each resource copied to a destination-course path not already in use, and for each parent folder the copy creates. | | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | When the copied source is a deletion marker and the destination path held a live file. | These events are sent only when the destination entity is a course and the resource is in the course's default (unclassed) content storage. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example copies all resources from the course whose ID is 553668 to the course whose ID is 527182, preserving all source resource paths in the destination course. **URL:** `?cmd=copyresources` **Request body:** ```json { "requests": { "resource": [ { "sourceentityid": "553668", "destinationentityid": "527182" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [GetResource](https://api.agilixbuzz.com/docs/entry/Command/GetResource.md) - [GetResourceInfo2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceInfo2.md) - [GetResourceList](https://api.agilixbuzz.com/docs/entry/Command/GetResourceList.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # CopyWikiPages This command copies one or more wiki pages from the specified source course, item and group to the specified destination course, item and group. ## Request **Method:** POST **Rights:** UpdateCourse@destinationentity (UpdateSection when the destination is a section). The caller must also be able to read the source course: ReadCourse/ReadSection on the source (or observer access). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `copywikipages` | **Request body (JSON):** ```json { "requests": { "wikipage": [ { "sourceentityid": "id", "sourceitemid": "id", "sourcegroupid": "string", "sourceslug": "string", "destinationentityid": "id", "destinationitemid": "id", "destinationgroupid": "string", "destinationslug": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `wikipage.sourceentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity to which this wiki pages belong. | | `wikipage.sourceitemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the item (in the course manifest) to which the wiki pages belong. | | `wikipage.sourcegroupid` | string | No | Optional group ID to which the wiki pages belong. | | `wikipage.sourceslug` | string | No | Optional string that uniquely identifies the page within the item wiki. Slug can contain the "\*" wildcard character. | | `wikipage.destinationentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity to where the wiki pages will be copied to. | | `wikipage.destinationitemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the item (in the course manifest) to which the wiki pages will be copied to. | | `wikipage.destinationgroupid` | string | No | Optional group ID to which the wiki pages will be copied to. Omit this parameter if sourcegroupid is empty or contains a wildcard. | | `wikipage.destinationslug` | string | No | Optional string that uniquely identifies the page to copy to. Omit this parameter if sourceslug is empty or contains a wildcard. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceChanged.md) | During the request | For each page copied onto a destination path already in use, when the destination pages are in the course's *(Initial)* group. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each page copied to a destination path not already in use, when the destination pages are in the course's *(Initial)* group. | The CourseResource events are sent only for pages in the course's (Initial) group, which are stored as course content files; pages of other groups are stored outside the course content storage and send no content events. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example copies all of the wiki pages from item ID "UPKA1" to item ID "UPKA2" in the same course with entity ID 26793. **URL:** `?cmd=copywikipages` **Request body:** ```json { "requests": { "wikipage": [ { "sourceentityid": "26793", "destinationentityid": "26793", "sourceitemid": "UPKA1", "destinationitemid": "UPKA2" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [GetWikiPage](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPage.md) - [GetWikiPageList](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPageList.md) - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) --- # CreateBadge This command creates a badge. The attribute values posted to this call except *entityid* and *imageentityid* allow replacement variables. To use a replacement variable include {{VARIABLE\_NAME}} in the string. For example, to include the enrollment ID and badge ID in the evidence string, you could use a value of "badges/evidence/{{ENROLLMENTID}}/{{BADGEID}}". The variables are: - **IMAGEENTITYID** - the value from *imageentityid* - **IMAGEPATH** - the value from *imageentityid* - **BADGEID** - the badge ID - **USERID** - the user's ID (as determined from *entityid*) - **FIRSTNAME** - the user's first name - **LASTNAME** - the user's last name - **DOMAINID** - the user's domain ID - **DOMAINNAME** - the name of the user's domain - **USERSPACE** - the userspace of the user's domain - **ENROLLMENTID** - the enrollment ID if *entityid* is an enrollment ID, otherwise this variable is not used - **COURSEID** - the course ID if *entityid* is an enrollment ID, otherwise this variable is not used - **COURSETITLE** - the course title if *entityid* is an enrollment ID, otherwise this variable is not used ## Request **Method:** POST **Rights:** UpdateUser@entityid when entityid refers a user or GradeExam|GradeAssignment|GradeDiscussion@entityid when entityId refers to an enrollment. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createbadge` | **Request body (JSON):** ```json { "request": { "entityid": "id", "imageentityid": "id", "imagepath": "string", "requirements": "string", "badge": { "name": "string", "description": "string", "issuer": { "origin": "string", "name": "string", "org": "string", "contact": "string" } } } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The user ID or enrollment ID of a user who is to receive the badge. If entityid is an enrollment ID, CreateBadge assigns the badge to the user associated with the enrollment. | | `imageentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the entity that contains the PNG image to use for the badge. | | `imagepath` | string | Yes | The resource path to the PNG image resource in imageentityid. | | `requirements` | string | No | The requirements for earning the badge. | | `badge.name` | string | Yes | The name of the badge. Must be no more than 128 characters. | | `badge.description` | string | Yes | A description of the badge. Must be no more than 128 characters. | | `badge.issuer.origin` | string | No | The origin of the issuer. | | `badge.issuer.name` | string | No | The name of the issuer. | | `badge.issuer.org` | string | No | Organization that issued the badge. | | `badge.issuer.contact` | string | No | An email address associated with the issuer. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "badge": { "id": "string", "url": "string" } } } ``` ### badge | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the created badge. | | `url` | string | The URL of the badge. | ## Example This example creates a new badge for the user with ID 2272. **URL:** `?cmd=createbadge` **Request body:** ```json { "assertion": { "entityid": "2272", "imageentityid": "3383", "imagepath": "badge.png", "badge": { "name": "My Badge", "description": "Description of my badge", "criteria": "/Criteria/Badge", "issuer": { "origin": "http://myschool.brainhoney.com", "name": "Buzz" } } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "badge": { "id": "92374987298734928734", "url": "https://myschool.agilixbuzz.com/Cmd/getbadge?entityid=2272&badgeid=E92374987298734928734" } } } ``` ## See Also - [GetBadgeList](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeList.md) - [GetBadge](https://api.agilixbuzz.com/docs/entry/Command/GetBadge.md) - [GetBadgeAssertion](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeAssertion.md) - [DeleteBadge](https://api.agilixbuzz.com/docs/entry/Command/DeleteBadge.md) --- # CreateCommandTokens This command creates one or more command tokens. Command tokens contain codes that are short sequences of letters, digits, and symbols that allow lesser-privileged users to proxy as you to execute a specific command that you set up when you create the command token. The characters in the code are designed to avoid confusion between characters such as zero/oh (0/o/O), one/el (1/L/l), etc. that are often confused during written communication. Capitals vs. lower-case are also avoided due to the complexity of communicating those distinctions when communicating the code vocally. If the scope entity is a domain, access will also be granted to users in the scope domain and descendant domains and users with any rights in the scope domain. If the scope entity is a group, access will be granted to users with enrollments in the group and users with rights on the domain the group belongs to. If the scope entity is a course, access will be granted to users with enrollments on the course and users with rights on the domain the course belongs to. If the scope entity is a user, access will be granted only to that user. When allowunauthenticatedredemption is set to true and the redeeming user is not authenticated, the $userid$ parameter will be null, which may or may not matter depending on the action being executed. Tokens are guaranteed to be unqiue within the specified scope. Note that this doesn't guarantee uniqueness if a user attempts to redeem a token withour specifying a specific token id or the domain id of a domain scoped token. Note that care must be taken to ensure that security is maintained during the token redemption. Certain API calls may leak the creator's security token or other sensitive information, which could allow the token redeemer access to information they shouldn't have, or allow them to spoof the account the action runs as. ## Request **Method:** POST **Rights:** ReadUser@scopeentityid, Proxy@runasuserid (same as Proxy.) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createcommandtokens` | **Request body (JSON):** ```json { "requests": { "commandtoken": [ { "scopeentityid": "id", "description": "string", "runasuserid": "id", "allowunauthenticatedredemption": "boolean", "totalusecountlimit": "int", "userusecountlimit": "int", "peruserusecountlimit": "int", "perusercodes": "boolean", "codelength": "int", "startvalidity": "datetime", "endvalidity": "datetime", "action": { "request": { "cmd": "string" } }, "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `commandtoken.scopeentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of a domain, group, course, or user to which the command token's use will be restricted. | | `commandtoken.description` | string | No | A description of the purpose of the command token. (For future reference by you and other humans). | | `commandtoken.runasuserid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of the user the action will be run as. Defaults to the current user if not specified. The current user must have the same rights as they would to proxy as that user. | | `commandtoken.allowunauthenticatedredemption` | boolean | No | Whether or not to allow unauthenticated redemption of command tokens. Default is false. | | `commandtoken.totalusecountlimit` | int | No | The total number of times the token may be used (not restricted if not specified or zero). | | `commandtoken.userusecountlimit` | int | No | The total number of unique users that may use the token (not restricted if not specified or zero). | | `commandtoken.peruserusecountlimit` | int | No | The total number of times any given user may use the token (not restricted if not specified or zero). | | `commandtoken.perusercodes` | boolean | No | Whether or not each user in the specified scope is given a unique code specific to them. The default is false. Per-user codes prevent users from sharing the same code with each other, but also make it so you have to communicate different codes to each user. Per-user tokens are not stored in the database, so no code uniqueness can be enforced with this option. Due to the number of codes that would generally be required, per-user codes are not recommended with domain scoped tokens. Per-user tokens can only be redeemed by administrative users if they specify the command token id when redeeming. | | `commandtoken.codelength` | int | No | The number of characters that should be in the code. The default is 8. The maximum is 102. The more characters in the code the harder it is for someone to guess, the less characters in the code, the easier it is to communicate and enter. Each character provides 5 bits of uniqueness or 32 possible combinations, so the number of possible codes for a given length is 32^length. For example, a one character code has only 32 possible combinations, but a five character code has about 33.5 million possible combinations, and an eight character code has about 1.1 trillion possible combinations. If the first attempt at generating a code of the specified length results in a non-unique code, longer codes will be used until a unique one is found. | | `commandtoken.startvalidity` | datetime | No | The date/time (in UTC) when the code will start being valid. Any attempt to use the code before this date/time will result in access being denied. The default value is the beginning of time. | | `commandtoken.endvalidity` | datetime | No | The date/time (in UTC) when the code will stop being valid. Any attempt to use the code after this date/time will result in access being denied. The default value is the end of time. | | `commandtoken.action.request.cmd` | string | Yes | The API command to run when the token is redeemed. | | `commandtoken.data` | object | No | Optional free-form structured data. (See Free-form Data for more details.) | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "commandtoken": { "commandtokenid": "id", "code": "id", "user": [ { "userid": "id", "code": "id" } ] } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### commandtoken | Attribute | Type | Description | |-----------|------|-------------| | `commandtokenid` | id | The ID of the command token which can be used to identify and possibly modify this command token in the future. | | `code` | id | *(optional)* The code (if perusercodes was false--otherwise there should be a list of users with user-specific codes). | ###### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The ID of a user in the specified domain, group, or course (or specified directly). | | `code` | id | The code specific to this user. | ## Example This example allows any user in the domain with ID 4832 to create a single enrollment for themselves in the course with id 78903 by calling the RedeemCommandToken command and passing it the three character code (g4m) returned in the response. **URL:** `?cmd=createcommandtokens` **Request body:** ```json { "requests": { "commandtoken": [ { "scopeentityid": "4832", "description": "Self Enrollment in Supplemental Course", "peruserusecountlimit": "1", "codelength": "3", "action": { "request": { "cmd": "createenrollments", "requests": { "enrollment": { "domainid": "4832", "entityid": "78903", "userid": "$userid$", "flags": "131073", "status": "1", "schema": "2" } } } } } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "commandtoken": { "commandtokenid": "587", "code": "g4m" } } ] } } } ``` ## See Also - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # CreateCourses This command creates one or more courses. To create a new course that is linked to another course, use the CopyCourses command. CreateCourses automatically enrolls the calling user as the course owner unless *status* is 0 or the status is 10 and the user already has the requested rights on the course. ## Request **Method:** POST **Rights:** CreateCourse@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createcourses` | **Request body (JSON):** ```json { "requests": { "course": [ { "title": "string", "domainid": "id", "schema": "2|3|4", "reference": "string", "status": "0|1|10", "roleid": "id", "type": "Continuous|Range", "startdate": "datetime", "enddate": "datetime", "days": "int", "term": "string", "indexrule": "IndexRule", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `course.title` | string | Yes | Course title. The maximum length is 256 characters. | | `course.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain that owns the course. (See Extended IDs for more details.) | | `course.schema` | `2\|3\|4` | Yes | The schema version of the course, defaulting to 2 when the attribute is omitted. New courses should normally be created with schema 4, which enables group inheritance, in which groups are defined in the course's data (a `groups` element) and inherit to derivative courses; see CreateGroups and GetGroupList. CreateCourses no longer supports schema 1 (formerly called GoCourse courses). | | `course.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `course.status` | `0\|1\|10` | No | EnrollmentStatus for the user. The only allowed values are 0 (None), 1 (Active), and 10 (Inactive), with 0 indicating that no owner enrollment should be created. The default is 10 (Inactive). | | `course.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the role to use to assign privileges to the owner enrollment. | | `course.type` | `Continuous\|Range` | No | The course type. Range types have startdate and enddate but no days, while Continuous have days but no startdate nor enddate. The default is Range. | | `course.startdate` | datetime | No | The startdate for the course. Meaningful only when type is Range. The default is MinDate. The start date is used by the API only as a default for an enrollment start date. The enrollment start date controls access to the course. | | `course.enddate` | datetime | No | The end date for the new course. Meaningful only when type is Range. The default is MaxDate. The end date is used by the API only as a default for an enrollment end date. The enrollment end date controls access to the course. | | `course.days` | int | No | The number of days a student has to complete the new course. Meaningful only when type is Continuous. The default is 365. | | `course.term` | string | No | The academic term of the new course. The default is the source course's term. The maximum length is 128 characters. | | `course.indexrule` | [IndexRule](https://api.agilixbuzz.com/docs/entry/Enum/IndexRule.md) | No | An IndexRule value that controls whether this course's content is searchable with the Search2 command. The default is **0** (Nothing). | | `course.data` | object | No | Free-form structured data for the course. See Free-form Data and Course Data for more details. Storing more than 16K of data in the free-form XML is not recommended. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "course": { "courseid": "id", "enrollmentid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### course | Attribute | Type | Description | |-----------|------|-------------| | `courseid` | id | ID for the new course. | | `enrollmentid` | id | *(optional)* ID for the new enrollment. This attribute is omitted if no enrollment was created. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityCreated.md) | During the request | Once for each course successfully created by the request. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Creating a course extends the domain's activity range. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates a new course in the domain whose ID is 4378. **URL:** `?cmd=createcourses` **Request body:** ```json { "requests": { "course": [ { "title": "Introduction to Computer Science", "domainid": "4378", "reference": "CS101" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "course": { "courseid": "6050", "enrollmentid": "6051" } } ] } } } ``` ## See Also - [CopyCourses](https://api.agilixbuzz.com/docs/entry/Command/CopyCourses.md) - [DeleteCourses](https://api.agilixbuzz.com/docs/entry/Command/DeleteCourses.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # CreateDemoCourse This command creates a demo course. ## Request **Method:** POST **Rights:** CreateCourse@domainid and ReadCourseFull@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createdemocourse` | **Request body (JSON):** ```json { "request": { "courseid": "id", "domainid": "id", "schema": "int", "reference": "string", "title": "string", "daysoffset": "int", "usermap": { "user": [ { "sourceid": "id", "destinationid": "id" } ] } } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The base course to copy to create the demo course. | | `domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain in which to create the demo course. | | `schema` | int | No | The schema version of the course, defaulting to the source course's schema. New courses should normally be created with schema 4. CreateDemoCourse supports earlier schemas for backwards compatibility, and cannot lower the schema below the source's. A schema of 4 or higher is refused when the source course still has groups stored as entities, because a Schema 4 course cannot hold them. | | `reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `title` | string | Yes | Course title. | | `daysoffset` | int | Yes | The number of days to offset dates on the course to make the demo course feel current. | | `usermap.user.sourceid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of a user associated with the base course. | | `usermap.user.destinationid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of a user to assoicate with the demo course in place of the source user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "course": { "courseid": "id" } } } ``` ### course | Attribute | Type | Description | |-----------|------|-------------| | `courseid` | id | ID of the newly created course. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityCreated.md) | During the request | For the new demonstration course. | | [EnrollmentEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityCreated.md) | During the request | For each enrollment created in the new demonstration course. | | [GroupEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityCreated.md) | During the request | For each group copied into the new demonstration course, which happens only when the new course is below Schema 4. A Schema 4+ demonstration course keeps its groups in course data and inherits them from the source as its base, so no group entity is created and no event is sent. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates a new demo course in the domain with ID 4879 using the course with ID 88939 as the master. **URL:** `?cmd=createdemocourse` **Request body:** ```json { "course": { "courseid": "88939", "domainid": "4879", "title": "My Demo", "schema": "3", "daysoffset": "30", "usermap": { "user": [ { "sourceid": "1234", "destination": "2234" }, { "sourceid": "1235", "destination": "2235" }, { "sourceid": "1236", "destination": "2236" }, { "sourceid": "1237", "destination": "2237" } ] } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "course": { "courseid": "98123" } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) --- # CreateDomains This command creates one or more domains and links them as children to the domain specified by parentid. ## Request **Method:** POST **Rights:** CreateDomain@parentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createdomains` | **Request body (JSON):** ```json { "requests": { "domain": [ { "name": "string", "userspace": "string", "parentid": "id", "reference": "string", "flags": "EntityFlags", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `domain.name` | string | Yes | Title of the domain to create. The maximum length is 256 characters. | | `domain.userspace` | string | Yes | Unique name that identifies the domain. This is also the "login prefix" that each user enters with their username when they sign in. Because many clients use this as a first label in the domain name for this domain (so that users don't have to explicitly enter the login prefix when logging in), it is restricted to the patterns for internet host name labels as defined in the appropriate RFCs, which is currently that the label cannot start or end with a dash, must contain only alphanumeric and dash characters. We have one added restriction that the userspace must contain an alphabetic character somewhere so that we can more easily distinguish IP address parts from hostname labels. Userspace is limited to 128 characters. | | `domain.parentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the parent domain for the new domain. | | `domain.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `domain.flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | No | Bitwise OR of EntityFlags to set on the domain. | | `domain.data` | object | No | Optional free-form structured data. (See Domain Data and Free-form Data for more details.) Storing more than 16K of data in the free-form structured data is not recommended. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "domain": { "domainid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### domain | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | ID of the newly created domain. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityCreated.md) | During the request | Once for each domain successfully created by the request. | | [DomainPermissionsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsCreated.md) | During the request | The domain owner is granted permissions on the new domain. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes that an existing domain with ID 4378 already exists. **URL:** `?cmd=createdomains&parentid=4378` **Request body:** ```json { "requests": { "domain": [ { "name": "Virtual School", "userspace": "vschool", "reference": "123412341234" }, { "name": "Canyon Elementary", "userspace": "canyon", "reference": "432143214321", "flags": "2" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "domain": { "domainid": "4879" } }, { "code": "OK", "domain": { "domainid": "4880" } } ] } } } ``` ## See Also - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) - [GetDomainParentList](https://api.agilixbuzz.com/docs/entry/Command/GetDomainParentList.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) --- # CreateEnrollments This command enrolls a user with the specified rights in a course. ## Request **Method:** POST **Rights:** ControlCourse@entityid when entityid refers to a course; ReadUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createenrollments` | | `disallowduplicates` | bool | No | When true, this command generates an error for an attempt to create a duplicate enrollment which is the case where an enrollment already exists for the specified user ID on the specified entity ID. | | `disallowsamestatusduplicates` | bool | No | When true, this command generates an error for an attempt to create a duplicate enrollment which is the case where an enrollment already exists for the specified user ID on the specified entity ID with the specified status. | **Request body (JSON):** ```json { "requests": { "enrollment": [ { "userid": "id", "entityid": "id", "roleid": "id", "flags": "RightsFlags", "status": "EnrollmentStatus", "domainid": "id", "startdate": "datetime", "enddate": "datetime", "reference": "string", "schema": "(1|2)", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollment.userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user to enroll. (See Extended IDs for more details.) | | `enrollment.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the course in which to enroll the user. (See Extended IDs for more details.) | | `enrollment.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the role used to specify the privileges. The role's privileges override those specified by the flags attribute. | | `enrollment.flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | Bitwise OR of RightsFlags to grant to the user. | | `enrollment.status` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | Yes | EnrollmentStatus for the user. | | `enrollment.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of the domain to create the enrollment in. If omitted, the enrollment is created in the owning domain of entityid. | | `enrollment.startdate` | datetime | No | Date that the enrollment begins. | | `enrollment.enddate` | datetime | No | Date that the enrollment ends. Students may not submit any documents, assignments, assessment attempts, forum, blog, journal posts, wiki pages, etc. after enddate. If entityid refers to a course and you omit enddate, for Range courses enddate defaults to the course enddate, and for Continuous courses enddate defaults to today’s date plus the course’s days. (See CreateCourses for more details.) | | `enrollment.reference` | string | No | Optional field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `enrollment.schema` | `(1\|2)` | No | An optional parameter that specifies how to interpret flags. If schema is 2 then SubmitFinalGrade privilege is treated as a distinct privilege and you must explicitly specify it in flags. If schema is 1, then specifying GradeExam, GradeAssignment, or GradeForum for flags automatically include the SubmitFinalGrade right. The default schema is 1. | | `enrollment.data` | object | No | Optional free-form structured data. (See Free-form Data for more details.) | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "enrollment": { "enrollmentid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | ID of the newly created enrollment. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityActivity.md) | During the request | Creating an enrollment extends the course's activity range to the later of the enrollment start date and the time it was created. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Creating an enrollment extends the domain's activity range, and course activity also cascades up. | | [EnrollmentEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityCreated.md) | During the request | Once for each enrollment successfully created by the request. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example enrolls two students and one teacher in the course “vschool/CS101-P1". The student request flags value is 131073, which equals 0x20001 and is the bitwise-OR of the Participate and ReadCourse rights. The teacher's flags value is 2399535104, which equals 0x8F060000 and is the bitwise-OR of ReadCourse, UpdateCourse, GradeAssignment, GradeForum, GradeExam, SetupGradebook, and ReadGradebook rights. **URL:** `?cmd=createenrollments` **Request body:** ```json { "requests": { "enrollment": [ { "userid": "vschool/112233", "entityid": "mydomain/CS101-P1", "flags": "131073", "status": 1, "startdate": "2008-01-01T12:00:00.0Z", "enddate": "2008-04-30T12:00:00.0Z" }, { "userid": "vschool/223344", "entityid": "mydomain/CS101-P1", "flags": "131073", "status": 1, "startdate": "2008-01-01T12:00:00.0Z", "enddate": "2008-04-30T12:00:00.0Z" }, { "userid": "vschool/445566", "entityid": "mydomain/CS101-P1", "flags": "2399535104", "status": 1, "startdate": "2008-01-01T12:00:00.0Z", "enddate": "2008-04-30T12:00:00.0Z" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "enrollment": { "enrollmentid": "5201" } }, { "code": "OK", "enrollment": { "enrollmentid": "5202" } }, { "code": "OK", "enrollment": { "enrollmentid": "5203" } } ] } } } ``` ## See Also - [DeleteEnrollments](https://api.agilixbuzz.com/docs/entry/Command/DeleteEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # CreateGroups This command creates one or more groups in the specified owner course. ## Request **Method:** POST **Rights:** ControlCourse|UpdateCourse|SetupGradebook@ownerid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `creategroups` | **Request body (JSON):** ```json { "requests": { "group": [ { "domainid": "id", "ownerid": "id", "id": "string", "reference": "string", "setid": "string", "title": "string", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `group.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain to create the group in. (See Extended IDs for more details.) | | `group.ownerid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course to which this group belongs. (See Extended IDs for more details.) | | `group.id` | string | No | Schema 4+: required. The group's stable identifier, unique within the course. May only contain alphanumeric characters, hyphens, and underscores. | | `group.reference` | string | No | Optional field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `group.setid` | string | Yes | The ID of the group set within the owning entity to which this group belongs. | | `group.title` | string | Yes | Title for the group. | | `group.data` | object | No | Optional free-form structured data. (See Free-form Data for more details.) | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "group": { "groupid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### group *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `groupid` | id | The ID of the newly created group. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | When adding a group changes the course record. On Schema 4+ courses the group definitions are part of the course record, so a create that adds one sends this event. A create whose id is already present is rejected instead. | | [GroupEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityCreated.md) | During the request | Once for each group successfully created by the request on a course below Schema 4. Schema 4+ courses have no group entities, so the create is reported by CourseEntityChanged instead. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Creates two groups in the course with userspace/reference of "vschool/CS101". **URL:** `?cmd=creategroups` **Request body:** ```json { "requests": { "group": [ { "title": "Boys", "ownerid": "vschool/CS101", "reference": "CS101-BY", "domainid": "24", "setid": "1" }, { "title": "Girls", "ownerid": "vschool/CS101", "reference": "CS101-GL", "domainid": "24", "setid": "1" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "group": { "groupid": "204235" } }, { "code": "OK", "group": { "groupid": "204236" } } ] } } } ``` ## See Also - [AddGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/AddGroupMembers.md) - [DeleteGroups](https://api.agilixbuzz.com/docs/entry/Command/DeleteGroups.md) - [GetGroup](https://api.agilixbuzz.com/docs/entry/Command/GetGroup.md) - [UpdateGroups](https://api.agilixbuzz.com/docs/entry/Command/UpdateGroups.md) --- # CreateObjectiveSets This command creates one or more objective sets or objective map sets, which are containers for either objectives or objective maps, respectively. ## Request **Method:** POST **Rights:** UpdateObjective@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createobjectivesets` | **Request body (JSON):** ```json { "requests": { "set": [ { "name": "string", "domainid": "id", "reference": "string", "owner": "string", "flags": "ObjectiveSetFlags", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `set.name` | string | Yes | The name of the set. The maximum length is 128 characters. | | `set.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain that owns the set. (See Entity IDs for more details.) | | `set.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `set.owner` | string | No | Specifies the set's owner or group name. For example, specify a common owner value for multiple, related sets. The maximum length is 128 characters. | | `set.flags` | [ObjectiveSetFlags](https://api.agilixbuzz.com/docs/entry/Enum/ObjectiveSetFlags.md) | No | A bitwise OR of ObjectiveSetFlags that control set behavior, including whether it is an objective set or objective map set and whether the set is inherited by descendent domains of domainid. The default value is 0 (None). | | `set.data` | object | No | Free-form structured data for the objective set. See Free-form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "set": { "setid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### set | Attribute | Type | Description | |-----------|------|-------------| | `setid` | id | ID of the newly created set. | ## Example This example creates a new objective set in the domain whose ID is 4378. Any descendent domains of the 4378 domain inherit the set. **URL:** `?cmd=createobjectivesets` **Request body:** ```json { "requests": { "set": [ { "name": "Utah State Core Curriculum", "domainid": "4378", "reference": "UTC", "owner": "UT", "flags": "8" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "set": { "setid": "6050" } } ] } } } ``` ## See Also - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) - [DeleteObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveSets.md) - [GetObjectiveSet2](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSet2.md) - [ListObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/ListObjectiveSets.md) - [PutObjectives](https://api.agilixbuzz.com/docs/entry/Command/PutObjectives.md) - [PutObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/PutObjectiveMaps.md) - [UpdateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/UpdateObjectiveSets.md) --- # CreateRole This command creates a role on a given domain. When a user is assigned a role the rights associated with the role as granted to the user. ## Request **Method:** POST **Rights:** UpdateDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createrole` | **Request body (JSON):** ```json { "request": { "domainid": "id", "name": "string", "privileges": "RightsFlags", "reference": "string", "entitytype": "D|C|empty" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain in which to create the role. | | `name` | string | Yes | Name for the role. The maximum length is 128 characters. | | `privileges` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | Yes | Bitwise OR of RightsFlags to grant to the user. | | `reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external system. The maximum length is 128 characters. | | `entitytype` | `D\|C\|empty` | No | The entity type that the role can provide access rights for. Valid values include "D" for domain, "C" for course, or an empty string if the role can be applied to any entity type. The default is an empty string. See Rights for a description of what privileges apply to what entities. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "role": { "roleid": "id" } } } ``` ### role | Attribute | Type | Description | |-----------|------|-------------| | `roleid` | id | ID of the newly created role. | ## Example This example creates a new role in the domain with ID 4879 that grants typical student privileges. **URL:** `?cmd=createrole` **Request body:** ```json { "request": { "domainid": "4879", "name": "My Role", "privileges": "131073" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "role": { "roleid": "98123" } } } ``` ## See Also - [DeleteRole](https://api.agilixbuzz.com/docs/entry/Command/DeleteRole.md) - [GetRole](https://api.agilixbuzz.com/docs/entry/Command/GetRole.md) - [ListRoles](https://api.agilixbuzz.com/docs/entry/Command/ListRoles.md) - [UpdateRole](https://api.agilixbuzz.com/docs/entry/Command/UpdateRole.md) --- # CreateSecondFactorAuthenticationSecret This command creates an RFC 6238 second factor authentication secret for use with 2FA authentication. This is usually the first step in setting up software/app-based 2FA for an account. (For email based 2FA, this step is not needed). The secret and encryption type or the equivalent QR code should be displayed to the user and two one-time-passwords associated with that secret should be returned back to SetupSecondFactorAuthentication along with the secret to finish setting up 2FA for the account. This function neither reads nor modifes any state. If a client wishes to use some other method to generate an RFC-compliant secret instead (including a local algorithm, which may have security advantages), they may do so. The 2FA system supports SHA1, SHA256, and SHA512, with 16, 26, or 32-character BASE-32 encoded keys. This function currently generates a 32-character BASE-32 encoded SHA256 key, though that may change as new algorithms are added. ## Request **Method:** GET **Rights:** Authenticated User **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createsecondfactorauthenticationsecret` | | `encryption` | string | No | SHA1\|SHA256\|SHA512: Uses the specified encryption algorithm. SHA1 was broken many years ago, but there is some debate as to whether it is safe in the context of TOTP codes. SHA256 or SHA512 is recommended by NIST (SP800-63B). Some Authenticator apps like Microsoft Authenticator only support SHA1 and ignore any algorithm encoded in QR codes, resulting in failed attempts to configure MFA, making it impossible to have a system that works reliably with a wide range of popular MFA apps and that follows NIST recommendations. Microsoft has not responded to requests made in 2015 to add support for SHA256 and SHA512 in Authenticator. Defaults to SHA256. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "mfa": { "encryption": "string", "secret": "string" } } } ``` ### mfa | Attribute | Type | Description | |-----------|------|-------------| | `encryption` | string | The encryption type for the secret, which will be needed to get the correct one-time-passwords. | | `secret` | string | The BASE-32 encoded secret. | ## Example This example requests a second factor authentication secret **URL:** `?cmd=createsecondfactorauthenticationsecret` **Response** (code: `OK`): ```json { "response": { "code": "OK", "mfa": { "encryption": "SHA256", "secret": "RME3QIDHCGM47EJCB7I7WJRCN3FMTCZM" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [SetupSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/SetupSecondFactorAuthentication.md) - [ClearSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/ClearSecondFactorAuthentication.md) - [SecondFactorAuthenticate](https://api.agilixbuzz.com/docs/entry/Command/SecondFactorAuthenticate.md) --- # CreateUsers > **Deprecated** — use [CreateUsers2](https://api.agilixbuzz.com/docs/entry/../Command/CreateUsers2.md) instead. This command creates one or more users. ## Request **Method:** POST **Rights:** CreateUser@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createusers` | | `forcepasswordchange` | bool | No | Whether or not to force each created user to change their password before logging in for the first time. The default is false. | **Request body (JSON):** ```json { "requests": { "user": [ { "username": "string", "password": "string", "passwordquestion": "string", "passwordanswer": "string", "firstname": "string", "lastname": "string", "email": "string", "domainid": "id", "reference": "string", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `user.username` | string | Yes | Username of the new user account. End-users enter this name to login. The maximum length is 128 characters, and the value may not contain the forward-slash character (/). | | `user.password` | string | Yes | Password for the new account. There is no maximum length for this field. If not specified or empty, the account is marked to never allow password login (though it may still be used for SSO). | | `user.passwordquestion` | string | No | Security question that end-user can respond to to reset their password. The maximum length is 256 characters. | | `user.passwordanswer` | string | No | Answer to passwordquestion. The maximum length is 128 characters. | | `user.firstname` | string | Yes | User’s first (given) name. The maximum length is 256 characters. | | `user.lastname` | string | Yes | User’s last (surname) name. The maximum length is 256 characters. | | `user.email` | string | Yes | User’s e-mail address. The maximum length is 256 characters. | | `user.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | User’s domain ID. (See Extended IDs for more details.) | | `user.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `user.data` | object | No | Optional free-form structured data. See User Data and Free Form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "user": { "userid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the newly created user. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Creating a user extends the domain's activity range. | | [DomainPermissionsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsCreated.md) | During the request | When the new user is given administrative rights as part of creation. | | [UserEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityCreated.md) | During the request | Once for each user successfully created by the request. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates a new user account in the domain with ID 4879. **URL:** `?cmd=createusers` **Request body:** ```json { "requests": { "user": [ { "username": "sally.johnson", "password": "sally1234", "passwordquestion": "What model is my car?", "passwordanswer": "Toyota", "firstname": "Sally", "lastname": "Johnson", "email": "sally.johnson@myschool.edu", "domainid": "4879", "reference": "12345678" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "user": { "userid": "589" } } ] } } } ``` ## See Also - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # CreateUsers2 This command creates one or more users. ## Request **Method:** POST **Rights:** CreateUser@domainid and ControlDomain@domainid when using rights or roleid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `createusers2` | | `forcepasswordchange` | bool | No | Whether or not to force each created user to change their password before logging in for the first time. The default is false. | **Request body (JSON):** ```json { "requests": { "user": [ { "type": "string", "username": "string", "password": "string", "passwordquestion": "string", "passwordanswer": "string", "firstname": "string", "lastname": "string", "email": "string", "domainid": "id", "reference": "string", "flags": "EntityFlags", "rights": "RightsFlags", "roleid": "id", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `user.type` | string | No | Account type. Omit (or leave empty) for a regular user account. Set to `applicationidentity` to create a machine-to-machine service account that authenticates via OAuth 2.0 client credentials instead of a password. Application Identity accounts cannot log in with a password; see OAuth 2.0 Application Identity for details. | | `user.username` | string | Yes | Username of the new user account. End-users enter this name to login. The maximum length is 128 characters, and the value may not contain the forward-slash character (/). Unicode characters may be used. If you want to substitue something that looks like a slash, you may use Unicode character U+2044. The maximum length is 128 characters. | | `user.password` | string | Yes | Password for the new account. Because passwords are hashed, there is no set maximum length in the system for this field, but extremely long passwords require more network transfer, memory, and processing, so they may perform somewhat slower than reasonably shorter ones. If no password is specified, the account will be marked so that password logins are not allowed. SSO and proxy logins will still be allowed, but any attempt to login with a password will fail. | | `user.passwordquestion` | string | No | Security question that end-user can respond to to reset their password. The maximum length is 256 characters. | | `user.passwordanswer` | string | No | Answer to passwordquestion. Password answers are hashed similarly to passwords, so they have the same size and performance constraints. | | `user.firstname` | string | Yes | User’s first (given) name. The maximum length is 256 characters. | | `user.lastname` | string | Yes | User’s last (surname) name. The maximum length is 256 characters. | | `user.email` | string | Yes | User’s e-mail address. The maximum length is 256 characters. | | `user.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | User’s domain ID. (See Extended IDs for more details.) | | `user.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. The maximum length is 128 characters. | | `user.flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | No | Bitwise OR of EntityFlags to set on the user. | | `user.rights` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | Bitwise OR of RightsFlags to grant to the user in domain domainid. | | `user.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the role used to specify the rights to grant to the user in the domain domainid. The role's privileges override those specified by the rights attribute. | | `user.data` | object | No | Optional free-form structured data. See User Data and Free Form Data for more details. Storing more than 16K of data in the free-form XML is not recommended. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "user": { "userid": "id" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the newly created user. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Creating a user extends the domain's activity range. | | [DomainPermissionsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsCreated.md) | During the request | When the new user is given administrative rights as part of creation. | | [UserEntityCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityCreated.md) | During the request | Once for each user successfully created by the request. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates a new user account in the domain with ID 4879. **URL:** `?cmd=createusers2` **Request body:** ```json { "requests": { "user": [ { "username": "sally.johnson", "password": "sally1234", "passwordquestion": "What model is my car?", "passwordanswer": "Toyota", "firstname": "Sally", "lastname": "Johnson", "email": "sally.johnson@myschool.edu", "domainid": "4879", "reference": "12345678", "flags": "0", "rights": "0" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "user": { "userid": "589" } } ] } } } ``` ## See Also - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # DeactivateCourse This command deactivates a course. Deactivating a course deactivates all derivative and static copies of the course. Deactivated course cannot be copied, or used as the source for item links. New enrollments cannot be created on deactivated courses, and existing enrollments cannot be updated except to change the reference, change the data, or make the status non active. Deactivated courses are removed from the search index and the community catalog. Deactivating a course cannot be undone. Deactivating a course is asynchronous, and will happen in a background task. Depending on the number of copies, deactivating a course may take a long time to complete. ## Request **Method:** GET **Rights:** ControlCourse@domainid of course identified by courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deactivatecourse` | | `courseid` | id | Yes | ID of the course to deactivate | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseAncestorChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseAncestorChanged.md) | Background | Deactivating a course changes its record, so each of its derivative courses is notified. | | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | Deactivating a course clears its active flag on the course record. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example deactivates a course with ID 6048. **URL:** `?cmd=deactivatecourse&courseid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [DeleteCourses](https://api.agilixbuzz.com/docs/entry/Command/DeleteCourses.md) - [GetCourse2](https://api.agilixbuzz.com/docs/entry/Command/GetCourse2.md) - [ListCourses](https://api.agilixbuzz.com/docs/entry/Command/ListCourses.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) - [RestoreCourse](https://api.agilixbuzz.com/docs/entry/Command/RestoreCourse.md) --- # DeleteAnnouncements This command deletes one or more domain or course announcements. ## Request **Method:** POST **Rights:** PostDomainAnnouncements@domainid for domains referred to by entityid OR UpdateCourse|SetupGradebook|GradeExam|GradeAssignment|GradeForum@courseid for courses referred to by entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteannouncements` | **Request body (JSON):** ```json { "requests": { "announcement": [ { "entityid": "id", "path": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `announcement.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the domain from which to delete the announcement. | | `announcement.path` | string | Yes | Unique path to the zip-compressed announcement file. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | When the entity is a course and the deleted announcement was stored as a legacy course content file (a go/announcements/ path), that legacy file is deleted with it. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example deletes an announcement with path “6d7ddd94a2924d908da4d190d728fe8f.zip” in the entity with ID 4378. **URL:** `?cmd=deleteannouncements` **Request body:** ```json { "requests": { "announcement": [ { "entityid": "4378", "path": "6d7ddd94a2924d908da4d190d728fe8f.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # DeleteAttemptFile This command deletes a previously uploaded file associated with a fileupload question. ## Request **Method:** GET **Rights:** ReadCourse@enrollment.courseid or GradeExam|UpdateCourse@enrollment.courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteattemptfile` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this uploaded file belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this uploaded file belongs. | | `partid` | string | Yes | PartId of the fileupload question to which this uploaded file beglong. | | `filepath` | string | Yes | File path to the uploaded file as specified in the response of the PutAttemptFile command. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example deletes the previously uploaded file 'answer.pdf' for enrollment ID 4378, item ID 'assesment\_1', fileupload question part ID "1". **URL:** `?cmd=deleteattemptfile&enrollmentid=4378&itemid=assessment_1&partid=1&filepath=answer.pdf` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [PutAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/PutAttemptFile.md) - [GetAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/GetAttemptFile.md) --- # DeleteBadge This command deletes a badge. ## Request **Method:** GET **Rights:** UpdateUser@entityid when entityid refers a user or GradeExam|GradeAssignment|GradeDiscussion@entityid when entityId refers to an enrollment. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletebadge` | | `entityid` | id | Yes | The user that received the badge. | | `badgeid` | string | Yes | The ID of the badge. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example deletes a badge for the user with ID 2272. **URL:** `?cmd=deletebadge&entityid=2272&badgeid=28383792873897398739873382748` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [GetBadgeList](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeList.md) - [GetBadge](https://api.agilixbuzz.com/docs/entry/Command/GetBadge.md) - [GetBadgeAssertion](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeAssertion.md) --- # DeleteBlogs This command deletes one or more blog messages. ## Request **Method:** POST **Rights:** GradeForum@entityid in the entity (course or section) referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteblogs` | **Request body (JSON):** ```json { "requests": { "message": [ { "enrollmentid": "id", "itemid": "string", "messageid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `message.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of the blog owner. | | `message.itemid` | string | Yes | ID of the blog item from the course manifest. | | `message.messageid` | string | Yes | Unique ID of the message to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes a message from the blog item with ID "BLOG12" from the blog owned by enrollment ID 4378. **URL:** `?cmd=deleteblogs` **Request body:** ```json { "requests": { "message": [ { "entityid": "4378", "itemid": "BLOG12", "messageid": "3B37DE8C48984c649A95015EACD33DCF.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) - [GetBlogList](https://api.agilixbuzz.com/docs/entry/Command/GetBlogList.md) - [PutBlog](https://api.agilixbuzz.com/docs/entry/Command/PutBlog.md) --- # DeleteCommandTokens This command deletes one or more command tokens. ## Request **Method:** POST **Rights:** ReadUser@scopeentityid and ControlUser@runasuserid (the runasuserid from the associated command token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletecommandtokens` | **Request body (JSON):** ```json { "requests": { "commandtoken": [ { "commandtokenid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `commandtoken.commandtokenid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the command token to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes the command token with id 587. **URL:** `?cmd=deletecommandtokens&` **Request body:** ```json { "requests": { "commandtoken": [ { "commandtokenid": "587" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # DeleteCourses This command deletes one or more courses. When a course is deleted, all related sections and enrollments are deleted as well. ## Request **Method:** POST **Rights:** DeleteCourse@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletecourses` | **Request body (JSON):** ```json { "requests": { "course ": [ { "courseid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `course .courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityDeleted.md) | During the request | Once for each course successfully deleted by the request. | | [EnrollmentEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityDeleted.md) | During the request | A course's enrollments are deleted with the course. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the Course with ID 6050 already exists. **URL:** `?cmd=deletecourses` **Request body:** ```json { "requests": { "course": [ { "courseid": "6050" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [GetCourse](https://api.agilixbuzz.com/docs/entry/Command/GetCourse.md) - [RestoreCourse](https://api.agilixbuzz.com/docs/entry/Command/RestoreCourse.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # DeleteDocuments This command deletes one or more user documents from the server. ## Request **Method:** POST **Rights:** GradeAssignment|GradeExam@enrollmentid where enrollmentid refers to a course or section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletedocuments` | **Request body (JSON):** ```json { "requests": { "document ": [ { "enrollmentid": "id", "itemid": "string", "path": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `document .enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user’s enrollment to which this document belongs. | | `document .itemid` | string | Yes | ID of the course item to which this document belongs. | | `document .path` | string | Yes | The unique path to the document. You can use forward-slash (/) between path elements to create a document hierarchy. Path cannot start with '/'. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## See Also - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # DeleteDomain This command deletes a domain. When a domain is deleted, its descendant domains, and all the users, courses, and enrollments in those domains are deleted as well. ## Request **Method:** GET **Rights:** DeleteDomain@parentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletedomain` | | `domainid` | id | Yes | ID of the domain to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityDeleted.md) | Background | The containing domain was deleted. Its contents are deleted by cascading delete after the request returns, so these events arrive later and, for a large domain, over an extended period. | | [DomainEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityDeleted.md) | During the request | For the domain named in the request, during the request. Each descendant domain produces a further event later, as cascading delete works through them. | | [EnrollmentEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityDeleted.md) | Background | The containing domain was deleted. Its contents are deleted by cascading delete after the request returns, so these events arrive later and, for a large domain, over an extended period. | | [UserEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityDeleted.md) | Background | The containing domain was deleted. Its contents are deleted by cascading delete after the request returns, so these events arrive later and, for a large domain, over an extended period. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes that the domain with ID 6048 already exists **URL:** `?cmd=deletedomain&domainid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [RestoreDomain](https://api.agilixbuzz.com/docs/entry/Command/RestoreDomain.md) - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) - [GetDomainParentList](https://api.agilixbuzz.com/docs/entry/Command/GetDomainParentList.md) --- # DeleteEnrollments This command deletes one or more user enrollments. ## Request **Method:** POST **Rights:** ControlCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteenrollments` | **Request body (JSON):** ```json { "requests": { "enrollment ": [ { "enrollmentid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollment .enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the enrollment to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityDeleted.md) | During the request | Once for each enrollment successfully deleted by the request. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the enrollment with ID 6068 already exists. **URL:** `?cmd=deleteenrollments` **Request body:** ```json { "requests": { "enrollment": [ { "enrollmentid": "6068" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [RestoreEnrollment](https://api.agilixbuzz.com/docs/entry/Command/RestoreEnrollment.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # DeleteGroups This command deletes one or more groups. All group memberships are removed before the group is deleted. ## Request **Method:** POST **Rights:** ControlCourse|UpdateCourse|SetupGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletegroups` | **Request body (JSON):** ```json { "requests": { "group": [ { "groupid": "id", "courseid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `group.groupid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the group to delete. | | `group.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Schema 4+: ID of the owning course. When present, groupid is interpreted as a string group identifier within the course data rather than a group entity ID. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | When removing a group changes the course record. On Schema 4+ courses the group definitions are part of the course record, so a delete that removes one sends this event; deleting a group that is not defined changes nothing and sends nothing. | | [GroupEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityDeleted.md) | During the request | Once for each group successfully deleted by the request on a course below Schema 4. Schema 4+ courses have no group entities, so the delete is reported by CourseEntityChanged instead. | | [GroupEntityMembersChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityMembersChanged.md) | During the request | Deleting a group on a course below Schema 4 removes its members, which is reported before the group deletion. On Schema 4+ courses the membership is retained, so no membership event is sent. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Deletes the group with ID 6052. **URL:** `?cmd=deletegroups` **Request body:** ```json { "requests": { "group": [ { "groupid": "6052" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [UpdateGroups](https://api.agilixbuzz.com/docs/entry/Command/UpdateGroups.md) --- # DeleteItems This command deletes one or more items from a manifest. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteitems` | | `cascade` | string | No | When *true*, items that are descendants of the items being deleted are also deleted. The default is *false*. | **Request body (JSON):** ```json { "requests": { "item": [ { "entityid": "id", "itemid": "string", "groupid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `item.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course that owns the item. | | `item.itemid` | string | Yes | ID of the item to delete. | | `item.groupid` | string | No | Schema 4+: when entityid is a course, deletes the group-specific override for the specified group rather than the course-level item. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemDeleted.md) | During the request | For each course item deleted by the request. | | [EnrollmentItemDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemDeleted.md) | During the request | For each enrollment item deleted by the request. | | [GroupItemDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupItemDeleted.md) | During the request | For each group item deleted by the request. | Which of the course, enrollment, or group item events is sent is determined by the type of the entity the item belongs to. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example deletes an item with ID “Assignment12” in the course whose ID is 4378. **URL:** `?cmd=deleteitems` **Request body:** ```json { "requests": { "item": [ { "entityid": "4378", "itemid": "Assignment12" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CopyItems](https://api.agilixbuzz.com/docs/entry/Command/CopyItems.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) - [RestoreItems](https://api.agilixbuzz.com/docs/entry/Command/RestoreItems.md) --- # DeleteMessage This command deletes a discussion board message from a discussion forum. ## Request **Method:** GET **Rights:** Participate@entityid or GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletemessage` | | `entityid` | id | Yes | ID of the entity (course or section) that contains the message or the enrollment ID of the student. | | `itemid` | string | Yes | ID of the item that the message applies to. | | `messageid` | string | Yes | ID of the message to get. | | `groupid` | string | No | Optional group ID for the message. If omitted, the default group is used. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example deletes a message from the default group in the forum item with ID "Forum12" in the entity whose ID is 4378. **URL:** `?cmd=deletemessage&entityid=6162&itemid=DISCUSSION_1__POINTS&messageid=89b2b64f710949018d5cf618a0bb681e` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [PutMessagePart](https://api.agilixbuzz.com/docs/entry/Command/PutMessagePart.md) - [DeleteMessagePart](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessagePart.md) - [SubmitMessage](https://api.agilixbuzz.com/docs/entry/Command/SubmitMessage.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) - [RestoreMessages](https://api.agilixbuzz.com/docs/entry/Command/RestoreMessages.md) --- # DeleteMessagePart This command deletes individual parts from a discussion board message. When called, the message enters an edit state where changes to the message parts are stored in a temporary location on the server. While in this state, only the message owner can see the changed message parts with the GetMessage command. Other users get the message as it existed before the edits began. To commit these changes to a new message, call SubmitMessage. To rollback changes and revert to the pre-changed state, call *DeleteMessagePart* and omit the *filepath* parameter. ## Request **Method:** GET **Rights:** Participate@entityid or GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletemessage` | | `entityid` | id | Yes | ID of the entity (course or section) that contains the message or the enrollment ID of the student. | | `itemid` | string | Yes | ID of the item that the message applies to. | | `messageid` | string | Yes | ID of the message to get. | | `groupid` | string | No | Optional group ID for the message. If omitted, the default group is used. | | `filepath` | string | No | When filepath is specified, it is the path to a file within the message. For example, specify a filepath to delete an attachment from within the message. If this parameter is omitted, the server resets the edit state of the message and clears all temporary parts. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example deletes an attachment of a message from the default group in the forum item with ID "Forum12" in the entity whose ID is 4378. **URL:** `?cmd=deletemessagepart&entityid=6162&itemid=DISCUSSION_1__POINTS&messageid=89b2b64f710949018d5cf618a0bb681e&filepath=Attachement1.pdf` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [PutMessagePart](https://api.agilixbuzz.com/docs/entry/Command/PutMessagePart.md) - [SubmitMessage](https://api.agilixbuzz.com/docs/entry/Command/SubmitMessage.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) - [DeleteMessage](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessage.md) - [RestoreMessages](https://api.agilixbuzz.com/docs/entry/Command/RestoreMessages.md) --- # DeleteMessages > **Deprecated** — use [DeleteMessage](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessage.md) instead. This command deletes one or more discussion board messages from a discussion forum. ## Request **Method:** POST **Rights:** GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletemessages` | **Request body (JSON):** ```json { "requests": { "message": [ { "entityid": "id", "itemid": "string", "groupid": "string", "messageid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `message.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity (course or section) that owns the discussion forum and messages. | | `message.itemid` | string | Yes | ID of the discussion forum item from the course manifest. | | `message.groupid` | string | No | Optional ID of the group within the discussion forum. If omitted, the default group is used. | | `message.messageid` | string | Yes | Unique ID of the message to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes a message from the default group in the forum item with ID "Forum12" in the entity whose ID is 4378. **URL:** `?cmd=deletemessages` **Request body:** ```json { "requests": { "message": [ { "entityid": "4378", "itemid": "Forum12", "messageid": "3B37DE8C48984c649A95015EACD33DCF.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) - [RestoreMessages](https://api.agilixbuzz.com/docs/entry/Command/RestoreMessages.md) --- # DeleteObjectiveMaps This command deletes one or more objective maps from an objective map set. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteobjectivemaps` | **Request body (JSON):** ```json { "requests": { "map": [ { "setid": "id", "guid": "guid", "correlation": "guid" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `map.setid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the objective map set that contains this map. | | `map.guid` | guid | Yes | The guid of the learning objective. | | `map.correlation` | guid | Yes | The guid of the correlated learning objective. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes the objective mapping with GUID 4bebfa5f-e5d0-49c6-99a9-0048be0d0170 and correlation f2d5feab-72f1-4294-8325-375ff86f5531 from the set with ID 4378. **URL:** `?cmd=deleteobjectivemaps` **Request body:** ```json { "requests": { "map": [ { "setid": "4378", "guid": "4bebfa5f-e5d0-49c6-99a9-0048be0d0170", "correlation": "f2d5feab-72f1-4294-8325-375ff86f5531" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/PutObjectiveMaps.md) - [GetObjectiveMapList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveMapList.md) --- # DeleteObjectives This command deletes one or more objectives in an objective set. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteobjectives` | **Request body (JSON):** ```json { "requests": { "objective": [ { "guid": "guid" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `objective.guid` | guid | Yes | Globally unique identifier of the objective to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes the objective with guid 239bd83f-0064-95b7-49fb-8d8167489a94. **URL:** `?cmd=deleteobjectives` **Request body:** ```json { "requests": { "objective": [ { "guid": "239bd83f-0064-95b7-49fb-8d8167489a94" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [GetObjectiveList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveList.md) - [PutObjectives](https://api.agilixbuzz.com/docs/entry/Command/PutObjectives.md) --- # DeleteObjectiveSets This command deletes one or more objective sets or objective map sets. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteobjectivesets` | **Request body (JSON):** ```json { "requests": { "set": [ { "setid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `set.setid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the set to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example assumes the Objective Set with ID 6050 already exists. **URL:** `?cmd=deleteobjectivesets` **Request body:** ```json { "requests": { "set": [ { "setid": "6050" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [UpdateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/UpdateObjectiveSets.md) --- # DeleteQuestions This command deletes one or more questions from a course. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletequestions` | **Request body (JSON):** ```json { "requests": { "question ": [ { "entityid": "id", "questionid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `question .entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course that owns the question. | | `question .questionid` | string | Yes | ID of the question to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes a question with ID “question12” in the course whose ID is 4378. **URL:** `?cmd=deletequestions` **Request body:** ```json { "requests": { "question": [ { "entityid": "4378", "questionid": "Question12" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) - [RestoreQuestions](https://api.agilixbuzz.com/docs/entry/Command/RestoreQuestions.md) --- # DeleteResources This command deletes one or more resources from a domain, course, or enrollment. ## Request **Method:** POST **Rights:** UpdateDomain@entityid when entityid refers to a domain; UpdateCourse@entityid when entityid refers to a course; UpdateEnrollment@entityid when entityid refers to an enrollment, GradeAssignment@the enrollment's entity ID, or Participate@entityID and the enrollment is active. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteresources` | **Request body (JSON):** ```json { "requests": { "resource": [ { "entityid": "id", "path": "string", "class": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `resource.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Course or domain ID that owns this resource. | | `resource.path` | string | Yes | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Path cannot start with ‘/’. | | `resource.class` | string | No | The four character string that specifies the class, or type, of resources to delete. The default of an empty string deletes normal course or user resources. The special class of *MISC* can be used to delete arbitrary or application-specific resources on the specified entity. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | For each file or folder the request deletes. Sent only when the entity is a course and the resource is in the course's default (unclassed) content storage. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example deletes the resource with path "Assets/index.html" from the course whose ID is 4378. **URL:** `?cmd=deleteresources` **Request body:** ```json { "requests": { "resource": [ { "entityid": "4378", "path": "Assets/index.html" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) - [RestoreResources](https://api.agilixbuzz.com/docs/entry/Command/RestoreResources.md) --- # DeleteRole This command deletes a role from the server. ## Request **Method:** GET **Rights:** UpdateDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleterole` | | `roleid` | id | Yes | ID of the role to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example assumes the role with ID 4654 already exists. **URL:** `?cmd=deleterole&roleid=4654` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateRole](https://api.agilixbuzz.com/docs/entry/Command/CreateRole.md) - [ListRoles](https://api.agilixbuzz.com/docs/entry/Command/ListRoles.md) - [RestoreRole](https://api.agilixbuzz.com/docs/entry/Command/RestoreRole.md) - [UpdateRole](https://api.agilixbuzz.com/docs/entry/Command/UpdateRole.md) --- # DeleteSubscriptions This command deletes one or more subscriptions. Each subscription is uniquely identified by its subscriberid, entityid, and flags. ## Request **Method:** POST **Rights:** ControlCourse@entityid when entityid is a course; ControlDomain@entityid when entityid is a domain. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletesubscriptions` | **Request body (JSON):** ```json { "requests": { "subscription": [ { "subscriberid": "id", "entityid": "id", "flags": "RightsFlags" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `subscription.subscriberid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user or domain to delete a subscription for. The value 0 indicates a subscription for every domain in the system. | | `subscription.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the subscribed-to domain or course. | | `subscription.flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | When subscriberid is a domain ID, a bitwise-OR of RightsFlags that a user must have in the domain to be included in this subscription. When subscriberid is a user ID, flags is ignored. The default value is 0 (None). | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example deletes subscriptions for the user with ID 4879 and for users in the domain ID 5010 who have the CreateCourse (65536) right. The subscribed-to course has ID 87923. **URL:** `?cmd=deletesubscriptions` **Request body:** ```json { "requests": { "subscription": [ { "subscriberid": "4879", "entityid": "87923" }, { "subscriberid": "5010", "entityid": "87923", "flags": "65536" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [GetEntitySubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEntitySubscriptionList.md) - [GetSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetSubscriptionList.md) - [UpdateSubscriptions](https://api.agilixbuzz.com/docs/entry/Command/UpdateSubscriptions.md) --- # DeleteUsers This command deletes one or more users from the server. When a user is deleted, all related enrollments are deleted as well. Note that in order to prevent abuse, users who have DeleteUser rights will be denied access to delete another user in their domain when that user has any domain privilege in any domain they do not. Further, if the target user has a cross-domain enrollment with rights other than ReadCourse/Section and Participate in any other domain, the user requesting the deletion must also have DeleteUser rights in the domain of that enrollment. Also, this function cannot be used to delete the account that is performing the deletion (so you can't accidentally delete yourself). ## Request **Method:** POST **Rights:** DeleteUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteusers` | **Request body (JSON):** ```json { "requests": { "user": [ { "userid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `user.userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user to delete. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityDeleted.md) | During the request | A user's enrollments are deleted with the user. | | [UserEntityDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityDeleted.md) | During the request | Once for each user successfully deleted by the request. | | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | Deleting a user ends their sessions. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the users with IDs 589 and 590 already exist. **URL:** `?cmd=deleteusers` **Request body:** ```json { "requests": { "user": [ { "userid": "589" }, { "userid": "590" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [RestoreUser](https://api.agilixbuzz.com/docs/entry/Command/RestoreUser.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # DeleteWikiPages This command deletes one or more wiki pages from a course. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deletewikipages` | **Request body (JSON):** ```json { "requests": { "wikipage": [ { "entityid": "id", "itemid": "id", "slug": "string", "groupid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `wikipage.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity to which this wiki page belongs. | | `wikipage.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the item (in the course manifest) to which this wiki page belongs. | | `wikipage.slug` | string | Yes | String that uniquely identifies the page within the item wiki. | | `wikipage.groupid` | string | No | Group ID to which the wiki page belongs. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | For each page deleted from the course's *(Initial)* group, which is stored as course content files; pages of other groups send no content events. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example deletes the "Home" wiki page from the course with an ID of 26793, the item with an ID of "UPKA2" and the group with an ID of "(Default)". **URL:** `?cmd=deletewikipages` **Request body:** ```json { "requests": { "wikipage": [ { "entityid": "26793", "itemid": "UPKA2", "groupid": "(Default)", "slug": "Home" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) - [RestoreWikiPages](https://api.agilixbuzz.com/docs/entry/Command/RestoreWikiPages.md) --- # DeleteWorkInProgress This command deletes an attachment file from a student's previously saved work-in-progress submission. ## Request **Method:** GET **Rights:** Participate@entityid or GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `deleteworkinprogress` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this student submission belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this student submission belongs. | | `filepath` | string | Yes | Specifies the attachment path of an attachment in the student Submission to delete. | | `type` | string | No | Identifies the type of the attachment to delete. Possible values are: - **file** - The attachment is a file that is part of the submission and *filepath* identifies the path to the attached file. This is the default. - **googledrivedoc** - The attachment is a document stored in Google™ Drive and *filepath* contains the URL to the attached Google Drive document. - **media** - The attachment is a media file, and *filepath* contains the media id and content types. The default is *file*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example deletes the file 'essay.pdf' from the work-in-progress submission for enrollment ID 4378 and item ID 'ASSIGNMENT\_1'. **URL:** `?cmd=deleteworkinprogress&enrollmentid=4378&itemid=ASSIGNMENT_1 &filepath=essay.pdf` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [PutWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/PutWorkInProgress.md) - [GetWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/GetWorkInProgress.md) --- # ExportData This command convert structured post data to a tab or comma-delimited file. ## Request **Method:** POST **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `exportdata` | | `to` | string | Yes | The destination file format. | | `saveto` | string | Yes | Saves the output to a temporary resource for the user. Use with GetConvertedData. | | `bom` | boolean | No | Whether or not to include byte order marks in the output file. The default is to include byte order marks. | | `spreadsheet` | boolean | No | Whether or not the generated CSV should be in spreadsheet format. Always use this for Excel, Google Sheets, or other spreadsheets, but not to import into other databases. The default is to assume the CSV will be used with a spreadsheet (true). | **Request body (JSON):** ```json { "request": { "row": [ { "col": [ {} ] } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `row.col` | object | Yes | Value | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example Convert data to comma separated file MyCourseExport **URL:** `?cmd=exportdata&to=csv&saveto=MyCourseExport.csv` **Request body:** ```json { "request": { "file": { "row": [ { "col": [ { "$value": "Code" }, { "$value": "Name" } ] }, { "col": [ { "$value": "CHEM 105" }, { "$value": "General College Chemistry 1" } ] }, { "col": [ { "$value": "CHEM 106" }, { "$value": "General College Chemistry 2" } ] }, { "col": [ { "$value": "CHEM 107" }, { "$value": "General College Chemistry Laboratory" } ] }, { "col": [ { "$value": "CHEM 223" }, { "$value": "Quantitative and Qualitative Analysis" } ] } ] } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [GetConvertedData](https://api.agilixbuzz.com/docs/entry/Command/GetConvertedData.md) - [ImportData](https://api.agilixbuzz.com/docs/entry/Command/ImportData.md) --- # ExtendSession Each API command automatically refreshes the authorization token, extending the expiration for the duration originally specified at login, but if you need to keep the extend the token life without making any specific API call, this command will simply extend the token duration. For example, if the interval between API calls in your application is long (over 10 minutes), you can call ExtendSession more frequently than every 10 minutes to keep the user authorized. ## Request **Method:** POST **Content-Type:** application/json **Request body (JSON):** ```json { "request": { "cmd": "extendsession" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `extendsession` | Yes | | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "session": { "token": "string", "authenticationexpirationminutes": "int", "userid": "id", "proxyuserid": "id" } } } ``` ### session | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | The token that needs to be extended (usually the one returned from Login). | | `authenticationexpirationminutes` | int | The number of minutes until the specified authentication token will timeout unless there are subsequent calls that affect it. The token expiration will automatically be extended when any API commands are called and the token will be immediately expired when Logout is called or when explicitly revoked by an administrator prior to the normal expiration. This value is returned so that clients know how often they need to call ExtendSession or some other function to keep their authentication from expiring under normal circumstances. | | `userid` | id | User ID used to authenticate this session. | | `proxyuserid` | id | *(optional)* If this authorization token is being used in a proxy session, the ID of the proxied as user. See Proxy for details on proxy sessions. | ## Example **Request body:** ```json { "request": { "cmd": "extendsession" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "session": { "token": "SYC-UhGJ|7rsM!xiaWNlb9P8dxHRoLA", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) --- # FindPersonalizedEntities This command finds the course, enrollment, and group entities that contain items which have been personalized in the way specified by the query parameter. A personalized item is an item that has been created in that entity, or is different from the entity's parent. ## Request **Method:** GET **Rights:** UpdateCourse@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `findpersonalizedentities` | | `courseid` | id | Yes | ID of the course to search. *FindPersonalizedEntities* searches the course and the enrollments and groups in the course. *FindPersonalizedEntities* does not search derivative or base courses. | | `query` | string | Yes | Query used to search the course, enrollments and groups. The entities returned must have an item matching this query. Only items that do not exist in the entity's parent, or that have been modified in a way such that the query matches the changes in the item are considered a match. See Free-Form Data Query for more details. | | `itemid` | string | No | Optional. When specified, only entities that have created or changed the item with the specified *itemid* are returned. | | `includegroups` | (true|false) | No | Optional. When false, only the course and enrollments are searched. The default is false. | | `privileges` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list of enrollments that are searched. When present, only enrollments with the specified privileges are searched. | | `allstatus` | string | No | Optional. When true, all enrollments, whether active or not, are searched. When false, only active or suspended enrollments are searched. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "entities": { "entity": [ { "id": "id", "type": "string", "item": [ { "id": "id" } ] } ] } } } ``` ### entities #### entity | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of the matching entity. | | `type` | string | Type of the matching entity. 'C' for course, 'E' for enrollment, and 'G' for group. | ##### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | Item ID that matches the query. | ## Example This example find the enrollments and groups of course 123 that have assigned item A3. **URL:** `?cmd=findpersonalizedentities&courseid=123&itemid=A3&query=/assigned='true'&includegroups="true"` **Response** (code: `OK`): ```json { "response": { "code": "OK", "entities": { "entity": [ { "id": "1001", "type": "E", "item": [ { "id": "A3" } ] }, { "id": "1100", "type": "G", "item": [ { "id": "A3" } ] }, { "id": "1101", "type": "G", "item": [ { "id": "A3" } ] } ] } } } ``` ## See Also - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) - [AssignItem](https://api.agilixbuzz.com/docs/entry/Command/AssignItem.md) --- # FinishPasswordReset This command updates the password of the specified user. An error code of PasswordPolicyRequirementsNotMet may be returned if the specified password does not meet the domain's configured requirements. Note that in order to prevent privilege escalation, users who have UpdateUser rights will be denied access to update another user in their domain when that user has any domain privilege in any domain they do not. If the new password does \*not\* match the old password, all of the target user's sessions will be terminated. If the Buzz application settings disallow student updating their own passwords, this will (also) be enforced here. The new password is checked against the password policy that is in effect *for the target user*, which is the domain's policy combined with the stricter of any requirements configured for the personas that user currently holds and, for users with root domain privileges, the root domain's minimum requirements. This is the same policy that Login3 enforces. For this API, a warning may also be returned to the caller as a "warning" property on the response object. The value of this property will indicate what the problem is. PasswordPolicyRequirementsNotMet indicates that the password update succeeded, but the password policy is configured to warn users when the new password they selected does not meet the active policy requirements, but that will be allowed anyway. An appropriate warning should be issued indicating that it is recommended that the user change their password, but the user should be allowed to proceed after the warning. When the caller is *not already authenticated*, redeeming the emailed reset token is what authenticates them, and the token this command returns is a new session - so it is a login, and it enforces multi-factor authentication exactly as Login3 does. Control of the user's mailbox is worth no more than the password itself and does not stand in for a second factor. The same warnings UpdatePassword returns are returned here on the (successful) response: SecondFactorRequired when the user has multi-factor authentication configured and has not yet satisfied it, and SecondFactorConfigurationNowRequired when the password policy requires multi-factor authentication that the user has not configured. In both cases the password really was changed and every existing session for the user has been terminated, but the token in the response is a short-lived token good only for completing (or configuring) the second factor - not a session token. A valid remembermfa token satisfies the second factor here just as it does for Login3. A response carries only one warning, so when a second factor is owed *and* the new password trips a warn-level policy rule, the second-factor warning is the one returned - it is the one the caller has to act on. A user who has forgotten their password *and* lost their second factor must be helped by an administrator. A caller who *is* already signed in as the user the token names is never asked for a second factor *code* by this command: they presented it when they logged in. Being signed in as somebody else does not count - the session this mints belongs to the token's user, not to the caller - and neither does a token that is only part-way through logging in, such as the short-lived one Login3 returns alongside SecondFactorRequired. In order to help the user understand why a password is (or will be) rejected, when either a password policy violation error or warning occurs, a reason attribute will be included in the response that indicates which part of the password policy the password did not meet. That reason string should exactly match the attribute name in the password policy that was violated. If there are multiple violations, only the first one detected will be returned. ## Request **Method:** POST **Rights:** A token generated by the ResetPassword API. **Request body (JSON):** ```json { "request": { "cmd": "finishpasswordreset", "token": "string", "newpassword": "string", "remembermfa": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `finishpasswordreset` | Yes | | | `token` | string | Yes | A secure single-use token that identifies the user to update. The server generates this token and includes it in the email message it sends in response to ResetPassword calls. Pass it back exactly as it was received: this command accepts only the current query-string form, which begins with version=, and rejects the older opaque form with a BadRequest. | | `newpassword` | string | Yes | New password for the user. Maximum possible length is 64KB. | | `remembermfa` | string | No | An optional remember MFA token that identifies the device as one which has been previously authorized. When it is valid, the user is not asked for a second factor again after the reset. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "token": "string", "authenticationexpirationminutes": "int" } } } ``` ### user *(optional)* This node conforms to the User format. | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | A new authentication token since the token used to make the call has been terminated. | | `authenticationexpirationminutes` | int | The number of minutes before this new token will expire. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAdminPasswordChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminPasswordChanged.md) | During the request | The target account holds an active Administrator role. Sent whether the change succeeds or fails. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | Completing a reset leaves the user signed in. | | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | Completing a reset stores the new password on the user record. | | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | Completing a reset ends the user's other sessions. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | Completing a reset leaves the user signed in, which starts a session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Changes the password from a ResetPassword email link. **Request body:** ```json { "request": { "cmd": "finishpasswordreset", "token": "version=1&userid=27×tamp=2026-07-28T21%3A14%3A02Z&onetimecode=2026-04-02T17%3A55%3A31Z&hash=Uu9k3S%2Bx1s7QpX0mJcW4bQhV6nZr8yTgL1AeK5dMoP0%3D", "newpassword": "newpassword" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "27", "firstname": "Tiger", "lastname": "Jones", "username": "teacher", "email": "tiger.jones@myschool.edu", "domainid": "24", "domainname": "Test", "userspace": "myschool", "token": "iuds980fds789078asv78cz0890889wr7890a7fdsa75390q2789", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [ResetPassword](https://api.agilixbuzz.com/docs/entry/Command/ResetPassword.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [SecondFactorAuthenticate](https://api.agilixbuzz.com/docs/entry/Command/SecondFactorAuthenticate.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) --- # ForcePasswordChange Forces a user to change their password the next time they login, exactly as if their password had expired. Note that in order to prevent privilege escalation, users who have UpdateUser rights will be denied access to update another user in their domain when that user has any domain privilege in any domain they do not. Further, if the target user has a cross-domain enrollment with rights other than ReadCourse/Section and Participate in any other domain, the user requesting the update must also have UpdateUser rights in the domain of that enrollment. ## Request **Method:** POST **Rights:** UpdateUser@userid **Content-Type:** application/json **Request body (JSON):** ```json { "request": { "cmd": "forcepasswordchange", "userid": "id" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `forcepasswordchange` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user whose password needs to be changed. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example marks the user with ID 582094 so that they will have to change their password the next time they login. **URL:** `?cmd=forcepasswordchange&userid=582094` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [GetPasswordLoginAttemptHistory](https://api.agilixbuzz.com/docs/entry/Command/GetPasswordLoginAttemptHistory.md) - [GetEffectivePasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/GetEffectivePasswordPolicy.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # GenerateAttempt > **Deprecated** — use [GenerateSubmission](https://api.agilixbuzz.com/docs/entry/../Command/GenerateSubmission.md) instead. This command generates an assessment attempt by processing assessment and randomization criteria from the assessment definition. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `generateattempt` | | `entityid` | string | Yes | ID of the course or section that owns the questions. | | `itemid` | string | Yes | ID of the assessment item. | ## Response **Response body (JSON):** ```json { "attempt": {} } ``` ### attempt The attempt format is currently internal and subject to change. See *Student Exam Attempt File* under Other Schemas for more details. --- # GenerateSubmission > **Deprecated** — use [GetAttempt](https://api.agilixbuzz.com/docs/entry/GetAttempt.md) instead. This command generates an assessment submission by processing assessment and randomization criteria from the assessment definition. Call GenerateSubmission to retrieve an initial submission for Assessment and Homework items. This call takes an optional template, use it to generate additional attempts for Homework items. GenerateSubmission will generate a new submission based on the template, preserving question order and parameter values if possible. When adding this new submission to an existing submission, you need to update the new partid values to unique numbers. ## Request **Method:** POST **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `generatesubmission` | | `enrollmentid` | id | Yes | ID of the enrollment for which to generate the assessment submission. | | `itemid` | string | Yes | ID of the assessment item. | **Request body (JSON):** ```json { "request": {} } ``` ## Response **Response body (JSON):** ```json { "submission": {} } ``` ### submission See Submission for more details. ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # GetActiveUserCount Gets the number of active users either currently or for the given date range. If the date range specified includes a partial unit of the grouping unit specified, only the activity in the partial unit specified is counted. For example, if the date range specified is 2012-01-15 through 2012-02-15 and the data is grouped by month, the user activity between 2012-01-15 and 2012-01-31 will be returned in one row and the user activity between 2012-02-01 and 2012-02-15 will be returned in another row. For the purposes of this function, an active user is any user that was logged in at any point before the end of the specified time window and was logged out at any point after the start of the specified time window. The user logout will be estimated as 15 minutes after the last user activity. This function only works in terms of days (so you can't specify 1:00 PM-2:00 PM on the same day and get any results). For finer granularity, use the user activity details (GetUserActivity). ## Request **Method:** GET **Rights:** ReadUser@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getactiveusercount` | | `domainid` | id | Yes | Domain ID of the domain to get active user counts for. | | `includedescendantdomains` | bool | No | Whether or not to recurse through all descendant domains in addition to the specified domain. Default is false. | | `persona` | enum-Persona | No | An optional persona to restrict the count(s) to. If not specified, returns numbers for ALL personas. | | `startdate` | datetime | No | Specifies the start date to use to filter activity. If neither startdate nor enddate is specified, current activity will be returned. | | `enddate` | datetime | No | Specifies the end date to use to filter activity. If neither startdate nor enddate is specified, current activity will be returned. | | `byday` | bool | No | Groups results by calendar day (UTC). | | `bymonth` | bool | No | Groups results by calendar month (UTC). | | `byyear` | bool | No | Groups results by calendar year (UTC). | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "activity": { "activeusers": [ { "date": "datetime", "count": "int" } ] } } } ``` ### activity #### activeusers | Attribute | Type | Description | |-----------|------|-------------| | `date` | datetime | The start of the range in question (either the current date-time, the day, the first day of the month, or the first day of the year in the group). | | `count` | int | The number of active users in the range indicated by the date. | ## Example This example retrieves the number of users currently active in the domain with ID activity log for the domain with ID 1337. **URL:** `?cmd=getactiveusercount&domainid=1337` **Response** (code: `OK`): ```json { "response": { "code": "OK", "activity": { "activeusers": [ { "date": "2013-05-24", "count": "37" } ] } } } ``` ## See Also - [GetUserActivity](https://api.agilixbuzz.com/docs/entry/Command/GetUserActivity.md) --- # GetActorRights This command lists entities that an actor (user) has rights for. ## Request **Method:** GET **Rights:** ReadUser@actorid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getactorrights` | | `actorid` | id | Yes | ID of the actor (user) to get rights for. | | `entitytypes` | string | Yes | The entity types to get rights for. One or more of the following separated by a vertical bar (\|). 'D' for domains, 'C' for courses, 'S' for sections, 'E' for enrollments or 'U' for users. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "entities": { "domain": [ { "domainid": "id", "name": "string", "userspace": "string", "reference": "string", "creationdate": "datetime", "roleid": "id", "flags": "RightsFlags" } ], "course": [ { "courseid": "id", "title": "string", "reference": "string", "guid": "guid", "domainid": "id", "domainame": "string", "schema": "2", "creationdate": "datetime", "roleid": "id", "flags": "RightsFlags", "enrollmentid": "id", "enrollmentstatus": "EnrollmentStatus", "enrollmentstartdate": "datetime", "enrollmentenddate": "datetime" } ], "enrollment": [ { "enrollmentid": "id", "reference": "string", "userid": "id", "userreference": "string", "lastname": "string", "firstname": "string", "username": "string", "userspace": "string", "entityid": "id", "entitytype": "C|S", "title": "string", "entityreference": "string", "baseid": "id", "basetitle": "string", "basereference": "string", "status": "EnrollmentStatus", "roleid": "id", "privileges": "RightsFlags", "startdate": "datetime", "enddate": "datetime", "flags": "RightsFlags" } ], "user": [ { "userid": "id", "firstname": "string", "lastname": "string", "reference": "string", "userspace": "string", "username": "string", "creationdate": "datetime", "roleid": "id", "flags": "RightsFlags" } ] } } } ``` ### entities #### domain *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | Domain ID. | | `name` | string | Domain name. | | `userspace` | string | Domain userspace (login prefix) value. | | `reference` | string | Domain reference field value. Typically this is an external ID. | | `creationdate` | datetime | Domain creation date. | | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags for the user in the domain. The value -1 indicates all rights, including any that may be defined in the future. | #### course *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `courseid` | id | Course ID | | `title` | string | Course title | | `reference` | string | *(optional)* Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `guid` | guid | Globally unique course ID (guid) | | `domainid` | id | ID of the domain that owns the course | | `domainame` | string | Name of the domain that owns the course | | `schema` | string | The schema version of the course. All new courses should be created with schema 2. CreateCourses supports schema 1 (formerly called GoCourse courses) for backwards compatibility. | | `creationdate` | datetime | Creation date of the course | | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags for the user in the course | | `enrollmentid` | id | Enrollment ID | | `enrollmentstatus` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | EnrollmentStatus for the user | | `enrollmentstartdate` | datetime | Start date for the enrollment | | `enrollmentenddate` | datetime | End date for the enrollment | #### enrollment *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | Enrollment ID. | | `reference` | string | *(optional)* Reference field for this enrollment. | | `userid` | id | ID of the enrollment's user. | | `userreference` | string | *(optional)* Reference field for the enrollment's user. | | `lastname` | string | Last name of the enrollment's user. | | `firstname` | string | First name of the enrollment's user. | | `username` | string | Username of the enrollment's user. | | `userspace` | string | Userspace, or login prefix, of the enrollment's user. | | `entityid` | id | ID of the enrollment's course or section. | | `entitytype` | string | "C" if the enrollment is on a course, "S" if the enrollment is on a section | | `title` | string | Title of the enrollment's course or section. | | `entityreference` | string | *(optional)* Reference value for the enrollment's course or section. | | `baseid` | id | *(optional)* If the enrollment is on a section, the ID of the section's course, "0" otherwise. | | `basetitle` | string | *(optional)* If the enrollment is on a section, title of the section's course. | | `basereference` | string | *(optional)* If the enrollment is on a section, the reference value of the section's course. | | `status` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | EnrollmentStatus of the enrollment. | | `roleid` | id | Role ID that optionally specifies privileges. | | `privileges` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise OR of RightsFlags for the user. | | `startdate` | datetime | Start date for the enrollment. | | `enddate` | datetime | End date for the enrollment. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags for the user on the enrollment. | #### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the user. | | `firstname` | string | User's first or given name. | | `lastname` | string | User's last or surname. | | `reference` | string | User's reference field value. | | `userspace` | string | Userspace (login prefix) of this user's domain. | | `username` | string | Username of this user. | | `creationdate` | datetime | Date and time that this user was created. | | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | Bitwise-OR of this user's RightsFlags for the entity. | ## Example This example shows user ID 1257 has all rights to two domains. **URL:** `?cmd=getactorrights&actorid=1257&entitytypes=D` **Response** (code: `OK`): ```json { "response": { "code": "OK", "entities": { "domain": [ { "domainid": "4", "name": "Virtual District", "userspace": "vdistrict", "reference": "123123123123", "creationdate": "2007-06-07T16:37:50.237Z", "flags": "-1" }, { "domainid": "4879", "name": "Virtual School", "userspace": "vschool", "reference": "123412341234", "creationdate": "2007-06-07T17:14:56.38Z", "flags": "-1" } ] } } } ``` ## See Also - [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [UpdateRights](https://api.agilixbuzz.com/docs/entry/Command/UpdateRights.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # GetAnnouncement This command gets an announcement, which is a file that conforms to the Announcement format. With this command, you can retrieve the entire announcement or individual parts of it. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getannouncement` | | `entityid` | id | Yes | Entity ID (domain or course) to retrieve the announcement from. | | `path` | string | Yes | Unique path to the zip-compressed announcement file. | | `filepath` | string | No | When *packagetype* is *file*, *filepath* is the path to a file within the zip-compressed announcement. For example, specify a *filepath* to retrieve an attachment from within the announcement. | | `packagetype` | string | No | Specifies the format of the returned data. These are possible values: - **data** - Returns just the contents of the *meta.xml* file from within the zip-compressed Announcement. - **file** - Returns a single file from within the zip-compressed Announcement. You must also specify *filepath* to identify which file to retrieve. - **zip** - Returns the entire zip-compressed Announcement file, which contains meta.xml and any supporting attached files. | | `version` | int | No | Version of the announcement to retrieve. Omit *version* to retrieve the most recent announcement. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example Get the announcement from domain with ID 1274 and path e362a72809af4dd882797522d9db6c61.zip **URL:** `?cmd=getannouncement&entityid=1274&path=e362a72809af4dd882797522d9db6c61.zip` ## See Also - [Announcement](https://api.agilixbuzz.com/docs/entry/Schema/Announcement.md) - [GetAnnouncementInfo](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementInfo.md) - [GetAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementList.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # GetAnnouncementInfo This command gets information about an announcement. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getannouncementinfo` | | `entityid` | id | Yes | Entity ID (domain or course) that contains the announcement. | | `path` | string | Yes | Unique path to the announcement. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "announcement": { "entityid": "id", "entitytype": "C|S|D", "path": "string", "title": "string", "version": "string", "startdate": "datetime", "enddate": "datetime", "domainid": "id", "domainname": "string", "coursetitle": "string", "sectiontitle": "string", "viewed": "boolean", "creationdate": "datetime", "modifieddate": "datetime", "creator": { "firstname": "string", "lastname": "string" }, "modifier": { "firstname": "string", "lastname": "string" }, "groups": { "group": [ { "id": "id", "title": "string" } ] }, "roles": { "role": [ { "flags": "RightsFlags" } ] } } } } ``` ### announcement | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | Entity ID (domain or course) that owns this announcement. | | `entitytype` | string | Type of the owning entity of this announcement: C for course, S for section, and D for domain. | | `path` | string | Path to the annoucement resource. | | `title` | string | Annoucement title. | | `version` | string | Annoucement version. | | `startdate` | datetime | Annoucement start date and time. | | `enddate` | datetime | Annoucement end date and time. | | `domainid` | id | The ID of the domain that contains the course or section of the announcement. This is also the domain that defines the recipient roles. | | `domainname` | string | *(optional)* When entitytype is D, the name of the domain that this announcement was sent to. | | `coursetitle` | string | *(optional)* When entitytype is C, the title of the course that this announcement was sent to. | | `sectiontitle` | string | *(optional)* When entitytype is S, the title of the section that this announcement was sent to. | | `viewed` | boolean | *(optional)* Whether the user has viewed this announcement. This is normally the calling user; however, when the requested path was obtained for another user (for example from GetUserAnnouncementList or GetDomainContent with a userid) and the caller has ReadUser rights on that user, it reflects that user's viewed state. | | `creationdate` | datetime | Announcement creation date and time. | | `modifieddate` | datetime | Annoucement last modified date and time. | #### creator *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first (given) name of the user who created the announcement. | | `lastname` | string | The last name (surname) of the user who created the announcement. | #### modifier *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first (given) name of the user who last modified the announcement. | | `lastname` | string | The last name (surname) of the user who last modified the announcement. | #### groups *(optional)* Recipient groups of this announcement. Applies only when entitytype is C. ##### group | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of the course group. | | `title` | string | Title of the group. | #### roles *(optional)* Recipient roles of this announcement. Applies only when entitytype is C or S. ##### role | Attribute | Type | Description | |-----------|------|-------------| | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | Bitwise-OR of the RightsFlags that define the recipient role in the course. | ## Example This example gets the announcement information from the course with ID 268973 for the announcement with a path of b9221989332b40d48edaaaae34fb9f8e.zip. **URL:** `?cmd=getannouncementinfo&entityid=268973&path=b9221989332b40d48edaaaae34fb9f8e.zip` **Response** (code: `OK`): ```json { "response": { "code": "OK", "announcement": { "entityid": "268973", "entitytype": "C", "path": "b9221989332b40d48edaaaae34fb9f8e.zip", "title": "Grades are posted", "startdate": "2011-02-10T07:00:00Z", "enddate": "2011-02-18T06:59:00Z", "version": "2", "domainid": "9909", "domainname": "State University", "coursetitle": "Biology 3", "viewed": true, "creationdate": "2011-02-10T23:47:04.233Z", "modifieddate": "2011-02-10T23:55:04.633Z", "creator": { "firstname": "Jeff", "lastname": "Gammon" }, "modifier": { "firstname": "Jeff", "lastname": "Gammon" }, "roles": { "role": [ { "flags": "552155348992" }, { "flags": "2265055232" }, { "flags": "131073" } ] } } } } ``` ## See Also - [Announcement](https://api.agilixbuzz.com/docs/entry/Schema/Announcement.md) - [GetAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncement.md) - [GetUserAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetUserAnnouncementList.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # GetAnnouncementList This command lists an entity's announcements. To get the content of the returned announcements, call GetAnnouncement. ## Request **Method:** GET **Rights:** PostDomainAnnouncements|ReadDomain@entityid when entityid is a domain ID, OR UpdateCourse|ReadGradebook|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid when entityid is a course ID **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getannouncementlist` | | `entityid` | id | Yes | ID of the domain or course to list announcements for. | | `modifieddate` | datetime | No | Optional filter value that limits the result to announcements whose modified date is on or after the specified date. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "announcements": { "announcement": [ { "path": "string", "entityid": "id", "title": "string", "version": "string", "startdate": "datetime", "enddate": "datetime", "recurse": "boolean", "hasurl": "boolean", "creationdate": "datetime", "modifieddate": "datetime" } ] } } } ``` ### announcements #### announcement | Attribute | Type | Description | |-----------|------|-------------| | `path` | string | Unique path to the announcement. | | `entityid` | id | ID of the entity that owns the announcement. | | `title` | string | The announcement title. | | `version` | string | The announcement version. | | `startdate` | datetime | The start datetime of the announcement. | | `enddate` | datetime | The end datetime of the announcement. | | `recurse` | boolean | For domain announcements, whether the announcement is visible to descendent domains. | | `hasurl` | boolean | Currently unused. | | `creationdate` | datetime | The creation datetime of the announcement. | | `modifieddate` | datetime | The modified datetime of the announcement. | ## Example This example lists the announcements in the domain with ID 6153. **URL:** `?cmd=getannouncementlist&entityid=6153` **Response** (code: `OK`): ```json { "response": { "code": "OK", "announcements": { "announcement": [ { "entityid": "6153", "path": "02e839940ac34dd3ae466b42f61e6418.zip", "title": "Final Exam moved to Friday", "version": "2", "startdate": "2008-04-24T00:00:00Z", "enddate": "2008-04-25T23:59:00Z", "recurse": true, "hasurl": false, "creationdate": "2008-04-24T09:58:15.75Z", "modifieddate": "2008-04-24T09:58:27.75Z" }, { "entityid": "6153", "path": "b2ac7c19527e4cf29e28da922df2657d.zip", "title": "Final Exams results declared", "version": "2", "startdate": "2008-04-24T00:00:00Z", "enddate": "2009-04-24T23:59:00Z", "recurse": false, "hasurl": false, "creationdate": "2008-04-24T11:38:17.773Z", "modifieddate": "2008-04-24T11:41:07.32Z" } ] } } } ``` ## See Also - [GetAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncement.md) - [GetUserAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetUserAnnouncementList.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # GetApiTimeLimits Gets information about the current API time limits for the authenticated account, or a specified user, domain, or customer that the authenticated account has access to. Note that this API should only be used for manually diagnosing issues and verifying hostnames, \*not\* for controlling code flow and timing. Code control and timing should use the values in the HTTP response headers documented in the ApiTimeLimiting concept. An action value of Allow indicates that when the limit is exceeded, logging will occur, but the request will be allowed to proceed. An action value of ForceRetry indicates than when the limit is exceeded, the request will be rejected with a 429 Too Many Requests response and the appropriate headers estimating how long the caller should wait. The indicated scope is a string that uniquely identifies the set of counters used in that context, and contains the ID of the entity (user, domain, or customer) that the associated limits are attached to. Standard, Interactive, Background, and Testing usage are all tracked separately. The number of provisioned milliseconds corresponds to thousandths of a vCPU. ## Request **Method:** GET **Rights:** ControlUser@userid, ControlDomain@domainid, ControlDomain@customerid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getapitimelimits` | | `userid` | id | Yes | User ID of the user to get API time limit information for. | | `domainid` | id | Yes | Domain ID of the domain to get API time limit information for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "apiTimeLimits": { "custom": { "standard": { "hostname": "string", "action": "string", "scope": "string", "minimumProvisionedMilliseconds": "int", "maximumProvisionedMilliseconds": "int", "acceleration": "int", "currentProvisionedMilliseconds": "int", "currentProvisionedMillisecondsUsed": "int", "currentProvisionedMillisecondsRemaining": "int", "recentPeakMillisecondsUsed": "int", "recentPeakAcceleration": "int" }, "interactive": { "hostname": "string", "action": "string", "scope": "string", "minimumProvisionedMilliseconds": "int", "maximumProvisionedMilliseconds": "int", "acceleration": "int", "currentProvisionedMilliseconds": "int", "currentProvisionedMillisecondsUsed": "int", "currentProvisionedMillisecondsRemaining": "int", "recentPeakMillisecondsUsed": "int", "recentPeakAcceleration": "int" }, "background": { "hostname": "string", "action": "string", "scope": "string", "minimumProvisionedMilliseconds": "int", "maximumProvisionedMilliseconds": "int", "acceleration": "int", "currentProvisionedMilliseconds": "int", "currentProvisionedMillisecondsUsed": "int", "currentProvisionedMillisecondsRemaining": "int", "recentPeakMillisecondsUsed": "int", "recentPeakAcceleration": "int" }, "testing": { "hostname": "string", "action": "string", "scope": "string", "minimumProvisionedMilliseconds": "int", "maximumProvisionedMilliseconds": "int", "acceleration": "int", "currentProvisionedMilliseconds": "int", "currentProvisionedMillisecondsUsed": "int", "currentProvisionedMillisecondsRemaining": "int", "recentPeakMillisecondsUsed": "int", "recentPeakAcceleration": "int" } } } } } ``` ### apiTimeLimits #### custom ##### standard | Attribute | Type | Description | |-----------|------|-------------| | `hostname` | string | The DNS hostname to use for requests for this scope. | | `action` | string | The action taken when the limit is exceeded, Allow or ForceRetry. | | `scope` | string | A string uniquely identifying the limit scope. | | `minimumProvisionedMilliseconds` | int | The number of milliseconds of usage (per second of actual time) that is always allowed for this scope. | | `maximumProvisionedMilliseconds` | int | The maximum number of milliseconds (per second of actual time) that will ever be allowed for this scope. | | `acceleration` | int | The fastest rate (per second) at which the provisioning can increase before reaching the maximum level. | | `currentProvisionedMilliseconds` | int | The current allowed usage rate (the number of milliseconds allowed to be used per second of actual time, equivalent to thousandths of a vCPU). | | `currentProvisionedMillisecondsUsed` | int | The amount of the scope's provisioned usage that has actually been used. When this number hits (or exceeds) currentProvisionedMilliseconds, requests may fail with a response indicating that the caller is using too many resources or increasing the rate of usage too quickly. | | `currentProvisionedMillisecondsRemaining` | int | The number of milliseconds of processing currently available for this scope, which may include more than one second of provisioned usage because usage is tracked over sliding window rather than second-by-second. | | `recentPeakMillisecondsUsed` | int | The highest value for currentProvisionedMilliseconds that would have been returned if this call had been made during peak recent usage. | | `recentPeakAcceleration` | int | The highest value for acceleration that would have been returned if this call had been made during the fastest increase in usage. | ##### interactive | Attribute | Type | Description | |-----------|------|-------------| | `hostname` | string | The DNS hostname to use for requests for this scope. | | `action` | string | The action taken when the limit is exceeded, Allow or ForceRetry. | | `scope` | string | A string uniquely identifying the limit scope. | | `minimumProvisionedMilliseconds` | int | The number of milliseconds of usage (per second of actual time) that is always allowed for this scope. | | `maximumProvisionedMilliseconds` | int | The maximum number of milliseconds (per second of actual time) that will ever be allowed for this scope. | | `acceleration` | int | The fastest rate (per second) at which the provisioning can increase before reaching the maximum level. | | `currentProvisionedMilliseconds` | int | The current allowed usage rate (the number of milliseconds allowed to be used per second of actual time, equivalent to thousandths of a vCPU). | | `currentProvisionedMillisecondsUsed` | int | The amount of the scope's provisioned usage that has actually been used. When this number hits (or exceeds) currentProvisionedMilliseconds, requests may fail with a response indicating that the caller is using too many resources or increasing the rate of usage too quickly. | | `currentProvisionedMillisecondsRemaining` | int | The number of milliseconds of processing currently available for this scope, which may include more than one second of provisioned usage because usage is tracked over sliding window rather than second-by-second. | | `recentPeakMillisecondsUsed` | int | The highest value for currentProvisionedMilliseconds that would have been returned if this call had been made during peak recent usage. | | `recentPeakAcceleration` | int | The highest value for acceleration that would have been returned if this call had been made during the fastest increase in usage. | ##### background | Attribute | Type | Description | |-----------|------|-------------| | `hostname` | string | The DNS hostname to use for requests for this scope. | | `action` | string | The action taken when the limit is exceeded, Allow or ForceRetry. | | `scope` | string | A string uniquely identifying the limit scope. | | `minimumProvisionedMilliseconds` | int | The number of milliseconds of usage (per second of actual time) that is always allowed for this scope. | | `maximumProvisionedMilliseconds` | int | The maximum number of milliseconds (per second of actual time) that will ever be allowed for this scope. | | `acceleration` | int | The fastest rate (per second) at which the provisioning can increase before reaching the maximum level. | | `currentProvisionedMilliseconds` | int | The current allowed usage rate (the number of milliseconds allowed to be used per second of actual time, equivalent to thousandths of a vCPU). | | `currentProvisionedMillisecondsUsed` | int | The amount of the scope's provisioned usage that has actually been used. When this number hits (or exceeds) currentProvisionedMilliseconds, requests may fail with a response indicating that the caller is using too many resources or increasing the rate of usage too quickly. | | `currentProvisionedMillisecondsRemaining` | int | The number of milliseconds of processing currently available for this scope, which may include more than one second of provisioned usage because usage is tracked over sliding window rather than second-by-second. | | `recentPeakMillisecondsUsed` | int | The highest value for currentProvisionedMilliseconds that would have been returned if this call had been made during peak recent usage. | | `recentPeakAcceleration` | int | The highest value for acceleration that would have been returned if this call had been made during the fastest increase in usage. | ##### testing | Attribute | Type | Description | |-----------|------|-------------| | `hostname` | string | The DNS hostname to use for requests for this scope. | | `action` | string | The action taken when the limit is exceeded, Allow or ForceRetry. | | `scope` | string | A string uniquely identifying the limit scope. | | `minimumProvisionedMilliseconds` | int | The number of milliseconds of usage (per second of actual time) that is always allowed for this scope. | | `maximumProvisionedMilliseconds` | int | The maximum number of milliseconds (per second of actual time) that will ever be allowed for this scope. | | `acceleration` | int | The fastest rate (per second) at which the provisioning can increase before reaching the maximum level. | | `currentProvisionedMilliseconds` | int | The current allowed usage rate (the number of milliseconds allowed to be used per second of actual time, equivalent to thousandths of a vCPU). | | `currentProvisionedMillisecondsUsed` | int | The amount of the scope's provisioned usage that has actually been used. When this number hits (or exceeds) currentProvisionedMilliseconds, requests may fail with a response indicating that the caller is using too many resources or increasing the rate of usage too quickly. | | `currentProvisionedMillisecondsRemaining` | int | The number of milliseconds of processing currently available for this scope, which may include more than one second of provisioned usage because usage is tracked over sliding window rather than second-by-second. | | `recentPeakMillisecondsUsed` | int | The highest value for currentProvisionedMilliseconds that would have been returned if this call had been made during peak recent usage. | | `recentPeakAcceleration` | int | The highest value for acceleration that would have been returned if this call had been made during the fastest increase in usage. | ## Example This example retrieves the time limit information for the calling user. **URL:** `?cmd=getapitimelimits` **Response** (code: `OK`): ```json { "response": { "code": "OK", "apiTimeLimits": { "custom": { "standard": { "action": "ForceRetry", "scope": "1337", "minimumProvisionedMilliseconds": "1000", "maximumProvisionedMilliseconds": "1000", "acceleration": "0", "currentProvisionedMilliseconds": "1000", "currentProvisionedMillisecondsUsed": "0", "currentProvisionedMillisecondsRemaining": "300000", "recentPeakMillisecondsUsed": "1000", "recentPeakAcceleration": "0" }, "interactive": { "action": "ForceRetry", "scope": "I-1337", "minimumProvisionedMilliseconds": "1000", "maximumProvisionedMilliseconds": "1000000", "acceleration": "0", "currentProvisionedMilliseconds": "1000", "currentProvisionedMillisecondsUsed": "0", "currentProvisionedMillisecondsRemaining": "300000", "recentPeakMillisecondsUsed": "1000", "recentPeakAcceleration": "0" }, "background": { "action": "ForceRetry", "scope": "B-1337", "minimumProvisionedMilliseconds": "1000", "maximumProvisionedMilliseconds": "1000", "acceleration": "0", "currentProvisionedMilliseconds": "1000", "currentProvisionedMillisecondsUsed": "0", "currentProvisionedMillisecondsRemaining": "300000", "recentPeakMillisecondsUsed": "1000", "recentPeakAcceleration": "0" }, "testing": { "action": "ForceRetry", "scope": "T-1337", "minimumProvisionedMilliseconds": "10", "maximumProvisionedMilliseconds": "50", "acceleration": "0", "currentProvisionedMilliseconds": "10", "currentProvisionedMillisecondsUsed": "0", "currentProvisionedMillisecondsRemaining": "3000", "recentPeakMillisecondsUsed": "10", "recentPeakAcceleration": "0" } } } } } ``` ## See Also - [ApiTimeLimiting](https://api.agilixbuzz.com/docs/entry/Concept/ApiTimeLimiting.md) --- # GetAttempt This command returns the data needed for an assessment or homework attempt. It includes the parts of the question needed for taking the assessment. GetAttempt loads a saved attempt, or creates a new one if there is no saved attempt. If the assessment is password protected, this command returns InvalidCredentials unless you provide the correct password. ## Request **Method:** GET **Rights:** ReadCourse@enrollment.courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getattempt` | | `enrollmentid` | id | Yes | ID of the enrollment. | | `itemid` | string | Yes | ID of the assessment item. | | `groupid` | string | No | ID of the homework group. Required when the item is homework. | | `questionid` | string | No | Pipe (\|) separated list of question ids to include in the attempt. User needs to be an author on the course. | | `password` | string | No | Password for protected assessments | | `utcoffset` | int | No | The number of minutes, positive or negative, from UTC time that the end-user's timezone is. The default is 0. | ## Response **Response body (JSON):** ```json { "attempt": { "page": "int", "save": "boolean", "seconds": "int", "adaptive": "boolean", "question": [ { "partid": "string", "number": "string", "page": "int", "passage": "string", "bookmark": "boolean", "clientdata": "string", "body": { "$value": "html" }, "interaction": { "type": "string", "count": "int", "data": "string", "flags": "InteractionFlags", "height": "int", "minwords": "int", "maxwords": "int", "texttype": "string", "width": "int", "maxfiles": "int", "filetypes": "string", "label": "string", "choicesorientation": "Top | Bottom | Left | Right", "choicestitle": "string", "choicewidth": "int", "choiceheight": "int", "answerwidth": "int", "answerheight": "int", "choice": [ { "id": "string", "selected": "boolean", "body": { "$value": "html" } } ], "left": [ { "id": "string", "studentChoice": "string", "body": { "$value": "html" } } ], "right": [ { "id": "string", "body": { "$value": "html" } } ], "text": [ { "answer": "string" } ], "answer": { "$value": "string" } }, "apip": {}, "meta": {}, "submission": { "answer": {}, "notes": { "$value": "html" }, "attachments": { "attachment": [ { "name": "string", "path": "string" } ] } }, "response": { "pointspossible": "double" } } ], "content": { "$value": "html" }, "button": [ { "action": "previous|next|submit" } ], "template": { "$value": "html" } } } ``` ### attempt | Attribute | Type | Description | |-----------|------|-------------| | `page` | int | Current page number | | `save` | boolean | Allow save and continue for this attempt | | `seconds` | int | Number of seconds the user has spent on the attempt | | `adaptive` | boolean | *(optional)* Set to true if the assessment is adaptive. | #### question | Attribute | Type | Description | |-----------|------|-------------| | `partid` | string | Submission part id | | `number` | string | Number of question | | `page` | int | Page number of question on the original assessment | | `passage` | string | *(optional)* If this question is part of a passage, then the part ID of the passage. | | `bookmark` | boolean | *(optional)* *true* if this question was bookmarked (see SaveAttemptAnswers). | | `clientdata` | string | *(optional)* Temporary opaque string data for client use. Stripped during submission. | ##### body ##### interaction | Attribute | Type | Description | |-----------|------|-------------| | `type` | string | Question interaction type | | `count` | int | Number of interaction, for multiple interaction questions. | | `data` | string | Custom question data | | `flags` | [InteractionFlags](https://api.agilixbuzz.com/docs/entry/Enum/InteractionFlags.md) | Flags for this interaction | | `height` | int | Height in pixels of the input box for essay questions | | `minwords` | int | Minimum words for essay questions. This attribute is absent if minwords is 0. The default is 0. | | `maxwords` | int | Maximum words for essay questions. This attribute is absent if maxwords is 0. The default is 0. | | `texttype` | string | Text question input type | | `width` | int | Width in pixels of the input box for text questions | | `maxfiles` | int | The maximum number of files allowed for upload for fileupload questions | | `filetypes` | string | *(optional)* An optional vertical-bar separated list of allowed file extensions for file upload for fileupload questions. | | `label` | string | Optional label format for multiple choice, multiple answer, and ordering questions | | `choicesorientation` | string | *(optional)* Choices box orientation for drag-and-drop, matching question. | | `choicestitle` | string | *(optional)* Choices box title for drag-and-drop, matching question. | | `choicewidth` | int | *(optional)* Choice width (pixels) for drag-and-drop, matching question. | | `choiceheight` | int | *(optional)* Choice box height (pixels) for drag-and-drop, matching question. | | `answerwidth` | int | *(optional)* Answer width (pixels) for drag-and-drop, matching question. | | `answerheight` | int | *(optional)* Answer height (pixels) for drag-and-drop, matching question. | ###### choice For multiple-choice and multiple-answer questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the choice | | `selected` | boolean | User selected this choice. For multiple-choice and multiple-answer questions only. | ####### body ###### left For matching and ordering questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the match | | `studentChoice` | string | Id of the right side that the user selected | ####### body ###### right For matching and ordering questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the right side | ####### body ###### text For text questions | Attribute | Type | Description | |-----------|------|-------------| | `answer` | string | Student answer for this part. | ###### answer For text questions ##### apip ##### meta ##### submission ###### answer ###### notes *(optional)* ###### attachments *(optional)* ####### attachment | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | Name of a uploaded file by student for fileupload questions. | | `path` | string | File path to a uploaded file. | ##### response | Attribute | Type | Description | |-----------|------|-------------| | `pointspossible` | double | Points possible for this response. | #### content *(optional)* #### button *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `action` | string | Button to display on adaptive assessment. | #### template *(optional)* ## See Also - [GetAttemptReview](https://api.agilixbuzz.com/docs/entry/Command/GetAttemptReview.md) - [GetNextQuestion](https://api.agilixbuzz.com/docs/entry/Command/GetNextQuestion.md) - [GetSubmissionState](https://api.agilixbuzz.com/docs/entry/Command/GetSubmissionState.md) - [SaveAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SaveAttemptAnswers.md) - [SubmitAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SubmitAttemptAnswers.md) --- # GetAttemptFile This command gets a uploaded file associated with a fileupload question. ## Request **Method:** GET **Rights:** ReadCourse@enrollment.courseid or GradeExam|UpdateCourse@enrollment.courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getattemptfile` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this uploaded file belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this uploaded file belongs. | | `partid` | string | Yes | PartId of the fileupload question to which uploaded files beglong. | | `filepath` | string | Yes | File path to the uploaded file as specified in the response of the PutAttemptFile command. | | `inline` | bool | No | Whether the requested file content to be displayed inline or as an attachment. Default is false. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the student uploaded file for enrollment with ID 4317, the item with ID "test12", fileupload question with part ID "5", and file path "answer.doc". **URL:** `?cmd=getattemptfile&enrollmentid=4317&itemid=test12&partid=5&filepath=answer.doc` ## See Also - [PutAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/PutAttemptFile.md) - [DeleteAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/DeleteAttemptFile.md) --- # GetAttemptReview This command returns the data needed to review an assessment or homework attempt. It includes the parts of the question available for the review according to the review settings of the item. It can also return a uploaded file associated with a fileupload question in an assessment or homework attempt. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getattemptreview` | | `enrollmentid` | id | Yes | ID of the enrollment. | | `itemid` | string | Yes | ID of the assessment item. | | `groupid` | string | No | ID of the homework group. If the item is a homework item and groupid is not specified, returns the latest attempt for each group. | | `submissionversion` | int | No | Version of the submission. The default is the latest submission. | | `responseversion` | int | No | Version of the response. The default is the latest response matching the submission. | | `packagetype` | string | No | Specifies the format of the returned data. These are possible values: - **data** - Returns the data needed to review an assessment or homework attempt. This is the default value. - **file** - Returns the content of a uploaded file associated with a fileupload quesiton in the attempt. You must also specify partid, filepath, and inline. | | `partid` | string | No | PartId of the fileupload question the requested file is associated with in the attempt. | | `filepath` | string | No | File path to the requested file in the attempt. | | `inline` | bool | No | Whether the requested file content to be displayed inline or as an attachment. Default is false. | | `forviewing` | bool | No | When *true*, GetAttemptReview treats the current user as a student in the course when evaluating feedback conditions, even if the current user has GradeExam rights on the course. Otherwise, the current user is treated as a teacher if they have GradeExam rights on the course. The default is *false*. | ## Response **Response body (JSON):** ```json { "attempt": { "seconds": "int", "question": [ { "partid": "string", "number": "string", "page": "int", "passage": "string", "excluded": "boolean", "correct": "boolean", "body": { "$value": "html" }, "feedback": [ { "$value": "html" } ], "interaction": { "type": "string", "count": "int", "data": "string", "flags": "InteractionFlags", "height": "int", "minwords": "int", "maxwords": "int", "maxfiles": "int", "filetypes": "string", "texttype": "string", "width": "int", "label": "string", "choicesorientation": "Top | Bottom | Left | Right", "choicestitle": "string", "choicewidth": "int", "choiceheight": "int", "answerwidth": "int", "answerheight": "int", "choice": [ { "id": "string", "selected": "boolean", "correct": "boolean", "partial": "string", "body": { "$value": "html" }, "feedback": [ { "$value": "html" } ] } ], "left": [ { "id": "string", "studentChoice": "string", "correctChoice": "string", "correct": "boolean", "body": { "$value": "html" } } ], "right": [ { "id": "string", "body": { "$value": "html" } } ], "text": [ { "correct": "boolean", "answer": "string", "correctanswer": "string" } ], "answer": { "$value": "string" } }, "apip": {}, "meta": {}, "template": { "$value": "html" }, "learningobjectives": { "objective": [ { "id": "string" } ] }, "submission": { "answer": {}, "notes": { "$value": "html" }, "attachments": { "attachment": [ { "name": "string", "path": "string" } ] } }, "response": { "pointsassigned": "double", "pointscomputed": "double", "pointspossible": "double", "flags": "ResponseFlags", "attachments": { "attachment": [ { "name": "string", "path": "string" } ] }, "audio": { "$value": "string" }, "notes": { "$value": "html" } }, "rubric": { "entityid": "string", "path": "string", "version": "string", "rubricrule": [ { "id": "string", "max": "double", "assigned": "double", "body": [ { "$value": "html" } ], "notes": { "$value": "html" } } ] } } ] } } ``` ### attempt | Attribute | Type | Description | |-----------|------|-------------| | `seconds` | int | Number of seconds the user has spent on the attempt | #### question | Attribute | Type | Description | |-----------|------|-------------| | `partid` | string | Submission part id | | `number` | string | Number of question | | `page` | int | Page number of question on the original assessment | | `passage` | string | *(optional)* The part id of the passage question for this question | | `excluded` | boolean | *(optional)* Question has been excluded from the assessment score | | `correct` | boolean | *(optional)* The answer is correct. This attribute is absent if the assessment settings prevent this data. In that case the application should treat the question as neither correct nor incorrect. | ##### body ##### feedback *(optional)* ##### interaction | Attribute | Type | Description | |-----------|------|-------------| | `type` | string | Question interaction type | | `count` | int | Number of interaction, for multiple interaction questions. | | `data` | string | Custom question data | | `flags` | [InteractionFlags](https://api.agilixbuzz.com/docs/entry/Enum/InteractionFlags.md) | Flags for this interaction | | `height` | int | Height in pixels of the input box for essay questions | | `minwords` | int | Minimum words for essay questions. This attribute is absent if minwords is 0. The default is 0. | | `maxwords` | int | Maximum words for essay questions. This attribute is absent if maxwords is 0. The default is 0. | | `maxfiles` | int | The maximum number of files allowed for upload for fileupload questions | | `filetypes` | string | *(optional)* An optional vertical-bar separated list of allowed file extensions for file upload for fileupload questions. | | `texttype` | string | Text question input type | | `width` | int | Width in pixels of the input box for text questions | | `label` | string | Optional label format for multiple choice, multiple answer, and ordering questions | | `choicesorientation` | string | *(optional)* Choices box orientation for drag-and-drop, matching question. | | `choicestitle` | string | *(optional)* Choices box title for drag-and-drop, matching question. | | `choicewidth` | int | *(optional)* Choice width (pixels) for drag-and-drop, matching question. | | `choiceheight` | int | *(optional)* Choice box height (pixels) for drag-and-drop, matching question. | | `answerwidth` | int | *(optional)* Answer width (pixels) for drag-and-drop, matching question. | | `answerheight` | int | *(optional)* Answer height (pixels) for drag-and-drop, matching question. | ###### choice For multiple-choice and multiple-answer questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the choice | | `selected` | boolean | User selected this choice. For multiple-choice and multiple-answer questions only. | | `correct` | boolean | *(optional)* The user correctly picked this value. This attribute is absent if the assessment settings prevent this data. In that case the application should treat is as neither correct nor incorrect. | | `partial` | string | *(optional)* This attribute can have the values of *full*, *partial*, or *none*, which indicate that user receives full, partial, or zero score if this choice is selected. The attribute instead of *correct* attribute is returned when the question is a multiple choice question and allows partial credit. | ####### body ####### feedback ###### left For matching and ordering questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the match | | `studentChoice` | string | Id of the right side that the user selected | | `correctChoice` | string | *(optional)* Id of the correct choice from the right side. This attribute is absent if the assessment settings prevent this data. | | `correct` | boolean | *(optional)* The user correctly picked this value. This attribute is absent if the assessment settings prevent this data. In that case the application should treat is as neither correct nor incorrect. | ####### body ###### right For matching and ordering questions | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Id of the right side | ####### body ###### text For text questions | Attribute | Type | Description | |-----------|------|-------------| | `correct` | boolean | *(optional)* The user answered this part correctly. This attribute is absent if the assessment settings prevent this data. In that case the application should treat is as neither correct nor incorrect. | | `answer` | string | Student answer for this part. | | `correctanswer` | string | *(optional)* A list of CRLF delimited list of correct answers. | ###### answer ##### apip ##### meta ##### template *(optional)* ##### learningobjectives *(optional)* Defines which course learning objectives this question is aligned to. ###### objective | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | ID (guid) of the course objective that this question is aligned to. This ID corresponds to an objective's guid, which is defined in the Course Data of the course that contains this question. | ##### submission ###### answer ###### notes *(optional)* ###### attachments *(optional)* ####### attachment | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | Name of a uploaded file submitted by student for fileupload questions. | | `path` | string | File path to a uploaded file. | ##### response | Attribute | Type | Description | |-----------|------|-------------| | `pointsassigned` | double | *(optional)* Points achieved as determined by the teacher. This can be omitted if pointscomputed is specified; however, at least one of them must be present. If both exist, pointsassigned takes precedence over pointscomputed. The special value **NaN** indicates that pointscomputed should be cleared without assigning a new score. | | `pointscomputed` | double | *(optional)* Points achieved as determined by any auto-grading process. This can be omitted if pointsassigned is specified; however, at least one of them must be present. If both exist, pointsassigned takes precedence over pointscomputed. | | `pointspossible` | double | Points possible for this response. | | `flags` | [ResponseFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResponseFlags.md) | *(optional)* Bitwise OR of ResponseFlags values to set. | ###### attachments *(optional)* ####### attachment | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | The original file name (display name) of the attachment file. | | `path` | string | Unique path within the .zip file to the attachment file. | ###### audio *(optional)* ###### notes *(optional)* ##### rubric *(optional)* Defines the rubric that was used for providing a response to the submission. | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | string | *(optional)* The entity ID of the course containing the rubric. This is only provided if the entity containing the rubric is not the entity containing the assessment. | | `path` | string | The resource path for the rubric. | | `version` | string | The version of the rubric resource. If the user matches the user for the enrollmentid then the version is one rubric used to grade the attempt. Otherwise it is the latest rubric version. | ###### rubricrule | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The unique ID of the rule within this rubric. | | `max` | double | The maximum score for this rubric rule. Specify 0 to indicate that graders leave text feedback instead of a numerical score for this rubric rule. | | `assigned` | double | *(optional)* The assigned score | ####### body ####### notes *(optional)* ## See Also - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) - [SubmitAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SubmitAttemptAnswers.md) --- # GetBadge This command gets the badge image. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getbadge` | | `entityid` | id | Yes | The user that received the badge. | | `badgeid` | string | Yes | The ID of the badge. | ## Response **Content-Type:** image/png ## Example **URL:** `?cmd=getbadge&entityid=6050&badgeid=28383792873897398739873382748` ## See Also - [CreateBadge](https://api.agilixbuzz.com/docs/entry/Command/CreateBadge.md) - [GetBadgeList](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeList.md) - [GetBadgeAssertion](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeAssertion.md) - [DeleteBadge](https://api.agilixbuzz.com/docs/entry/Command/DeleteBadge.md) --- # GetBadgeAssertion This command gets the assertion associated with a badge. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getbadge` | | `entityid` | id | Yes | The ID of the user or enrollment that received the badge. | | `badgeid` | string | Yes | The ID of the badge. | ## Response **Content-Type:** application/json ## Example **URL:** `?cmd=getbadgeassertion&entityid=6050&badgeid=28383792873897398739873382748` ## See Also - [CreateBadge](https://api.agilixbuzz.com/docs/entry/Command/CreateBadge.md) - [GetBadgeList](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeList.md) - [GetBadge](https://api.agilixbuzz.com/docs/entry/Command/GetBadge.md) - [DeleteBadge](https://api.agilixbuzz.com/docs/entry/Command/DeleteBadge.md) --- # GetBadgeList This command gets a list of badges for a user. ## Request **Method:** GET **Rights:** ReadUser@entityid where entity refers to a user; ReadGradebook@the enrollment's entity ID where entity refers to an enrollment. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getbadgelist` | | `entityid` | id | Yes | ID of the user or enrollment for which to get badges. | | `query` | string | No | Optional query used to filter the list of items to retrieve. See Free-Form Data Query for more details. The query expression can include the following *xpath* fields defined in Assertions: - **/assertion@recipient** - **/assertion@issued\_on** - **/assertion@evidence** - **/assertion@enrollmentid** - **/assertion/badge@version** - **/assertion/badge@name** - **/assertion/badge@image** - **/assertion/badge@description** - **/assertion/badge@criteria** - **/assertion/badge/issuer@origin** - **/assertion/badge/issuer@name** - **/assertion/badge/issuer@org** - **/assertion/badge/issuer@contact** | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "badges": { "badge": { "id": "string", "assertion": { "recipient": "string", "salt": "string", "issued_on": "datetime", "evidence": "string", "enrollmentid": "id", "courseid": "id", "coursetitle": "string", "itemid": "id", "itemtitle": "id", "requirements": "string", "badge": { "name": "string", "image": "string", "description": "string", "criteria": "string", "issuer": { "origin": "string", "name": "string", "org": "string", "contact": "string" } } } } } } } ``` ### badges #### badge | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the badge. | ##### assertion | Attribute | Type | Description | |-----------|------|-------------| | `recipient` | string | The salted hash that identifies the recipient of the badge. | | `salt` | string | The salt for the recipient hash. | | `issued_on` | datetime | The datetime when the server issued the badge. | | `evidence` | string | *(optional)* A URL with information about the user earned this specific badge instance. | | `enrollmentid` | id | *(optional)* If the badge was assigned to an enrollment, the enrollment ID. | | `courseid` | id | *(optional)* If the badge was assigned to an enrollment, the enrollment's course ID. | | `coursetitle` | string | *(optional)* If the badge was assigned to an enrollment, the enrollment's course title. | | `itemid` | id | *(optional)* If the badge was auto-assigned for an item, the item's ID. | | `itemtitle` | id | *(optional)* If the badge was auto-assigned for an item, the item's title. | | `requirements` | string | *(optional)* The requirements for earning the badge. | ###### badge | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | The name of the badge. No more than 128 characters. | | `image` | string | A URL to the original image for the badge. | | `description` | string | A description of the badge. No more than 128 characters. | | `criteria` | string | A URL describing the criteria for earning the badge. | ####### issuer | Attribute | Type | Description | |-----------|------|-------------| | `origin` | string | The origin of the issuer. | | `name` | string | The name of the issuer. | | `org` | string | *(optional)* Organization that issued the badge. | | `contact` | string | *(optional)* An email address associated with the issuer | ## Example This example gets the badges for the user with ID 6050 issued by http://myschool.agilixbuzz.com. **URL:** `?cmd=getbadgelist&entityid=6050&query=/assertion/badge/issuer='http://myschool.agilixbuzz.com'` **Response** (code: `OK`): ```json { "response": { "code": "OK", "badges": { "badge": { "id": "28383792873897398739873382748", "assertion": { "recipient": "sha256$382879374582987ab8d97e289782", "salt": "2398739782323987", "issued_on": "Mon, 15 Jun 2009 20:45:30 GMT", "badge": { "name": "Big", "image": "/Badge/Image", "description": "The big badge", "criteria": "/Criteria/Big", "issuer": { "origin": "http://myschool.agilixbuzz.com", "name": "Buzz" } } } } } } } ``` ## See Also - [CreateBadge](https://api.agilixbuzz.com/docs/entry/Command/CreateBadge.md) - [GetBadge](https://api.agilixbuzz.com/docs/entry/Command/GetBadge.md) - [GetBadgeAssertion](https://api.agilixbuzz.com/docs/entry/Command/GetBadgeAssertion.md) - [DeleteBadge](https://api.agilixbuzz.com/docs/entry/Command/DeleteBadge.md) --- # GetBlog This command gets a blog or journal message, which conforms to the Message format. ## Request **Method:** GET **Rights:** ReadCourse or ReadSection in the course referred to by enrollmentid, or the caller must be an observer of that enrollment. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getblog` | | `enrollmentid` | id | Yes | Enrollment ID of the blog owner. | | `itemid` | id | Yes | ID of the associated blog or journal item from the course manifest. | | `messageid` | string | Yes | ID of the message to get. | | `packagetype` | string | No | Specifies the format of the returned data. These are possible values: - **data** - Returns the Message data from within the zip-compressed blog package. Equivalent to the now obsolete value xml. - **file** - Returns a single file from within the zip-compressed blog package. You must also specify filepath to identify which file to retrieve. - **zip** - Returns the entire zip-compressed blog package containing the file meta.xml, which is a Message, and any supporting attached files. This is the default value if the parameter is not supplied. | | `version` | string | No | Optional message version to get. If omitted, the most recent version is returned. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This example assumes the enrollment with ID 6162 exists with a blog message of ID "89b2b64f710949018d5cf618a0bb681e.zip". **URL:** `?cmd=getblog&enrollmentid=6162&itemid=AE5T8&messageid=89b2b64f710949018d5cf618a0bb681e.zip` ## See Also - [Message](https://api.agilixbuzz.com/docs/entry/Schema/Message.md) - [GetBlogList](https://api.agilixbuzz.com/docs/entry/Command/GetBlogList.md) - [PutBlog](https://api.agilixbuzz.com/docs/entry/Command/PutBlog.md) --- # GetBlogList This command returns a list of blog or journal messages for the specified enrollment and item, ordered by message creationdate. ## Request **Method:** GET **Rights:** ReadCourse or ReadSection in the course referred to by enrollmentid, or the caller must be an observer of that enrollment. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getbloglist` | | `enrollmentid` | id | Yes | Enrollment ID of the blog owner. | | `itemid` | id | Yes | ID of the associated blog or journal item from the course manifest. | | `parentid` | string | No | ID of the parent to get replies to. Omit to retrieve top-most messages. | | `start` | int | No | The index of the first message to return. The default is 0. | | `rows` | int | No | The maximum number of messages to return. If omitted, all messages are returned. | | `startdate` | datetime | No | An optional, inclusive starting datetime to filter returned messages. GetBlogList returns messages created on or after startdate. | | `enddate` | datetime | No | An optional, exclusive ending datetime to filter returned messages. GetBlogList returns messages created before (but not including) enddate. | | `tag` | string | No | An optional tag value by which to filter the list. GetBlogList returns only messages that contain the tag value in their Message XML. | | `sort` | string | No | Specifies the order in which to return the messages. Specify asc to order from oldest to newest creationdate. Specify desc to order from newest to oldest creationdate. The default is asc. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "messages": { "message": [ { "id": "string", "creationdate": "datetime", "creationby": "id", "modifieddate": "datetime", "modifiedby": "id", "version": "string", "authorid": "id", "replies": "int", "title": "string", "wordcount": "int", "creator": { "firstname": "string", "lastname": "string" }, "tags": { "tag": [ { "$value": "string" } ] } } ] } } } ``` ### messages #### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the message. | | `creationdate` | datetime | The creation date of the message. | | `creationby` | id | The ID of the user that created the message. | | `modifieddate` | datetime | The last-modified date of the message. | | `modifiedby` | id | The ID of the user that last modified the message. | | `version` | string | The version of this message. | | `authorid` | id | *(optional)* Enrollment ID of the user who created the message. | | `replies` | int | *(optional)* The number of replies to this message. The default is 0. | | `title` | string | *(optional)* The title of the blog post. | | `wordcount` | int | *(optional)* The number of words in this message. The default is 0. | ##### creator | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first (given) name of the user who created the message. | | `lastname` | string | The last name (surname) of the user who created the message. | ##### tags *(optional)* Searchable tags for this message. ###### tag ## Example This example gets the blog list for enrollment ID 303137, filtered by blog messages with the tag value of "learn". **URL:** `?cmd=getbloglist&enrollmentid=303137&itemid=BLOG1&tag=learn` **Response** (code: `OK`): ```json { "response": { "code": "OK", "messages": { "message": [ { "id": "c03b477007f54f288433b326691d5afb.zip", "creationdate": "2011-03-01T21:06:30.37Z", "modifieddate": "2011-03-01T21:06:30.37Z", "version": "1", "authorid": "303137", "title": "Listen and learn", "wordcount": 18, "creator": { "firstname": "Kate", "lastname": "Gammon" }, "tags": { "tag": [ { "$value": "learn" }, { "$value": "struggle" } ] } }, { "id": "efc0c8e799fe47bc967c352d03d981a1.zip", "creationdate": "2011-03-01T21:09:13.457Z", "modifieddate": "2011-03-01T21:09:13.457Z", "version": "1", "authorid": "303137", "title": "Struggling", "wordcount": 7, "creator": { "firstname": "Kate", "lastname": "Gammon" }, "tags": { "tag": [ { "$value": "like" }, { "$value": "learn" } ] } } ] } } } ``` ## See Also - [Message](https://api.agilixbuzz.com/docs/entry/Schema/Message.md) - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) - [GetBlogSummary](https://api.agilixbuzz.com/docs/entry/Command/GetBlogSummary.md) - [PutBlog](https://api.agilixbuzz.com/docs/entry/Command/PutBlog.md) --- # GetBlogSummary This command returns a blog or journal summary for each enrollment in the specified entity. GetBlogSummary returns summaries for only those enrollments and groups whose blogs or journals the caller can access. ## Request **Method:** GET **Rights:** ReadCourse@entityid or ReadSection@entityid, or the caller must be an observer of (or own) an enrollment within entityid. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getblogsummary` | | `entityid` | id | Yes | ID of the entity that contains the blog messages. | | `itemid` | string | Yes | ID of the associated blog or journal item from the course manifest. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "groups": { "group": [ { "id": "id", "title": "string", "enrollment": [ { "id": "id", "firstname": "string", "lastname": "string", "messages": "int" } ] } ] } } } ``` ### groups #### group Defines a group of enrollments. Can also be a placeholder group for journals or blogs that do not use groups. | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | The group ID. The value is empty for the placeholder group for journals or blogs that do not use groups. | | `title` | string | The group title. The value is empty for the placeholder group for journals or blogs that do not use groups. | ##### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | Enrollment ID of the blog owner. | | `firstname` | string | The first (given) name of the blog owner. | | `lastname` | string | The last (surname) name of the blog owner. | | `messages` | int | The number of top-level messages in this enrollment's blog. | ## Example This example gets the summary for blog ID BLOG1, which has two groups. **URL:** `?cmd=getblogsummary&entityid=268973&itemid=BLOG1` **Response** (code: `OK`): ```json { "response": { "code": "OK", "groups": { "group": [ { "id": "320886", "title": "Group 1", "enrollment": [ { "id": "320555", "firstname": "Johny", "lastname": "Cash", "messages": 0 }, { "id": "303137", "firstname": "Kate", "lastname": "Gammon", "messages": 3 }, { "id": "457501", "firstname": "Reba", "lastname": "McIntire", "messages": 0 }, { "id": "457502", "firstname": "Brooke", "lastname": "Rickenbach", "messages": 1 } ] }, { "id": "320887", "title": "Group 2", "enrollment": [ { "id": "303138", "firstname": "Hank", "lastname": "Williams", "messages": 0 }, { "id": "303139", "firstname": "Willie", "lastname": "Nelson", "messages": 0 } ] } ] } } } ``` ## See Also - [Message](https://api.agilixbuzz.com/docs/entry/Schema/Message.md) - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) - [GetBlogList](https://api.agilixbuzz.com/docs/entry/Command/GetBlogList.md) - [PutBlog](https://api.agilixbuzz.com/docs/entry/Command/PutBlog.md) --- # GetCalendar Gets the iCalendar (RFC2445) file of events for the user or enrollments specified by token. This command requires no additional authentication outside the token. The URL is meant for consumption of calendar programs that connect to .ics files. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcalendar` | | `token` | string | Yes | Token returned from GetCalendarToken that specifies the user or enrollments. | ## Response **Content-Type:** text/calendar ## Example Get the calendar for the specified user. **URL:** `?cmd=getcalendar&token=zuQrJfrTw1toX3zM.3UycD!!` ## See Also - [GetCalendarToken](https://api.agilixbuzz.com/docs/entry/Command/GetCalendarToken.md) --- # GetCalendarItems This command gets duedates and blackoutdates for the specified enrollments. ## Request **Method:** GET **Rights:** ReadUser@userid or userid is current signed-on user when userid is non-empty; ReadUser@the enrollment's userid or the enrollment's userid is the current signed-on user or ControlCourse|UpdateCourse|ReadGradebook@the enrollment's course when enrollmentid is non-empty; **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcalendaritems` | | `userid` | id | No | ID of the user for which to get calendar items. If both userid and enrollmentid are empty, then userid defaults to the userid of the current signed-on user. | | `enrollmentid` | id | No | A comma-delimited list of enrollment IDs for which to get calendar items. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "calendar": { "duedates": { "item": [ { "id": "id", "title": "string", "type": "string", "duedate": "string", "duedategrace": "int", "enrollmentid": "id", "courseid": "id", "coursetitle": "string", "parents": { "parent": [ { "id": "id", "title": "string" } ] }, "grade": {} } ] }, "blackoutdates": { "range": [ { "start": "date", "end": "date", "name": "string", "type": "string", "enrollmentids": "string" } ] } } } } ``` ### calendar #### duedates ##### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of the item. | | `title` | string | Title of the item. | | `type` | string | Type of the item | | `duedate` | string | *duedate* as defined in ItemData. If this is an item in a continuous course then the due dates are calculated automatically based on the enrollment's start date and end date. | | `duedategrace` | int | *duedategrace* as defined in ItemData. | | `enrollmentid` | id | Enrollment ID | | `courseid` | id | Course ID | | `coursetitle` | string | Title of the course | ###### parents *(optional)* This node lists all of the parent items in order (closest to the item first). ####### parent | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of this item | | `title` | string | Title of this item | ###### grade *(optional)* This node conforms to the Grade format, and is included only if the item is graded. #### blackoutdates *(optional)* ##### range | Attribute | Type | Description | |-----------|------|-------------| | `start` | date | The range starting date, in the format of "YYYY-MM-DD", such as "2015-12-25". | | `end` | date | The range ending date, in the foramt of "YYYY-MM-DD", such as "2016-01-01". | | `name` | string | *(optional)* The name of the blackout range as defined in the course or domain. | | `type` | string | The type of the source where the blackout date range is define. It can be one of these values: domain, course, or user. | | `enrollmentids` | string | Comma delimited list of enrollment IDs that use this blackout date range. | ## Example This example retrieves calendar items for the user with ID 15002. **URL:** `?cmd=getcalendaritems&userid=15002` **Response** (code: `OK`): ```json { "response": { "code": "OK", "calendar": { "duedates": { "item": [ { "duedate": "2015-11-18T07:00:00Z", "id": "7a7a999bf05b419881a296dbaa5ef65a", "title": "Assignment 1", "type": "Assignment", "duedategrace": "100", "enrollmentid": "5594713", "courseid": "5594704", "coursetitle": "Geometry" }, { "duedate": "2015-12-16T07:00:00Z", "id": "76630bc6a81044b3bbdf4f0491b012ff", "title": "Assignment 2", "type": "Assignment", "duedategrace": "0", "enrollmentid": "5594713", "courseid": "5594704", "coursetitle": "Geometry" } ] }, "blackoutdates": { "range": [ { "start": "2015-11-26", "end": "2015-11-27", "name": "Thanksgiving", "type": "course", "enrollmentids": "5594713" }, { "start": "2015-12-24", "end": "2015-12-25", "name": "Christmas", "type": "user", "enrollmentids": "5594713" } ] } } } } ``` ## See Also - [GetDueSoonList](https://api.agilixbuzz.com/docs/entry/Command/GetDueSoonList.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetCalendarToken Get a token to generate a URL that can retrieve the current user's calendar without any authentication. ## Request **Method:** GET **Rights:** Currently logged in user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcalendartoken` | | `enrollment` | string | No | Vertical bar separated list of enrollment ids. If not specified the calendar return items for all active enrollments. | | `appname` | string | No | Application name that is used in some parts of the response to GetCalendar, like *PRODID*, and *X-WR-CALNAME*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "calendar": { "token": "string" } } } ``` ### calendar | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | Token to use in call to GetCalendar, that encapsulated the current user and the optional enrollments. | ## Example Get the token for the current user. **URL:** `?cmd=getcalendartoken` **Response** (code: `OK`): ```json { "response": { "code": "OK", "calendar": { "token": "zuQrJfrTw1toX3zM.3UycD!!" } } } ``` ## See Also - [GetCalendar](https://api.agilixbuzz.com/docs/entry/Command/GetCalendar.md) --- # GetCertificates This command gets the completion certificates associated with a course or section enrollment. ## Request **Method:** GET **Rights:** ReadUser@domainid where domainid is the domain that contains enrollmentid. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcertificates` | | `enrollmentid` | id | Yes | Enrollment for which to list certificates. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "certificates": { "certificate": [ { "certificateguid": "guid", "certificatedate": "datetime", "enrollmentid": "id", "enrollmentstatus": "EnrollmentStatus", "coursetitle": "string", "coursedescription": "string", "sectiontitle": "string", "domainname": "string", "autocompletetype": "(None|All|Gradable|Category)", "autocompletecategory": "string", "teachers": { "teacher": [ { "id": "id" } ] } } ] } } } ``` ### certificates #### certificate | Attribute | Type | Description | |-----------|------|-------------| | `certificateguid` | guid | Globally unique ID of this certificate. | | `certificatedate` | datetime | The date-time that the certificate was created. | | `enrollmentid` | id | Enrollment ID for this certificate. | | `enrollmentstatus` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | EnrollmentStatus for this user's enrollment. | | `coursetitle` | string | Course title for this certificate. | | `coursedescription` | string | Course description for this certificate. | | `sectiontitle` | string | Section title for this certificate. | | `domainname` | string | Domain name for this certificate. | | `autocompletetype` | string | | | `autocompletecategory` | string | When autocompletetype is Category, the ID of the category required for completion. | ##### teachers ###### teacher | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | User ID of teacher who taught the student for this certificate. | ## Example This example assumes the enrollment with ID 6062 exists with these certificates: **URL:** `?cmd=getcertificates&enrollmentid=6062` **Response** (code: `OK`): ```json { "response": { "code": "OK", "certificates": { "certificate": [ { "certificateguid": "710a6393-2ca7-4574-a1fa-e109aa200eca", "certificatedate": "2010-02-23T21:35:14.127Z", "enrollmentid": "6062", "enrollmentstatus": "1", "coursetitle": " Introduction to Computer Science", "coursedescription": " Introduction to the basics of Computer Science", "sectiontitle": "Section 100", "domainname": "State University", "autocompletetype": "None", "autocompletecategory": "0", "teachers": { "teacher": [ { "id": "6068" } ] } } ] } } } ``` ## See Also - [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) --- # GetCommandList This returns a complete list of all commands available on the API Server. ## Request **Method:** GET **Rights:** none **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcommandlist` | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "commands": { "command": [ { "code": "string" } ] } } } ``` ### commands #### command | Attribute | Type | Description | |-----------|------|-------------| | `code` | string | Name of the API command | --- # GetCommandToken This command gets details about a previously created command token. ## Request **Method:** GET **Rights:** ReadUser@scopeentityid and ControlUser@runasuserid (the runasuserid from the associated command token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcommandtoken` | | `commandtokenid` | id | Yes | The ID of the previously created command token. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "commandtoken": { "commandtokenid": "id", "scopeentityid": "id", "description": "string", "startvalidity": "datetime", "endvalidity": "datetime", "version": "int", "code": "id", "runasuserid": "id", "totalusecountlimit": "int", "userusecountlimit": "int", "peruserusecountlimit": "int", "codelength": "int", "user": [ { "userid": "id", "code": "id" } ], "action": { "request": { "cmd": "string" } }, "data": {} } } } ``` ### commandtoken | Attribute | Type | Description | |-----------|------|-------------| | `commandtokenid` | id | The ID of the command token which can be used to identify and possibly modify this command token in the future. | | `scopeentityid` | id | The ID of a domain, group, course, or user to which the command token's use will be restricted. | | `description` | string | A description of the purpose of the command token. (For future reference by you and other humans). | | `startvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will start being valid. Any attempt to use the code before this date/time will result in access being denied. The default value is the beginning of time. | | `endvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will stop being valid. Any attempt to use the code after this date/time will result in access being denied. The default value is the end of time. | | `version` | int | The current version of the command token. | | `code` | id | *(optional)* The code (if perusercodes was false--otherwise there should be a list of users with user-specific codes). | | `runasuserid` | id | The ID of the user the action will be run as. | | `totalusecountlimit` | int | *(optional)* The total number of times the token may be used (not restricted if not specified or zero). | | `userusecountlimit` | int | *(optional)* The total number of unique users that may use the token (not restricted if not specified or zero). | | `peruserusecountlimit` | int | *(optional)* The total number of times any given user may use the token (not restricted if not specified or zero). | | `codelength` | int | The number of characters that should be in the code. | #### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The ID of a user in the specified domain, group, or course (or specified directly). | | `code` | id | The code specific to this user. | #### action ##### request | Attribute | Type | Description | |-----------|------|-------------| | `cmd` | string | The API command to run when the token is redeemed. | #### data *(optional)* Optional free-form structured data. (See Free-form Data for more details.) ## Example This example gets details about the previously created command token with id 587. **URL:** `?cmd=getcommandtoken&commandtokenid=587` **Response** (code: `OK`): ```json { "response": { "code": "OK", "commandtoken": { "commandtokenid": "587", "scopeentityid": "4832", "description": "Self Enrollment in Supplemental Course", "peruserusecountlimit": "1", "codelength": "3", "code": "g4m", "action": { "request": { "cmd": "createenrollments", "requests": { "enrollment": { "domainid": "4832", "entityid": "78903", "userid": "$userid$", "flags": "131073", "status": "1", "schema": "2" } } } } } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # GetCommandTokenInfo This command gets the description and other non-sensitive info about a previously created command token from the code. Note that there may be more than one matching command token. A calling application can distinguish its own codes from others by placing application-specific data into the optional free-form data for the token, always using non-overlapping scopes, and not using per-user tokens. ## Request **Method:** GET **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcommandtokeninfo` | | `code` | string | Yes | The code from the previously created command token. The code may be a user-specific code or a fixed code. | | `scopedomainid` | id | No | The ID of a domain used to lookup the command token (one with a scope of the domain) when the user is not authenticated. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "commandtokens": { "commandtoken": [ { "commandtokenid": "id", "scopeentityid": "id", "description": "string", "startvalidity": "datetime", "endvalidity": "datetime", "version": "int" } ] } } } ``` ### commandtokens #### commandtoken | Attribute | Type | Description | |-----------|------|-------------| | `commandtokenid` | id | The ID of the command token which can be used to identify and possibly modify this command token in the future. | | `scopeentityid` | id | The ID of a domain, group, course, or user to which the command token's use will be restricted. | | `description` | string | A description of the purpose of the command token. (For future reference by you and other humans). | | `startvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will start being valid. Any attempt to use the code before this date/time will result in access being denied. The default value is the beginning of time. | | `endvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will stop being valid. Any attempt to use the code after this date/time will result in access being denied. The default value is the end of time. | | `version` | int | The current version of the command token. | ## Example This example gets details about the previously created command token with code 'g4m' in either the user's domain, a course they are enrolled in, a group they are a member of, or a code that is user-specific. **URL:** `?cmd=getcommandtokeninfo&code=g4m` **Response** (code: `OK`): ```json { "response": { "code": "OK", "commandtokens": { "commandtoken": [ { "commandtokenid": "587", "scopeentityid": "4832", "description": "Self Enrollment in Supplemental Course" } ] } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # GetConvertedData Retrieves the converted data generated from either ImportData or ExportData and deletes the temporary file. When posting to an iFrame, it may be difficult to process the return value. Using *ImportData* with the *saveto* parameter stores a temporary copy of the data on the server. Also use this command to download files that have been exported using the *ExportData* command. *GetConvertedData* retrieves the data and deletes the copy. The response matches the response that would be given by *ImportData* or *ExportData*. ## Request **Method:** GET **Rights:** Authenticated user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getconverteddata` | | `path` | string | Yes | The value previously passed as *saveto* on the *ImportData* command. | | `name` | string | No | The filename returned in the http header. If not specified, uses the path. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "file": { "row": [ { "col": [ {} ] } ], "error": {} } } } ``` ### file #### row ##### col Value from import #### error *(optional)* Error messages ## Example Upload this file and store in under the name MyCourseImport. ``` Code,Name CHEM 105,General College Chemistry 1 CHEM 106,General College Chemistry 2 CHEM 107,General College Chemistry Laboratory CHEM 223,Quantitative and Qualitative Analysis ``` **URL:** `?cmd=importdata&from=delimited&saveto=MyCourseImport` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [ExportData](https://api.agilixbuzz.com/docs/entry/Command/ExportData.md) - [ImportData](https://api.agilixbuzz.com/docs/entry/Command/ImportData.md) --- # GetCookie > **Deprecated** — use [ExtendSession](https://api.agilixbuzz.com/docs/entry/ExtendSession.md) instead. Each API command automatically refreshes the API authorization token, extending the expiration for the duration originally specified at login, but if you need to keep the extend the token life without making any specific API call, this command will simply extend the token duration. For example, if the interval between API calls in your application is long (over 10 minutes), you can call GetCookie more frequently than every 10 minutes to keep the user authorized. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcookie` | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "cookie": { "token": "string", "authenticationexpirationminutes": "int", "userid": "id", "proxyuserid": "id" } } } ``` ### cookie | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | The token that needs to be extended (usually the one returned from Login). | | `authenticationexpirationminutes` | int | The number of minutes until the specified authentication token will timeout unless there are subsequent calls that affect it. The token expiration will automatically be extended when any API commands are called and the token will be immediately expired when Logout is called or when explicitly revoked by an administrator prior to the normal expiration. This value is returned so that clients know how often they need to call GetCookie or some other function to keep their authentication from expiring under normal circumstances. | | `userid` | id | User ID used to authenticate this session. | | `proxyuserid` | id | *(optional)* If this authorization token is being used in a proxy session, the ID of the proxied as user. See Proxy for details on proxy sessions. | ## Example **URL:** `?cmd=getcookie` **Response** (code: `OK`): ```json { "response": { "code": "OK", "cookie": { "token": "SYC-UhGJ|7rsM!xiaWNlb9P8dxHRoLA", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) --- # GetCourse > **Deprecated** — use [GetCourse2](https://api.agilixbuzz.com/docs/entry/Command/GetCourse2.md) instead. This command gets information for a course. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcourse` | | `courseid` | id | Yes | ID of the course to get. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "course": { "courseid": "id", "title": "string", "reference": "string", "guid": "guid", "domainid": "id", "schema": "int", "creationdate": "datetime", "baseid": "id", "type": "Continuous|Range", "startdate": "datetime", "enddate": "datetime", "days": "int", "term": "string", "data": {} } } } ``` ### course | Attribute | Type | Description | |-----------|------|-------------| | `courseid` | id | Course ID. | | `title` | string | Course title. | | `reference` | string | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `guid` | guid | Globally unique ID (guid) of this course. | | `domainid` | id | ID of the domain that owns the course. | | `schema` | int | The schema version of the course. | | `creationdate` | datetime | The creation data and time of the course. | | `baseid` | id | *(optional)* If this course is linked to a base course (the base course changes propogate to this course), baseid is the ID of the base course. See CopyCourses for details about creating linked courses. | | `type` | string | The course type. Range types have startdate and enddate but no days, while Continuous have days but no startdate nor enddate. | | `startdate` | datetime | The startdate for the course. Meaningful only when type is Range. | | `enddate` | datetime | The end date for the course. Meaningful only when type is Range. | | `days` | int | The number of days a student has to complete the course. Meaningful only when type is Continuous. | | `term` | string | The academic term of the course. | #### data *(optional)* Optional free-form structured data. (See Free-form Data and Course Data for more details.) ## Example This example assumes the course with ID 6050 already exists. **URL:** `?cmd=getcourse&courseid=6050` **Response** (code: `OK`): ```json { "response": { "code": "OK", "course": { "courseid": "6050", "title": "Algebra I", "reference": "", "guid": "a0a3e20a-ce06-4f80-a61a-7d446c859753", "schema": "2", "domainid": "9909", "baseid": "268973", "type": "Range", "startdate": "2011-03-21T06:00:00Z", "enddate": "2011-09-22T05:59:00Z", "days": 365, "term": "", "creationdate": "2011-03-21T16:00:14.43Z" } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # GetCourse2 This command gets information for a course. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getcourse2` | | `courseid` | id | Yes | ID of the course to get. | | `select` | string | No | Comma-separated list of which data to return. By default, *GetCourse2* returns only the course node. Possible values are: - *data[(...)]* - Includes the course's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. - *teachers* - Includes the list of teachers for the course in the response. - *enrollmentmetrics* - Includes the course's enrollment metrics in the response. - *copypermissions* - Includes the copy permissions available for the course. | | `version` | string | No | The version of the course to get. If omitted, the command returns the latest version. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "course": { "copypermissions": { "allowstatic": "bool", "allowderivativechild": "bool", "allowderivativesibling": "bool" }, "data": {}, "history": [ { "parameters": "string", "course": [ {} ] } ], "domain": { "data": {} }, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "courseenrollmentmetrics": {} } } } ``` ### course This node conforms to the Course format. #### copypermissions *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `allowstatic` | string | The system allows static copies. | | `allowderivativechild` | string | The system allows derivative child copies. | | `allowderivativesibling` | string | The system allows derivative sibling copies. | #### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. #### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ##### course *(optional)* This node conforms to the Course format. These are the results of the history query. #### domain *(optional)* This node conforms to the Domain format. ##### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. #### teachers *(optional)* ##### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | #### courseenrollmentmetrics *(optional)* This node conforms to the Course Enrollment Metrics format. ## Example This example assumes the course with ID 6050 already exists. **URL:** `?cmd=getcourse2&courseid=6050` **Response** (code: `OK`): ```json { "response": { "code": "OK", "course": { "id": "6050", "title": "Algebra I", "domainid": "2829", "reference": "103", "guid": "a0a3e20a-ce06-4f80-a61a-7d446c859753", "schema": "2", "baseid": "0", "type": "Continuous", "startdate": "2011-03-21T06:00:00Z", "enddate": "2011-09-22T05:59:00Z", "days": "128", "term": "", "protection": "0", "flags": "0", "creationdate": "2011-03-21T16:00:14.43Z", "creationby": "512", "modifieddate": "2011-03-21T16:00:14.43Z", "modifiedby": "512", "version": "1" } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # GetDataStreamConfiguration This command gets the data stream configuration previously set using SetDataStreamConfiguration for a specified domain. Note that this does not query configurations further up the domain hierarchy, even if the caller has rights to query that information, this call only returns the configuration set in the specified domain. ## Request **Method:** GET **Rights:** ControlDomain **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdatastreamconfiguration` | | `domainid` | id | No | The ID of the domain whose data stream configuration is desired. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "firehose": [ { "title": "string", "enabled": "boolean", "targetFirehoseStream": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "kinesis": [ { "title": "string", "enabled": "boolean", "targetKinesisStream": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "sqs": [ { "title": "string", "enabled": "boolean", "targetSqsQueue": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "https": [ { "title": "string", "enabled": "boolean", "streamName": "string", "timeoutSeconds": "int", "retries": "int", "endpoints": "string", "httpMethod": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ] } } ``` ### firehose *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `title` | string | The optional title of this target, allowing it to be identified later. | | `enabled` | boolean | Whether this target is enabled or not (defaults to true). | | `targetFirehoseStream` | string | The name of the Kinesis Firehose Delivery Stream to put event records into. | | `roleArn` | string | The ARN of the role to use to connect to the Kinesis Firehose Delivery Stream. | | `targetRegion` | string | *(optional)* The AWS region of the target Firehose stream (for example, us-east-1). If omitted, us-east-1 is used. | #### filter *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `eventType` | string | *(optional)* An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `properties` | string | *(optional)* A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desited property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | ### kinesis *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `title` | string | The optional title of this target, allowing it to be identified later. | | `enabled` | boolean | Whether this target is enabled or not (defaults to true). | | `targetKinesisStream` | string | The name of the Kinesis Data Stream to put event records into. | | `roleArn` | string | The ARN of the role to use to connect to the Kinesis Data Stream. | | `targetRegion` | string | *(optional)* The AWS region of the target Kinesis stream (for example, us-east-1). If omitted, us-east-1 is used. | #### filter *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `eventType` | string | *(optional)* An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `properties` | string | *(optional)* A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desited property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | ### sqs *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `title` | string | The optional title of this target, allowing it to be identified later. | | `enabled` | boolean | Whether this target is enabled or not (defaults to true). | | `targetSqsQueue` | string | The name of the SQS queue to put event records into. | | `roleArn` | string | The ARN of the role to use to connect to the SQS queue. | | `targetRegion` | string | *(optional)* The AWS region of the target SQS queue (for example, us-east-1). If omitted, us-east-1 is used. | #### filter *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `eventType` | string | *(optional)* An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `properties` | string | *(optional)* A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desited property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | ### https *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `title` | string | The optional title of this target, allowing it to be identified later. | | `enabled` | boolean | Whether this target is enabled or not (defaults to true). | | `streamName` | string | A name for this data stream used to distinguish it from any others. | | `timeoutSeconds` | int | The number of seconds to use as a timeout for each attempt to notify a configured HTTPS endpoint. Defaults to 2 seconds. | | `retries` | int | The number of times to retry each endpoint before moving on to the next one. Defaults to 2 retries. | | `endpoints` | string | A semicolon-separated list of the URLs of HTTPS endpoints to call to put event records. The URLs may contain the brace sequences {PartitionKey} which will be replaced with a partition key before making the HTTP request. This allows you to partition the notification handling across multiple URLs. | | `httpMethod` | string | *(optional)* The HTTP method (PUT, POST) to use when sending event notification records. If not specified, defaults to POST. | #### filter *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `eventType` | string | *(optional)* An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `properties` | string | *(optional)* A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desited property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | ## Example Attempt to get the configuration for a domain where no configuration has been set. **URL:** `getdatastreamconfiguration?domainid=582075` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Data Stream Concept Overview](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) - [SetDataStreamConfiguration](https://api.agilixbuzz.com/docs/entry/Command/SetDataStreamConfiguration.md) --- # GetDocument This command retrieves a user document from the server. A user document is content produced by a user in response to using a course within a section. These documents include things like assignment submissions, teacher response to assignments, and exam attempts. ## Request **Method:** GET **Rights:** User who submitted the document or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdocument` | | `enrollmentid` | id | Yes | ID of the user’s enrollment to which this document belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this document belongs. | | `path` | string | Yes | The unique path to the document. You can use forward-slash (/) between path elements to create a document hierarchy. Path cannot start with ‘/’. | | `version` | string | No | Version of the document to retrieve. | ## Response **Content-Type:** package-mime-type **Content-Length:** package-length ## Example **URL:** `?cmd=getdocument&entityid=4317&itemid=assign12&path=assign.zip` ## See Also - [DeleteDocuments](https://api.agilixbuzz.com/docs/entry/Command/DeleteDocuments.md) - [GetDocumentInfo](https://api.agilixbuzz.com/docs/entry/Command/GetDocumentInfo.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # GetDocumentInfo This command retrieves information about one or more user documents from the server. A user document is content produced by a user in response to using a course within a section. These documents include assignment submissions, teacher response to assignments, and exam attempts. ## Request **Method:** POST **Rights:** User who submitted the document or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdocumentinfo` | **Request body (JSON):** ```json { "requests": { "document": [ { "enrollmentid": "id", "itemid": "string", "path": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `document.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user’s enrollment to which this document belongs. | | `document.itemid` | string | Yes | ID of the item (in the course manifest) to which this document belongs. | | `document.path` | string | Yes | The unique path to the document. You can use forward-slash (/) between path elements to create a document hierarchy. Path cannot start with ‘/’. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "document": { "version": "string", "size": "int", "status": "(Hidden|Normal)" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### document | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the document. | | `size` | int | The size, in bytes, of the document. | | `status` | string | *(optional)* The status of the document. | ## See Also - [GetDocument](https://api.agilixbuzz.com/docs/entry/Command/GetDocument.md) --- # GetDomain > **Deprecated** — use [GetDomain2](https://api.agilixbuzz.com/docs/entry/Command/GetDomain2.md) instead. This command gets information for the specified domain. ## Request **Method:** GET **Rights:** ReadDomain@domainid for full domain information. Basic domain information can be retrieved by any user for the domain their account belongs to (own domain with unscoped token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomain` | | `domainid` | id | Yes | ID of the domain to get. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domain": { "domainid": "id", "name": "string", "userspace": "string", "reference": "string", "guid": "guid", "creationdate": "datetime", "flags": "EntityFlags", "data": {} } } } ``` ### domain | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | ID of the domain. | | `name` | string | Title of the domain. | | `userspace` | string | Userspace (login prefix) of the domain. | | `reference` | string | External reference value of the domain. | | `guid` | guid | GUID of the domain | | `creationdate` | datetime | Date and time when the domain was created. | | `flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | Bitwise OR of EntityFlags on the domain. | #### data *(optional)* Optional free-form structured data. See Free Form Data for more details. This data is not returned if the user was only able to call this function because they belong to the domain in question. ## Example This example assumes the domain with ID 4879 exists. **URL:** `?cmd=getdomain&domainid=4879` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domain": { "domainid": "4879", "name": "Virtual School", "userspace": "vschool", "reference": "123412341234", "guid": "11B26B3F-2ABD-4adc-B9CA-5F7F233DBE11", "flags": "0", "creationdate": "2007-06-07T17:14:56.38Z" } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) --- # GetDomain2 This command gets information for the specified domain. ## Request **Method:** GET **Rights:** ReadDomain@domainid for full domain information. Basic domain information can be retrieved by any user for the domain their account belongs to (own domain with unscoped token). ManageLicense@domainid for basic domain information. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomain2` | | `domainid` | id | Yes | ID of the domain to get. | | `select` | string | No | Comma-separated list of which data to return. By default, *GetDomain2* returns only the domain node. Possible values are: - *data* - Includes the domains's free-form structured data in the response. - *history(...)* - Includes the domain history in the response. See History Query for more details. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domain": { "data": {}, "history": [ { "parameters": "string", "domain": [ {} ] } ] } } } ``` ### domain This node conforms to the Domain format. #### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. This data is not returned if the user was only able to call this function because they belong to the domain in question. #### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ##### domain *(optional)* This node conforms to the Domain format. These are the results of the history query. ## Example This example assumes the domain with ID 4879 exists. **URL:** `?cmd=getdomain2&domainid=4879` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domain": { "id": "4879", "name": "Alpha", "userspace": "vschool", "parentid": "223", "reference": "1", "guid": "11B26B3F-2ABD-4adc-B9CA-5F7F233DBE11", "flags": "0", "creationdate": "2007-06-07T17:14:56.38Z", "creationby": "4123", "modifieddate": "2007-06-07T17:14:56.38Z", "modifiedby": "4123", "version": "1" } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) --- # GetDomainActivity This command lists activity for all users in a specified domain. ## Request **Method:** GET **Rights:** ReadUser@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainactivity` | | `domainid` | id | Yes | ID of the domain for which to get user activity. | | `startdate` | datetime | No | Filters the response by login activity that occurred after the specified date. If not specified, uses 1 hour ago. | | `enddate` | datetime | No | Filters the response by login activity that occurred before the specified date. If not specified, uses the current date/time. | | `maxusers` | int | No | Sets the maximum number of users for which activity records will be returned. If not specified, returns data for 1000 users. | | `select` | string | No | Comma-separated list of which data to return. Possible values are: - *user* - Includes user data in the response. - *courseactivity* - Includes course activity for each user in the response. - *courseactivity.seconds* - Includes total number of seconds for all course item activity in the specified date/time range. - *courseactivity.privileges* - Includes the aggregate privilege flags for any enrollments on the course. - *domainrights* - Includes domain rights for each user in the response. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "users": { "user": [ { "id": "long", "domainrights": "long", "courseactivity": [ { "id": "long", "name": "string", "seconds": "long", "privileges": "RightsFlags" } ], "activity": [ { "logindate": "datetime", "logoutdate": "datetime" } ] } ] } } } ``` ### users #### user If "user" is included in the select parameter, the remainder of this node conforms to the User format. | Attribute | Type | Description | |-----------|------|-------------| | `id` | long | User ID | | `domainrights` | long | *(optional)* Domain rights for the user | ##### courseactivity *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `id` | long | Course ID | | `name` | string | Course Title | | `seconds` | long | *(optional)* Total number of seconds spent in activities for all enrollments to this course. | | `privileges` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | *(optional)* The union of privileges for all enrollments to this course. | ##### activity | Attribute | Type | Description | |-----------|------|-------------| | `logindate` | datetime | The date and time the user logged in | | `logoutdate` | datetime | The date and time the user logged out | ## Example This example retrieves domain activity for users in domain 3740260. **URL:** `?cmd=getdomainactivity&domainid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "users": { "user": [ { "id": "3740261", "activity": [ { "logindate": "2012-08-18T16:06:51.747Z" }, { "logoutdate": "2012-10-17T21:17:42.743Z" } ] }, { "id": "3818801", "activity": [ { "logindate": "2012-08-18T16:06:51.747Z" }, { "logoutdate": "2012-10-17T21:17:42.743Z" } ] } ] } } } ``` ## See Also - [GetUserActivity](https://api.agilixbuzz.com/docs/entry/Command/GetUserActivity.md) --- # GetDomainContent This command returns the list of content items for the current signed-on user’s domain. Currently, only announcements are in the list, and only non-expired items are returned (the announcement’s enddate is today or later.) Announcements can originate in ancestor domains, so resulting domain IDs may not equal the current signed-on user’s domain ID. ## Request **Method:** GET **Rights:** No extra rights are needed to return the calling user's own domain content. Returning another user's domain content (via the userid parameter) requires ReadUser rights on that user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomaincontent` | | `userid` | id | No | Optional user whose domain content (and per-announcement viewed state) to return. Defaults to the calling user. An administrator may pass another user's id to retrieve that user's domain content without proxying in as that user. Requires ReadUser rights on the specified user; the request is denied if the caller lacks that right. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domain": { "announcements": { "announcement": { "domainid": "id", "path": "string", "version": "string", "viewed": "(true|false)", "magnitude": "int" } } } } } ``` ### domain #### announcements ##### announcement | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | ID of the domain from which this announcement originated. | | `path` | string | Unique path for the announcement. | | `version` | string | The announcement's version. | | `viewed` | boolean | Whether the user (the calling user, or the user given by the userid parameter) has viewed the announcement. | | `magnitude` | int | Magnitude of the announcement file size. Larger numbers mean larger files. | ## Example Return the content for the user's domain. **URL:** `?cmd=getdomaincontent` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domain": { "announcements": { "announcement": [ { "path": "76d62b5328df488ba2f0611d14cf62e6.zip", "domainid": "4378", "version": "1", "viewed": false, "magnitude": 3 } ] } } } } ``` ## See Also - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # GetDomainEnrollmentMetrics This command gets enrollment metrics for courses in the specified domain. To reduce server load this response may be cached on the server for up to one hour (during that time the data returned from the server may not be current). ## Request **Method:** GET **Rights:** ReadDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainenrollmentmetrics` | | `domainid` | id | Yes | Domain ID that limits the courses to consider. Enrollments in these courses will still be included in the metrics even if they are in other domains. | | `skipempty` | bool | Yes | When true, *GetDomainEnrollmentMetrics* does not return teachers with 0 active, inactive, and complete enrollments. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domainenrollmentmetrics": { "domainid": "id", "active": "int", "inactive": "int", "complete": "int", "red": "int", "yellow": "int", "completion": { "signal": "string" }, "pastperformance": { "signal": "string" }, "teacher": [ { "userid": "id", "firstname": "string", "lastname": "string", "active": "int", "inactive": "int", "complete": "int", "responsiveness": { "signal": "string", "total": "int", "yellow": "int", "red": "int" }, "performance": { "signal": "string" }, "pace": { "signal": "string" }, "completion": { "signal": "string" }, "pastperformance": { "signal": "string" } } ] } } } ``` ### domainenrollmentmetrics | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | Domain ID. | | `active` | int | Number of active enrollments in this domain. An enrollment is considered active if the enrollment's status is active or suspended, and the current date is between the enrollment's start date and end date. | | `inactive` | int | Number of inactive enrollments in this domain. | | `complete` | int | Number of completed enrollments in this domain. | | `red` | int | Number of active enrollments with either a red pace or a red performance. | | `yellow` | int | Number of active enrollments with either a yellow pace or yellow performance. Enrollments with either a red pace or red performance are not included. | #### completion | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The domain's completion status signal. One of *Green*, *Yellow*, or *Red*. | #### pastperformance | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The domain's past performance status signal. One of *Green*, *Yellow*, or *Red*. | #### teacher *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `active` | int | The number of active enrollments in the classes taught by this teacher. | | `inactive` | int | The number of inactive enrollments in classes taught by this teacher. | | `complete` | int | The number of completed enrollments in classes taught by this teacher. | ##### responsiveness | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The teacher's responsiveness status signal. One of *Green*, *Yellow*, or *Red*. | | `total` | int | The total number of student-submitted items awaiting teacher grading. | | `yellow` | int | Count of student-submitted items awaiting teacher grading that have remained ungraded long enough to trigger a *Yellow* teacher responsiveness signal. | | `red` | int | Count of student-submitted items awaiting teacher grading that have remained ungraded long enough to trigger a *Red* teacher responsiveness signal. | ##### performance | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The teacher's performance status signal. One of *Green*, *Yellow*, or *Red*. | ##### pace | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The teacher's pace status signal. One of *Green*, *Yellow*, or *Red*. | ##### completion | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The teacher's completion status signal. One of *Green*, *Yellow*, or *Red*. | ##### pastperformance | Attribute | Type | Description | |-----------|------|-------------| | `signal` | string | The teacher's past performance status signal. One of *Green*, *Yellow*, or *Red*. | ## Example This example assumes the domain with ID 4879 exists. **URL:** `?cmd=getdomainenrollmentmetrics&domainid=4879` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domain": { "domainid": "4879", "active": "52", "red": "20", "yellow": "12", "inactive": "79", "complete": "2", "completion": { "signal": "Red" }, "pastperformance": { "signal": "Red" }, "teacher": [ { "userid": "9911", "firstname": "Tiger", "lastname": "Teaching", "active": "18", "inactive": "25", "complete": "2", "responsiveness": { "signal": "Green" }, "performance": { "signal": "Yellow" }, "pace": { "signal": "Yellow" }, "completion": { "signal": "Red" }, "pastperformance": { "signal": "Yellow" } }, { "userid": "9913", "firstname": "Arthur", "lastname": "Authoritative", "active": "0", "inactive": "6", "complete": "0", "responsiveness": { "signal": "Green" }, "performance": { "signal": "Green" }, "pace": { "signal": "Green" }, "completion": { "signal": "Red" }, "pastperformance": { "signal": "Yellow" } } ] } } } ``` ## See Also - [GetDomain2](https://api.agilixbuzz.com/docs/entry/Command/GetDomain2.md) --- # GetDomainEnrollmentMetricsParameters This command gets parameters that affect calculations used in Enrollment Metrics, Course EnrollmentMetrics, and GetDomainEnrollmentMetrics. ## Request **Method:** GET **Rights:** ReadDomain@domainid or the authenticated user has an Administrator or Teacher persona in domainid or the authenticated user's domain is domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainenrollmentmetricsparameters` | | `domainid` | id | Yes | Domain ID | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domainenrollmentmetricsparameters": { "performance": { "score": { "red": "number", "yellow": "number" }, "direction": { "count": "int", "red": "int", "yellow": "int" } }, "pace": { "late": { "red": "number", "yellow": "number" }, "activity": { "red": "number", "yellow": "number", "range": "bool" } }, "responsiveness": { "red": "int", "yellow": "int" }, "completion": { "red": "number", "yellow": "number" }, "rollup": { "redweight": "number", "yellowweight": "number", "red": "number", "yellow": "number" } } } } ``` ### domainenrollmentmetricsparameters #### performance ##### score | Attribute | Type | Description | |-----------|------|-------------| | `red` | number | The fraction above the course passing score for the red threshold. The default is 0. For example if passing score is 0.7 set red="0.1" to make the threshold 0.73. | | `yellow` | number | The fraction above the course passing score for the yellow threshold. This is larger than red. The default is 0.25. For example if passing score is 0.7 set yellow="0.3" to make the threshold 0.79. | ##### direction | Attribute | Type | Description | |-----------|------|-------------| | `count` | int | The last count number of gradable items to use. Default is 5. | | `red` | int | The minimum number of items below passing. The default is 2. | | `yellow` | int | The minimum number of items below passing. The default is 1. | #### pace ##### late | Attribute | Type | Description | |-----------|------|-------------| | `red` | number | The fraction of items that are past the due date. The default is 0.3. | | `yellow` | number | The fraction of items that are past the due date. The default is 0.15. | ##### activity | Attribute | Type | Description | |-----------|------|-------------| | `red` | number | The number of days without any student activity in this enrollment. The default is 15. | | `yellow` | number | The number of days without any student activity in this enrollment. The default is 8. | | `range` | bool | Set to true to apply activity metrics to range sections. The default is false. Normally range sections have other indications that the student needs help, including late and performance. | #### responsiveness | Attribute | Type | Description | |-----------|------|-------------| | `red` | int | The number of days that the oldest assignment has been in the queue to be graded. The default is 5. | | `yellow` | int | The number of days that the oldest assignment has been in the queue to be graded. The default is 3. | #### completion | Attribute | Type | Description | |-----------|------|-------------| | `red` | number | The fraction of student enrollments with a passing grade. The default is 0.8. | | `yellow` | number | The fraction of student enrollments with a passing grade. The default is 0.9. | #### rollup | Attribute | Type | Description | |-----------|------|-------------| | `redweight` | number | The weight for a rollup for a red signal. The default is 4. | | `yellowweight` | number | The weight for a rollup for a yellow signal. The default is 1. | | `red` | number | The weighted average for signals for a rollup. The default is 0.3. | | `yellow` | number | The weighted average for signals for a rollup. The default is 0.1. | ## Example This example assumes the domain with ID 4879 exists. **URL:** `?cmd=getdomainenrollmentmetricsparameters&domainid=4879` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domainenrollmentmetricsparameters": { "performance": { "score": { "red": "0", "yellow": "0.25" }, "direction": { "count": "5", "red": "2", "yellow": "1" } }, "pace": { "late": { "red": "0.3", "yellow": "0.15" }, "activity": { "red": "15", "yellow": "8", "range": "false" } }, "responsiveness": { "red": "5", "yellow": "3" }, "completion": { "red": "0.8", "yellow": "0.9" }, "rollup": { "redweight": "4", "yellowweight": "1", "red": "0.3", "yellow": "0.1" } } } } ``` ## See Also - [GetDomainEnrollmentMetrics](https://api.agilixbuzz.com/docs/entry/Command/GetDomainEnrollmentMetrics.md) --- # GetDomainParentList This command gets the list of parent domains for a domain. **Important:** The currently signed-on user must have Read rights on a parent domain in order for it to appear in this list. Therefore, the list may be empty or incomplete. ## Request **Method:** GET **Rights:** ReadDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainparentlist` | | `domainid` | id | Yes | ID of the domain to get parents for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domains": { "domain": [ { "domainid": "id", "name": "string", "userspace": "string", "reference": "string", "flags": "EntityFlags", "creationdate": "datetime" } ] } } } ``` ### domains #### domain | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | Parent domain ID. | | `name` | string | Parent domain name. | | `userspace` | string | Parent domain userspace (login prefix). | | `reference` | string | Parent domain reference field value. | | `flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | *(optional)* Bitwise OR of EntityFlags on the domain. | | `creationdate` | datetime | Parent domain creation date. | ## Example This example assumes the domain with ID 4879 exists and it is a child of domain ID 4. **URL:** `?cmd=getdomainparentlist&domainid=4879` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domains": { "domain": [ { "domainid": "4", "name": "Virtual District", "userspace": "vdistrict", "reference": "123123123123", "flags": "0", "creationdate": "2007-06-07T16:37:50.237Z" } ] } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) --- # GetDomainSettings Retrieves the settings for an application, merging multiple settings file in the domain hierarchy. **Note:** Settings resources under public/shadow/app/ require no authentication; this is primarily so that unauthenticated users can get domain branding/app settings to render login pages that are customized for a particular application or domain. Therefore, do NOT store sensitive information in public/shadow/app/ domain-settings resource files. Any other path requires *ReadDomain* on the specified domain. The caller may provide settings in the body of a POST request. This allows the caller to provide default settings that are used when no other settings in the domain heirarchy override their values. ## Request **Method:** GET or POST **Rights:** None for path values under public/shadow/app/ (readable without authentication for login-page branding); ReadDomain@domainid for all other paths. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainsettings` | | `domainid` | id | Yes | The ID of the domain for which to get settings. | | `path` | string | Yes | The path of the settings file to load. | | `includesource` | boolean | No | Whether or not to include source-domainid attributes in the response to indicate the ID of the child-most domain where that settings node was set. Default is false. | **Request body (JSON):** ```json { "settings": {} } ``` *GetDomainSettings* looks for the resource identified by *path* in the specified *domainid* and in each ancestor domain. If the resource exists in multiple domains, *GetDomainSettings* merges the settings, with child-most domain settings overwriting ancestor domain settings according to the merge rules described below. All Agilix-created products use settings paths that start with *Agilix*; for example, *AgilixBuzzSettings.xml*. To avoid collisions with any current or future settings files, do not prefix your paths with *Agilix*. We suggest you create your own unique prefix. If *GetDomainSettings* does not find *path*, it returns an empty *settings* element in the response. The settings resource file must be an XML file with a top-level element named *settings*. As with all commands, the response can be either JSON or XML. To ensure you can easily parse JSON responses, follow these rules in your settings XML files: - Store settings as attributes, not as element values. - Use number strings and the strings *true* and *false* in XML to get number values and boolean values, respectively, in JSON objects. ## Merging Setting Attributes Elements are matched by element name and path within the structure of the settings. When a matching element is found, the attributes for the matching elements are merged together. When attributes are merged the child domain attributes take precedence over the parent domain attributes. The following example shows the result of merging domain setting attributes: ### Parent <settings backgroundColor="green"> <features allowChangePassword="false" requireLogin="false" /> </settings> ### Child <settings backgroundColor="red" style="mystyle.css" /> <features allowMobileAccess="true" requireLogin="true" /> </settings> ### Result <settings domainName="My domain" backgroundColor="red" style="mystyle.css" /> <features allowChangePassword="false" allowMobileAccess="true" requireLogin="true" /> </settings> ## Settings Merge Control Attributes ### remove-item In order to remove a parent setting in a child domain, specify an attribute named *remove-item* with a value of *true* on the element that you want to remove. If you use *remove-item* with other attributes, the remove instruction will remove any matching item from ancestor domains and replace it with the item where the *remove-item* is (minus the *remove-item*, of course). This usage of *remove-item* will cause an item to replace the corresponding ancestor item if there was one. If there was no matching ancestor item, the *remove-item* attribute will be ignored. *remove-item* may be used on lists or elements of lists, but will have no effect if placed on elements inside a list item. ### lock-item In order to lock a parent setting so that child domains cannot change it, specify an attribute named *lock-item* with a value of *true* on the element that you want to lock. Locking a list will prevent any modification of the list by descendant domains. Locking a list item will prevent a matching item (either by position or key) from changing anything about that item. *lock-item* may be used on lists or elements of lists, but will have no effect if placed on elements inside a list item. ## Source Tracking Attributes When the *includesource* parameter is set, the output will contain *source-domainid* attributes indicating the domain from which this node originated, allowing you to diagnose why a particular settings node exists and has the value it has. ## Replacing and Merging Lists of Settings If you have settings represented by a list of elements with the same name then create an outer element with the same name but ending with a *-list* suffix. Add a *key* attribute to specify the key attribute used for matching lists during merging. The *key* attribute causes a list with a similar key to be replaced by child domain settings. You must provide the *key* attribute on all lists in the domain settings heirarchy in order for the list to be replaced at all levels. If no *key* is specified then the list elements are merged together by replacing the parent domain settings with elements found in the same list position of the child domain settings. The following is an example of replacing a list of settings without a specified *key*. See the example given in the *Response* section for a demonstration of replacing list elements. ### Parent Domain Settings <settings> <fruit-list > <fruit name="Apple" description="Great tasting Golden Delicious" /> <fruit name="Banana" description="Freshly imported bananas" /> </fruit-list> </settings> ### Child Domain Settings <settings> <fruit-list > <fruit name="Cherry" description="Sweet cherries" /> </fruit-list> </settings> ### Result <settings> <fruit-list > <fruit name="Cherry" description="Sweet cherries" /> <fruit name="Banana" description="Freshly imported bananas" /> </fruit-list> </settings> ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "settings": { "domainname": "string", "domainid": "string" } } } ``` ### settings This node contains the merged XML (or converted JSON) from the retrieved settings files in whatever form those files define. | Attribute | Type | Description | |-----------|------|-------------| | `domainname` | string | The name of the domain referenced by *domainid*. | | `domainid` | string | The ID of the domain. | ## Example This example demonstrates the use of attribute and list merging. Note that you must specify the key at every domain level otherwise the list items will be merged by list position rather than by the specified key value. ### Parent Domain Settings <settings> <features allowChangePassword="false" /> <fruit-list key="name" > <fruit name="Apple" description="Great tasting Golden Delicious" /> <fruit name="Banana" description="Freshly imported bananas" /> <fruit name="Cherry" description="Sweet cherries" /> <fruit name="Pineapple" description="Sweet ripe pineapple, always available" lock-item="true" /> </fruit-list> <color-list key="name" lock-item="true" > <color name="Green" description="We like photosynthesis" /> <color name="Blue" description="Color of the sky and deep clean water" /> <color name="Red" description="Tasty apple color" /> </color-list> <car-list key="name" > <car name="Ford" description="Built in America" /> <car name="Toyota" description="From Japan" /> <car name="Hyundai" description="From Korea" /> </car-list> </settings> ### Child Domain Settings <settings> <features allowChangePassword="true" /> <fruit-list key="name" > <fruit name="Apple" remove-item="true" description="My apples are better than yours." /> <fruit name="Banana" description="Limited quantities this week" /> <fruit name="Cherry" remove-item="true" /> <fruit name="Dates" description="Newly added to the menu" /> <fruit name="Pineapple" description="I don't like pineapple!" /> </fruit-list> <color-list key="name" > <color name="Green" description="Plants are cool" /> <color name="Purple" description="Lovely mix of red and blue" /> </color-list> <car-list key="name" remove-item="true" > <car name="Tesla" description="Eco friendly and fast!" /> <car name="Ferrari" description="Magnum P.I." /> <car name="Porsche" description="Still pretty cool" /> </car-list> </settings> **URL:** `?cmd=getdomainsettings&domainid=//myschool&path=MyAppSettings.xml` **Response** (code: `OK`): ```json { "response": { "code": "OK", "settings": { "domainName": "My school", "features": { "allowChangePassword": "true" }, "fruit-list": { "key": "name", "fruit": [ { "name": "Pineapple", "description": "Sweet ripe pineapple, always available", "lock-item": true }, { "name": "Apple", "description": "My apples are better than yours" }, { "name": "Banana", "description": "Limited quantities this week" }, { "name": "Dates", "description": "Newly added to the menu" } ] }, "color-list": { "key": "name", "lock-item": true, "color": [ { "name": "Green", "description": "We like photosynthesis" }, { "name": "Blue", "description": "Color of the sky and deep clean water" }, { "name": "Red", "description": "Tasty apple color" } ] }, "car-list": { "key": "name", "car": [ { "name": "Tesla", "description": "Eco friendly and fast!" }, { "name": "Ferrari", "description": "Magnum P.I." }, { "name": "Porsche", "description": "Still pretty cool" } ] } } } } ``` --- # GetDomainStats This command gets statistics for a domain. ## Request **Method:** GET **Rights:** ReadCourse@domainid or ReadDomain@domainid when options is courses. ReadDomain@domainid when options is anything else. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getdomainstats` | | `domainid` | id | Yes | ID of the domain to get statistics for. | | `options` | string | Yes | A vertical-bar (\|) separated list of one or more of these options: - **users** - Returns the number of users in the domain. - **courses** - Returns the number of courses in the domain. - **activecourses** - Returns the number of active courses in the domain. A course counts as active if it is not deleted and not deactiveated. - **enrollments** - Returns the number of student enrollments in the domain. - **activeenrollments** - Returns the number of active student enrollments in the domain. - **activestudents** - Returns the number of users in the domain actively enrolled as a student. | | `recurse` | boolean | No | Set to *true* to include all sub-domains in stats. The default is *false*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "stats": { "stat": [ { "name": "string", "value": "int" } ] } } } ``` ### stats #### stat | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | The name of the statistic. | | `value` | int | The value of the statistic. | ## Example This example gets statistics for the domain with ID 4879. **URL:** `?cmd=getdomainstats&domainid=4879&options=users|courses|enrollments|activeenrollments|activestudents` **Response** (code: `OK`): ```json { "response": { "code": "OK", "stats": { "stat": [ { "name": "users", "value": 51 }, { "name": "courses", "value": 8 }, { "name": "enrollments", "value": 307 }, { "name": "activeenrollments", "value": 144 }, { "name": "activestudents", "value": 48 } ] } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) --- # GetDueSoonList This command gets list of items that will soon become due for a student. It optionally returns items that are past due or that have already been completed by the student. For enrollments in continuous courses, *GetDueSoonList* does not list non-gradable items unless Buzz has the domain configuration to show them. ## Request **Method:** GET **Rights:** ReadUser@userid or userid is current signed-on user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getduesoonlist` | | `userid` | id | No | ID of the user for which to get due soon list. Caller must supply either the userid or enrollmentid parameter. | | `enrollmentid` | id | No | List of 1 or more enrollment IDs for which to get due soon list. | | `showcompleted` | boolean | No | When true, returns items that are due soon even if already completed. The default is false. | | `showpastdue` | id | No | When true, returns items that are due soon even if past due. The default is true. If an item may no longer be submitted (for example, the item's due date and due date grace period have passed), then *GetDueSoonList* does not return the item. | | `days` | int | No | Filters the list of items by due date. The due date must fall between now and the number of days in the future. The default is 7. | | `utcoffset` | int | Yes | The current time difference between GMT and local time, in minutes. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "enrollmentid": "id", "itemid": "string", "title": "string", "type": "ItemType", "status": "GradeStatus", "scoredversion": "int", "scoreddate": "datetime", "responseversion": "int", "achieved": "double", "possible": "double", "gradeview": "GradeView", "letter": "string", "passing": "boolean", "passingscore": "double", "rawachieved": "double", "rawpossible": "double", "attempts": "int", "seconds": "int", "submittedversion": "int", "submitteddate": "datetime", "duedate": "datetime", "universalduedate": "datetime", "pacedate": "datetime", "entity": { "id": "id", "title": "string" }, "thumbnail": { "entityid": "id", "$value": "string" } } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | ID of the enrollment to which the item relates. | | `itemid` | string | ID of the item. | | `title` | string | Title of the item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | An ItemType value that represents the type of this item. | | `status` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | *(optional)* The bitwise OR of GradeStatus flags for this item grade, including whether the student has completed the item, been excused from it, whether the score has been released to the student, etc. | | `scoredversion` | int | *(optional)* Version of the last scored submission. | | `scoreddate` | datetime | *(optional)* The date the item was last scored. | | `responseversion` | int | *(optional)* Version of the last teacher response. | | `achieved` | double | *(optional)* The number of points achieved for this item adjusted for curving rules. | | `possible` | double | *(optional)* The number of points possible for this item. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | A GradeView value that controls how to display scores for this item's category (as defined in Course Data). | | `letter` | string | *(optional)* The letter grade achieved for the item. | | `passing` | boolean | *(optional)* *true* if the score is greater than or equal to the passing score for the item and enrollment. Otherwise omitted. | | `passingscore` | double | *(optional)* The passing score threshold for this item and enrollment. | | `rawachieved` | double | *(optional)* The number of actual points achieved for this item without any curving rules applied. This attribute is included only if it differs from achieved. | | `rawpossible` | double | *(optional)* The number of actual points possible for this item without any curving rules applied. This attribute is included only if it differs from possible. | | `attempts` | int | *(optional)* The number of attempts made on this item. | | `seconds` | int | *(optional)* The number of seconds spent in this item online material. | | `submittedversion` | int | *(optional)* Version of the last submission. | | `submitteddate` | datetime | *(optional)* The date of the last submission. | | `duedate` | datetime | *(optional)* The date the item is due. If the due date does not have a time element (is due at the end of the day in the timezone of the student), then *GetDueSoonList* shifts this value by the input *utcoffset* . Also see *universalduedate*. | | `universalduedate` | datetime | *(optional)* The date the item is due (in universal time; i.e., not shifted by *utcoffset*. Also see *duedate*). | | `pacedate` | datetime | *(optional)* The estimated date by when this item should be completed to finish the course on pace. When the seconds is zero, the time is shifted to the time zone of the student just like data.duedate | ##### entity | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of the entity to which the enrollment is associated. | | `title` | string | Title of the entity. | ##### thumbnail *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | *(optional)* The ID of the entity that owns the thumbnail resource when it is not owned by the same entity that owns the item. | ## Example This example retrieves due soon list for the user with ID 15002. **URL:** `?cmd=getduesoonlist&userid=15002&showcompleted=true&utcoffset=-240` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "enrollmentid": "15933", "itemid": "A1", "title": "Assignment", "status": "261", "responseversion": "1", "scoredversion": "1", "scoreddate": "2012-05-23T07:42:00Z", "achieved": "80", "possible": "100", "letter": "B", "submittedversion": "1", "submitteddate": "2012-05-23T07:14:00Z", "duedate": "2012-05-23T11:00:00Z", "entity": { "id": "15900", "title": "Section Title" } } ] } } } ``` ## See Also - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetEffectivePasswordPolicy Gets the password policy in force for a user or for a domain, optionally with inherited policies and persona restrictions already resolved. Which of those is returned depends on the parameters supplied: - Neither userid nor domainid: the policy in force for the currently-authenticated user. - userid: the policy in force for that user. A user ID takes precedence over a domain ID, which is then ignored. - domainid only: the policy in force for that domain, which is what applies to a member of the domain who holds no persona. Adding persona also applies the restrictions the domain places on that persona. The policy in force for a *user* is the base policy of the domain their account lives in, merged with the restrictions of every persona they currently hold, each taken from the domain where they hold it. This is the same resolution the login and password-change paths perform, so it is what a new password will actually be held to. A base policy is the one stored on the domain, or, when the domain stores none of its own, the one inherited from the nearest ancestor domain that does; the domainid attribute of the response names the domain it came from. Restrictions are merged by keeping the stricter of each value, so merging can only tighten a policy: a result that includes persona restrictions is never weaker than the base policy alone. A persona's restrictions are gathered from the named domain *and from every one of its ancestors*, so the result can be stricter than what that domain itself stores for the persona. This command resolves a policy for reading, not for editing. To edit one, read the single policy stored on one domain with GetRawPasswordPolicy, which inherits and merges nothing, and write it back with SetPasswordPolicy. ## Request **Method:** GET **Rights:** ControlUser when a user ID other than the caller's own is specified (the caller's own user ID requires no rights). When neither a user ID nor a domain ID is specified, none: the currently-authenticated user's own effective policy is returned. When a domain ID is specified, a caller may always read the policies that apply to them, which are these domains: The domain their own user account lives in. Every domain in which they currently hold a persona. A persona names the domain of the course, enrollment, user or domain right it came from, so a caller may hold any number of them, in any number of domains, including domains outside their own domain's subtree - and each contributes its restrictions to the policy their next password must satisfy. The direct parent of any of the above, which is the domain those inherit from when they store no policy of their own. One level only: a grandparent is not readable on its own, though its restrictions are still visible, merged, in the reads above. Beyond those, a domain requires any privilege on it (granted on it directly or inherited from an ancestor domain), or a right granted on that domain or on one of its immediate child domains. The persona parameter additionally requires one of the following: the ReadDomain privilege on the specified domain or on an ancestor of it; a right including ReadDomain granted on one of its immediate child domains; or that the caller currently hold the named persona on the specified domain or on one of its immediate child domains - that is, on the domain being read, or on a domain that inherits that persona's restrictions from it. A caller with none of these is given an access denied error. Throughout, the caller is the user the session is acting as: in a session established with Proxy, the caller's own domain and personas are those of the user being acted as, not those of the account which proxied. An administrator reading on behalf of a user they control gets the policy in force for that user - the restrictions of every persona that user holds already merged in, and, with includecontext, attributed to the domain and persona each came from - from a userid read. A domain-level read is a separate question, judged against the administrator's own rights and personas by the rules above: holding ControlUser over a user means holding a right at or above that user's domain, which reaches that domain, every persona's policy there, and its direct parent - but not a domain elsewhere in which that user happens to hold a persona. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `geteffectivepasswordpolicy` | | `userid` | id | No | The ID of the user whose effective password policy is desired. If specified, it takes precedence over any domain ID and requires the ControlUser right on that user unless it is the currently-authenticated user's own ID. If omitted and no domain ID is specified, defaults to the currently-authenticated user. | | `domainid` | id | No | The ID of the domain whose effective password policy is desired, returned instead of the currently-authenticated user's. Ignored when a user ID is specified, because that user's own domain is the one that applies to them. | | `persona` | string | No | A persona name (see the Persona enumeration) whose restrictions in the specified domain are to be merged in as well, giving the policy that applies to a member of that domain who holds that persona. It requires a domain ID, and it may not be combined with a user ID, because the policy a user ID resolves already carries the restrictions of the personas that user actually holds. This parameter is never ignored: naming a persona the caller may not read on that domain (see the rights section) is an access denied error, while combining it with a user ID, supplying it with no domain ID, and giving a value that does not name a persona are each a bad request. | | `bypasscache` | boolean | No | Whether or not to bypass the cache for this retrieval, resolving the policy from the stored data instead. This is rarely needed: a resolved policy is cached against the exact stored data it was resolved from, so editing a policy - on this domain or on any domain it inherits from - is reflected in the very next read, at any depth in the hierarchy. Reading back an edit to confirm it therefore does not require this parameter. | | `includecontext` | bool | No | Whether or not to include the context of where each restriction came from. Defaults to false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "passwordpolicy": { "domainid": "id", "hashalgorithmfornewhashes": "string", "maxage": "timespan", "maxagesource": "string", "loginattempthistoryretentiontime": "timespan", "loginattempthistoryretentiontimesource": "string", "lockoutaftertries": "int", "lockoutaftertriessource": "string", "lockoutduration": "timespan", "lockoutdurationsource": "string", "lockoutstaleaccountsafter": "timespan", "lockoutstaleaccountsaftersource": "string", "minimumlength": "int", "minimumlengthsource": "string", "minimumcharacterclasses": "int", "minimumcharacterclassessource": "string", "recycletime": "timespan", "recycletimesource": "string", "complexityenforcement": "PasswordPolicyEnforcement", "complexityenforcementsource": "string", "additionalcontextwords": "string", "additionalcontextwordssource": "string", "minimumentropy": "int", "minimumentropysource": "string", "entropyenforcement": "PasswordPolicyEnforcement", "entropyenforcementsource": "string", "pwnenforcement": "PasswordPolicyEnforcement", "pwnenforcementsource": "string", "mfaenforcement": "PasswordPolicyEnforcement", "mfaenforcementsource": "string" } } } ``` ### passwordpolicy | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | The ID of the domain the password policy was taken from. If no password policy was found on the specified domain, this lets the caller know which ancestor domain this policy was found on. | | `hashalgorithmfornewhashes` | string | The hash algorithm that will be used for newly-set passwords. Currently always the system default. | | `maxage` | timespan | *(optional)* The maximum time a password can be used for accessing the system. After a password reaches this age, it can only be used to set a new password. The default behavior is not to expire passwords (forever). | | `maxagesource` | string | *(optional)* The source where this specified maxage value came from, if specified, usually a domain ID and persona. | | `loginattempthistoryretentiontime` | timespan | *(optional)* The length of time password login attempts are recorded (the longest of what is required by this, what is required by the lockout rules, or the system-wide minimum is what will be retained). The default is none, which will use the system-wide minimum. GetPasswordLoginAttemptHistory may be used to retrieve this history. | | `loginattempthistoryretentiontimesource` | string | *(optional)* The source where this specified login attempt history retention time value came from, if specified, usually a domain ID and persona. | | `lockoutaftertries` | int | *(optional)* The maximum number of times a user can enter the wrong password before their account is locked out, requiring an administrator to unlock it. The default behavior is not to lock out accounts. | | `lockoutaftertriessource` | string | *(optional)* The source where this specified lockout after tries value came from, if specified, usually a domain ID and persona. | | `lockoutduration` | timespan | *(optional)* The length of time an account remains locked out after a lockout occurs. The default is forever, but this only applies if a lockout count is set. An administrator must call ResetLockout | | `lockoutdurationsource` | string | *(optional)* The source where this specified lockout duration value came from, if specified, usually a domain ID and persona. | | `lockoutstaleaccountsafter` | timespan | *(optional)* A duration of time after the last login (or after account creation if no logins have occurred) after which the account will be locked out just as if too many bad passwords were entered, but even if account lockout is not configured. | | `lockoutstaleaccountsaftersource` | string | *(optional)* The source where this specified lockout stale accounts after value came from, if specified, usually a domain ID and persona. | | `minimumlength` | int | The minimum number of characters required for an acceptable password. Defaults to one character (1) when no policy specifies it. | | `minimumlengthsource` | string | *(optional)* The source where this specified minimum length value came from, if specified, usually a domain ID and persona. | | `minimumcharacterclasses` | int | The minimum number of character classes (a-z, A-Z, 0-9, other) required for an acceptable password. Defaults to no restriction (0) when no policy specifies it. | | `minimumcharacterclassessource` | string | *(optional)* The source where this specified minimum character classes value came from, if specified, usually a domain ID and persona. | | `recycletime` | timespan | *(optional)* The amount of time to store old passwords and prevent their reuse. The default behavior is not to block password reuse (zero time). | | `recycletimesource` | string | *(optional)* The source where this specified recycle time value came from, if specified, usually a domain ID and persona. | | `complexityenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | How to handle situations where the password does not meet the policy for the minimum length, minimum character classes, and recycle time conditions. Defaults to None when no policy specifies it. | | `complexityenforcementsource` | string | *(optional)* The source where this specified complexity enforcement value came from, if specified, usually a domain ID and persona. | | `additionalcontextwords` | string | *(optional)* A comma-separated list of strings associated with the domain that will lower the entropy score when they are used as any part of the password. This should include parts of the names of the hostname of the website as well as parts of the name of the school(s) this policy applies to. | | `additionalcontextwordssource` | string | *(optional)* The source where this specified additional context words value came from, if specified, usually a domain ID and persona. | | `minimumentropy` | int | *(optional)* The minimum number of bits of estimated entropy for new passwords, adjusting for patterns commonly used by users to just meet old-style complexity requirements, such as capitalizing a single character, substituting the letter oh with zero, adding a 1 or ! at the end of a password, including the website name, using family names, using common words, etc. This is a "volatile" property, as the implementation may change at any time, causing password that passed before the implementation change to begin failing after the change, without any change to the policy itself. | | `minimumentropysource` | string | *(optional)* The source where this specified minimum entropy value came from, if specified, usually a domain ID and persona. | | `entropyenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* How to handle situations where the password does not meet the specified minimum entropy. | | `entropyenforcementsource` | string | *(optional)* The source where this specified entropy enforcement value came from, if specified, usually a domain ID and persona. | | `pwnenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* Whether and how to enforce passwords found in publicly-available data breaches. | | `pwnenforcementsource` | string | *(optional)* The source where this specified pwn enforcement value came from, if specified, usually a domain ID and persona. | | `mfaenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* Whether and how to enforce one-time (TOTP) token requirements in addition to the password for accounts subject to this policy. If required but not yet established, the user will be required to setup MFA after logging in with their password but before doing anything else. | | `mfaenforcementsource` | string | *(optional)* The source where this specified MFA enforcement value came from, if specified, usually a domain ID and persona. | ## Example This example gets the password policy effective for the currently-authenticated in user. **URL:** `?cmd=geteffectivepasswordpolicy` **Response** (code: `OK`): ```json { "response": { "code": "OK", "passwordpolicy": { "minimumlength": "1", "minimumcharacterclasses": "1", "maxage": "PT30D", "complexityenforcement": "BlockOnUse" } } } ``` ## See Also - [PasswordPolicyEnforcement Enum](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) - [Persona Enum](https://api.agilixbuzz.com/docs/entry/Enum/Persona.md) - [GetRawPasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/GetRawPasswordPolicy.md) - [SetPasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/SetPasswordPolicy.md) - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [ForcePasswordChange](https://api.agilixbuzz.com/docs/entry/Command/ForcePasswordChange.md) - [GetPasswordLoginAttemptHistory](https://api.agilixbuzz.com/docs/entry/Command/GetPasswordLoginAttemptHistory.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # GetEffectiveRights This command gets the effective rights granted to the current user for the specified entity (domain, course, or section). It takes into account all rights granted through domain privileges as well as course and section enrollments. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `geteffectiverights` | | `entityid` | id | Yes | ID of the domain, course, or section to get the current user’s rights. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "Authentication": { "UserId": "id", "Issued": "datetime", "Authorization": { "EntityId": "id", "Privileges": "RightsFlags" } } } } ``` ### Authentication | Attribute | Type | Description | |-----------|------|-------------| | `UserId` | id | ID of the current user. | | `Issued` | datetime | The date and time the authorization was determined. | #### Authorization | Attribute | Type | Description | |-----------|------|-------------| | `EntityId` | id | ID of the domain, course, or section that the user has rights to. | | `Privileges` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags for the user in the specified entity. | ## Example This example lists the effective rights of the current user (9747) on the entity with ID 6065. **URL:** `?cmd=geteffectiverights&entityId=6065` **Response** (code: `OK`): ```json { "response": { "code": "OK", "Authentication": { "UserId": "9747", "Issued": "2010-05-10T22:58:00Z", "Authorization": { "EntityId": "6065", "Privileges": "-1" } } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) - [UpdateRights](https://api.agilixbuzz.com/docs/entry/Command/UpdateRights.md) --- # GetEffectiveSubscriptionList This command lists effective subscriptions for the current signed-in user, including those inherited from the user's domain, and excluding any whose enddate has passed or startdate is in the future. To list subscriptions explicitly assigned to a user, see GetSubscriptionList. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `geteffectivesubscriptionlist` | | `select` | string | No | Specify domainthumbnail to include domainthumbnail in the response. The default is to not include domainthumbnail. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "subscriptions": { "subscription": [ { "subscriberid": "id", "entityid": "id", "subscriptionflags": "SubscriptionFlags", "startdate": "datetime", "enddate": "datetime", "creationdate": "datetime", "modifieddate": "datetime", "version": "string", "entitytype": "C|D", "name": "string", "parentid": "id", "domainname": "id", "domainthumbnail": "id" } ] } } } ``` ### subscriptions #### subscription | Attribute | Type | Description | |-----------|------|-------------| | `subscriberid` | id | ID of the subscribing entity (user or domain). The value 0 means all domains. | | `entityid` | id | ID of the subscribed-to entity (course or domain). | | `subscriptionflags` | [SubscriptionFlags](https://api.agilixbuzz.com/docs/entry/Enum/SubscriptionFlags.md) | A bitwise-OR of the subscription's SubscriptionFlags. | | `startdate` | datetime | Date and time when the subscription begins. | | `enddate` | datetime | Date and time when the subscription ends. | | `creationdate` | datetime | Date and time when the subscription was created. | | `modifieddate` | datetime | Date and time when the subscription was last modified. | | `version` | string | Version of the subscription. | | `entitytype` | string | The type of entity entityid refers to. C is a course; D is a domain. | | `name` | string | When entitytype is D, the name of the domain. When entitytype is C, the title of the course. | | `parentid` | id | ID of the domain that owns this domain or course. | | `domainname` | id | The name of the related domain. When entitytype is D, the name of the domain. When entitytype is C, the name of the domain that owns the course. | | `domainthumbnail` | id | *(optional)* The URL to the thumbnail image of the domain named in domainname. See Domain Data for more information on the thumbnail. domainthumbnail is included only when you specify domainthumbnail for select, and only if the domain contains a thumbnail URL. | ## Example This example lists effective subscriptions for the current signed-on user. **URL:** `?cmd=geteffectivesubscriptionlist` **Response** (code: `OK`): ```json { "response": { "code": "OK", "subscriptions": { "subscription": [ { "subscriberid": "47473", "entityid": "3838", "startdate": "2011-03-30T00:00:00Z", "enddate": "2099-03-30T00:00:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.443Z", "version": "1", "entitytype": "D", "name": "My District Content" }, { "subscriberid": "9911", "entityid": "38301", "startdate": "2011-03-30T00:00:00Z", "enddate": "2099-03-30T00:00:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.46Z", "version": "1", "entitytype": "C", "title": "Biology Master" } ] } } } ``` ## See Also - [GetEntitySubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEntitySubscriptionList.md) - [GetSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetSubscriptionList.md) - [UpdateSubscriptions](https://api.agilixbuzz.com/docs/entry/Command/UpdateSubscriptions.md) --- # GetEnrollment2 > **Deprecated** — use [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) instead. This command gets enrollment data for a particular enrollment. ## Request **Method:** GET **Rights:** ReadUser@the enrollment’s userid; ControlCourse|ReadCourse@entityid when the enrollment’s entityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollment2` | | `enrollmentid` | id | Yes | The enrollment ID to get information for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollment": {} } } ``` ### enrollment This element conforms to the Enrollment-User-Entity format ## Example This example assumes the enrollment with ID 303137 already exists. **URL:** `?cmd=getenrollment2&enrollmentid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollment": { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": 1, "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "15002", "firstname": "Kate", "lastname": "Gammon", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "userspace": "state", "username": "kate", "email": "kate.gammon@nowhere.com", "lastlogindate": "2010-10-11T19:34:46.74Z" }, "entity": { "id": "268973", "title": "Biology", "reference": "", "guid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "days": 365, "term": "", "baseid": "0" }, "domain": { "id": "9909", "name": "State University" } } } } ``` ## See Also - [Enrollment-User-Entity](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUserEntity.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # GetEnrollment3 This command gets enrollment data for a particular enrollment. ## Request **Method:** GET **Rights:** ReadUser@the enrollment’s userid; ControlCourse|ReadCourse@entityid when the enrollment’s entityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollment3` | | `enrollmentid` | id | Yes | ID of the enrollment to get. | | `select` | string | No | Comma-separated list of which data to return. By default, *GetEnrollment3* returns only the enrollment node. Possible values are: - *data* - Includes the enrollment's free-form structured data in the response. - *history(...)* - Includes the enrollment history in the response. See History Query for more details. - *course* - Includes course data in the response. - *course.data* - Includes the course's free-form structured data in the response. - *course.teachers* - Includes the list of teachers for the courses in the response. - *course.history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *user* - Includes user data in the response. - *user.data* - Includes the user's free-form structured data in the response. - *user.history(...)* - Includes the user history in the response. See History Query for more details. - *user.session* - Includes the user's most recently logged on and active session. - *metrics* - Includes the enrollment metrics in the response. - *metrics.history(...)* - Includes the enrollment metrics history in the response. See History Query for more details. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollment": { "data": {}, "history": [ { "parameters": "string", "enrollment": [ {} ] } ], "course": { "data": {}, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "history": [ { "parameters": "string", "course": [ {} ] } ] }, "domain": {}, "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "session": {} }, "enrollmentmetrics": { "history": [ { "parameters": "string", "enrollmentmetricshistory": [ {} ] } ] } } } } ``` ### enrollment This node conforms to the Enrollment format. #### data *(optional)* Optional free-form structured data. See Free-form Data for more details. #### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ##### enrollment *(optional)* This node conforms to the Enrollment format. These are the results of the history query. #### course *(optional)* This node conforms to the Course format. ##### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ##### teachers *(optional)* ###### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to course.history | ###### course *(optional)* This node conforms to the Course format. These are the results of the course.history query. #### domain *(optional)* This node conforms to the Domain format. #### user *(optional)* This node conforms to the User format. ##### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to user.history | ###### user *(optional)* This node conforms to the User format. These are the results of the user.history query. ##### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session. #### enrollmentmetrics *(optional)* This node conforms to the Enrollment Metrics format. This is the current enrollment metrics. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to metrics.history | ###### enrollmentmetricshistory *(optional)* This node conforms to the Enrollment Metrics format. These are the results of the metrics.history query. ## Example This example assumes the enrollment with ID 6050 already exists. **URL:** `?cmd=getenrollment2&enrollmentid=6050&select=course,user` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollment": { "id": "6050", "userid": "283", "courseid": "333", "domainid": "24", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "privileges": "552161378304", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2010-08-17T06:00:00Z", "creationby": "99", "modifieddate": "2010-08-17T06:00:00Z", "modifiedby": "99", "version": "1", "course": { "id": "333", "title": "Biology", "domainid": "24", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "schema": "2", "baseid": "0", "type": "Continuous", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "days": "300", "term": "", "protection": "0", "flags": "0", "creationdate": "2010-08-17T06:00:00Z", "creationby": "99", "modifieddate": "2010-08-17T06:00:00Z", "modifiedby": "99", "version": "1" }, "user": { "id": "283", "firstname": "Kate", "lastname": "Gammon", "domainid": "24", "reference": "", "guid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "username": "kate", "email": "", "flags": "0", "lastpasswordchangeddate": "2010-08-17T06:00:00Z", "firstlogindate": "1753-01-01T00:00:00Z", "lastlogindate": "1753-01-01T00:00:00Z", "creationdate": "2010-08-17T06:00:00Z", "creationby": "99", "modifieddate": "2010-08-17T06:00:00Z", "modifiedby": "99", "version": "1" } } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # GetEnrollmentActivity This command gets the activity detail for the specified user enrollment. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollmentactivity` | | `enrollmentid` | id | Yes | Enrollment ID of user for which to get activity. This parameter also accepts a list of enrollment IDs separated by the vertical bar (\|) character. | | `itemid` | string | No | Filters the list of activity records returned by the server to those that pertain to the indicated item. If this parameter is omitted, the command returns activity records for all items. | | `startdate` | datetime | No | Filters the list of activity records returned by the server to those with a date greater than or equal to the specified value. | | `enddate` | enddate | No | Filters the list of activity records returned by the server to those with a date less than the specified value. | | `limit` | int | No | Limits the number of records returned by the server. It returns the most recent activity records for the specified enrollment [and item] up the specified limit. If this parameter is omitted, the command returns all matching activity records. | | `last` | bool | No | Set to *true* to return only the latest activity. | | `mergeoverlap` | bool | No | Set to *true* to merge overlapping activity that results from the user opening more than one browser window. When multiple enrollment IDs are specified, this merges overlapping activity *across all enrollments* in the query. Each second of wall-clock time is attributed to only one activity, so per-enrollment durations may be lower than when querying each enrollment individually. To get per-enrollment durations that are consistent with single-enrollment queries, call this command separately for each enrollment ID. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollment": { "activity": [ { "enrollmentid": "id", "itemid": "string", "date": "datetime", "seconds": "int", "title": "string" } ] } } } ``` ### enrollment #### activity | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The ID of the enrollment the user spent time in. | | `itemid` | string | The ID of the item the user spent time in. | | `date` | datetime | The date the activity started. | | `seconds` | int | The number of seconds the user spent in the item. | | `title` | string | *(optional)* The title of the item. Omitted if the item does not exist in the current course manifest. | ## Example This example retrieves activity detail for the enrollment with ID 303137. **URL:** `?cmd=getenrollmentactivity&enrollmentid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollment": { "activity": [ { "itemid": "C1", "date": "2011-08-18T16:06:51.747Z", "seconds": 154 }, { "itemid": "E1", "date": "2011-10-17T21:17:42.743Z", "seconds": 20 } ] } } } ``` ## See Also - [PutItemActivity](https://api.agilixbuzz.com/docs/entry/Command/PutItemActivity.md) --- # GetEnrollmentGradebook > **Deprecated** — use [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/../Command/GetEnrollmentGradebook2.md) instead. This command gets the gradebook detail for the specified user enrollment in a section. You can specify a special itemid to obtain the final course grade or other grading-period grades. (See PutTeacherResponse for more information.) ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollmentgradebook` | | `enrollmentid` | id | Yes | Enrollment ID of user for which to get grades. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grades. | | `calculated` | boolean | No | When **true**, returns item titles and calculated score values and due dates as they appear in the end-user's gradebook. The response also includes additional item elements containing a snapshot of the current period and course grades. These items have special itemid values: **(!Course)** for the course grade, and **(!Period:n)** for period grades, where n is 1, 2, 3, etc. The response includes scores for all gradable items and none of the non-gradable items. The server ignores the itemid parameter. When **false**, returns raw (uncurved) score values for only item elements that have non-null score, attempts, or seconds. Titles are omitted. The default is **false**. | | `scorm` | boolean | No | Optional, when **true**, returns the detailed data about the student’s response represented as name-value pairs defined by SCORM. The default is **false**. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "itemid": "id", "status": "GradeStatus", "submittedversion": "int", "scoredversion": "int", "pointsachieved": "double", "pointspossible": "double", "score": "double", "grade": "string", "attempts": "int", "seconds": "int" } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | id | ID of the item. | | `status` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | The bitwise OR of GradeStatus flags for this submission. | | `submittedversion` | int | Version of the last submission. | | `scoredversion` | int | Version of the last scored submission. | | `pointsachieved` | double | *(optional)* The number of points achieved for this student for this item. | | `pointspossible` | double | *(optional)* The number of points possible for this student for this item. | | `score` | double | *(optional)* Score for this item (achieved/possible). | | `grade` | string | *(optional)* The letter grade for this student for this item. | | `attempts` | int | Number of student attempts for this item. | | `seconds` | int | Number of seconds student spent on this item. | ## Example This example retrieves gradebook detail for the enrollment with ID 6165. **URL:** `?cmd=getenrollmentgradebook&enrollmentid=6165` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "itemid": "ASSIGNMENT_DCVK", "status": "5", "submittedversion": 1, "scoredversion": 1, "score": 0.76, "attempts": 1, "seconds": 494 }, { "itemid": "DEFAULT", "status": "0", "submittedversion": 0, "scoredversion": 0, "attempts": 3, "seconds": 0 }, { "itemid": "FINALEXAM_DCVK", "status": "5", "submittedversion": 1, "scoredversion": 1, "score": 0.6666666666666666, "attempts": 4, "seconds": 19 } ] } } } ``` ## See Also - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetEnrollmentGradebook2 This command gets the gradebook detail, including rolled-up period, category, and course grades, for the specified user enrollment. If the enrollment's entity is a course whose type is Continuous and you also request individual items with itemid, this command also returns calculated due dates for the gradable course items by evenly distributing them between the enrollment's startdate and enddate. The calculated dates are not actual due dates; they exist only to help students stay on pace in Continuous courses. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollmentgradebook2` | | `enrollmentid` | id | Yes | Enrollment ID of user for which to get grades. | | `forcerequireditems` | boolean | No | Specify true to force the final rollup scores to be 0 if any required item (see PassingScoreRequired in GradeFlags) score is missing or below passing. Specify false to calculate rolled-up scores even if a required item score is either missing or below passing. The default is false. | | `gradingschemeid` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `gradingscheme` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grades. Specify '\*' to get all gradable-item grade data. Specify '\*\*' (that's two asterisks) to get gradable and non-gradable item grade data. Non-gradable items typically don't have scores, but they do have time spent and completion statuses. If omitted, only rolled up (period, category, course) grades are returned. | | `scorm` | boolean | No | When true, returns the student’s submitted SCORM data as name-value pairs beneath each item element. The default is false. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0 when computing rolled-up grades. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollment": { "grades": {} } } } ``` ### enrollment This node conforms to the Enrollment-User-Entity format. #### grades This node conforms to the Grades format. ## Example This example retrieves gradebook detail for the enrollment with ID 303137. **URL:** `?cmd=getenrollmentgradebook2&enrollmentid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollment": { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": 1, "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "15002", "firstname": "Kate", "lastname": "Gammon", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "userspace": "state", "username": "kate", "email": "kate.gammon@nowhere.com", "lastlogindate": "2010-10-11T19:34:46.74Z" }, "entity": { "id": "268973", "title": "Biology", "reference": "", "guid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "days": 365, "term": "", "baseid": "0" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 91.6282, "possible": 100, "letter": "A", "passingscore": 0.7, "complete": 0.9473684210526315, "seconds": 12945, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 594.875, "possible": 610, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 877, "possible": 1000, "letter": "B" } ] }, "final": { "status": 260, "scoreddate": "2010-08-19T19:29:42.41Z", "achieved": 54.8833, "possible": 60, "letter": "A" } } } } } ``` ## See Also - [Enrollment-User-Entity](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUserEntity.md) - [Grades](https://api.agilixbuzz.com/docs/entry/Schema/Grades.md) - [GetEntityGradebook3](https://api.agilixbuzz.com/docs/entry/Command/GetEntityGradebook3.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetEnrollmentGroupList This command lists groups that the specified enrollment is a member of. ## Request **Method:** GET **Rights:** enrollmentid belongs to current signed-on user or ReadUser@userid referred to by enrollmentid or ControlCourse|UpdateCourse|ReadGradebook@entityid referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollmentgrouplist` | | `enrollmentid` | id | Yes | ID of the enrollment to list groups for. | | `setid` | int | No | Optionally filters the list of groups to those that belong to the specified set. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "groups": { "group": [ {} ] } } } ``` ### groups #### group This element conforms to the Group format. ## Example This example lists the groups for the enrollment with ID 177932. **URL:** `?cmd=getenrollmentgrouplist&enrollmentid=177932` **Response** (code: `OK`): ```json { "response": { "code": "OK", "groups": { "group": [ { "id": "204235", "title": "Males", "reference": "CS101-BY", "guid": "db36868d-ff5d-4856-a38e-f1ed87953343", "ownerid": "136875", "domainid": "9909", "setid": "1", "creationdate": "2010-07-28T16:21:23.813Z" } ] } } } ``` ## See Also - [AddGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/AddGroupMembers.md) - [GetGroupEnrollmentList](https://api.agilixbuzz.com/docs/entry/Command/GetGroupEnrollmentList.md) - [RemoveGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/RemoveGroupMembers.md) --- # GetEnrollmentMetricsReport Returns report data for the enrollment metrics of a domain, teacher, or student. GetEnrollmentMetricsReport reports on active student enrollments. ## Request **Method:** GET **Rights:** ReadGradebook@entityid when entityid refers to a domain or course, ReadUser@entityid when entityid refers to a user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getenrollmentmetricsreport` | | `entityid` | id | Yes | Domain ID, course ID, or user ID. | | `report` | string | Yes | Specifies the data to reutrn. - **Student** - The list of students and their rolled up enrollment metrics. - **Enrollment** - The list of enrollments and their enrollment metrics. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, GetEnrollmentMetricsReport considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `nodata` | string | Yes | Localized text to write into the output if there are no rows of data to put in the results. | | `select` | string | Yes | The fields to include on the report. You may select the following for any report: - **user.firstname** - The first name of the student. - **user.lastname** - The last name of the student. - **user.username** - The username of the student. - **user.id** - The ID of the student. - **user.reference** - The reference of the student. You may select from the following for Student: - **coursecount** - The number of active enrollments for this student. - **latecount** - The number of late items. - **failedcount** - The number of failed items. - **paceyellows** - The number of yellow pace signals. - **pacereds** - The number of red pace signals. - **performanceyellows** - The number of yellow performance signals. - **performancereds** - The number of red performance signals. You may select from the following for Enrollment: - **enrollment.id** - The ID of the student's enrollment in the section or course or one of its derivatives. - **enrollment.startdate** - The start date of the student's enrollment formatted in YYYY-MM-DD and offset by *utcoffset*. - **enrollment.enddate** - The end date of the student's enrollment formatted in YYYY-MM-DD and offset by *utcoffset*. - **enrollment.reference** - The reference of the student's enrollment. - **course.title** - The title of the section or course the student is enrolled in. - **course.id** - The ID of the section or course the student is enrolled in. - **course.reference** - The reference of the section or course the student is enrolled in. - **score** - The student's score. - **achieved** - The total achieved points. - **possible** - The total possible points. - **finalletter** - The letter that was reported using (Course) as the item ID. - **failing** - True if the student is failing this course. - **seconds** - The number of seconds the student has spent in the course. - **completable** - The number of items in the course that can be completed. - **completed** - The number of items the student has completed. - **gradable** - The number of items in the course that are gradable. - **completedgradable** - The number of gradable items that the student has completed. - **graded** - The number of gradable items that have been graded. - **gradablecompletion** - The percent complete of gradable items (calculated by *completedgradable*/*gradable*). - **overallcompletion** - The percent complete of completable items (calculated by *completed*/*completable*). - **late** - The number of late items. - **failed** - The number of failed items. - **recentlyfailed** - The number of recent items that are failed. Recent is determined by the domain's enrollmentmetrics customization. - **pacelight** - The student's pace status signal. One of *Green*, *Yellow*, or *Red*. - **pacereason** - The student's pace status reason. - **performancelight** - The student's performance status signal. One of *Green*, *Yellow*, or *Red*. - **performancereason** - The student's performance status reason. - **lastduedatemissed** - The date and time of the most recent due date that was missed. This value is offset by *utcoffset*. - **calculateddate** - Date and time that the metrics were calculated. This value is offset by *utcoffset*. | | `filename` | string | No | The suggested filename for the report data download. | | `format` | string | Yes | The format of the extracted data. | | `spreadsheet` | boolean | No | Whether or not the generated CSV should be in spreadsheet format.Always use this for Excel, Google Sheets, or other spreadsheets, but not to import into other databases.The default is to assume the CSV will be used with a spreadsheet(true). | | `utcoffset` | int | No | The current time difference between GMT and local time, in minutes. | ## Response **Content-Type:** text/plain or text/csv **Content-Length:** data length ## See Also - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEnrollments.md) - [Enrollment Metrics](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentMetrics.md) --- # GetEntityEnrollmentList > **Deprecated** — use [ListEntityEnrollments](https://api.agilixbuzz.com/docs/entry/../Command/ListEntityEnrollments.md) instead. This command gets the list of users enrolled in the specified course. ## Request **Method:** GET **Rights:** ControlCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentityenrollmentlist` | | `entityid` | string | Yes | ID of the course for which to get the enrollment list. | | `flags` | string | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified flags are returned in the response. | | `allstatus` | string | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. | | `userid` | string | No | Optional user ID by which to filter the list. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": { "enrollmentid": "id", "userid": "id", "firstname": "string", "lastname": "string", "domainid": "id", "domainname": "string", "userspace": "string", "username": "string", "email": "string", "userreference": "string", "flags": "RightsFlags", "enrollmentstatus": "EnrollmentStatus", "enrollmentstartdate": "datetime", "enrollmentenddate": "datetime", "enrollmentreference": "string", "data": { "description": {} } } } } } ``` ### enrollments #### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | ID of this enrollment. | | `userid` | id | ID of the user for this enrollment. | | `firstname` | string | User's first, or given, name. | | `lastname` | string | User's last, or surname. | | `domainid` | id | ID of this user's domain. | | `domainname` | string | Name of this user's domain. | | `userspace` | string | Userspace (login prefix) for this user's domain. | | `username` | string | Username of this user. | | `email` | string | Email address for this user. | | `userreference` | string | Reference field value for this user. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | Bitwise-OR of this user's RightsFlags for this enrollment. | | `enrollmentstatus` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | EnrollmentStatus for this enrollment. | | `enrollmentstartdate` | datetime | Start date and time for this enrollment. | | `enrollmentenddate` | datetime | End date and time for this enrollment. | | `enrollmentreference` | string | Reference field value for this enrollment. | ##### data *(optional)* Optional free-form structured data. See Free Form Data for more details. ###### description Enrollment description ## Example This example assumes the entity with ID 6065 exists with these enrollments. **URL:** `?cmd=getentityenrollmentlist&entityid=6065` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "userid": "6062", "courseid": "6063", "firstname": "Sabrina", "lastname": "Smart", "reference": "ID112233", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "username": "sabrina", "email": "sabrina@myschool.edu", "flags": "2097153", "enrollmentid": "6068", "enrollmentstatus": 1, "enrollmentstartdate": "2008-04-21T18:30:00Z", "enrollmentenddate": "2008-05-21T18:30:00Z" } ] } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListUserEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListUserEnrollments.md) --- # GetEntityEnrollmentList2 > **Deprecated** — use [ListEntityEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEntityEnrollments.md) instead. This command gets the list of users enrolled in the specified entity. ## Request **Method:** GET **Rights:** ControlCourse|UpdateCourse|ReadGradebook@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentityenrollmentlist2` | | `entityid` | id | Yes | ID of the course for which to get the enrollment list. | | `flags` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified flags are returned in the response. | | `allstatus` | string | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. | | `userid` | id | No | Optional user ID by which to filter the list. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": {} } } } ``` ### enrollments #### enrollment This element conforms to the Enrollment-User format. ## Example This example assumes the entity with ID 268973 exists with these enrollments. **URL:** `?cmd=getentityenrollmentlist2&entityid=268973` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "320555", "userid": "46218", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "ee483486-7b54-4c0f-8ec6-4b243cc4d64b", "flags": "131073", "status": "1", "startdate": "2010-08-18T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46218", "firstname": "Johny", "lastname": "Cash", "reference": "", "guid": "c93ef043-b261-4f07-bc46-58c901904dd3", "userspace": "state", "username": "johny", "email": "johny@nowhere.com", "lastlogindate": "2010-07-29T20:34:36.58Z" }, "domain": { "id": "9909", "name": "State University" } }, { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "15002", "firstname": "Kate", "lastname": "Gammon", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "userspace": "state", "username": "kate", "email": "kate.gammon@nowhere.com", "lastlogindate": "2010-10-11T19:34:46.74Z" }, "domain": { "id": "9909", "name": "State University" } }, { "id": "303139", "userid": "46216", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "cda240d6-7ccf-448d-a797-3b943beff39d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46216", "firstname": "Willie", "lastname": "Nelson", "reference": "", "guid": "3bf7ddb9-ef17-469a-90c3-79eb49fd516e", "userspace": "state", "username": "willie", "email": "willie@nowhere.com", "lastlogindate": "2010-10-05T00:57:51.117Z" }, "domain": { "id": "9909", "name": "State University" } } ] } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [GetUserEnrollmentList2](https://api.agilixbuzz.com/docs/entry/Command/GetUserEnrollmentList2.md) --- # GetEntityGradebook2 This command gets grades for all students enrolled in the specified entity. The same due-date calculation occurs as that described in GetEnrollmentGradebook2. If there are more than 500 enrollments in the specified entity then to improve performance this call uses course data and item data from the entity's manifest for all enrollments, even if the enrollment has changes to those attributes. ## Request **Method:** GET **Rights:** ReadGradebook@sectionid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitygradebook2` | | `entityid` | id | Yes | Course ID, section ID, or group ID for which to get grades. | | `allstatus` | boolean | No | When true, returns grades for all enrollments, regardless of enrollment status. When false, returns grades for only Active or Suspended enrollments. The default is false. GetEntityGradebook2 considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active; use the *daysactivepastend* parameter to change this behavior. | | `forcerequireditems` | boolean | No | Specify true to force the final rollup scores to be 0 if any required item (see PassingScoreRequired in GradeFlags) score is missing or below passing. Specify false to calculate rolled-up scores even if a required item score is either missing or below passing. The default is false. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, GetEntityGradebook2 considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `gradingschemeid` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `gradingscheme` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grades. Specify '\*' to get all gradable-item grade data. Specify '\*\*' (that's two asterisks) to get gradable and non-gradable item grade data. Non-gradable items typically don't have scores, but they do have time spent and completion statuses. If omitted, only rolled up (period, category, course) grades are returned. | | `scorm` | boolean | No | When true, returns the student’s submitted SCORM data as name-value pairs beneath each item element. The default is false. | | `select` | string | No | Comma-separated list of which data to return. By default, only enrollment nodes are returned. Possible values are: - *enrollment.data[(...)]* - Includes the enrollment's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *user.data[(...)]* - Includes the user's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. | | `userid` | id | No | Optional user ID for which to get grades. If omitted, grades for all enrolled users are returned. | | `groupid` | string | No | Schema 4+: when entityid is a course, filters results to only enrollments that are members of the specified group, and uses the group's item overrides when computing grades. The group ID is the string group identifier from the course's group definitions. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0 when computing rolled-up grades. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "grades": {} } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment-User format. ##### grades This node conforms to the Grades format. ## Example This example retrieves the gradebook for the course with ID 268973. **URL:** `?cmd=getentitygradebook2&entityid=268973` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "320555", "userid": "46218", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "ee483486-7b54-4c0f-8ec6-4b243cc4d64b", "flags": "131073", "status": "1", "startdate": "2010-08-18T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46218", "firstname": "Johny", "lastname": "Cash", "reference": "", "guid": "c93ef043-b261-4f07-bc46-58c901904dd3", "userspace": "state", "username": "johny", "email": "", "lastlogindate": "2010-07-29T20:34:36.58Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 38, "possible": 40, "letter": "A", "passingscore": 0.7, "complete": 0.10526315789473684, "seconds": 0, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 190, "possible": 200, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 0, "possible": 0 } ] } } }, { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "15002", "firstname": "Kate", "lastname": "Gammon", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "userspace": "state", "username": "kate", "email": "kate@nowhere.com", "lastlogindate": "2010-10-11T19:34:46.74Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 91.6282, "possible": 100, "letter": "A", "passingscore": 0.7, "complete": 0.9473684210526315, "seconds": 12945, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 594.875, "possible": 610, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 877, "possible": 1000, "letter": "B" } ] }, "final": { "status": "260", "scoreddate": "2010-08-19T19:29:42.41Z", "achieved": 54.8833, "possible": 60, "letter": "A" } } }, { "id": "303139", "userid": "46216", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "cda240d6-7ccf-448d-a797-3b943beff39d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46216", "firstname": "Willie", "lastname": "Nelson", "reference": "", "guid": "3bf7ddb9-ef17-469a-90c3-79eb49fd516e", "userspace": "state", "username": "willie", "email": "willie@nowhere.com", "lastlogindate": "2010-10-05T00:57:51.117Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 184.3333, "possible": 200, "letter": "A", "passingscore": 0.7, "complete": 0.3333333333333333, "seconds": 10217.999999999998, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 265, "possible": 300, "letter": "B" }, { "id": "1", "name": "Quizzes", "achieved": 100, "possible": 100, "letter": "A" } ] } } }, { "id": "303138", "userid": "46220", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "061f444a-d4fe-4a11-a724-513eddd9c5ab", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46220", "firstname": "Hank", "lastname": "Williams", "reference": "", "guid": "ffba942e-2c57-4b0d-8310-77b96adaefe3", "userspace": "state", "username": "hank", "email": "", "lastlogindate": "2010-10-08T20:58:13.817Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 46.94, "possible": 100, "letter": "F", "passingscore": 0.7, "complete": 0.3157894736842105, "seconds": 2462.0000000000005, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 461.75, "possible": 500, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 66.6667, "possible": 400, "letter": "F" } ] } } } ] } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [Grades](https://api.agilixbuzz.com/docs/entry/Schema/Grades.md) - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) - [GetGradebookSummary](https://api.agilixbuzz.com/docs/entry/Command/GetGradebookSummary.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetEntityGradebook3 This command gets grades for students enrolled in the specified entity. The same due-date calculation occurs as that described in GetEnrollmentGradebook2. To perform well for most class sizes this call uses course data and item data from the entity's manifest for all enrollments, even if the enrollment has changes to those attributes. To use course data and item data from the enrollment's manifest, use GetEnrollmentGradebook2. ## Request **Method:** GET **Rights:** ReadGradebook@sectionid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitygradebook3` | | `entityid` | id | Yes | Course ID, section ID, or group ID for which to get grades. | | `allstatus` | boolean | No | When true, returns grades for all enrollments, regardless of enrollment status. When false, returns grades for only Active or Suspended enrollments. The default is false. | | `enrollmentids` | string | No | Vertical-bar-separated list of enrollment IDs for which to get grades. If omitted, all student enrollments in the specified entity are used. | | `forcerequireditems` | boolean | No | Specify true to force the final rollup scores to be 0 if any required item (see PassingScoreRequired in GradeFlags) score is missing or below passing. Specify false to calculate rolled-up scores even if a required item score is either missing or below passing. The default is false. | | `gradingschemeid` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `gradingscheme` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grades. Specify '\*' to get all gradable-item grade data. Specify '\*\*' (that's two asterisks) to get gradable and non-gradable item grade data. Non-gradable items typically don't have scores, but they do have time spent and completion statuses. If omitted, only rolled up (period, category, course) grades are returned. | | `scorm` | boolean | No | When true, returns the student’s submitted SCORM data as name-value pairs beneath each item element. The default is false. | | `select` | string | No | Comma-separated list of which data to return. By default, only enrollment nodes are returned. Possible values are: - *enrollment.data[(...)]* - Includes the enrollment's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *user.data[(...)]* - Includes the user's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. | | `userid` | id | No | Optional user ID for which to get grades. If omitted, grades for all enrolled users are returned. | | `groupid` | string | No | Schema 4+: when entityid is a course, filters results to only enrollments that are members of the specified group, and uses the group's item overrides when computing grades. The group ID is the string group identifier from the course's group definitions. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0 when computing rolled-up grades. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "grades": {} } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment-User format. ##### grades This node conforms to the Grades format. ## Example This example retrieves the gradebook for the course with ID 268973. **URL:** `?cmd=getentitygradebook3&entityid=268973` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "320555", "userid": "46218", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "ee483486-7b54-4c0f-8ec6-4b243cc4d64b", "flags": "131073", "status": "1", "startdate": "2010-08-18T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46218", "firstname": "Johny", "lastname": "Cash", "reference": "", "guid": "c93ef043-b261-4f07-bc46-58c901904dd3", "userspace": "state", "username": "johny", "email": "", "lastlogindate": "2010-07-29T20:34:36.58Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 38, "possible": 40, "letter": "A", "passingscore": 0.7, "complete": 0.10526315789473684, "seconds": 0, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 190, "possible": 200, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 0, "possible": 0 } ] } } }, { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "15002", "firstname": "Kate", "lastname": "Gammon", "reference": "", "guid": "dbdfc54b-ba97-42e9-9694-3ce72cbc1b75", "userspace": "state", "username": "kate", "email": "kate@nowhere.com", "lastlogindate": "2010-10-11T19:34:46.74Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 91.6282, "possible": 100, "letter": "A", "passingscore": 0.7, "complete": 0.9473684210526315, "seconds": 12945, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 594.875, "possible": 610, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 877, "possible": 1000, "letter": "B" } ] }, "final": { "status": "260", "scoreddate": "2010-08-19T19:29:42.41Z", "achieved": 54.8833, "possible": 60, "letter": "A" } } }, { "id": "303139", "userid": "46216", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "cda240d6-7ccf-448d-a797-3b943beff39d", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46216", "firstname": "Willie", "lastname": "Nelson", "reference": "", "guid": "3bf7ddb9-ef17-469a-90c3-79eb49fd516e", "userspace": "state", "username": "willie", "email": "willie@nowhere.com", "lastlogindate": "2010-10-05T00:57:51.117Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 184.3333, "possible": 200, "letter": "A", "passingscore": 0.7, "complete": 0.3333333333333333, "seconds": 10217.999999999998, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 265, "possible": 300, "letter": "B" }, { "id": "1", "name": "Quizzes", "achieved": 100, "possible": 100, "letter": "A" } ] } } }, { "id": "303138", "userid": "46220", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "061f444a-d4fe-4a11-a724-513eddd9c5ab", "flags": "131073", "status": "1", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "user": { "id": "46220", "firstname": "Hank", "lastname": "Williams", "reference": "", "guid": "ffba942e-2c57-4b0d-8310-77b96adaefe3", "userspace": "state", "username": "hank", "email": "", "lastlogindate": "2010-10-08T20:58:13.817Z" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 46.94, "possible": 100, "letter": "F", "passingscore": 0.7, "complete": 0.3157894736842105, "seconds": 2462.0000000000005, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 461.75, "possible": 500, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 66.6667, "possible": 400, "letter": "F" } ] } } } ] } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [Grades](https://api.agilixbuzz.com/docs/entry/Schema/Grades.md) - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) - [GetGradebookSummary](https://api.agilixbuzz.com/docs/entry/Command/GetGradebookSummary.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetEntityGradebookSummary This command gets grade summaries for students enrolled in the specified entity. The same due-date calculation occurs as that described in GetEnrollmentGradebook2. To perform well for most class sizes this call uses course data and item data from the entity's manifest for all enrollments, even if the enrollment has changes to those attributes. ## Request **Method:** GET **Rights:** ReadGradebook@sectionid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitygradebooksummary` | | `entityid` | id | Yes | ID of the course, section, or group for which to get grade summaries. | | `allstatus` | boolean | No | When true, uses all enrollments to calculate grade summaries, regardless of enrollment status. When false, uses only Active or Suspended enrollments. The default is false. | | `enrollmentids` | string | No | Vertical-bar-separated list of enrollment IDs to use when calculating grade summaries. If omitted, all student enrollments in the specified entity are used. | | `forcerequireditems` | boolean | No | Specify true to force the final rollup scores to be 0 if any required item (see PassingScoreRequired in GradeFlags) score is missing or below passing. Specify false to calculate rolled-up scores even if a required item score is either missing or below passing. The default is false. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, GetEntityGradebookSummary considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `gradingschemeid` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `gradingscheme` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grade summaries. Specify '\*' to get all gradable-item grade summaries. Specify '\*\*' (that's two asterisks) to get gradable and non-gradable item grade summaries. Non-gradable items typically don't have scores, but they do have time spent and completion statuses. If omitted, only rolled up (period, category, course) grade summaries are returned. | | `userid` | id | No | Optional user ID for which to get grades. If omitted, grades for all enrolled users are returned. | | `groupid` | string | No | Schema 4+: when entityid is a course, filters results to only enrollments that are members of the specified group, and uses the group's item overrides when computing grade summaries. The group ID is the string group identifier from the course's group definitions. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0 when computing rolled-up grades. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "summary": { "enrollments": "int", "items": { "item": [ { "itemid": "string", "achieved": "double", "possible": "double", "rawachieved": "double", "rawpossible": "double", "score": "double", "scored": "int", "graded": "int", "completed": "int", "unsubmitted": "int", "failing": "int", "seconds": "int", "hasseconds": "int", "minutes": "int", "hasminutes": "int" } ] }, "categories": { "category": [ { "id": "string", "achieved": "double", "possible": "double", "seconds": "int", "hasseconds": "int", "minutes": "int", "hasminutes": "int", "scored": "int" } ] }, "periods": { "period": [ { "id": "string", "achieved": "double", "possible": "double", "seconds": "int", "hasseconds": "int", "minutes": "int", "hasminutes": "int", "categories": { "category": [ {} ] } } ] } } } } ``` ### summary | Attribute | Type | Description | |-----------|------|-------------| | `enrollments` | int | The number of enrollments considered when summarizing grade data. | #### items ##### item | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | string | The item ID. | | `achieved` | double | The sum of the achieved for all grades on this item. | | `possible` | double | The sum of the possible for all grades on this item. | | `rawachieved` | double | The sum of the rawachieved for all grades on this item. | | `rawpossible` | double | The sum of the rawpossible for all grades on this item. | | `score` | double | The sum of the score (achieved/possible) for all grades on this item. | | `scored` | int | The number of grades on this item that have a score. | | `graded` | int | The number of enrollments that have a grade for this item. | | `completed` | int | The number of grades on this item that are marked completed. | | `unsubmitted` | int | The number of enrollments that have not made a submission. | | `failing` | int | The number of grades on this item that have a failing score. | | `seconds` | int | The sum of the seconds for all grades on this item. | | `hasseconds` | int | The number of grades that have more than 0 seconds. | | `minutes` | int | The sum of the minutes for all grades on this item. Each grade's seconds is rounded to the nearest minute. | | `hasminutes` | int | The number of grades that have more than 0 minutes. | #### categories ##### category | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The category ID. | | `achieved` | double | The sum of the achieved for all grades in this category. | | `possible` | double | The sum of the possible for all grades in this category. | | `seconds` | int | The sum of the seconds for all grades in this category. | | `hasseconds` | int | The number of enrollments that have more than 0 seconds for this category. | | `minutes` | int | The sum of the minutes for all grades in this category. Each grade's seconds is rounded to the nearest minute. | | `hasminutes` | int | The number of enrollments that have more than 0 minutes for this category. | | `scored` | int | The number of enrollments that have a score for this category. | #### periods ##### period | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The period ID. | | `achieved` | double | The sum of the achieved for all grades in this period. | | `possible` | double | The sum of the possible for all grades in this period. | | `seconds` | int | The sum of the seconds for all grades in this period. | | `hasseconds` | int | The number of enrollments that have more than 0 seconds for this period. | | `minutes` | int | The sum of the minutes for all grades in this period. Each grade's seconds is rounded to the nearest minute. | | `hasminutes` | int | The number of enrollments that have more than 0 minutes for this period. | ###### categories ####### category This node has the same attributes as the summary/categories/category node, but all attributes are limited to the period instead of for the whole category. ## Example This example retrieves the grade summary for all gradable items in the the course with ID 3379082. **URL:** `?cmd=getentitygradebooksummary&entityid=3379082&itemid=*` **Response** (code: `OK`): ```json { "response": { "code": "OK", "summary": { "enrollments": "4", "items": { "item": [ { "itemid": "L65VI", "achieved": "100", "possible": "100", "rawachieved": "1", "rawpossible": "1", "score": "1", "scored": "1", "unsubmitted": "3", "failing": "0", "seconds": "3", "minutes": "0", "graded": "1", "hasseconds": "1", "hasminutes": "0", "completed": "1" }, { "itemid": "HUGL4", "achieved": "0", "possible": "0", "rawachieved": "0", "rawpossible": "0", "score": "0", "scored": "0", "unsubmitted": "4", "failing": "0", "seconds": "0", "minutes": "0", "graded": "0", "hasseconds": "0", "hasminutes": "0", "completed": "0" }, { "itemid": "91LWJ", "achieved": "150", "possible": "200", "rawachieved": "150", "rawpossible": "200", "score": "1.5", "scored": "2", "unsubmitted": "2", "failing": "1", "seconds": "0", "minutes": "0", "graded": "2", "hasseconds": "0", "hasminutes": "0", "completed": "2" }, { "itemid": "7IVS1", "achieved": "80", "possible": "100", "rawachieved": "80", "rawpossible": "100", "score": "0.8", "scored": "1", "unsubmitted": "3", "failing": "0", "seconds": "0", "minutes": "0", "graded": "1", "hasseconds": "0", "hasminutes": "0", "completed": "1" }, { "itemid": "UE7FV", "achieved": "60", "possible": "100", "rawachieved": "60", "rawpossible": "100", "score": "0.6", "scored": "1", "unsubmitted": "3", "failing": "1", "seconds": "0", "minutes": "0", "graded": "1", "hasseconds": "0", "hasminutes": "0", "completed": "1" } ] }, "categories": { "category": [ { "id": "1", "achieved": "390", "possible": "500", "seconds": "3780", "minutes": "63", "scored": "3" }, { "id": "0", "achieved": "0", "possible": "0", "seconds": "0", "minutes": "0", "scored": "0" } ] } } } } ``` ## See Also - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) - [GetEntityGradebook3](https://api.agilixbuzz.com/docs/entry/Command/GetEntityGradebook3.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) --- # GetEntityResourceId This command gets the resource entity ID of the specified entity. This ID includes the resource version of the entity and allows clients to cache resources indefinitely because updates to the resource alter this ID. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentityresourceid` | | `entityid` | id | Yes | Entity ID for which to get the resource entity ID. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "resourceentityid": {} } } ``` ### resourceentityid The resource entity ID of for the entity. ## Example This example gets the resource entity ID for the course with ID 136875. **URL:** `?cmd=getentityresourceid&entityid=136875` **Response** (code: `OK`): ```json { "response": { "code": "OK", "resourceentityid": { "$value": "136875,2" } } } ``` ## See Also - [Course Data](https://api.agilixbuzz.com/docs/entry/Schema/CourseData.md) - [GetManifestData](https://api.agilixbuzz.com/docs/entry/Command/GetManifestData.md) --- # GetEntityRights This command lists users and the rights granted to those users for the specified entity (domain, course, section, enrollment or user.) ## Request **Method:** GET **Rights:** ReadDomain@domainentityid or ReadCourse@courseentityid or ReadEnrollment@enrollmententityid or ReadUser@userentityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentityrights` | | `entityid` | id | Yes | The ID of the entity to get rights for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "users": { "user": [ { "userid": "id", "userguid": "guid", "firstname": "string", "lastname": "string", "reference": "string", "domainid": "id", "domainname": "string", "userspace": "string", "username": "string", "email": "string", "creationdate": "datetime", "roleid": "id", "flags": "RightsFlags", "enrollmentid": "id", "enrollmentstatus": "EnrollmentStatus", "enrollmentstartdate": "datetime", "enrollmentenddate": "datetime", "data": {} } ] } } } ``` ### users #### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the user. | | `userguid` | guid | Globally unique ID for this user. | | `firstname` | string | User's first or given name. | | `lastname` | string | User's last or surname. | | `reference` | string | User's reference field value. | | `domainid` | id | ID of this user's domain. | | `domainname` | string | Name of this user's domain. | | `userspace` | string | Userspace (login prefix) of this user's domain. | | `username` | string | Username of this user. | | `email` | string | Email address for this user. | | `creationdate` | datetime | Date and time that this user was created. | | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | Bitwise-OR of this user's RightsFlags for the entity. | | `enrollmentid` | id | *(optional)* ID of this user's enrollment in the specified entity. | | `enrollmentstatus` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | *(optional)* The EnrollmentStatus for this user's enrollment in the specified entity. | | `enrollmentstartdate` | datetime | Start date and time for this enrollment. | | `enrollmentenddate` | datetime | End date and time for this enrollment. | ##### data *(optional)* Optional free-form structured data. See User Data and Free Form Data for more details. ## Example This example requests the actor (user) rights from the domain with ID 24. **URL:** `?cmd=getentityrights&entityid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "users": { "user": [ { "userid": "26", "firstname": "Ally", "lastname": "Smith", "reference": "223344", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "author", "email": "ally.smith@vschool.edu", "creationdate": "2007-06-07T17:17:16.567Z", "flags": "537853952" }, { "userid": "27", "firstname": "Tiger", "lastname": "Jones", "reference": "111222", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "teacher", "email": "teacher@vschool.edu", "creationdate": "2007-06-07T17:17:46.3Z", "flags": "2097664" }, { "userid": "1258", "firstname": "Arthur", "lastname": "Admin", "reference": "112233", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "admin", "email": "admin@vschool.edu", "creationdate": "2007-11-12T23:04:48.11Z", "flags": "-1" }, { "userid": "1265", "firstname": "Sammy", "lastname": "Secretary", "reference": "123123", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "sammy", "email": "sammy@vschool.edu", "creationdate": "2007-11-13T16:20:13.843Z", "flags": "34359738368" } ] } } } ``` ## See Also - [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [UpdateRights](https://api.agilixbuzz.com/docs/entry/Command/UpdateRights.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # GetEntitySubscriptionList This command lists subscriptions to the specified entity (course or domain). ## Request **Method:** GET **Rights:** ControlCourse@entity where entityid refers to a course; ControlDomain@entityid where entityid refers to a domain. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitysubscriptionlist` | | `entityid` | id | Yes | The ID of the course or domain to list subscriptions to. | | `subscriberid` | id | No | The ID of a user or domain to filter the list of subscriptions by. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "subscriptions": { "subscription": [ { "subscriberid": "id", "subscriberentitytype": "U|D", "subscriptionflags": "SubscriptionFlags", "startdate": "datetime", "enddate": "datetime", "creationdate": "datetime", "modifieddate": "datetime", "version": "string", "name": "string", "firstname": "string", "lastname": "string" } ] } } } ``` ### subscriptions #### subscription | Attribute | Type | Description | |-----------|------|-------------| | `subscriberid` | id | ID of the subscriber (user or domain). The value 0 means all domains. | | `subscriberentitytype` | string | The type of entity subscriberid refers to. U is a user; D is a domain. | | `subscriptionflags` | [SubscriptionFlags](https://api.agilixbuzz.com/docs/entry/Enum/SubscriptionFlags.md) | A bitwise-OR of the subscription's SubscriptionFlags. | | `startdate` | datetime | Date and time when the subscription begins. | | `enddate` | datetime | Date and time when the subscription ends. | | `creationdate` | datetime | Date and time when the subscription was created. | | `modifieddate` | datetime | Date and time when the subscription was last modified. | | `version` | string | Version of the subscription. | | `name` | string | *(optional)* When subscriberentitytype is D, the name of the domain. | | `firstname` | string | *(optional)* When subscriberentitytype is U, the user's firstname. | | `lastname` | string | *(optional)* When subscriberentitytype is U, the user's lastname. | ## Example This example lists subscriptions to the domain with ID 268973. **URL:** `?cmd=getentitysubscriptionlist&entityid=268973` **Response** (code: `OK`): ```json { "response": { "code": "OK", "subscriptions": { "subscription": [ { "subscriberid": "9911", "subscriberentitytype": "D", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.443Z", "version": "1", "title": "Canyon School" }, { "subscriberid": "9956", "subscriberentitytype": "U", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.443Z", "version": "1", "firstname": "Sally", "lastname": "Johnson" } ] } } } ``` ## See Also - [GetEffectiveSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEffectiveSubscriptionList.md) - [GetSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetSubscriptionList.md) - [UpdateSubscriptions](https://api.agilixbuzz.com/docs/entry/Command/UpdateSubscriptions.md) --- # GetEntityType This command gets the entity type (Course, Domain, Group, or Section) for a given entity ID. ## Request **Method:** GET **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitytype` | | `entityid` | id | Yes | ID of the course, domain, enrollment, group, objective set, role, section, or user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "entity": { "entitytype": "(Course|Domain|Enrollment|Group|ObjectiveSet|Role|Section|User)" } } } ``` ### entity | Attribute | Type | Description | |-----------|------|-------------| | `entitytype` | string | | ## Example This example assumes the course with ID 6065 already exists. **URL:** `?cmd=getentitytype&entityid=6065` **Response** (code: `OK`): ```json { "response": { "code": "OK", "entity": { "entitytype": "Course" } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) --- # GetEntityWork2 Gets the list of items that have been graded or need grading in a course back to a specified date. If the course has 1000 or more active enrollments (as determined by Course Enrollment Metrics ), then GetEntityWork2 does not return any results. ## Request **Method:** GET **Rights:** ReadGradebook@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getentitywork2` | | `entityid` | id | Yes | ID of the course for which to get the list of work. | | `date` | datetime | No | Optional date that specifies the limit to look back in history from now for work items. If omitted, all work items are returned. | | `outstanding` | boolean | No | When **true**, returns only work that needs grading. The default is **false**. | | `allstatus` | boolean | No | When **true**, returns work for all enrollments,regardless of enrollment status. When **false**, returns grades for only Active or Suspended enrollments. The default is **false**. | | `include` | string | No | Comma-separated list of optional data to return. Possible values are: - *user* - Includes the user data in the response. - *course* - Includes the course data in the response. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "works": { "work": [ { "enrollmentid": "id", "entityid": "string", "entitytitle": "string", "itemid": "string", "itemtitle": "string", "itemtype": "ItemType", "workid": "string", "submittedversion": "int", "submitteddate": "datetime", "scoredversion": "int", "scoreddate": "datetime", "score": "double", "pointspossible": "double", "pointsachieved": "double", "grade": "string", "groupid": "id", "groupname": "string", "userid": "id", "userfirstname": "string", "userlastname": "string", "breadcrumb": { "title": [ {} ] }, "thumbnail": { "entityid": "id", "$value": "string" } } ] } } } ``` ### works #### work Identifies a single work item. | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | Enrollment ID for the student who submitted something, which generated this work item. | | `entityid` | string | The course ID. | | `entitytitle` | string | *(optional)* The title of the course referred to by *entityid*. *entitytitle* is included only if *include* contains *course*. | | `itemid` | string | Item ID for which the student submitted something. | | `itemtitle` | string | Title of the item for which the student submitted something. | | `itemtype` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | An ItemType value that is the type of item that *itemid* refers to. | | `workid` | string | The ID of this work entry. Multiple work items for an enrollmentid-itemid pair can exist if the student has re-submitted for the item, and workid distinguishes multiple entries. It is unique only within the enrollmentid-itemid pair. | | `submittedversion` | int | The version of the student submission that this work item corresponds to. | | `submitteddate` | datetime | The date that the student submitted the work item. | | `scoredversion` | int | Version of the last scored submission. | | `scoreddate` | datetime | The date the item was scored. | | `score` | double | *(optional)* The assigned score for this item. | | `pointspossible` | double | *(optional)* The number of points possible for this item. | | `pointsachieved` | double | *(optional)* The number of points achieved for this item. | | `grade` | string | The letter grade, if any, for this item. | | `groupid` | id | *(optional)* The group ID if this work item resulted from a group assignment being submitted. | | `groupname` | string | *(optional)* The group name if this work item resulted from a group assignment being submitted. | | `userid` | id | *(optional)* The user ID associated with *enrollmentid*. *userid* is included only when this work item did not result from a group assignment being submitted. | | `userfirstname` | string | *(optional)* The first name of the user referred to by *userid*. *userfirstname* is included only when *include* contains *user*, and *userid* has a value. | | `userlastname` | string | *(optional)* The last name of the user referred to by *userid*. *userlastname* is included only when *include* contains *user*, and *userid* has a value. | ##### breadcrumb ###### title ##### thumbnail *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | *(optional)* The ID of the entity that owns the thumbnail resource when it is not owned by the same entity that owns the item. | ## Example This example gets all outstanding section work for a section with ID 20881 back to Jan 1, 2010. **URL:** `?cmd=getentitywork2&entityid=20881&outstanding=true&date=2010-01-01` **Response** (code: `OK`): ```json { "response": { "code": "OK", "works": { "work": [ { "enrollmentid": "22390", "itemid": "TG53D", "itemtitle": "Assignment with Dropbox", "itemtype": "Assignment", "workid": "1", "submittedversion": 1, "submitteddate": "2010-03-16T20:31:55.303Z", "scoredversion": 0, "scoreddate": "1753-01-01T00:00:00Z", "grade": "", "breadcrumb": { "title": [ { "$value": "Lesson 5" }, { "$value": "Module 2" } ] } }, { "enrollmentid": "22390", "itemid": "CJIF4", "itemtitle": "Lesson 5 Homework", "itemtype": "Assignment", "workid": "1", "submittedversion": 0, "submitteddate": "2010-03-16T18:28:11.66Z", "scoredversion": 0, "scoreddate": "1753-01-01T00:00:00Z", "grade": "", "breadcrumb": { "title": [ { "$value": "Lesson 5" }, { "$value": "Module 2" } ] } }, { "enrollmentid": "22390", "itemid": "TU87A", "itemtitle": "Lesson 5 Reading and Report", "itemtype": "Assignment", "workid": "1", "submittedversion": 0, "submitteddate": "2010-02-11T00:06:18.87Z", "scoredversion": 0, "scoreddate": "1753-01-01T00:00:00Z", "grade": "", "breadcrumb": { "title": [ { "$value": "Lesson 5" }, { "$value": "Module 2" } ] } }, { "enrollmentid": "22390", "itemid": "RT5F2", "itemtitle": "Week 1 Introduction", "itemtype": "Discussion", "workid": "1", "submittedversion": 0, "submitteddate": "2010-03-16T21:17:40.313Z", "scoredversion": 0, "scoreddate": "1753-01-01T00:00:00Z", "grade": "", "breadcrumb": { "title": [ { "$value": "Lesson 5" }, { "$value": "Module 2" } ] } } ] } } } ``` ## See Also - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetGrade This command gets the grade detail for the specified user enrollment and item. If no grade detail exists or the item referred to by itemid is of type lesson, an empty grade element is returned. GetGrade does not calculate or return due dates. For more extensive grade information or to retrieve lesson grades (which are a rollup of multiple item grades), see GetEnrollmentGradebook2. **Performance notes**: GetGrade performs significant set-up work to get a grade. When retrieving more than one grade, do not call GetGrade multiple times or from a loop, which duplicates the set-up work for each call. Instead, call a gradebook command that retrieves multiple grades (GetEnrollmentGradebook2, GetUserGradebook2, or GetEntityGradebook3), optionally specifying multiple item IDs to get exactly those grades you need. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgrade` | | `enrollmentid` | id | Yes | Enrollment ID of user for which to get the grade. | | `itemid` | string | Yes | Item ID for which to get the grade. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "grade": {} } } ``` ### grade This node conforms to the Grade format. ## Example This example retrieves gradebook detail for the enrollment with ID 6165 and the item with ID XG99D. **URL:** `?cmd=getgrade&enrollmentid=6165&itemid=XG99D` **Response** (code: `OK`): ```json { "response": { "code": "OK", "grade": { "status": "261", "responseversion": 3, "scoredversion": 1, "scoreddate": "2011-04-25T22:29:58.717Z", "achieved": 100, "possible": 100, "letter": "A", "attempts": 11, "seconds": 270, "submittedversion": 1, "submitteddate": "2011-04-11T16:46:32.263Z" } } } ``` ## See Also - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) --- # GetGradebookList This command lists entities (courses and sections) that have gradebooks. ## Request **Method:** GET **Rights:** ReadCourse@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgradebooklist` | | `title` | string | No | Optional title filter that limits the result to entities whose title matches the pattern. The pattern may contain the wildcard character ‘\*’. | | `reference` | string | No | Optional reference filter that limits the result to entities whose reference matches the pattern. | | `domainid` | id | No | Optional domain filter that limits the result to entities from the specified domain. If omitted, domainid is the current signed-on user's domain. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "gradebooks": { "gradebook": { "entityid": "id", "entitytype": "C|S", "title": "string", "reference": "string", "guid": "guid", "schema": "2", "baseid": "id", "basetitle": "string", "basereference": "string", "baseguid": "string", "type": "Continuous|Range", "startdate": "datetime", "enddate": "datetime", "days": "int", "term": "string", "domainid": "id", "domainame": "string", "creationdate": "datetime" } } } } ``` ### gradebooks #### gradebook | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the owning entity of this gradebook. | | `entitytype` | id | Type of the owning entity of this gradebook: C for course, S for section. | | `title` | string | Title of the owning entity for this gradebook. | | `reference` | string | *(optional)* This owning entity's reference field value, which is reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `guid` | guid | This owning entity's globally unique ID (guid). | | `schema` | string | The schema version of this gradebook's course. If entitytype is S (section), schema is the schema version of the course identified by baseid. All new courses should be created with schema 2. CreateCourses supports schema 1 (formerly called GoCourse courses) for backwards compatibility. | | `baseid` | id | If entitytype is S (section), the ID of the section's base course, otherwise 0. | | `basetitle` | string | If entitytype is S (section), the title of the section's base course, otherwise undefined. | | `basereference` | string | If entitytype is S (section), the reference of the section's base course, otherwise undefined. | | `baseguid` | string | If entitytype is S (section), the globally unique ID (guid) of the section's base course, otherwise undefined. | | `type` | string | The gradebook type. Range gradebooks are for traditional courses where all students start and stop on the same dates. Continuous gradebooks are for rolling courses where students can start and finish on any date, proceeding through the course at their own pace independent of other students. | | `startdate` | datetime | The gradebook start date and time. | | `enddate` | datetime | The gradebook end date and time. | | `days` | int | The number of days student's should be enrolled in this gradebook. This value applies when the type is Continuous. | | `term` | string | The academic term of this gradebook. | | `domainid` | id | ID of the domain that owns the entity. | | `domainame` | string | Name of the domain that owns the entity. | | `creationdate` | datetime | Creation date and time of the gradebook's owning entity. | ## Example This example assumes the domain with ID 9909 exists with these entities. **URL:** `?cmd=getgradebooklist&domainid=9909` **Response** (code: `OK`): ```json { "response": { "code": "OK", "gradebooks": { "gradebook": [ { "entityid": "24155", "entitytype": "S", "title": "Section 1", "reference": "", "guid": "d2746bc8-2a08-4992-aef2-2271f04e08c6", "schema": "2", "baseid": "20836", "basetitle": "Chemistry", "basereference": "", "baseguid": "4d6ab992-145f-446e-8396-5ed1a085b84d", "type": "Range", "startdate": "2009-02-24T07:00:00Z", "enddate": "2010-02-25T06:59:00Z", "days": 365, "term": "", "domainid": "9909", "domainname": "My University", "creationdate": "2009-02-24T17:25:59.24Z" }, { "entityid": "118588", "entitytype": "C", "title": "Algebra I", "reference": "", "guid": "b95967d5-69de-4874-aaa2-6a7483bf1920", "schema": "2", "baseid": "0", "basetitle": "", "basereference": "", "baseguid": "00000000-0000-0000-0000-000000000000", "type": "Range", "startdate": "2010-08-01T06:00:00Z", "enddate": "2011-08-02T05:59:00Z", "days": 365, "term": "", "domainid": "9909", "domainname": "My University", "creationdate": "2010-02-15T22:13:21.8Z" } ] } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [GetCourse](https://api.agilixbuzz.com/docs/entry/Command/GetCourse.md) --- # GetGradebookSummary This command gets a summary of course participants that match the specified parameters. When *GetGradebookSummary* is called by a student, some data is ommitted to protect student privacy when there are fewer than five grades for the item across the included enrollments (the *allstatus* parameter changes which enrollments are included). ## Request **Method:** GET **Rights:** ReadGradebook or ReadCourse @entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgradebooksummary` | | `entityid` | id | Yes | Course ID for which to get time spent. | | `allstatus` | boolean | No | When *true*, returns time spent for all enrollments, regardless of enrollment status. When *false*, returns time spent for only Active or Suspended enrollments. The default is *false*. | | `itemid` | id | No | Optional, vertical-bar separated list of item IDs for which to get time spent. | | `verbose` | boolean | No | Optional, when *true*, returns more detail about each grade book entry. The default is *false*. | | `calculated` | boolean | No | Optional, when *true*, returns calculated score values as they appear in the end-user's gradebook as opposed to the raw score values. The default is *false*. | | `scorm` | boolean | No | Optional, when *true*, returns the detailed data about the student’s response represented as name-value pairs defined by SCORM. The default is *false*. | | `completed` | boolean | No | Optional, when *true*, and the entity's domain has set *allowviewingpeercompletion* to *true* (see Domain Data), returns the list of enrollments that have completed the listed items. The default is *false*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "itemid": "id", "minutes": {}, "completed": { "enrollment": [ { "enrollmentid": "id", "userid": "id", "firstname": "string", "lastname": "string" } ] } } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | id | | ##### minutes A comma-separated list of minutes spent on the item; however, when multiple students spend the same number of minutes, the minute number precedes **:n**, where n is the number of students who spent that much time. For example, a value of **5,3,2** indicates 3 students spent 5, 3, and 2 minutes, respectively. A value of **3:2,5** indicates 2 students spent 3 minutes, and 1 student spent 5 minutes. ##### completed *(optional)* This node is included when *completed* is *true* and there are enrollments that have completed this item. ###### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The enrollment ID that has completed this item. | | `userid` | id | The user ID. | | `firstname` | string | The user's first name. | | `lastname` | string | The user's last name. | ## Example This example retrieves the grade book summary for the section with ID 6162 **URL:** `?cmd=getgradebooksummary§ionid=6162` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "itemid": "ASSIGNMENT_DCVK", "minutes": { "$value": "8,1" } }, { "itemid": "DEFAULT", "minutes": { "$value": "0:2" } }, { "itemid": "FINALEXAM_DCVK", "minutes": { "$value": "1,0" } }, { "itemid": "BIOFUNDAMENTALS_DCVK", "minutes": { "$value": "0" } } ] } } } ``` ## See Also - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetGradebookWeights This command gets the item and category gradebook weights for the specified entity, optionally filtered by a specific grading period. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgradebookweights` | | `entityid` | id | Yes | ID of the course or section to get weights for. | | `periodid` | string | No | Optional period ID to filter the results by. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "weights": { "categoryweighttotal": "double", "itemweighttotal": "double", "total": "double", "totalwithextracredit": "double", "weightedcategories": "boolean", "category": [ { "id": "string", "itemweighttotal": "double", "name": "string", "percent": "double", "percentwithextracredit": "double", "weight": "double", "item": [ { "id": "string", "percent": "double", "percentwithextracredit": "double", "title": "string", "weight": "double" } ] } ] } } } ``` ### weights | Attribute | Type | Description | |-----------|------|-------------| | `categoryweighttotal` | double | *(optional)* Present when weightedcategories is true. Contains the sum of all category weight values. | | `itemweighttotal` | double | *(optional)* Present when weightedcategories is false. Contains the sum of all item weight values. | | `total` | double | The sum of all the category percent's excluding extra credit items and categories. If there is at least one non-extra credit category or item, this equals 1.0. | | `totalwithextracredit` | double | The sum of all the category percent's including extra credit items and categories. This can equal more than 1.0. | | `weightedcategories` | boolean | Indicates whether the entity's grading categories are weighted or not. | #### category Defines a grading category's weight. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The grading category ID. | | `itemweighttotal` | double | Contains the sum of all item weight values within this category. | | `name` | string | The grading category name. | | `percent` | double | A number between 0 and 1.0 that is this category's percent (excluding extra credit items) of the gradebook total. | | `percentwithextracredit` | double | A number between 0 and 1.0 that is this category's percent (including extra credit items) of totalwithextracredit. | | `weight` | double | The end-user assigned grading category weight. | ##### item Defines a course item's weight. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID. | | `percent` | double | A number between 0 and 1 that is this item's calculated percentage of the gradebook total. For extra credit items, this number is 0. | | `percentwithextracredit` | double | A number between 0 and 1 that is this item's calculated percentage of the totalwithextracredit. | | `title` | string | The item title. | | `weight` | double | The end-user assigned item weight. | ## Example This example retrieves gradebook weights for the course with ID 6165. **URL:** `?cmd=getgradebookweights&entityid=6165` **Response** (code: `OK`): ```json { "response": { "code": "OK", "weights": { "weightedcategories": true, "categoryweighttotal": 100, "total": 1, "totalwithextracredit": 1.02, "category": [ { "id": "0", "name": "Homework", "weight": 40, "itemweighttotal": 210, "percent": 0.4, "percentwithextracredit": 0.42, "item": [ { "id": "8KEIP", "title": "Research Paper", "weight": 100, "percent": 0.2, "percentwithextracredit": 0.2 }, { "id": "P9TVQ", "title": "Bonus Paper", "weight": 10, "percent": 0, "percentwithextracredit": 0.02 }, { "id": "DYVOM", "title": "Story Problems", "weight": 100, "percent": 0.2, "percentwithextracredit": 0.2 } ] }, { "id": "1", "name": "Quizzes", "weight": 60, "itemweighttotal": 200, "percent": 0.6, "percentwithextracredit": 0.6, "item": [ { "id": "BD7CK", "title": "Quiz 1", "weight": 100, "percent": 0.3, "percentwithextracredit": 0.3 }, { "id": "3HE1F", "title": "Parameters assessment", "weight": 100, "percent": 0.3, "percentwithextracredit": 0.3 } ] } ] } } } ``` ## See Also - [Course Data](https://api.agilixbuzz.com/docs/entry/Schema/CourseData.md) - [Item Data](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) --- # GetGradeHistory This command gets the history of grades for an item in the gradebook for the specified user enrollment. Each grade history item indicates some change in the grade state including time spent, recorded score, or changed grade status flags. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgradehistory` | | `enrollmentid` | id | Yes | Enrollment ID of student user for which to get grade history. | | `itemid` | string | Yes | ID of the item for which to get grade history. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "grades": { "grade": [ { "attempts": "int", "letter": "string", "modifieddate": "datetime", "achieved": "double", "possible": "double", "passing": "boolean", "rawachieved": "double", "rawpossible": "double", "responseversion": "int", "scoreddate": "datetime", "scoredversion": "int", "seconds": "int", "status": "GradeStatus", "submitteddate": "datetime", "submittedversion": "int", "user": { "firstname": "string", "lastname": "string", "reference": "string", "userid": "id", "username": "string", "agent": { "firstname": "string", "lastname": "string", "reference": "string", "username": "string", "userid": "id" } } } ] } } } ``` ### grades #### grade | Attribute | Type | Description | |-----------|------|-------------| | `attempts` | int | *(optional)* The number of attempts made on this item. | | `letter` | string | *(optional)* The letter grade, if any, for this grade history item. | | `modifieddate` | datetime | The date and time that the grade (including any of its attributes) was modified. | | `achieved` | double | *(optional)* The points achieved value, if any, for this grade history item. | | `possible` | double | *(optional)* The points possible value, if any, for this grade history item. | | `passing` | boolean | *(optional)* *true* if the score is greater than or equal to the passing score for the item and enrollment. Otherwise omitted. | | `rawachieved` | double | *(optional)* The number of actual points achieved for this item without any curving rules applied. This attribute is included only if it differs from achieved. | | `rawpossible` | double | *(optional)* The number of actual points possible for this item without any curving rules applied. This attribute is included only if it differs from possible. | | `responseversion` | int | *(optional)* The version of the teacher response that generated this grade history entry. (See PutTeacherResponse for more details.) 0 indicates no teacher response. | | `scoreddate` | datetime | *(optional)* The date and time that pointsachieved was assigned. | | `scoredversion` | int | The version of the student Submission that this grade history item applies to. (See GetStudentSubmission for more details.) 0 indicates no student submission exists at this point in time. | | `seconds` | int | *(optional)* The number of accumulated seconds the student has spent online in the item. | | `status` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | The bitwise OR of GradeStatus flags for this grade history item. | | `submitteddate` | datetime | *(optional)* Override from the teacher, if it exists, otherwise the student submission date. | | `submittedversion` | int | *(optional)* Version of the last student submission when this score was assigned. 0 indicates no student submission exists. | ##### user | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | First name of the user who created this response. | | `lastname` | string | Last name of the user who created this response. | | `reference` | string | Reference field value of the user who created this response. | | `userid` | id | ID of the user who created this response. | | `username` | string | Username of the user who created this response. | ###### agent *(optional)* If this agent node is present, then agent was proxying as user to create this grade history entry. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | First name of the agent user. | | `lastname` | string | Last name of the agent user. | | `reference` | string | Reference field value of the agent user. | | `username` | string | Username of the agent user. | | `userid` | id | ID of the agent user. | ## Example This example retrieves grade history for the enrollment with ID 6165 and item with ID "assign12". **URL:** `?cmd=getgradehistory&enrollmentid=6165&itemid=assign12` **Response** (code: `OK`): ```json { "response": { "code": "OK", "grades": { "grade": [ { "status": 261, "submittedversion": 0, "submitteddate": "2010-07-29T06:00:00Z", "scoredversion": 0, "scoreddate": "2010-07-29T19:48:57.44Z", "responseversion": 1, "pointsachieved": 95, "pointspossible": 100, "seconds": 973, "modifieddate": "2010-07-29T19:48:57.44Z", "user": { "userid": "9911", "firstname": "Sally", "lastname": "Anderson", "username": "teacher", "reference": "" } }, { "status": 0, "submittedversion": 0, "scoredversion": 0, "responseversion": 0, "seconds": 973, "modifieddate": "2010-07-29T19:48:16.893Z", "user": { "userid": "22288", "firstname": "Haley", "lastname": "Gammon", "username": "student", "reference": "haley-12345" } }, { "status": 0, "submittedversion": 0, "scoredversion": 0, "responseversion": 0, "seconds": 896, "modifieddate": "2010-07-15T22:13:49.687Z", "user": { "userid": "22288", "firstname": "Haley", "lastname": "Gammon", "username": "student", "reference": "haley-12345" } } ] } } } ``` ## See Also - [GetEntityGradebook3](https://api.agilixbuzz.com/docs/entry/Command/GetEntityGradebook3.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetGroup This command gets information for a particular group. ## Request **Method:** GET **Rights:** ControlCourse|UpdateCourse|ReadGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgroup` | | `groupid` | id | Yes | The ID of the group to get information for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "group": {} } } ``` ### group This element conforms to the Group format ## Example This example assumes the group with ID 204235 already exists. **URL:** `?cmd=getgroup&groupid=204235` **Response** (code: `OK`): ```json { "response": { "code": "OK", "group": { "id": "204235", "title": "Boys", "reference": "CS101-BY", "guid": "db36868d-ff5d-4856-a38e-f1ed87953343", "ownerid": "136875", "domainid": "9909", "setid": "1", "creationdate": "2010-07-28T16:21:23.813Z" } } } ``` ## See Also - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [DeleteGroups](https://api.agilixbuzz.com/docs/entry/Command/DeleteGroups.md) - [GetGroupList](https://api.agilixbuzz.com/docs/entry/Command/GetGroupList.md) - [UpdateGroups](https://api.agilixbuzz.com/docs/entry/Command/UpdateGroups.md) --- # GetGroupEnrollmentList This command lists enrollments for the specified group. ## Request **Method:** GET **Rights:** ControlCourse|UpdateCourse|ReadGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgroupenrollmentlist` | | `groupid` | id | Yes | ID of the group to list enrollments for. | | `courseid` | id | No | Schema 4+: ID of the owning course. When present, groupid is interpreted as a string group identifier within the course data rather than a group entity ID. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ {} ] } } } ``` ### enrollments #### enrollment *(optional)* This element conforms to the Enrollment-User format ## Example Lists the enrollments for the group with ID 204235. **URL:** `?cmd=getgroupenrollmentlist&groupid=204235` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "177932", "userid": "46220", "entityid": "136877", "domainid": "9909", "reference": "", "guid": "06174aca-62f6-49dd-89ff-8f01c875f7a4", "flags": "2097153", "status": "1", "startdate": "2010-06-10T06:00:00Z", "enddate": "2038-10-17T05:59:00Z", "user": { "id": "46220", "firstname": "Hank", "lastname": "Williams", "reference": "123456789", "guid": "ffba942e-2c57-4b0d-8310-77b96adaefe3", "userspace": "vschool", "username": "hank", "email": "", "lastlogindate": "2010-07-08T17:26:55.41Z" }, "domain": { "id": "9909", "name": "Jeff University" } } ] } } } ``` ## See Also - [AddGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/AddGroupMembers.md) - [GetEnrollmentGroupList](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGroupList.md) - [RemoveGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/RemoveGroupMembers.md) --- # GetGroupList This command lists groups in the specified owner entity (course). ## Request **Method:** GET **Rights:** ControlCourse|UpdateCourse|ReadGradebook@ownerid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getgrouplist` | | `ownerid` | id | Yes | ID of the owning entity (course) to list groups for. | | `includeenrollments` | boolean | No | When true, GetGroupList includes the list of group-member enrollments for each group. The default is false. | | `select` | string | No | Comma-separated list of which data to return. By default, only enrollment nodes are returned. Possible values are: - *data* - Includes the group's free-form structured data in the response. | | `setid` | string | No | Optional group set ID by which to filter the list. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "groups": { "group": [ { "enrollment": [ {} ] } ] } } } ``` ### groups #### group This element conforms to the Group format. ##### enrollment *(optional)* This element conforms to the Enrollment-User format ## Example Lists groups in the course with ID 136875. **URL:** `?cmd=getgrouplist&ownerid=136875` **Response** (code: `OK`): ```json { "response": { "code": "OK", "groups": { "group": [ { "id": "204236", "title": "Females", "reference": "CS101-GL", "guid": "3d2348f2-7ec2-4d3e-94c4-538d856d1863", "ownerid": "136875", "domainid": "9909", "setid": "1", "creationdate": "2010-07-28T16:21:23.86Z" }, { "id": "204235", "title": "Males", "reference": "CS101-BY", "guid": "db36868d-ff5d-4856-a38e-f1ed87953343", "ownerid": "136875", "domainid": "9909", "setid": "1", "creationdate": "2010-07-28T16:21:23.813Z" } ] } } } ``` ## See Also - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [DeleteGroups](https://api.agilixbuzz.com/docs/entry/Command/DeleteGroups.md) - [GetGroup](https://api.agilixbuzz.com/docs/entry/Command/GetGroup.md) - [UpdateGroups](https://api.agilixbuzz.com/docs/entry/Command/UpdateGroups.md) --- # GetItem This command gets a manifest item. The item data returned from **GetItem** may not match the item data returned from GetManifest because the latter function post-processes the item data for rolled-up learning objectives and other features. The item data for sections or groups shows the result of merging the underlying course item data with the overrides in the section or group item data. (See Item Data Schema for more details on the contents of the manifest.) ## Request **Method:** GET **Rights:** ReadCourse@course's entity ID when entityid refers to a course or a group in a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitem` | | `entityid` | id | Yes | ID of the course, or group that owns the manifest. | | `itemid` | string | Yes | ID of the item. | | `version` | string | No | Version of the item, defaults to latest version. | | `embedmaster` | bool | No | Indicates whether or not the server should recursively embed the derivative masters in the item. | | `groupid` | string | No | Schema 4+: when entityid is a course, returns the item with group-specific overrides merged in for the specified group. The group ID is the string group identifier from the course's group definitions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "item": { "id": "string", "resourceentityid": "id", "actualentityid": "string", "creationdate": "datetime", "modifieddate": "datetime", "version": "string", "origindepth": "int", "derivativedepth": "int", "data": {} } } } ``` ### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | ID of the item. | | `resourceentityid` | id | ID of the entity that owns the resources associated with the item. | | `actualentityid` | string | *(optional)* ID of the entity whose stored data actually defines this item after inheritance and group overrides are resolved. Present only when it differs from the requested entity. On a Schema 4+ course, when the item is requested with a groupid and that group overrides the item, this is the composite `{courseId}:{groupId}` (for example, `12345:team-alpha`), which lets clients detect that a group-specific override is in effect. The groupid segment contains only alphanumeric characters, hyphens, and underscores, so the value can always be split on the first colon. | | `creationdate` | datetime | The date and time the item was created. | | `modifieddate` | datetime | The date and tiem the item was last modified. | | `version` | string | The version of this item | | `origindepth` | int | *(optional)* The depth in a course chain where this item originated. | | `derivativedepth` | int | *(optional)* The depth in a course chain that represents where edits in a derivative farthest from the master occured. | #### data See Item Data Schema for more details. ## Example This example gets the item from the course whose ID is 4378 and whose itemid is "DISCUSSION\_1\_\_POINTS". **URL:** `?cmd=getitem&entityid=4378&itemid=DISCUSSION_1__POINTS` **Response** (code: `OK`): ```json { "response": { "code": "OK", "item": { "id": "DISCUSSION_1__POINTS", "resourceentityid": "20723", "creationdate": "2009-10-30T22:01:58.887Z", "modifieddate": "2009-11-05T00:20:34.96Z", "version": "3", "data": { "type": { "$value": "Discussion" }, "parent": { "$value": "MODULE 1" }, "sequence": { "$value": "f" }, "title": { "$value": "Discussion #1 - Points" }, "abbreviation": { "$value": "D#1- P" }, "folder": { "$value": "XLBSJ" }, "href": { "$value": "Templates/Data/XLBSJ/index.html" }, "period": { "$value": "0" }, "duedate": { "$value": "2010-08-25T23:59:00Z" }, "allowlatesubmission": { "$value": true }, "gradable": { "$value": true }, "perfectscore": { "$value": 1 }, "weight": { "$value": 50 } } } } } ``` ## See Also - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [GetManifestItem](https://api.agilixbuzz.com/docs/entry/Command/GetManifestItem.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetItemAnalysis2 Some items compute their score from scores assigned within the item. For example, assessments and homework items compute their score from individual question scores, SCORM-based custom activities compute their score from the SCO's cmi.interactions, and rubric-graded assignments compute their score from rubric-row scores. GetItemAnalysis2 returns a summary analysis for these item types and their constituent part scores. The analysis includes answer choices, question difficulty, and a correlation between the question, SCO-interaction, or rubric-rule scores and overall item scores. This command analyzes submissions and scores associated with all courses and items that derive from the course identified by entityid. ## Request **Method:** GET **Rights:** GradeExam@entityid or ReadGradebook@entityid when itemid refers to an assessment or homework item, GradeForum@entityid or ReadGradebook@entityid when itemid refers to a discussion, wiki, blog, or journal item, GradeAssignment@entityid or ReadGradebook@entityid when itemid refers to an assignment, custom activity, or RSS-feed item. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemanalysis2` | | `entityid` | id | Yes | Course or section ID that contains itemid. | | `itemid` | string | Yes | Item ID of the assessment, homework, SCO, or rubric-graded item to analyze. | | `groupid` | id | No | Optional group ID to filter the analysis. If specified, the analysis includes data from only enrollments that belong to the group. | | `enrollmentid` | id | No | Optional enrollment ID to filter the analysis. If specified, the analysis includes data from only the specified enrollment. | | `allstatus` | boolean | No | When true, returns analysis for enrollments of any status. When false, returns analysis for only Active or Suspended enrollments. The default is false. | | `summary` | string | No | Optional parameter that controls the response summaries element. Applies only if itemid refers to a homework or assessment item. If summary is omitted, the summaries response element is also omitted. You can specify a comma separated list of the following: - **Objective** - Summarize questions by learning objective - **Type** - Summarize questions by type (multiple choice, matching, etc.) - **Group** - Summarize questions by question groups - **Meta-PROPERTY** - Summarize questions by the named metadata property (replace "PROPERTY" with the actual metadata property name.) A question may appear in more than one summary in the response. | | `verbose` | boolean | No | When true, the response includes the grades element, which contains score details for analyzed enrollments. The default is false. | | `sources` | boolean | No | When true, the response includes the sources element, which further subdivides that data used to compute a summary according to its source (user or course). The default is false. | | `setid` | id | No | Optional objective mapping set used to translate the objectives. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "analysis": { "scores": { "score": [ { "score": "double", "count": "int" } ] }, "grades": { "grade": [ { "grade": "string", "count": "int" } ] }, "details": { "detail": [ { "number": "string", "excluded": "(true|false)", "enrollments": "int", "attempts": "int", "score": "double", "correlation": "double", "seconds": "double", "answer": [ { "correct": "boolean", "count": "int" } ], "question": {}, "rubricrule": { "id": "string", "max": "double", "body": {} }, "grades": { "enrollment": [ { "enrollmentid": "id", "achieved": "double", "possible": "double", "notes": {}, "answer": {} } ] } } ] }, "summaries": [ { "type": "string", "summary": [ { "key": "string", "enrollments": "int", "attempts": "int", "score": "double", "correlation": "double", "objective": { "id": "string", "title": "string", "sources": { "guid": [ {} ] } }, "brackets": { "bracket": [ { "label": "string" } ] }, "detail": [ { "number": "string" } ] } ], "sources": { "source": [ { "id": "id", "itemid": "string", "user": {}, "course": {}, "summary": [ { "key": { "$value": "string" }, "score": { "$value": "double" }, "bracket": { "$value": "string" } } ] } ] } } ] } } } ``` ### analysis #### scores ##### score | Attribute | Type | Description | |-----------|------|-------------| | `score` | double | The score for this bracket. | | `count` | int | The number of attempts that achieved the score of this bracket. | #### grades ##### grade | Attribute | Type | Description | |-----------|------|-------------| | `grade` | string | The letter grade for this bracket. | | `count` | int | The number of attempts that achieved this letter grade. | #### details ##### detail | Attribute | Type | Description | |-----------|------|-------------| | `number` | string | Detail number. | | `excluded` | boolean | *(optional)* true if this questions has been excluded from the score. Default is false. Questions that have been excluded are not counted in the summary, although they are listed in the summaries they would be counted in. | | `enrollments` | int | Number of unique enrollments that had attempts for this question. | | `attempts` | int | Number of attempts for this question. | | `score` | double | Scaled average score for this question [0,1]. | | `correlation` | double | Correlation coefficient [-1,1] between students' question scores and overall assessment scores, which is calculated using Spearman's rank algorithm. | | `seconds` | double | *(optional)* Average seconds spent for this question. This value is only available for questions in homework in groups where it is the only question. | ###### answer Submission answer | Attribute | Type | Description | |-----------|------|-------------| | `correct` | boolean | *(optional)* Whether the answer is correct. The default is false. | | `count` | int | Number of submissions that selected this answer. | ###### question *(optional)* Question Data ###### rubricrule *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The unique ID of the rule within this rubric. | | `max` | double | The maximum score for this rubric rule. Zero indicate that graders leave text feedback instead of a numerical score for this rubric rule. | ####### body *(optional)* An XHTML fragment that is the body of the first cell in the rubric rule. ###### grades *(optional)* Included if the request specified verbose=true. ####### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The enrollment ID of the student. | | `achieved` | double | *(optional)* The points achieved by the student for this question or rubric rule. | | `possible` | double | *(optional)* The points possible for this question or rubric rule. | ######## notes *(optional)* An XHTML fragment that is the notes or feedback recorded by the teacher. ######## answer *(optional)* Contains the student's answer, if any, to this question. Follows same format as *answer* in Submission. #### summaries *(optional)* Included if the request contained the summary parameter. | Attribute | Type | Description | |-----------|------|-------------| | `type` | string | The value specified for summary in the request. | ##### summary | Attribute | Type | Description | |-----------|------|-------------| | `key` | string | A summary key that identifies this summary grouping. Its value depends on the summary type: - **Objective** - key is the learning objective ID - **Type** - key is the Question type (choice, match, answer, etc.) - **Group** - key is the Question group name - **Meta-PROPERTY** - key is the metadata property's value. For questions that do not participate in any summary grouping (do not have an objective, group, or metadata property) key is the empty string (""). | | `enrollments` | int | Number of unique enrollments that had attempts for this summary. | | `attempts` | int | Number of attempts for this summary. | | `score` | double | Scaled average score for this summary [0,1]. | | `correlation` | double | Correlation coefficient [-1,1] between students' summary scores and overall assessment scores, which is calculated using Spearman's rank algorithm. | ###### objective *(optional)* If you specify an input *setId* and input *summary* of *Objective*, *objective* identifies a translated-to objective. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | *(optional)* If the objective was translated, the public ID of the objective. | | `title` | string | *(optional)* If the objective was translated, the title of the objective. | ####### sources *(optional)* If the objective was translated, the GUID(s) of the pre-translation objectives that correlate with this objective. ######## guid The GUID of the source objective. ###### brackets *(optional)* ####### bracket The value of this element is the number of students that achieved this learning objective bracket. | Attribute | Type | Description | |-----------|------|-------------| | `label` | string | The label for this bracket | ###### detail | Attribute | Type | Description | |-----------|------|-------------| | `number` | string | Detail number. | ##### sources *(optional)* ###### source | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | The ID of the source (a user or course ID). | | `itemid` | string | The ID of the item at the source. | ####### user *(optional)* A User element if the source is a user. ####### course *(optional)* A Course element if the source is a course. ####### summary ######## key ######## score ######## bracket *(optional)* ## Example Retrieves the question analysis in the assessment with item ID "MIDTERM" and summarized by learning objective. **URL:** `?cmd=getitemanalysis2&entityid=43562&itemid=MIDTERM&summary=Objective` **Response** (code: `OK`): ```json { "response": { "code": "OK", "analysis": { "scores": { "score": [ { "score": "20", "count": "1" }, { "score": "70", "count": "1" }, { "score": "80", "count": "1" }, { "score": "100", "count": "1" } ] }, "grades": { "grade": [ { "grade": "A", "count": "1" }, { "grade": "B", "count": "1" }, { "grade": "C", "count": "1" }, { "grade": "D", "count": "0" }, { "grade": "F", "count": "1" } ] }, "details": { "detail": [ { "number": "1", "enrollments": "4", "attempts": "4", "score": "0.75", "correlation": "0.7745966692414834", "question": {}, "answer": [ { "count": "0", "$value": "1" }, { "count": "0", "$value": "2" }, { "correct": "true", "count": "3", "$value": "3" }, { "count": "0", "$value": "4" }, { "count": "1" } ] }, { "number": "2", "enrollments": "4", "attempts": "4", "score": "0.5", "correlation": "0.89442719099991586", "question": {}, "answer": [ { "correct": "true", "count": "2", "$value": "sqrt(10)/5" }, { "count": "1", "$value": "sqrt(10)/sqrt(25)" }, { "count": "1" } ] }, { "number": "3", "enrollments": "4", "attempts": "4", "score": "0.75", "correlation": "-0.2581988897471611", "question": {}, "answer": [ { "correct": "true", "count": "3", "$value": "1" }, { "count": "1", "$value": "2" }, { "count": "0" } ] }, { "number": "4", "enrollments": "4", "attempts": "4", "score": "0.75", "correlation": "0.7745966692414834", "question": {}, "answer": [ { "count": "0", "$value": "1" }, { "correct": "true", "count": "3", "$value": "2" }, { "correct": "true", "count": "3", "$value": "3" }, { "count": "0", "$value": "4" }, { "count": "1" } ] }, { "number": "5", "enrollments": "4", "attempts": "4", "score": "0.625", "correlation": "0.94868329805051377", "question": {}, "answer": [ { "correct": "true", "count": "3", "$value": "1-1" }, { "count": "0", "$value": "1-2" }, { "count": "0", "$value": "1-3" }, { "count": "0", "$value": "1-4" }, { "count": "1", "$value": "1-" }, { "count": "0", "$value": "2-1" }, { "correct": "true", "count": "3", "$value": "2-2" }, { "count": "0", "$value": "2-3" }, { "count": "0", "$value": "2-4" }, { "count": "1", "$value": "2-" }, { "count": "0", "$value": "3-1" }, { "count": "0", "$value": "3-2" }, { "correct": "true", "count": "2", "$value": "3-3" }, { "count": "1", "$value": "3-4" }, { "count": "1", "$value": "3-" }, { "count": "0", "$value": "4-1" }, { "count": "0", "$value": "4-2" }, { "count": "1", "$value": "4-3" }, { "correct": "true", "count": "2", "$value": "4-4" }, { "count": "1", "$value": "4-" } ] } ] }, "summaries": { "type": "Objective", "summary": [ { "key": "", "enrollments": "4", "attempts": "8", "score": "0.6875", "correlation": "0.63245553203367588", "brackets": [ { "bracket": [ { "label": "A", "$value": "1" }, { "label": "B", "$value": "0" }, { "label": "C", "$value": "1" }, { "label": "D", "$value": "0" }, { "label": "F", "$value": "2" } ] } ], "detail": [ { "number": "3" }, { "number": "5" } ] }, { "key": "624B1D43E8AB4CDB9ED19F1154E858C0", "enrollments": "4", "attempts": "8", "score": "0.75", "correlation": "0.7745966692414834", "objective": { "id": "AX", "title": "Objective AX" }, "brackets": [ { "bracket": [ { "label": "A", "$value": "3" }, { "label": "B", "$value": "0" }, { "label": "C", "$value": "0" }, { "label": "D", "$value": "0" }, { "label": "F", "$value": "1" } ] } ], "detail": [ { "number": "1" }, { "number": "4" } ] }, { "key": "E10B301628924043B6E6B706FB93F5C4", "enrollments": "4", "attempts": "8", "score": "0.625", "correlation": "0.94868329805051377", "objective": { "id": "AY", "title": "Objective AY" }, "brackets": [ { "bracket": [ { "label": "A", "$value": "2" }, { "label": "B", "$value": "0" }, { "label": "C", "$value": "0" }, { "label": "D", "$value": "0" }, { "label": "F", "$value": "2" } ] } ], "detail": [ { "number": "2" }, { "number": "4" } ] } ] } } } } ``` ## See Also - [GetQuestion](https://api.agilixbuzz.com/docs/entry/Command/GetQuestion.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) - [Rubric](https://api.agilixbuzz.com/docs/entry/Schema/Rubric.md) - [Question](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [GetItemReport](https://api.agilixbuzz.com/docs/entry/Command/GetItemReport.md) --- # GetItemInfo This command gets information about an item in the course, section or group specified by entityid. ## Request **Method:** POST **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getiteminfo` | **Request body (JSON):** ```json { "requests": { "item": [ { "entityid": "id", "itemid": "string", "groupid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `item.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Course, section, or group ID that owns this item. | | `item.itemid` | string | Yes | The ID of the item. | | `item.groupid` | string | No | Schema 4+: when entityid is a course, returns information about the group-specific override for the specified group rather than the course-level item. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "item": { "version": "string", "creationdate": "datetime", "modifieddate": "datetime" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### item | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The current resource version. | | `creationdate` | datetime | The creation date and time of the resource. | | `modifieddate` | datetime | The modified date and time of the resource. | ## See Also - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [DeleteItems](https://api.agilixbuzz.com/docs/entry/Command/DeleteItems.md) - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetItemLinks This command gets a list of manifest items that link to the specified item through course or item chaining. It can also get the list of courses that link to (are derivates of) a specified course. GetItemLinks is recursive; it lists items or courses whether they directly or indirectly link to the specified item or course. For example, if course with ID 222 links to 333, and 333 links to 444, then GetItemLinks reports both 222 and 333 as links to 444. ## Request **Method:** GET **Rights:** ReadCourse@entityid when entityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemlinks` | | `entityid` | id | Yes | ID of the course that owns the item. | | `itemid` | string | No | ID of the item. Omit itemid to return the list of courses that link to (are derivatives of) entityid. | | `derivatives` | boolean | No | Indicates whether or not to include items chained to the specified item through a derivative course relationship. The default is true | | `limit` | int | No | Limits the number of items returned by the server. *limit* must be greater than 0 and less than or equal to 10000. If *limit* is omitted, *GetItemLinks* uses 10000 for the limit. | | `links` | boolean | No | Indicates whether or not to include items chained to the specified item through item links. The default is true | | `recurse` | boolean | No | Indicates whether or not to recursive through the item graph including all items that indirectly link to the specified item. The default is true | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "entityid": "id", "itemid": "string" } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the course that contains id. If id is empty, this is the derivative course ID that links to the entityid specified in the request. | | `itemid` | string | ID of the item that links to itemid; or empty string ("") if you did not specify an itemid. | ## Example This example gets the list items that link to an item from the course whose ID is 4378 and whose itemid is "12345". **URL:** `?cmd=getitemlinks&entityid=4378&itemid=12345` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "entityid": "4379", "itemid": "12345" }, { "entityid": "4395", "itemid": "12345" }, { "entityid": "5522", "itemid": "XXYYZ" } ] } } } ``` ## See Also - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [GetManifestItem](https://api.agilixbuzz.com/docs/entry/Command/GetManifestItem.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetItemList This command lists items. The item data returned from **GetItemList** may not match the item data returned from GetManifest because the latter function post-processes the item data for rolled-up learning objectives and other features. (See Item Data Schema for more details on the contents of the manifest.) ## Request **Method:** GET **Rights:** : ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemlist` | | `entityid` | id | Yes | ID of the course that owns the manifest. | | `itemid` | string | No | Optional ID of the item to retrieve. When specified, only the item with the specified itemid is returned. To get an item with its descendant children from the manifest, see GetManifestItem. | | `query` | string | No | Optional query used to filter the list of items to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, allversions is ignored. | | `allversions` | boolean | No | Specify true to retrieve metadata for all versions of the specified item; or specify false to retrieve only the latest version's metadata. The default is false. When true, you must have the Update right (UpdateCourse) for the entity specified by entityid. | | `groupid` | string | No | Schema 4+: when entityid is a course, returns items with group-specific overrides merged in for the specified group. The group ID is the string group identifier from the course's group definitions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "id": "string", "data": {} } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID. | ##### data See Item Data Schema for more details. ## Example This example lists the items from the course whose ID is 4378. **URL:** `?cmd=getitemlist&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "id": "Assignment12", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 12" }, "href": { "$value": "Assets/assignment12.htm" } } } ] } } } ``` ## See Also - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [GetManifestItem](https://api.agilixbuzz.com/docs/entry/Command/GetManifestItem.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetItemRating This command gets a user rating on a manifest item. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemrating` | | `entityid` | id | Yes | ID of the course that owns the manifest. | | `itemid` | string | Yes | ID of the item. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "rating": { "rating": "double", "flags": "RightsFlags" } } } ``` ### rating | Attribute | Type | Description | |-----------|------|-------------| | `rating` | double | The user rating assigned to the item. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags that indicate the user's privileges associated with the rating. | ## See Also - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [PutItemRating](https://api.agilixbuzz.com/docs/entry/Command/PutItemRating.md) - [GetItemRatingSummary](https://api.agilixbuzz.com/docs/entry/Command/GetItemRatingSummary.md) --- # GetItemRatingSummary This command gets the summary of user ratings on a manifest item. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemratingsummary` | | `entityid` | id | Yes | ID of the course that owns the manifest. | | `itemid` | string | Yes | ID of the item. | | `flags` | enum-RightsFlags | No | A bitwise-OR of RightsFlags used to filter the ratings summarized. The server will only include those ratings that were assigned by users with at least these privileges. If this parameter is not supplied, all ratings are summarized. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "summary": { "average": "double", "count": "int" } } } ``` ### summary | Attribute | Type | Description | |-----------|------|-------------| | `average` | double | The average rating assigned to the item. | | `count` | int | The number of user ratings. | ## See Also - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [PutItemRating](https://api.agilixbuzz.com/docs/entry/Command/PutItemRating.md) - [GetItemRating](https://api.agilixbuzz.com/docs/entry/Command/GetItemRating.md) --- # GetItemReport Some items compute their score from scores assigned within the item. For example, assessments and homework items compute their score from individual question scores, SCORM-based custom activities compute their score from the SCO's cmi.interactions, and rubric-graded assignments compute their score from rubric-row scores. GetItemReport returns report data for these item types and their constituent part scores. The reports include answer choices, question difficulty, and a correlation between the question, SCO-interaction, or rubric-rule scores and overall item scores. This command analyzes submissions and scores associated with all courses and items that derive from the course identified by entityid. This command provides the analysis information used by GetItemAnalysis2 in exportable data formats. ## Request **Method:** GET **Rights:** GradeExam@entityid when itemid refers to an assessment or homework item, GradeForum@entityid when itemid refers to a discussion, wiki, blog, or journal item, GradeAssignment@entityid when itemid refers to an assignment, custom activity, or RSS-feed item. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getitemreport` | | `entityid` | id | Yes | Course or section ID that contains itemid. | | `itemid` | string | Yes | Item ID of the assessment, homework, SCO, or rubric-graded item to analyze. | | `groupid` | id | No | Optional group ID to filter the analysis. If specified, the analysis includes data from only enrollments that belong to the group. | | `enrollmentid` | id | No | Optional enrollment ID to filter the analysis. If specified, the analysis includes data from only the specified enrollment. | | `allstatus` | boolean | No | When true, returns analysis for enrollments of any status. When false, returns analysis for only Active or Suspended enrollments. The default is false. | | `report` | string | Yes | Specifies which data to extract. - **StudentScores** - The list of students and the scores they received for the item. - **StudentResponses** - The list of students and their responses or scores to the individual questions, rubric-rules and interactions. - **ItemAnalysis** - The list of questions, rubric-rules or interactions and an analysis of each. - **ObjectiveMastery** - The list of objective's aligned to the item and an analysis of the students' mastery of those objectives. - **StudentProficienty** - The list of students and their mastery of the learning objectives. | | `select` | string | Yes | The fields to include on the report. You may select the following for any report: - **item.title** - The title of the item. - **item.id** - The ID of the item. You may select for the following for StudentScores, StudentResponses, and StudentProficiency: - **user.firstname** - The first name of the student. - **user.lastname** - The last name of the student. - **user.username** - The username of the student. - **user.id** - The ID of the student. - **user.reference** - The reference of the student. - **enrollment.id** - The ID of the student's enrollment in the section or course or one of its derivatives. - **course.title** - The title of the section or course the student is enrolled in. - **course.id** - The ID of the section or course the student is enrolled in. - **course.reference** - The reference of the section or course the student is enrolled in. - **domain.name** - The name of the student's domain. - **domain.userspace** - The userspace of the student's domain. - **domain.id** - The ID of the student's domain. - **domain.reference** - The reference of the student's domain. You may select for the following for StudentScores: - **achieved** - The points achieved by the student for the item. - **possible** - The maximum number points possible. - **score** - The percentage score for the student: achieved / possible. You may select for the following for StudentResponses: - **questions.response** - The student's response or score for each question, rubric-rule or interaction. - **questions.score** - The student's score for each question, rubric-rule or interaction. You may select for the following for ObjectiveMastery: - **objective.id** - The ID of the objective. - **objective.title** - The title (description) of the objective. - **brackets.count** - The number of students that achieved each objective mastery bracket for the objective. - **brackets.percent** - The percent of students that achieved each objective mastery bracket for the objective. You may select for the following for StudentProficiency: - **objectives** - The student's mastery bracket foreach objective aligned to the item. You may select for the following for ItemAnalysis: - **question.number** - The sequence number of the question, rubric-rule or interaction in the item. - **question.id** - The ID of the question, rubric-rule or interaction. - **question.body** - The body (description) of the question, rubric-rule or interaction. - **difficulty** - Scaled average score for this question [0,1]. This is an indicator of the scores difficulty. - **discrimination** - Correlation coefficient [-1,1] between students' question scores and overall item scores, which is calculated using Spearman's rank algorithm. - **answers.count** - For some question types, the responses available and the number of student's that selected that response. - **answers.percent** - For some question types, the responses available and the percent of student's that selected that response. | | `filename` | string | No | The suggested filename for the report data download. | | `format` | string | Yes | The format of the extracted data. | | `setid` | id | No | Optional objective mapping set used to translate the objectives. | | `spreadsheet` | boolean | No | Whether or not the generated CSV should be in spreadsheet format. Always use this for Excel, Google Sheets, or other spreadsheets, but not to import into other databases. The default is to assume the CSV will be used with a spreadsheet (true). | ## Response **Content-Type:** text/plain or text/csv **Content-Length:** data length ## See Also - [GetItemAnalysis2](https://api.agilixbuzz.com/docs/entry/Command/GetItemAnalysis2.md) - [Rubric](https://api.agilixbuzz.com/docs/entry/Schema/Rubric.md) - [Question](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) --- # GetKey This command retrieves a name/value pair from an entity. ## Request **Method:** GET **Rights:** UpdateDomain@entityid when entityid refers to a domain. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getkey` | | `entityid` | string | Yes | The ID of the domain that owns the name/value pair. | | `name` | string | Yes | The name of the key | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "key": { "value": "string" } } } ``` ### key | Attribute | Type | Description | |-----------|------|-------------| | `value` | string | The key's value. | ## Example This example gets the key with the name "ExamPassword" from the domain with ID 616. **URL:** `?cmd=getkey&entityid=616&name=ExamPassword` **Response** (code: `OK`): ```json { "response": { "code": "OK", "key": { "value": "Secret" } } } ``` ## See Also - [PutKey](https://api.agilixbuzz.com/docs/entry/Command/PutKey.md) --- # GetLoginActivity > **Deprecated** — use [GetEnrollmentActivity](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentActivity.md) instead. This command gets the login activity detail for a user or domain. ## Request **Method:** GET **Rights:** ReadUser@entityid or entityid is the signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getloginactivity` | | `entityid` | id | Yes | Entity ID of user or domain for which to get activity. If a domain is specified, the command lists activity for all users on the domain. | | `startdate` | datetime | No | Filters the response by login activity that occurred after the specified date. | | `enddate` | datetime | No | Filters the response by login activity that occurred before the specified date. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "activity": { "login": [ { "userid": "string", "firstname": "string", "lastname": "string", "username": "string", "reference": "string", "guid": "guid", "date": "datetime" } ] } } } ``` ### activity #### login | Attribute | Type | Description | |-----------|------|-------------| | `userid` | string | The ID of the user that logged in | | `firstname` | string | The first name of the user | | `lastname` | string | The last name of the user | | `username` | string | The username of the user | | `reference` | string | The reference of the user | | `guid` | guid | The GUID of the user | | `date` | datetime | The date and time the user logged in | ## Example This example retrieves activity detail for the enrollment with ID 303137. **URL:** `?cmd=getenrollmentactivity&enrollmentid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollment": { "activity": [ { "itemid": "C1", "date": "2011-08-18T16:06:51.747Z", "seconds": 154 }, { "itemid": "E1", "date": "2011-10-17T21:17:42.743Z", "seconds": 20 } ] } } } ``` ## See Also - [PutItemActivity](https://api.agilixbuzz.com/docs/entry/Command/PutItemActivity.md) --- # GetManifest This command gets the manifest for the specified entity (course, section, group, or enrollment). The manifest contains data field from the course and all the items in the course. The items are organized in a tree according to the parent-child relationships defined on the items, and the items are ordered by their *sequence* values. See Course Data Schema and Item Data Schema for more details on the contents of the manifest. To get all manifest data except the items, see GetManifestData. ## Request **Method:** GET **Rights:** ReadCourse@course's entity ID when entityid refers to a course or a group in a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmanifest` | | `entityid` | id | Yes | Entity ID (course, section, or enrollment) for which to get the manifest. | | `cached` | string | No | This parameter enables those who cache manifests to, in one call, either get the most recent manifest or be notified that their cached version is up to date. You specify for cached the version of a manifest that you previously retrieved from GetManifest. If the current manifest version differs from cached, then GetManifest sets the response code to OK and returns the manifest (including its version) in the response. If the current manifest version matches cached, then GetManifest sets the response code to NotModified and omits the manifest element from the response. | | `groupid` | string | No | Schema 4+: when entityid is a course, returns the manifest with group-specific item overrides merged in for the specified group. The group ID is the string group identifier from the course's group definitions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "manifest": { "schema": "int", "version": "string", "resourceentityid": "string", "derivativedepth": "int", "denycontenteditsdepth": "int", "flagcontenteditsdepth": "int", "data": {}, "item": [ { "id": "string", "resourceentityid": "string", "origindepth": "int", "derivativedepth": "int", "partial": "boolean", "data": {} } ] } } } ``` ### manifest | Attribute | Type | Description | |-----------|------|-------------| | `schema` | int | The schema version of the course. All new courses should be created with schema 2. GetManifest supports schema 1 (formerly called GoCourse courses) for backwards compatibility. | | `version` | string | Identifies the version of this manifest. | | `resourceentityid` | string | Defines the entity that contains this manifest's items and their associated resources in this manifest. | | `derivativedepth` | int | *(optional)* The depth in a course chain of this manifest. | | `denycontenteditsdepth` | int | *(optional)* The depth in a course chain after which content edits are denied. | | `flagcontenteditsdepth` | int | *(optional)* The depth in a course chain after which content edits are flagged. | #### data See Course Data Schema for more details. #### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | ID of the item. | | `resourceentityid` | string | *(optional)* Omitted if the item's resourcentityid is identical to this manifest's resourceentityid. Defines the entity that contains this item's referenced resources. | | `origindepth` | int | *(optional)* The depth in a course chain where this item originated. | | `derivativedepth` | int | *(optional)* The depth in a course chain that represents where edits in a derivative farthest from the master occured. | | `partial` | boolean | *(optional)* Specifies whether some elements are omitted from the item's *data* element. If partial is *true*, call NavigateItem to get the missing data. *GetManifest* sets *partial* to *true* when the caller may not view all the item's content. | ##### data See Item Data Schema for more details. ## Example This example gets the manifest for the course whose ID is 4378. **URL:** `?cmd=getmanifest&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "manifest": { "schema": "2", "version": "4378:15|4378:543", "resourceentityid": "4378,0", "data": { "learningobjectives": { "objective": [ { "guid": "9f179282-b083-4bbb-ae00-1a0af6b09009", "id": "2.2. [3]", "group": "Mathematics", "description": { "$value": "Make precise calculations and check the validity of the results from the context of the problem." } }, { "guid": "78968f13-b026-4bea-8e92-2d05615ca6ca", "id": "3.0. [2]", "group": "Mathematics", "description": { "$value": "Students note connections between one problem and another." } }, { "guid": "b98dc39a-f85c-4d3a-bb56-10d76c39457f", "id": "1.2. [5]", "group": "Mathematics", "description": { "$value": "Use tools, such as manipulatives or sketches, to model problems." } } ] }, "gradetables": { "table": [ { "id": "0", "name": "A,B,C,D,F", "scale": "Percent", "bracket": [ { "grade": "A", "score": 0.9 }, { "grade": "B", "score": 0.8 }, { "grade": "C", "score": 0.7 }, { "grade": "D", "score": 0.6 }, { "grade": "F", "score": 0 } ] }, { "id": "1", "name": "P/F", "scale": "Percent", "bracket": [ { "grade": "P", "score": 0.7 }, { "grade": "F", "score": 0 } ] } ] }, "outputtable": { "$value": "1" }, "gradeview": { "$value": "13" }, "categories": { "weighted": "false", "category": [ { "id": "0", "name": "Homework", "weight": 25, "sequence": "a" }, { "id": "1", "name": "Quizzes", "weight": 25, "sequence": "b", "gradeview": "5" }, { "id": "2", "name": "Final Exam", "weight": 50, "sequence": "c" } ] } }, "item": [ { "id": "DEFAULT", "creationdate": "2010-02-08T19:52:01.797Z", "creationby": "9911", "modifieddate": "2010-07-16T21:24:30.407Z", "modifiedby": "9911", "data": { "parent": { "$value": "[-MANIFEST-]" }, "title": { "$value": "Mathematics" }, "category": { "$value": "0" }, "inputtable": { "inherit": true, "$value": "1" } }, "item": [ { "id": "Assignment1", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 1" }, "href": { "$value": "Assets/assignment1.htm" } } }, { "id": "Assignment2", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "b" }, "title": { "$value": "Assignment 2" }, "href": { "$value": "Assets/assignment2.htm" }, "learningobjectives": { "objective": { "guid": "78968f13-b026-4bea-8e92-2d05615ca6ca" } } } }, { "id": "OR5TGN", "creationdate": "2010-03-22T21:21:30.307Z", "creationby": "9911", "modifieddate": "2010-03-22T21:24:59.21Z", "modifiedby": "9911", "data": { "type": { "$value": "AssetLink" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "c" }, "title": { "$value": "Count, Read and Write 1-100" }, "abbreviation": { "$value": "CRW" }, "folder": { "$value": "ASSIGN_1" }, "href": { "$value": "Assets/reading.htm" }, "learningobjectives": { "objective": [ { "guid": "9f179282-b083-4bbb-ae00-1a0af6b09009" } ] }, "categorysequence": { "$value": "a._m" }, "inputtable": { "inherit": true, "$value": "1" } } } ] } ] } } } ``` ## See Also - [Course Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/CourseData.md) - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetManifestItem](https://api.agilixbuzz.com/docs/entry/Command/GetManifestItem.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetManifestData This command gets the manifest data (see Course Data) for the specified entity (course, section, group, or enrollment) except for the <item> data. Call GetManifest to also get the <item> data. ## Request **Method:** GET **Rights:** ReadCourse@entityid when entityid refers to a course; ReadCourse@entityid when entityid refers to a group in the course; ReadUser|ControlCourse|UpdateCourse|ReadGradebook@entityid when entityid refers to a user's enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmanifestdata` | | `entityid` | id | Yes | Entity ID for which to get the manifest. | | `cached` | string | No | This parameter enables those who cache manifest data to, in one call, either get the most recent manifest data or be notified that their cached version is up to date. You specify for cached the version of manifest data that you previously retrieved from GetManifestData. If the current manifest data version differs from cached, then GetManifestData sets the response code to OK and returns the manifest data (including its version) in the response. If the current manifest data version matches cached, then GetManifestData sets the response code to NotModified and omits the manifest element from the response. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "manifest": { "schema": "int", "version": "string", "resourceentityid": "string", "derivativedepth": "int", "denycontenteditsdepth": "int", "flagcontenteditsdepth": "int", "data": {} } } } ``` ### manifest | Attribute | Type | Description | |-----------|------|-------------| | `schema` | int | The schema of the manifest data. The most recent schema is currently 2. | | `version` | string | Identifies the version of this manifest data. | | `resourceentityid` | string | Defines the entity that contains this manifest's items and their associated resources in this manifest. | | `derivativedepth` | int | *(optional)* The depth in a course chain of this manifest. | | `denycontenteditsdepth` | int | *(optional)* The depth in a course chain after which content edits are denited. | | `flagcontenteditsdepth` | int | *(optional)* The depth in a course chain after which content edits are flagged. | #### data This element conforms to the Course Data format minus the <item> elements. ## Example This example gets the manifest data for the course with ID 136875. **URL:** `?cmd=getmanifestdata&entityid=136875` **Response** (code: `OK`): ```json { "response": { "code": "OK", "manifest": { "resourceentityid": "136875,39", "version": "136875:116", "schema": "2", "data": { "description": { "$value": "
 
" }, "gradetables": { "table": [ { "id": "0", "name": "A,B,C,D,F", "scale": "Percent", "bracket": [ { "grade": "A", "score": 0.9 }, { "grade": "B", "score": 0.8 }, { "grade": "C", "score": 0.7 }, { "grade": "D", "score": 0.6 }, { "grade": "F", "score": 0 } ] }, { "id": "1", "name": "A+,A,A-,...,F", "scale": "Percent", "bracket": [ { "grade": "A+", "score": 0.97 }, { "grade": "A", "score": 0.93 }, { "grade": "A-", "score": 0.9 }, { "grade": "B+", "score": 0.87 }, { "grade": "B", "score": 0.83 }, { "grade": "B-", "score": 0.8 }, { "grade": "C+", "score": 0.77 }, { "grade": "C", "score": 0.73 }, { "grade": "C-", "score": 0.7 }, { "grade": "D+", "score": 0.67 }, { "grade": "D", "score": 0.63 }, { "grade": "D-", "score": 0.6 }, { "grade": "F", "score": 0 } ] }, { "id": "2", "name": "P/F", "scale": "Percent", "bracket": [ { "grade": "P", "score": 0.7 }, { "grade": "F", "score": 0 } ] } ] }, "categories": { "weighted": true, "category": [ { "id": "0", "name": "Homework", "weight": 40, "sequence": "a" }, { "id": "1", "name": "Quizzes", "weight": 60, "sequence": "b" } ] }, "periods": { "enabled": false } } } } } ``` ## See Also - [Course Data](https://api.agilixbuzz.com/docs/entry/Schema/CourseData.md) - [UpdateManifestData](https://api.agilixbuzz.com/docs/entry/Command/UpdateManifestData.md) --- # GetManifestInfo This command gets information about the manifest of one or more courses or sections. ## Request **Method:** POST **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmanifestinfo` | **Request body (JSON):** ```json { "requests": { "manifest": [ { "entityid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `manifest.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course or section that owns the manifest. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "manifest": { "version": "string" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### manifest | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the manifest. | ## Example This example gets information for the manifest for the course whose ID is 37681. **URL:** `?cmd=getmanifestinfo` **Request body:** ```json { "request": { "requests": { "manifest": { "entityid": "37681" } } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": { "code": "OK", "manifest": { "version": "11.11|20723:190|37681:172" } } } } } ``` ## See Also - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) --- # GetManifestItem This command gets an item and optionally some of its descendents from the manifest of a course or section. The items are organized in a tree according to the parent-child relationships defined on the items. (See Item Data Schema for more details on the contents of the manifest.) **Performance notes**: GetManifestItem performs significant set-up work to get a manifest item. When retrieving more than one item from a manifest, avoid calling GetManifestItem multiple times or from a loop, which duplicates the set-up work for each call. Instead, call GetManifest to get all items, and then parse out the items you want from the manifest's item list. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmanifestitem` | | `entityid` | id | Yes | ID of the course or section that owns the manifest. | | `itemid` | string | Yes | ID of the item to get. | | `generations` | int | No | The number of descendant generations to include in the result. 0 means include only the item specified by itemid, 1 includes 1 generation of descendants, 2 includes 2 generations, etc. The default is 0. | | `groupid` | string | No | Schema 4+: when entityid is a course, returns the item with group-specific overrides merged in for the specified group. The group ID is the string group identifier from the course's group definitions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "item": { "id": "string", "data": {}, "item": [ {} ] } } } ``` ### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | ID of the item. | #### data See Item Data Schema for more details. #### item *(optional)* When generations is non-zero and the item with ID itemid has descendants, the descendants are listed here as a tree of item nodes. ## Example This example gets the manifest item for the course whose ID is 4378 and whose itemid is "Assignment12". **URL:** `?cmd=getmanifestitem&entityid=4378&itemid=Assignment12&generations=0` **Response** (code: `OK`): ```json { "response": { "code": "OK", "item": { "id": "Assignment12", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 12" }, "href": { "$value": "Assets/assignment12.htm" } } } } } ``` ## See Also - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) --- # GetMasteryDetail This command summarizes a single learning objective's mastery for each enrollment in the specified entities. ## Request **Method:** GET **Rights:** ReportDomain@domainid when entityid is a domain; ReadGradebook|ReportCourse@courseid when entityid is a course; ReadGradebook|ReportSection@sectionid when entityid is a section; ReadUser|ReportUser@userid or userid is the current signed-on user when entityid is a user; ReadUser|ReportUser@enrollmentid.userid or ControlCourse|UpdateCourse|ReadGradebook|ReportCourse@enrollmentid.courseid or enrollmentid belongs to current signed-on user when entityid is an enrollment; **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmasterydetail` | | `entityid` | string | Yes | Vertical-bar-separated list of entity IDs. These entity IDs may refer to a domain, course, section, user, or enrollment. When the entity ID is a domain, all subdomains are included, and GetMasteryDetail may be slow to process all of the data. The provided entities must all be of the same type. | | `guid` | guid | Yes | The guid of the learning objective to use when summarizing mastery. | | `allstatus` | boolean | No | When true, uses all enrollments, regardless of enrollment status. When false, uses only Active or Suspended enrollments. The default is false. | | `startdate` | datetime | No | An optional enrollment date filter. GetMasteryDetail lists only enrollments that end after this date. | | `enddate` | datetime | No | An optional enrollment date filter. GetMasteryDetail lists only enrollments that start before this date. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "detail": { "enrollment": [ { "enrollmentid": "id", "userid": "id", "userreference": "string", "firstname": "string", "lastname": "string", "username": "string", "email": "string", "domainid": "id", "domainreference": "string", "domainname": "string", "courseid": "id", "coursereference": "string", "coursetitle": "string", "teachers": "string", "coverage": "double", "attempts": "double", "date": "datetime", "achieved": "double", "possible": "double", "unweightedaverage": "double", "formativecoverage": "double", "formativeattempts": "double", "formativedate": "datetime", "formativeachieved": "double", "formativepossible": "double", "formativeunweightedaverage": "double", "threshold": "double" } ] } } } ``` ### detail #### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The enrollment's ID. | | `userid` | id | The user ID. | | `userreference` | string | The user's reference. | | `firstname` | string | The user's first name. | | `lastname` | string | The user's last name. | | `username` | string | The user's reference. | | `email` | string | The user's email. | | `domainid` | id | The domain ID. | | `domainreference` | string | The domain's reference. | | `domainname` | string | The domain's name. | | `courseid` | id | The course ID. | | `coursereference` | string | The course's reference. | | `coursetitle` | string | The course's title. | | `teachers` | string | Vertical-bar-separated list of the names of the teachers that are enrolled in the course. Each teacher's name is formatted as *lastName*,*firstName*. For example, *Doe,Jane\|Smith,John*. | | `coverage` | double | The number of items related to the objective. | | `attempts` | double | The number of gradable attempts contributing to the *achieved* mastery-level calculation. | | `date` | datetime | The date of the last score the student received that was related to the learning objective. | | `achieved` | double | The number of weighted points achieved for the objective. | | `possible` | double | The number of weighted points possible for the objective. | | `unweightedaverage` | double | The unweighted average of the scores for the objective. | | `formativecoverage` | double | The number of formative items related to the objective. | | `formativeattempts` | double | The number of formative attempts contributing to the *formativeachieved* formative-mastery-level calculation. | | `formativedate` | datetime | The date of the last score the student received that was related to the learning objective for a formative assessment. | | `formativeachieved` | double | The number of formative weighted points achieved for the objective. | | `formativepossible` | double | The number of formative weighted points possible for the objective. | | `formativeunweightedaverage` | double | The unweighted average of the formative scores for the objective. | | `threshold` | double | The percent that demonstrates whether students have mastered a learning objective. | ## Example This example retrieves the learning objective mastery summary for enrollments in the course with ID 3379082. **URL:** `?cmd=getmasterydetail&entityid=3379082&guid=f80eb345-9e2c-4eae-8dbe-162b3c786514` **Response** (code: `OK`): ```json { "response": { "code": "OK", "detail": { "enrollment": [ { "enrollmentid": "412312341", "userid": "31234121", "userreference": "", "firstname": "Ophelia", "lastname": "Miller", "username": "omiller", "email": "", "domainid": "253224", "domainreference": "", "domainname": "My School Domain", "courseid": "3379082", "coursereference": "", "coursetitle": "Algebra 101", "teachers": "Smith,John|Teacher,Tad", "coverage": "1", "attempts": "0", "achieved": "0", "possible": "0.5", "unweightedaverage": "0", "formativecoverage": "0", "formativeattempts": "0", "formativeachieved": "0", "formativepossible": "0", "formativeunweightedaverage": "0", "threshold": "0.7" }, { "enrollmentid": "414123123", "userid": "41241123", "userreference": "", "firstname": "Silvia", "lastname": "White", "username": "swhite", "email": "", "domainid": "253224", "domainreference": "", "domainname": "My School Domain", "courseid": "3379082", "coursereference": "", "coursetitle": "Algebra 101", "teachers": "Smith,John|Teacher,Tad", "coverage": "1", "attempts": "1", "achieved": "1.5", "possible": "1.5", "unweightedaverage": "1", "date": "2014-01-08T00:00:00Z", "formativecoverage": "0", "formativeattempts": "0", "formativeachieved": "0", "formativepossible": "0", "formativeunweightedaverage": "0", "threshold": "0.7" } ] } } } ``` ## See Also - [GetObjectiveMastery](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveMastery.md) - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) --- # GetMasterySummary This command lists learning objectives and summarizes their mastery for enrollments in the specified entities. All of the objectives associated with an enrollment that are defined as part of an objective set are summarized. Additionally, if the requested entity is a course or enrollment then the objectives defined directly on a course are also summarized. ## Request **Method:** GET **Rights:** ReportDomain@domainid when entityid is a domain; ReadGradebook|ReportCourse@courseid when entityid is a course; ReadGradebook|ReportSection@sectionid when entityid is a section; ReadUser|ReportUser@userid or userid is the current signed-on user when entityid is a user; ReadUser|ReportUser@enrollmentid.userid or ControlCourse|UpdateCourse|ReadGradebook|ReportCourse@enrollmentid.courseid or enrollmentid belongs to current signed-on user when entityid is an enrollment; **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmasterysummary` | | `entityid` | string | Yes | Vertical-bar-separated list of entity IDs. These entity IDs may refer to a domain, course, section, user, or enrollment. When the entity ID is a domain, all subdomains are included, and GetMasterySummary may be slow to process all of the data. The provided entities must all be of the same type. | | `allstatus` | boolean | No | When true, uses all enrollments, regardless of enrollment status. When false, uses only Active or Suspended enrollments. The default is false. | | `setid` | id | No | An optional set filter. GetMasterySummary summarizes only objectives in the specified objective set. | | `mapsetid` | id | No | When specified, GetMasterySummary summarizes only objectives in the specified objective map set and ignores the *setid* filter. | | `startdate` | datetime | No | An optional enrollment date filter. GetMasterySummary summarizes only enrollments that end after this date. | | `enddate` | datetime | No | An optional enrollment date filter. GetMasterySummary summarizes only enrollments that start before this date. | | `grades` | long | No | An optional filter on a bitwise OR of GradeLevels. GetMasterySummary summarizes only objectives with matching GradeLevels. | | `subject` | string | No | An optional subject filter. GetMasterySummary summarizes only objectives that have the specified subject. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0. Specify false to ignore them. The default is false. | | `filterbycourseobjectives` | boolean | Yes | Specify true to get summary on objectives only included in course. This only applies when entity IDs refer to course, section, or enrollment. Specify false to get summary on all objectives including those deleted from course. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "summary": { "objective": [ { "guid": "guid", "id": "string", "title": "string", "coverage": "double", "attempts": "double", "achieved": "double", "possible": "double", "unweightedaverage": "double", "formativecoverage": "double", "formativeattempts": "double", "formativeachieved": "double", "formativepossible": "double", "formativeunweightedaverage": "double", "threshold": "double", "mastered": "double", "notmastered": "double", "notattempted": "double", "formativemastered": "double", "formativenotmastered": "double", "formativenotattempted": "double" } ] } } } ``` ### summary #### objective | Attribute | Type | Description | |-----------|------|-------------| | `guid` | guid | The unique identifier of the learning objective. | | `id` | string | The ID of the learning objective assigned by the source of the objective set. | | `title` | string | The title or description of the learning objective. | | `coverage` | double | The average number of items related to the objective. | | `attempts` | double | The sum of the number of gradable attempts contributing to the *achieved* mastery-level calculation. | | `achieved` | double | The average number of weighted points achieved for the objective. | | `possible` | double | The average number of weighted points possible for the objective. | | `unweightedaverage` | double | The average unweighted average of the scores for the objective. | | `formativecoverage` | double | The average number of formative items related to the objective. | | `formativeattempts` | double | The sum of the number of formative attempts contributing to the *formativeachieved* formative-mastery-level calculation. | | `formativeachieved` | double | The average number of formative weighted points achieved for the objective. | | `formativepossible` | double | The average number of formative weighted points possible for the objective. | | `formativeunweightedaverage` | double | The average unweighted average of the formative scores for the objective. | | `threshold` | double | The percent that demonstrates whether students have mastered a learning objective. | | `mastered` | double | The students that have mastered this objective. | | `notmastered` | double | The students that have attempted, but have not yet mastered, this objective. | | `notattempted` | double | The students that have not attempted this objective. | | `formativemastered` | double | The students that have mastered this objective using formative points. | | `formativenotmastered` | double | The students that have attempted, but have not yet mastered this objective using formative points. | | `formativenotattempted` | double | The students that have not attempted this objective's formative items. | ## Example This example retrieves the learning objective mastery summary for enrollments in the course with ID 3379082. **URL:** `?cmd=getmasterysummary&entityid=3379082` **Response** (code: `OK`): ```json { "response": { "code": "OK", "summary": { "objective": [ { "guid": "3efe0007-7950-4584-aa9e-c9399cd3236d", "id": "A1", "title": "Objective A1: Concepts and Principles", "coverage": "1", "attempts": "1", "achieved": "0.75", "possible": "1", "unweightedaverage": "0.5", "formativecoverage": "0", "formativeattempts": "0", "formativeachieved": "0", "formativepossible": "0", "formativeunweightedaverage": "0", "threshold": "0.7", "mastered": "1", "notmastered": "0", "notattempted": "1", "formativemastered": "0", "formativenotmastered": "0", "formativenotattempted": "2" }, { "guid": "d062b62f-fb43-4314-8f59-a2236f2d2e4f", "id": "A2", "title": "Objective A2: Theory and Rhetoric", "coverage": "1", "attempts": "1", "achieved": "0", "possible": "0.5", "unweightedaverage": "0", "formativecoverage": "0", "formativeattempts": "0", "formativeachieved": "0", "formativepossible": "0", "formativeunweightedaverage": "0", "threshold": "0.7", "mastered": "0", "notmastered": "1", "notattempted": "1", "formativemastered": "0", "formativenotmastered": "0", "formativenotattempted": "2" }, { "guid": "ffa299a9-3e1f-41f3-88d7-75ef77a4490b", "id": "A3", "title": "Objective A3: Practical Application", "coverage": "1", "attempts": "1", "achieved": "0.75", "possible": "1.25", "unweightedaverage": "0.375", "formativecoverage": "0", "formativeattempts": "0", "formativeachieved": "0", "formativepossible": "0", "formativeunweightedaverage": "0", "threshold": "0.7", "mastered": "1", "notmastered": "0", "notattempted": "1", "formativemastered": "0", "formativenotmastered": "0", "formativenotattempted": "2" } ] } } } ``` ## See Also - [GetObjectiveMastery](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveMastery.md) - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) --- # GetMessage This command returns a discussion forum message. ## Request **Method:** GET **Rights:** Authenticated user with ReadCourse/ReadSection on the containing course or section (or observer access). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmessage` | | `entityid` | id | Yes | ID of the entity (course or section) that contains the message. | | `itemid` | string | Yes | ID of the item that the message applies to. | | `messageid` | string | Yes | ID of the message to get. | | `groupid` | string | No | Optional group ID for the message. If omitted, the default group is used. | | `version` | string | No | Optional message version to get. If omitted, the most recent version is returned. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within message. For example, specify a filepath to retrieve an attachment from within the message. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Message data from within the message. - **file** - Returns a single file from within message. You must also specify filepath to identify which file to retrieve. - **zip** - Returns the entire message in a zip-compressed file containing the file meta.xml, which is a Message, and any supporting attached files. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This example assumes the entity with ID 6162 exists with a forum message of ID "89b2b64f710949018d5cf618a0bb681e.zip". **URL:** `?cmd=getmessage&entityid=6162&itemid=DISCUSSION_1__POINTS&messageid=89b2b64f710949018d5cf618a0bb681e.zip` ## See Also - [DeleteMessage](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessage.md) - [GetMessageList](https://api.agilixbuzz.com/docs/entry/Command/GetMessageList.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) --- # GetMessageList This command returns the messages associated with a discussion board of an entity. ## Request **Method:** GET **Rights:** Participate|ReadCourse|UpdateCourse|ReadGradebook|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getmessagelist` | | `entityid` | id | Yes | Entity ID (course) for which to get discussion board messages. | | `itemid` | string | Yes | Item ID for which to get discussion board messages. | | `groupid` | string | No | Group ID for which to get discussion board messages. If this parameter is not supplied, the command returns messages for the default group. | | `query` | string | No | Optional query used to filter the list of messages to retrieve. See Free-Form Data Query for more details. | | `userid` | id | No | Optional user to evaluate the per-message viewed (read/unread) state for. Defaults to the calling user. An administrator may pass another user's id to see that user's read state (for example a student's) without proxying in as that user. Requires ReadUser rights on the specified user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "messages": { "message": [ { "messageid": "string", "version": "string", "magnitude": "int", "status": "(Normal|Hidden)", "creationdate": "datetime", "modifieddate": "datetime", "creationby": "id", "viewed": "boolean", "wordcount": "int", "title": "string", "enrollmentid": "id", "creator": { "firstname": "string", "lastname": "string" }, "message": [ {} ] } ] } } } ``` ### messages #### message | Attribute | Type | Description | |-----------|------|-------------| | `messageid` | string | ID of this message. | | `version` | string | Version of this message. | | `magnitude` | int | The message magnitude. Larger numbers mean larger files. | | `status` | string | *(optional)* View status of this message. | | `creationdate` | datetime | The creation date of the message. | | `modifieddate` | datetime | The last-modified date of the message. | | `creationby` | id | ID of the user who created this message. | | `viewed` | boolean | Whether the user (the calling user, or the user given by the userid parameter) has viewed this message. | | `wordcount` | int | *(optional)* Number of words in this message. | | `title` | string | *(optional)* Title of the message. | | `enrollmentid` | id | *(optional)* Enrollment ID of the user who created the message. | ##### creator *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first (given) name of the user who created the message. | | `lastname` | string | The last name (surname) of the user who created the message. | ##### message *(optional)* Reply messages to the current message. These descendent message elements follow the same schema as the parent message element. ## Example This example assumes the entity with ID 6162 exists with these forum messages. **URL:** `?cmd=getmessagelist&entityid=6162&itemid=DISCUSSION_1__POINTS` **Response** (code: `OK`): ```json { "response": { "code": "OK", "messages": { "message": [ { "messageid": "89b2b64f710949018d5cf618a0bb681e.zip", "version": "1", "magnitude": 3, "creationby": "9898", "viewed": false, "wordcount": 153, "message": [ { "messageid": "d564c6aa2ccd4591b39f61d85e77408c.zip", "version": "1", "magnitude": 2, "creationby": "9984", "viewed": false, "wordcount": 49 } ] } ] } } } ``` ## See Also - [GetMessage](https://api.agilixbuzz.com/docs/entry/Command/GetMessage.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) - [UpdateMessageViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateMessageViewed.md) --- # GetNextQuestion Submits answers for the current question in an adpative assessment. Returns the next question or questions. If there are not more questions, it returns a submission. ## Request **Method:** POST **Rights:** ReadCourse@entityid or UpdateCourse|GradeExam@entityid **Request body (JSON):** ```json { "request": { "enrollmentid": "id", "itemid": "string", "action": "next|previous|submit", "page": "int", "seconds": "int", "submission": [ { "partid": "string", "answer": { "$value": "string" } } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID | | `itemid` | string | Yes | Item ID | | `action` | `next\|previous\|submit` | Yes | Adaptive action | | `page` | int | Yes | One-based index of current page. | | `seconds` | int | Yes | Number of seconds spent on the attempt. | | `submission.partid` | string | Yes | Partid of question | | `submission.answer` | string | Yes | Question answer | ## Response **Response body (JSON):** ```json { "attempt or submission": {} } ``` ### attempt or submission Return either an attempt or submission as specified in GetAttempt and SubmitAttemptAnswers. ## See Also - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) - [SubmitAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SubmitAttemptAnswers.md) --- # GetObjectiveList This command gets a list of learning objectives. Each of setid, guid, and parent are optional parameters; however, you must specify exactly one of them to retrieve any objectives. ## Request **Method:** GET **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getobjectivelist` | | `setid` | id | No | The ID of the set to list objectives for. | | `guid` | string | No | A bar-separated list of objective guids to get. | | `parent` | guid | No | The parent objective to list child objectives for. | | `grades` | enum-GradeLevels | No | An optional bitwise OR of the GradeLevels enumeration used to filter the list of learning objectives. | | `subject` | string | No | An optional subject filter. GetObjectiveList returns only objectives that have the specified subject. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "objectives": { "objective": [ { "guid": "guid", "id": "string", "title": "string", "setid": "id", "reference": "string", "grades": "GradeLevels", "subject": "string", "parent": "guid", "creationdate": "datetime", "creationby": "id", "modifieddate": "datetime", "modifiedby": "id", "version": "string", "data": {} } ] } } } ``` ### objectives #### objective | Attribute | Type | Description | |-----------|------|-------------| | `guid` | guid | The unique identifier of the learning objective. | | `id` | string | The ID of the learning objective assigned by the source of the objective set. | | `title` | string | The title or description of the learning objective. | | `setid` | id | The ID of the learning objective set this learning objective belongs to. | | `reference` | string | A field reserved to identify the objective in other systems such as ASN. | | `grades` | [GradeLevels](https://api.agilixbuzz.com/docs/entry/Enum/GradeLevels.md) | An bitwise OR of the GradeLevels enumeration that indicates the applicable grades for this learning objective. | | `subject` | string | The academic subject this learning objective relates to. | | `parent` | guid | The unique identifier of the parent objective. | | `creationdate` | datetime | The date the objective was created. | | `creationby` | id | The ID of the user that created the objective. | | `modifieddate` | datetime | The date the objective was last modified. | | `modifiedby` | id | The ID of the user that last modified the objective. | | `version` | string | The version of the objective. | ##### data *(optional)* Optional free-form structured data. See Free Form Data for more details. ## Example This example gets the list of learning objectives for the objective set with ID 745770 for grades 9, 10, 11 and 12 in the "science" subject. **URL:** `?cmd=getobjectivelist&setid=745770&grades=30720&subject=science` **Response** (code: `OK`): ```json { "response": { "code": "OK", "objectives": { "objective": [ { "guid": "881f003e-a204-617e-a596-624386a19a3b", "id": "D100013C", "title": "Alabama Course of Study: Science", "setid": "745770", "reference": "http://purl.org/ASN/resources/D100013C", "grades": "32764", "subject": "Science", "creationdate": "2011-10-14T19:58:05.073Z", "creationby": "2", "modifieddate": "2011-10-14T19:58:05.073Z", "modifiedby": "2", "version": "1", "data": { "url": { "$value": "http://purl.org/ASN/resources/D100013C" } } }, { "guid": "239bd83f-0064-95b7-49fb-8d8167489a94", "id": "D1000255", "title": "Alabama Course of Study: Science", "setid": "745770", "reference": "http://purl.org/ASN/resources/D1000255", "grades": "32764", "subject": "Science", "creationdate": "2011-10-14T19:58:05.073Z", "creationby": "2", "modifieddate": "2011-10-14T19:58:05.073Z", "modifiedby": "2", "version": "1", "data": { "url": { "$value": "http://purl.org/ASN/resources/D1000255" }, "description": { "$value": "The Alabama Course of Study: Science (Bulletin 2005, No. 20) provides the framework for the K-12 science education program in Alabama’s public schools. Content standards in this document are minimum and required (Code of Alabama, 1975, §16-35-4). They are fundamental and specific but not exhaustive. When developing a local curriculum, each school system may include additional content standards to address specific local needs or focus on local resources. Implementation guidelines, resources, and activities may also be added" } } }, { "guid": "f8785335-beec-66b9-85a0-f984abdeb574", "id": "S1000060", "title": "24. Identify animal species by comparing similarities in molecular, anatomical, and fossil evidence.", "setid": "745770", "reference": "http://purl.org/ASN/resources/S1000060", "grades": "30720", "subject": "Science", "parent": "cbbe1d82-6cd3-fdde-ae3c-48463a96ae61", "creationdate": "2011-10-14T19:58:05.073Z", "creationby": "2", "modifieddate": "2011-10-14T19:58:05.073Z", "modifiedby": "2", "version": "1", "data": { "url": { "$value": "http://purl.org/ASN/resources/S1000060" } } }, { "guid": "8753b419-205c-083a-ee9d-12e4d74f3e4b", "id": "S10001D2", "title": "18. Relate cellular functions to specialized structures in cells and tissues of roots, stems, leaves, and flowers.\n
  • Transport of materials
    • \n
  • Waste disposal
    • \n
  • Protein synthesis
    • \n
  • Energy capture and release
    • \n
  • Information feedback
    • \n
  • Movement
    • \n
  • Homeostasis
\n", "setid": "745770", "reference": "http://purl.org/ASN/resources/S10001D2", "grades": "30720", "subject": "Science", "parent": "29af9e39-0688-1180-72fd-2adbac2f86b3", "creationdate": "2011-10-14T19:58:05.073Z", "creationby": "2", "modifieddate": "2011-10-14T19:58:05.073Z", "modifiedby": "2", "version": "1", "data": { "url": { "$value": "http://purl.org/ASN/resources/S10001D2" } } } ] } } } ``` ## See Also - [GradeLevels](https://api.agilixbuzz.com/docs/entry/Enum/GradeLevels.md) - [ListObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/ListObjectiveSets.md) - [GetObjectiveSubjectList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSubjectList.md) --- # GetObjectiveMapList This command gets the list of maps defined in an objective map set. ## Request **Method:** GET **Rights:** ReadObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getobjectivemaplist` | | `setid` | id | Yes | The ID of the set for which to list objective maps. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "maps": { "map": [ { "guid": "guid", "correlation": "guid", "weight": "double" } ] } } } ``` ### maps #### map | Attribute | Type | Description | |-----------|------|-------------| | `guid` | guid | The unique identifier of the learning objective. | | `correlation` | guid | The unique identifier of the correlated learning objective. | | `weight` | double | The weight of the mapping. | ## Example This example gets the list of learning objectives mappings for the objective set with ID 750297. **URL:** `?cmd=getobjectivemaplist&setid=750297` **Response** (code: `OK`): ```json { "response": { "code": "OK", "maps": { "map": [ { "guid": "4bebfa5f-e5d0-49c6-99a9-0048be0d0170", "correlation": "f2d5feab-72f1-4294-8325-375ff86f5531", "weight": 1 }, { "guid": "4bebfa5f-e5d0-49c6-99a9-0048be0d0170", "correlation": "6ba8a57f-df65-4adf-a69b-6d66b631c04b", "weight": 1 }, { "guid": "88adefd0-6378-4967-9caa-0079a4ba36d7", "correlation": "dfe4cb60-be91-459b-8275-0538f76a2099", "weight": 1 }, { "guid": "88adefd0-6378-4967-9caa-0079a4ba36d7", "correlation": "82698bb9-73c8-4701-bc19-1ddf7819e664", "weight": 1 }, { "guid": "88adefd0-6378-4967-9caa-0079a4ba36d7", "correlation": "235819a2-2d5c-4275-b730-21705099aff4", "weight": 1 } ] } } } ``` ## See Also - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveMaps.md) - [GetObjectiveList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveList.md) - [ListObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/ListObjectiveSets.md) - [GetObjectiveSubjectList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSubjectList.md) - [PutObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/PutObjectiveMaps.md) --- # GetObjectiveMastery This command gets objective mastery report data for the specified entity using student scores from objective-aligned items and questions. ## Request **Method:** GET **Rights:** ReadGradebook@entityid when entityid refers to a course or section; ReadEnrollment@entityid when entityid refers to an enrollment; ReadCourse@courseid where entityid refers to a group and courseid is the group's owner. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getobjectivemastery` | | `entityid` | id | Yes | Course, section, group or enrollment ID for which to get objective mastery report data. | | `setid` | id | No | An objective map set ID that maps entityid's objectives to some other objectives. GetObjectiveMastery translates objectives from entityid to the correlated objectives in setid, returns the correlated objective guid, id, and title in the response objectives, and for each mapped-to objective includes a sources element that identifies the source objectives. If entityid contains an objective that has no corresponding mapping in setid, GetObjectiveMastery returns the original, unmapped objective. | | `guid` | string | No | Vertical-bar-separated list of learning objective GUIDs for which to get mastery. If omitted, returns mastery for all objectives defined for entityid. If you specify an objective map set in setid, guids in this list should be the mapped-to guids from setid, not the original guids in entityid. | | `zerounscored` | boolean | No | Indicates that the server should calculate the report data by substituting a score of zero for unscored items. | | `mappedonly` | boolean | No | Indicates that the server should not return information about learning objectives not included in the map specified by setid. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "objectives": { "objective": [ { "guid": "guid", "id": "string", "title": "string", "coverage": "int", "attempts": "int", "possible": "double", "achieved": "double", "unweightedaverage": "double", "threshold": "double", "date": "datetime", "letter": "string", "fcoverage": "int", "fattempts": "int", "fpossible": "double", "fachieved": "double", "funweightedaverage": "double", "fthreshold": "double", "fdate": "datetime", "fletter": "string", "sources": { "guid": [ { "$value": "guid" } ] } } ] } } } ``` ### objectives #### objective | Attribute | Type | Description | |-----------|------|-------------| | `guid` | guid | The GUID of the objective. | | `id` | string | *(optional)* If this objective is a mapped-to objective from setid, id is the mapped-to objective's ID; otherwise, id is omitted. | | `title` | string | *(optional)* If this objective is a mapped-to objective from setid, title is the mapped-to objective's title; otherwise, title is omitted. | | `coverage` | int | The number of items related to the objective. | | `attempts` | int | The number of gradable attempts contributing to the achieved mastery-level calculation. | | `possible` | double | The number of weighted points possible for the objective. | | `achieved` | double | The number of weighted points achieved for the objective. | | `unweightedaverage` | double | The unweighted average of the scores for the objective. | | `threshold` | double | The percent that demonstrates whether students have mastered a learning objective. | | `date` | datetime | The date of the last score the student received that was related to the learning objective. | | `letter` | string | *(optional)* The letter grade from the objective mastery grade table. | | `fcoverage` | int | *(optional)* The number of formative items related to the objective. | | `fattempts` | int | *(optional)* The number of formative attempts contributing to the fachieved formative-mastery-level calculation. | | `fpossible` | double | *(optional)* The number of formative weighted points possible for the objective. | | `fachieved` | double | *(optional)* The number of formative weighted points achieved for the objective. | | `funweightedaverage` | double | *(optional)* The unweighted average of the formative scores for the objective. | | `fthreshold` | double | The percent that demonstrates whether students have mastered a learning objective for a formative assessment. | | `fdate` | datetime | The date of the last score the student received that was related to the learning objective for a formative assessment. | | `fletter` | string | *(optional)* The letter grade from the objective mastery grade table. | ##### sources *(optional)* If this objective is a mapped-to objective from setid, sources contains the GUID(s) of the source objectives that mapped to this objective. ###### guid ## Example This example retrieves the objective mastery for the course with ID 268948. **URL:** `?cmd=getobjectivemastery&entityid=268948` **Response** (code: `OK`): ```json { "response": { "code": "OK", "objectives": { "objective": [ { "guid": "3718f993-2b36-4fb5-bbe0-288b31039334", "id": "A1", "title": "Objective A1: Concepts and Principles", "coverage": "3", "attempts": "5", "possible": "100", "achieved": "50", "unweightedaverage": "0.5" }, { "guid": "0010ca26-4954-4501-9bbc-adac5831b758", "id": "A2", "title": "Objective A2: Theory and Rhetoric", "coverage": "2", "attempts": "4", "possible": "100", "achieved": "25", "unweightedaverage": "0.25" }, { "guid": "ee2dc06a-344f-469b-9eca-4e1efd81a280", "id": "A3", "title": "Objective A3: Practical Application", "coverage": "2", "attempts": "4", "possible": "100", "achieved": "50", "unweightedaverage": "0.5" } ] } } } ``` ## See Also - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) - [PutObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/PutObjectiveMaps.md) --- # GetObjectiveSet2 This command gets information for a objective set or objective map set. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getobjectiveset2` | | `setid` | id | Yes | ID of the objective set to get. | | `select` | string | No | Comma-separated list of which data to return. By default, *GetObjectiveSet2* returns only the objective set node. Possible values are: - *data* - Includes the set's free-form structured data in the response. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "set": { "data": {}, "domain": { "data": {} } } } } ``` ### set This node conforms to the Objective Set format. #### data *(optional)* Optional free-form structured data. See Free-form Data for more details. #### domain *(optional)* This node conforms to the Domain format. ##### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. ## Example This example assumes the set with ID 6050 already exists. **URL:** `?cmd=getobjectiveset2&setid=6050` **Response** (code: `OK`): ```json { "response": { "code": "OK", "set": { "id": "6050", "name": "State Standards", "domainid": "2829", "reference": "state-standards", "guid": "a0a3e20a-ce06-4f80-a61a-7d446c859753", "owner": "State", "flags": "0", "creationdate": "2011-03-21T16:00:14.43Z", "creationby": "334", "modifieddate": "2011-03-21T16:00:14.43Z", "modifiedby": "334", "version": "1" } } } ``` ## See Also - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [UpdateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/UpdateObjectiveSets.md) --- # GetObjectiveSubjectList This command gets the list of subjects covered by the learning objectives for an objective set. Each of setid, guid, and parent are optional parameters; however, you must specify exactly one of them to retrieve any subjects. ## Request **Method:** GET **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getobjectivesubjectlist` | | `setid` | id | No | The ID of the set to list subjects for. | | `guid` | string | No | A bar-separated list of objective guids to list subjects for. | | `parent` | guid | No | The ID of the parent objective from which to get child objectives to list subjects for. | | `grades` | enum-GradeLevels | No | An optional, bitwise OR of GradeLevels flags. Only subjects from objectives in the specified grades are returned. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "subjects": { "subject": [ { "subject": "string" } ] } } } ``` ### subjects #### subject | Attribute | Type | Description | |-----------|------|-------------| | `subject` | string | The subject. | ## Example This example gets the list of subjects for the objective set "MNC" for grades 9, 10, 11 and 12. **URL:** `?cmd=getobjectivesubjectlist&setid=MNC&grades=30720` **Response** (code: `OK`): ```json { "response": { "code": "OK", "subjects": { "subject": [ { "subject": "Language Arts" }, { "subject": "Mathematics" }, { "subject": "Science" }, { "subject": "Social Studies" } ] } } } ``` ## See Also - [GradeLevels](https://api.agilixbuzz.com/docs/entry/Enum/GradeLevels.md) - [GetObjectiveList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveList.md) - [ListObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/ListObjectiveSets.md) --- # GetPasswordLoginAttemptHistory Gets the record of password login attempts for the specified user account. Only up to the last 1000 records are ever returned. ## Request **Method:** GET **Rights:** ReadUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpasswordloginattempthistory` | | `userid` | id | No | The ID of the user to get the password login attempt history for. | | `earliestrecordtoreturn` | datetime | No | The datetime of the earliest record to return. Defaults to one week ago. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "passwordloginattemptrecords": { "passwordloginattemptrecord": [ { "userid": "id", "attempttime": "datetime", "attemptresult": "string", "trackinginfo": "string" } ] } } } ``` ### passwordloginattemptrecords #### passwordloginattemptrecord | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The ID of the user for this record. | | `attempttime` | datetime | The date-time (in UTC) when the login attempt was made. | | `attemptresult` | string | The result of this login attempt. Currently limited to: Failure, Success, LockoutStart, LockoutReset. | | `trackinginfo` | string | A string containing information about the location from which the login attempt originated, including the IP address and user-agent as best as the server could determine them. | ## Example This example gets the password login attempt history for user 390843 for the past week. **URL:** `?cmd=getpasswordloginattempthistory&userid=390843` **Response** (code: `OK`): ```json { "response": { "code": "OK", "passwordloginattemptrecords": { "passwordloginattemptrecord": [ { "userid": "390843", "attempttime": "2016-03-21T16:00:14.43Z", "attemptresult": "Failure", "trackinginfo": "254.58.23.94(35.62.5.124):Buzz:Mozilla/5.0 (Android; Mobile; rv:13.0) Gecko/13.0 Firefox/13.0" }, { "userid": "390843", "attempttime": "2016-03-21T15:15:12.59Z", "attemptresult": "Success", "trackinginfo": "254.58.23.97(35.62.5.124):Buzz:Mozilla/5.0 (Linux; Android 4.4.2); Nexus 5 Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/33.0.1750.117 Mobile Safari/537.36 OPR/20.0.1396.72047" } ] } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [ForcePasswordChange](https://api.agilixbuzz.com/docs/entry/Command/ForcePasswordChange.md) - [GetEffectivePasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/GetEffectivePasswordPolicy.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # GetPasswordQuestion This command gets the question to ask a user who has forgotten their password. ## Request **Method:** GET **Rights:** None **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpasswordquestion` | | `username` | string | Yes | The userspace/username to get the password question for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "question": { "user": "string" } } } ``` ### question | Attribute | Type | Description | |-----------|------|-------------| | `user` | string | Username to whom the question applies. | ## Example This example **URL:** `?cmd=getpasswordquestion&username=myschool/student1` **Response** (code: `OK`): ```json { "response": { "code": "OK", "question": { "user": "student1", "$value": "What was the name of your first dog?" } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [ResetPassword](https://api.agilixbuzz.com/docs/entry/Command/ResetPassword.md) --- # GetPeerResponse This command gets a peer's response to a student's submission. A response is a zip-compressed file that can contain comments, rubric data, likert data, and supporting files. If the peer response has no supporting files, you can retrieve just the Response XML. ## Request **Method:** GET **Rights:** User to whom the peer response applies or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpeerresponse` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this peer response belongs; i.e., identifies the user whose submission was reviewed. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within the zip-compressed peer response. For example, specify a filepath to retrieve an attachment from within the peer response. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this peer response belongs. | | `peerid` | id | Yes | ID of the peer who responsed or reviewed their peer's submission. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Response data from within the zip-compressed peer response. Equivalent to the now obsolete value xml. - **file** - Returns a single file from within the zip-compressed peer response. You must also specify filepath to identify which file to retrieve. - **zip** - Returns the entire zip-compressed peer response containing the file meta.xml, which is a Response, and any supporting files. | | `version` | int | No | Version of the peer response to retrieve. Omit version to retrieve the most recent peer response. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the response by a peer with enrollment ID 4901 for the item with ID "assign12" for enrollment with ID 4317. **URL:** `?cmd=getpeerresponse&enrollmentid=4317&itemid=assign12&packagetype=data&peerid=4901` **Response:** ```json { "response": { "$value": "The data from within the zip-compressed response" } } ``` ## See Also - [Response](https://api.agilixbuzz.com/docs/entry/Schema/Response.md) - [GetPeerResponseList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponseList.md) - [GetPeerReviewList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerReviewList.md) - [PutPeerResponse](https://api.agilixbuzz.com/docs/entry/Command/PutPeerResponse.md) --- # GetPeerResponseList This command lists peer's responses to the specified student's submission to a course item. ## Request **Method:** POST **Rights:** User referred to by enrollmentid or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpeerresponselist` | | `enrollmentid` | id | Yes | Enrollment ID of the user whose submission was responded to by peers. | | `itemid` | string | Yes | ID of the item (in the course manifest) that was responded to. | | `select` | string | Yes | Comma-separated list of which data to return. By default, *GetPeerResponseList* does not return any of the additional nodes. Possible values are: - *user* - Includes the user node. - *response* - Includes the response node. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "peerresponses": { "peerresponse": [ { "peerid": "id", "responseversion": "int", "scoreddate": "datetime", "scoredversion": "int", "user": { "userid": "string", "firstname": "string", "lastname": "string" }, "response": {} } ] } } } ``` ### peerresponses #### peerresponse | Attribute | Type | Description | |-----------|------|-------------| | `peerid` | id | Enrollment ID of the peer user who provided the peer response. | | `responseversion` | int | The version of this peer response. | | `scoreddate` | datetime | The date of this peer response. | | `scoredversion` | int | The version of the student submission that this peer response applies to. | ##### user *(optional)* Information about the peer user. | Attribute | Type | Description | |-----------|------|-------------| | `userid` | string | The peer's user ID. | | `firstname` | string | The peer's first name. | | `lastname` | string | The peer's last name. | ##### response *(optional)* The peer's response. This node conforms to the Response format. ## See Also - [GetPeerResponse](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponse.md) - [GetPeerReviewList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerReviewList.md) --- # GetPeerReviewList This command lists peers that may be reviewed by the specified enrollment user. If the item does not have PeerAssessmentOnly set on the peerreviewflags, and the enrollment user has already reviewed a peer's submission for the specified item, the returned data includes information about the existing peer review. ## Request **Method:** GET **Rights:** the current signed-on user is enrollment.userid or ReadGradebook@enrollment.courseid where enrollment is the enrollment referred to by peerid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpeerreviewlist` | | `peerid` | id | Yes | Enrollment ID of the user who is the peer reviewer. | | `itemid` | string | Yes | ID of the item (in the course manifest) to peer review. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "enrollmentid": "id", "firstname": "string", "lastname": "string", "responseversion": "int", "scoreddate": "datetime", "scoredversion": "int", "submittedversion": "int" } ] } } } ``` ### enrollments #### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | Enrollment ID of the peer user whose submissions can be reviewed. | | `firstname` | string | First name of the peer user. | | `lastname` | string | Last name of the peer user. | | `responseversion` | int | *(optional)* Version, if any, of the user's current review for this peer. | | `scoreddate` | datetime | *(optional)* Date, if any, when the input enrollmentid user submitted a review for this peer. | | `scoredversion` | int | *(optional)* Version, if any, of this peer's submission that the input enrollmentid user has reviewed. | | `submittedversion` | int | *(optional)* Version, if any, of the most recent peer submission that can be reviewed. | ## See Also - [GetPeerResponse](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponse.md) - [GetPeerResponseList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponseList.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [PutPeerResponse](https://api.agilixbuzz.com/docs/entry/Command/PutPeerResponse.md) --- # GetPersonas This command gets the list of personas associated with a user. ## Request **Method:** GET **Rights:** ReadUser@user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getpersonas` | | `userid` | id | No | ID of the user to get personas for. If you omit userid, the list of personas is for the current signed-on user. | | `domainid` | id | No | Optional ID of a domain. If specified, the command only returns personas associated with that domain | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "personas": { "persona": [ {} ] } } } ``` ### personas #### persona A Persona. ## Example This example assumes the user with ID 621 already exists. **URL:** `?cmd=getpersonas&userid=621` **Response** (code: `OK`): ```json { "response": { "code": "OK", "personas": { "persona": [ { "$value": "Teacher" } ] } } } ``` ## See Also - [Persona](https://api.agilixbuzz.com/docs/entry/Enum/Persona.md) --- # GetProfilePicture This command gets binary content for the user's profile picture if it exists. If the user's profile references an absolute URL, then this command redirects to that URL through an HTTP 302. If the user's profile picture is not configured, a default image will be used. The default image is configurable in the Buzz settings. ## Request **Method:** GET **Rights:** ReadEnrollment@enrollmentid,ReadUser@enrollment.user,Participate|ReadCourse@enrollment.course, user is enrolled in the same course as the target user, or user is the target user, or user is the system admin user or BusyBee user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getprofilepicture` | | `entityid` | id | Yes | The user or enrollment ID that contains the profile picture. | | `usedefault` | bool | No | Whether or not to use the default URL if the profile picture isn't configured. If false, and the profile picture does not exist, this command returns an HTTP 404. The default value is true. | ## Response **Content-Type:** package-mime-type **Content-Length:** package-length ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | Only the first time an externally hosted profile picture is fetched: the image is re-hosted locally and the user record is updated to point at the local copy. This event has no userId, because the system performs the change rather than the caller. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **URL:** `?cmd=getprofilepicture&entityid=4317` ## See Also - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) - [UserData](https://api.agilixbuzz.com/docs/entry/Schema/UserData.md) --- # GetQuestion This command gets one question from a course. ## Request **Method:** GET **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getquestion` | | `entityid` | id | Yes | ID of the course that owns the question. | | `questionid` | string | Yes | ID of the question to get. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "question": { "questionid": "id", "partial": "boolean", "resourceentityid": "id", "round": "boolean", "schema": "int", "score": "double", "version": "string" } } } ``` ### question See Question Schema for a detailed description of the returned XML for a question | Attribute | Type | Description | |-----------|------|-------------| | `questionid` | id | ID of the question. | | `partial` | boolean | *(optional)* True if partial credit is allowed for this question; otherwise false. The default is false. | | `resourceentityid` | id | ID of the entity that owns the question. | | `round` | boolean | *(optional)* True to round partial scores down to the next whole number, otherwise false. The default is false. | | `schema` | int | All newly created questions should have value 2. (Schema 1 is an obsolete schema supported only for backwards compatibility.) | | `score` | double | *(optional)* The points possible for this question. If omitted, uses the assessment default score. | | `version` | string | The version of the question. | ## Example This example gets question 2f58ddabe0e343eda629b405759be802 from the course whose ID is 111963. **URL:** `?cmd=getquestion&entityid=111963&questionid=00d025a61e6e46f888245f887324cecb` **Response** (code: `OK`): ```json { "response": { "code": "OK", "question": { "questionid": "00d025a61e6e46f888245f887324cecb", "version": "2", "resourceentityid": "111963", "schema": "2", "partial": false, "answer": { "value": { "$value": "1" } }, "body": { "$value": "Is a traffic light red, yellow, and green?" }, "interaction": { "type": "choice", "choice": [ { "id": "1", "body": { "$value": "Yes" } }, { "id": "2", "body": { "$value": "No" } } ] } } } } ``` ## See Also - [Question Schema](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [GetQuestionList](https://api.agilixbuzz.com/docs/entry/Command/GetQuestionList.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) --- # GetQuestionList > **Deprecated** — use [ListQuestions](https://api.agilixbuzz.com/docs/entry/Command/ListQuestions.md) instead. This command lists one or more questions in a course. ## Request **Method:** GET **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getquestionlist` | | `entityid` | id | Yes | ID of the course that owns the questions. | | `questionid` | idlist | No | Optional, bar-separated ID list of questions to get. If omitted, GetQuestionList returns all questions for the specified entityid. | | `query` | string | No | Optional query used to filter the list of questions to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, allversions is ignored. | | `count` | int | No | Thr max number of questions to return when using a query. | | `allversions` | boolean | No | Specify true to retrieve metadata for all versions of the specified questions; or specify false to retrieve only the latest version's metadata. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": { "code": "code", "message": "string", "question": [ { "questionid": "id", "modifieddate": "datetime", "partial": "boolean", "resourceentityid": "id", "round": "boolean", "schema": "int", "score": "double", "version": "string" } ] } } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### question See Question Schema for a detailed description of the returned XML for a question | Attribute | Type | Description | |-----------|------|-------------| | `questionid` | id | ID of the question. | | `modifieddate` | datetime | Last modified date and time of the question. | | `partial` | boolean | *(optional)* True if partial credit is allowed for this question; otherwise false. The default is false. | | `resourceentityid` | id | ID of the entity from which this question retrieves its resources, such as images. resourceentityid is different than entityid when this question is in a base course and entityid refers to a course derived from the base. See CopyCourses for more details about derivative courses. | | `round` | boolean | *(optional)* True to round partial scores down to the next whole number, otherwise false. The default is false. | | `schema` | int | All newly created questions should have value 2. (Schema 1 is an obsolete schema supported only for backwards compatibility.) | | `score` | double | *(optional)* The points possible for this question. If omitted, uses the assessment default score. | | `version` | string | The version of the question. | ## Example This example lists questions from the course whose ID is 2838. **URL:** `?cmd=getquestionlist&entityid=2838` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": { "code": "OK", "question": [ { "questionid": "2f58ddabe0e343eda629b405759be802", "version": "1", "schema": "2", "partial": "true", "round": "true", "answer": {}, "body": { "$value": "Match the animals with their sounds." }, "interaction": { "type": "match", "flags": "2", "choice": [ { "id": "1", "body": { "$value": "dog" }, "answer": { "$value": "woof" } }, { "id": "2", "body": { "$value": "cat" }, "answer": { "$value": "meow" } }, { "id": "3", "body": { "$value": "cow" }, "answer": { "$value": "moo" } } ] } }, { "questionid": "44cead279c0f46dcab0c2d4ff1ce5c67", "version": "1", "schema": "2", "partial": "false", "groups": { "group": { "$value": "Group A" } }, "answer": { "value": { "$value": "1" } }, "body": { "$value": "Is this a multiple choice question?" }, "interaction": { "type": "choice", "flags": "2", "choice": [ { "id": "1", "body": { "$value": "Yes" } }, { "id": "2", "body": { "$value": "No" } } ] } } ] } } } } ``` ## See Also - [Question Schema](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) --- # GetQuestionScores This command scores one or more question submissions. The question and student answer (submission) are passed in as the POST data of this command. GetQuestionScores computes the score given the inputs and returns it; no data is read or updated on the server. ## Request **Method:** POST **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getquestionscores` | **Request body (JSON):** ```json { "request": { "questions": { "question": [ {} ] }, "submission": { "type": "attempt", "submission": [ { "type": "question", "answer": {}, "attemptquestion": {} } ] } } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `questions.question` | object | Yes | See Question for a detailed description of the XML for a question. | | `submission.type` | `attempt` | Yes | | | `submission.submission.type` | `question` | Yes | | | `submission.submission.answer` | object | Yes | Student answer | | `submission.submission.attemptquestion` | object | Yes | This element conforms to the Attempt Question format | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "scores": { "score": [ { "pointspossible": "double", "pointscomputed": "double" } ] } } } ``` ### scores #### score | Attribute | Type | Description | |-----------|------|-------------| | `pointspossible` | double | The points possible for this question. | | `pointscomputed` | double | *(optional)* The points computed for this question, given the submission. | ## Example This example get the score for a question and response. **URL:** `?cmd=getquestionscores` **Request body:** ```json { "request": { "questions": { "question": [ { "schema": "2", "partial": true, "answer": { "value": [ { "$value": "2" }, { "$value": "3" } ] }, "body": { "$value": "What are the prime factor of 6" }, "interaction": { "type": "answer", "choice": [ { "id": "1", "body": { "$value": "1" } }, { "id": "2", "body": { "$value": "2" } }, { "id": "3", "body": { "$value": "3" } }, { "id": "4", "body": { "$value": "4" } }, { "id": "5", "body": { "$value": "5" } }, { "id": "6", "body": { "$value": "6" } } ] } } ] }, "submission": { "type": "attempt", "submission": [ { "type": "question", "partid": "1", "answer": { "$value": "2,3,6" }, "attemptquestion": { "attemptpossible": { "$value": "4" }, "attemptchoice": [ { "id": "1" }, { "id": "2" }, { "id": "3" }, { "id": "4" }, { "id": "5" }, { "id": "6" } ] } } ] } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "scores": { "score": [ { "pointspossible": 4, "pointscomputed": 2 } ] } } } ``` ## See Also - [Question](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) --- # GetQuestionStats This command gets system-wide statistics about a particular question. ## Request **Method:** GET **Rights:** Authenticated user with ReadGradebook@entityid on the owning course, or UpdateDomain on the root domain. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getquestionstats` | | `entityid` | id | Yes | Course ID that actually owns the question. If the question is linked from another course or exists in a course derived from a base course, entityid should be the base course ID, not the derived course ID or the linking course ID. | | `questionid` | string | Yes | Path that identifies the question resource. | | `version` | string | No | Optional version of the question for which to get statistics. If omitted, the command returns information for all versions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "question": { "count": "int", "averageachieved": "double", "averagepossible": "double" } } } ``` ### question | Attribute | Type | Description | |-----------|------|-------------| | `count` | int | The number of attempts associated with the question. | | `averageachieved` | double | *(optional)* The average points achieved for all attempts of this question. | | `averagepossible` | double | *(optional)* The average points possible for all attempts of this question. | ## Example Retrieves the question stats for the question with path "2f58ddabe0e343eda629b405759be802" for the course with ID 77838. **URL:** `?cmd=getquestionstats&entityid=77838&questionid=2f58ddabe0e343eda629b405759be802` **Response** (code: `OK`): ```json { "response": { "code": "OK", "question": { "count": "5", "averagepossible": "2.8", "averageachieved": "1.4" } } } ``` ## See Also - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) - [Question](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) --- # GetRawPasswordPolicy Gets the raw password policy stored on the specified domain, exactly as stored: no values are inherited from ancestor domains and no persona restrictions are merged in. When a persona is specified, the persona-specific policy stored on the domain is returned instead of the base policy. When the domain has no policy of the requested kind stored on it, the response is OK with no passwordpolicy element at all - this is the normal result the first time a policy is edited at a given level. This function always bypasses any cache, assuming that this is being used to display the policy for editing and subsequent update using the SetPasswordPolicy command. To get the policy that is actually in effect (with inheritance and persona merging applied), use GetEffectivePasswordPolicy instead. ## Request **Method:** GET **Rights:** ControlDomain@domainid - the same right required to write the policy back with SetPasswordPolicy, including for the caller's own domain. Callers without administrative rights who need the policy that applies to them should use GetEffectivePasswordPolicy instead. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrawpasswordpolicy` | | `domainid` | id | Yes | The ID of the domain to get the password policy for. Required. | | `persona` | string | No | The persona name. When specified, the persona-specific policy stored on the domain is returned instead of the base policy (the two are stored separately and this command never merges them). | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "passwordpolicy": { "domainid": "id", "hashalgorithmfornewhashes": "string", "maxage": "timespan", "loginattempthistoryretentiontime": "timespan", "lockoutaftertries": "int", "lockoutduration": "timespan", "lockoutstaleaccountsafter": "timespan", "minimumlength": "int", "minimumcharacterclasses": "int", "recycletime": "timespan", "complexityenforcement": "PasswordPolicyEnforcement", "additionalcontextwords": "string", "minimumentropy": "int", "entropyenforcement": "PasswordPolicyEnforcement", "pwnenforcement": "PasswordPolicyEnforcement", "mfaenforcement": "PasswordPolicyEnforcement" } } } ``` ### passwordpolicy *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `domainid` | id | The ID of the domain the password policy was read from - always the requested domain, since this command never consults ancestor domains. The entire passwordpolicy element is absent when the requested domain has no policy of the requested kind stored on it. | | `hashalgorithmfornewhashes` | string | The hash algorithm that will be used for newly-set passwords. Currently always the system default (Pbkdf2Sha256Variable); not configurable through SetPasswordPolicy. | | `maxage` | timespan | *(optional)* The maximum time a password can be used for accessing the system. After a password reaches this age, it can only be used to set a new password. The default behavior is not to expire passwords (forever). | | `loginattempthistoryretentiontime` | timespan | *(optional)* The length of time password login attempts are recorded (the longest of what is required by this, what is required by the lockout rules, or the system-wide minimum is what will be retained). The default is none, which will use the system-wide minimum. GetPasswordLoginAttemptHistory may be used to retrieve this history. | | `lockoutaftertries` | int | *(optional)* The maximum number of times a user can enter the wrong password before their account is locked out, requiring an administrator to unlock it. The default behavior is not to lock out accounts. | | `lockoutduration` | timespan | *(optional)* The length of time an account remains locked out after a lockout occurs. The default is forever, but this only applies if a lockout count is set. An administrator must call ResetLockout | | `lockoutstaleaccountsafter` | timespan | *(optional)* A duration of time after the last login (or after account creation if no logins have occurred) after which the account will be locked out just as if too many bad passwords were entered, but even if account lockout is not configured. | | `minimumlength` | int | The minimum number of characters required for an acceptable password. Defaults to one character (1) when the stored policy does not specify it. | | `minimumcharacterclasses` | int | The minimum number of character classes (a-z, A-Z, 0-9, other) required for an acceptable password. Defaults to no restriction (0) when the stored policy does not specify it. | | `recycletime` | timespan | *(optional)* The amount of time to store old passwords and prevent their reuse. The default behavior is not to block password reuse (zero time). | | `complexityenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | How to handle situations where the password does not meet the policy for the minimum length, minimum character classes, and recycle time conditions. Defaults to None when the stored policy does not specify it. | | `additionalcontextwords` | string | *(optional)* A comma-separated list of strings associated with the domain that will lower the entropy score when they are used as any part of the password. This should include parts of the names of the hostname of the website as well as parts of the name of the school(s) this policy applies to. | | `minimumentropy` | int | *(optional)* The minimum number of bits of estimated entropy for new passwords, adjusting for patterns commonly used by users to just meet old-style complexity requirements, such as capitalizing a single character, substituting the letter oh with zero, adding a 1 or ! at the end of a password, including the website name, using family names, using common words, etc. This is a "volatile" property, as the implementation may change at any time, causing password that passed before the implementation change to begin failing after the change, without any change to the policy itself. | | `entropyenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* How to handle situations where the password does not meet the specified minimum entropy. | | `pwnenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* Whether and how to enforce passwords found in publicly-available data breaches. | | `mfaenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | *(optional)* Whether and how to enforce one-time (TOTP) token requirements in addition to the password for accounts subject to this policy. If required but not yet established, the user will be required to setup MFA after logging in with their password but before doing anything else. | ## Example This example gets the raw base password policy for domain 205218. **URL:** `?cmd=getrawpasswordpolicy&domainid=205218` **Response** (code: `OK`): ```json { "response": { "code": "OK", "passwordpolicy": { "minimumlength": "1", "minimumcharacterclasses": "1", "maxage": "PT30D", "complexityenforcement": "BlockOnUse" } } } ``` ## See Also - [PasswordPolicyEnforcement Enum](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [ForcePasswordChange](https://api.agilixbuzz.com/docs/entry/Command/ForcePasswordChange.md) - [GetPasswordLoginAttemptHistory](https://api.agilixbuzz.com/docs/entry/Command/GetPasswordLoginAttemptHistory.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [SetPasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/SetPasswordPolicy.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # GetRecentPosts This command returns recent posts to discussion boards, wikis, blogs and journals that have not been marked as viewed. ## Request **Method:** GET **Rights:** Participate|ReadCourse|UpdateCourse|ReadGradebook|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid referenced by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrecentposts` | | `enrollmentid` | id | Yes | Enrollment ID for course to get recent posts for. | | `date` | datetime | No | Optional date to filter posts by. Returns posts that are posted on or after this date. If omitted, GetRecentPosts returns posts for the last 7 days. | | `rows` | int | No | Optional number of posts to return. The default is 20 rows. | | `userid` | id | No | Optional user to evaluate unread/viewed state for. Because the "not viewed" state of a post is per-user, by default posts are returned relative to the calling user. An administrator may pass another user's id to retrieve that user's unread posts directly (for example a student's), rather than proxying in as that user. Requires ReadUser rights on the specified user. | | `manifestonly` | boolean | No | Whether to only show recent posts for items in the manifest. The default is *true* . | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "posts": { "post": [ { "entityid": "id", "coursetitle": "string", "sectiontitle": "string", "term": "string", "itemid": "string", "itemtitle": "string", "itemtype": "string", "groupid": "string", "messageid": "string", "messagetitle": "string", "slug": "string", "modifieddate": "datetime", "breadcrumb": { "title": [ {} ] }, "owner": { "enrollmentid": "id", "firstname": "string", "lastname": "string" }, "modifier": { "firstname": "string", "lastname": "string", "userid": "id" }, "replyto": { "messageid": "string", "messagetitle": "string", "modifieddate": "datetime", "modifier": { "firstname": "string", "lastname": "string", "userid": "id" } } } ] } } } ``` ### posts #### post | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the entity that owns the post. | | `coursetitle` | string | The title of the entity if it is a course or the course associated with the entity if it is a section. | | `sectiontitle` | string | *(optional)* The title of the entity if it is section. | | `term` | string | *(optional)* The academic term of the entity. | | `itemid` | string | The ID of the discussion board, wiki, blog or journal item that owns the post. | | `itemtitle` | string | The title of the item. | | `itemtype` | string | The type of the items. | | `groupid` | string | *(optional)* ID of the group if item type is discusson board or wiki and groups are defined for the item. If the item type is blog or journal and groups are defined for the item, this returns a bar-separated list of groups that the passed student enrollment shares with the blog's enrollment. Graders do not share group membership, so this value will always be empty for them. | | `messageid` | string | *(optional)* ID of the message if the item type is discussion board, blog or journal. | | `messagetitle` | string | *(optional)* Title or first line of the message if the item type is discussion board, blog or journal. | | `slug` | string | *(optional)* The slug of the post if the item type is wiki. | | `modifieddate` | datetime | The date of the post. | ##### breadcrumb *(optional)* ###### title The title of the item's ancestor in the manifest tree of items. ##### owner *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | ID of the enrollment that owns the post if item type is blog or journal. | | `firstname` | string | The first name of the enrollment that owns the post if item type is blog or journal. | | `lastname` | string | The last name of the enrollment that owns the post if item type is blog or journal. | ##### modifier *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that authored the post. | | `lastname` | string | The last name of the user that authored the post. | | `userid` | id | The ID of the user that authored the post. | ##### replyto *(optional)* The parent message of the post if the item type is blog or journal and the post is a reply to another message. | Attribute | Type | Description | |-----------|------|-------------| | `messageid` | string | *(optional)* ID of the message if the item type is discussion board, blog or journal. | | `messagetitle` | string | *(optional)* Title or first line of the message if the item type is discussion board, blog or journal. | | `modifieddate` | datetime | The date of the post. | ###### modifier *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that authored the post. | | `lastname` | string | The last name of the user that authored the post. | | `userid` | id | The ID of the user that authored the post. | ## See Also - [GetMessage](https://api.agilixbuzz.com/docs/entry/Command/GetMessage.md) - [GetWikiPage](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPage.md) - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) --- # GetRecord > **Deprecated** — use [ListCourses](https://api.agilixbuzz.com/docs/entry/Command/ListCourses.md) instead. This command gets one content record that you can use in course development. ## Request **Method:** GET **Rights:** None. (The server returns domain or user-specific records only to members of that domain or the user.) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrecord` | | `recordid` | guid | Yes | ID of the record. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "record": { "recordid": "guid", "title": "string", "instructiontype": "InstructionType", "mediatype": "MediaType", "url": "string", "source": "string", "access": "AccessPrivilege", "entityid": "id", "license": "string", "grades": "GradeLevels", "usagecount": "int", "description": {}, "keywords": {}, "details": {} } } } ``` ### record | Attribute | Type | Description | |-----------|------|-------------| | `recordid` | guid | This record's ID. | | `title` | string | This record's title. | | `instructiontype` | [InstructionType](https://api.agilixbuzz.com/docs/entry/Enum/InstructionType.md) | InstructionType | | `mediatype` | [MediaType](https://api.agilixbuzz.com/docs/entry/Enum/MediaType.md) | The MediaType this record refers to. | | `url` | string | The URL this record refers to. | | `source` | string | The source of this record. | | `access` | [AccessPrivilege](https://api.agilixbuzz.com/docs/entry/Enum/AccessPrivilege.md) | The AccessPrivilege for this record. | | `entityid` | id | The entity ID this record refers to. | | `license` | string | The license for this record. | | `grades` | [GradeLevels](https://api.agilixbuzz.com/docs/entry/Enum/GradeLevels.md) | The grades this record applies to. | | `usagecount` | int | | #### description string #### keywords string #### details *(optional)* Optional free-form structured data. See Free Form Data for more details. ## Example This example gets the record whose ID is E7CDCDC5-454B-4d34-8265-FE509341F381. **URL:** `?cmd=getrecord&recordid=E7CDCDC5-454B-4d34-8265-FE509341F381` **Response** (code: `OK`): ```json { "response": { "code": "OK", "record": { "recordid": "E7CDCDC5-454B-4d34-8265-FE509341F381", "title": "Why is the sea salty?", "instructiontype": 1, "mediatype": 10, "access": 1, "license": "Creative Commons", "source": "EdGate", "grades": 256, "version": "2", "url": "http://www.eduref.org/Virtual/Lessons/Science/Geology/GLG0030.html", "description": { "$value": "For students to observe how salt concentration increases in water. Also, how the salt remains\n after the water evaporates." }, "keywords": { "$value": "sea salt seawater" } } } } ``` --- # GetReportInfo This command lists the information about a report including the parameters required to run it. ## Request **Method:** GET **Rights:** Authenticated user. When an entity is supplied it must match the report scope and the caller must hold the report privilege on that entity: ReportDomain (domain), ReportCourse (course or objective set), or ReportUser (user). With no entity, returns the global report definition metadata. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getreportinfo` | | `reportid` | id | Yes | | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "report": { "reportid": "id", "scopentitytype": "D|C|S|P|J", "name": "string", "description": "string", "domainid": "id", "inheritable": "boolean", "formats": { "format": [ { "name": "string", "description": "string" } ] }, "parameters": { "parameter": [ { "name": "string", "type": "string", "attributes": "string" } ] } } } } ``` ### report | Attribute | Type | Description | |-----------|------|-------------| | `reportid` | id | | | `scopentitytype` | string | | | `name` | string | | | `description` | string | | | `domainid` | id | | | `inheritable` | boolean | | #### formats ##### format | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | Name of attribute to pass in as the format parameter in a call to runreport. | | `description` | string | Description of the format. | #### parameters ##### parameter | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | | | `type` | string | Parameter types are in the XML Schema Datatype format (e.g. “boolean”, “byte”, “int”, “string”, “dateTime”, “time”, “duration”, and so forth.) These are well-known parameter names found in many reports: **EntityId:** The ID of the entity on which the report is to be run. scopeentitytype dictates the expected entity type. | | `attributes` | string | Attributes add information about a field that may make a corresponding data-driven parameter input dialog more user-friendly. This value is a comma-separated list of attributes. Each attribute consists of an attribute name followed by an optional an attribute value enclosed in parenthesis. Whitespace around the commas and parenthesis should be ignored. The backslash character is used as an escape character in the attribute specification to represent characters that might carry syntactic meaning outside the context in which they are used. An attribute value is a comma-separated list of simple values or name-value pairs. Simple values are either a quoted string (the quotes should be ignored), or a simple token consisting of everything up to the comma or end parenthesis (whitespace should be escaped or quoted, so it should be ignored in a simple token). Name-value pairs are identified by having an unescaped equal sign character. The following attributes are currently defined: - EntityType, where the attribute value is a single character indicating which entity type the parameter represents so that an appropriate entity finder dialog can be used for this parameter. All entity finder dialogs should limit results to the currently-selected domain and its subdomains. - Default, where the attribute value is a value that should be prepopulated in the dialog. - Min, where the attribute value is the minimum allowed value (inclusive). - Max, where the attribute value is the maximum allowed value (inclusive). - PossibleValues, where the attribute value is a comma-separated list of values, each either a simple value or a name-value pair. If this attribute is present, the dialog should use a drop-down or similar selection control, presenting the name (if available, or the value if not) for selection by the user, and using the corresponding value as the value for the parameter sent in to run the report. Care must be taken to properly quote or escape values and name-value pairs so that they are not misinterpreted. More attributes may be defined at a later date, so clients who parse attribute specifications should be prepared to ignore attributes not listed here. | ## See Also - [GetReportList](https://api.agilixbuzz.com/docs/entry/Command/GetReportList.md) - [GetRunnableReportList](https://api.agilixbuzz.com/docs/entry/Command/GetRunnableReportList.md) - [RunReport](https://api.agilixbuzz.com/docs/entry/Command/RunReport.md) --- # GetReportList This command lists all reports defined on a domain. Reports inherited from parent domains are not included. (See GetRunnableReportList for getting all reports, including inherited ones.) ## Request **Method:** GET **Rights:** Only accounts with all rights on the root domain can make this call. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getreportlist` | | `domainid` | id | Yes | The ID of the domain on which the reports are defined. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "reports": { "report": [ { "reportid": "id", "definitionid": "id", "domainid": "id", "scopentitytype": "D|C|S|P|J", "name": "string", "description": "string", "inheritable": "boolean" } ] } } } ``` ### reports #### report | Attribute | Type | Description | |-----------|------|-------------| | `reportid` | id | | | `definitionid` | id | | | `domainid` | id | | | `scopentitytype` | string | | | `name` | string | | | `description` | string | | | `inheritable` | boolean | | ## See Also - [GetReportInfo](https://api.agilixbuzz.com/docs/entry/Command/GetReportInfo.md) - [GetRunnableReportList](https://api.agilixbuzz.com/docs/entry/Command/GetRunnableReportList.md) - [RunReport](https://api.agilixbuzz.com/docs/entry/Command/RunReport.md) --- # GetResource This command gets resource metadata and/or binary content for the course, section, enrollment, user, or domain. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getresource` | | `entityid` | id | Yes | The course, section, domain, or enrollment ID that contains the resource. | | `path` | string | Yes | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Path cannot start with '/'. Default (unclassed) and Likert-class resources whose path starts with public/ are accessible cross-tenant and even to unauthenticated users; resources stored under any other class still require the normal per-class authorization. | | `version` | string | No | Optional resource version to retrieve. If not specified, the most recent resource version is returned. | | `packagetype` | string | No | Indicates what kind of package is expected to be returned. If unspecified, only the binary part of the resource is returned. If any of the package types explained in PutResource are given, that type of package is returned. | | `attachment` | boolean | No | If set to *true*, the content-disposition header will be set to "attachment" in the response. The default is *false*. | | `class` | string | No | The four character string that specifies the class, or type, of resource to get. The default of an empty string gets normal course or user resources. The special class of *MISC* can be used to get arbitrary or application-specific resources on the specified entity. | ## Response **Content-Type:** package-mime-type **Content-Length:** package-length ## Example **URL:** `?cmd=getresource&entityid=4317&path=images/picture.png` ## See Also - [GetDocument](https://api.agilixbuzz.com/docs/entry/Command/GetDocument.md) - [GetResourceInfo2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceInfo2.md) - [GetResourceList](https://api.agilixbuzz.com/docs/entry/Command/GetResourceList.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # GetResourceInfo2 This command gets information about a resource in the domain, course, section, or enrollment specified by entityid. ## Request **Method:** POST **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getresourceinfo2` | **Request body (JSON):** ```json { "requests": { "resource": [ { "entityid": "id", "path": "string", "class": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `resource.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Course, section, enrollment, or domain ID that owns this resource. | | `resource.path` | string | Yes | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Path cannot start with '/'. | | `resource.class` | string | No | The four character string that specifies the class, or type, for which to get resource information. The default of an empty string gets normal course or user resources. The special class of *MISC* can be used to get arbitrary or application-specific resources on the specified entity. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "resource": { "version": "string", "size": "int", "status": "(Normal|Hidden)", "creationdate": "datetime", "modifieddate": "datetime", "origindepth": "int", "derivativedepth": "int" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### resource | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | Version of the resource. Note that the version supports chained resources and uses a dotted notation for the levels in the chain (i.e. 2.1.5). | | `size` | int | The size, in bytes, of the resource. | | `status` | string | The resource view status. | | `creationdate` | datetime | The creation date and time of the resource. | | `modifieddate` | datetime | The modified date and time of the resource. | | `origindepth` | int | *(optional)* The depth in a course chain where this item originated. | | `derivativedepth` | int | *(optional)* The depth in a course chain that represents where edits in a derivative farthest from the master occured. | ## See Also - [CopyResources](https://api.agilixbuzz.com/docs/entry/Command/CopyResources.md) - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [GetResource](https://api.agilixbuzz.com/docs/entry/Command/GetResource.md) - [GetResourceList2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceList2.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # GetResourceList > **Deprecated** — use [GetResourceList2](https://api.agilixbuzz.com/docs/entry/../Command/GetResourceList2.md) instead. This command lists metadata for entity resources. ## Request **Method:** GET **Rights:** ReadDomain@entityid where entityid refers to a domain; ReadCourse where entityid refers to a course; ReadUser where entityid refers to a user; when entityid refers to an enrollment, GradeAssignment@the enrollment's entity ID, or Participate@entityID and the enrollment is active. **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getresourcelist` | | `entityid` | id | Yes | ID of the entity for which to list resources. | | `path` | string | No | Optional path by which to filter the list. Path can contain the "\*" wildcard character. | | `recurse` | boolean | No | Indicates whether to list resources recursively. The default is true. | | `query` | string | No | Optional query used to filter the list of resources to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, allversions is ignored. | | `allversions` | boolean | No | Specify true to retrieve metadata for all versions of the specified resources; or specify false to retrieve only the latest version's metadata. The default is false. When true, you must have the Update right (UpdateDomain, UpdateCourse, or UpdateUser) for the entity specified by entityid. | | `entries` | int | No | Use the following values to specify which resources to list: 0 to lists resources. This is the default. 1 to lists resource folders. 2 to lists both resources and folders. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "resources": { "resource": [ { "creationdate": "datetime", "entityid": "id", "flags": "ResourceFlags", "modifieddate": "datetime", "path": "string", "size": "int", "version": "string" } ] } } } ``` ### resources #### resource | Attribute | Type | Description | |-----------|------|-------------| | `creationdate` | datetime | Creation date of the resource. | | `entityid` | id | ID of the resource's owning entity. | | `flags` | [ResourceFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResourceFlags.md) | Bitwise OR of the ResourceFlags of the resource. | | `modifieddate` | datetime | Last modified date and time of the resource. | | `path` | string | The resource path. | | `size` | int | Size, in bytes, of the resource. | | `version` | string | Version of the resource. | ## Example This example assumes the entity with ID 4348 exists with these resources. **URL:** `?cmd=getresourcelist&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "resources": { "resource": [ { "entityid": "4378", "path": "imsmanifest.xml", "version": "1", "size": 4430, "flags": 2, "creationdate": "2008-04-0T06:52:22.587Z", "modifieddate": "2008-04-20T06:52:22.587Z" }, { "entityid": "4378", "path": "Templates/Data/HTMLDoc/Text.htm", "version": "1", "size": 56, "flags": 2, "creationdate": "2008-04-20T06:52:23.26Z", "modifieddate": "2008-04-20T06:52:23.26Z" } ] } } } ``` ## See Also - [CopyResources](https://api.agilixbuzz.com/docs/entry/Command/CopyResources.md) - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [GetResource](https://api.agilixbuzz.com/docs/entry/Command/GetResource.md) - [GetResourceInfo2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceInfo2.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # GetResourceList2 This command lists metadata for entity (domain, course, or enrollment) resources. ## Request **Method:** GET **Rights:** ReadDomain@entityid where entityid refers to a domain; ReadCourse where entityid refers to a course; ReadUser where entityid refers to a user; when entityid refers to an enrollment, GradeAssignment@the enrollment's entity ID, or Participate@entityID and the enrollment is active. **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getresourcelist2` | | `entityid` | id | Yes | ID of the entity (domain, course, or enrollment) for which to list resources. | | `path` | string | No | Optional path by which to filter the list. Path can contain the "\*" wildcard character. | | `recurse` | boolean | No | Indicates whether to list resources recursively. The default is true. | | `query` | string | No | Optional query used to filter the list of resources to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, allversions is ignored. | | `allversions` | boolean | No | Specify true to retrieve metadata for all versions of the specified resources; or specify false to retrieve only the latest version's metadata. The default is false. When true, you must have the Update right (UpdateDomain, UpdateCourse, or UpdateUser) for the entity specified by entityid. | | `entries` | int | No | Use the following values to specify which resources to list: 0 to lists resources. This is the default. 1 to lists resource folders. 2 to lists both resources and folders. | | `class` | string | No | The four character string that specifies the class, or type, of resources to get. The default of an empty string gets normal course or user resources. The special class of *MISC* can be used to get arbitrary or application-specific resources on the specified entity. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "resources": { "resource": [ { "creationdate": "datetime", "entityid": "id", "flags": "ResourceFlags", "modifieddate": "datetime", "path": "string", "size": "int", "status": "(Normal|Hidden)", "version": "string" } ] } } } ``` ### resources #### resource | Attribute | Type | Description | |-----------|------|-------------| | `creationdate` | datetime | Creation date of the resource. | | `entityid` | id | ID of the resource's owning entity. | | `flags` | [ResourceFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResourceFlags.md) | Bitwise OR of the ResourceFlags of the resource. | | `modifieddate` | datetime | Last modified date and time of the resource. | | `path` | string | The resource path. | | `size` | int | Size, in bytes, of the resource. | | `status` | string | *(optional)* The visibility status of the resource. (See PutResource for more details.) If omitted, the resource's status is Normal. If the caller does not have adequate rights (ReadDomain, UpdateCourse or ReadCourseFull, UpdateUser) for the requested entityid, GetResourceList2 does not return hidden resources in the list. | | `version` | string | Version of the resource. Note that the version supports chained resources and uses a dotted notation for the levels in the chain (i.e. 2.1.5). | ## Example This example assumes the entity with ID 4348 exists with these resources. **URL:** `?cmd=getresourcelist2&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "resources": { "resource": [ { "entityid": "4378", "path": "imsmanifest.xml", "version": "1", "size": 4430, "flags": 2, "creationdate": "2008-04-0T06:52:22.587Z", "modifieddate": "2008-04-20T06:52:22.587Z" }, { "entityid": "4378", "path": "Templates/Data/HTMLDoc/Text.htm", "version": "1", "size": 56, "flags": 2, "creationdate": "2008-04-20T06:52:23.26Z", "modifieddate": "2008-04-20T06:52:23.26Z" } ] } } } ``` ## See Also - [CopyResources](https://api.agilixbuzz.com/docs/entry/Command/CopyResources.md) - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [GetResource](https://api.agilixbuzz.com/docs/entry/Command/GetResource.md) - [GetResourceInfo2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceInfo2.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # GetRights This command gets the rights granted to the specified actor (user or role) for the specified entity (domain, course, or section). ## Request **Method:** GET **Rights:** ReadUser@actorid; ReadDomain@entityid when entityid refers to a domain; ReadCourse@entityid when entityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrights` | | `actorid` | id | Yes | ID of the user for whom to get rights. | | `entityid` | id | Yes | ID of the domain or course to get actorid’s rights. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "rights": { "roleid": "id", "flags": "RightsFlags" } } } ``` ### rights | Attribute | Type | Description | |-----------|------|-------------| | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise-OR of RightsFlags for the user in the specified entity. The value -1 indicates all rights, including any that may be defined in the future. | ## Example This example lists the rights of the user with ID 6062 on the entity with ID 6065. **URL:** `?cmd=getrights&actorid=6062&entityId=6065` **Response** (code: `OK`): ```json { "response": { "code": "OK", "rights": { "actorid": "6062", "entityid": "6065", "flags": "0", "roleid": "0", "creationdate": "2017-06-24T12:35:00Z", "creationby": "1", "modifieddate": "2017-06-24T12:35:00Z", "modifiedby": "1" } } } ``` ## See Also - [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) - [UpdateRights](https://api.agilixbuzz.com/docs/entry/Command/UpdateRights.md) --- # GetRightsList This command lists rights granted to users on entities (domains, users, and enrollments). ## Request **Method:** GET **Rights:** ReadUser@actor.domainid; ReadDomain@entity.domainid when entity refers to a domain; ReadEnrollment@entity.domainid when entity refers to an enrollment; ReadUser@entity.domainid when entity refers to a user; **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrightslist` | | `domainid` | id | No | Optional domain ID by which to filter the list. | | `restrictdomain` | string | No | How to restrict the list of users and entities returned. The default is both. Possible values are: - **actor** - For all users in domainid, get the entities that they have rights to. The entities can be in any domain. - **entity** - For all entities in domainid, get the users that they have rights on them. The users can be in any domain. - **both** - For all users in domainid, get the entities in domainid that they have rights to. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "list": { "rights": [ { "actorid": "id", "entityid": "id", "roleid": "id", "flags": "RightsFlags", "actorreference": "string", "actorguid": "guid", "entitytype": "string", "entityreference": "string", "entityguid": "guid", "creationdate": "datetime", "creationby": "id", "modifieddate": "datetime", "modifiedby": "id", "version": "string" } ] } } } ``` ### list #### rights | Attribute | Type | Description | |-----------|------|-------------| | `actorid` | id | ID of the user for whom the rights were granted. | | `entityid` | id | ID of the domain, user or enrollment for which the rights apply. | | `roleid` | id | Role ID that optionally specifies privileges. | | `flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | A bitwise OR of RightsFlags for the user. | | `actorreference` | string | A reference that identifies the user to external systems. | | `actorguid` | guid | Globally unique ID (guid) for the user. | | `entitytype` | string | The type of the entity. | | `entityreference` | string | A reference that identifies the entity to external systems. | | `entityguid` | guid | Globally unique ID (guid) for the entity. | | `creationdate` | datetime | The creation date and time of the rights. | | `creationby` | id | ID of the user that initially granted the rights. | | `modifieddate` | datetime | The last modified date and time of the rights. | | `modifiedby` | id | ID of the user that last modified the rights. | | `version` | string | The version of the rights. | ## Example This example assumes the domain with ID 24 exists with these users: **URL:** `?cmd=getrightslist&domainid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "list": { "rights": [ { "actorid": "932", "entityid": "24", "flags": "-1", "actorreference": "User1", "actorguid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "entitytype": "D", "entityreference": "", "entityguid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9dd", "creationdate": "2010-10-11T19:34:46.74Z", "creationby": "25", "modifieddate": "2010-10-11T19:34:46.74Z", "modifiedby": "25", "version": "1" }, { "actorid": "1038", "entityid": "24", "flags": "32", "actorreference": "User2", "actorguid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c9", "entitytype": "D", "entityreference": "", "entityguid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9dd", "creationdate": "2010-10-11T19:34:46.74Z", "creationby": "25", "modifieddate": "2010-10-11T19:34:46.74Z", "modifiedby": "25", "version": "1" } ] } } } ``` ## See Also - [UpdateRights](https://api.agilixbuzz.com/docs/entry/Command/UpdateRights.md) - [GetRights](https://api.agilixbuzz.com/docs/entry/Command/GetRights.md) --- # GetRole This command gets information for a role. ## Request **Method:** GET **Rights:** ReadDomain@domainid or ReadUser@domainid or ReadCourse@domainid or ReadEnrollment@domainid or Proxy@domainid, or the user the session is acting as belongs to the role's domain or one of its subdomains, or holds the Teacher persona in the role's domain or one of its ancestors. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrole` | | `roleid` | id | Yes | ID of the role to get. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "role": [ {} ] } } ``` ### role This node conforms to the Role format. This additionally includes the domain name. ## Example This example assumes the role with ID 6050 already exists. **URL:** `?cmd=getrole&roleid=6050` **Response** (code: `OK`): ```json { "response": { "code": "OK", "role": { "id": "6050", "name": "MyRole", "domainid": "24", "domainname": "East High", "reference": "", "guid": "AF7ABB74-43DB-4334-80A5-833F2AF59C57", "privileges": "131073", "flags": "0", "creationdate": "20012-11-10T16:45:10.123Z", "creationby": "28839", "modifieddate": "20012-11-10T16:45:10.123Z", "modifiedby": "28839", "version": "1" } } } ``` ## See Also - [CreateRole](https://api.agilixbuzz.com/docs/entry/Command/CreateRole.md) - [UpdateRole](https://api.agilixbuzz.com/docs/entry/Command/UpdateRole.md) - [DeleteRole](https://api.agilixbuzz.com/docs/entry/Command/DeleteRole.md) - [ListRoles](https://api.agilixbuzz.com/docs/entry/Command/ListRoles.md) --- # GetRubricMastery This command gets report data that shows how students are performing for items related to the specified rubric. ## Request **Method:** GET **Rights:** ReadGradebook@entityid when entityid refers to a course or section; ReadEnrollment@entityid when entityid refers to an enrollment; ReadCourse@courseid where entityid refers to a group and courseid is the group's owner. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrubricmastery` | | `entityid` | id | Yes | Course, section, group or enrollment ID for which to get rubric mastery report data. | | `rubricentityid` | id | No | Optional course ID that owns the rubric if the rubric is linked from another course not associated the course, section or enrollment specified by the entityid parameter. | | `rubricpath` | string | Yes | Path that identifies the rubric resource. | | `zerounscored` | boolean | No | Specify *true* to indicate that the server should calculate the report data by substituting a score of zero for unscored items. The default is *false*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "rubric": { "entityid": "id", "path": "string", "coverage": "int", "attempts": "int", "possible": "double", "achieved": "double", "unweightedaverage": "double", "row": [ { "id": "string", "attempts": "int", "unweightedaverage": "double" } ] } } } ``` ### rubric | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | *(optional)* The course ID that owns the rubric if the rubric is linked from another course not associated the course, section or enrollment specified by the entityid parameter. | | `path` | string | The path of the rubric resource. | | `coverage` | int | The number of items related to this rubric. | | `attempts` | int | The number of gradable attempts associated with the rubric. | | `possible` | double | The number of weighted points possible for the rubric. | | `achieved` | double | The number of weighted points achieved for the rubric. | | `unweightedaverage` | double | The unweighted average of the scores for rubric. | #### row *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the detail row from the rubric definition | | `attempts` | int | THe number attempts associated with the rubric row. | | `unweightedaverage` | double | The unweighted average of the scores for the rubric row. | ## Example This example retrieves the rubric mastery for the course with ID 268948 and the rubric in resource 'Assets/rubric.xml'. **URL:** `?cmd=getrubricmastery&entityid=268948&path=Assets/rubric.xml` **Response** (code: `OK`): ```json { "response": { "code": "OK", "rubric": { "path": "Assets/rubric.xml", "coverage": "2", "attempts": "3", "possible": "100", "achieved": "80", "unweightedaverage": "0.73333333333333339", "row": [ { "id": "1", "attempts": "2", "unweightedaverage": "0.6" }, { "id": "2", "attempts": "2", "unweightedaverage": "0.83333333333333326" }, { "id": "3", "attempts": "2", "unweightedaverage": "0.41666666666666663" } ] } } } ``` ## See Also - [Rubric](https://api.agilixbuzz.com/docs/entry/Schema/Rubric.md) --- # GetRubricStats This command gets detailed information about responses and scores associated with the rules in a rubric. ## Request **Method:** GET **Rights:** Authenticated user with ReadGradebook@entityid on the owning course, or UpdateDomain on the root domain. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrubricstats` | | `entityid` | id | Yes | Course ID that owns the rubric. If the rubric is linked from another course or derived from a base course, the entityid is the course where the rubric originates. | | `path` | string | Yes | Path that identifies the rubric resource. | | `version` | string | No | Optional version of the rubric for which to get response information. If omitted, the command returns information for all versions. | | `ruleid` | string | No | Optional ID of a rule for which to get response information. If omitted, the command returns information for all rules within the rubric. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "rubric": { "rubricrule": [ { "id": "string", "count": "int", "averageachieved": "double", "averagepossible": "double" } ] } } } ``` ### rubric #### rubricrule | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The unique ID of the rule within the rubric. | | `count` | int | The number of scores associated with the rubric rule. | | `averageachieved` | double | The average points achieved for all the scores. | | `averagepossible` | double | The average points possible for all the scores. | ## Example Retrieves the rubric stats for the rubic with path "Assets/rubric.xml" for the course with ID 77838. **URL:** `?cmd=getrubricstats&entityid=77838&path=Assets/rubric.xml` **Response** (code: `OK`): ```json { "response": { "code": "OK", "rubric": { "rubricrule": [ { "id": "1", "count": "2", "averagepossible": "50", "averageachieved": "30" }, { "id": "2", "count": "2", "averagepossible": "25", "averageachieved": "20" }, { "id": "3", "count": "2", "averagepossible": "25", "averageachieved": "10" } ] } } } ``` ## See Also - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) - [Rubric](https://api.agilixbuzz.com/docs/entry/Schema/Rubric.md) --- # GetRunnableReportList This command lists all reports available to the currently logged-on user. Optionally, the list of reports is restricted to those available for a particular Entity. Entities on which reports can be run are Domains, Courses and Sections. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getrunnablereportlist` | | `entityid` | id | No | The ID of the course entity on which a report is to be run. | | `domainid` | id | No | The ID of the domain containing entities on which to run reports. | Specify either entityid, domainid, or neither. If both are specified, domainid is ignored. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "reports": { "report": [ { "reportid": "id", "scopeentitytype": "D|C|S|P|J", "name": "string", "description": "string" } ] } } } ``` ### reports #### report | Attribute | Type | Description | |-----------|------|-------------| | `reportid` | id | The report id. | | `scopeentitytype` | string | The scope (domain, course, section, user, objective set) that this report applies to. | | `name` | string | The human-readable report name. | | `description` | string | A brief description of the report. | ## Example This example lists the runnable reports for domain with ID 4536. **URL:** `?cmd=getrunnablereportlist&domainid=4536` **Response** (code: `OK`): ```json { "response": { "code": "OK", "reports": { "report": [ { "reportid": "12", "scopeentitytype": "D", "name": "Domain Hierarchy", "description": "Shows the hierarchy of all subdomains of the specified domain." }, { "reportid": "34", "scopeentitytype": "D", "name": "Users by Domain", "description": "Lists the number of Teachers, Students, ActiveUsers, TotalUsers and NeverLoggedIn in each domain" }, { "reportid": "56", "scopeentitytype": "C", "name": "Objective Alignment", "description": "The objective alignment for a course." }, { "reportid": "78", "scopeentitytype": "D", "name": "Enrollment Rollup", "description": "Number of registered users in all domains with subtotal rollups." } ] } } } ``` ## See Also - [GetReportList](https://api.agilixbuzz.com/docs/entry/Command/GetReportList.md) - [GetReportInfo](https://api.agilixbuzz.com/docs/entry/Command/GetReportInfo.md) - [RunReport](https://api.agilixbuzz.com/docs/entry/Command/RunReport.md) --- # GetScoData This command gets a user's SCORM data for a SCO activity from the server. The data is a list of name-value pairs of SCORM-defined variables plus some additional API-defined variables. For details about the SCORM run-time environment and the variables it defines, see the official SCORM Runtime Environment reference manual at http://www.adlnet.gov/capabilities/scorm. These are the API-defined variables: | Name | Meaning | | --- | --- | | xli.course\_id | The ID of the course that contains the SCORM activity. | | xli.course\_name | The name of the course that contains the SCORM activity. | | xli.course\_reference | The external ID of the course that contains the SCORM activity. | | xli.custom.nnn | A custom value stored on the customfields element of the Item Data. Replace nnn with the custom field name. | | xli.domain\_id | The ID of the current user's (xli.user\_id) domain. | | xli.domain\_name | The name of the current user's (xli.user\_id) domain. | | xli.enrollment\_first | The enrollment's (xli.enrollment\_id) first name. | | xli.enrollment\_id | The enrollment ID of the user who owns and submits the SCORM data for this SCORM activity. For example, if a teacher is getting a student's SCORM activity for review, xli.enrollment\_id is the student's enrollment ID. If a teacher is viewing the SCORM activity while browsing the course for herself, xli.enrollment\_id is the teacher's enrollment ID. | | xli.enrollment\_last | The enrollment's (xli.enrollment\_id) last name. | | xli.enrollment\_rights | The enrollment's (xli.enrollment\_id) rights in the course. Possible values are defined by RightsFlags. Also see xli.user\_rights. | | xli.enrollment\_username | The enrollment's (xli.enrollment\_id) username. | | xli.enrollment\_reference | The enrollment's (xli.enrollment\_id) external ID. | | xli.item\_id | The ID of this SCORM activity item in the course (xli.course\_id). | | xli.item\_name | The name of this SCORM activity item in the course (xli.course\_id). | | xli.item\_duedate | The due date of the item that the current user is viewing, or empty string ("") if no due date is set. | | xli.section\_id | The ID of the section the current user is viewing. | | xli.section\_name | The name of the section the current user is viewing. | | xli.section\_reference | The external ID of the section the current user is viewing. | | xli.user\_display | The current user's (xli.user\_id) full display name. | | xli.user\_first | The current user's (xli.user\_id) first name. | | xli.user\_last | The current user's (xli.user\_id) last name. | | xli.user\_id | The current user's ID. For example, if a teacher is getting a student's SCORM activity for review, xli.user\_id is the teacher's user ID. This ID is unique only within the user's userspace; i.e., the xli.userspace/xli.user\_id value uniquely identifies a user. | | xli.user\_rights | The current user's (xli.user\_id) rights in the course. Possible values are defined by RightsFlags. Also see xli.enrollment\_rights. | | xli.username | The current user's (xli.user\_id) username. This name is unique only within the userspace. | | xli.userspace | The current user's (xli.user\_id) userspace. The xli.userspace/xli.username or xli.userspace/xli.user\_id combination uniquely identifies a user. | | xli.user\_reference | The current user's (xli.user\_id) external ID. | ## Request **Method:** GET **Rights:** User who submitted the SCORM data or ReadGradebook@enrollmentid where enrollmentid refers to a course enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getscodata` | | `enrollmentid` | id | Yes | ID of the user’s enrollment to which this data belongs. | | `itemid` | string | Yes | ID of the SCO item (in the course manifest) to which this data belongs. The item must be a custom activity that has the sco attribute set in its Item Data. | | `review` | boolean | No | Specify *true* to retrieve the SCO data in review mode. The field values come from the latest submitted attempt unless otherwise specified by the submittedversion parameter. The default is false. | | `submittedversion` | int | No | If review is true, this parameter specifies the submitted version to review. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "data": { "entry": [ { "name": "string", "value": "string" } ] } } } ``` ### data #### entry | Attribute | Type | Description | |-----------|------|-------------| | `name` | string | The name of the SCORM- or API-defined variable. | | `value` | string | The value of the variable. | ## Example **URL:** `?cmd=getscodata&enrollmentid=99812&itemid=SCO1` **Response** (code: `OK`): ```json { "response": { "code": "OK", "data": { "entry": [ { "name": "cmi.score.scaled", "value": "0.5" }, { "name": "cmi.interactions.0.id", "value": "Q1" }, { "name": "cmi.interactions.0.type", "value": "other" }, { "name": "cmi.interactions.0.result", "value": "0" }, { "name": "cmi.interactions.0.weighting", "value": "1.0" }, { "name": "cmi.interactions.1.id", "value": "Q2" }, { "name": "cmi.interactions.1.type", "value": "other" }, { "name": "cmi.interactions.1.result", "value": "1" }, { "name": "cmi.interactions.1.learner_response", "value": "Green flame" }, { "name": "cmi.interactions.1.weighting", "value": "1.0" }, { "name": "xli.domain_id", "value": "838838" }, { "name": "xli.domain_name", "value": "My Domain" }, { "name": "xli.user_id", "value": "77383" }, { "name": "xli.username", "value": "studentB" }, { "name": "xli.userspace", "value": "mydomain" }, { "name": "xli.user_display", "value": "Jolene Smith" }, { "name": "xli.user_first", "value": "Jolene" }, { "name": "xli.user_last", "value": "Smith" }, { "name": "xli.user_rights", "value": "2228225" }, { "name": "xli.user_reference", "value": "ext1234" }, { "name": "xli.enrollment_id", "value": "99812" }, { "name": "xli.enrollment_first", "value": "Jolene" }, { "name": "xli.enrollment_last", "value": "Smith" }, { "name": "xli.enrollment_username", "value": "studentB" }, { "name": "xli.enrollment_rights", "value": "2228225" }, { "name": "xli.enrollmnet_reference", "value": "ext4567" }, { "name": "xli.course_id", "value": "35687" }, { "name": "xli.course_name", "value": "My Course" }, { "name": "xli.course_reference", "value": "ext9876" }, { "name": "xli.item_id", "value": "SCO1" }, { "name": "xli.item_duedate", "value": "9999-12-31T23:59:59Z" }, { "name": "xli.item_name", "value": "Sco" } ] } } } ``` ## See Also - [PutScoData](https://api.agilixbuzz.com/docs/entry/Command/PutScoData.md) - [GetItemAnalysis2](https://api.agilixbuzz.com/docs/entry/Command/GetItemAnalysis2.md) --- # GetStatus The API servers do fairly extensive self-testing for all subsystems. Overall system health is reported through GetStatus. It also doubles as a basic “ping" operation. This command may require an authenticated connection for detailed data, and even then, details may depend on hosting settings. Security-sensitive data (attributes prefixed with an underscore indicate security-sensitive data) such as server names, urls, file paths, etc. may or may not be hidden or obfuscated depending on hosting settings. Status is reported using the following levels: Ideal (4): Everything is configured and running optimally. Acceptable (3): Everything is running fine, but there are minor issues such as a lack of redundancy. Degraded (2): Part of a redundant system has failed, but the redundancy is keeping the system running. Warning (1): Something other than redundancy is causing issues or may cause issues in the near future, such as disk space running low. Failure (0): At least part of the system has failed completely. SMS and HTML responses are available (if the parameters indicate) and are intended to provide human-readable summaries of issues encountered. The SMS response is suitable for an SMS text message, while the HTML response is suitable for email. The response will always include an ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getstatus` | | `rating` | string | No | Optional status rating level for the response. Status may be indicated by string or number (see function description). Although this parameter affects many details of the XML returned, the specifics of what is returned should not be relied upon in code, as it is subject to change at any time. Code callers can rely on the status and rating attributes as documented here, as well as the existence of a string in the ratingtext attribute, as well as the sms attribute (if applicable) and the HTML contents of the | | `rating` | int | No | Optional status rating level for the response. Any nodes with a status level at or below the specified level will be returned. Although this parameter affects many details of the XML returned, the specifics of what is returned should not be relied upon in code, as it is subject to change at any time. Code callers can rely on the status and rating attributes as documented here, as well as the existence of a string in the ratingtext attribute, as well as the sms attribute (if applicable) and the HTML contents of the | | `sms` | boolean | No | Optional parameter to include sms data in the /response/status/overall/@sms portion of the response. The verboseness of the sms data will match the specified rating. | | `html` | boolean | No | Optional parameter to include an HTML summary in the contents of the /response/status/overall node of the response. The verboseness of the HTML data will match the specified rating. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "status": { "rating": "int", "ratingtext": "string", "status": "string", "secondssincelastratingchange": "int", "lastratingchange": "datetime", "testtime": "datetime", "version": "string", "overall": { "status": "OK", "rating": "1", "ratingtext": "Acceptable", "sms": "SMS message text describing any problem at the specified rating or worse. This attribute may be absent or have an empty value if there are no conditions at or below the specified rating." } } } } ``` ### status | Attribute | Type | Description | |-----------|------|-------------| | `rating` | int | The numeric status rating for the system as a whole. | | `ratingtext` | string | The status rating string (Ideal, Acceptable, Degraded, Warning, or Failed). | | `status` | string | A simple status string indicating the state of the server. OK means everything is good, FAIL means there is a problem (see sms and or html for more information). Other values are also possible under certain conditions and may have different meanings. | | `secondssincelastratingchange` | int | The number of seconds since the rating has changed, useful for sending notifications when an issue initially occurs and then less frequently after the first notification. For diagnostic purposes only. Subject to change. | | `lastratingchange` | datetime | The UTC datetime of the last rating change. For diagnostic purposes only. Subject to change. | | `testtime` | datetime | The UTC datetime when the request was received by the server and began processing. For diagnostic purposes only. Subject to change. | | `version` | string | API Server version. The first number indicates the year of release; the second number indicates the release number during the year, the third number indicates the patch number, and the last number indicates the build number. | #### overall XHTML message with more human-readable details about issues than the SMS message. | Attribute | Type | Description | |-----------|------|-------------| | `status` | string | | | `rating` | string | | | `ratingtext` | string | | | `sms` | string | | ## Example This example shows what you might get back when doing a basic status check when the system is functioning ideally. **URL:** `?cmd=getstatus` **Response** (code: `OK`): ```json { "response": { "code": "OK", "status": { "testtime": "2014-07-04T17:38:27.2790152Z", "version": "2014.4.0.16454", "testms": "109", "lastratingchange": "2014-07-04T03:18:33.3710432Z", "secondssincelastratingchange": "51593", "dlapversion": "2", "status": "OK", "rating": "4", "ratingtext": "Ideal", "overall": { "status": "OK", "rating": "4", "ratingtext": "Ideal" } } } } ``` --- # GetStudentSubmission This command gets a student's submission. A student submission is a zip-compressed file that can contain comments, exam answers, URLs, attached files, etc. With this command you can retrieve the entire submission or individual parts of it. ## Request **Method:** GET **Rights:** User who put the submission or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getstudentsubmission` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this student submission belongs. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within the zip-compressed student submission. For example, specify a filepath to retrieve an attachment from within the student submission. | | `inline` | bool | Yes | When packagetype is file, and inline is true, then the server uses an inline content disposition instead of attachment. An inline content disposition tells the browser to attempt to display the content inline in the browser as part of the web page. An attachment content disposition header tells the browser to download the file and use the operating system to display the content. Note that content types that are executed by the browser when inline are not allowed to be rendered inline due to security reasons. For these types this parameter will be ignored. This includes HTML, CSS, Javascript, XML, SVG, and other types. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this student submission belongs. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Submission data from within the zip-compressed student submission. Equivalent to the now obsolete value xml. - **file** - Returns a single file from within the zip-compressed student submission. You must also specify filepath to identify which file to retrieve. - **zip** - Returns the entire zip-compressed student submission containing the file meta.xml, which is a Submission, and any supporting attached files. | | `version` | int | No | Version of the student submission to retrieve. Omit version to retrieve the most recent student submission. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the student submission for enrollment with ID 4317 and for the item with ID "assign12". **URL:** `?cmd=getstudentsubmission&enrollmentid=4317&itemid=assign12&packagetype=zip` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetStudentSubmissionInfo](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmissionInfo.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # GetStudentSubmissionHistory This command gets the history of submissions for an item in the gradebook for the specified user enrollment. If the submission has been scored or responded to by a teacher, the submission entry includes the teacher response data. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid or enrollmentid belongs to current signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getstudentsubmissionhistory` | | `enrollmentid` | id | Yes | Enrollment ID of user for which to get submission history. | | `itemid` | string | Yes | ID of the item for which to get submission history. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "submissions": { "submission": [ { "creationdate": "datetime", "scoreddate": "datetime", "responseversion": "int", "achieved": "double", "possible": "double", "letter": "string", "passing": "boolean", "rawachieved": "double", "rawpossible": "double", "attempts": "int", "scoredversion": "int", "seconds": "int", "submitteddate": "datetime", "version": "int", "user": { "firstname": "string", "lastname": "string", "reference": "string", "userid": "id", "username": "string", "agent": { "firstname": "string", "lastname": "string", "reference": "string", "username": "string", "userid": "id" } } } ] } } } ``` ### submissions #### submission | Attribute | Type | Description | |-----------|------|-------------| | `creationdate` | datetime | The date and time the submission was created. | | `scoreddate` | datetime | *(optional)* The date the item was last scored. | | `responseversion` | int | *(optional)* Version of the last teacher response. | | `achieved` | double | *(optional)* The number of points achieved for this item adjusted for curving rules. | | `possible` | double | *(optional)* The number of points possible for this item. | | `letter` | string | *(optional)* The letter grade achieved for the item. | | `passing` | boolean | *(optional)* *true* if the score is greater than or equal to the passing score for the item and enrollment. Otherwise omitted. | | `rawachieved` | double | *(optional)* The number of actual points achieved for this item without any curving rules applied. This attribute is included only if it differs from achieved. | | `rawpossible` | double | *(optional)* The number of actual points possible for this item without any curving rules applied. This attribute is included only if it differs from possible. | | `attempts` | int | *(optional)* The number of attempts made on this item. | | `scoredversion` | int | *(optional)* Version of the last scored submission. | | `seconds` | int | *(optional)* The number of seconds spent in this item online material. | | `submitteddate` | datetime | *(optional)* The date of the last submission. | | `version` | int | The submission version that generated this submission entry. (See PutStudentSubmission for more details.) | ##### user | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user who created this submission. | | `lastname` | string | Last name of the user who created this submission. | | `reference` | string | Reference field value of the user who created this submission. | | `userid` | id | ID of the user who created this submission. | | `username` | string | Username of the user who created this submission. | ###### agent *(optional)* If this agent node is present, then agent was proxying as user to create this submission. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | First name of the agent user. | | `lastname` | string | Last name of the agent user. | | `reference` | string | Reference field value of the agent user. | | `username` | string | Username of the agent user. | | `userid` | id | ID of the agent user. | ## Example This example retrieves student submission history for the enrollment with ID 6165 and item with ID "assign12". **URL:** `?cmd=getstudentsubmissionhistory&enrollmentid=6165&itemid=assign12` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [GetEntityGradebook3](https://api.agilixbuzz.com/docs/entry/Command/GetEntityGradebook3.md) - [GetUserGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetUserGradebook2.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetStudentSubmissionInfo This command retrieves information about one or more student submissions from the server. A student submission is content produced by a student in the process of consuming a course. ## Request **Method:** POST **Rights:** User who put the submission or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getstudentsubmissioninfo` | **Request body (JSON):** ```json { "requests": { "submission": [ { "enrollmentid": "id", "itemid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `submission.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user’s enrollment to which this submission belongs. | | `submission.itemid` | string | Yes | ID of the item (in the course manifest) to which this submission belongs. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "submission": { "version": "int" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### submission | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the student submisssion. | ## See Also - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # GetSubmissionState Retrieves state information for an enrollment's assessment or homework submission, including whether the enrollment can start, resume, or retake the assessment or homework group. ## Request **Method:** GET **Rights:** enrollmentid belongs to the current signed-on user or ReadGradebook@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getsubmissionstate` | | `enrollmentid` | id | Yes | ID of the enrollment to get submission state for. | | `itemid` | string | Yes | ID of the assessment item to get submission state for. | | `utcoffset` | int | Yes | The time difference between GMT and local time, in minutes, of the user referred to by *enrollmentid*. | | `createifempty` | boolean | No | Set to *true* to create a submission for a homework item. The default is *false*. You must have an attempt before calling *GetAttempt*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "submissionstate": { "isownenrollment": "boolean", "isstudent": "boolean", "isteacher": "boolean", "canprint": "boolean", "canstart": "boolean", "canretake": "boolean", "cancontinue": "boolean", "disablereason": "string", "submittedversion": "int", "duedate": "datetime", "duedategrace": "int", "groups": { "group": [ { "groupid": "string", "first": "int", "last": "int", "canstart": "boolean", "cancontinue": "boolean", "canretake": "boolean", "disablereason": "string", "submittedversion": "int", "attemptlimit": "int", "timelimit": "int", "pointsachieved": "double", "pointspossible": "double" } ] } } } } ``` ### submissionstate | Attribute | Type | Description | |-----------|------|-------------| | `isownenrollment` | boolean | Whether the input enrollment's user is the same user who is requesting submission state. | | `isstudent` | boolean | Whether the input enrollment's user is a student in this course. | | `isteacher` | boolean | Whether the input enrollment's user is a teacher in this course. | | `canprint` | boolean | Whether the input enrollment's user can print the assessment. | | `canstart` | boolean | Whether the input enrollment's user can start the assessment, which implies that the user has never started it before. | | `canretake` | boolean | Whether the input enrollment's user can retake the assessment, which implies that the user has taken it before. | | `cancontinue` | boolean | Whether the input enrollment's user can continue a saved assessment. When *cancontinue* is *true*, the user started and then saved a submission without submitting it. In this state, *canstart* and *canretake* are also *false*. | | `disablereason` | string | When *canstart*, *canretake*, and *cancontinue* are all *false*, *disablereason* is the reason why the input enrollment's user can neither start nor retake the assessment. These are possible values: - **noQuestions** - There are no questions here to take. - **attemptsExceeded** - The user has used the maximum number of attempts (*attemptlimit*) allowed by the item. - **auditor** - Student users who are auditors of the course (the enrollment does not have the *participate* RightsFlags) may not take this assessment. - **enrollmentExpired** - The enrollment for the user has expired, which means the current date is outside of the enrollment's *startdate* and *enddate*. - **notActive** - The enrollment *status* is not *Active*. - **pastDue** - The due date for the assessment has passed. - **noAdaptivePurchase** - The assessment uses the internal adaptive engine, but the domain does not have access to that feature. | | `submittedversion` | int | *(optional)* Version of the last submission. | | `duedate` | datetime | *(optional)* The item's due date, which matches *duedate* in Item Data. If the item has no due date, this attribute is not present. | | `duedategrace` | int | *(optional)* The item's due date grace, which matches *duedategrace* in Item Data. If the item has no due date grace, this attribute is not present. | #### groups *(optional)* Homework groups ##### group | Attribute | Type | Description | |-----------|------|-------------| | `groupid` | string | Id of the group. | | `first` | int | Question number of the first question in the group. | | `last` | int | Question number of the last question in the group. Most groups only have one question, so *last* is usually the same as *first*. | | `canstart` | boolean | Whether the input enrollment's user can start the homework group. | | `cancontinue` | boolean | Whether the input enrollment's user can continue the homework group. | | `canretake` | boolean | Whether the input enrollment's user can retake the homework group. | | `disablereason` | string | The reason why the user cannot start, continue, or retake the homework group. For possible values see above. | | `submittedversion` | int | Version of the last attempt submission. | | `attemptlimit` | int | Maximum number of attempts the user can use. 0 if there is no limit. | | `timelimit` | int | Time limit in minutes that a student may spend on this question group. 0 if there is no limit. | | `pointsachieved` | double | The number of points achieved for the group. | | `pointspossible` | double | The number of points possible for the group. | ## See Also - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) --- # GetSubscriptionList This command lists subscriptions explicitly assigned to the specified subscriber (user or domain). To list effective subscriptions for a user, including those inherited from the user's domain, see GetEffectiveSubscriptionList. ## Request **Method:** GET **Rights:** ReadUser@subscriberid where subscriberid refers to a user; ReadDomain@subscriberid where subscriberid refers to a domain **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getsubscriptionlist` | | `subscriberid` | string | Yes | The ID of the domain or user to list subscriptions for. | | `entityid` | string | No | The ID of a domain or course to filter the list of subscriptions by. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "subscriptions": { "subscription": [ { "subscriberid": "id", "entityid": "id", "entitytype": "D|C", "startdate": "datetime", "enddate": "datetime", "subscriptionflags": "SubscriptionFlags", "creationdate": "datetime", "modifieddate": "datetime", "version": "string", "name": "string", "title": "string" } ] } } } ``` ### subscriptions #### subscription | Attribute | Type | Description | |-----------|------|-------------| | `subscriberid` | id | ID of the subscriber (user or domain). | | `entityid` | id | ID of the entity (course or domain) that subscriberid subscribes to. | | `entitytype` | string | The type of entity entityid refers to. D is a domain; C is a course. | | `startdate` | datetime | Date and time when the subscription begins. | | `enddate` | datetime | Date and time when the subscription ends. | | `subscriptionflags` | [SubscriptionFlags](https://api.agilixbuzz.com/docs/entry/Enum/SubscriptionFlags.md) | A bitwise-OR of the subscription's SubscriptionFlags. | | `creationdate` | datetime | Date and time when the subscription was created. | | `modifieddate` | datetime | Date and time when the subscription was last modified. | | `version` | string | Version of the subscription. | | `name` | string | *(optional)* When subscriberentitytype is D, the name of the domain. | | `title` | string | *(optional)* When subscriberentitytype is C, the title of the course. | ## Example This example lists all subscriptions for the user with ID 9911. **URL:** `?cmd=getsubscriptionlist&subscriberid=9911` **Response** (code: `OK`): ```json { "response": { "code": "OK", "subscriptions": { "subscription": [ { "subscriberid": "9911", "entityid": "9742", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.443Z", "version": "1" }, { "subscriberid": "9911", "entityid": "9909", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z", "subscriptionflags": "0", "flags": "65535", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.443Z", "version": "2" }, { "subscriberid": "9911", "entityid": "102073", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:01:00Z", "subscriptionflags": "0", "creationdate": "2011-03-24T21:08:04.697Z", "modifieddate": "2011-03-24T21:32:38.46Z", "version": "2" } ] } } } ``` ## See Also - [GetEntitySubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEntitySubscriptionList.md) - [GetEffectiveSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEffectiveSubscriptionList.md) - [UpdateSubscriptions](https://api.agilixbuzz.com/docs/entry/Command/UpdateSubscriptions.md) --- # GetTeacherResponse This command gets a teacher's response to a student's submission. A response is a zip-compressed file that can contain scores, feedback, rubric data, attached files, etc. With this command you can retrieve the entire response or individual parts of it. ## Request **Method:** GET **Rights:** User to whom the teacher response applies or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment. ReadGradebook@enrollmentid is always required for private.zip. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getteacherresponse` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this teacher response belongs. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within the zip-compressed teacher response. For example, specify a filepath to retrieve an attachment from within the teacher response. | | `inline` | bool | Yes | When packagetype is file, and inline is true, then the server uses an inline content disposition instead of attachment. An inline content disposition tells the browser to attempt to display the content inline in the browser as part of the web page. An attachment content disposition header tells the browser to download the file and use the operating system to display the content. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this teacher response belongs. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Response data from within the zip-compressed teacher response. Equivalent to the now obsolete value xml. - **file** - Returns a single file from within the zip-compressed teacher response. You must also specify filepath to identify which file to retrieve. If you specify *private.zip/notes.htm*, then GetTeacherResponse returns the contents of notes.htm from the private.zip resource used by PutTeacherResponse . - **zip** - Returns the entire zip-compressed teacher response containing the file meta.xml, which is a Response, and any supporting attached files. | | `version` | int | No | Version of the teacher response to retrieve. Omit version to retrieve the teacher response resulting in the current grade. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the teacher response for enrollment with ID 4317 and for the item with ID "assign12". **URL:** `?cmd=getteacherresponse&enrollmentid=4317&itemid=assign12&packagetype=zip` ## See Also - [Response](https://api.agilixbuzz.com/docs/entry/Schema/Response.md) - [GetTeacherResponseInfo](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponseInfo.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetTeacherResponseInfo This command retrieves information about teacher responses from the server. ## Request **Method:** POST **Rights:** User to whom the teacher response applies or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getteacherresponseinfo` | **Request body (JSON):** ```json { "requests": { "teacherresponse": [ { "enrollmentid": "id", "itemid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `teacherresponse.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user’s enrollment to which this teacher response belongs. | | `teacherresponse.itemid` | string | Yes | ID of the item (in the course manifest) to which this teacher response belongs. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "teacherresponse": { "version": "int" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### teacherresponse | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the teacher response. | ## See Also - [GetTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponse.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # GetUser > **Deprecated** — use [GetUser2](https://api.agilixbuzz.com/docs/entry/Command/GetUser2.md) instead. This command gets information for a particular user. ## Request **Method:** GET **Rights:** ReadUser@domain, or self (the signed-on user may read their own account -- userid omitted, or userid equal to the signed-on user -- which is allowed even with a scoped token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuser` | | `userid` | id | No | ID of the user to get information for. If you omit userid, the result is for the current signed-on user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "guid": "guid", "firstname": "string", "lastname": "string", "reference": "string", "flags": "EntityFlags", "domainid": "id", "username": "string", "email": "string", "passwordquestion": "string", "lastlogindate": "datetime", "creationdate": "datetime", "data": {} } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The user's ID. | | `guid` | guid | The user's globally unique ID (guid). | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | | `reference` | string | The user's reference field value. This is typically an external ID, such as the user's ID in an external SIS system. | | `flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | Bitwise OR of EntityFlags for the user. | | `domainid` | id | The user's domain ID. | | `username` | string | The user's username. | | `email` | string | The user's email address. | | `passwordquestion` | string | The user's password question. | | `lastlogindate` | datetime | The user's last login date. | | `creationdate` | datetime | The creation date and time of the user. | #### data *(optional)* Optional free-form structured data. See User Data and Free Form Data for more details. ## Example This example assumes the user with ID 589 already exists. **URL:** `?cmd=getuser&userid=589` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "589", "firstname": "Sally", "lastname": "Johnson", "reference": "12345678", "guid": "cf2d9568-8a47-449b-bbda-0c70e1afda7f", "domainid": "24", "username": "sally.johnson", "email": "sally.johnson@myschool.edu", "passwordquestion": "What model is my car?", "flags": "0", "lastlogindate": "2008-11-13T15:22:12:884Z", "creationdate": "2007-11-12T16:48:13.483Z", "data": { "blti": { "hideemail": "true", "hidefullname": "true" }, "boilerplatedata": { "boilerplate": [ { "type": "Grading", "title": "Grading number one", "path": "assets/profile/boilerplates3746d315-c19e-412a-dd93-b4fbd1f1b79c.xml" }, { "type": "Forum", "title": "Forum post one", "path": "assets/profile/boilerplatescecb54fd-f14e-95fc-8aa4-96223eaa10af.xml" } ] }, "profilepicture": { "$value": "assets/profile/profilepicture.png" }, "profilebio": { "$value": "assets/profile/profilebio.htm" } } } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUserList](https://api.agilixbuzz.com/docs/entry/Command/GetUserList.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # GetUser2 This command gets information for a particular user. ## Request **Method:** GET **Rights:** ReadUser@domain, or self (the signed-on user may read their own account -- userid omitted, or userid equal to the signed-on user -- which is allowed even with a scoped token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuser2` | | `userid` | id | No | ID of the user to get information for. If you omit userid, the result is for the current signed-on user. | | `select` | string | No | Comma-separated list of which data to return. By default, *GetUser2* returns only the user node. Possible values are: - *data[(...)]* - Includes the user's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *history(...)* - Includes the user history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. - *securityconfig* - Includes the user's security configuration such as whether MFA is required for this user. - *session* - Includes the user's most recent active session, if they are currently logged-in. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "domain": { "data": {} }, "session": {} } } } ``` ### user This node conforms to the User format. #### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. #### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ##### user *(optional)* This node conforms to the User format. These are the results of the history query. #### domain *(optional)* This node conforms to the Domain format. ##### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. #### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session. ## Example This example assumes the user with ID 589 already exists. **URL:** `?cmd=getuser2&userid=589&select=data` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "id": "589", "firstname": "Sally", "lastname": "Johnson", "domainid": "24", "reference": "12345678", "guid": "cf2d9568-8a47-449b-bbda-0c70e1afda7f", "username": "sally.johnson", "email": "sally.johnson@myschool.edu", "flags": "0", "lastpasswordchangeddate": "2007-11-12T16:48:13.483Z", "firstlogindate": "1753-01-01T00:00:00Z", "lastlogindate": "1753-01-01T00:00:00Z", "creationdate": "2007-11-12T16:48:13.483Z", "creationby": "2838", "modifieddate": "2007-11-12T16:48:13.483Z", "modifiedby": "2838", "version": "1", "data": { "blti": { "hideemail": "true", "hidefullname": "true" }, "boilerplatedata": { "boilerplate": [ { "type": "Grading", "title": "Grading number one", "path": "assets/profile/boilerplates3746d315-c19e-412a-dd93-b4fbd1f1b79c.xml" }, { "type": "Forum", "title": "Forum post one", "path": "assets/profile/boilerplatescecb54fd-f14e-95fc-8aa4-96223eaa10af.xml" } ] }, "profilepicture": { "$value": "assets/profile/profilepicture.png" }, "profilebio": { "$value": "assets/profile/profilebio.htm" } } } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUserList](https://api.agilixbuzz.com/docs/entry/Command/GetUserList.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # GetUserActivity This command lists the login activity for a user. ## Request **Method:** GET **Rights:** ReadUser@userid or userid is the signed-on user **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuseractivity` | | `userid` | id | Yes | User ID of the user for which to get activity. | | `startdate` | datetime | No | Filters the response by login activity that occurred after the specified date. | | `enddate` | datetime | No | Filters the response by login activity that occurred before the specified date. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "log": { "activity": [ { "logindate": "datetime", "logoutdate": "datetime" } ] } } } ``` ### log #### activity | Attribute | Type | Description | |-----------|------|-------------| | `logindate` | datetime | The date and time the user logged in | | `logoutdate` | datetime | The date and time the user logged out | ## Example This example retrieves activity log for the user with ID 303137. **URL:** `?cmd=getuseractivity&userid=303137` **Response** (code: `OK`): ```json { "response": { "code": "OK", "log": { "activity": [ { "logindate": "2012-08-18T16:06:51.747Z", "logoutdate": "2012-08-18T16:10:51.747Z" }, { "logindate": "2012-10-17T21:17:42.743Z", "logoutdate": "2012-10-17T18:10:51.747Z" } ] } } } ``` ## See Also - [GetEnrollmentActivity](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentActivity.md) --- # GetUserActivityStream This command lists activities in a user's activity stream. Activities are created when events specified in ActivityStreamType occur. Activities are returned sorted by date with the most recent first. Activities older than 90 days are not returned. ## Request **Method:** GET **Rights:** userid is the signed-on user, enrollment.userid is the signed-on user, or ReadUser@userid, or ReadGradebook@enrollment.courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuseractivitystream` | | `userid` | id | No | User ID of the user for which to get activity. The default is the user ID of the signed-on user. | | `enrollmentid` | id | No | ID of the enrollment for which to get activity. The enrollment's user must be *userid*, if *userid* is specified, or the currently signed on user if *userid* is omitted. | | `startkey` | string | No | *GetUserActivityStream* paginates the results. Pass the value returned in *endkey* for *startkey* to get the next page of results. | | `limit` | int | No | Restricts the number of results to at most this value. The default is 10. The maximum value is 100. | | `types` | string | No | A vertical-bar (\|) separated list of types that can be returned. If no types are supplied, then activities of all types are returned. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "activities": { "endkey": "string", "activity": [ { "userid": "id", "enrollmentid": "id", "date": "datetime", "type": "ActivityStreamType", "data": { "conversation": { "id": "string", "subject": "string", "type": "string" }, "message": { "id": "string", "forteacher": "boolean", "userspace": "string" }, "user": { "id": "string", "firstname": "string", "lastname": "string" }, "recipient": { "id": "string", "firstname": "string", "lastname": "string" }, "course": { "id": "string", "title": "string", "thumbnail": "string" }, "item": { "id": "string", "title": "string", "type": "ItemType", "gradable": "boolean", "gradeview": "GradeView", "thumbnail": "string", "thumbnailentityid": "string", "gradeflags": "GradeFlags" } } } ] } } } ``` ### activities | Attribute | Type | Description | |-----------|------|-------------| | `endkey` | string | *(optional)* *endkey* may be passed as the parameter *startkey* to get the next page of results. If *endkey* is empty then there are no more activities. | #### activity | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The user ID. | | `enrollmentid` | id | The enrollment ID or 0 if there was no associated enrollment. | | `date` | datetime | The date and time the activity occurred. | | `type` | [ActivityStreamType](https://api.agilixbuzz.com/docs/entry/Enum/ActivityStreamType.md) | The ActivityStreamType of this activity. | ##### data *(optional)* The data node when the activity type is: Submission. | Attribute | Type | Description | |-----------|------|-------------| | `dueindays` | double | If the item has a due date and the course is a range course, the days until the duedate passes. Otherwise, omitted. If the due date has passed, then this number will be negative. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### newgrade *(optional)* The grade after this activity. This node conforms to the Grade format. ###### user *(optional)* Information about the user that made the call that triggered the grade change. For submissions this typically happens with group assignments. Omitted unless this is a different user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: SubmissionTeacher. | Attribute | Type | Description | |-----------|------|-------------| | `dueindays` | double | If the item has a due date and the course is a range course, the days until the duedate passes. Otherwise, omitted. If the due date has passed, then this number will be negative. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### newgrade *(optional)* The grade after this activity. This node conforms to the Grade format. ###### user *(optional)* Information about the user that made the call that triggered the grade change. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: Response. ###### response | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The response version that triggered this activity. | | `hasFeedback` | boolean | *(optional)* Marked true if the response that triggered the activity record has feedback either in the form of notes or an attachment. Default is false. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### newgrade *(optional)* The grade after this activity. This node conforms to the Grade format. ###### user *(optional)* Information about the user that made the call that triggered the grade change. Omitted unless this is a different user. For example, this node is ommitted when a student marks an activity complete, or completes an activity by spending time on it. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: ResponseVisible. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### newgrade *(optional)* The grade after this activity. This node conforms to the Grade format. ##### data *(optional)* The data node when the activity type is: DiscussionBoardPost. ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Unique message ID. | | `parentid` | string | *(optional)* Unique message ID of the message being replied to. Omitted if this message was not a response. | | `version` | string | The version of the newly put message. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ##### data *(optional)* The data node when the activity type is: DiscussionBoardReply. ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | Unique message ID. | | `parentid` | string | Unique message ID of the message being replied to. | | `version` | string | The version of the newly put message. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### user Information about the user that posted the discussion board message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: AnnouncementCreatedOrUpdated or AnnouncementDeleted. ###### announcement | Attribute | Type | Description | |-----------|------|-------------| | `title` | string | Title of the announcement. | | `path` | string | Unique path to the zip-compressed announcement file. | | `version` | string | The version of the announcement. | ###### user Information about the user that created, updated, or deleted the announcement. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: BadgeManual. ###### badge | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the badge. | | `name` | string | The name of the badge. | | `description` | string | A description of the badge. | ###### user Information about the user that created the badge. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course *(optional)* Included when the badge was created on an an enrollment (badges may also be created on users) | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: BadgeAutomatic. ###### badge | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the badge. | | `name` | string | The name of the badge. | | `description` | string | A description of the badge. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: EmailSent. ###### email | Attribute | Type | Description | |-----------|------|-------------| | `subject` | string | The e-mail subject. | | `bodystart` | string | The first 100 characters of the email body's plaintext. | ###### recipients The recipients for this e-mail. These nodes mirror the *enrollments*, *groups*, and *roles* nodes found in the Mail schema. ####### enrollments *(optional)* The recipient enrollments for this e-mail. ######## enrollment | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | The recipient enrollment ID for this e-mail. In addition to an enrollment ID, the value may be one of *all*, *students*, or *teachers*. See the Mail schema for more information. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: EmailReceived. ###### email | Attribute | Type | Description | |-----------|------|-------------| | `subject` | string | The e-mail subject. | | `bodystart` | string | The first 100 characters of the email body's plaintext. | ###### user Information about the user that sent the e-mail. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: EnrollmentStatusChangedStudent. | Attribute | Type | Description | |-----------|------|-------------| | `oldstatus` | string | The string value that represents the old status | | `newstatus` | string | The string value that represents the new status | ###### user Information about the user that changed the enrollment status. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: EnrollmentStatusChangedTeacher. | Attribute | Type | Description | |-----------|------|-------------| | `oldstatus` | string | The string value that represents the old status | | `newstatus` | string | The string value that represents the new status | ###### user Information about the user that changed the enrollment status. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### studentuser Information about the enrollment's student user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: EnrollmentStatusChangedObserver. | Attribute | Type | Description | |-----------|------|-------------| | `oldstatus` | string | The string value that represents the old status | | `newstatus` | string | The string value that represents the new status | ###### user Information about the user that changed the enrollment status. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### studentuser Information about the enrollment's student user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ##### data *(optional)* The data node when the activity type is: UserJoinedTeam. ###### user Information about the user that joined the team. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ##### data *(optional)* The data node when the activity type is: TeamDeleted. ###### user Information about the user that deleted the team. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ##### data *(optional)* The data node when the activity type is: TeamDeleted. ###### user Information about the user that deleted the team. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ##### data *(optional)* The data node when the activity type is: TeamConversationCreated. ###### user Information about the user that created the message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The message ID | | `title` | string | The message title | | `bodystart` | string | The first 100 characters of the message body's plaintext. | | `rootid` | string | The message ID | | `roottitle` | string | The message title | ##### data *(optional)* The data node when the activity type is: MessageInConversation. ###### user Information about the user that created the message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The message ID | | `title` | string | The message title | | `bodystart` | string | The first 100 characters of the message body's plaintext. | | `rootid` | string | The message ID | | `roottitle` | string | The message title | ##### data *(optional)* The data node when the activity type is: ReplyToConversationMessage. ###### user Information about the user that created the message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### team | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The team ID | | `name` | string | The team name | ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The message ID | | `title` | string | The message title | | `bodystart` | string | The first 100 characters of the message body's plaintext. | | `rootid` | string | The message ID | | `roottitle` | string | The message title | ##### data *(optional)* The data node when the activity type is: CommunityCatalogItemCopied. ###### user Information about the user that copied the item. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course that the item was copied from. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ##### data *(optional)* The data node when the activity type is: ItemDueDateChanged. ###### duedate | Attribute | Type | Description | |-----------|------|-------------| | `olddate` | datetime | The old duedate. | | `newdate` | datetime | The new duedate. | ###### user Information about the user that changed the due date. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ##### data *(optional)* The data node when the activity type is: ItemAdded. ###### user Information about the user that added the item. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ##### data *(optional)* The data node when the activity type is: GradeBelowPassing. ###### user Information about the student user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course that the item was copied from. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### newcoursegrade Information about the new, and failing, course grade. | Attribute | Type | Description | |-----------|------|-------------| | `achieved` | double | The course ID | | `possible` | double | The course title | ###### oldcoursegrade *(optional)* Information about the old course grade. It is possible that there was no previous course grade. | Attribute | Type | Description | |-----------|------|-------------| | `achieved` | double | The course ID | | `possible` | double | The course title | ##### data *(optional)* The data node when the activity type is: StudentGradeBelowPassing. ###### user Information about the student user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course that the item was copied from. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### newcoursegrade Information about the new, and failing, course grade. | Attribute | Type | Description | |-----------|------|-------------| | `achieved` | double | The course ID | | `possible` | double | The course title | ###### oldcoursegrade *(optional)* Information about the old course grade. It is possible that there was no previous course grade. | Attribute | Type | Description | |-----------|------|-------------| | `achieved` | double | The course ID | | `possible` | double | The course title | ##### data *(optional)* The data node when the activity type is: AllowRetry. ###### user Information about the student user. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course that the item was copied from. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### remediationassessmentitem Information about the remediation assessment item that triggers the AllowRetry. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | ##### data *(optional)* The data node when the activity type is: PasswordChanged. ###### user Information about the user whose password changed. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### changedbyuser Information about the user who changed the password. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: AncestorCourseEntityChanged. ###### course Information about the descendant course. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### ancestorcourse Information about the ancestor course that was changed. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### user *(optional)* Information about the user that changed the course entity. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: AncestorCourseItemChanged. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### ancestorcourse Information about the ancestor course that was changed. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### user *(optional)* Information about the user that changed the item. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: AncestorCourseItemDeleted. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### ancestorcourse Information about the ancestor course that was changed. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ###### user *(optional)* Information about the user that deleted the item. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: StudentEnrollmentBeganStudent. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### user *(optional)* Information about the student user whose enrollment started. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: StudentEnrollmentBeganTeacher. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### user *(optional)* Information about the student user whose enrollment started. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: StudentEnrollmentBeganObserver. ###### course | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### user *(optional)* Information about the student user whose enrollment started. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ##### data *(optional)* The data node when the activity type is: SubmissionBasedMessageForStudent. ###### conversation Information about the conversation the inbox message belongs to. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The conversation ID | | `subject` | string | Subject of the conversation | ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The message ID | ###### user Information about the user who creates the submission based inbox message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course the inbox conversation is associated with. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item Information about the item the inbox conversation is associated with. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ##### data *(optional)* The data node when the activity type is: InboxMessageReceived or InboxMessageReceivedObserver. ###### conversation Information about the conversation the inbox message belongs to. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The conversation ID | | `subject` | string | Subject of the conversation | | `type` | string | Type of the conversation. Possible values are "normal", "item", and "submission". | ###### message | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The message ID | | `forteacher` | boolean | *(optional)* Whether the recipient is a teacher or not. | | `userspace` | string | User space of the course domain the message is associated with. | ###### user Information about the user who creates the inbox message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### recipient Information about the user who receives the inbox message. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The user ID | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | ###### course Information about the course the inbox conversation is associated with. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The course ID | | `title` | string | The course title | | `thumbnail` | string | *(optional)* The course thumbnail as defined in the Course Data. | ###### item *(optional)* Information about the item the inbox conversation is associated with. | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID | | `title` | string | The title for this item. | | `type` | [ItemType](https://api.agilixbuzz.com/docs/entry/Enum/ItemType.md) | The "Name" value of the item's ItemType. | | `gradable` | boolean | *(optional)* *true* if the item is gradable. Otherwise *gradable* is omitted. | | `gradeview` | [GradeView](https://api.agilixbuzz.com/docs/entry/Enum/GradeView.md) | *(optional)* A GradeView value that controls how to display scores for this item. This is determined using the item's category (defined in Item Data) and the category's gradeview (defined in Course Data). *gradeview* is omitted if the item is not in a category, or if the category is not found in the Course Data. | | `thumbnail` | string | *(optional)* The item thumbnail path (see Item Data) | | `thumbnailentityid` | string | *(optional)* The item thumbnail.entityid (see Item Data) | | `gradeflags` | [GradeFlags](https://api.agilixbuzz.com/docs/entry/Enum/GradeFlags.md) | *(optional)* The item grade flags (see Item Data). Ommitted when the flags are *None*. | ## Example This example retrieves activity log for the user with ID 303137. **URL:** `?cmd=getuseractivitystream` **Response** (code: `OK`): ```json { "response": { "code": "OK", "activities": { "activity": [ { "userid": "2067319", "date": "2015-05-25T03:06:34.7020166Z", "enrollmentid": "2067317", "type": 200, "data": { "response": { "version": 5 }, "course": { "id": "2067315", "title": "Geometry" }, "item": { "id": "dfdc9284-ae81-40c4-b2f8-dc8c82e1ba6a", "title": "Assignment 1", "type": "Assignment" }, "user": { "id": "2067321", "firstname": "John", "lastname": "Smith" }, "oldgrade": { "status": "257", "responseversion": 4, "submittedversion": 1, "submitteddate": "2015-05-25T03:06:30.51Z" }, "newgrade": { "status": "261", "responseversion": 5, "scoredversion": 1, "scoreddate": "2015-05-25T03:06:34.6350099Z", "achieved": 100, "possible": 100, "letter": "A", "passing": true, "rawachieved": 10, "rawpossible": 10, "submittedversion": 1, "submitteddate": "2015-05-25T03:06:30.51Z" } } }, { "userid": "2067319", "date": "2015-05-25T03:06:31.6997164Z", "enrollmentid": "2067317", "type": 200, "data": { "response": { "version": 3, "hasnotes": true }, "course": { "id": "2067315", "title": "Geometry" }, "item": { "id": "dfdc9284-ae81-40c4-b2f8-dc8c82e1ba6a", "title": "Assignment 2", "type": "Assignment" }, "user": { "id": "2067321", "firstname": "John", "lastname": "Smith" }, "oldgrade": { "status": "261", "responseversion": 2, "scoredversion": 1, "scoreddate": "2015-05-25T03:06:31.187Z", "achieved": 70, "possible": 100, "letter": "C", "passing": true, "rawachieved": 7, "rawpossible": 10, "submittedversion": 1, "submitteddate": "2015-05-25T03:06:30.51Z" }, "newgrade": { "status": "261", "responseversion": 3, "scoredversion": 1, "scoreddate": "2015-05-25T03:06:31.6297094Z", "achieved": 80, "possible": 100, "letter": "B", "passing": true, "rawachieved": 8, "rawpossible": 10, "submittedversion": 1, "submitteddate": "2015-05-25T03:06:30.51Z" } } } ] } } } ``` ## See Also - [ActivityStreamType](https://api.agilixbuzz.com/docs/entry/Enum/ActivityStreamType.md) --- # GetUserAnnouncementList This command lists course, section, and domain announcements for the current user. To get the content of the returned announcements, call GetAnnouncement. ## Request **Method:** GET **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuserannouncementlist` | | `userid` | id | No | User for whom to list announcements. If not supplied, the command lists announcements for the current user. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. GetUserAnnouncementList lists announcements for courses in which the user has an active enrollment. When not supplied, GetUserAnnouncementList considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "announcements": { "announcement": [ { "entityid": "id", "path": "string", "title": "string", "version": "string", "startdate": "datetime", "enddate": "datetime", "domainname": "string", "coursetitle": "string", "sectiontitle": "string", "viewed": "boolean", "creationdate": "datetime", "modifieddate": "datetime" } ] } } } ``` ### announcements #### announcement | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | Entity ID (domain, course, or section) that owns this announcement. | | `path` | string | Path to the annoucement resource. | | `title` | string | Annoucement title. | | `version` | string | Annoucement version. | | `startdate` | datetime | Annoucement start date and time. | | `enddate` | datetime | Annoucement end date and time. | | `domainname` | string | *(optional)* Name of the domain that this announcement was sent to. | | `coursetitle` | string | *(optional)* Title of the course that this announcement was sent to. | | `sectiontitle` | string | *(optional)* Title of the section that this announcement was sent to. | | `viewed` | boolean | *(optional)* Whether the current signed-on user has viewed this announcement. | | `creationdate` | datetime | Announcement creation date and time. | | `modifieddate` | datetime | Annoucement last modified date and time. | ## Example **URL:** `?cmd=getuserannouncementlist` **Response** (code: `OK`): ```json { "response": { "code": "OK", "announcements": { "announcement": [ { "entityid": "6153", "path": "02e839940ac34dd3ae466b42f61e6418.zip", "title": "Final Exam moved to Friday", "startdate": "2008-04-24T00:00:00Z", "enddate": "2008-04-25T23:59:00Z", "version": "2", "domainname": "VirtualSchool", "creationdate": "2008-04-24T09:58:15.75Z", "modifieddate": "2008-04-24T09:58:27.75Z" }, { "entityid": "6153", "path": "b2ac7c19527e4cf29e28da922df2657d.zip", "title": "Final Exams results declared", "startdate": "2008-04-24T00:00:00Z", "enddate": "2009-04-24T23:59:00Z", "version": "2", "domainname": "VirtualSchool", "viewed": true, "creationdate": "2008-04-24T11:38:17.773Z", "modifieddate": "2008-04-24T11:41:07.32Z" } ] } } } ``` ## See Also - [DeleteAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/DeleteAnnouncements.md) - [GetAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementList.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) - [UpdateAnnouncementViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateAnnouncementViewed.md) --- # GetUserEnrollmentList2 > **Deprecated** — use [ListUserEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListUserEnrollments.md) instead. This command lists enrollments for the specified user. ## Request **Method:** GET **Rights:** ReadUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuserenrollmentlist2` | | `userid` | id | Yes | User for whom to list enrollments. | | `allstatus` | boolean | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. | | `entityid` | id | No | Optional entity ID by which to filter the list. | | `flags` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified flags are returned in the response. | | `query` | string | No | Optional query used to filter the list of courses. See ListCourses for more information. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ {} ] } } } ``` ### enrollments #### enrollment *(optional)* These nodes conform to the Enrollment-Entity format. ## Example This example assumes the user with ID 15002 exists with these enrollments: **URL:** `?cmd=getuserenrollmentlist2&userid=15002` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": 1, "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "entity": { "id": "268973", "entitytype": "C", "title": "Chemistry", "reference": "", "guid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "days": 365, "term": "", "baseid": "0" }, "domain": { "id": "9909", "name": "State University" } }, { "id": "22687", "userid": "15002", "entityid": "22496", "domainid": "9909", "reference": "", "guid": "fee490b8-6311-4fab-992f-6fe486f9f8b6", "flags": "2097153", "status": 1, "startdate": "2009-02-06T07:00:00Z", "enddate": "2020-02-12T06:59:00Z", "entity": { "id": "22496", "entitytype": "S", "title": "Section 1", "reference": "", "guid": "654767fe-8bbc-43b7-b7b0-3343b36f7491", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2009-01-27T07:00:00Z", "enddate": "2022-01-29T06:59:00Z", "days": 365, "term": "", "baseid": "20836", "base": { "id": "20836", "title": "English", "reference": "", "guid": "4d6ab992-145f-446e-8396-5ed1a085b84d", "domainid": "9909", "flags": "0" } }, "domain": { "id": "9909", "name": "State University" } } ] } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [DeleteEnrollments](https://api.agilixbuzz.com/docs/entry/Command/DeleteEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [ListEntityEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEntityEnrollments.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # GetUserGradebook2 This command gets gradebook detail for the specified user. This command is similar to GetEnrollmentGradebook2, except that it returns grades for multiple enrollments. The same due-date calculation also occurs as described in GetEnrollmentGradebook2. Note that this API is subject to API rate limiting. See the API Rate Limiting concept for more information. ## Request **Method:** GET **Rights:** ReadUser@userid or userid is current signed-on user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getusergradebook2` | | `userid` | id | Yes | ID of the user for which to get grades. | | `allstatus` | boolean | No | When true, returns grades for all enrollments, regardless of enrollment status. When false, returns grades for only Active or Suspended enrollments where today's date falls between the start and end dates of the enrollment. The default is false. | | `entityid` | id | No | Optional entity ID by which to filter the returned data. When omitted, grade data from all this user's enrollments is returned. | | `forcerequireditems` | boolean | No | Specify true to force the final rollup scores to be 0 if any required item (see PassingScoreRequired in GradeFlags) score is missing or below passing. Specify false to calculate rolled-up scores even if a required item score is either missing or below passing. The default is false. | | `gradingschemeid` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `gradingscheme` | string | No | Optional grading scheme to use when calculating rollup (category, period, or course) grades. Grading Schemes are defined in Course Data. | | `itemid` | string | No | Vertical-bar-separated list of item IDs for which to get grades. Specify '\*' to get all gradable-item grade data. Specify '\*\*' (that's two asterisks) to get gradable and non-gradable item grade data. Non-gradable items typically don't have scores, but they do have time spent and completion statuses. If omitted, only rolled up (period, category, course) grades are returned. | | `scorm` | boolean | No | When true, returns the student’s submitted SCORM data as name-value pairs beneath each item element. The default is false. | | `zerounscored` | boolean | No | Specify true to treat all unscored gradable items as having a score of 0 when computing rolled-up grades. Specify false to ignore them. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "grades": {} } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment-Entity format. ##### grades This node conforms to the Grades format. ## Example This example retrieves gradebook detail for the user with ID 15002. **URL:** `?cmd=getusergradebook2&userid=15002` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "303137", "userid": "15002", "entityid": "268973", "domainid": "9909", "reference": "", "guid": "75150037-e781-468a-8bc8-2a8599c8989d", "flags": "131073", "status": 1, "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "entity": { "id": "268973", "entitytype": "C", "title": "Chemistry", "reference": "", "guid": "7d24a4e8-0de7-4bbe-9dd3-3b39feb2b9c8", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2010-08-17T06:00:00Z", "enddate": "2011-02-18T06:59:00Z", "days": 365, "term": "", "baseid": "0" }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 91.6282, "possible": 100, "letter": "A", "passingscore": 0.7, "complete": 0.9473684210526315, "seconds": 12945, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 594.875, "possible": 610, "letter": "A" }, { "id": "1", "name": "Quizzes", "achieved": 877, "possible": 1000, "letter": "B" } ] }, "final": { "status": 260, "scoreddate": "2010-08-19T19:29:42.41Z", "achieved": 54.8833, "possible": 60, "letter": "A" } } }, { "id": "111967", "userid": "15002", "entityid": "111965", "domainid": "9909", "reference": "", "guid": "69aae604-07b8-45ed-9a9a-3cf366a69982", "flags": "2097153", "status": 1, "startdate": "2010-02-08T07:00:00Z", "enddate": "2010-08-23T05:59:00Z", "entity": { "id": "111965", "entitytype": "S", "title": "Section 1", "reference": "", "guid": "256a0544-f0b7-4e84-884f-83c6e28d467b", "domainid": "9909", "schema": "2", "protection": 0, "type": "Range", "startdate": "2010-02-08T07:00:00Z", "enddate": "2010-08-09T05:59:00Z", "days": 0, "term": "", "baseid": "111963", "base": { "id": "111963", "title": "Biology", "reference": "", "guid": "f109fc25-9606-4a19-845d-cb42a5636db0", "domainid": "9909", "flags": "0" } }, "domain": { "id": "9909", "name": "State University" }, "grades": { "achieved": 1579.6053, "possible": 2000, "letter": "C+", "passingscore": 0.7, "complete": 0.5789473684210527, "seconds": 36325, "categories": { "category": [ { "id": "0", "name": "Homework", "achieved": 791, "possible": 1000, "letter": "C+" }, { "id": "1", "name": "Quizzes", "achieved": 788.6053, "possible": 1000, "letter": "C+" } ] } } } ] } } } ``` ## See Also - [Enrollment-Entity](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentEntity.md) - [Grades](https://api.agilixbuzz.com/docs/entry/Schema/Grades.md) - [GetEnrollmentGradebook2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollmentGradebook2.md) - [GetEntityGradebook3](https://api.agilixbuzz.com/docs/entry/Command/GetEntityGradebook3.md) --- # GetUserList > **Deprecated** — use [ListUsers](https://api.agilixbuzz.com/docs/entry/Command/ListUsers.md) instead. This command lists users. ## Request **Method:** GET **Rights:** ReadUser@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getuserlist` | | `name` | string | No | Optional user first or last name by which to filter the list. The wildcard “\*" is allowed in name. | | `username` | string | No | Optional username by which to filter the list. The wildcard “\*" is allowed in username. | | `reference` | string | No | Optional reference (external id) by which to filter the list. The wildcard “\*" is allowed in reference. | | `domainid` | id | No | Optional domain ID by which to filter the list. | | `query` | string | No | Optional query used to filter the list of users to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, name, username and reference are ignored. The query expression can include the following *xpath* fields defined in GetUser: - **/creationdate** - **/modifieddate** | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "users": { "user": [ { "userid": "id", "userguid": "guid", "firstname": "string", "lastname": "string", "domainid": "id", "domainname": "string", "userspace": "string", "username": "string", "email": "string", "reference": "string", "flags": "EntityFlags", "creationdate": "datetime", "data": {} } ] } } } ``` ### users #### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The user's ID. | | `userguid` | guid | The user's globally unique ID (guid). | | `firstname` | string | The user's first (given) name. | | `lastname` | string | The user's last (surname) name. | | `domainid` | id | The user's domain ID. | | `domainname` | string | The user's domain name. | | `userspace` | string | The user's domain userspace (login prefix). | | `username` | string | The user's username. | | `email` | string | The user's email address. | | `reference` | string | The user's reference field value. This is typically an external ID, such as the user's ID in an external SIS system. | | `flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | Bitwise OR of EntityFlags for the user. | | `creationdate` | datetime | The creation date and time of the user. | ##### data *(optional)* Optional free-form structured data. See User Data and Free Form Data for more details. ## Example This example assumes the domain with ID 24 exists with these users: **URL:** `?cmd=getuserlist&domainid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "users": { "user": [ { "userid": "1258", "firstname": "Arthur", "lastname": "Admin", "reference": "112233", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "admin", "email": "admin@myschool.edu", "flags": "0", "creationdate": "2007-11-12T23:04:48.11Z" }, { "userid": "26", "firstname": "Ally", "lastname": "Smith", "reference": "223344", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "author", "email": "ally.smith@myschool.edu", "flags": "0", "creationdate": "2007-06-07T17:17:16.567Z" }, { "userid": "1265", "firstname": "Sammy", "lastname": "Secretan", "reference": "123456", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "sammy", "email": "sammy@myschool.edu", "flags": "0", "creationdate": "2007-11-13T16:20:13.843Z" }, { "userid": "25", "firstname": "Sam", "lastname": "Foster", "reference": "234567", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "student", "email": "student@myschool.edu", "flags": "2", "creationdate": "2007-06-07T17:16:04.067Z" }, { "userid": "27", "firstname": "Tiger", "lastname": "Jones", "reference": "111222", "domainid": "24", "domainname": "Virtual School", "userspace": "vschool", "username": "teacher", "email": "tiger.jones@myschool.edu", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "data": { "blti": { "hideemail": "true", "hidefullname": "true" }, "boilerplatedata": { "boilerplate": [ { "type": "Grading", "title": "Grading number one", "path": "assets/profile/boilerplates3746d315-c19e-412a-dd93-b4fbd1f1b79c.xml" }, { "type": "Forum", "title": "Forum post one", "path": "assets/profile/boilerplatescecb54fd-f14e-95fc-8aa4-96223eaa10af.xml" } ] }, "profilepicture": { "$value": "assets/profile/profilepicture.png" }, "profilebio": { "$value": "assets/profile/profilebio.htm" } } } ] } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # GetWikiPage This command retrieves a wiki page from the server. ## Request **Rights:** Authenticated user with ReadCourse/ReadSection on the requested course (or observer access). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getwikipage` | | `entityid` | id | Yes | ID of the entity to which this wiki page belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this wiki page belongs. | | `groupid` | string | No | Optional group ID to which the wiki page belongs. | | `slug` | string | Yes | String that uniquely identifies the page within the item wiki. | | `version` | string | No | Version of the wiki page to retrieve. | | `fallback` | boolean | No | Whether to try the "(Initial)" group if the requested wiki page is not found. | ## Response **Content-Type:** text/plain **Content-Length:** content length ## See Also - [CopyWikiPages](https://api.agilixbuzz.com/docs/entry/Command/CopyWikiPages.md) - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [GetWikiPageList](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPageList.md) - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) --- # GetWikiPageList This command lists metadata for wiki pages. ## Request **Method:** GET **Rights:** Authenticated user with ReadCourse/ReadSection on the requested course or section (or observer access). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getwikipagelist` | | `entityid` | id | Yes | ID of the entity to which this wiki pages belong. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this wiki page belongs. | | `groupid` | string | No | Optional group ID to which the wiki page belongs. | | `slug` | string | No | Optional string by which to filter the list. Slug can contain the "\*" wildcard character. | | `allversions` | boolean | No | Specify *true* to to return all versions of the pages. Specify *false* to return just the latest version. The default is *false*. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "wikipages": { "wikipage": [ { "itemid": "id", "groupid": "string", "slug": "string", "size": "int", "creationdate": "datetime", "modifieddate": "datetime", "version": "string", "user": { "userid": "id", "firstname": "string", "lastname": "string", "agent": { "userid": "id", "firstname": "string", "lastname": "string" } } } ] } } } ``` ### wikipages #### wikipage | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | id | ID of the item (in the course manifest) to which this wiki page belongs. | | `groupid` | string | ID of the group to which this wiki page belongs. | | `slug` | string | ID that uniquely identifies the pae within the item wiki. | | `size` | int | Size, in bytes, of the wiki page. | | `creationdate` | datetime | Creation date and time of the wiki page. | | `modifieddate` | datetime | Last modified date and time of the wiki page. | | `version` | string | Version of the wiki page. | ##### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the user who edited the wiki page. | | `firstname` | string | First (given) name of the user who edited the wiki page. | | `lastname` | string | Last name (surname) of the user who edited the wiki page. | ###### agent *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | If the edit was made by a proxied user, the ID of the agent user who made the edit. | | `firstname` | string | If the edit was made by a proxied user, the first (given) name of the agent user. | | `lastname` | string | If the edit was made by a proxied user, the last name (surname) of the agent user. | ## See Also - [CopyWikiPages](https://api.agilixbuzz.com/docs/entry/Command/CopyWikiPages.md) - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [GetWikiPage](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPage.md) - [Proxy](https://api.agilixbuzz.com/docs/entry/Command/Proxy.md) - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) --- # GetWorkInProgress > **Deprecated** — use [GetWorkInProgress2](https://api.agilixbuzz.com/docs/entry/../Command/GetWorkInProgress2.md) instead. This command gets a work-in-progress file. ## Request **Method:** GET **Rights:** User who put the submission or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `getworkinprogress` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this student submission belongs. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within student submission. For example, specify a filepath to retrieve an attachment from within the student submission. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this student submission belongs. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Submission data from within the student submission. - **file** - Returns a single file from within the student submission. You must also specify filepath to identify which file to retrieve. - **zip** - Returns the entire student submission in a zip-compressed file containing the file meta.xml, which is a Submission, and any supporting attached files. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the student work-in-progress for enrollment with ID 4317 and for the item with ID "assign12". **URL:** `?cmd=getworkinprogress&enrollmentid=4317&itemid=assign12&packagetype=zip` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [PutWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/PutWorkInProgress.md) - [DeleteWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/DeleteWorkInProgress.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) --- # GetWorkInProgress2 This command gets a work-in-progress file. ## Request **Method:** GET **Rights:** User who put the submission or ReadGradebook@enrollmentid where enrollmentid refers to a section enrollment **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `GetWorkInProgress2` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this student submission belongs. | | `filepath` | string | No | When packagetype is file, filepath is the path to a file within student submission. For example, specify a filepath to retrieve an attachment from within the student submission. | | `inline` | bool | Yes | When packagetype is file, and inline is true, then the server uses an inline content disposition instead of attachment. An inline content disposition tells the browser to attempt to display the content inline in the browser as part of the web page. An attachment content disposition header tells the browser to download the file and use the operating system to display the content. Note that content types that are executed by the browser when inline are not allowed to be rendered inline due to security reasons. For these types this parameter will be ignored. This includes HTML, CSS, Javascript, XML, SVG, and other types. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this student submission belongs. | | `packagetype` | string | Yes | Specifies the format of the returned data. These are possible values: - **data** - Returns the Submission data from within the student submission. - **file** - Returns a single file from within the student submission. You must also specify filepath to identify which file to retrieve. - **filehistory** - Returns an array of metadata in the WorkInProgressFileInfo format, one for each version of each file. If *filepath* is specified then only metadata for that file is returned. Metadata for deleted files is returned. Metadata for the submission file *meta.xml* is returned. - **fileinfo** - Returns metadata in the WorkInProgressFileInfo format for the current version of each file. If *filepath* is specified then only metadata for that file is returned. Metadata for deleted files is not returned. Metadata for the submission file *meta.xml* is returned. - **zip** - Returns the entire student submission in a zip-compressed file containing the file meta.xml, which is a Submission, and any supporting attached files. | | `version` | int | No | Specifies the version of the file to retrieve. Applies to packagetype *fileinfo* (only when *filepath* is also specified), to packagetype *file*, and to packagetype *data*. When not specified the latest version of the file is used. | ## Response **Content-Type:** content type **Content-Length:** content length ## Example This sample retrieves the student work-in-progress for enrollment with ID 4317 and for the item with ID "assign12". **URL:** `?cmd=GetWorkInProgress2&enrollmentid=4317&itemid=assign12&packagetype=zip` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [WorkInProgressFileInfo](https://api.agilixbuzz.com/docs/entry/Schema/WorkInProgressFileInfo.md) - [PutWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/PutWorkInProgress.md) - [DeleteWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/DeleteWorkInProgress.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) --- # ImportData This command imports and converts various data formats. ## Request **Method:** POST **Rights:** Authenticated user. **Content-Type:** multipart/form-data or others **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `importdata` | | `from` | string | Yes | Data type of the incoming stream. Can be one of the following: - **delimited** - parse a tab or comma-delimited file into a structured format. - **qti** - convert a question following the QTI Schema into a corresponding question following the Question Schema. Currently supports the conversion of an <assessmentItem> conforming to the QTI 2.0 or 2.1 specification. | | `saveto` | string | No | Saves the output to a temporary resource for the user. Use with GetConvertedData. When this parameter is set the output to this command contains only the response element. | | `responsetype` | string | No | When posting from an iFrame, it may be difficult to set the accept headers. Specify text/xml to return XML else returns JSON. | | `filetype` | string | No | Output file type for use with *saveto*. Defaults to responsetype if no filetype is specified. | | `maxsize` | number | No | Max number of KB to import. The default is 1024, or 1MB. If the file is larger than *maxsize* the entire file will be rejected. | | `maxrows` | number | No | Used when *from* is set to **delimited**. Max number of rows to import. The default is 5000. If the file contains more than *maxrows* row, all the rows up to the limit will be imported. The last row will have an error attribute. | If the contentType is *multipart/form-data* than the first file in the form is converted, otherwise the post is assumed to be the file. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "Varies depending on from and saveto parameters": {} } } ``` ### Varies depending on from and saveto parameters ## Example Convert a csv file into a structured file. The uploaded file had this format: ``` Code,Name CHEM 105,General College Chemistry 1 CHEM 106,General College Chemistry 2 CHEM 107,General College Chemistry Laboratory CHEM 223,Quantitative and Qualitative Analysis ``` **URL:** `?cmd=importdata&from=delimited` **Response** (code: `OK`): ```json { "response": { "code": "OK", "file": { "row": [ { "col": [ { "$value": "Code" }, { "$value": "Name" } ] }, { "col": [ { "$value": "CHEM 105" }, { "$value": "General College Chemistry 1" } ] }, { "col": [ { "$value": "CHEM 106" }, { "$value": "General College Chemistry 2" } ] }, { "col": [ { "$value": "CHEM 107" }, { "$value": "General College Chemistry Laboratory" } ] }, { "col": [ { "$value": "CHEM 223" }, { "$value": "Quantitative and Qualitative Analysis" } ] } ] } } } ``` ## See Also - [GetConvertedData](https://api.agilixbuzz.com/docs/entry/Command/GetConvertedData.md) - [ExportData](https://api.agilixbuzz.com/docs/entry/Command/ExportData.md) --- # ListAssignableItems ListAssignableItems uses the *assignableitemsquery* attribute on the *folderid* item to list items in the course that may be assigned to *folderid*. If *assignableitemsquery* has no value, then ListAssignableItems does not return any items. ListAssignableItems does not return items that are currently visible to the student. ## Request **Method:** GET **Rights:** UpdateCourse@entityid or (Participate@entityid and entityid refers to an enrollment and the current user is the enrollment's user) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listassignableitems` | | `entityid` | id | Yes | ID of the entity that owns the *folderid* item. | | `folderid` | string | Yes | Item ID of the folder for which items should be listed. | | `showassigned` | string | No | Optional. When true, show items that are already assigned, otherwise, do not show those items. The default is false. | | `groupid` | string | No | Schema 4+: when the entity is a course, lists assignable items in the context of this group. The group ID is the string group identifier from the course's group definitions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "id": "string", "data": {} } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The item ID. | ##### data See Item Data Schema for more details. ## Example This example lists the assignable item of the PRACTICE folder in the 1234 enrollment. **URL:** `?cmd=listassignableitems&entityid=1234&folderid=PRACTICE` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "id": "Assignment12", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "PRACTICE" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 12" }, "href": { "$value": "Assets/assignment12.htm" } } } ] } } } ``` ## See Also - [AssignItem](https://api.agilixbuzz.com/docs/entry/Command/AssignItem.md) - [UnassignItem](https://api.agilixbuzz.com/docs/entry/Command/UnassignItem.md) - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) --- # ListCommandTokens This command lists all the command tokens created by a particular user and associated with a specified domain, course, group, or user. ## Request **Method:** GET **Rights:** ReadUser@scopeentityid and ControlUser@runasuserid (the runasuserid from the associated command token). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listcommandtokens` | | `onlyvalid` | boolean | No | Whether or not to exclude command tokens that are not yet valid or that are no longer valid (and thus cannot currently be used). The default value is false. | | `runasuserid` | id | No | The user the action will be run as (ie. the user that created the token). Defaults to the current user if not specified. | | `scopeentityid` | id | No | The domain, course, group, or user the desired command token(s) are associated with. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "response": { "code": "code", "message": "string", "commandtokens": { "commandtoken": [ { "commandtokenid": "id", "scopeentityid": "id", "description": "string", "startvalidity": "datetime", "endvalidity": "datetime", "version": "int", "code": "id", "runasuserid": "id", "allowunauthenticatedredemption": "boolean", "totalusecountlimit": "int", "userusecountlimit": "int", "peruserusecountlimit": "int", "codelength": "int", "user": [ { "userid": "id", "code": "id" } ], "action": { "request": { "cmd": "string" } }, "data": {} } ] } } } } ``` ### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | #### commandtokens ##### commandtoken | Attribute | Type | Description | |-----------|------|-------------| | `commandtokenid` | id | The ID of the command token which can be used to identify and possibly modify this command token in the future. | | `scopeentityid` | id | The ID of a domain, group, course, or user to which the command token's use will be restricted. | | `description` | string | A description of the purpose of the command token. (For future reference by you and other humans). | | `startvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will start being valid. Any attempt to use the code before this date/time will result in access being denied. The default value is the beginning of time. | | `endvalidity` | datetime | *(optional)* The date/time (in UTC) when the code will stop being valid. Any attempt to use the code after this date/time will result in access being denied. The default value is the end of time. | | `version` | int | The current version of the command token. | | `code` | id | *(optional)* The code (if perusercodes was false--otherwise there should be a list of users with user-specific codes). | | `runasuserid` | id | The ID of the user the action will be run as. | | `allowunauthenticatedredemption` | boolean | *(optional)* Whether or not this token can be redeemed by unauthenticated users. The default is false. | | `totalusecountlimit` | int | *(optional)* The total number of times the token may be used (not restricted if not specified or zero). | | `userusecountlimit` | int | *(optional)* The total number of unique users that may use the token (not restricted if not specified or zero). | | `peruserusecountlimit` | int | *(optional)* The total number of times any given user may use the token (not restricted if not specified or zero). | | `codelength` | int | The number of characters that should be in the code. | ###### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The ID of a user in the specified domain, group, or course (or specified directly). | | `code` | id | The code specific to this user. | ###### action ####### request | Attribute | Type | Description | |-----------|------|-------------| | `cmd` | string | The API command to run when the token is redeemed. | ###### data *(optional)* Optional free-form structured data. (See Free-form Data for more details.) ## Example This example lists both usable and now invalid command tokens associated with the domain with ID 4832. **URL:** `?cmd=listcommandtokens&scopeentityid=4832` **Response** (code: `OK`): ```json { "response": { "code": "OK", "commandtokens": { "commandtoken": [ { "commandtokenid": "587", "scopeentityid": "4832", "description": "Self Enrollment in Supplemental Course", "allowunauthenticatedredemption": "false", "peruserusecountlimit": "1", "codelength": "3", "code": "g4m", "action": { "request": { "cmd": "createenrollments", "requests": { "enrollment": { "domainid": "4832", "entityid": "78903", "userid": "$userid$", "flags": "131073", "status": "1", "schema": "2" } } } } }, { "commandtokenid": "588", "scopeentityid": "4832", "description": "Self Enrollment in Bonus Supplemental Course", "allowunauthenticatedredemption": "false", "totalusecountlimit": "10", "codelength": "5", "code": "u3#j", "action": { "request": { "cmd": "createenrollments", "requests": { "enrollment": { "domainid": "4832", "entityid": "78904", "userid": "$userid$", "flags": "131073", "status": "1", "schema": "2" } } } } } ] } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # ListCourses This command lists courses. ## Request **Method:** GET **Rights:** ReadCourse@domainid. When domainid is a user ID (a personal-course domain), the signed-on user may list their own personal courses; listing another user's personal courses requires both ReadCourse on that user's home domain and ReadUser on that user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listcourses` | | `domainid` | id | Yes | All listed courses accessible through domain privileges or enrollments must be in this domain. To search all domains for which the current user has rights, specify 0. | | `includedescendantdomains` | bool | No | Gets information for the specified domain and all descendant domains. Default is false. | | `limit` | int | No | Maximum number of courses to return. The default value is *100*. Pass *0* to not limit the number of courses to return. A large limit or no limit may cause a slow response time. When *domainid* is 0, then passing 0 for *limit* uses a limit of 25000 and passing more than 50000 for *limit* uses a limit of 50000. | | `show` | string | No | Specifies whether to show current courses, deleted courses, or both. Possible values are: - *current* - Show only current courses, i.e., courses that are not deleted. This is the default. - *deleted* - Show only deleted courses. - *active* - Show current courses that are not deactivated. - *all* - Show current and deleted courses. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListCourses* returns only course nodes. Possible values are: - *data[(...)]* - Includes the course's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. - *base* - Includes the course's base in the response if the a course has a base. - *base.data* - Includes the base's free-form structured data in the response. - *teachers* - Includes the list of teachers for the courses in the response. - *enrollmentmetrics* - Includes the course's enrollment metrics in the response. - *creationbyuser* - Includes information about the the user that created this course. - *modifiedbyuser* - Includes information about the the user that most recently modified or deleted this course. | | `text` | string | No | Filters the list of courses to courses where one of the following is true for the value of *text*: - The value exactly matches the course's id. - The value exactly matches the course's reference. - The value is a close match to the course's title. | | `query` | string | No | Optional query used to filter the list of courses to retrieve. The value for the query parameter follows the format defined at Free-Form Data Query. The query expression can include *xpath* fields for searchable metadata that is in the course's Free-form Data. For example, if you have a meta-subject node in your free-form structured data, you could use /meta-subject in the query expression. The query expression can include the following *xpath* fields defined in Course: - **/id** - **/title** - **/reference** - **/guid** - **/baseid** - **/startdate** - **/enddate** - **/term** - **/creationdate** - **/modifieddate** (Note that specifying the */modifieddate* field in your *xpath* query will search the course mainmodifieddate attribute.) | | `subscriptionmode` | string | No | Optional mode for listing courses authorized subscription through subscriptions. Specifiy one of the following: - *Include* - to list all authorized courses including those available through subscriptions. - *IncludeSkipDescendants* - to list the same as *Include*, but omitting courses that are in descendant domains of a subscription. - *Exclude* - do not list subscribed courses (the default). - *Exclusive* - only list subscribed courses. - *ExclusiveSkipDescendants* - to list the same as *Exclusive*, but omitting courses that are in descendant domains of a subscription. | | `subscriptiondomainid` | id | No | All listed courses accessible through subscriptions must be in this domain. To search all domains for which the current user has a subscription, omit this parameter. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "courses": { "course": [ { "data": {}, "history": [ { "parameters": "string", "course": [ {} ] } ], "domain": { "data": {} }, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "courseenrollmentmetrics": {}, "creationbyuser": { "firstname": "string", "lastname": "string" }, "modifiedbyuser": { "firstname": "string", "lastname": "string" } } ] } } } ``` ### courses #### course This node conforms to the Course format. ##### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### course *(optional)* This node conforms to the Course format. These are the results of the history query. ##### domain *(optional)* This node conforms to the Domain format. ###### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. ##### teachers *(optional)* ###### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ##### courseenrollmentmetrics *(optional)* This node conforms to the Course Enrollment Metrics format. ##### creationbyuser *(optional)* Information about the user that created this course. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that created this course. | | `lastname` | string | The last name of the user that created this course. | ##### modifiedbyuser *(optional)* Information about the user that modified or deleted this course. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that modified or deleted this course. | | `lastname` | string | The last name of the user that modified or deleted this course. | ## Example This example assumes the domain with ID 24 exists with these courses: **URL:** `?cmd=listcourses&domainid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "courses": { "course": [ { "id": "25", "title": "Crawling 101", "domainid": "24", "reference": "101", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "schema": "2", "baseid": "0", "type": "Range", "startdate": "2010-06-29T00:00:00Z", "enddate": "2010-07-29T00:00:00Z", "days": "365", "term": "2010 Summer", "protection": "0", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "title": "Walking 102", "domainid": "24", "reference": "102", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "schema": "2", "baseid": "0", "type": "Continuous", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "days": "128", "term": "", "protection": "0", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "title": "Running 103", "domainid": "24", "reference": "103", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "schema": "2", "baseid": "0", "type": "Continuous", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "days": "128", "term": "", "protection": "0", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [DeleteCourses](https://api.agilixbuzz.com/docs/entry/Command/DeleteCourses.md) - [GetCourse](https://api.agilixbuzz.com/docs/entry/Command/GetCourse.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # ListDomains This command lists domains. ## Request **Method:** GET **Rights:** ReadDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listdomains` | | `domainid` | id | Yes | All listed domains must be in this domain. To search all domains for which the current user has rights, specify 0. | | `includedescendantdomains` | bool | No | Gets information for the specified domain and all descendant domains. Default is false. | | `limit` | int | No | Maximum number of domains to return. The default value is *100*. Pass *0* to not limit the number of domains to return. A large limit or no limit may cause a slow response time. When *domainid* is 0, then passing 0 for *limit* uses a limit of 1000 and passing more than 10000 for *limit* uses a limit of 10000. Domains are always returned in domain ID order, so you can list domains in chunks by setting the limit and making subsequent requests with a query that gets domains with IDs greater than the last one listed in the previous request. | | `show` | string | No | Specifies whether to show current domains, deleted domains, or both. Possible values are: - *current* - Show only current domains, i.e., domains that are not deleted. This is the default. - *deleted* - Show only deleted domains. - *all* - Show current and deleted domains. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListDomains* returns only domain nodes. Possible values are: - *data* - Includes the domains's free-form structured data in the response. - *history(...)* - Includes the domain history in the response. See History Query for more details. - *creationbyuser* - Includes information about the the user that created this domain. - *modifiedbyuser* - Includes information about the the user that most recently modified or deleted this domain. | | `text` | string | No | Filters the list of domains to domains that match the value of *text* in one of several fields defined in Domain. For each listed domain one of the following must be true for the value of *text*: - The value exactly matches the domain's id. - The value exactly matches the domain's reference. - The value exactly matches the domain's userspace. - The value is a close match to the domain's name. | | `query` | string | No | Optional query used to filter the list of domains to retrieve. The value for the query parameter follows the format defined at Free-Form Data Query. The query expression can include *xpath* fields for searchable metadata that is in the domain's Free-form Data. For example, if you have a meta-subject node in your free-form structured data, you could use /meta-subject in the query expression. The query expression can include the following *xpath* fields defined in Domain: - **/id** - **/name** - **/userspace** - **/reference** - **/guid** - **/creationdate** - **/modifieddate** | | `includemanageddomains` | bool | No | Indicates whether or not the result list includes domains for which the user has the ManageLicense privilege. When this parameter is set to true, the server ignores the *select* parameter. Default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "domains": { "domain": [ { "data": {}, "history": [ { "parameters": "string", "domain": [ {} ] } ], "creationbyuser": { "firstname": "string", "lastname": "string" }, "modifiedbyuser": { "firstname": "string", "lastname": "string" } } ] } } } ``` ### domains #### domain This node conforms to the Domain format. ##### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### domain *(optional)* This node conforms to the Domain format. These are the results of the history query. ##### creationbyuser *(optional)* Information about the user that created this domain. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that created this domain. | | `lastname` | string | The last name of the user that created this domain. | ##### modifiedbyuser *(optional)* Information about the user that modified or deleted this domain. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that modified or deleted this domain. | | `lastname` | string | The last name of the user that modified or deleted this domain. | ## Example This example assumes the domain with ID 24 exists with these domains: **URL:** `?cmd=listdomains&domainid=24&limit=3` **Response** (code: `OK`): ```json { "response": { "code": "OK", "domains": { "domain": [ { "id": "25", "name": "Alpha", "userspace": "alpha", "parentid": "24", "reference": "alpha", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "name": "Bravo", "userspace": "bravo", "parentid": "24", "reference": "bravo", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "flags": "2", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "name": "Charlie", "userspace": "charlie", "parentid": "24", "reference": "charlie", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) --- # ListEnrollments This command lists enrollments. ## Request **Method:** GET **Rights:** ReadEnrollment@domainid. When domainid is a user ID (a personal-course domain), the signed-on user may list enrollments in their own personal courses; listing another user's requires both ReadEnrollment on that user's home domain and ReadUser on that user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listenrollments` | | `domainid` | id | Yes | All listed enrollments must be in this domain. To search all domains for which the current user has rights, specify 0. | | `includedescendantdomains` | bool | No | Gets information for the specified domain and all descendant domains. Default is false. | | `limit` | int | No | Maximum number of enrollments to return. The default value is *100*. Pass *0* to not limit the number of enrollments to return. A large limit or no limit may cause a slow response time. When *domainid* is 0, then passing 0 for *limit* uses a limit of 1000 and passing more than 10000 for *limit* uses a limit of 10000. Enrollments are always returned in enrollment ID order, so you can list enrollments in chunks by setting the limit and making subsequent requests with a query that gets enrollments with IDs greater than the last one listed in the previous request. | | `show` | string | No | Specifies whether to show current enrollments, deleted enrollments, or both. Possible values are: - *current* - Show only current enrollments, i.e., enrollments that are not deleted. This is the default. - *deleted* - Show only deleted enrollments. - *all* - Show current and deleted enrollments. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListEnrollments* returns only enrollment nodes. Possible values are: - *data* - Includes the enrollment's free-form structured data in the response. - *history(...)* - Includes the enrollment history in the response. See History Query for more details. - *course* - Includes course data in the response. - *course.data* - Includes the course's free-form structured data in the response. - *course.teachers* - Includes the list of teachers for the courses in the response. - *course.history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *user* - Includes user data in the response. - *user.data* - Includes the user's free-form structured data in the response. - *user.history(...)* - Includes the user history in the response. See History Query for more details. - *user.session* - Includes the user's most recently logged on and active session. - *metrics* - Includes the enrollment metrics in the response. - *metrics.history(...)* - Includes the enrollment metrics history in the response. See History Query for more details. - *creationbyuser* - Includes information about the the user that created this enrollment. - *modifiedbyuser* - Includes information about the the user that most recently modified or deleted this enrollment. | | `query` | string | No | Optional query used to filter the list of enrollments to retrieve. The value for the query parameter follows the format defined at Free-Form Data Query. The query expression can include *xpath* fields for searchable metadata that is in the enrollment's Free-form Data. For example, if you have a meta-subject node in your free-form structured data, you could use /meta-subject in the query expression. The query expression can include the following *xpath* fields defined in Enrollment: - **/id** - **/userid** - **/courseid** - **/reference** - **/guid** - **/status** - **/startdate** - **/enddate** - **/creationdate** - **/modifieddate** | | `userdomainid` | id | No | All listed enrollments must be associated with users in this domain. This parameter defaults to the value from the domainid parameter. | | `userquery` | string | No | Optional query used to filter the list of enrollments. The system applies this query to users associated with the enrollment. See ListUsers for more information. | | `usertext` | string | No | Optional text used to filter the list of enrollments. The system applies this text to users associated with the enrollment. See ListUsers for more information. | | `coursedomainid` | id | No | All listed enrollments must be associated with courses in this domain. This parameter defaults to the value from the domainid parameter. | | `coursequery` | string | No | Optional query used to filter the list of enrollments. The system applies this query to courses associated with the enrollment. See ListCourses for more information. | | `coursetext` | string | No | Optional text used to filter the list of enrollments. The system applies this text to courses associated with the enrollment. See ListCourses for more information. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "data": {}, "history": [ { "parameters": "string", "enrollment": [ {} ] } ], "course": { "data": {}, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "history": [ { "parameters": "string", "course": [ {} ] } ] }, "domain": {}, "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "session": {} }, "enrollmentmetrics": { "history": [ { "parameters": "string", "enrollmentmetricshistory": [ {} ] } ] }, "creationbyuser": { "firstname": "string", "lastname": "string" }, "modifiedbyuser": { "firstname": "string", "lastname": "string" } } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment format. ##### data *(optional)* Optional free-form structured data. See Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### enrollment *(optional)* This node conforms to the Enrollment format. These are the results of the history query. ##### course *(optional)* This node conforms to the Course format. ###### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ###### teachers *(optional)* ####### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to course.history | ####### course *(optional)* This node conforms to the Course format. These are the results of the course.history query. ##### domain *(optional)* This node conforms to the Domain format. ##### user *(optional)* This node conforms to the User format. ###### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to user.history | ####### user *(optional)* This node conforms to the User format. These are the results of the user.history query. ###### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session. ##### enrollmentmetrics *(optional)* This node conforms to the Enrollment Metrics format. This is the current enrollment metrics. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to metrics.history | ####### enrollmentmetricshistory *(optional)* This node conforms to the Enrollment Metrics format. These are the results of the metrics.history query. ##### creationbyuser *(optional)* Information about the user that created this enrollment. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that created this enrollment. | | `lastname` | string | The last name of the user that created this enrollment. | ##### modifiedbyuser *(optional)* Information about the user that modified or deleted this enrollment. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that modified or deleted this enrollment. | | `lastname` | string | The last name of the user that modified or deleted this enrollment. | ## Example This example assumes the domain with ID 24 exists with these enrollments: **URL:** `?cmd=listenrollments&domainid=24&limit=3` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "25", "userid": "16", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "userid": "17", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "userid": "18", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "privileges": "553239183360", "status": "10", "startdate": "2009-01-01T12:34:45.79Z", "enddate": "2019-01-01T12:34:45.79Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [DeleteEnrollments](https://api.agilixbuzz.com/docs/entry/Command/DeleteEnrollments.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # ListEnrollmentsByTeacher This command lists enrollments in courses where the specified user is a teacher. A user is considered a teacher in a course if they have an active teacher enrollment (an enrollment with ReadGradebook rights) in that course. ## Request **Method:** GET **Rights:** ReadUser@teacheruserid; ReadGradebook@courseid for each course in which teacheruserid is enrolled as a teacher. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listenrollmentsbyteacher` | | `teacheruserid` | id | No | Optional user ID of the teacher. The default is the ID of the currently signed on user. | | `teacherallstatus` | string | No | Optional. When true, all teacher enrollments of teacheruserid, whether active or not, are used to find courses. When false, only active or suspended enrollments are used. The default is false. ListEnrollmentsByTeacher considers teacher enrollments as inactive when they are more than three months after the end date, even if they have a status of active; use the *teacherdaysactivepastend* parameter to change this behavior. | | `teacherdaysactivepastend` | int | No | The number of days past the enrollment end date to continue treating teacher enrollments as active. When not supplied, ListEnrollmentsByTeacher considers teacher enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `privileges` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified privileges are returned in the response. | | `allstatus` | string | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. ListEnrollmentsByTeacher considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active; use the *daysactivepastend* parameter to change this behavior. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, ListEnrollmentsByTeacher considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `userid` | id | No | Optional user ID by which to filter the list. | | `select` | string | No | Comma-separated list of which data to return. By default, only enrollment nodes are returned. Possible values are: - *data[(...)]* - Includes the enrollment's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *history(...)* - Includes the enrollment history in the response. See History Query for more details. - *course* - Includes course data in the response. - *course.data* - Includes the course's free-form structured data in the response. - *course.teachers* - Includes the list of teachers for the courses in the response. - *course.history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *user* - Includes user data in the response. - *user.data[(...)]* - Includes the user's free-form structured data in the response.. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *user.history(...)* - Includes the user history in the response. See History Query for more details. - *user.session* - Includes the user's most recently logged on and active session. - *metrics* - Includes the enrollment metrics in the response. - *metrics.history(...)* - Include the enrollment metrics history in the response. See History Query for more details. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "data": {}, "history": [ { "parameters": "string", "enrollment": [ {} ] } ], "course": { "data": {}, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "history": [ { "parameters": "string", "course": [ {} ] } ] }, "domain": {}, "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "session": {} }, "enrollmentmetrics": { "history": [ { "parameters": "string", "enrollmentmetricshistory": [ {} ] } ] } } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment format. ##### data *(optional)* Optional free-form structured data. See Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### enrollment *(optional)* This node conforms to the Enrollment format. These are the results of the history query. ##### course *(optional)* This node conforms to the Course format. ###### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ###### teachers *(optional)* ####### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to course.history | ####### course *(optional)* This node conforms to the Course format. These are the results of the course.history query. ##### domain *(optional)* This node conforms to the Domain format. ##### user *(optional)* This node conforms to the User format. ###### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to user.history | ####### user *(optional)* This node conforms to the User format. These are the results of the user.history query. ###### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session ##### enrollmentmetrics *(optional)* This node conforms to the Enrollment Metrics format. This is the current enrollment metrics. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to metrics.history | ####### enrollmentmetricshistory *(optional)* This node conforms to the Enrollment Metrics format. These are the results of the metrics.history query. ## Example This example gets student enrollments in the courses that the current user teaches. **URL:** `?cmd=listenrollmentsbyeacher&privileges=1` **Response** (code: `OK`): ```json { "response": { "code": "OK", "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "25", "userid": "16", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "privileges": "2097153", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "userid": "17", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "privileges": "2097153", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "userid": "18", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "privileges": "2097153", "status": "10", "startdate": "2009-01-01T12:34:45.79Z", "enddate": "2019-01-01T12:34:45.79Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [GetUserEnrollmentList2](https://api.agilixbuzz.com/docs/entry/Command/GetUserEnrollmentList2.md) - [ListEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEnrollments.md) --- # ListEntityEnrollments This command lists enrollments in the specified entity. ## Request **Method:** GET **Rights:** ControlCourse|UpdateCourse|ReadGradebook@course when entityid refers to a course or entityid refers to a group in a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listentityenrollments` | | `entityid` | id | Yes | ID of the course or group for which to get the enrollment list. | | `privileges` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified privileges are returned in the response. | | `allstatus` | boolean | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. ListEntityEnrollments considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active; use the *daysactivepastend* parameter to change this behavior. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, ListEntityEnrollments considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `userid` | id | No | Optional user ID by which to filter the list. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListEnrollments* returns only enrollment nodes. Possible values are: - *data* - Includes the enrollment's free-form structured data in the response. - *history(...)* - Includes the enrollment history in the response. See History Query for more details. - *course* - Includes course data in the response. - *course.data* - Includes the course's free-form structured data in the response. - *course.teachers* - Includes the list of teachers for the courses in the response. - *course.history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *user* - Includes user data in the response. - *user.data* - Includes the user's free-form structured data in the response. - *user.history(...)* - Includes the user history in the response. See History Query for more details. - *user.session* - Includes the user's most recently logged on and active session. - *metrics* - Includes the enrollment metrics in the response. - *metrics.history(...)* - Includes the enrollment metrics history in the response. See History Query for more details. - *aiconversation* - Most recently started AI conversation for the specified itemid. Returns summary fields only; excludes conversation children (updates, interactions, attachments). Requires itemid. - *aiconversationtutor* - Most recently started Get Help (tutor) AI conversation for the specified itemid. Returns summary fields only; excludes conversation children (updates, interactions, attachments). Requires itemid. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "data": {}, "history": [ { "parameters": "string", "enrollment": [ {} ] } ], "course": { "data": {}, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "history": [ { "parameters": "string", "course": [ {} ] } ] }, "domain": {}, "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "session": {} }, "enrollmentmetrics": { "history": [ { "parameters": "string", "enrollmentmetricshistory": [ {} ] } ] }, "aiconversation": {}, "aiconversationtutor": {} } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment format. ##### data *(optional)* Optional free-form structured data. See Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### enrollment *(optional)* This node conforms to the Enrollment format. These are the results of the history query. ##### course *(optional)* This node conforms to the Course format. ###### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ###### teachers *(optional)* ####### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to course.history | ####### course *(optional)* This node conforms to the Course format. These are the results of the course.history query. ##### domain *(optional)* This node conforms to the Domain format. ##### user *(optional)* This node conforms to the User format. ###### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to user.history | ####### user *(optional)* This node conforms to the User format. These are the results of the user.history query. ###### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session ##### enrollmentmetrics *(optional)* This node conforms to the Enrollment Metrics format. This is the current enrollment metrics. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to metrics.history | ####### enrollmentmetricshistory *(optional)* This node conforms to the Enrollment Metrics format. These are the results of the metrics.history query. ##### aiconversation *(optional)* This node conforms to the AiConversation format, excluding conversation children (updates, interactions, attachments). ##### aiconversationtutor *(optional)* This node conforms to the AiConversation format, excluding conversation children (updates, interactions, attachments). ## Example This example assumes the entity with ID 268973 exists with these enrollments. **URL:** `?cmd=listentityenrollments&entityid=11` **Response** (code: `OK`): ```json { "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "25", "userid": "16", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "userid": "17", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "userid": "18", "courseid": "11", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "privileges": "553239183360", "status": "10", "startdate": "2009-01-01T12:34:45.79Z", "enddate": "2019-01-01T12:34:45.79Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListUserEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListUserEnrollments.md) - [ListEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEnrollments.md) --- # ListObjectiveSets This command gets a list of objective sets or objective map sets. ## Request **Method:** GET **Rights:** ReadObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listobjectivesets` | | `domainid` | id | Yes | All listed objective sets or map sets must be in this domain. To search all domains for which the current user has rights, specify 0. | | `includedescendantdomains` | bool | No | Gets information for the specified domain and all descendant domains. Default is false. | | `limit` | int | No | Maximum number of sets to return. The default value is *100*. Pass *0* to not limit the number of sets to return. A large limit or no limit may cause a slow response time. When *domainid* is 0, then passing 0 for *limit* uses a limit of 1000 and passing more than 10000 for *limit* uses a limit of 10000. Objectives are always returned in objective ID order, so you can list objectives in chunks by setting the limit and making subsequent requests with a query that gets objectives with IDs greater than the last one listed in the previous request. | | `show` | string | No | Specifies whether to show current sets, deleted sets, or both. Possible values are: - *current* - Show only current sets, i.e., sets that are not deleted. This is the default. - *deleted* - Show only deleted sets. - *all* - Show current and deleted sets. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListObjectiveSets* returns only set nodes. Possible values are: - *data* - Includes the set's free-form structured data in the response. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. | | `text` | string | No | Filters the list of sets to sets that match the value of *text* in one of several fields defined in Objective Set. For each listed set one of the following must be true for the value of *text*: - The value exactly matches the set's id. - The value exactly matches the set's reference. - The value is a close match to the set's name. | | `query` | string | No | Optional query used to filter the list of sets to retrieve. The value for the query parameter follows the format defined at Free-Form Data Query. The query expression can include *xpath* fields for searchable metadata that is in the set's Free-form Data. For example, if you have a meta-subject node in your free-form structured data, you could use /meta-subject in the query expression. The query expression can include the following *xpath* fields defined in Objective Set: - **/id** - **/name** - **/reference** - **/guid** - **/owner** - **/creationdate** - **/modifieddate** | | `map` | bool | No | If **true**, return a list of objective map sets; otherwise, return a list objective sets. The default value is **false**. | | `inherit` | bool | No | If **true**, include sets that have the inherit ObjectiveSetFlag from any ancestor domain of the current user's domain. The default value is **false**. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "sets": { "set": [ { "data": {}, "domain": { "data": {} } } ] } } } ``` ### sets #### set This node conforms to the Objective Set format. ##### data *(optional)* Optional free-form structured data. See Free-form Data for more details. ##### domain *(optional)* This node conforms to the Domain format. ###### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. ## Example This example assumes the domain with ID 24 exists with these sets: **URL:** `?cmd=listobjectivesets&domainid=24&limit=2` **Response** (code: `OK`): ```json { "response": { "code": "OK", "sets": { "set": [ { "id": "26", "name": "Michigan", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "owner": "Custom", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "name": "Hawaii", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "owner": "Custom", "flags": "0", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } ``` ## See Also - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveSets.md) - [GetObjectiveSet2](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSet2.md) - [UpdateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/UpdateObjectiveSets.md) --- # ListQuestions This command lists one or more questions in a course. ## Request **Method:** GET **Rights:** UpdateCourse@entityid or ReadCourseFull@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listquestions` | | `entityid` | id | Yes | ID of the course that owns the questions. | | `questionid` | idlist | No | Optional, bar-separated ID list of questions to get. If omitted, ListQuestions returns all questions for the specified entityid. If this parameter is supplied then the query parameter is ignored. | | `query` | string | No | Optional query used to filter the list of questions to retrieve. See Free-Form Data Query for more details. If this parameter is supplied, allversions is ignored. | | `count` | int | No | The max number of questions to return. This limit also applies to question versions. | | `allversions` | boolean | No | Specify true to retrieve metadata for all versions of the specified questions; or specify false to retrieve only the latest version's metadata. The default is false. This option only applies when listing all questions for a course, or when specific question IDs were provided. | | `itemid` | string | No | Optional ID of an assessment item. The command will list the questions of the assessment. If this parameter is supplied then the query parameter is ignored. | | `groupid` | string | No | Optional ID of a group within the course. When specified together with itemid, the command returns the question list as it appears on the group's overridden version of the assessment item (group inheritance). Only applies when entityid refers to a course on schema 4 or higher; ignored otherwise. If the group does not exist or the course schema does not support group inheritance, the call falls back to the course-level questions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "response": { "code": "code", "message": "string", "question": [ { "questionid": "id", "modifieddate": "datetime", "partial": "boolean", "resourceentityid": "id", "round": "boolean", "schema": "int", "score": "double", "version": "string" } ] } } } ``` ### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | #### question See Question Schema for a detailed description of the returned XML for a question | Attribute | Type | Description | |-----------|------|-------------| | `questionid` | id | ID of the question. | | `modifieddate` | datetime | Last modified date and time of the question. | | `partial` | boolean | *(optional)* True if partial credit is allowed for this question; otherwise false. The default is false. | | `resourceentityid` | id | ID of the entity from which this question retrieves its resources, such as images. resourceentityid is different than entityid when this question is in a base course and entityid refers to a course derived from the base. See CopyCourses for more details about derivative courses. | | `round` | boolean | *(optional)* True to round partial scores down to the next whole number, otherwise false. The default is false. | | `schema` | int | All newly created questions should have value 2. (Schema 1 is an obsolete schema supported only for backwards compatibility.) | | `score` | double | *(optional)* The points possible for this question. If omitted, uses the assessment default score. | | `version` | string | The version of the question. | ## Example This example lists questions from the course whose ID is 2838. **URL:** `?cmd=listquestions&entityid=2838` **Response** (code: `OK`): ```json { "response": { "code": "OK", "question": [ { "questionid": "2f58ddabe0e343eda629b405759be802", "version": "1", "schema": "2", "body": { "$value": "Discuss the position of King George." }, "interaction": { "type": "essay", "flags": "4" } }, { "questionid": "44cead279c0f46dcab0c2d4ff1ce5c67", "version": "1", "schema": "2", "body": { "$value": "Discuss the position of George Washington." }, "interaction": { "type": "essay", "flags": "4" } } ] } } ``` ## See Also - [Question Schema](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) --- # ListRejectedLTIGrades This command returns a list of the rejected grades from a LTI source when there is already a score directly set by a teacher and no resubmission is allowed. The rejected grades are sorted in descending order by the date and time that the rejection of the LTI grade occurred. ## Request **Method:** GET **Rights:** ReadGradebook@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrejectedltigrades` | | `enrollmentid` | id | Yes | Enrollment ID of student user for which to get the rejected LTI grades. | | `itemid` | string | Yes | ID of the item for which to get the rejected LTI grades. | | `responseversion` | int | Yes | Version of the response related to the score directly set by the teacher that caused the LTI grades to be rejected. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "grades": { "grade": [ { "modifieddate": "datetime", "rawachieved": "double", "rawpossible": "double", "achieved": "double", "possible": "double", "passing": "boolean", "user": { "firstname": "string", "lastname": "string", "reference": "string", "userid": "id", "username": "string" } } ] } } } ``` ### grades #### grade | Attribute | Type | Description | |-----------|------|-------------| | `modifieddate` | datetime | The date and time that the rejection of the LTI grade occurred. | | `rawachieved` | double | *(optional)* The number of actual points achieved for this item, if any, as sent from the LTI source. | | `rawpossible` | double | *(optional)* The number of actual points possible for this item, if any, as sent from the LTI source. | | `achieved` | double | *(optional)* The points achieved value, if any, for this item. | | `possible` | double | *(optional)* The points possible value, if any, for this item. | | `passing` | boolean | *(optional)* *true* if the score is greater than or equal to the passing score for the item and enrollment. Otherwise omitted. | ##### user | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | First name of the admin user who generated this grade on behalf of the LTI source. | | `lastname` | string | Last name of the admin user who generated this grade on behalf of the LTI source. | | `reference` | string | *(optional)* Reference field value of the user who generated this grade. | | `userid` | id | ID of the user who generated this grade. | | `username` | string | Username of the user who generated this grade. | ## Example This example retrieves the rejected LTI grades for the enrollment with ID 6165, item with ID "assign12" and response version 2. **URL:** `?cmd=listrejectedltigrades&enrollmentid=6165&itemid=assign12&responseversion=2` **Response** (code: `OK`): ```json { "response": { "code": "OK", "grades": { "grade": [ { "modifieddate": "2026-03-31T19:48:57.44Z", "rawachieved": "3", "rawpossible": "4", "achieved": "75", "possible": "100", "passing": "true", "user": { "userid": "9911", "firstname": "Sally", "lastname": "Anderson", "username": "domainadmin", "reference": "" } }, { "modifieddate": "2026-03-30T07:31:16.893Z", "rawachieved": "2", "rawpossible": "4", "achieved": "50", "possible": "100", "user": { "userid": "9911", "firstname": "Sally", "lastname": "Anderson", "username": "domainadmin", "reference": "" } } ] } } } ``` ## See Also - [GetGradeHistory](https://api.agilixbuzz.com/docs/entry/Command/GetGradeHistory.md) --- # ListRestorableAnnouncements This command lists domainor course announcements that have been deleted and can be restored. ## Request **Method:** GET **Rights:** PostDomainAnnouncements|ReadDomain@entityid when entityid is a domain ID, OR UpdateCourse|ReadGradebook|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid when entityid is a course ID **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorableannouncements` | | `entityid` | id | Yes | ID of the domain or course that owns the restorable announcements. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "announcements": { "announcement": [ { "entityid": "id", "path": "string", "version": "string", "size": "int", "creationdate": "datetime", "modifieddate": "datetime", "flags": "ResourceFlags" } ] } } } ``` ### announcements #### announcement | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the announcement's owning domain or course. | | `path` | string | The announcement path. | | `version` | string | Current version of the announcement. | | `size` | int | Size, in bytes, of the announcement. | | `creationdate` | datetime | Creation date of the announcement. | | `modifieddate` | datetime | Last modified date and time of the announcement. | | `flags` | [ResourceFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResourceFlags.md) | The ResourceFlags value for the announcement. | ## Example This example lists the restorable announcements from the domain whose ID is 9909. **URL:** `?cmd=listrestorableannouncements&entityid=9909` **Response** (code: `OK`): ```json { "response": { "code": "OK", "announcements": { "announcement": [ { "entityid": "9909", "path": "0bd9430f7016434caf1f7de488df068c.zip", "version": "2", "size": 1075, "creationdate": "2009-02-17T18:37:00.033Z", "modifieddate": "2009-02-17T21:00:36.383Z", "flags": 7 }, { "entityid": "9909", "path": "108f31b4554f4693a0eaec74a98d79a0.zip", "version": "2", "size": 1081, "creationdate": "2008-11-20T16:46:56.877Z", "modifieddate": "2009-02-17T21:00:41.727Z", "flags": 7 }, { "entityid": "9909", "path": "2e6f7d4b1b3b4fe1bfa0d36e5e31008c.zip", "version": "2", "size": 1073, "creationdate": "2009-02-17T18:23:38.237Z", "modifieddate": "2009-02-17T21:24:38.32Z", "flags": 7 } ] } } } ``` ## See Also - [DeleteAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/DeleteAnnouncements.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) - [RestoreAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/RestoreAnnouncements.md) --- # ListRestorableDocuments This command lists documents that have been deleted and can be restored. ## Request **Method:** GET **Rights:** GradeExam|GradeAssignment|GradeDiscussion@sectionid refered by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorabledocuments` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which the documents belong. | | `itemid` | id | Yes | ID of the item (in the course manifest) to which the documents belong. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "documents": {} } } ``` ### documents ## See Also - [DeleteDocuments](https://api.agilixbuzz.com/docs/entry/Command/DeleteDocuments.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) - [RestoreDocuments](https://api.agilixbuzz.com/docs/entry/Command/RestoreDocuments.md) --- # ListRestorableItems This command lists items that have been deleted and can be restored. ## Request **Method:** GET **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorableitems` | | `entityid` | id | Yes | ID of the course that owns the items. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "items": { "item": [ { "id": "id", "deletedby": "id", "deleteddate": "date", "data": {} } ] } } } ``` ### items #### item | Attribute | Type | Description | |-----------|------|-------------| | `id` | id | ID of the restorable item. | | `deletedby` | id | ID of the user that deleted the item. | | `deleteddate` | date | Date that the item was deleted. | ##### data Free form structured data that describes the item. See Item Data for more details. ## Example This example lists the restorable items from the course whose ID is 4378. **URL:** `?cmd=listrestorableitems&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "items": { "item": [ { "id": "DEFAULT", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 12" }, "href": { "$value": "Assets/assignment12.htm" } } } ] } } } ``` ## See Also - [DeleteItems](https://api.agilixbuzz.com/docs/entry/Command/DeleteItems.md) - [PutItems](https://api.agilixbuzz.com/docs/entry/Command/PutItems.md) - [RestoreItems](https://api.agilixbuzz.com/docs/entry/Command/RestoreItems.md) --- # ListRestorableMessages This command lists messages that have been deleted from a entity and can be restored. ## Request **Method:** GET **Rights:** GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorablemessages` | | `entityid` | id | Yes | ID of the entity (course or section) that owns the messages. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "messages": { "message": [ { "messageid": "string", "entityid": "id", "itemid": "string", "groupid": "string", "version": "string", "magnitude": "int", "status": "Normal|Hidden" } ] } } } ``` ### messages #### message | Attribute | Type | Description | |-----------|------|-------------| | `messageid` | string | The message ID. | | `entityid` | id | ID of the entity that owns the message. | | `itemid` | string | The ID of the item to which this message belongs. | | `groupid` | string | *(optional)* The ID of the forum group. | | `version` | string | Version of this message. | | `magnitude` | int | The message magnitude. Larger numbers mean larger files. | | `status` | string | *(optional)* View status of this message. | ## Example This example lists the restorable messages from the entity whose ID is 4378. **URL:** `?cmd=listrestorablemessages&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "messages": { "message": [ { "messageid": "89b2b64f710949018d5cf618a0bb681e.zip", "entityid": "4378", "itemid": "FORUM1", "groupid": "group1", "version": "2", "magnitude": 2 } ] } } } ``` ## See Also - [DeleteMessages](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessages.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) - [RestoreMessages](https://api.agilixbuzz.com/docs/entry/Command/RestoreMessages.md) --- # ListRestorableQuestions This command lists questions that have been deleted and can be restored. ## Request **Method:** GET **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorablequestions` | | `entityid` | id | Yes | ID of the course that owns the questions. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "questions": { "question": [ { "questionid": "id", "version": "string", "score": "double", "partial": "boolean", "round": "boolean" } ] } } } ``` ### questions #### question See Question Schema for a detailed description of the returned XML for a question | Attribute | Type | Description | |-----------|------|-------------| | `questionid` | id | | | `version` | string | | | `score` | double | | | `partial` | boolean | | | `round` | boolean | | ## Example This example lists the restorable questions from the course whose ID is 4378. **URL:** `?cmd=listrestorablequestions&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "questions": { "question": [ { "questionid": "2f58ddabe0e343eda629b405759be802", "version": "1", "schema": "2", "partial": true, "round": true, "answer": {}, "body": { "$value": "Match the animals with their sounds." }, "interaction": { "type": "match", "flags": 2, "choice": [ { "id": "1", "body": { "$value": "dog" }, "answer": { "$value": "woof" } }, { "id": "2", "body": { "$value": "cat" }, "answer": { "$value": "meow" } }, { "id": "3", "body": { "$value": "cow" }, "answer": { "$value": "moo" } } ] } }, { "questionid": "44cead279c0f46dcab0c2d4ff1ce5c67", "version": "1", "schema": "2", "partial": false, "groups": { "group": [ { "$value": "Group A" } ] }, "answer": { "value": [ { "$value": "1" } ] }, "body": { "$value": "Is this a multiple choice question?" }, "interaction": { "type": "choice", "flags": 2, "choice": [ { "id": "1", "body": { "$value": "Yes" } }, { "id": "2", "body": { "$value": "No" } } ] } } ] } } } ``` ## See Also - [DeleteQuestions](https://api.agilixbuzz.com/docs/entry/Command/DeleteQuestions.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) - [RestoreQuestions](https://api.agilixbuzz.com/docs/entry/Command/RestoreQuestions.md) --- # ListRestorableResources This command lists resources that have been deleted and can be restored. ## Request **Method:** GET **Rights:** UpdateCourse@entityid when entityid refers to a course; UpdateDomain@entityid when entityid refers to a domain; UpdateUser@entityid when entityid refers to a user. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorableresources` | | `entityid` | id | Yes | ID of the entity (course, domain, or user) to list restorable resources for. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "resources": { "resource": [ { "entityid": "id", "path": "string", "version": "string", "size": "int", "flags": "ResourceFlags", "status": "Normal|Hidden", "creationdate": "datetime", "modifieddate": "datetime" } ] } } } ``` ### resources #### resource | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the entity that owns this resource. | | `path` | string | The resource path. | | `version` | string | The resource version. | | `size` | int | The size, in bytes, of the resource. | | `flags` | [ResourceFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResourceFlags.md) | A bitwise OR of the resource's ResourceFlags. | | `status` | Normal|Hidden | *(optional)* The view status of the resource. | | `creationdate` | datetime | The resource creation date and time. | | `modifieddate` | datetime | The resource's last modified date and time. | ## Example This example lists the restorable resources for the entity whose ID is 4378. **URL:** `?cmd=listrestorableresources&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "resources": { "resource": [ { "entityid": "4378", "path": "Assets/index.html", "version": "1", "size": 4430, "flags": 2, "creationdate": "2008-04-0T06:52:22.587Z", "modifieddate": "2008-04-20T06:52:22.587Z" } ] } } } ``` ## See Also - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [RestoreResources](https://api.agilixbuzz.com/docs/entry/Command/RestoreResources.md) --- # ListRestorableWikiPages This command lists wiki pages that have been deleted from a course or section and can be restored. ## Request **Method:** GET **Rights:** Participate@entityid or GradeForum@entityid when entityid refers to a section; UpdateCourse@entityid when entityid refers to a course. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listrestorablewikipages` | | `entityid` | id | Yes | ID of the entity to list restorable wiki pages. | | `itemid` | id | Yes | ID of the wiki item from the course manifest. | | `groupid` | string | No | Optional group ID to which the wiki pages belong. | | `slug` | string | No | String that uniquely identifies the page within the item wiki. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "wikipages": { "wikipage": [ { "itemid": "id", "groupid": "string", "slug": "string", "version": "string", "size": "int", "modifieddate": "datetime", "flags": "ResourceFlags", "user": { "userid": "id", "firstname": "string", "lastname": "string", "agent": { "userid": "id", "firstname": "string", "lastname": "string" } } } ] } } } ``` ### wikipages #### wikipage | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | id | ID of the item (in the course manifest) to which this wiki page belongs. | | `groupid` | string | ID of the group to which this wiki page belongs. | | `slug` | string | ID that uniquely identifies the pae within the item wiki. | | `version` | string | Version of the wiki page. | | `size` | int | Size, in bytes, of the wiki page. | | `modifieddate` | datetime | Last modified date and time of the wiki page. | | `flags` | [ResourceFlags](https://api.agilixbuzz.com/docs/entry/Enum/ResourceFlags.md) | A bitwise OR of the wiki page's ResourceFlags. | ##### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the user who edited the wiki page. | | `firstname` | string | First (given) name of the user who edited the wiki page. | | `lastname` | string | Last name (surname) of the user who edited the wiki page. | ###### agent *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | If the edit was made by a proxied user, the ID of the agent user who made the edit. | | `firstname` | string | If the edit was made by a proxied user, the first (given) name of the agent user. | | `lastname` | string | If the edit was made by a proxied user, the last name (surname) of the agent user. | ## Example This example lists the restorable wiki pages from the section whose ID is 4378. **URL:** `?cmd=listrestorablewikipages&entityid=4378` **Response** (code: `OK`): ```json { "response": { "code": "OK", "wikipages": { "wikipage": [ { "itemid": "H0V3O", "groupid": "", "slug": "Home", "version": "3", "size": 44, "creationdate": "2010-03-05T17:50:44.88Z", "modifieddate": "2010-03-05T18:30:30.037Z", "flags": 6, "user": { "userid": "46216", "firstname": "Kate", "lastname": "Johnson" } } ] } } } ``` ## See Also - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) - [RestoreWikiPages](https://api.agilixbuzz.com/docs/entry/Command/RestoreWikiPages.md) --- # ListRoles This command lists roles defined for a domain. Each domain can specify one or more roles. The roles for a domain include all of the roles inherited from any of the ancestor domains. ## Request **Method:** GET **Rights:** ReadDomain@domainid or ReadUser@domainid or ReadCourse@domainid or ReadEnrollment@domainid or Proxy@domainid, or the user the session is acting as belongs to the specified domain or one of its subdomains, or holds the Teacher persona in the specified domain or one of its ancestors. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listroles` | | `domainid` | id | Yes | The domain ID to return roles for. The roles for a domain include all of the roles inherited from any of the ancestor domains. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "roles": { "role": [ {} ] } } } ``` ### roles #### role This node conforms to the Role format. This additionally includes the domain name. ## Example This example gets the roles associated with domain ID 24. **URL:** `?cmd=listroles&domainid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "roles": { "role": [ { "id": "7898", "name": "Admin", "domainid": "24", "domainname": "East High", "reference": "", "guid": "AF7ABB74-43DB-4334-80A5-833F2AF59C57", "privileges": "131073", "flags": "0", "creationdate": "20012-11-10T16:45:10.123Z", "creationby": "28839", "modifieddate": "20012-11-10T16:45:10.123Z", "modifiedby": "28839", "version": "1" }, { "id": "8343", "name": "Student", "domainid": "24", "domainname": "East High", "reference": "", "guid": "6F3D61EA-9A41-4D54-8579-7C99323653A1", "privileges": "131073", "flags": "0", "creationdate": "20012-11-10T16:45:10.123Z", "creationby": "28839", "modifieddate": "20012-11-10T16:45:10.123Z", "modifiedby": "28839", "version": "1" } ] } } } ``` ## See Also - [CreateRole](https://api.agilixbuzz.com/docs/entry/Command/CreateRole.md) - [DeleteRole](https://api.agilixbuzz.com/docs/entry/Command/DeleteRole.md) - [GetRole](https://api.agilixbuzz.com/docs/entry/Command/GetRole.md) - [UpdateRole](https://api.agilixbuzz.com/docs/entry/Command/UpdateRole.md) --- # ListUserEnrollments This command lists enrollments for the specified user. ## Request **Method:** GET **Rights:** ReadUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listuserenrollments` | | `userid` | id | Yes | User for whom to list enrollments. | | `allstatus` | boolean | No | Optional. When true, all enrollments, whether active or not, are returned in the response. When false, only active or suspended enrollments are returned. The default is false. ListUserEnrollments considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active; use the *daysactivepastend* parameter to change this behavior. | | `entityid` | id | No | Optional entity ID by which to filter the list. | | `privileges` | enum-RightsFlags | No | Optional, bitwise-OR of RightsFlags by which to filter the list. When present, only enrollments with the specified privileges are returned in the response. | | `daysactivepastend` | int | No | The number of days past the enrollment end date to continue treating enrollments as active. When not supplied, ListUserEnrollments considers enrollments as inactive when they are more than three months after the end date, even if they have a status of active. | | `query` | string | No | Optional query used to filter the list of courses. See ListCourses for more information. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListEnrollments* returns only enrollment nodes. Possible values are: - *data* - Includes the enrollment's free-form structured data in the response. - *history(...)* - Includes the enrollment history in the response. See History Query for more details. - *course* - Includes course data in the response. - *course.data* - Includes the course's free-form structured data in the response. - *course.teachers* - Includes the list of teachers for the courses in the response. - *course.history(...)* - Includes the course history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *user* - Includes user data in the response. - *user.data* - Includes the user's free-form structured data in the response. - *user.history(...)* - Includes the user history in the response. See History Query for more details. - *user.session* - Includes the user's most recently logged on and active session. - *metrics* - Includes the enrollment metrics in the response. - *metrics.history(...)* - Includes the enrollment metrics history in the response. See History Query for more details. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "enrollments": { "enrollment": [ { "data": {}, "history": [ { "parameters": "string", "enrollment": [ {} ] } ], "course": { "data": {}, "teachers": { "teacher": [ { "enrollmentid": "id", "privileges": "RightsFlag", "roleid": "id", "userid": "id", "firstname": "string", "lastname": "string", "email": "string" } ] }, "history": [ { "parameters": "string", "course": [ {} ] } ] }, "domain": {}, "user": { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "session": {} }, "enrollmentmetrics": { "history": [ { "parameters": "string", "enrollmentmetricshistory": [ {} ] } ] } } ] } } } ``` ### enrollments #### enrollment This node conforms to the Enrollment format. ##### data *(optional)* Optional free-form structured data. See Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### enrollment *(optional)* This node conforms to the Enrollment format. These are the results of the history query. ##### course *(optional)* This node conforms to the Course format. ###### data *(optional)* Optional free-form structured data. See Course Data and Free-form Data for more details. ###### teachers *(optional)* ####### teacher | Attribute | Type | Description | |-----------|------|-------------| | `enrollmentid` | id | The teacher's enrollment ID. | | `privileges` | [RightsFlag](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlag.md) | The teacher enrollment's privileges. | | `roleid` | id | The teacher enrollment's role ID. | | `userid` | id | The teacher's user ID. | | `firstname` | string | The teacher's first name. | | `lastname` | string | The teacher's last name. | | `email` | string | The teacher's email. | ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to course.history | ####### course *(optional)* This node conforms to the Course format. These are the results of the course.history query. ##### domain *(optional)* This node conforms to the Domain format. ##### user *(optional)* This node conforms to the User format. ###### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to user.history | ####### user *(optional)* This node conforms to the User format. These are the results of the user.history query. ###### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session ##### enrollmentmetrics *(optional)* This node conforms to the Enrollment Metrics format. This is the current enrollment metrics. ###### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to metrics.history | ####### enrollmentmetricshistory *(optional)* This node conforms to the Enrollment Metrics format. These are the results of the metrics.history query. ## Example This example assumes the entity with ID 268973 exists with these enrollments. **URL:** `?cmd=listuserenrollments&userid=12` **Response** (code: `OK`): ```json { "response": { "code": "OK", "response": { "code": "OK", "enrollments": { "enrollment": [ { "id": "25", "userid": "12", "courseid": "13", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "26", "userid": "12", "courseid": "14", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dab", "privileges": "552692744192", "status": "10", "startdate": "1753-01-01T00:00:00Z", "enddate": "9999-12-31T00:00:00Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" }, { "id": "27", "userid": "12", "courseid": "15", "domainid": "24", "reference": "", "guid": "9e3b3650-37da-4324-bf96-716c851c8dac", "privileges": "553239183360", "status": "10", "startdate": "2009-01-01T12:34:45.79Z", "enddate": "2019-01-01T12:34:45.79Z", "flags": "0", "firstactivitydate": "0001-01-01T00:00:00Z", "lastactivitydate": "0001-01-01T00:00:00Z", "creationdate": "2007-06-07T17:17:46.3Z", "creationby": "2", "modifieddate": "2007-06-07T17:17:46.3Z", "modifiedby": "2", "version": "1" } ] } } } } ``` ## See Also - [Enrollment-User](https://api.agilixbuzz.com/docs/entry/Schema/EnrollmentUser.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEnrollments.md) --- # ListUsers This command lists users. ## Request **Method:** GET **Rights:** ReadUser@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `listusers` | | `domainid` | id | Yes | All listed users must be in this domain. To search all domains for which the current user has rights, specify 0. | | `includedescendantdomains` | bool | No | Gets information for the specified domain and all descendant domains. Default is false. | | `limit` | int | No | Maximum number of users to return. The default value is *100*. Pass *0* to not limit the number of users to return. A large limit or no limit may cause a slow response time. When *domainid* is 0, then passing 0 for *limit* uses a limit of 25000 and passing more than 50000 for *limit* uses a limit of 50000. | | `show` | string | No | Specifies whether to show current users, deleted users, or both. Possible values are: - *current* - Show only current users, i.e., users that are not deleted. This is the default. - *deleted* - Show only deleted users. - *all* - Show current and deleted users. | | `select` | string | No | Comma-separated list of which data to return. By default, *ListUsers* returns only user nodes. Possible values are: - *data[(...)]* - Includes the user's free-form structured data in the response. An optional filter may be specified that reduces the actual data that is returned. See Data Filter for more details. - *history(...)* - Includes the user history in the response. See History Query for more details. - *domain* - Includes domain data in the response. - *domain.data* - Includes the domain's free-form structured data in the response. - *session* - Includes the user's most recently logged on and active session. - *currentpersonas* - Includes the user's current personas. - *creationbyuser* - Includes information about the the user that created this user. - *modifiedbyuser* - Includes information about the the user that most recently modified or deleted this user. | | `text` | string | No | Filters the list of users to users that match the value of *text* in one of several fields defined in User. For each listed user one of the following must be true for the value of *text*: - The value exactly matches the user's id. - The value exactly matches the user's reference. - The value exactly matches the user's username. - The value exactly matches the user's email address. - The value is a close match to the user's first name or last name. | | `query` | string | No | Optional query used to filter the list of users to retrieve. The value for the query parameter follows the format defined at Free-Form Data Query. The query expression can include *xpath* fields for searchable metadata that is in the user's Free-form Data. For example, if you have a meta-subject node in your free-form structured data, you could use /meta-subject in the query expression. The query expression can include the following *xpath* fields defined in User: - **/id** - **/firstname** - **/lastname** - **/reference** - **/guid** - **/username** - **/email** - **/lastpasswordchangeddate** - **/firstlogindate** - **/lastlogindate** - **/currentpersona** - **/creationdate** - **/modifieddate** - **/active** (0 or 1, the bitwise NOT of the deactivated bit in the user's entity flags) | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "users": { "user": [ { "data": {}, "history": [ { "parameters": "string", "user": [ {} ] } ], "domain": { "data": {} }, "session": {}, "creationbyuser": { "firstname": "string", "lastname": "string" }, "modifiedbyuser": { "firstname": "string", "lastname": "string" } } ] } } } ``` ### users #### user This node conforms to the User format. ##### data *(optional)* Optional free-form structured data. See User Data and Free-form Data for more details. ##### history *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `parameters` | string | The parameters passed to history | ###### user *(optional)* This node conforms to the User format. These are the results of the history query. ##### domain *(optional)* This node conforms to the Domain format. ###### data *(optional)* Optional free-form structured data. See Domain Data and Free-form Data for more details. ##### session *(optional)* This node conforms to the Session format, and describes the user's most recently logged on and active session ##### creationbyuser *(optional)* Information about the user that created this user. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that created this user. | | `lastname` | string | The last name of the user that created this user. | ##### modifiedbyuser *(optional)* Information about the user that modified or deleted this user. | Attribute | Type | Description | |-----------|------|-------------| | `firstname` | string | The first name of the user that modified or deleted this user. | | `lastname` | string | The last name of the user that modified or deleted this user. | ## Example This example assumes the domain with ID 24 exists with these users: **URL:** `?cmd=listusers&domainid=24` **Response** (code: `OK`): ```json { "response": { "code": "OK", "users": { "user": [ { "id": "1258", "firstname": "Arthur", "lastname": "Admin", "reference": "112233", "guid": "e41614be-5659-4d99-b03f-7615fe876f9e", "username": "admin", "email": "admin@myschool.edu", "domainid": "24", "flags": "0", "creationby": "10", "creationdate": "2007-11-12T23:04:48.11Z", "modifiedby": "10", "modifieddate": "2007-11-12T23:04:48.11Z", "version": "1", "lastpasswordchangeddate": "2007-11-13T24:04:48.11Z", "firstlogindate": "2007-11-12T24:04:48.11Z", "lastlogindate": "2007-11-13T23:04:48.11Z" }, { "id": "27", "firstname": "Tiger", "lastname": "Jones", "reference": "111222", "guid": "9e3b3650-37da-4324-bf96-716c851c8daa", "username": "teacher", "email": "tiger.jones@myschool.edu", "domainid": "24", "flags": "0", "creationby": "10", "creationdate": "2007-06-07T17:17:46.3Z", "modifiedby": "10", "modifieddate": "2007-10-21T23:10:01.14Z", "version": "5", "lastpasswordchangeddate": "2007-11-12T24:04:48.11Z", "firstlogindate": "2007-06-18T24:04:48.11Z", "lastlogindate": "2007-11-12T13:51:44.29Z" } ] } } } ``` ## See Also - [CreateUsers2](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers2.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # Login2 > **Deprecated** — use [Login3](https://api.agilixbuzz.com/docs/entry/Login3.md) instead. API users should now authenticate with OAuth 2.0 Application Identity rather than this command. Login3, named as the replacement above, is the like-for-like successor only for interactive username/password sign-in; API integrations should move to OAuth instead. OAuth is more secure than password-based login because the private key never leaves your system and there is no shared secret to intercept. It also works in domains where MFA is required for administrative accounts, since it authenticates via signed JWT assertions rather than a username and password. See OAuth 2.0 Application Identity for details. This command authenticates a user on the server and initiates a session for them. A token is returned in the response, along with the number of minutes before the token will expire. This token provides access to subsequent calls to API commands within the specified time period, and must be passed as the \_token parameter on the GET portion of the URL or in the XML or JSON part of a POST command in the same context where the API command is specified. Each API command will extend the expiration of the session associated with the token. If you just need to extend the session and don't want to make a API call, the ExtendSession command will do nothing other than extend the session. The use of cookies for authentication tokens has been deprecated due to security concerns from cross-site scripting issues which are not fully addressed by the CORS standard. Keeping the token value returned from Login2 and passing it on to each subsequent API command as \_token helps prevent cross-site scripting because the value isn't automatically sent with every cross-site request. Passing tokens in an Authorization: Bearer header is also now supported. Unlike most other API commands, callers must support several different error codes returned by this function in different ways. InvalidCredentials will be returned if the username/password combination is not valid. DeactivatedUserOrDomain will be returned if the user or domain was explicitly deactivated. LicenseLimitExceeded will be returned if the domain's license limit is exceeded for one or more of the user's corresponding personas. NoLicense will be returned if the domain doesn't have a license and no ancestor domain has a license. LicenseExpired will be returned if the domain's license has expired. LicenseNotYetValid will be returned if the domain's license is not yet valid (ie. it's before the start date of the license). PasswordExpired will be returned if the user's password has expired due to the domain's password policy and the user must change their password (in this case, UpdatePassword is the only DLAP function that will be allowed for this user until their password is changed). AccountLockout will be returned if the user's account has been locked out due to too many contiguous password login failures. LoginMethodNotAllowed will be returned if the account doesn't allow the type of login being attempted (password login is not allowed for SSO-only users, for example). PasswordPolicyRequirementsNotMet will be returned if the password does not meet the active password policy requirements, and the policy is configured to force a password reset under these conditions. SecondFactorRequired will be returned if the user has opted for multi-factor authentication and the password was correct, but the caller must provide the seond factor to complete authentication. SecondFactorConfigurationNowRequired will be returned if the password policy now requires a second factor but the user has not yet configured the second factor. The user will be logged in, but will only be allowed to configure a second factor before doing anything else. For this API, a warning may also be returned to the caller as a "warning" property on the response object. The value of this property will indicate what the problem is. For login, the only possibly value is currently PasswordPolicyRequirementsNotMet, which indicates that the login succeeded, but the password policy is configured to warn users when the password they use to login no longer meets the active policy requirements, either because the policy changed, because the entropy calculation changed and caused this password to fall below the minimum level, or because the password was found in one or more publicly-available account breaches. An appropriate warning should be issued indicating that it is recommended that the user change their password, but the user should be allowed to proceed after the warning. ## Request **Method:** POST **Content-Type:** application/json **Request body (JSON):** ```json { "request": { "cmd": "login2", "username": "string", "password": "string", "token": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `login2` | Yes | | | `username` | string | Yes | Identifies the user attempting to log in. It must be formatted as userspace/username, where userspace is the userspace of the domain that contains the user account, and username is the user's username in that domain. | | `password` | string | Yes | Password for username. | | `token` | string | No | An optional authorization token that identifies a session that the server should continue to use. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string", "token": "string", "authenticationexpirationminutes": "int" } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | User ID of the logged-in user. | | `username` | string | Username of the logged-in user. | | `firstname` | string | First name of the logged-in user. | | `lastname` | string | Last name of the logged-in user. | | `email` | email | E-mail address of the logged-in user. | | `domainid` | id | ID of the domain that contains the logged-in user. | | `domainname` | string | Name of the domain that contains the logged-in user. | | `userspace` | string | Userspace of the domain that contains the logged-in user. | | `token` | string | This is the authentication token which must be kept and passed to subsequent API commands in order to authenticate the account making the request. | | `authenticationexpirationminutes` | int | The number of minutes until the specified authentication token will timeout unless there are subsequent calls that affect it. The token expiration will automatically be extended when any calls other than ExtendSession are made, the token will be immediately expired when Logout is called, and the token may be explicitly revoked by an administrator prior to the normal expiration. This value is returned so that clients know how often they need to call ExtendSession or some other function to keep their authentication from expiring under normal circumstances. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAccountLocked](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAccountLocked.md) | During the request | The failed attempt crossed the domain's lockout threshold. | | [AuthAdminAuthenticated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminAuthenticated.md) | During the request | The authenticated account holds an active Administrator role. | | [AuthLoginFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthLoginFailed.md) | During the request | The supplied password did not match. Only password logins produce this event. | | [AuthPasswordRisk](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthPasswordRisk.md) | During the request | The login succeeded with a password that is known to be compromised or that does not satisfy the domain's password policy. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | A sign-in extends the domain's activity range, and user activity also cascades up to the domain. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | A successful sign-in updates the user's login dates. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | A successful password authentication starts a session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **Request body:** ```json { "request": { "cmd": "login2", "username": "mydomain/administrator", "password": "password" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "4379", "username": "administrator", "firstname": "System", "lastname": "Administrator", "email": "administrator@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "token": "SYC-ihGJ|ML0jX11juQd8d8BtTPAuWC", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [ExtendSession](https://api.agilixbuzz.com/docs/entry/Command/ExtendSession.md) - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) - [Proxy](https://api.agilixbuzz.com/docs/entry/Command/Proxy.md) - [OAuth 2.0 Application Identity](https://api.agilixbuzz.com/docs/entry/Concept/OAuth.md) --- # Login3 API users should now authenticate with OAuth 2.0 Application Identity rather than this command. It is more secure than password-based login because the private key never leaves your system and there is no shared secret to intercept. It also works in domains where MFA is required for administrative accounts, since it authenticates via signed JWT assertions rather than a username and password, and it won't be disabled by Pwned password checks that might disable the integration in the event of the account's password being added to the database of known breached (pwned) passwords. See OAuth 2.0 Application Identity for details. This command should now be used ONLY for interactive username/password sign-in: Buzz itself, the API Console, and brief administrative steps such as the sample code's one-time setup scripts. New API integrations must not use it, and existing integrations should migrate to OAuth (interim guidance for integrations that have not yet migrated appears below). This command authenticates a user on the server and initiates a session for them. A token is returned in the response, along with the number of minutes before the token will expire. This token provides access to subsequent calls to API commands within the specified time period, and must be passed as the \_token parameter on the GET portion of the URL or in the XML or JSON part of a POST command in the same context where the API command is specified. Each API command will extend the expiration of the session associated with the token. If you just need to extend the session and don't want to make a API call, the ExtendSession command will do nothing other than extend the session. The use of cookies for authentication tokens has been deprecated due to security concerns from cross-site scripting issues which are not fully addressed by the CORS standard. Keeping the token value returned from Login3 and passing it on to each subsequent API command as \_token helps prevent cross-site scripting because the value isn't automatically sent with every cross-site request. Passing tokens in an Authorization: Bearer header is also now supported. Service accounts should use OAuth 2.0 Application Identity rather than this command. For an existing integration that has not moved yet: login once at the beginning of processing and obtain a token that will last for the duration of processing rather than logging in before every call. Alternatively, they can specify an infinite duration to obtain a token that lasts forever and then only use that token in the code rather than logging in at all. However, such tokens can be used by anyone, so care must be taken to keep them secret. They should be stored in a secure token storage system, and should \*never\* be put into source control. Note that this request MUST use POST. Unlike most other API commands, callers must support several different error and warning codes returned by this function in different ways. InvalidCredentials will be returned if the username/password combination is not valid. DeactivatedUserOrDomain will be returned if the user or domain was explicitly deactivated. LicenseLimitExceeded will be returned if the domain's license limit is exceeded for one or more of the user's corresponding personas. NoLicense will be returned if the domain doesn't have a license and no ancestor domain has a license. LicenseExpired will be returned if the domain's license has expired. LicenseNotYetValid will be returned if the domain's license is not yet valid (ie. it's before the start date of the license). PasswordExpired will be returned if the user's password has expired due to the domain's password policy and the user must change their password (in this case, UpdatePassword is the only API function that will be allowed for this user until their password is changed). AccountLockout will be returned if the user's account has been locked out due to too many contiguous password login failures. LoginMethodNotAllowed will be returned if the account doesn't allow the type of login being attempted (password login is not allowed for SSO-only users, for example). PasswordPolicyRequirementsNotMet will be returned if the password does not meet the active password policy requirements, and the policy is configured to force a password reset under these conditions. SecondFactorRequired will be returned if the user has opted for multi-factor authentication and the password was correct, but the caller must provide the seond factor to complete authentication. SecondFactorConfigurationNowRequired will be returned if the password policy now requires a second factor but the user has not yet configured the second factor. The user will be logged in, but will only be allowed to configure a second factor before doing anything else. For this API, a warning may also be returned to the caller as a "warning" property on the response object. The value of this property will indicate what the problem is. For login, the only possibly value is currently PasswordPolicyRequirementsNotMet, which indicates that the login succeeded, but the password policy is configured to warn users when the password they use to login no longer meets the active policy requirements, either because the policy changed, because the entropy calculation changed and caused this password to fall below the minimum level, or because the password was found in one or more publicly-available account breaches. An appropriate warning should be issued indicating that it is recommended that the user change their password, but the user should be allowed to proceed after the warning. ## Request **Method:** POST **Content-Type:** application/json **Request body (JSON):** ```json { "request": { "cmd": "login3", "username": "string", "password": "string", "expireseconds": "int", "newsession": "bool", "token": "string", "remembermfa": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `login3` | Yes | | | `username` | string | Yes | Identifies the user attempting to log in. It must be formatted as userspace/username, where userspace is the userspace of the domain that contains the user account, and username is the user's username in that domain. | | `password` | string | Yes | Password for username. | | `expireseconds` | int | No | The number of seconds the session should last before expiring. If a negative value is specified, the token will not expire until Logout is called with the token. If not specified the default timeout of 900 seconds (15 minutes) will be used. | | `newsession` | bool | No | Whether or not to create a new session even if there is already an existing session for this user. If not specified, the default is false, so sessions will be reused. When sessions are reused, a single call to logout will end the session whose token was returned by multiple login calls. To prevent a session from being reused, set *reusable* to false when calling Logout. | | `token` | string | No | An optional authorization token that identifies a session that the server should continue to use. | | `remembermfa` | string | No | An optional remember MFA token that identifies the device as one which has been previously authorized. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string", "token": "string", "authenticationexpirationminutes": "int" }, "remembermfa": { "token": "string", "expirationminutes": "int" } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | User ID of the logged-in user. | | `username` | string | Username of the logged-in user. | | `firstname` | string | First name of the logged-in user. | | `lastname` | string | Last name of the logged-in user. | | `email` | email | E-mail address of the logged-in user. | | `domainid` | id | ID of the domain that contains the logged-in user. | | `domainname` | string | Name of the domain that contains the logged-in user. | | `userspace` | string | Userspace of the domain that contains the logged-in user. | | `token` | string | This is the authentication token which must be kept and passed to subsequent API commands in order to authenticate the account making the request. | | `authenticationexpirationminutes` | int | The number of minutes until the specified authentication token will timeout unless there are subsequent calls that affect it. The token expiration will automatically be extended when any calls other than ExtendSession are made, the token will be immediately expired when Logout is called, and the token may be explicitly revoked by an administrator prior to the normal expiration. This value is returned so that clients know how often they need to call ExtendSession or some other function to keep their authentication from expiring under normal circumstances. | ### remembermfa | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | The possibly refreshed remember MFA token. | | `expirationminutes` | int | The number of minutes until the specified remember MFA token will timeout unless there are subsequent calls that affect it. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAccountLocked](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAccountLocked.md) | During the request | The failed attempt crossed the domain's lockout threshold. | | [AuthAdminAuthenticated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminAuthenticated.md) | During the request | The authenticated account holds an active Administrator role. | | [AuthLoginFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthLoginFailed.md) | During the request | The supplied password did not match. Only password logins produce this event. | | [AuthPasswordRisk](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthPasswordRisk.md) | During the request | The login succeeded with a password that is known to be compromised or that does not satisfy the domain's password policy. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | A sign-in extends the domain's activity range, and user activity also cascades up to the domain. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | A successful sign-in updates the user's login dates. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | A successful password authentication starts a session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example A successful login. **Request body:** ```json { "request": { "cmd": "login3", "username": "mydomain/administrator", "password": "password" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "4379", "username": "administrator", "firstname": "System", "lastname": "Administrator", "email": "administrator@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "token": "SYC-ihGJ|ML0jX11juQd8d8BtTPAuWC", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [ExtendSession](https://api.agilixbuzz.com/docs/entry/Command/ExtendSession.md) - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) - [Proxy](https://api.agilixbuzz.com/docs/entry/Command/Proxy.md) - [OAuth 2.0 Application Identity](https://api.agilixbuzz.com/docs/entry/Concept/OAuth.md) --- # Logout This command terminates the session state for an authenticated user. ## Request **Method:** POST **Content-Type:** application/json **Request body (JSON):** ```json { "request": { "cmd": "logout", "reusable": "bool", "clearallbrowserdata": "bool" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `logout` | Yes | | | `reusable` | bool | No | Whether or not this session can be reused by Login3 when *newsession* is false. If not specified, the default is true, so this session can be reused. | | `clearallbrowserdata` | bool | No | Whether or not to clear all browser data associated with this site. If true, instructs the browser to clear all cookies, local storage, and cache for this site as part of the logout process. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | With timeout set to *false*. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **Request body:** ```json { "request": { "cmd": "logout" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) --- # MergeCourses This command merges the deltas from a derivative course into its immediate base course. It then removes the deltas so that the derivative and the master are identical. ## Request **Method:** POST **Rights:** UpdateCourse@courseid, UpdateCourse@baseid of course identified by courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `mergecourses` | **Request body (JSON):** ```json { "requests": { "course": [ { "courseid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `course.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the derivative course to merge. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | For the courses whose records the merge changes; this form completes within the request. | | [CourseResourceChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceChanged.md) | During the request | For each content file the merged course had overridden where its base course holds a live file at the path; the write is made to the base course. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each content file the merged course had added that its base course had no file for; the write is made to the base course. | | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | When the merged course had deleted a file its base course holds; the deletion is applied to the base course. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example merges the derative course with ID 8874 into its base course. **URL:** `?cmd=mergecourses` **Request body:** ```json { "requests": { "course": [ { "courseid": "8874" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CopyCourses](https://api.agilixbuzz.com/docs/entry/Command/CopyCourses.md) --- # NavigateItem This command attempts to navigate a user's enrollment to a course item. If the enrollment has permission to view the item, *NavigateItem* returns item information that enables complete display of the item and its content. If the enrollment does not have permission to view the item, the response includes the reasons why. If the item is an *AssetLink* or *CustomActivity* with an *href* to an LTI-enabled web site (see the *lti* element in Item Data), you should include the parameters that begin with "*lti*", which are recommended by the LTI specification. See www.imsglobal.org/LTI for more details about LTI. If the item content includes references to LTILINK variables, the response will replace these variables with launch URL to view LTI item content in an external window. ## Request **Method:** POST **Rights:** ReadCourse@courseid referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `ltil` | | `enrollmentid` | id | Yes | ID of the enrollment that owns the item specified by *itemid*. | | `itemid` | string | Yes | Item ID of the item to navigate to. | | `password` | string | No | If the item is password protected (has *exampassword2* or *password2* element in Item Data), *password* is required and is the end-user's entered password for the item. | | `utcoffset` | int | No | The number of minutes, positive or negative, from UTC time that the end-user's timezone is. The default is 0. *NavigateItem* uses *utcoffset* when determining access to items that have an *availabledate* in Item Data. | | `groupid` | string | No | Schema 4+: when enrollmentid is a course, navigates the item using the course manifest with group-specific item overrides merged in for the specified group. The group ID is the string group identifier from the course's group definitions. Ignored when enrollmentid is a real enrollment, since a real enrollment's manifest already reflects its own group memberships. | | `ltidr` | string | No | The publically accessible Buzz API server root URL. The default is the root URL of this *NavigateItem* call. *NavigateItem* uses *ltidr* to construct *ltihref* and other LTI-required URLs in the response. If your call to *NavigateItem* is on a non-public URL, such as a URL visible only behind your firewall, you must specify *ltidr*; otherwise, omit *ltidr* and use the default. | | `ltilc` | string | No | The value to specify for *launch\_presentation\_css\_url* in the LTI launch. | | `ltilh` | string | No | The value to specify for *launch\_presentation\_height* in the LTI launch. | | `ltill` | string | No | The value to specify for *launch\_presentation\_locale* in the LTI launch. If omitted, the LTI launch specifies *en-US*. | | `ltilr` | string | No | The value to specify for *launch\_presentation\_return\_url* in the LTI launch. | | `ltilt` | string | No | The value to specify for *launch\_presentation\_document\_target* in the LTI launch. If omitted, the LTI launch specifies *iframe*. | | `ltilw` | string | No | The value to specify for *launch\_presentation\_width* in the LTI launch. | | `ltioe` | string | No | The ID of an observer enrollment. You specify this parameter when a teacher is attempting to view an LTI activity for a specific student. (LTI tools do not necessarily support that scenario, but for those that do, adding this parameter enables them to do it.) *ltioe* is the observer's enrollment ID. *NavigateItem* launches the LTI activity passing item information from the item owned by *enrollmentid*, it passes the user information from enrollment identified by *ltioe*, and it adds the *ext\_observed\_result\_sourcedid*, *ext\_observed\_user\_id*, and *ext\_observed\_user\_external\_id* values from *enrollmentid* so that the LTI tool provider can display the student's work to the teacher, let the teacher assign a score, and then store the teacher's score back in the system. | | `ltitc` | string | No | The value to specify for *tool\_consumer\_info\_product\_family\_code* in the LTI launch. | | `ltitg` | string | No | The value to specify for *tool\_consumer\_instance\_guid* in the LTI launch. | | `ltitn` | string | No | The value to specify for *tool\_consumer\_instance\_name* in the LTI launch. | | `ltitu` | string | No | The value to specify for *tool\_consumer\_instance\_url* in the LTI launch. | | `ltitv` | string | No | The value to specify for *tool\_consumer\_info\_version* in the LTI launch. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "navigate": { "status": { "success": {}, "accessdenied": {}, "completesequentialitem": { "itemid": "string", "title": "string" }, "completegate": { "itemid": "string", "title": "string" }, "passwordprotected": {}, "notavailableuntil": { "date": "datetime", "universaldate": "datetime" }, "masteryitem": [ { "itemid": "string", "title": "string" } ], "masteryobjective": [ { "guid": "string", "id": "string", "title": "string", "item": [ { "id": "string", "title": "string" } ] } ] }, "data": { "attachments": { "attachment": [ { "href": "string", "entityid": "id", "type": "file|googledrivedoc", "name": "string" } ] }, "content": { "$value": "string" }, "resourceentityid": { "$value": "id" }, "href": { "$value": "string" }, "ltihref": { "$value": "string" }, "surveyurl": { "$value": "string" }, "template": { "entityid": "id", "$value": "string" }, "template2": { "href": "string", "entityid": "id", "type": "file|googledrivedoc", "name": "string" } }, "enrollment": { "status": "EnrollmentStatus", "startdate": "datetime", "enddate": "datetime" } } } } ``` ### navigate #### status ##### success *(optional)* Present when end-user may access this item. ##### accessdenied *(optional)* Present when end-user may not access this item, such as when the input *itemid* is invalid, or the item is marked *hiddenfromstudent* in its *Item Data*. ##### completesequentialitem *(optional)* Present when end-user must complete a previous item before they may access this item. | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | string | The ID of the item that the user must complete. | | `title` | string | The title of the item that the user must complete. | ##### completegate *(optional)* Present when end-user must complete an item that acts as a gate to this item before they may access this item. | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | string | The ID of the gating item that the user must complete. | | `title` | string | The title of the gating item that the user must complete. | ##### passwordprotected *(optional)* Present when the input *password* is not the correct password. ##### notavailableuntil *(optional)* Present when item's *availabledate* is in the future. | Attribute | Type | Description | |-----------|------|-------------| | `date` | datetime | The date and time that the item becomes available. If the seconds part of the available time is zero, then *NavigateItem* shifts this value by the input *utcoffset*. | | `universaldate` | datetime | The date the item is available (in universal time; i.e., not shifted by *utcoffset*.). | ##### masteryitem *(optional)* Present when the user must receive a passing score on another item before they may access this item. | Attribute | Type | Description | |-----------|------|-------------| | `itemid` | string | The ID of the mastery item that the user must complete. | | `title` | string | The title of the mastery item that the user must complete. | ##### masteryobjective *(optional)* Present when the user must have a rolled-up passing score (see *objectivemasterythreshold* in Course Data) on a learning objective before they may access this item. | Attribute | Type | Description | |-----------|------|-------------| | `guid` | string | Guid of the learning objective that the user must master before accessing this item. | | `id` | string | The ID of the learning objective that the user must master before accessing this item. | | `title` | string | The text of the learning objective that the user must master before accessing this item. | ###### item *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `id` | string | The ID of the restricted item. | | `title` | string | The title of the restricted item. | #### data When the user may access this item, the *data* element is present and contains information about the item. ##### attachments *(optional)* If the item has *attachments* in its *Item Data*, this node contains references to the attachments. ###### attachment A single attachment to this item. | Attribute | Type | Description | |-----------|------|-------------| | `href` | string | Path to the attachment resource. | | `entityid` | id | *(optional)* ID of the entity that contains the attachment resource. NavigateItem omits *entityid* when the owning entity also owns the item or when type is *googledrivedoc*. | | `type` | string | *(optional)* Identifies the type of the attachment. Possible values are *file* and *googledrivedoc*. NavigateItem omits *type* when its value is the default *file* value. | | `name` | string | *(optional)* When *type* is *googledrivedoc*, this is the name of the attached Google document. | ##### content *(optional)* ##### resourceentityid *(optional)* ##### href *(optional)* ##### ltihref *(optional)* ##### surveyurl *(optional)* ##### template *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | *(optional)* ID of the entity that contains the template resource. *NavigateItem* omits *entityid* when the owning entity also owns the item. | ##### template2 *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `href` | string | Path to course resource, or Google Docs file URL, to use as the template for this item. Uses the template defined using *template2* in this item's Item Data. | | `entityid` | id | *(optional)* The ID of the entity of that owns the template resource when it is not owned by the same entity that owns the item. Uses the template defined using *template2* in this item's Item Data. | | `type` | string | *(optional)* Identifies the type of this template. Uses the template defined using *template2* in this item's Item Data. Possible values are: - **file** - The template is a course resource file and *href* identifies the path to the attached file. This is the default. - **googledrivedoc** - The template is a document stored in Google™ Drive and *href* contains the URL to the document. The default is *file*. | | `name` | string | *(optional)* The original file name (display name) of the template. Uses the template defined using *template2* in this item's Item Data. | #### enrollment | Attribute | Type | Description | |-----------|------|-------------| | `status` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | EnrollmentStatus for the enrollment. | | `startdate` | datetime | Date that the enrollment begins. | | `enddate` | datetime | Date that the enrollment ends. | ## Example This example attempts to navigate to a password-protected item, quiz1, without specifying the correct password. **URL:** `?cmd=navigateitem&enrollmentid=156873&itemid=quiz1&utcoffset=-6` **Response** (code: `OK`): ```json { "response": { "code": "OK", "navigate": { "status": { "passwordprotected": {} } } } } ``` ## See Also - [Item Data](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) --- # Proxy This command starts a session as a different user. The data retrieved from this session appears as if the proxy user had logged in. Both the user and proxy user are recorded for any modifications. This command is intended for interactive use by administrators and support staff to troubleshoot user issues. This command should not be used in automation or integrations. Automation and integrations should perform operations directly using their own authentication. If the userid value is malformed or syntactically invalid, BadRequest is returned. To prevent user enumeration, all other failure conditions — including the target user not existing and the caller lacking Proxy rights — return AccessDenied, with two exceptions: when the target user's domain is deactivated, DeactivatedUserOrDomain is returned; and when the target user account is disabled, DoesNotExist is returned. Callers cannot distinguish between a user that does not exist and one they lack rights to proxy as, except when they explicitly specify a domain as part of the user specification, and they don't have Proxy rights in that domain. Note that in order to prevent privilege escalation, users who have Proxy rights will be denied access to proxy as another user in their domain when that user has any domain privilege in any domain they do not. Further, if the target user has a cross-domain enrollment with rights other than ReadCourse/Section and Participate in any other domain, the user requesting to proxy must also have Proxy rights in the domain of that enrollment. Proxy does not "stack" authentication, so if this API is called with a token that is already proxying, this API will return a new token that proxies the original proxy-authorized user as the newly specified user, the same as if Unproxy was called and then Proxy was called after that. Unproxy always returns to the original proxy-authorized user. ## Request **Method:** POST **Rights:** Proxy@user domain **Request body (JSON):** ```json { "request": { "cmd": "proxy", "userid": "id", "noazt": "bool" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `proxy` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user to proxy as. | | `noazt` | bool | No | Indicates that the server should not set an authentication cookie. If not specified or false, uses the settings for the current session. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string", "agent": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string" } } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the current user | | `username` | string | User name | | `firstname` | string | First name | | `lastname` | string | Last name | | `email` | email | Email | | `domainid` | id | Domain ID | | `domainname` | string | Domain name | | `userspace` | string | Userspace | #### agent | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | ID of the agent user | | `username` | string | User name | | `firstname` | string | First name | | `lastname` | string | Last name | | `email` | email | Email | | `domainid` | id | Domain ID | | `domainname` | string | Domain name | | `userspace` | string | Userspace | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthProxyLoginFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthProxyLoginFailed.md) | During the request | The proxy login was denied because the caller lacks the required privileges. | | [AuthProxyLoginStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthProxyLoginStarted.md) | During the request | The proxy login was authorized and the impersonation session began. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | A proxy session updates the proxied user's login dates. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | A proxy session is a session in its own right. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **Request body:** ```json { "request": { "cmd": "proxy", "userid": ".//student1" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "4453", "username": "student1", "firstname": "Sally", "lastname": "Student", "email": "student1@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "agent": { "userid": "4379", "username": "administrator", "firstname": "System", "lastname": "Administrator", "email": "administrator@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "token": "SYC-ihGJ|ML0jX11juQd8d8BtTPAuWC", "authenticationexpirationminutes": "15" } } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [Unproxy](https://api.agilixbuzz.com/docs/entry/Command/Unproxy.md) --- # PutAnnouncement This command posts an announcement to the domain or course specified by entityid. The announcement is the POST content of this request and should be in the format as described in Announcement. ## Request **Method:** POST **Rights:** PostDomainAnnouncements@entityid when entityid is a domain ID, OR UpdateCourse|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid when entityid is a course ID **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putannouncement` | | `entityid` | id | Yes | ID of the domain or course to post the announcement to. | | `path` | string | Yes | Unique path to the zip-compressed announcement file. Although not enforced, to guarantee uniqueness you should name your file guid.zip, where guid is a 32-character GUID. Path has the same character restrictions as path in PutResource. | The HTTP Content-Type header specifies the format of the POST data. These are the possible header values: - **application/json** - The POST data is JSON in the Announcement format. This implies that this announcement package requires no supporting attached files. - **text/xml** - The POST data is an XML fragment in the Announcement format. This implies that this announcement package requires no supporting attached files. - **application/zip** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Announcement format, and any supporting attached files. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "announcement": { "version": "string" } } } ``` ### announcement | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put announcement. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | When the entity is a course and an announcement at the same path was stored as a legacy course content file (a go/announcements/ path), that legacy file is deleted as the announcement is rewritten in its current storage. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the domain with ID 1274 exists and that the POST content is a zip-compressed stream as described in Announcement. **URL:** `?cmd=putannouncement&entityid=1274&path=e362a72809af4dd882797522d9db6c61.zip` **Response** (code: `OK`): ```json { "response": { "code": "OK", "announcement": { "version": "1" } } } ``` ## See Also - [DeleteAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/DeleteAnnouncements.md) - [GetAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncement.md) - [GetAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementList.md) - [UpdateAnnouncementViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateAnnouncementViewed.md) --- # PutAttemptFile This command puts files on the server to be associated with a fileupload question as part of a student assessment/homework attempt. ## Request **Method:** POST **Rights:** ReadCourse@enrollment.courseid or GradeExam|UpdateCourse@enrollment.courseid **Content-Type:** multipart/form-data **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putattemptfile` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which the uploaded files belong. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which uploaded files belong. | | `partid` | string | Yes | PartId of the fileupload question to which uploaded files beglong. | The HTTP Content-Type header must be multipart/form-data. PutAttemptFile associateds each file in the multipart data with the fileupload question. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "files": { "file": [ { "path": "string" } ] } } } ``` ### files #### file | Attribute | Type | Description | |-----------|------|-------------| | `path` | string | File path to a uploaded file. | ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) - [GetAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/GetAttemptFile.md) - [DeleteAttemptFile](https://api.agilixbuzz.com/docs/entry/Command/DeleteAttemptFile.md) --- # PutBlog This command puts a blog or journal message to the server. The message is the POST content of this request and should be in the format as described in Message. ## Request **Method:** POST **Rights:** Participate|GradeForum@entityid in the entity (course or section) referred to by enrollmentid. When itemid refers to a journal, caller must own enrollmentid. **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putblog` | | `enrollmentid` | id | Yes | Enrollment ID of the blog owner. | | `itemid` | string | Yes | ID of the associated blog or journal item from the course manifest. | | `messageid` | string | Yes | Unique message ID. To ensure uniqueness, we suggest a string in the format guid.zip, where guid is a 32-character GUID. Messageid has the same character restrictions as path in PutResource. | | `parentid` | string | No | The messageid of the blog message you are replying to. When posting to your own blog (enrollmentid belongs to the current signed-on user), parentid is optional; otherwise, it is required and must be a message ID created by the blog owner (enrollmentid). | | `authorid` | id | No | Enrollment ID of the user authoring the blog message. This is required when the poster is a student (has the Participate right) of the course so that PutBlog can properly credit the student for the post. It is optional if the poster has the GradeForum right. However, if you omit authorid, PutBlog does not determine the caller's enrollment ID nor does GetBlogList return an authorid for this post. | The HTTP Content-Type header specifies the format of the POST data. These are the possible header values: - **application/json** - The POST data is JSON in the Message format. This implies that this blog package requires no supporting attached files. - **text/xml** - The POST data is an XML fragment in the Message format. This implies that this blog package requires no supporting attached files. - **application/zip** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Message format, and any supporting attached files. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": { "version": "string" } } } ``` ### message | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put message. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A graded blog post is scored on submission. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A graded blog post is scored on submission. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the caller has enrollment ID 1254, the caller is a student in the course, and that the POST content is a zip-compressed stream as described in Message. **URL:** `?cmd=putblog&enrollmentid=1254&itemid=AE5T8&messageid=e362a72809af4dd882797522d9db6c61.zip&authorid=1254` **Response** (code: `OK`): ```json { "response": { "code": "OK", "message": { "version": "1" } } } ``` ## See Also - [Message](https://api.agilixbuzz.com/docs/entry/Schema/Message.md) - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) - [GetBlogList](https://api.agilixbuzz.com/docs/entry/Command/GetBlogList.md) --- # PutItemActivity This command reports per-item student time spent to the server. Note that this API is subject to API rate limiting. See the API Rate Limiting concept for more information. ## Request **Method:** POST **Rights:** Participate@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putitemactivity` | **Request body (JSON):** ```json { "requests": { "activity": [ { "enrollmentid": "id", "itemid": "id", "newattempt": "bool", "seconds": "int" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `activity.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of the student receiving the activity data. | | `activity.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the item. | | `activity.newattempt` | bool | No | Indicates that this call marks the start of a new attempt for the student. | | `activity.seconds` | int | Yes | Number of seconds student spent on the item, at most 3600 (one hour). This number is added to any previously submitted time-spent number. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityActivity.md) | During the request | Enrollment activity cascades up to the course. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Enrollment activity cascades up through the course to the domain. | | [EnrollmentEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityActivity.md) | During the request | For the reported time spent, which extends the enrollment's activity range. | | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Recorded time and activity are part of the enrollment metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Recorded time and activity are part of the enrollment metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | Recorded activity can change an item's status, which writes a grade record. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | Recorded activity can change an item's status, which writes a grade record. Sent when no grade record existed for the item and student yet. | | [ItemActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/ItemActivity.md) | During the request | For the reported time spent on the item. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) --- # PutItemRating This command puts a user rating on a manifest item. ## Request **Method:** GET **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putitemrating` | | `entityid` | id | Yes | ID of the course that owns the manifest. | | `itemid` | string | Yes | ID of the item. | | `rating` | double | Yes | User rating to assign to the item. This number must be greater than zero and typically less or equal to one. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "rating": { "flags": "enum" } } } ``` ### rating | Attribute | Type | Description | |-----------|------|-------------| | `flags` | enum | A bitwise-OR of RightsFlags that indicate the user's privileges associated with the rating. | ## See Also - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [GetItemRating](https://api.agilixbuzz.com/docs/entry/Command/GetItemRating.md) - [GetItemRatingSummary](https://api.agilixbuzz.com/docs/entry/Command/GetItemRatingSummary.md) --- # PutItems This command puts one or more items in a manifest. ## Request **Method:** POST **Rights:** When entityid refers to a course or a group in the course: UpdateCourse@courseid When entityid refers to an enrollment: UpdateCourse@enrollment.courseid, or the current user is the enrollment's user and the enrollment represents an active student enrollment (Participate@enrollment, enrollment status is active, and the current date is between the enrollment's start and end dates). Students can create new items. Students can modify existing items only if the item has studentcanmodify=true. When students create or modify items, they may only modify these item data elements: attachments, comments, completiontrigger, dropbox, dropboxtype, duedate, duedategrace, flags (may only set or remove the ExternalLaunch bit), folder, gradable (only when AllowStudentTasksSubmission is set in the course's CourseDataFlags), href, learningobjectives, studentcustom, thumbnail, timetocomplete, title, and type (may only be set to AssetLink, Assignment, CustomActivity, or Resource). **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putitems` | **Request body (JSON):** ```json { "requests": { "item": [ { "entityid": "id", "itemid": "string", "groupid": "string", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `item.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course, group, or enrollment that owns the item. You only need to specify the Item Data elements and attributes that are deltas from the base course item because GetItem and GetManifest merge Item Data from the base course. | | `item.itemid` | string | Yes | ID of the item. Maximum length is 256 characters. Item IDs for new items may only contains alphanumeric, underscore, period, and dash characters. The ID "DEFAULT" always refers to the root item. | | `item.groupid` | string | No | Schema 4+: when entityid is a course, stores the item data as a group-specific override for the specified group (string group ID from the course's group definitions). The override applies to enrollments in that group. | | `item.data` | object | No | See Item Data Schema for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemChanged.md) | During the request | For each course item the request actually modifies. If the course has derivative courses, further events follow later, one per affected derivative course. | | [CourseItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemCreated.md) | During the request | For each item added to a course by the request. | | [EnrollmentItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemChanged.md) | During the request | For each enrollment item the request actually modifies. | | [EnrollmentItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemCreated.md) | During the request | For each item added to an enrollment by the request. | | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Changing a course's items or grading rules changes what the metrics are computed from. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Changing a course's items or grading rules changes what the metrics are computed from. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | Changing an item's grading rules recalculates the affected grades. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | Changing an item's grading rules recalculates the affected grades. Sent when no grade record existed for the item and student yet. | | [GroupItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupItemChanged.md) | During the request | For each group item the request actually modifies. | | [GroupItemCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupItemCreated.md) | During the request | For each item added to a group by the request. | Which of the course, enrollment, or group item events is sent is determined by the type of the entity the item belongs to. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates a new item with ID “Assignment12" in the course whose ID is 4378. **URL:** `?cmd=putitems` **Request body:** ```json { "requests": { "item": { "entityid": "4378", "itemid": "Assignment12", "data": { "type": { "$value": "Assignment" }, "parent": { "$value": "DEFAULT" }, "sequence": { "$value": "a" }, "title": { "$value": "Assignment 12" }, "href": { "$value": "Assets/assignment12.htm" } } } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) - [GetItem](https://api.agilixbuzz.com/docs/entry/Command/GetItem.md) - [GetItemList](https://api.agilixbuzz.com/docs/entry/Command/GetItemList.md) - [GetManifest](https://api.agilixbuzz.com/docs/entry/Command/GetManifest.md) - [GetManifestItem](https://api.agilixbuzz.com/docs/entry/Command/GetManifestItem.md) --- # PutItemStatus This command is obsolete. Use PutTeacherResponse or PutTeacherResponses or PutStudentSubmission instead. This command puts student item status and/or student scores to the server. ## Request **Method:** POST **Rights:** GradeExam|GradeAssignment|GradeForum|SetupGradebook@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putitemstatus` | **Request body (JSON):** ```json { "requests": { "status": [ { "enrollmentid": "id", "itemid": "id", "status": "GradeStatus", "mask": "GradeStatus" } ], "score": [ { "enrollmentid": "id", "itemid": "id", "pointsachieved": "double", "pointspossible": "double", "grade": "string", "submitteddate": "datetime", "version": "int", "show": "boolean" } ], "submit": [ { "enrollmentid": "id", "itemid": "id", "submitteddate": "datetime" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `status.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of the student receiving the score or status | | `status.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Item ID of the gradable item. Specify (Course) to record a final grade for the entire course. | | `status.status` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | Yes | Bitwise OR of GradeStatus values to set. | | `status.mask` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | Yes | A bitwise OR mask that indicates which GradeStatus bits are being set or cleared in status. | | `score.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | | | `score.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | | | `score.pointsachieved` | double | Yes | The number of points achieved for this student for this item. | | `score.pointspossible` | double | Yes | The number of points possible for this student for this item. | | `score.grade` | string | No | The letter grade for this student for this item. | | `score.submitteddate` | datetime | No | Specifies the date the a student completed an assignment that does not have a drop box. | | `score.version` | int | Yes | The submission version to which the score applies. You obtain this value from item@submittedversion attribute in the Get\*Gradebook commands. | | `score.show` | boolean | Yes | Specifies whether the student can see the score. | | `submit.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | | | `submit.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | | | `submit.submitteddate` | datetime | Yes | | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Changing an item's status changes progress metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Changing an item's status changes progress metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | Setting an item's status or score writes a grade record. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | Setting an item's status or score writes a grade record. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [PutItemActivity](https://api.agilixbuzz.com/docs/entry/Command/PutItemActivity.md) --- # PutKey This command stores a name/value pair on an entity. **Send the parameters in a POST body.** The value stored is often a credential, and a query string is recorded in access logs, proxy logs and browser history. Query-string parameters are still read, with either method, so existing integrations keep working — but that form is deprecated. Use application/json or application/x-www-form-urlencoded for the body. text/xml is also parsed, but prefer one of the other two: a small text/\* request body can be captured verbatim in the request log, which for this command would record the value you are trying to keep out of the logs. Note that application/xml is NOT parsed — only text/xml. ## Request **Method:** POST **Rights:** UpdateDomain@entityid when entityid refers to a domain. **Content-Type:** application/json , application/x-www-form-urlencoded , or text/xml **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putkey` | **Request body (JSON):** ```json { "request": { "entityid": "id", "name": "string", "value": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the domain that owns the name/value pair. | | `name` | string | Yes | The name of the key. | | `value` | string | Yes | The value of the key. | For assessments, the server supports a key that acts as domain-wide password. This password is convenient for testing facilities. It allows them to have a common password across all assessments in the domain. When checking this password for students taking tests, the server uses the domain of the student's enrollment. The name of the key is ExamPassword. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example assigns a key with the name "ExamPassword" to the domain with ID 616, sending the value in the request body so that it does not appear in the URL. **URL:** `?cmd=putkey` **Request body:** ```json { "request": { "entityid": "616", "name": "ExamPassword", "value": "Secret" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [GetKey](https://api.agilixbuzz.com/docs/entry/Command/GetKey.md) --- # PutMessage This command puts a discussion board message to the server. ## Request **Method:** POST **Rights:** Participate@entityid or GradeForum@entityid **Content-Type:** application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putmessage` | | `entityid` | id | Yes | ID of the entity (course, section, or enrollment) to post the message to. | | `itemid` | id | Yes | ID of the threaded discussion item from the course manifest. | | `groupid` | string | No | Optional group ID to which the message belongs. If omitted, the default group is used. This command supports two special group IDs. - **(Common)** - Indicates the message is common to all groups. The system automatically includes the message in every group. - **(Initial)** - Indicates the message is part of a base course and derivative courses inherit the message in each group. | | `messageid` | string | Yes | Unique message ID. To ensure uniqueness, we suggest a string in the format guid.zip, where guid is a 32-character GUID. Messageid has the same character restrictions as path in PutResource. | | `parentid` | string | No | When replying to another message, parentid is the messageid of the message being replied to. | | `status` | string | No | Specifies whether the message is hidden or not. Hidden messages are not visible to students. | The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Message format, and any supporting files. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": { "version": "string" } } } ``` ### message | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put message. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A graded discussion post is scored on submission. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A graded discussion post is scored on submission. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [PutMessagePart](https://api.agilixbuzz.com/docs/entry/Command/PutMessagePart.md) - [DeleteMessagePart](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessagePart.md) - [SubmitMessage](https://api.agilixbuzz.com/docs/entry/Command/SubmitMessage.md) - [DeleteMessage](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessage.md) - [GetMessage](https://api.agilixbuzz.com/docs/entry/Command/GetMessage.md) - [UpdateMessageViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateMessageViewed.md) --- # PutMessagePart This command puts individual parts of a discussion board message to the server. When called, the message enters an edit state where changes to the message parts are stored in a temporary location on the server. While in this state, only the message owner can see the changed message parts with the GetMessage command. Other users get the message as it existed before the edits began. To commit these changes to a new message, call SubmitMessage. To rollback changes and revert to the pre-changed state, call DeleteMessagePart and omit the *filepath* parameter. ## Request **Method:** POST **Rights:** Participate@entityid or GradeForum@entityid **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putmessage` | | `entityid` | id | Yes | ID of the entity (course or section) to post the message to. | | `itemid` | id | Yes | ID of the threaded discussion item from the course manifest. | | `messageid` | string | Yes | Unique message ID. To ensure uniqueness, we suggest a string in the format guid.zip, where guid is a 32-character GUID. Messageid has the same character restrictions as path in PutResource. | | `groupid` | string | No | Optional group ID to which the message belongs. If omitted, the default group is used. | | `filepath` | string | No | When Content-Type is not one of the special types mentioned below, filepath is the path that identifies this file within the collection of supporting files such as attachments associated with the message. | | `disposition` | string | No | When Content-Type is not one of the special types mentioned below, disposition identifies the role of the supporting file. The possible values are: - **attachment** - The file is an attachment to the message. - **inline** - The file is resource such as an image used within the body of the message. | | `schema` | int | No | When Content-Type is multipart/form-data or application/x-www-form-urlencoded this parameter specifies the schema of the message format. This should be set to 5. | The HTTP Content-Type header specifies the format of the POST data. The following header values indicate special handling by the API server. The server treats any other value as a supporting file and you must supply the filepath parameter. - **application/json** - The POST data is JSON in the Message format. - **application/x-dlap-message-xml** - The POST data is an XML fragment in the Message format. - **multipart/form-data** - The POST data is multipart form data. The server saves each file in the multipart data as a supporting file for the message. - **application/x-www-form-urlencoded** - The POST data is form data. The server saves an included notes field in the body element of the message. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## See Also - [DeleteMessagePart](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessagePart.md) - [SubmitMessage](https://api.agilixbuzz.com/docs/entry/Command/SubmitMessage.md) - [GetMessage](https://api.agilixbuzz.com/docs/entry/Command/GetMessage.md) - [UpdateMessageViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateMessageViewed.md) --- # PutObjectiveMaps This command creates or updates one or more objective maps and puts them into an objective map set. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putobjectivemaps` | **Request body (JSON):** ```json { "requests": { "map": [ { "setid": "id", "guid": "guid", "correlation": "guid", "weight": "double" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `map.setid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the objective map set to assign this map to. | | `map.guid` | guid | Yes | The unique identifier of the learning objective. | | `map.correlation` | guid | Yes | The unique identifier of the correlated learning objective. | | `map.weight` | double | Yes | The weight of the map. Maps with higher weight have higher precedence than those with lower weight. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example puts a new objective mapping in the set whose ID is 4378. **URL:** `?cmd=putobjectivemaps` **Request body:** ```json { "requests": { "map": { "guid": "4bebfa5f-e5d0-49c6-99a9-0048be0d0170", "correlation": "f2d5feab-72f1-4294-8325-375ff86f5531", "setid": "4378", "weight": "1" } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectiveMaps](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveMaps.md) - [GetObjectiveMapList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveMapList.md) --- # PutObjectives This creates or updates one or more learning objectives and puts them in an objective set. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putobjectives` | **Request body (JSON):** ```json { "requests": { "objective": [ { "guid": "guid", "id": "string", "title": "string", "setid": "id", "reference": "string", "grades": "GradeLevels", "subject": "string", "parent": "guid", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `objective.guid` | guid | Yes | The globally unique identifier for the objective. | | `objective.id` | string | Yes | The ID string that the external, objective-set source assigns to this objective. | | `objective.title` | string | Yes | The title or description of the objective. | | `objective.setid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the objective set that this objective belongs to. | | `objective.reference` | string | Yes | A field that identifies the objective in other systems such as ASN. | | `objective.grades` | [GradeLevels](https://api.agilixbuzz.com/docs/entry/Enum/GradeLevels.md) | Yes | A bitwise OR of GradeLevels that indicates the applicable grades for this objective. | | `objective.subject` | string | Yes | The academic subject for this objective. | | `objective.parent` | guid | No | The unique identifier of the parent objective, if any. | | `objective.data` | object | No | Free-form structured data for the objective. See Free-form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example puts a new objective in the set whose ID is 4378. **URL:** `?cmd=putobjectives` **Request body:** ```json { "requests": { "objective": [ { "guid": "239bd83f-0064-95b7-49fb-8d8167489a94", "id": "D1000255", "title": "Alabama Course of Study: Science", "setid": "4378", "reference": "http://purl.org/ASN/resources/D1000255", "grades": "32764", "subject": "Science", "data": { "url": { "$value": "http://purl.org/ASN/resources/D1000255" }, "description": { "$value": "The Alabama Course of Study: Science (Bulletin 2005, No. 20) provides the framework for the K-12 science \n education program in Alabama’s public schools. Content standards in this document are minimum and required (Code of \n Alabama, 1975, §16-35-4). They are fundamental and specific but not exhaustive. When developing a local curriculum, \n each school system may include additional content standards to address specific local needs or focus on local resources. \n Implementation guidelines, resources, and activities may also be added." } } } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectives](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectives.md) - [GetObjectiveList](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveList.md) --- # PutPeerResponse This command puts peer response data including comments, rubric score, and likert responses to the server. Although a peer response can include a score, PutPeerResponse does not record the score in the gradebook. A peer response is a zip-compressed file that contains a Response XML file named meta.xml and additional supporting attached files. If the peer response has no supporting files, you can put just the Response XML. ## Request **Method:** POST **Rights:** Participate@courseid in the course referred to by enrollmentid **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putpeerresponse` | | `enrollmentid` | id | Yes | ID of the user's enrollment whose submission is being responded to with this peer response; i.e., identifies the student who is being reviewed. | | `itemid` | string | Yes | ID of the item (in the course manifest) that is being responded to. The item must be peer reviewable (see allowpeerreview in Item Data for more details.) | | `peerid` | id | Yes | Enrollment ID of the peer who is responding or reviewing their peer's submission. | The HTTP Content-Type header specifies the format of the POST data. These are the possible header values: - **application/json** - The POST data is JSON in the Response format. This implies that this peer response requires no supporting attached files. - **text/xml** - The POST data is an XML fragment in the Response format. This implies that this peer response requires no supporting attached files. - **application/zip** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Response format, and any supporting attached files. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "peerresponse": { "version": "int" } } } ``` ### peerresponse | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the newly put peer response. "1" is the first response, then "2", etc. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A peer review score updates the grade. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A peer review score updates the grade. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [Response](https://api.agilixbuzz.com/docs/entry/Schema/Response.md) - [GetPeerResponse](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponse.md) - [GetPeerResponseList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerResponseList.md) - [GetPeerReviewList](https://api.agilixbuzz.com/docs/entry/Command/GetPeerReviewList.md) --- # PutQuestions This command puts (adds or updates) one or more questions in a course. For a description of possible interactionflags values, see InteractionFlags. All body and feedback tags contain HTML that can also contain the special a:math and a:media tags. ## Request **Method:** POST **Rights:** UpdateCourse@entityid where entityid refers to a course. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putquestions` | **Request body (JSON):** ```json { "requests": { "question": [ { "entityid": "id", "questionid": "string", "schema": "2", "score": "double", "partial": "boolean", "round": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `question.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course that owns the question. | | `question.questionid` | string | Yes | A unique ID that identifies the question. If a question with this ID already exists in the course or section, the question is updated; otherwise, a new question is added with this ID. | | `question.schema` | `2` | Yes | You must specify 2 for schema. (Schema 1 is an obsolete schema supported only for backwards compatibility.) | | `question.score` | double | No | The points possible for this question. If omitted, uses the assessment default score. | | `question.partial` | boolean | No | True if partial credit is allowed for this question; otherwise false. The default is false. | | `question.round` | boolean | No | True to round partial scores down to the next whole number, otherwise false. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "question": { "questionid": "string", "version": "string" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### question | Attribute | Type | Description | |-----------|------|-------------| | `questionid` | string | A unique ID that identifies the question. | | `version` | string | Version of the question. | ## Example This example creates a matching question, a multiple-choice question, and a short-answer math question in the course whose ID is 4378. **URL:** `?cmd=putquestions` **Request body:** ```json { "requests": { "question": [ { "questionid": "2f58ddabe0e343eda629b405759be802", "entityid": "4378", "schema": "2", "partial": true, "round": true, "answer": {}, "body": { "$value": "Match the animals with their sounds." }, "interaction": { "type": "match", "flags": 2, "choice": [ { "id": "1", "body": { "$value": "dog" }, "answer": { "$value": "woof" } }, { "id": "2", "body": { "$value": "cat" }, "answer": { "$value": "meow" } }, { "id": "3", "body": { "$value": "cow" }, "answer": { "$value": "moo" } } ] } }, { "questionid": "44cead279c0f46dcab0c2d4ff1ce5c67", "entityid": "4378", "schema": "2", "partial": false, "body": { "$value": "Is this a multiple choice question?" }, "interaction": { "type": "choice", "flags": 2, "choice": [ { "id": "1", "body": { "$value": "Yes" } }, { "id": "2", "body": { "$value": "No" } } ] }, "groups": { "group": [ { "$value": "Group A" } ] }, "answer": { "value": [ { "$value": "1" } ] } }, { "questionid": "b10b8b13991947fe89fa1cc436206f6a", "entityid": "4378", "schema": "2", "partial": false, "interaction": { "type": "text", "flags": 2, "width": 150, "texttype": "Numeric" }, "parameters": { "parameter": [ { "name": "a", "type": "Range", "min": 1, "max": 9, "step": 1 }, { "name": "b", "type": "Range", "min": 1, "max": 9, "step": 1 }, { "name": "c", "type": "List", "values": { "value": [ { "$value": "1" }, { "$value": "3" }, { "$value": "5" }, { "$value": "7" } ] } } ] }, "body": { "$value": "$c$($a$ + $b$) = <a:text />" }, "answer": { "value": [ { "$value": "$c$*($a$+$b$)" } ] } } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "question": { "questionid": "2f58ddabe0e343eda629b405759be802", "version": "1" } }, { "code": "OK", "question": { "questionid": "44cead279c0f46dcab0c2d4ff1ce5c67", "version": "1" } }, { "code": "OK", "question": { "questionid": "b10b8b13991947fe89fa1cc436206f6a", "version": "1" } } ] } } } ``` ## See Also - [InteractionFlags](https://api.agilixbuzz.com/docs/entry/Enum/InteractionFlags.md) - [Question Schema](https://api.agilixbuzz.com/docs/entry/Schema/Question.md) - [GetQuestionList](https://api.agilixbuzz.com/docs/entry/Command/GetQuestionList.md) --- # PutResource This command puts a resource to the server for the specified course, section, enrollment, user, or domain. Resources include things such as course manifests, rich media content, or HTML pages. ## Request **Method:** POST **Rights:** UpdateDomain@entityid when entityid refers to a domain; UpdateCourse@entityid when entityid refers to a course; UpdateUser@entityid when entityid refers to a user; when entityid refers to an enrollment, GradeAssignment@the enrollment's entity ID, or Participate@entityID and the enrollment is active and (path starts with "Student/" or class is "STUD"); **Content-Type:** package-mime-type **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putresource` | | `entityid` | id | Yes | ID of the course, enrollment, or domain that owns this resource. | | `path` | string | Yes | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Path cannot contain control characters (0x00-0x1f), quotation mark ("), less than (<), greater than (>), pipe (\|), colon (:), asterisk (\*), dot-dot-slash (../), dot-dot-backslash (..\), and it cannot start nor end with slash (/) or backslash (\). Note that if the path ends with settings.xml (case-insensitive), the contents must be empty or valid XML. If a default (unclassed) or Likert-class resource's path starts with public/ then the resource will be publicly accessible, cross-tenant and even to unauthenticated users, so you must not store anything you don't want exposed in that path. (Resources stored under any other class still require the normal per-class authorization.) | | `status` | string | No | Specifies whether the resource is hidden or not. Hidden resources are not visible to students, who are users with the Participate rights. | | `class` | string | No | The four character string that specifies the class, or type, of resource to store. The default of an empty string stores normal course or user resources. The special class of *MISC* can be used to store arbitrary or application-specific resources on the specified entity. | | `drophistory` | boolean | No | Whether the version of the resource being uploaded is a temporary version that should be completely erased when another subsequent upload occurs. Used for when the resource is a work in progress that is expected to be reuploaded at a later time. Note that when this parameter is true, the corresponding resource cannot be used with course chaining, which relies on history to manage change propagation. | | `contenttype` | string | No | Override value for the Content-Type header. If this parameter is supplied, it is used instead of the Content-Type HTTP header. This parameter should be used when attempting to put content with the "application/x-dlap-resource-xml" content type from an AJAX request in IE 8 or IE 9. | These are the types of packages accepted by PutResource: application/x-dlap-resource-xml this package type indicates that the post data contains only the resource metadata xml. application/x-dlap-resource-json this package type indicates that the post data contains only the resource metadata JSON. application/x-dlap-resource-zip-package this package type indicates that the post data is a zip package containing two files, meta.xml (containing the metadata) and data.bin containing the binary data for the resource. multipart/form-data this package type indicates that the post data is a multipart form upload. The resource type, file name and contents will be taken from the first file in the multipart upload that does not have one of the special content types used to indentify metadata. The *path* attribute may then specify the folder where the resource should be placed. To upload resource metadata along with the a resource file, include a second file in the form data with the content-type of *application/x-dlap-resource-xml* or *application/x-dlap-resource-json*. anything else any other content-type specification will be stored as that type with no metadata. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "resource": { "size": "int", "version": "string" } } } ``` ### resource | Attribute | Type | Description | |-----------|------|-------------| | `size` | int | The number of bytes written into the resource. | | `version` | string | A combination of the version of this resource in the entity referred to by *entityid*, and that entity's chain depth. The lower 20 bits contain the version, and the higher bits contain the chain depth. See Derivative Courses (Chaining) for more information on chain depth. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceChanged.md) | During the request | For a file stored at a path already in use, whether the write replaces the file's content or only its details. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For a file stored at a path not already in use, and one more for each parent folder the write creates. | | [CourseResourceDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceDeleted.md) | During the request | When the path is an announcement (a go/announcements/ path) on a course, the write is stored as an announcement instead of a content file, and any legacy content file at the path is deleted. | These events are sent only when the entity is a course and the resource is in the course's default (unclassed) content storage. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example puts a file named picture.png into a folder named images. Although not shown below, we assume the image file contents are the content of the POST command, and we assume the Content-Type HTTP header has been set to image/png. **URL:** `?cmd=putresource&entityid=4137&path=images/picture.png&status=Normal` **Response** (code: `OK`): ```json { "response": { "code": "OK", "resource": { "version": "1" } } } ``` ## See Also - [CopyResources](https://api.agilixbuzz.com/docs/entry/Command/CopyResources.md) - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [GetResource](https://api.agilixbuzz.com/docs/entry/Command/GetResource.md) - [GetResourceInfo2](https://api.agilixbuzz.com/docs/entry/Command/GetResourceInfo2.md) - [GetResourceList](https://api.agilixbuzz.com/docs/entry/Command/GetResourceList.md) --- # PutResourceFolders This command creates one or more resource folders for a domain or course. ## Request **Method:** POST **Rights:** UpdateDomain@entityid when entityid refers to a domain; UpdateCourse@entityid when entityid refers to a course. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putresourcefolders` | **Request body (JSON):** ```json { "requests": { "folder": [ { "entityid": "id", "path": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `folder.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Course or domain ID that owns this resource. | | `folder.path` | string | Yes | The unique path to the resource. You can use forward-slash (/) between path elements to create a resource hierarchy. Path has the same character restrictions as path in PutResource. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "folder": { "version": "string" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### folder | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | Version of the folder | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each folder created. Sent only when the entity is a course and the folder is in the course's default (unclassed) content storage. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example creates the resource folder with path "Assets/Images" in the course whose ID is 4378. **URL:** `?cmd=putresourcefolders` **Request body:** ```json { "requests": { "folder": { "entityid": "4378", "path": "Assets/Images" } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": { "code": "OK", "folder": { "version": "1" } } } } } ``` ## See Also - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) - [RestoreResources](https://api.agilixbuzz.com/docs/entry/Command/RestoreResources.md) - [GetResourceList](https://api.agilixbuzz.com/docs/entry/Command/GetResourceList.md) --- # PutScoData This command puts a user's SCORM data for a SCO activity to the server. The data is a list of name-value pairs where each name is a SCORM run-time data-model variable name. For details about the SCORM run-time environment and the variables it defines, see the official SCORM Runtime Environment reference manual at http://www.adlnet.gov/capabilities/scorm. As per the SCORM spec, *PutScoData* strips read-only fields from the data and accumulates *cmi.total\_time*. It also automatically generates a corresponding Submission for the SCO data when *cmi.completion\_status* is *completed*, and any of *cmi.score.scaled*, *cmi.score.raw*, *cmi.score.max*, or *cmi.completion\_status* changes from the previous call to *PutScoData* for the same *enrollmentid* and *itemid*. If *PutScoData* generates a *Submission* and the SCO data contains a score, *PutScoData* also automatically generates a corresponding Response. ## Request **Method:** POST **Rights:** Participate@entityid or GradeAssignment@entityid in the course or section referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putscodata` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this data belongs. | | `itemid` | string | Yes | ID of the SCO item (in the course manifest) to which this data belongs. The item must be a custom activity that has the sco attribute set in its Item Data. | **Request body (JSON):** ```json { "request": { "entry": [ { "name": "string", "value": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `entry.name` | string | Yes | The name of the SCORM run-time data model variable to set. | | `entry.value` | string | Yes | The value of the variable. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | SCORM data reported by the content can set a score. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | SCORM data reported by the content can set a score. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **URL:** `?cmd=putscodata&enrollmentid=4317&itemid=SCO1` **Request body:** ```json { "data": { "entry": [ { "name": "cmi.score.scaled", "value": "0.5" }, { "name": "cmi.session_time", "value": "PT2M" }, { "name": "cmi.interactions.0.id", "value": "Q1" }, { "name": "cmi.interactions.0.type", "value": "other" }, { "name": "cmi.interactions.0.result", "value": "0" }, { "name": "cmi.interactions.0.weighting", "value": "1.0" }, { "name": "cmi.interactions.1.id", "value": "Q2" }, { "name": "cmi.interactions.1.type", "value": "other" }, { "name": "cmi.interactions.1.result", "value": "1" }, { "name": "cmi.interactions.1.learner_response", "value": "Green flame" }, { "name": "cmi.interactions.1.weighting", "value": "1.0" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [GetScoData](https://api.agilixbuzz.com/docs/entry/Command/GetScoData.md) --- # PutSelfAssessment This command puts self-assessment ratings of understanding, interest, and effort into the student's Enrollment Metrics. Students can rate their understanding, interest, and effort so that instructors can respond or help them, if necessary. To retrieve posted self-assessment data, call a command like GetEnrollment3, which can return Enrollment Metrics. ## Request **Method:** GET **Rights:** Participate@enrollmentid or GradeExam|GradeAssignment|GradeDiscussion@courseid in the course referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putselfassessment` | | `enrollmentid` | id | Yes | Enrollment to post the self assessment. | | `understanding` | int | No | Number that represents how well the student feels he or she understands the course. May be a number from 1 (to indicate low understanding) to 255 (to indicate excellent understanding). If not set, the Enrollment Metrics retains the value from the previous self-assessment, if any. | | `interest` | int | No | Number that represents how interested the student is in the course. May be a number from 1 (to indicate low interest) to 255 (to indicate high interest). If not set, the Enrollment Metrics retains the value from the previous self-assessment, if any. | | `effort` | int | No | Number that represents how much effort the student feels he or she is giving to the course. May be a number from 1 (to indicate low effort) to 255 (to indicate high effort). If not set, the Enrollment Metrics retains the value from the previous self-assessment, if any. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example Posts a self assessment to enrollment 12345678. **URL:** `?cmd=putselfassessment&understanding=3&interest=2&effort=1` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Enrollment Metrics](https://api.agilixbuzz.com/docs/entry/../Schema/EnrollmentMetrics.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListUserEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListUserEnrollments.md) --- # PutStudentSubmission This command puts a student submission for an activity to the server. A student submission is a zip-compressed file that contains a Submission XML file named meta.xml and additional supporting attached files. If the submission has no supporting files, you can put just the Submission data. ## Request **Method:** POST **Rights:** Participate@entityid or GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putstudentsubmission` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this submission belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this submission belongs. | | `recordactivity` | bool | No | When *true*, and this item is an assessment or homework, then *PutStudentSubmission* records activity time for this item as if you had called PutItemActivity for the total time of the submission at the same time. The default is *true*. | The HTTP Content-Type header specifies the format of the POST data. These are the possible header values: - **application/json** - The POST data is JSON in the Submission format. This implies that this submission requires no supporting attached files. - **text/xml** - The POST data is an XML fragment in the Submission format. This implies that this submission requires no supporting attached files. - **application/zip** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Submission format, and any supporting attached files. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "submission": { "version": "double" } } } ``` ### submission | Attribute | Type | Description | |-----------|------|-------------| | `version` | double | The version of the newly put student submission. "1" is the first submission, then "2", etc. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityActivity.md) | During the request | Enrollment activity cascades up to the course. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Enrollment activity cascades up through the course to the domain. | | [EnrollmentEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityActivity.md) | During the request | A submission records the time spent on the item against the enrollment. | | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Submitting work changes the student's progress and score metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Submitting work changes the student's progress and score metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A submission creates or updates the grade record for the item. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A submission creates or updates the grade record for the item. Sent when no grade record existed for the item and student yet. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Submits a dropbox/essay assignment as JSON (no attached files), with the student's answer in the notes element. Because there are no attachments, the Submission data is posted directly with Content-Type: application/json (no .zip). **URL:** `?cmd=putstudentsubmission&enrollmentid=6051&itemid=essay1` **Request body:** ```json { "submission": { "type": "assignment", "notes": { "$value": "

My essay response goes here.

" } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "submission": { "version": "1" } } } ``` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [GetStudentSubmissionInfo](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmissionInfo.md) --- # PutTeacherResponse This command puts teacher response data including scores, comments, and grade status flags to the server. A teacher response is a zip-compressed file that contains a Response XML file named meta.xml and additional supporting attached files. If the teacher response has no supporting files, you can put just the Response data. If you are putting only status or score information then PutTeacherResponses is more efficient. ## Request **Method:** POST **Rights:** GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putteacherresponse` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this teacher response belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this teacher response belongs. Specify **(Course)** to record a final grade for the entire course, or specify **(Period:n)**, where n is 1, 2, 3, etc., to record a final grade for the specified period. | | `zerounscored` | boolean | No | When putting a period or final grade (itemid is **(Course)** or **(Period:n)**), true causes all unscored gradable items for the period or course to be given a score of 0. When false, unscored gradable items are not modified. The default is false. | The HTTP Content-Type header specifies the format of the POST data. These are the possible header values: - **application/json** - The POST data is JSON in the Response format. This implies that this teacher response requires no supporting attached files. - **text/xml** - The POST data is an XML fragment in the Response format. This implies that this teacher response requires no supporting attached files. - **application/zip** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Response format, and any supporting attached files. - **multipart/form-data** - The POST data is multipart form data. PutTeacherResponse saves each file in the multipart data as a response attachment, and it saves form fields as defined in **application/x-www-form-urlencoded**. - **application/x-www-form-urlencoded** - The POST data is form data. PutTeacherResponse saves an included response field as the response data. The response field can be either JSON or an XML fragment in the Response format. To save teacher notes (notes that the student does not have access to), set the privatenotes field to the value of the notes. You can get the teacher notes by calling GetTeacherResponse and passing *private.zip/notes.htm* for *filepath*. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "teacherresponse": { "version": "int" } } } ``` ### teacherresponse | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the newly put teacher response. "1" is the first response, then "2", etc. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Grading changes the student's score metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Grading changes the student's score metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A teacher's score or feedback updates the grade. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A teacher's score or feedback updates the grade. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example puts a teacher response to a student with enrollment ID 4138 for assignment with item ID "assignment1". The computed score is 53 out of 60, which is a rollup of the individually assigned rubric scores. The status of 4 allows the student to see the score. **URL:** `?cmd=putteacherresponse&enrollmentid=4138&itemid=assignment1` **Request body:** ```json { "response": { "type": "none", "mask": 4, "status": 4, "pointscomputed": 53, "pointspossible": 60, "scoredversion": 1, "response": [ { "type": "rubricrow", "foreignid": "1", "pointsassigned": 18, "pointspossible": 20 }, { "type": "rubricrow", "foreignid": "2", "pointsassigned": 15, "pointspossible": 20 }, { "type": "rubricrow", "foreignid": "3", "pointsassigned": 20, "pointspossible": 20 } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "teacherresponse": { "version": 1 } } } ``` ## See Also - [Response](https://api.agilixbuzz.com/docs/entry/Schema/Response.md) - [GetTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponse.md) - [GetTeacherResponseInfo](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponseInfo.md) - [PutTeacherResponses](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponses.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # PutTeacherResponses This command puts one or more teacher responses including scores and grade status flags to the server. This command is more efficient than PutTeacherResponse when putting only status and score information. ## Request **Method:** POST **Rights:** GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putteacherresponses` | **Request body (JSON):** ```json { "requests": { "teacherresponse": [ { "enrollmentid": "id", "itemid": "id", "scoredversion": "int", "status": "GradeStatus", "mask": "GradeStatus", "pointsassigned": "double", "pointscomputed": "double", "pointspossible": "double", "letter": "string", "submitteddate": "datetime", "zerounscored": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `teacherresponse.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of the student receiving the score or status. | | `teacherresponse.itemid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Item ID of the gradable item. Specify **(Course)** to record a final grade for the entire course. | | `teacherresponse.scoredversion` | int | No | Version of the Submission that this response applies to. Specify 0 to create a response that does not correspond to a submission. The default is 0. | | `teacherresponse.status` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | No | Bitwise OR of GradeStatus values to set. | | `teacherresponse.mask` | [GradeStatus](https://api.agilixbuzz.com/docs/entry/Enum/GradeStatus.md) | No | A bitwise OR mask that indicates which GradeStatus bits are being set or cleared in status. | | `teacherresponse.pointsassigned` | double | No | Points achieved as determined by the teacher. If both pointsassigned and pointscomputed are omitted, the score will not be updated. If both exist, pointsassigned takes precedence over pointscomputed. The special value **NaN** indicates that pointscomputed should be cleared without assigning a new score. | | `teacherresponse.pointscomputed` | double | No | Points achieved as determined by any auto-grading process. If both pointsassigned and pointscomputed are omitted, the score will not be updated. If both exist, pointsassigned takes precedence over pointscomputed. | | `teacherresponse.pointspossible` | double | No | The number of points possible for this student for this item. If both pointsassigned and pointscomputed are omitted, the score will not be updated. In that case pointspossible is not required. | | `teacherresponse.letter` | string | No | The letter grade for this student for this item. | | `teacherresponse.submitteddate` | datetime | No | Specifies the date that a student completed an assignment. A teacher should not set this if the student submitted something through the dropbox, but the teacher should set it for non-dropbox items, such as oral presentations or other non-electronic assignments. Specify MinDate to clear an existing submitteddate value. If you omit submitteddate when calling PutTeacherResponses, any existing submitteddate is not modified. | | `teacherresponse.zerounscored` | boolean | No | When putting a period or final grade (itemid is **(Course)** or **(Period:n)**), true causes all unscored gradable items for the period or course to be given a score of 0. When false, unscored gradable items are not modified. The default is false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "teacherresponse": { "version": "int" } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### teacherresponse | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the newly put teacher response. "1" is the first response, then "2", etc. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Grading changes the student's score metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Grading changes the student's score metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A teacher's score or feedback updates the grade, once per response in the request. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A teacher's score or feedback updates the grade, once per response in the request. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [Response](https://api.agilixbuzz.com/docs/entry/Schema/Response.md) - [GetTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponse.md) - [GetTeacherResponseInfo](https://api.agilixbuzz.com/docs/entry/Command/GetTeacherResponseInfo.md) - [PutTeacherResponse](https://api.agilixbuzz.com/docs/entry/Command/PutTeacherResponse.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # PutWikiPage This command puts a wiki page to the server. ## Request **Method:** POST **Rights:** Participate@entityid or GradeForum@entityid when entityid refers to a section; UpdateCourse@entityid when entityid refers to a course. **Content-Type:** text/plain **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putwikipage` | | `entityid` | id | Yes | Entity ID to post the wiki page to | | `itemid` | id | Yes | ID of the wiki item from the Course Manifest. | | `groupid` | string | No | Optional group ID to which the wiki page belongs. | | `slug` | string | Yes | String that uniquely identifies the page within the item wiki. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "wikipage": { "version": "string" } } } ``` ### wikipage | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put wiki page. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceChanged.md) | During the request | For a page in the course's *(Initial)* group written to a path already in use. | | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For a page in the course's *(Initial)* group written to a path not already in use, and one more for each parent folder the write creates. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A graded wiki contribution is scored on submission. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A graded wiki contribution is scored on submission. Sent when no grade record existed for the item and student yet. | The CourseResource events are sent only for pages in the course's (Initial) group, which are stored as course content files; pages of other groups are stored outside the course content storage and send no content events. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [CopyWikiPages](https://api.agilixbuzz.com/docs/entry/Command/CopyWikiPages.md) - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [GetWikiPage](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPage.md) - [GetWikiPageList](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPageList.md) --- # PutWorkInProgress This command puts a work-in-progress file on the server in preparation for a student submission. Call SubmitWorkInProgress to submit the work. ## Request **Method:** POST **Rights:** Participate@entityid or GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Content-Type:** application/json , text/xml , or application/zip **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `putworkinprogress` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this submission belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this submission belongs. | | `filepath` | string | No | When Content-Type is not one of the special types mentioned below, filepath is the path that identifies this file within the collection of supporting files such as attachments associated with the student submission. | | `disposition` | string | No | When Content-Type is not one of the special types mentioned below, disposition identifies the role of the supporting file. The possible values are: - **attachment** - The file is an attachment to the submission. - **inline** - The file is resource such as an image used within the notes of the submission. | | `keephistory` | bool | No | Specify *true* to keep a history of the version of this work-in-progress file that is currently being submitted. Keeping a history causes this version of this file to be stored permanently. When not keeping a history, this version of this file will be deleted as soon as a newer version is submitted. To get previous versions of this file use GetWorkInProgress with a value for *version*. | The HTTP Content-Type header specifies the format of the POST data. PutWorkInProgress handles the following header values as defined and treats any other value as the content type of a supporting file, in which case you must supply the filepath parameter. - **application/json** - The POST data is JSON in the Submission format. - **application/x-dlap-resource-xml** - The POST data is an XML fragment in the Submission format. - **application/x-dlap-resource-zip-package** - The POST data is a zip-compressed file. The .zip contains a file named meta.xml, which is an XML fragment in the Submission format, and any supporting files. - **multipart/form-data** - The POST data is multipart form data. PutWorkInProgress saves each file in the multipart data as a submission attachment, and it saves form fields as defined in **application/x-www-form-urlencoded**. - **application/x-www-form-urlencoded** - The POST data is form data. - To populate the notes element of the submission, include a notes field in the form data. - To populate the url element of the submission, include a submissionurl field in the form data. - To add Google Drive attachments to the submission, include pairs of fields whose names start with googledrivedocname and googledrivedocurl, respectively, and end with the same numeric suffix. For example, to add a single Google Drive document attachmentr, include fields named googledrivedocname0 and googledrivedocurl0 in the form. To add two Google Drive document attachments, additionally include the fields named googledrivedocname1 and googledrivedocurl1. - To add media file attachments to the submission include pairs of fields whose names start with medianame and mediapath, respectively, and end with the same numeric suffix. For example, to add a single media file attachment, include fields named medianame0 and mediapath0 in the form. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/GetWorkInProgress.md) - [DeleteWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/DeleteWorkInProgress.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # RedeemCommandToken This command redeems a command token using the code given to the currently authenticated user by the creator. The response from this command is the response from the action associated with the command token being redeemed, so it can vary greatly. Errors triggered during the search to find the command token and the redemption authorization will be returned in the top-level response. Errors triggered while executing the action will be returned in an inner response or responses element. If the calling user is not authenticated, scopedomainid must be specified, and the action will run as the token's runasuserid account with the proxy account set as -1. The action will be executed with the currently authenticated user proxied as the command token's 'runasuserid' user just for the execution of the action (even if the currently authenticated user doesn't normally have proxy rights--the command token gives them these limited proxy rights). Any additional parameters specified will be available to the action as replacement variables. If there is more than one matching (and valid) command token (if the command token id is specified, only one can match), all of them will be redeemed. Note that the output from this function is very different from other functions because it embeds potentially multiple API calls within its response. There is a rate limit for ReedemCommandToken designed to thwart both brute-force guessing of the token as well as overloading the system with processing expensive tokens. The limit may vary. If you need a token that is secure, using a token with a large length will ensure that brute-force guesses will not be possible in a reasonable amount of time. ## Request **Method:** GET **Rights:** None, depending on the parameters used when the token was created. See CreateCommandTokens for details. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `redeemcommandtoken` | | `code` | string | Yes | The code, which can be either a user-specific code or a universal code associated with the command token. | | `commandtokenid` | id | No | The ID of the command token (if previously determined). Optional. Speeds up processing and guarantees which token is redeemed if specified, otherwise the first matching token will be redeemed. | | `scopedomainid` | id | No | The ID of a domain used to lookup the command token (one with a scope of the domain) when the user is not authenticated. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "response": { "code": "code", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "response": { "code": "code", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ] } } } } ``` ### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | #### responses *(optional)* ##### response *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ###### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ####### responses *(optional)* ######## response *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example is what would be executed by an unprivileged user to use a command token with the code 'g4m' in either the user's domain, a course they are enrolled in, a group they are a member of, or a code that is user-specific. **URL:** `?cmd=redeemtoken&code=g4m` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "enrollment": { "enrollmentid": "2336826" } } ] } } } ] } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [UpdateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/UpdateCommandTokens.md) - [Api Rate Limiting](https://api.agilixbuzz.com/docs/entry/Concept/ApiRateLimiting.md) --- # RemoveGroupMembers This command removes one or more member enrollments from an existing group. ## Request **Method:** POST **Rights:** ControlCourse|UpdateCourse|SetupGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `removegroupmembers` | **Request body (JSON):** ```json { "requests": { "member": [ { "groupid": "id", "courseid": "id", "enrollmentid": "id" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `member.groupid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the group to remove members from. | | `member.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Schema 4+: ID of the owning course. When present, groupid is interpreted as a string group identifier within the course data rather than a group entity ID. | | `member.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the enrollment to remove from the group. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GroupEntityMembersChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityMembersChanged.md) | During the request | Once per group whose membership the request changes. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Removes an enrollment from the group with ID 204235. **URL:** `?cmd=removegroupmembers` **Request body:** ```json { "requests": { "member": [ { "groupid": "204235", "enrollmentid": "177933" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [AddGroupMembers](https://api.agilixbuzz.com/docs/entry/Command/AddGroupMembers.md) - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) --- # ResetLockout This command resets an account that has been locked out due to too many contiguous password failures. ## Request **Method:** POST **Rights:** UpdateUser@userid **Request body (JSON):** ```json { "request": { "cmd": "resetlockout", "userid": "id" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `resetlockout` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user whose account lockout is to be reset. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAccountUnlocked](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAccountUnlocked.md) | During the request | An administrator cleared the lockout on the named account. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the user with ID 6158 already exists. **Request body:** ```json { "request": { "cmd": "resetlockout", "userid": "6158" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # ResetPassword This command sends an email to the specified user with a time-limited link that can be used to reset their password. If the user has a password question-answer configured and the logged-in user doesn't have rights to update the specified user account, the passsword answer will also be required. If the logged-in user has ControlUser rights over this account or if the firstname and lastname match the values for the account (with a small margin for error), detailed error information will be returned. Otherwise, no error information will be returned and the call will always appear to succeed. This is to prevent automated account validity testing to harvest user accounts. A partial email address, first login date, and creation date will also be returned. These values will be randomly generated if the specified account was not valid, but may help the end-user to know whether or not the username was correct. A domain administrator may add a ResetPassword.tmpl file to the domain to customize the email message the server sends to the user. ## Request **Method:** POST **Request body (JSON):** ```json { "request": { "cmd": "resetpassword", "username": "string", "firstname": "string", "lastname": "string", "answer": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `resetpassword` | Yes | | | `username` | string | Yes | userspace/username of the user for whom to reset the password. | | `firstname` | string | No | The first name of the user. | | `lastname` | string | No | The last name of the user. | | `answer` | string | No | The answer to the reset password question as specified by the user. This parameter is only required if the specified user account has a password question configured and the logged-in user doesn't have UpdateUser rights over that user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "partialemail": "string", "firstlogindate": "datetime", "creationdate": "datetime" } } } ``` ### user This node conforms to the User format, except for the partialemail field, which is only partial data. | Attribute | Type | Description | |-----------|------|-------------| | `partialemail` | string | A partial email address to show the user to possibly help them determine whether or not their request was successful. | | `firstlogindate` | datetime | The user's first-ever login date. | | `creationdate` | datetime | The date and time when this user's account record was created. | ## Example Reset the password of user sroberts in the domain with login prefix ussu. **Request body:** ```json { "request": { "cmd": "resetpassword", "username": "ussu/sroberts" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "partialemail": "s******s@gmail.com", "firstlogindate": "1753-01-01T00:00:00Z", "creationdate": "2007-11-12T16:48:13.483Z" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [FinishPasswordReset](https://api.agilixbuzz.com/docs/entry/Command/FinishPasswordReset.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) - [Reset Password Email Customization](https://api.agilixbuzz.com/docs/entry/Concept/ResetPasswordEmail.md) --- # RestoreAnnouncements This command restores one or more domain or course announcements. ## Request **Method:** POST **Rights:** PostDomainAnnouncements|ReadDomain@entityid when entityid is a domain ID, OR UpdateCourse|ReadGradebook|SetupGradebook|GradeExam|GradeAssignment|GradeForum@entityid when entityid is a course ID **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreannouncements` | **Request body (JSON):** ```json { "requests": { "announcement": [ { "entityid": "id", "path": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `announcement.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of domain or course for the announcement | | `announcement.path` | string | Yes | Path of the announcement | | `announcement.version` | string | Yes | Version of the announcement. If omitted the most recent version is used. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example restores a announcement in the domain with ID 1274 with path path e362a72809af4dd882797522d9db6c61.zip. **URL:** `?cmd=restoreannouncements` **Request body:** ```json { "requests": { "announcement": [ { "entityid": "1274", "path": "e362a72809af4dd882797522d9db6c61.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/DeleteAnnouncements.md) - [GetAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncement.md) - [GetAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementList.md) - [ListRestorableAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableAnnouncements.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # RestoreCourse This command restores a deleted course. ## Request **Method:** GET **Rights:** DeleteCourse@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restorecourse` | | `courseid` | id | Yes | ID of the course to restore | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityRestored.md) | During the request | For the course named in the request. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores a course with ID 6048. **URL:** `?cmd=restorecourse&courseid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [DeleteCourses](https://api.agilixbuzz.com/docs/entry/Command/DeleteCourses.md) - [GetCourse2](https://api.agilixbuzz.com/docs/entry/Command/GetCourse2.md) - [ListCourses](https://api.agilixbuzz.com/docs/entry/Command/ListCourses.md) - [UpdateCourses](https://api.agilixbuzz.com/docs/entry/Command/UpdateCourses.md) --- # RestoreDocuments This command restores one or more documents. ## Request **Method:** POST **Rights:** Participate | GradeAssignment | GradeExam | GradeForum | SetupGradebook@enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoredocuments` | **Request body (JSON):** ```json { "requests": { "document": [ { "enrollmentid": "id", "itemid": "string", "path": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `document.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user enrollment. | | `document.itemid` | string | Yes | Item id of the associated item. | | `document.path` | string | Yes | Path of the document. | | `document.version` | string | No | Version of the document. If omitted, the most recent version is used. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example **URL:** `?cmd=restoredocuments` **Request body:** ```json { "requests": { "document": [ { "enrollmentid": "4317", "itemid": "assign", "path": "assign.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) - [DeleteDocuments](https://api.agilixbuzz.com/docs/entry/Command/DeleteDocuments.md) - [GetDocument](https://api.agilixbuzz.com/docs/entry/Command/GetDocument.md) --- # RestoreDomain This command restores a deleted domain. ## Request **Method:** GET **Rights:** DeleteDomain@domainid. Not available with a domain-scoped token. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoredomain` | | `domainid` | id | Yes | ID of the domain to restore | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityRestored.md) | During the request | For the domain named in the request, during the request. Each descendant domain restored with it produces a further event later. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores a domain with ID 6048. **URL:** `?cmd=restoredomain&domainid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [DeleteDomain](https://api.agilixbuzz.com/docs/entry/Command/DeleteDomain.md) - [GetDomain2](https://api.agilixbuzz.com/docs/entry/Command/GetDomain2.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) --- # RestoreEnrollment This command restores a deleted enrollment. ## Request **Method:** POST **Rights:** ControlCourse@entityid when the enrollment’s entityid refers to a course **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreenrollment` | | `enrollmentid` | id | Yes | ID of the enrollment to restore | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example restores a enrollment with ID 6048. **URL:** `?cmd=restoreenrollment&enrollmentid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [DeleteEnrollments](https://api.agilixbuzz.com/docs/entry/Command/DeleteEnrollments.md) - [GetEnrollment3](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment3.md) - [ListEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEnrollments.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # RestoreItems This command restores one or more items in a manifest. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreitems` | **Request body (JSON):** ```json { "requests": { "item": [ { "entityid": "id", "itemid": "string", "version": "string", "groupid": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `item.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course that owns the item. | | `item.itemid` | string | Yes | ID of the item. | | `item.version` | string | No | Optional version of the item. If omitted, the most current version is used. | | `item.groupid` | string | No | Schema 4+: when entityid is a course, restores the group-specific override for the specified group rather than the course-level item. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemRestored.md) | During the request | For each course item restored by the request. | | [EnrollmentItemRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemRestored.md) | During the request | For each enrollment item restored by the request. | | [GroupItemRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupItemRestored.md) | During the request | For each group item restored by the request. | Which of the course, enrollment, or group item events is sent is determined by the type of the entity the item belongs to. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores an item with ID “Assignment12" in the course whose ID is 4378. **URL:** `?cmd=restoreitems` **Request body:** ```json { "requests": { "item": [ { "entityid": "4378", "itemid": "Assignment12" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [ListRestorableItems](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableItems.md) --- # RestoreMessages This command restores one or more messages in a discussion forum. ## Request **Method:** POST **Rights:** GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoremessages` | **Request body (JSON):** ```json { "requests": { "message": [ { "entityid": "id", "itemid": "string", "messageid": "string", "groupid": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `message.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity (course or section) that owns the message. | | `message.itemid` | string | Yes | ID of the discussion forum item from the course manifest that this message is in. | | `message.messageid` | string | Yes | ID of the message. | | `message.groupid` | string | No | Optional group ID that owns the message. | | `message.version` | string | No | Optional version of the message to restore. If omitted, the most current version is used. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example restores a message with ID "89b2b64f710949018d5cf618a0bb681e.zip" from in the forum item "Forum12" in entity with ID 4378. **URL:** `?cmd=restoremessages` **Request body:** ```json { "requests": { "message": [ { "entityid": "4378", "itemid": "Forum12", "messageid": "89b2b64f710949018d5cf618a0bb681e.zip" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteMessages](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessages.md) - [ListRestorableMessages](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableMessages.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) --- # RestoreObjectiveSet This command restores a deleted objective set. ## Request **Method:** GET **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreobjectiveset` | | `setid` | id | Yes | ID of the set to restore | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example restores a objective set with ID 6048. **URL:** `?cmd=restoreobjectiveset&setid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveSets.md) - [GetObjectiveSet2](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSet2.md) - [ListObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/ListObjectiveSets.md) - [UpdateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/UpdateObjectiveSets.md) --- # RestoreQuestions This command restores one or more questions in a course. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restorequestions` | **Request body (JSON):** ```json { "requests": { "question": [ { "entityid": "id", "questionid": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `question.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course that owns the question. | | `question.questionid` | string | Yes | ID of the question to restore. | | `question.version` | string | No | Optional version of the question. If omitted, the most current version is used. If the question to be restored is in a derivative course, you can specify master to restore to the current base version and to re-connect the question with the base course's question; any future updates to the base question automatically flow to the derivative question. If a base question with questionid does not exist, the derivative question identified by questionid is removed. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example restores a question with ID "00d025a61e6e46f888245f887324cecb" from the course with ID 111963. **URL:** `?cmd=restorequestions` **Request body:** ```json { "requests": { "question": [ { "entityid": "111963", "questionid": "00d025a61e6e46f888245f887324cecb" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteQuestions](https://api.agilixbuzz.com/docs/entry/Command/DeleteQuestions.md) - [ListRestorableQuestions](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableQuestions.md) - [PutQuestions](https://api.agilixbuzz.com/docs/entry/Command/PutQuestions.md) --- # RestoreResources This command restores one or more resources in a domain, course, or enrollment. ## Request **Method:** POST **Rights:** UpdateDomain@entityid when entityid refers to a domain; UpdateCourse@entityid when entityid refers to a course; UpdateEnrollment@entityid when entityid refers to an enrollment, GradeAssignment@the enrollment's entity ID, or Participate@entityID and the enrollment is active. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreresources` | **Request body (JSON):** ```json { "requests": { "resource": [ { "entityid": "id", "path": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `resource.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity (domain, course, or enrollment) that owns the resource. | | `resource.path` | string | Yes | Path of the resource to restore. | | `resource.version` | string | No | Optional version of the resource to restore. If omitted, the most current version is used. If the resource to be restored is in a derivative course, you can specify master to restore to the current base version and to re-connect the resource with the base course's resource; any future updates to the base resource automatically flow to the derivative resource. If a base resource with path does not exist, the derivative resource identified by path is removed. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each parent folder a restore recreates when the restored file's folder had also been deleted. | | [CourseResourceRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceRestored.md) | During the request | For each resource restored, including reverting a derivative course's file to the version inherited from its base course. | These events are sent only when the entity is a course and the resource is in the course's default (unclassed) content storage. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores a resource with ID "Assets/index.html" from the course with ID 111963. **URL:** `?cmd=restoreresources` **Request body:** ```json { "requests": { "resource": [ { "entityid": "111963", "path": "Assets/index.html" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteResources](https://api.agilixbuzz.com/docs/entry/Command/DeleteResources.md) - [ListRestorableResources](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableResources.md) - [PutResource](https://api.agilixbuzz.com/docs/entry/Command/PutResource.md) --- # RestoreRole This command restores a role that has been previously deleted. ## Request **Method:** GET **Rights:** UpdateDomain@domainid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restorerole` | | `roleid` | long | Yes | ID of the role to restore. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example restores a role with ID 98243089. **URL:** `?cmd=restorerole&roleid=98243089` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateRole](https://api.agilixbuzz.com/docs/entry/Command/CreateRole.md) - [DeleteRole](https://api.agilixbuzz.com/docs/entry/Command/DeleteRole.md) - [ListRoles](https://api.agilixbuzz.com/docs/entry/Command/ListRoles.md) --- # RestoreUser This command restores a deleted user. ## Request **Method:** POST **Rights:** DeleteUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restoreuser` | | `userid` | id | Yes | ID of the user to restore | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserEntityRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityRestored.md) | During the request | For the user named in the request. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores a user with ID 6048. **URL:** `?cmd=restoreuser&userid=6048` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser2](https://api.agilixbuzz.com/docs/entry/Command/GetUser2.md) - [ListUsers](https://api.agilixbuzz.com/docs/entry/Command/ListUsers.md) - [UpdateUsers](https://api.agilixbuzz.com/docs/entry/Command/UpdateUsers.md) --- # RestoreWikiPages This command restores one or more wiki pages in a course or section. ## Request **Method:** POST **Rights:** UpdateCourse@entityid when entityid refers to a course; GradeForum@entityid when entityid refers to a section **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `restorewikipages` | **Request body (JSON):** ```json { "requests": { "wikipage": [ { "entityid": "id", "groupid": "string", "itemid": "string", "slug": "string", "version": "string" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `wikipage.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course or section that owns the wiki page. | | `wikipage.groupid` | string | No | Optional group ID that owns the wiki page. | | `wikipage.itemid` | string | Yes | ID of the wiki item that this wiki page is in. | | `wikipage.slug` | string | Yes | String that uniquely identifies the page within the item wiki. | | `wikipage.version` | string | No | Optional version of the wiki page. If omitted, the most current version is used. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseResourceCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceCreated.md) | During the request | For each parent folder a restore recreates when the restored page's folder had also been deleted. | | [CourseResourceRestored](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseResourceRestored.md) | During the request | For each page restored in the course's *(Initial)* group, which is stored as course content files; pages of other groups send no content events. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example restores a wiki page with slug "Page-Three" from the wiki item "Wiki12" in section with ID 111963. **URL:** `?cmd=restorewikipages` **Request body:** ```json { "requests": { "wikipage": [ { "entityid": "111963", "itemid": "Wiki12", "slug": "Page-Three" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteWikiPages](https://api.agilixbuzz.com/docs/entry/Command/DeleteWikiPages.md) - [ListRestorableWikiPages](https://api.agilixbuzz.com/docs/entry/Command/ListRestorableWikiPages.md) - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) --- # RunReport This command runs the specified report. ## Request **Method:** GET **Rights:** ReportDomain@entityid when entityid is a domain ID; ReportCourse@entityid when entityid is a course ID; ReportSection@entityid when entityid is a section ID; ReportUser@entityid when entityid is a user ID; ReportDomain@entityid or ReportCourse@entityid when entityid is an objective set ID. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `runreport` | | `reportid` | id | Yes | The ID of the report to run. | | `entityid` | id | Yes | The domain, course/section, user, or objective set entity ID on which the report is to be run. | | `format` | string | No | The desired format of the output. If omitted the response is a standard API Server XML response with response code and XML body. When format is csv the output is a comma-separated value file. When format is json the output will be in JSON instead of XML. When format is xml the output will be in the XML, just as it would if you didn't specify the format. Possible report formats can be determined using GetReportInfo. | | `content-disposition` | string | Yes | The value to send back in a content-disposition header. If empty (default), no Content-Disposition header will be returned. If not empty, a filename will also be returned in that header. | | `nodata` | string | Yes | Localized text to write into CSV output if CSV is used and there are no rows of data to put in the results. | | `parameter1..n` | string | No | The parameters and values required by this report. | | `spreadsheet` | boolean | No | Whether or not the generated CSV should be in spreadsheet format. Always use this for Excel, Google Sheets, or other spreadsheets, but not to import into other databases. The default is to assume the CSV will be used with a spreadsheet (true). | Parameter and column types are in XML type name format (boolean, byte, int, double, float, string, dateTime, time, duration, and so forth.) ## Response **Content-Type:** text/xml, application/json, text/csv, text/html or other depending on the format ## Example This example runs a report with ID 411174 on the domain ID 9909. The report also accepts the additional AsOf parameter, which is a dateTime value. **URL:** `?cmd=runreport&reportid=411174&EntityId=9909&AsOf=2010-12-22T21%3a40%3a35Z` **Response** (code: `OK`): ```json { "response": { "code": "OK", "report": { "reportid": "411174", "name": "Grades", "description": "A grades report for a domain", "scopeentitytype": "D", "parameters": { "parameter": [ { "name": "EntityId", "type": "long", "value": "9909" }, { "name": "AsOf", "type": "dateTime", "value": "2010-12-22T21:40:35Z" } ] }, "body": { "rowset": { "title": "", "layout": "normal", "columns": { "column": [ { "name": "UserID", "type": "long" }, { "name": "TermStart", "type": "string" }, { "name": "TermEnd", "type": "string" }, { "name": "PercentGrade", "type": "double" }, { "name": "Grade", "type": "string" }, { "name": "Name", "type": "string" } ] }, "row": [ { "UserID": "15002", "TermStart": "06 Feb 2009", "TermEnd": "12 Feb 2020", "Section": "Section 1", "PercentGrade": "84", "Grade": "B", "Name": "Gammon, Kate" }, { "UserID": "15004", "TermStart": "06 Feb 2009", "TermEnd": "12 Feb 2020", "Section": "Section 1", "PercentGrade": "96", "Grade": "A", "Name": "Smith, John" } ] } }, "run": { "start": "2010-12-22T22:07:19.6768027Z", "elapsed": "PT0.0468012S" } } } } ``` ## See Also - [GetReportInfo](https://api.agilixbuzz.com/docs/entry/Command/GetReportInfo.md) - [GetReportList](https://api.agilixbuzz.com/docs/entry/Command/GetReportList.md) - [GetRunnableReportList](https://api.agilixbuzz.com/docs/entry/Command/GetRunnableReportList.md) --- # SaveAttemptAnswers Save answers for an assessment of homework group attempt for later use. ## Request **Method:** POST **Rights:** ReadCourse@entityid or UpdateCourse|GradeExam@entityid **Request body (JSON):** ```json { "request": { "enrollmentid": "id", "itemid": "string", "groupid": "string", "page": "int", "seconds": "int", "submission": [ { "partid": "string", "bookmark": "boolean", "clientdata": "string", "answer": { "$value": "string" }, "notes": { "$value": "string" } } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID | | `itemid` | string | Yes | Item ID | | `groupid` | string | No | Homework group ID, when item is homework. | | `page` | int | Yes | One-based index of current page. | | `seconds` | int | Yes | Number of seconds spent on the attempt. | | `submission.partid` | string | Yes | Partid of question | | `submission.bookmark` | boolean | No | Set to *true* to bookmark this question. | | `submission.clientdata` | string | No | Temporary opaque string data for client use. Stripped during submission. | | `submission.answer` | string | Yes | Question answer | | `submission.notes` | string | No | Student essay or workspace HTML content | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "answers": { "version": "string" } } } ``` ### answers | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | Version of the saved answers. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | Saving an attempt may score the answers saved so far. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | Saving an attempt may score the answers saved so far. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) - [SubmitAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SubmitAttemptAnswers.md) --- # Search2 This command searches course content that has been marked by course creators as searchable and returns a paginated list of results. The number of returned results are limited by the *start* and *limit* parameters. Programmers looking for non-indexed courses and items with known Item Data field values should not use Search2, but instead use GetItemList. See Free-Form Data Query for more details. See Search Querying for more details about the available query fields and the query syntax, or Search Indexing for more details about how to index your course items. ## Request **Method:** GET **Rights:** ReadCourse@entityid for each entity in entityid UpdateCourse@entityid or ReadCourseFull@entityid to see items that are marked as hiddenfromstudent **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `search2` | | `entityid` | id-list | No | A vertical-bar separated list of entity IDs representing the entities to search. Entity IDs can refer to course or domain IDs. Specifying a domain ID searches courses in the specified domain and its descendant domains. If omitted, you must specify subscriptions in order to obtain results. | | `omitentityid` | id-list | No | A vertical-bar separated list of entity IDs to exclude from results. Entity IDs can refer to course or domain IDs. Use this to omit entities such as the current course the user is viewing. | | `itemtype` | integer-list | No | A vertical-bar separated list of item type integers that specify what type of items you would like returned. (1 = assignment, 2 = assessment, etc.) The default is to return all item types. | | `subscriptions` | boolean | No | Indicates whether the searched-entity list should include entities that the current signed-in user is effectively subscribed to (see GetEffectiveSubscriptionList.) If false, you must specify entityid in order to obtain results. The default is *false*. | | `query` | string | No | The query to execute. See Search Querying for more details about how to construct a query. | | `limit` | int | No | The limit of the number of matches to return. This must be a number between 0 and 100. The default is 10. | | `start` | int | No | A zero based index of the position to start returning results for. This allows you to paginate search results by picking up where the previous search results left off. For example if your first request result had a limit of 10 and a start of 0 you would specify a start of 10 on the next call to see the next 10 results. This number must be between 0 and 1000. The default is 0. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "results": { "numfound": "int", "items": { "item": [ { "entityid": "id", "id": "string", "score": "double", "data": { "title": { "$value": "string" }, "description": { "$value": "string" }, "type": { "$value": "ItemType" }, "thumbnail": { "$value": "string" }, "learningobjectives": { "objective": [ { "guid": "string" } ] }, "meta-nnnn": [ { "$value": "mixed" } ] } } ] } } } } ``` ### results | Attribute | Type | Description | |-----------|------|-------------| | `numfound` | int | Total number of result documents found. | #### items ##### item | Attribute | Type | Description | |-----------|------|-------------| | `entityid` | id | ID of the entity that contains this item. | | `id` | string | The ID of this item. See PutItems for details about item IDs. | | `score` | double | The ranking score of the match. | ###### data ####### title ####### description ####### type ####### thumbnail ####### learningobjectives ######## objective | Attribute | Type | Description | |-----------|------|-------------| | `guid` | string | The ID of the learning objective to associate with this item. Items automatically inherit objectives from their parent folders. You override the automatic inheritance with this element. Learning objectives are defined in Course Data. | ####### meta-nnnn ## Example This example searches all courses in the domain with ID 121212 except the course with ID 345. It shows the results from a query for "imaginary numbers" in the "meta-abstract" field. Notice that we restrict the resulting number of matches to the limit of 2. **URL:** `?cmd=search2&entityid=121212&omitentityid=345&limit=2&query=meta-abstract:'imaginary numbers'` **Response** (code: `OK`): ```json { "response": { "code": "OK", "results": { "numfound": "19000", "items": { "item": [ { "entityid": "268973", "id": "190563C32FA94A2996C78653E6F2551B", "score": "0.45623", "data": { "title": { "$value": "Square Roots" }, "thumbnail": { "$value": "course/thumbs/343jerw.jpg" }, "type": { "$value": "Assignment" }, "meta-abstract": [ { "$value": "imaginary numbers" } ], "meta-author": [ { "$value": "Jeff Gammon" } ] } }, { "entityid": "469684", "id": "SODGD", "score": "0.2353", "data": { "title": { "$value": "Advanced Algebra" }, "type": { "$value": "Assessment" }, "description": { "$value": "Introductory topic for advanced algebra." }, "learningobjectives": { "objective": [ { "guid": "2890323fs34326667481457501832910" }, { "guid": "379177691004477788f7f604ce475885" } ] }, "meta-abstracts": [ { "meta-abstract": [ { "$value": "binomials" }, { "$value": "polynomials" } ] } ] } } ] } } } } ``` ## See Also - [Search Querying](https://api.agilixbuzz.com/docs/entry/Concept/SearchQuerying.md) - [Search Indexing](https://api.agilixbuzz.com/docs/entry/Concept/SearchIndexing.md) --- # SecondFactorAuthenticate This command completes the two factor part of authentication for users who have opted for two factor authentication. Note that if the clock on the OTP device is more than a minute or two off from the server's, an error will be returned. The server time will be included in the error message in case the user's device has an adjustable clock and is able to sync it. The client may want to display the server time for the user in this situation to alert them to this possibility, as it may provide them a simple fix for the problem that won't require administrative intervention. ## Request **Method:** POST **Rights:** None **Request body (JSON):** ```json { "request": { "cmd": "secondfactorauthentication", "otp": "string", "rememberdevice": "boolean" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `secondfactorauthentication` | Yes | | | `otp` | string | Yes | The one-time-password provided by the user. | | `rememberdevice` | boolean | No | Whether to remember this device for 30 days and not ask for MFA until then. Defaults to false. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string", "token": "string", "authenticationexpirationminutes": "int" }, "remembermfa": { "token": "string", "expirationminutes": "int" } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | User ID of the logged-in user. | | `username` | string | Username of the logged-in user. | | `firstname` | string | First name of the logged-in user. | | `lastname` | string | Last name of the logged-in user. | | `email` | email | E-mail address of the logged-in user. | | `domainid` | id | ID of the domain that contains the logged-in user. | | `domainname` | string | Name of the domain that contains the logged-in user. | | `userspace` | string | Userspace of the domain that contains the logged-in user. | | `token` | string | This is the authentication token which must be kept and passed to subsequent API commands in order to authenticate the account making the request. | | `authenticationexpirationminutes` | int | The number of minutes until the specified authentication token will timeout unless there are subsequent calls that affect it. The token expiration will automatically be extended when any calls other than ExtendSession are made, the token will be immediately expired when Logout is called, and the token may be explicitly revoked by an administrator prior to the normal expiration. This value is returned so that clients know how often they need to call ExtendSession or some other function to keep their authentication from expiring under normal circumstances. | ### remembermfa | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | A token received from SecondFactorAuthenticate that can be used to bypass multi-factor authentication (MFA) for the device. This token should not ever be transferred between devices. | | `expirationminutes` | int | The number of minutes until the specified remember MFA token will timeout unless there are subsequent calls that affect it. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAdminAuthenticated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminAuthenticated.md) | During the request | The authenticated account holds an active Administrator role. | | [AuthMFAFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthMFAFailed.md) | During the request | The supplied second factor was not accepted. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | Completing second-factor authentication starts the session, which updates the login dates. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | Completing second-factor authentication starts the session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **Request body:** ```json { "request": { "cmd": "secondfactorauthenticate", "token": "09a8gfDVCX8u90pufds909u0", "otp": "548203" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "4379", "username": "administrator", "firstname": "System", "lastname": "Administrator", "email": "administrator@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "token": "SYC-ihGJ|ML0jX11juQd8d8BtTPAuWC", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [CreateSecondFactorAuthenticationSecret](https://api.agilixbuzz.com/docs/entry/Command/CreateSecondFactorAuthenticationSecret.md) - [SetupSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/SetupSecondFactorAuthentication.md) - [ClearSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/ClearSecondFactorAuthentication.md) - [GetEffectivePasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/GetEffectivePasswordPolicy.md) - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [UpdateDomains](https://api.agilixbuzz.com/docs/entry/Command/UpdateDomains.md) - [PasswordPolicy](https://api.agilixbuzz.com/docs/entry/Schema/PasswordPolicy.md) --- # SendMail This command sends an e-mail to recipients that are enrolled in the same entity as that specified by the sender's enrollmentid. The POST data to this command must conform to the Mail format. If the send fails, SendMail auto-generates an e-mail and sends it to the sender containing the reason for failure. ## Request **Method:** POST **Rights:** enrollmentid must be the caller's enrollment and it must be active. **Content-Type:** application/json or text/xml **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `sendmail` | | `enrollmentid` | id | Yes | An active enrollment ID of the caller. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example sends an e-mail from the caller whose active enrollment ID is 45879 to the recipient whose enrollment ID is 303137. **URL:** `?cmd=sendmail&enrollmentid=45879` **Request body:** ```json { "email": { "enrollments": { "enrollment": [ { "id": "303137" } ] }, "subject": { "$value": "Can I get some help?" }, "body": { "$value": "<html><body><div>Will you please help me with my Biology some time?</div><div>&nbsp;</div><div>Thanks,</div><div>Kate</div></body></html>" } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Mail](https://api.agilixbuzz.com/docs/entry/Schema/Mail.md) --- # SetDataStreamConfiguration This command tests a given data stream configuration to see if it is valid and if the API servers can connect to it and if successful, sets that configuration in the specified domain. A data stream event will be sent to the newly-configured data stream as well as any other applicable data streams indicating that the data stream configuration was changed. Notice that although you will typically only need one data stream, you may configure more than one for a domain, as you could have multiple data streams for different kinds of processing for different events. This command replaces the domain's entire data stream configuration; it is not a partial update. To change an existing configuration, first retrieve it with GetDataStreamConfiguration, modify what you need, and submit the complete desired configuration. Any previously-configured target that is omitted from the request is removed, and a request containing no targets clears the configuration entirely. Within each target type, the targets are an ordered list and are matched to the previous configuration by position (the first target of a type corresponds to the previously-first target of that type, and so on), not by title or any other identifier. The title attribute is a human-readable label only and is not used to identify a target when reconfiguring, so if you reorder the targets of a type, they are treated as changes to the targets that previously occupied those positions. Filters allow you to specify exactly which event types you want to receive and exactly which object members you want to receive for each event type, which can drastically reduce the volume of data sent to the data stream. Each data stream may have zero or more filters identifying event types and the desired members to include for them. Multiple data streams, even within the same domain, may receive the same event. If you have more than one domain, you can set up data streams for each, and if one domain is a descendant of another, events will be sent to both sets of data streams, with the top-level domainId identifying the source domain (see Data Stream topic under Concepts). ## Request **Method:** POST **Rights:** ControlDomain **Request body (JSON):** ```json { "request": { "cmd": "setdatastreamconfiguration", "domainid": "string", "test": "boolean", "firehose": [ { "title": "string", "enabled": "boolean", "targetFirehoseStream": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "kinesis": [ { "title": "string", "enabled": "boolean", "targetKinesisStream": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "https": [ { "title": "string", "enabled": "boolean", "streamName": "string", "timeoutSeconds": "int", "retries": "int", "endpoints": "string", "httpMethod": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "sqs": [ { "title": "string", "enabled": "boolean", "targetSqsQueue": "string", "roleArn": "string", "targetRegion": "string", "filter": [ { "eventType": "string", "properties": "string" } ] } ], "email": [ { "title": "string", "enabled": "boolean", "streamName": "string", "to": "string", "maxEmailsPerHour": "int", "filter": [ { "eventType": "string", "properties": "string" } ] } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `setdatastreamconfiguration` | Yes | | | `domainid` | string | Yes | The id of the domain the data stream configuration would apply to. | | `test` | boolean | No | Whether or not this is just a test. If set, the configuration will be tested and a test message put to the stream, but the configuration will not be saved for use outside this call. If not set, the configuration will be saved if there are no errors. Defaults to false. | | `firehose.title` | string | Yes | An optional human-readable label to distinguish this target from others of the same type. It is a label only: reconfiguration replaces the whole configuration and matches targets by position, not by title. Recommended when a domain has more than one target of a given type. | | `firehose.enabled` | boolean | Yes | Whether this target is enabled or not (defaults to true). | | `firehose.targetFirehoseStream` | string | Yes | The name of the Kinesis Firehose Delivery Stream to put event records into (relative to the role, so no ARN is needed; defaults to us-east-1 unless targetRegion is specified). | | `firehose.roleArn` | string | Yes | The ARN of the role to use to connect to the Kinesis Firehose Delivery Stream. | | `firehose.targetRegion` | string | No | The AWS region of the target Firehose stream (for example, us-east-1). If omitted, us-east-1 is used. | | `firehose.filter.eventType` | string | No | An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `firehose.filter.properties` | string | No | A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desired property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | | `kinesis.title` | string | Yes | An optional human-readable label to distinguish this target from others of the same type. It is a label only: reconfiguration replaces the whole configuration and matches targets by position, not by title. Recommended when a domain has more than one target of a given type. | | `kinesis.enabled` | boolean | Yes | Whether this target is enabled or not (defaults to true). | | `kinesis.targetKinesisStream` | string | Yes | The name of the Kinesis Data Stream to put event records into (relative to the role, so no ARN is needed; defaults to us-east-1 unless targetRegion is specified). | | `kinesis.roleArn` | string | Yes | The ARN of the role to use to connect to the Kinesis Data Stream. | | `kinesis.targetRegion` | string | No | The AWS region of the target Kinesis stream (for example, us-east-1). If omitted, us-east-1 is used. | | `kinesis.filter.eventType` | string | No | An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `kinesis.filter.properties` | string | No | A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desired property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | | `https.title` | string | Yes | An optional human-readable label to distinguish this target from others of the same type. It is a label only: reconfiguration replaces the whole configuration and matches targets by position, not by title. Recommended when a domain has more than one target of a given type. | | `https.enabled` | boolean | Yes | Whether this target is enabled or not (defaults to true). | | `https.streamName` | string | Yes | A name for this data stream used to distinguish it from any others. | | `https.timeoutSeconds` | int | Yes | The number of seconds to use as a timeout for each attempt to notify a configured HTTPS endpoint. Defaults to 2 seconds. | | `https.retries` | int | Yes | The number of times to retry each endpoint before moving on to the next one. Defaults to 2 retries. | | `https.endpoints` | string | Yes | A semicolon-separated list of the URLs of HTTPS endpoints to call to put event records. The URLs may contain the brace sequences {PartitionKey} which will be replaced with a partition key before making the HTTP request. This allows you to partition the notification handling across multiple URLs. | | `https.httpMethod` | string | No | The HTTP method (PUT, POST) to use when sending event notification records. If not specified, defaults to POST. | | `https.filter.eventType` | string | No | An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `https.filter.properties` | string | No | A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desired property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | | `sqs.title` | string | Yes | An optional human-readable label to distinguish this target from others of the same type. It is a label only: reconfiguration replaces the whole configuration and matches targets by position, not by title. Recommended when a domain has more than one target of a given type. | | `sqs.enabled` | boolean | Yes | Whether this target is enabled or not (defaults to true). | | `sqs.targetSqsQueue` | string | Yes | The name of the SQS Queue to put event records into (relative to the role, so no ARN is needed; defaults to us-east-1 unless targetRegion is specified). | | `sqs.roleArn` | string | Yes | The ARN of the role to use to connect to the SQS Queue. | | `sqs.targetRegion` | string | No | The AWS region of the target SQS queue (for example, us-east-1). If omitted, us-east-1 is used. | | `sqs.filter.eventType` | string | No | An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `sqs.filter.properties` | string | No | A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desired property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | | `email.title` | string | Yes | An optional human-readable label to distinguish this target from others of the same type. It is a label only: reconfiguration replaces the whole configuration and matches targets by position, not by title. Recommended when a domain has more than one target of a given type. | | `email.enabled` | boolean | Yes | Whether this target is enabled or not (defaults to true). | | `email.streamName` | string | Yes | A unique name for this stream within the domain, used to identify it (for example, in the unsubscribe flow and in DataStreamEmailDropped events). Must contain only printable ASCII characters (no spaces or control characters) and be at most 200 characters. | | `email.to` | string | Yes | The email address that will receive the event notifications. Must be a valid email address. | | `email.maxEmailsPerHour` | int | No | A non-negative cap on the number of event emails this stream will send per fixed clock-hour window. When omitted, a default of 10 is used (this default is subject to change in a given environment). When the cap is reached, a single throttle-notice email is sent to the recipient and a single DataStreamEmailDropped event is emitted to any other non-email data streams for the domain; further events in that window are discarded. Because of this cap, the email target is intended only for rare, high-importance events; use a different target type for a complete record. | | `email.filter.eventType` | string | No | An event name or a regular expression indicating which event types to receive at this data stream. If not specified, all event types will be included. | | `email.filter.properties` | string | No | A comma-separated list of property names to include in the record written to the data stream. Property names for child objects can be referenced using the name of the property containing the child object followed by a period, followed by the name of the desired property within the child. If the name of a property containing a child object is specified by itself, all child properties will be included. If not specified or empty, all properties from any matching event types will be included. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "firehose": [ { "code": "code", "message": "string" } ] } } ``` ### firehose | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | OK or an error code. | | `message` | string | *(optional)* The error message if an error occurred. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [ValidateDataStreamConfiguration](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/ValidateDataStreamConfiguration.md) | During the request | Sent to every target named in the request, whether or not the test attribute is set. Delivery failure fails validation for that target and the configuration is not saved. | | [DataStreamConfigurationChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DataStreamConfigurationChanged.md) | During the request | The domain already had a configuration and the request replaced it. | | [DataStreamConfigurationCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DataStreamConfigurationCreated.md) | During the request | The domain had no data stream configuration before the request. | | [DataStreamConfigurationDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DataStreamConfigurationDeleted.md) | During the request | The request removed the domain's entire configuration. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Attempt to set a configuration with a firehose stream that does not exist. **Request body:** ```json { "request": { "cmd": "setdatastreamconfiguration", "domainid": "582075", "firehose": [ { "targetFirehoseStream": "test-firehose-doesnt-exist", "roleArn": "arn:aws:iam::765890427748:role/firehose-agilix-acess-role" } ] } } ``` **Response:** ```json { "response": { "firehose": [ { "code": "testfirehoseconfiguration", "message": "Firehose test-firehose-doesnt-exist not found under account 572751075432.", "errorId": "1c8d6eac015e45a89391f57e37c50fed" } ] } } ``` ## See Also - [Data Stream Concept Overview](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) - [GetDataStreamConfiguration](https://api.agilixbuzz.com/docs/entry/Command/GetDataStreamConfiguration.md) --- # SetPasswordPolicy Sets the password policy for the specified domain (and persona, if specified). The password policy is stored in the data property of the domain. This is a full replacement, not a merge: the domain's existing policy node for the specified persona (or the base policy node when no persona is specified) is removed and replaced with the given policy, so any attribute omitted from the request is reset to its default. Callers editing an existing policy should first read it with GetRawPasswordPolicy and send back the complete policy. Note that a base policy set here shadows any base policy inherited from ancestor domains entirely (base policies are resolved nearest-ancestor-wins), while persona policies at every level of the hierarchy are merged with each attribute's strictest value winning. **A requirement attribute does nothing until its enforcement attribute is also set.** Each enforcement attribute defaults to None when omitted, and None means the requirements it governs are stored and reported but never checked: a policy carrying minimumlength with no complexityenforcement will accept a one-character password. See Password Policy for which enforcement attribute governs which requirements, and which attributes need no enforcement at all. ## Request **Method:** POST **Rights:** ControlDomain@domainid **Request body (JSON):** ```json { "request": { "cmd": "setpasswordpolicy", "domainid": "id", "persona": "string", "passwordpolicy": { "maxage": "timespan", "loginattempthistoryretentiontime": "timespan", "lockoutaftertries": "int", "lockoutduration": "timespan", "lockoutstaleaccountsafter": "timespan", "minimumlength": "int", "minimumcharacterclasses": "int", "recycletime": "timespan", "complexityenforcement": "PasswordPolicyEnforcement", "additionalcontextwords": "string", "minimumentropy": "int", "entropyenforcement": "PasswordPolicyEnforcement", "pwnenforcement": "PasswordPolicyEnforcement", "mfaenforcement": "PasswordPolicyEnforcement" } } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `setpasswordpolicy` | Yes | | | `domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the domain to set the password policy for. Required. | | `persona` | string | No | An optional persona name to which these password policy restrictions should apply. When specified, the persona-specific policy node is replaced and the base policy node is left untouched (and vice versa). | | `passwordpolicy.maxage` | timespan | No | The maximum time a password can be used for accessing the system. After a password reaches this age, it can only be used to set a new password. The default behavior is not to expire passwords (forever). | | `passwordpolicy.loginattempthistoryretentiontime` | timespan | No | The length of time password login attempts are recorded (the longest of what is required by this, what is required by the lockout rules, or the system-wide minimum is what will be retained). The default is none, which will use the system-wide minimum. | | `passwordpolicy.lockoutaftertries` | int | No | The maximum number of times a user can enter the wrong password before their account is locked out, requiring an administrator to unlock it. The default behavior is not to lock out accounts. | | `passwordpolicy.lockoutduration` | timespan | No | The length of time an account remains locked out after a lockout occurs. The default is forever, but this only applies if a lockout count is set. An administrator must call ResetLockout | | `passwordpolicy.lockoutstaleaccountsafter` | timespan | No | A duration of time after the last login (or after account creation if no logins have occurred) after which the account will be locked out just as if too many bad passwords were entered, but even if account lockout is not configured. | | `passwordpolicy.minimumlength` | int | No | The minimum number of characters required for an acceptable password. The default behavior if not specified is to require passwords at least one character in length (1). Governed by complexityenforcement: not checked unless that attribute is set to something other than None. | | `passwordpolicy.minimumcharacterclasses` | int | No | The minimum number of character classes (a-z, A-Z, 0-9, other) required for an acceptable password. The default behavior is no restriction based on character class count (0). Governed by complexityenforcement: not checked unless that attribute is set to something other than None. | | `passwordpolicy.recycletime` | timespan | No | The amount of time to store old passwords and prevent their reuse. The default behavior is not to block password reuse (zero time). Governed by complexityenforcement: not checked unless that attribute is set to something other than None, and only ever checked when a password is being set. | | `passwordpolicy.complexityenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | No | Whether and how to enforce the minimumlength, minimumcharacterclasses and recycletime requirements. Defaults to None when absent, which leaves all three unenforced. | | `passwordpolicy.additionalcontextwords` | string | No | A comma-separated list of strings associated with the domain that will lower the entropy score when they are used as any part of the password. This should include parts of the names of the hostname of the website as well as parts of the name of the school(s) this policy applies to. | | `passwordpolicy.minimumentropy` | int | No | The minimum number of bits of estimated entropy for new passwords, adjusting for patterns commonly used by users to just meet old-style complexity requirements, such as capitalizing a single character, substituting the letter oh with zero, adding a 1 or ! at the end of a password, including the website name, using family names, using common words, etc. This is a "volatile" property, as the implementation may change at any time, causing password that passed before the implementation change to begin failing after the change, without any change to the policy itself. | | `passwordpolicy.entropyenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | No | Whether and how to enforce the minimumentropy requirement. Defaults to None when absent, which leaves the minimum entropy unenforced and additionalcontextwords with no effect. | | `passwordpolicy.pwnenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | No | Whether and how to enforce passwords found in publicly-available data breaches. Defaults to None when absent, which means breached passwords are not checked for at all. | | `passwordpolicy.mfaenforcement` | [PasswordPolicyEnforcement](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) | No | Whether and how to enforce one-time (TOTP) token requirements in addition to the password for accounts subject to this policy. If required but not yet established, the user will be required to setup MFA after logging in with their password but before doing anything else. The enforcement levels mean here what they mean elsewhere: the "on change" levels act when a password is being set and leave signing in alone, while the "on use" levels act at sign-in as well. BlockOnChange requires a user with no second factor to configure one when they change their password, and BlockOnUse requires it at sign-in. WarnOnChange only recommends one, at a password change. **WarnOnUse both recommends and requires**: it recommends at sign-in without stopping the user, but - as a warning level does for every other requirement - it still *blocks* a password change, so a user with no second factor is required to configure one before they can change their password. The obsolete WarnVolatileOnUse and BlockVolatileOnUse are treated as WarnOnUse and BlockOnUse respectively. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "response": { "code": "code", "message": "string", "passwordpolicy": {} } } } ``` ### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | #### passwordpolicy ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityChanged.md) | During the request | The password policy is stored in the domain record, so changing it changes the domain. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example sets stricter password policy restrictions for users with a Teacher persona in domain 1483920. **Request body:** ```json { "request": { "cmd": "setpasswordpolicy", "domainid": "1483920", "persona": "Teacher", "passwordpolicy": { "minimumentropy": "50", "entropyenforcement": "BlockOnChange" } } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [PasswordPolicyEnforcement Enum](https://api.agilixbuzz.com/docs/entry/Enum/PasswordPolicyEnforcement.md) - [PasswordPolicy Schema](https://api.agilixbuzz.com/docs/entry/Schema/PasswordPolicy.md) - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [GetEffectivePasswordPolicy](https://api.agilixbuzz.com/docs/entry/Command/GetEffectivePasswordPolicy.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # SetupSecondFactorAuthentication Turns on second factor authentication for an account. If using notification-based 2FA, this API must be called twice. The first call will not configure 2FA but will send ONE OTP code to the caller through the selected external channel and that one OTP code must be passsed into a second call to this function as otp1. If using app based 2FA, an encryption key must be generated by the caller, possibly using CreateSecondFactorAuthenticationSecret. If using device-based 2FA, the secret must be obtained from the device and the caller must pass it in. Once 2FA is established, Login3 will return an MFA warning and a token on each login attempt. The token and the one-time-password should then be sent to SecondFactorAuthenticate to complete the authentication process. The number of digits in otp1 and otp2 must be the same, and will establish how many OTP digits are required when signing in if MFA setup is successful. Requiring 2FA codes from the app ensures that it received the correct secret and algorithm. Requiring 2FA codes via email ensures that the user has access to the email account and won't be locked out by performing this operation. ## Request **Method:** POST **Rights:** Only acts on the authenticated user account. **Request body (JSON):** ```json { "request": { "cmd": "setupsecondfactorauthentication", "delivery": "string", "encryption": "string", "secret": "string", "otp1": "string", "otp2": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `setupsecondfactorauthentication` | Yes | | | `delivery` | string | Yes | None\|Email. The method the user will use to get the TOTP code when attempting to login. Defaults to None, which means that the user has a hardware device or software (app) which will generate the TOTP codes, so no delivery from the server is needed. | | `encryption` | string | No | The encryption type for the 2FA secret, possibly obtained from CreateSecondFactorAuthenticationSecret. Defaults to SHA256. Not needed if delivery type is Email. | | `secret` | string | No | The 2FA secret, possibly obtained from CreateSecondFactorAuthenticationSecret. Must be a 16, 26, or 32 character BASE-32 string as specified in the TOTP RFC 6238. Not needed if delivery type is Email. | | `otp1` | string | No | The first one-time-password corresponding to the specified encryption and secret (must be six, seven, or eight digits). Time-sensitive. Not needed if delivery type is Email. | | `otp2` | string | No | A second (subsequent) one-time-password corresponding to the specified encryption and secret (must be six, seven, or eight digits). Time-sensitive. Not needed if delivery type is Email. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Example This example initiates set up of email-based 2FA for the currently authenticated user using email delivery of 2FA TOTP codes. An email will be delivered with the OTP code the user must provide to complete the setup process with a second call to this API. **Request body:** ```json { "request": { "cmd": "setupsecondfactorauthentication", "delivery": "Email" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "54237890", "mfa": "false" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [ClearSecondFactorAuthentication](https://api.agilixbuzz.com/docs/entry/Command/ClearSecondFactorAuthentication.md) - [CreateSecondFactorAuthenticationSecret](https://api.agilixbuzz.com/docs/entry/Command/CreateSecondFactorAuthenticationSecret.md) - [SecondFactorAuthenticate](https://api.agilixbuzz.com/docs/entry/Command/SecondFactorAuthenticate.md) --- # SubmitAttemptAnswers Submits answers for an assessment of homework group attempt for grading. ## Request **Method:** POST **Rights:** ReadCourse@entityid or UpdateCourse|GradeExam@entityid **Request body (JSON):** ```json { "request": { "enrollmentid": "id", "itemid": "string", "groupid": "string", "page": "int", "seconds": "int", "submission": [ { "partid": "string", "answer": { "$value": "string" }, "notes": { "$value": "string" } } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID | | `itemid` | string | Yes | Item ID | | `groupid` | string | No | Homework group ID, when item is homework. | | `page` | int | Yes | One-based index of current page. | | `seconds` | int | Yes | Number of seconds spent on the attempt. | | `submission.partid` | string | Yes | Partid of question | | `submission.answer` | string | Yes | Question answer | | `submission.notes` | string | No | Student essay or workspace HTML content | The HTTP Content-Type header specifies the format of the POST data. SubmitAttemptAnswers handles the following header values as defined. - **application/json** - The POST data is JSON in the format defined for answers above. - **text/xml** - The POST data is XML in the format defined for answers above. - **multipart/form-data** - The POST data is multipart form data. SubmitAttemptAnswers saves each file in the multipart data as a submission attachment. You should also include an answers field that contains either XML or JSON in for format defined for answers above. ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "submission": { "version": "string", "excuseditems": "boolean", "remediateitems": "boolean" } } } ``` ### submission | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put student submission. | | `excuseditems` | boolean | *(optional)* Set to *true*, if items were excused in the course because of this submission. | | `remediateitems` | boolean | *(optional)* Set to *true*, if items where flagged for remediation because of this submission. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityActivity.md) | During the request | Enrollment activity cascades up to the course. | | [DomainEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityActivity.md) | During the request | Enrollment activity cascades up through the course to the domain. | | [EnrollmentEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityActivity.md) | During the request | Submitting an attempt records the time spent against the enrollment. | | [EnrollmentMetricsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsChanged.md) | During the request | Submitting an attempt changes progress and score metrics. | | [EnrollmentMetricsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentMetricsCreated.md) | During the request | Submitting an attempt changes progress and score metrics. Sent the first time metrics are computed for the enrollment. | | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | Submitting an attempt scores it. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | Submitting an attempt scores it. Sent when no grade record existed for the item and student yet. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [GetAttempt](https://api.agilixbuzz.com/docs/entry/Command/GetAttempt.md) - [GetAttemptReview](https://api.agilixbuzz.com/docs/entry/Command/GetAttemptReview.md) - [SaveAttemptAnswers](https://api.agilixbuzz.com/docs/entry/Command/SaveAttemptAnswers.md) --- # SubmitMessage This command assembles changes from the PutMessagePart and DeleteMessagePart commands into a new message and posts the new message to the server. To undo message-part changes, see DeleteMessagePart. ## Request **Method:** POST **Rights:** Participate@entityid or GradeForum@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `submitmessage` | | `entityid` | id | Yes | ID of the entity (course, section, or enrollment) to post the message to. | | `itemid` | id | Yes | ID of the threaded discussion item from the course manifest. | | `messageid` | string | Yes | Unique message ID. To ensure uniqueness, we suggest a string in the format guid.zip, where guid is a 32-character GUID. Messageid has the same character restrictions as path in PutResource. | | `groupid` | string | No | Optional group ID to which the message belongs. If omitted, the default group is used. This command supports two special group IDs. - **(Common)** - Indicates the message is common to all groups. The system automatically includes the message in every group. - **(Initial)** - Indicates the message is part of a base course and derivative courses inherit the message in each group. | | `parentid` | string | No | When replying to another message, parentid is the messageid of the message being replied to. | | `status` | string | No | Specifies whether the message is hidden or not. Hidden messages are not visible to students. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": { "version": "string" } } } ``` ### message | Attribute | Type | Description | |-----------|------|-------------| | `version` | string | The version of the newly put message. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [GradeChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeChanged.md) | During the request | A graded discussion post is scored on submission. Sent when a grade record already existed. | | [GradeCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GradeCreated.md) | During the request | A graded discussion post is scored on submission. Sent when no grade record existed for the item and student yet. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## See Also - [PutMessagePart](https://api.agilixbuzz.com/docs/entry/Command/PutMessagePart.md) - [DeleteMessagePart](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessagePart.md) - [DeleteMessage](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessage.md) - [GetMessage](https://api.agilixbuzz.com/docs/entry/Command/GetMessage.md) - [UpdateMessageViewed](https://api.agilixbuzz.com/docs/entry/Command/UpdateMessageViewed.md) --- # SubmitWorkInProgress This command submits work-in-progress files on the server as a completed submission for the student. You must call PutWorkInProgress to put work-in-progress files on the server before calling *SubmitWorkInProgress*. ## Request **Method:** POST **Rights:** Participate@entityid or GradeExam|GradeAssignment|GradeDiscussion@entityid in the entity (course or section) referred to by enrollmentid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `submitworkinprogress` | | `enrollmentid` | id | Yes | ID of the user's enrollment to which this submission belongs. | | `itemid` | string | Yes | ID of the item (in the course manifest) to which this submission belongs. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "submission": { "version": "int" } } } ``` ### submission | Attribute | Type | Description | |-----------|------|-------------| | `version` | int | The version of the newly put student submission. "1" is the first submission, then "2", etc. | ## See Also - [Submission](https://api.agilixbuzz.com/docs/entry/Schema/Submission.md) - [GetWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/GetWorkInProgress.md) - [PutWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/PutWorkInProgress.md) - [DeleteWorkInProgress](https://api.agilixbuzz.com/docs/entry/Command/DeleteWorkInProgress.md) - [GetStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/GetStudentSubmission.md) - [PutStudentSubmission](https://api.agilixbuzz.com/docs/entry/Command/PutStudentSubmission.md) --- # TerminateUserSessions Ends a user's active login sessions, immediately invalidating the associated session tokens so they can no longer be used to access the system. Specify a session to end only that session, or omit it to end all of the user's sessions at once. This is commonly used to force re-authentication after a security-sensitive change (such as a password reset or a change to the user's rights), or to revoke access from a lost or compromised device. ## Request **Method:** POST **Rights:** ControlUser@userid to terminate another user's sessions; you may terminate your own sessions with an unscoped token (the self path requires no additional privilege). **Request body (JSON):** ```json { "request": { "cmd": "terminateusersessions", "userid": "id", "sessionid": "id" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `terminateusersessions` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of the user whose sessions are to be terminated. Uses the currently authenticated user if not specified. | | `sessionid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of a specific session to terminate (for example, one returned by ListUserSessions). If not specified, all of the user's active sessions are terminated. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | Once per session terminated by the request. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example terminates all active sessions for the user with ID 6158, forcing them to log in again. **Request body:** ```json { "request": { "cmd": "terminateusersessions", "userid": "6158" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) - [ExtendSession](https://api.agilixbuzz.com/docs/entry/Command/ExtendSession.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) --- # UnassignItem Unassigning an item changes the item’s parent and sequence to their default values (the values they would have if they had never been assigned). ## Request **Method:** POST **Rights:** UpdateCourse@entityid or (Participate@entityid and entityid refers to an enrollment and the current user is the enrollment's user and itemid's studentcanunassign attribute is true.) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `unassignitem` | | `entityid` | id | Yes | ID of the entity that owns the *itemid* item. | | `itemid` | string | Yes | Item ID of the item to unassign. | | `groupid` | string | No | Schema 4+: when entityid is a course, unassigns the item in the context of the specified group (removes the group-specific override). | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseItemChanged.md) | During the request | Unassigning an item changes it. | | [EnrollmentItemChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemChanged.md) | During the request | Unassigning an item changes the student's copy of it. | | [EnrollmentItemDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentItemDeleted.md) | During the request | Unassigning may remove the student-specific item. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example unassigns item ABCD in the 1234 enrollment. **URL:** `?cmd=unassignitem&entityid=1234&itemid=ABCD` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [AssignItem](https://api.agilixbuzz.com/docs/entry/Command/AssignItem.md) - [ListAssignableItems](https://api.agilixbuzz.com/docs/entry/Command/ListAssignableItems.md) - [Item Data Schema](https://api.agilixbuzz.com/docs/entry/Schema/ItemData.md) --- # Unproxy This command ends a proxy session. The command returns the token and user information for the original user. ## Request **Method:** POST **Request body (JSON):** ```json { "request": { "cmd": "unproxy", "noazt": "bool" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `unproxy` | Yes | | | `noazt` | bool | No | Indicates that the server should not set an authentication cookie. If not specified or false, uses the settings for the current session. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "userid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "email", "domainid": "id", "domainname": "string", "userspace": "string" } } } ``` ### user | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | User ID of the original user | | `username` | string | User name | | `firstname` | string | First name | | `lastname` | string | Last name | | `email` | email | Email | | `domainid` | id | Domain ID | | `domainname` | string | Domain name | | `userspace` | string | Userspace | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | Returning from a proxy session re-establishes the administrator's session. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | Returning from a proxy session re-establishes the administrator's session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **Request body:** ```json { "request": { "cmd": "unproxy" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "4379", "username": "administrator", "firstname": "System", "lastname": "Administrator", "email": "administrator@myschool.edu", "domainid": "4378", "domainname": "My Domain", "userspace": "mydomain", "token": "SYC-ihGJ|ML0jX11juQd8d8BtTPAuWC", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [Logout](https://api.agilixbuzz.com/docs/entry/Command/Logout.md) - [Proxy](https://api.agilixbuzz.com/docs/entry/Command/Proxy.md) --- # UpdateAnnouncementViewed This command updates the viewed state of one or more domain announcements for the current signed-on user. ## Request **Method:** POST **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updateannouncementviewed` | **Request body (JSON):** ```json { "requests": { "announcement": [ { "entityid": "id", "path": "string", "version": "string", "viewed": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `announcement.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Domain ID of the read announcement. | | `announcement.path` | string | Yes | Unique path to the zip-compressed announcement file. | | `announcement.version` | string | No | The version of the announcement viewed. | | `announcement.viewed` | boolean | Yes | Updated viewed state for the announcement. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example **URL:** `?updateannouncementviewed` **Request body:** ```json { "requests": { "announcement": [ { "entityid": "24", "path": "e362a72809af4dd882797522d9db6c61.zip", "viewed": true } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [DeleteAnnouncements](https://api.agilixbuzz.com/docs/entry/Command/DeleteAnnouncements.md) - [GetAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetAnnouncementList.md) - [GetUserAnnouncementList](https://api.agilixbuzz.com/docs/entry/Command/GetUserAnnouncementList.md) - [PutAnnouncement](https://api.agilixbuzz.com/docs/entry/Command/PutAnnouncement.md) --- # UpdateBlogViewed This command updates a user’s viewed state of one or more blog messages. ## Request **Method:** POST **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updateblogviewed` | **Request body (JSON):** ```json { "requests": { "message": [ { "enrollmentid": "id", "itemid": "string", "messageid": "string", "version": "string", "viewed": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `message.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | Enrollment ID of the blog owner. | | `message.itemid` | string | Yes | ID of the blog item from the course manifest. | | `message.messageid` | string | Yes | Unique ID of the message viewed. | | `message.version` | string | No | The version of the message viewed. | | `message.viewed` | boolean | Yes | Updated viewed state for the message. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | ## See Also - [PutBlog](https://api.agilixbuzz.com/docs/entry/Command/PutBlog.md) - [GetBlog](https://api.agilixbuzz.com/docs/entry/Command/GetBlog.md) --- # UpdateCommandTokens This command updates one or more existing command tokens, regenerating codes if the desired length or per-user settings change. ## Request **Method:** POST **Rights:** ReadUser@scopeentityid, ControlUser | Proxy@runasuserid (same as Proxy.) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatecommandtokens` | **Request body (JSON):** ```json { "requests": { "commandtoken": [ { "commandtokenid": "id", "scopeentityid": "id", "description": "string", "runasuserid": "id", "allowunauthenticatedredemption": "boolean", "totalusecountlimit": "int", "userusecountlimit": "int", "peruserusecountlimit": "int", "perusercodes": "boolean", "codelength": "int", "startvalidity": "datetime", "endvalidity": "datetime", "action": { "request": { "cmd": "string" } }, "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `commandtoken.commandtokenid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the command token. | | `commandtoken.scopeentityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of a domain, group, course, or user to which the command token's use will be restricted. | | `commandtoken.description` | string | No | A description of the purpose of the command token. (For future reference by you and other humans). | | `commandtoken.runasuserid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | The ID of the user the action will be run as. Defaults to the current user if not specified. The current user must have the same rights as they would to proxy as that user. | | `commandtoken.allowunauthenticatedredemption` | boolean | No | Whether or not to allow unauthenticated redemption of command tokens. Default is to not change the value in the existing command token. | | `commandtoken.totalusecountlimit` | int | No | The total number of times the token may be used (not restricted if not specified or zero). | | `commandtoken.userusecountlimit` | int | No | The total number of unique users that may use the token (not restricted if not specified or zero). | | `commandtoken.peruserusecountlimit` | int | No | The total number of times any given user may use the token (not restricted if not specified or zero). | | `commandtoken.perusercodes` | boolean | No | Whether or not each user in the specified scope is given a unique code specific to them. The default is false. Per-user codes prevent users from sharing the same code with each other, but also make it so you have to communicate different codes to each user. Per-user tokens are not stored in the database, so no code uniqueness can be enforced with this option. Due to the number of codes that would generally be required, per-user codes are not recommended with domain scoped tokens. Per-user tokens can only be redeemed by administrative users if they specify the command token id when redeeming. | | `commandtoken.codelength` | int | No | The number of characters that should be in the code. The default is 8. The maximum is 102. The more characters in the code the harder it is for someone to guess, the less characters in the code, the easier it is to communicate and enter. Each character provides 5 bits of uniqueness or 32 possible combinations, so the number of possible codes for a given length is 32^length. For example, a one character code has only 32 possible combinations, but a five character code has about 33.5 million possible combinations, and an eight character code has about 1.1 trillion possible combinations. If the first attempt at generating a code of the specified length results in a non-unique code, longer codes will be used until a unique one is found. | | `commandtoken.startvalidity` | datetime | No | The date/time (in UTC) when the code will start being valid. Any attempt to use the code before this date/time will result in access being denied. The default value is the beginning of time. | | `commandtoken.endvalidity` | datetime | No | The date/time (in UTC) when the code will stop being valid. Any attempt to use the code after this date/time will result in access being denied. The default value is the end of time. | | `commandtoken.action.request.cmd` | string | Yes | The API command to run when the token is redeemed. | | `commandtoken.data` | object | No | Optional free-form structured data. (See Free-form Data for more details.) | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string", "commandtoken": { "commandtokenid": "id", "code": "id", "user": { "userid": "id", "code": "id" } } } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ##### commandtoken | Attribute | Type | Description | |-----------|------|-------------| | `commandtokenid` | id | The ID of the command token which can be used to identify and possibly modify this command token in the future. | | `code` | id | *(optional)* The code (if perusercodes was false--otherwise there should be a list of users with user-specific codes). | ###### user *(optional)* | Attribute | Type | Description | |-----------|------|-------------| | `userid` | id | The ID of a user in the specified domain, group, or course (or specified directly). | | `code` | id | The code specific to this user. | ## Example This example updates the previously created command token with ID 587 to only be available until 2016-01-01 and changes it to a per-user 5 character code. Token 587 is assumed to NOT be a domain-scoped token. **URL:** `?cmd=updatecommandtokens` **Request body:** ```json { "requests": { "commandtoken": [ { "commandtokenid": "587", "codelength": "5", "endvalidity": "2015-01-01" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK", "commandtoken": { "commandtokenid": "587", "user": [ { "userid": "99237", "code": "w62mh" }, { "userid": "99238", "code": "-y0e8" }, { "userid": "99239", "code": "m9.g6" }, { "userid": "99240", "code": "p3djm" } ] } } ] } } } ``` ## See Also - [CreateCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/CreateCommandTokens.md) - [GetCommandToken](https://api.agilixbuzz.com/docs/entry/Command/GetCommandToken.md) - [GetCommandTokenInfo](https://api.agilixbuzz.com/docs/entry/Command/GetCommandTokenInfo.md) - [ListCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/ListCommandTokens.md) - [DeleteCommandTokens](https://api.agilixbuzz.com/docs/entry/Command/DeleteCommandTokens.md) - [RedeemCommandToken](https://api.agilixbuzz.com/docs/entry/Command/RedeemCommandToken.md) --- # UpdateCourses This command updates the title, reference, data (free-form XML), and other attributes of one or more courses. ## Request **Method:** POST **Rights:** UpdateCourse@courseid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatecourses` | **Request body (JSON):** ```json { "requests": { "course": [ { "courseid": "id", "domainid": "id", "title": "string", "reference": "string", "type": "Continuous|Range", "baseid": "id", "startdate": "datetime", "enddate": "datetime", "days": "int", "term": "string", "indexrule": "IndexRule", "schema": "int", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `course.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course to update. | | `course.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the domain to move the course to. If supplied, caller must have DeleteCourse@courseid and CreateCourse@domainid. | | `course.title` | string | Yes | Title of the course. | | `course.reference` | string | Yes | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `course.type` | `Continuous\|Range` | No | The course type. Range types have startdate and enddate but no days, while Continuous have days but no startdate nor enddate. If omitted, the course's type remains unchanged. | | `course.baseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the base course. If supplied, caller must have ReadCourseFull@baseid. | | `course.startdate` | datetime | No | The startdate for the course. Meaningful only when type is Range. If omitted, the course's startdate remains unchanged. | | `course.enddate` | datetime | No | The end date for the course. Meaningful only when type is Range. If omitted, the course's enddate remains unchanged. | | `course.days` | int | No | The number of days a student has to complete the course. Meaningful only when type is Continuous. If omitted, the course's days remains unchanged. | | `course.term` | string | No | The academic term of the course. If omitted, the course's term remains unchanged. | | `course.indexrule` | [IndexRule](https://api.agilixbuzz.com/docs/entry/Enum/IndexRule.md) | No | An IndexRule value that controls whether this course's content is searchable with the Search2 command. If omitted, the course's *indexrule* remains unchanged. | | `course.schema` | int | No | Indicates the new schema for the course. You can only upgrade a schema to a higher value. You cannot change the schema for courses with schema 1. Upgrading to schema 4 enables group inheritance for the course (see CreateGroups). | | `course.data` | object | No | Free-form structured data for the course. See Free-form Data and Course Data for more details. If omitted, the course's data remains unchanged. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseAncestorChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseAncestorChanged.md) | Background | Only when the updated course has derivative courses: one event is sent for each derivative course, reporting both the ancestor course that changed and the derivative course affected. | | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | Once for each course the request actually modifies. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example updates the title and reference value of the course with ID 6050. **URL:** `?cmd=updatecourses` **Request body:** ```json { "requests": { "course": [ { "courseid": "6050", "title": "Introduction to Computer Science", "reference": "CS101" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CopyCourses](https://api.agilixbuzz.com/docs/entry/Command/CopyCourses.md) - [CreateCourses](https://api.agilixbuzz.com/docs/entry/Command/CreateCourses.md) - [DeleteCourses](https://api.agilixbuzz.com/docs/entry/Command/DeleteCourses.md) - [GetCourse](https://api.agilixbuzz.com/docs/entry/Command/GetCourse.md) - [ListCourses](https://api.agilixbuzz.com/docs/entry/Command/ListCourses.md) - [RestoreCourse](https://api.agilixbuzz.com/docs/entry/Command/RestoreCourse.md) --- # UpdateDomains This command updates the name, reference value, flags, and free-forn structured data of one or more domains. If you omit an optional attribute (like name or reference) that attribute remains unchanged. ## Request **Method:** POST **Rights:** UpdateDomain@domainid, CreateDomain@parentid (if specified) **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatedomains` | **Request body (JSON):** ```json { "requests": { "domain": [ { "domainid": "id", "name": "string", "parentid": "id", "reference": "string", "flags": "EntityFlags", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `domain.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the domain to update. | | `domain.name` | string | No | Updated domain name. | | `domain.parentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the updated parent domain. | | `domain.reference` | string | No | Updated domain reference value. | | `domain.flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | No | Bitwise OR of EntityFlags to set on the domain. | | `domain.data` | object | No | Optional free-form structured data. See Domain Data and Free Form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainEntityChanged.md) | During the request | Once for each domain the request actually modifies. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes that the domains with IDs 4879 and 4880 already exist. **URL:** `?cmd=updatedomains` **Request body:** ```json { "requests": { "domain": [ { "domainid": "4879", "name": "Virtual School", "reference": "123412341234" }, { "domainid": "4880", "name": "Canyon Elementary", "reference": "432143214321", "flags": "2" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [CreateDomains](https://api.agilixbuzz.com/docs/entry/Command/CreateDomains.md) - [GetDomain](https://api.agilixbuzz.com/docs/entry/Command/GetDomain.md) - [ListDomains](https://api.agilixbuzz.com/docs/entry/Command/ListDomains.md) - [GetDomainParentList](https://api.agilixbuzz.com/docs/entry/Command/GetDomainParentList.md) --- # UpdateEnrollments This command updates the enrollment status, start date, end date, and rights granted to the specified user for a course. You can also change an enrollment from one course to another course.) **Warning:** When moving a course enrollment to a different course, the mapping of student work and grades to the new course’s manifest may yield unpredictable or unwanted results when the manifests (especially the item IDs) for the old and new courses are dissimilar. Also, student submissions to forums, blogs, and wikis remain in the original course and do not move with the student to the new course. ## Request **Method:** POST **Rights:** ControlCourse@entityid when entityid refers to a course; ReadUser@userid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updateenrollments` | **Request body (JSON):** ```json { "requests": { "enrollment": [ { "enrollmentid": "id", "userid": "id", "entityid": "id", "domainid": "id", "roleid": "id", "flags": "RightsFlags", "status": "EnrollmentStatus", "startdate": "datetime", "enddate": "datetime", "reference": "string", "schema": "(1|2)", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `enrollment.enrollmentid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the enrollment to update. | | `enrollment.userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the user to enroll in the course. | | `enrollment.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the course to enroll the user in. | | `enrollment.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the domain that the enrollment belongs to. | | `enrollment.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the role used to specify the privileges. The role's privileges override those specified by the flags attribute. | | `enrollment.flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | Optional bitwise-OR of RightsFlags for the user in the specified entity. | | `enrollment.status` | [EnrollmentStatus](https://api.agilixbuzz.com/docs/entry/Enum/EnrollmentStatus.md) | No | Optional EnrollmentStatus for the user. | | `enrollment.startdate` | datetime | No | Optional date that the enrollment begins. | | `enrollment.enddate` | datetime | No | Optional date that the enrollment ends. | | `enrollment.reference` | string | No | Optional updated reference value, which is a field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `enrollment.schema` | `(1\|2)` | No | An optional parameter that specifies how to interpret flags. If schema is 2 then SubmitFinalGrade privilege is treated as a distinct privilege and you must explicitly specify it in flags. If schema is 1, then specifying GradeExam, GradeAssignment, or GradeForum for flags automatically include the SubmitFinalGrade right. The default schema is 1. | | `enrollment.data` | object | No | Optional free-form structured data. See Free Form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [EnrollmentEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityChanged.md) | During the request | Once for each enrollment the request actually modifies. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the enrollment with ID 6068 on the entity with ID 6065 already exists. **URL:** `?cmd=updateenrollments` **Request body:** ```json { "requests": { "enrollment": [ { "enrollmentid": "6068", "entityid": "6065", "flags": "2097153", "status": 1, "startdate": "2008-04-21T18:30:00Z", "enddate": "2008-05-21T18:30:00Z" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [DeleteEnrollments](https://api.agilixbuzz.com/docs/entry/Command/DeleteEnrollments.md) - [GetEnrollment2](https://api.agilixbuzz.com/docs/entry/Command/GetEnrollment2.md) - [ListEntityEnrollments](https://api.agilixbuzz.com/docs/entry/Command/ListEntityEnrollments.md) - [GetUserEnrollmentList2](https://api.agilixbuzz.com/docs/entry/Command/GetUserEnrollmentList2.md) --- # UpdateGroups This command updates the title, set ID, reference, and data of one or more groups. It updates only the attributes specified in the call. Any omitted attributes retain their existing values. ## Request **Method:** POST **Rights:** ControlCourse|UpdateCourse|SetupGradebook@ownerid where ownerid is the group's owning entity **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updategroups` | **Request body (JSON):** ```json { "requests": { "group": [ { "groupid": "id", "courseid": "id", "title": "string", "reference": "string", "setid": "int", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `group.groupid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the group to update. | | `group.courseid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Schema 4+: ID of the owning course. When present, groupid is interpreted as a string group identifier within the course data rather than a group entity ID. | | `group.title` | string | No | Updated title for the group. | | `group.reference` | string | No | Updated reference value for the group. We recommend reference values be a unique reference, such as from an external SIS system. | | `group.setid` | int | No | Updated group-set ID to which this group belongs. | | `group.data` | object | No | Optional free-form structured data. (See Free-form Data for more details.) | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | When changing a group changes the course record. On Schema 4+ courses the group definitions are part of the course record, so this is sent for every change that alters them. | | [GroupEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/GroupEntityChanged.md) | During the request | Once for each group the request actually modifies on a course below Schema 4. Schema 4+ courses have no group entities, so the change is reported by CourseEntityChanged instead. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Schema 3 example: updates the titles of two groups by entity ID. **URL:** `?cmd=updategroups` **Request body:** ```json { "requests": { "group": [ { "groupid": "204235", "title": "Males" }, { "groupid": "204236", "title": "Females" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [CreateGroups](https://api.agilixbuzz.com/docs/entry/Command/CreateGroups.md) - [DeleteGroups](https://api.agilixbuzz.com/docs/entry/Command/DeleteGroups.md) - [GetGroup](https://api.agilixbuzz.com/docs/entry/Command/GetGroup.md) --- # UpdateManifestData This command updates the manifest data (see Course Data) on the specified entity (course or section.) Only the elements specified in the POST data are updated; existing manifest elements not contained in the POST data remain unchanged. ## Request **Method:** POST **Rights:** UpdateCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatemanifestdata` | **Request body (JSON):** ```json { "requests": { "manifest": [ { "entityid": "id", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `manifest.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the course or section to update. | | `manifest.data` | Course Data | Yes | This node contains elements in the Course Data format. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [CourseEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/CourseEntityChanged.md) | During the request | Manifest-level data is stored on the course record. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example updates the periods in the course with ID 136875. **URL:** `?cmd=updatemanifestdata` **Request body:** ```json { "requests": { "manifest": [ { "entityid": "136875", "data": { "periods": { "enabled": true, "period": [ { "id": "1", "name": "Q1", "weight": 0.25 }, { "id": "2", "name": "Q2", "weight": 0.25 }, { "id": "3", "name": "Q3", "weight": 0.25 }, { "id": "4", "name": "Q4", "weight": 0.25 } ] } } } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [Course Data](https://api.agilixbuzz.com/docs/entry/Schema/CourseData.md) - [GetManifestData](https://api.agilixbuzz.com/docs/entry/Command/GetManifestData.md) --- # UpdateMessageViewed This command updates a user’s viewed state of one or more discussion board messages. ## Request **Method:** POST **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatemessageviewed` | **Request body (JSON):** ```json { "requests": { "message": [ { "entityid": "id", "itemid": "string", "messageid": "string", "groupid": "string", "version": "string", "viewed": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `message.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the entity (course or section) that contains the message. | | `message.itemid` | string | Yes | ID of the threaded discussion item from the Course Manifest. | | `message.messageid` | string | Yes | ID of the message. | | `message.groupid` | string | No | Optional group ID to which the message belongs. | | `message.version` | string | No | The version of the message viewed. | | `message.viewed` | boolean | Yes | Updated viewed state for the message. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## See Also - [DeleteMessages](https://api.agilixbuzz.com/docs/entry/Command/DeleteMessages.md) - [PutMessage](https://api.agilixbuzz.com/docs/entry/Command/PutMessage.md) --- # UpdateObjectiveSets This command updates the name, reference, and other attributes of one or more objective sets or objective map sets. ## Request **Method:** POST **Rights:** UpdateObjective@setid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updateobjectivesets` | **Request body (JSON):** ```json { "requests": { "set": [ { "setid": "id", "name": "string", "domainid": "id", "reference": "string", "owner": "string", "flags": "ObjectiveSetFlags", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `set.setid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the set to update. | | `set.name` | string | No | The name of the set. | | `set.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the domain that owns the set. (See Extended IDs for more details.) | | `set.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `set.owner` | string | No | Specifies the set's owner or group name. For example, specify a common owner value for multiple, related sets. | | `set.flags` | [ObjectiveSetFlags](https://api.agilixbuzz.com/docs/entry/Enum/ObjectiveSetFlags.md) | No | A bitwise OR of ObjectiveSetFlags that control set behavior, including whether it is an objective set or objective map set and whether the set is inherited by descendent domains of domainid. You cannot change the Map flag once it is set; i.e., you cannot change an objective set to an objective map set or vice versa. | | `set.data` | object | No | Free-form structured data for the set. See Free-form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example updates the name of the objective set whose ID is 6050. **URL:** `?cmd=updateobjectivesets` **Request body:** ```json { "requests": { "set": [ { "setid": "6050", "name": "Alaska Core Curriculum" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [Learning Objectives](https://api.agilixbuzz.com/docs/entry/Concept/LearningObjectives.md) - [CreateObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/CreateObjectiveSets.md) - [DeleteObjectiveSets](https://api.agilixbuzz.com/docs/entry/Command/DeleteObjectiveSets.md) - [GetObjectiveSet2](https://api.agilixbuzz.com/docs/entry/Command/GetObjectiveSet2.md) --- # UpdatePassword This command updates the password of the specified user. An error code of PasswordPolicyRequirementsNotMet may be returned if the specified password does not meet the domain's configured requirements. In order to thwart user account name harvesting, if the specified user ID cannot be found, either an invalid credentials error or an access denied error will be returned, exactly the same as if the specified old password was incorrect or the authenticated user doesn't have rights to change the target user's password. Note that in order to prevent privilege escalation, users who have UpdateUser rights will be denied access to update another user in their domain when that user has any domain privilege in any domain they do not. Further, if the target user has a cross-domain enrollment with rights other than ReadCourse/Section and Participate in any other domain, the user requesting the update must also have UpdateUser rights in the domain of that enrollment. If the new password does \*not\* match the old password, all of the target user's sessions will be terminated. If the current session is also terminated, a new token will be returned in the response. If the Buzz application settings disallow student updating their own passwords, this will be enforced here. If the caller is not authenticated, but an old password is specified, the caller will be assumed to be the user themselves. The new password is checked against the password policy that is in effect *for the target user*, which is the domain's policy combined with the stricter of any requirements configured for the personas that user currently holds and, for users with root domain privileges, the root domain's minimum requirements. This is the same policy that Login3 enforces, so a password that would be rejected at login cannot be set here. For this API, a warning may also be returned to the caller as a "warning" property on the response object. The value of this property will indicate what the problem is. PasswordPolicyRequirementsNotMet indicates that the password update succeeded, but the password policy is configured to warn users when the new password they selected does not meet the active policy requirements, but that will be allowed anyway. An appropriate warning should be issued indicating that it is recommended that the user change their password, but the user should be allowed to proceed after the warning. When the caller is *not already authenticated*, this command authenticates them - the oldpassword, or the single-use token from a ResetPassword email, is the credential - and the token it returns is a new session. That makes it a login, so it enforces multi-factor authentication exactly as Login3 does, and reports the result as a warning on the (successful) response: SecondFactorRequired indicates that the password was changed, but the user has multi-factor authentication configured and has not yet satisfied it. The token returned in the response is *not* a session token; it is a short-lived token good only for calling SecondFactorAuthenticate, which returns the real session token on success. SecondFactorConfigurationNowRequired indicates that the password was changed, but the password policy requires multi-factor authentication and the user has not configured it. The token returned is good only for CreateSecondFactorAuthenticationSecret and SetupSecondFactorAuthentication. In both cases every existing session for the user has been terminated, and the caller must complete the second factor before it holds a usable session. A valid remembermfa token satisfies the second factor here just as it does for Login3. A response carries only one warning, so when a second factor is owed *and* the new password trips a warn-level policy rule, the second-factor warning is the one returned - it is the one the caller has to act on. The password-policy warning is not reported in that case; a caller that needs it can obtain it from CheckPasswordQuality before submitting the new password. A caller who *is* already signed in as that same user is never asked for a second factor *code* by this command: they presented it when they logged in, and the session they get back continues that authentication. Being signed in as somebody *else* does not count - the token form issues a session for whoever the token names, not for the caller - and neither does a token that is only part-way through logging in, such as the short-lived one Login3 returns alongside SecondFactorRequired. So these warnings appear whenever this command is the thing that authenticates the caller. They never appear when an administrator changes another user's password, or on a proxied change, because no token is issued to the caller in either case. Being signed in does *not* excuse a caller from a policy that requires a second factor they have never configured. Presenting a code at sign-in is what the exemption above covers; a user who has no second factor at all presented nothing, and mfaenforcement's "on change" levels exist to catch exactly that user here. Such a caller gets an okay response carrying a SecondFactorConfigurationNowRequired warning and a short-lived token good only for configuring the second factor - the password change itself still succeeds. See Password Policy. In order to help the user understand why a password is (or will be) rejected, when either a password policy violation error or warning occurs, a reason attribute will be included in the response that indicates which part of the password policy the password did not meet. That reason string should exactly match the attribute name in the password policy that was violated. If there are multiple violations, only the first one detected will be returned. ## Request **Method:** POST **Rights:** UpdateUser@userid, or self with unscoped token **Request body (JSON):** ```json { "request": { "cmd": "updatepassword", "userid": "id", "token": "string", "password": "string", "oldpassword": "string", "remembermfa": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `updatepassword` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the user to update. This is not used if token is used. | | `token` | string | No | A secure token that identifies the user to update. The server generates this token and includes it in the email message it sends in response to ResetPassword calls. | | `password` | string | Yes | New password for the user. If no password is specified, the account will be marked such that password login is not allowed. SSO and proxy logins will still be allowed, but any attempt to login using a password will fail. Maximum possible length is 64KB. | | `oldpassword` | string | No | Optional old password. If omitted, the password is reset if the caller has UpdateUser privileges. (Administrators omit oldpassword when resetting someone else’s password.) When present, if the oldpassword is correct, then the new password is saved. | | `remembermfa` | string | No | An optional remember MFA token that identifies the device as one which has been previously authorized. When it is valid, the user is not asked for a second factor again after the password change. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "user": { "token": "string", "authenticationexpirationminutes": "int" } } } ``` ### user *(optional)* This node conforms to the User format. | Attribute | Type | Description | |-----------|------|-------------| | `token` | string | A new authentication token since the token used to make the call has been terminated. | | `authenticationexpirationminutes` | int | The number of minutes before this new token will expire. | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAccountLocked](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAccountLocked.md) | During the request | The failed password verification crossed the lockout threshold. | | [AuthAdminPasswordChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminPasswordChanged.md) | During the request | The target account holds an active Administrator role. Sent whether the change succeeds or fails. | | [AuthLoginFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthLoginFailed.md) | During the request | The current password supplied for verification did not match. | | [UserEntityActivity](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityActivity.md) | During the request | When the password change issues a replacement session. | | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | The password is stored on the user record. | | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | A password change ends the user's other sessions. | | [UserSessionStarted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionStarted.md) | During the request | When the password change issues a replacement session. | Activity updates are throttled: if the stored last activity date is already within the last hour, nothing is written and no activity event is sent. Activity also cascades upward, so one action can produce an enrollment, course, and domain activity event together. *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Changes the password for user 6158. **Request body:** ```json { "request": { "cmd": "updatepassword", "userid": "6158", "password": "newpassword" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "user": { "userid": "6158", "firstname": "Tiger", "lastname": "Jones", "username": "teacher", "email": "tiger.jones@myschool.edu", "domainid": "24", "domainname": "Test", "userspace": "myschool", "token": "iuds980fds789078asv78cz0890889wr7890a7fdsa75390q2789", "authenticationexpirationminutes": "15" } } } ``` ## See Also - [Login3](https://api.agilixbuzz.com/docs/entry/Command/Login3.md) - [SecondFactorAuthenticate](https://api.agilixbuzz.com/docs/entry/Command/SecondFactorAuthenticate.md) - [ResetLockout](https://api.agilixbuzz.com/docs/entry/Command/ResetLockout.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) --- # UpdatePasswordQuestionAnswer This command updates the password question and answer for the specified user. Note that in order to prevent privilege escalation, users who have UpdateUser rights will be denied access to update another user in their domain when that user has any domain privilege in any domain they do not. Further, if the target user has a cross-domain enrollment with rights other than ReadCourse/Section and Participate in any other domain, the user requesting the update must also have UpdateUser rights in the domain of that enrollment. ## Request **Method:** POST **Rights:** UpdateUser@userid, or self with unscoped token **Request body (JSON):** ```json { "request": { "cmd": "updatepasswordquestionanswer", "userid": "id", "passwordquestion": "string", "passwordanswer": "string", "oldpassword": "string" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `cmd` | `updatepasswordquestionanswer` | Yes | | | `userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user to update. | | `passwordquestion` | string | Yes | Security question that end-user can respond to to reset their password. | | `passwordanswer` | string | Yes | Answer to passwordquestion. | | `oldpassword` | string | No | Optional old password. If omitted, the password question and answer is reset; assuming the caller has sufficient privileges. (Administrators omit oldpassword when resetting someone else’s question and answer.) When present, if the oldpassword is correct, then the question and answer is reset. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAccountLocked](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAccountLocked.md) | During the request | The failed password verification crossed the lockout threshold. | | [AuthLoginFailed](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthLoginFailed.md) | During the request | The current password supplied for verification did not match. | | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | The password question and answer are stored on the user record. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example assumes the user with ID 6158 already exists. **Request body:** ```json { "request": { "cmd": "updatepasswordquestionanswer", "userid": "6158", "passwordquestion": "What is your favorite color?", "passwordanswer": "Lavender" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) --- # UpdateRights This command updates the rights (flags) granted to the specified user (actorid) for the domain or enrollment specified by entityid. To grant a user rights to a course or section, use CreateEnrollments or UpdateEnrollments. Those commands modify the rights associated with an enrollment. In this command, granting rights for an enrollment grants rights for the user to view another user's enrollment. ## Request **Method:** POST **Rights:** ReadUser@actorid; ControlDomain@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updaterights` | **Request body (JSON):** ```json { "requests": { "rights": [ { "actorid": "id", "entityid": "id", "roleid": "id", "flags": "RightsFlags", "schema": "(1|2)" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `rights.actorid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user to whom rights are granted. | | `rights.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the domain or enrollment to which rights are granted. | | `rights.roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | Optional ID of the role used to specify the privileges. The role's privileges override those specified by the flags attribute. | | `rights.flags` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | A bitwise-OR of RightsFlags to grant for the user. The value -1 indicates all rights, including any that may be defined in the future. | | `rights.schema` | `(1\|2)` | No | An optional parameter that specifies how to interpret flags. If schema is 2 then SubmitFinalGrade privilege is treated as a distinct privilege and you must explicitly specify it in flags. If schema is 1, then specifying GradeExam, GradeAssignment, or GradeForum for flags automatically include the SubmitFinalGrade right. The default schema is 1. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainPermissionsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsChanged.md) | During the request | When the request changes permissions the user already had. | | [DomainPermissionsCreated](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsCreated.md) | During the request | When the request grants domain permissions a user did not have. | | [DomainPermissionsDeleted](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsDeleted.md) | During the request | When the request removes all of a user's permissions on the domain. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example updates a user’s rights in domain ID 4879 to the value 96: ReadDomain(32) and UpdateDomain(64). **URL:** `?cmd=updaterights` **Request body:** ```json { "requests": { "rights": [ { "actorid": "1257", "entityid": "4879", "flags": "96" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) - [CreateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/CreateEnrollments.md) - [GetRights](https://api.agilixbuzz.com/docs/entry/Command/GetRights.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdateEnrollments](https://api.agilixbuzz.com/docs/entry/Command/UpdateEnrollments.md) --- # UpdateRole This command updates the name, domainid, reference, or privileges for a role. If you omit an optional attribute (like domainid or name) that attribute remains unchanged. Note that the propagation of the change happens asynchronously and so there may be some delay for the change is realized. ## Request **Method:** POST **Rights:** UpdateDomain@domainid **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updaterole` | **Request body (JSON):** ```json { "request": { "roleid": "id", "name": "string", "domainid": "id", "reference": "string", "privileges": "RightsFlags", "entitytype": "D|C|empty" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `roleid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the role. | | `name` | string | No | The name of the role. | | `domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the domain to move the role to. If supplied, caller must have UpdateDomain@domainid for the domain to move the role to. | | `reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external system. The maximum length is 128 characters. | | `privileges` | [RightsFlags](https://api.agilixbuzz.com/docs/entry/Enum/RightsFlags.md) | No | Bitwise OR of RightsFlags to grant to the user. | | `entitytype` | `D\|C\|empty` | No | The entity type that the role can provide access rights for. Valid values include "D" for domain, "C" for course, or an empty string if the role can be applied to any entity type. See Rights for a description of what privileges apply to what entities. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [DomainPermissionsChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/DomainPermissionsChanged.md) | Background | A role used by these permissions was changed. Privileges are stored on the permission record rather than looked up through the role, so they are rewritten by role privilege propagation after the request returns. | | [EnrollmentEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EnrollmentEntityChanged.md) | Background | A role this enrollment uses was changed. Privileges are stored on the enrollment rather than looked up through the role, so they are rewritten by role privilege propagation after the request returns. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example Changes the name and reference of the role whose ID is 312098. **URL:** `?cmd=updaterole` **Request body:** ```json { "role": { "roleid": "312098", "name": "BetterRole", "reference": "12345678" } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [CreateRole](https://api.agilixbuzz.com/docs/entry/Command/CreateRole.md) - [DeleteRole](https://api.agilixbuzz.com/docs/entry/Command/DeleteRole.md) - [GetRole](https://api.agilixbuzz.com/docs/entry/Command/GetRole.md) - [ListRoles](https://api.agilixbuzz.com/docs/entry/Command/ListRoles.md) --- # UpdateSubscriptions This command creates or updates the subscription for the specified subscriber. A subscription is uniquely identified by its subscriberid, entityid, and flags. The subscriber is able to search for and read or view any course content covered by the subscription. ## Request **Method:** POST **Rights:** When subscriberid is a domain, ReadDomain@subscriberid or ManageLicense@subscriberid; when subscriberid is a user, ReadUser@domainid of the user's domain. When entityid is a course, ControlCourse@entityid; when entityid is a domain, ControlDomain@entityid. **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatesubscriptions` | **Request body (JSON):** ```json { "requests": { "subscription": [ { "subscriberid": "id", "entityid": "id", "startdate": "datetime", "enddate": "datetime", "subscriptionflags": "SubscriptionFlags" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `subscription.subscriberid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user or domain to update a subscription for. Specify 0 to subscribe all users in all domains (you must have ReadDomain@root-most domain to specify 0.). If subscriberid is a domain ID, only users in the subscriberid domain participate in the subscription; users in descendant domains do not participate. | | `subscription.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the domain or course to subscribe to. If entityid is a domain ID, the subscription applies to all courses in entityid domain and to all courses in all descendant domains of entityid. | | `subscription.startdate` | datetime | Yes | Date and time when the subscription begins. | | `subscription.enddate` | datetime | Yes | Date and time when the subscription ends. | | `subscription.subscriptionflags` | [SubscriptionFlags](https://api.agilixbuzz.com/docs/entry/Enum/SubscriptionFlags.md) | No | A bitwise-OR of SubscriptionFlags that affect the behavior of the updated subscription. The default is None. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Example This example creates a subscription for the user with ID 4879 and for users in the domain ID 5010 who have the CreateCourse (65536) right. The subscribed-to course has ID 87923. **URL:** `?cmd=updatesubscriptions` **Request body:** ```json { "requests": { "subscription": [ { "subscriberid": "4879", "entityid": "87923", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z" }, { "subscriberid": "5010", "entityid": "87923", "startdate": "2011-01-01T00:00:00Z", "enddate": "2012-01-01T00:00:00Z" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" }, { "code": "OK" } ] } } } ``` ## See Also - [DeleteSubscriptions](https://api.agilixbuzz.com/docs/entry/Command/DeleteSubscriptions.md) - [GetEffectiveSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEffectiveSubscriptionList.md) - [GetEntitySubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetEntitySubscriptionList.md) - [GetSubscriptionList](https://api.agilixbuzz.com/docs/entry/Command/GetSubscriptionList.md) --- # UpdateUsers This command updates the first name, last name, reference field, e-mail address, and flags for one or more users. If you omit an optional attribute (like domainid or firstname) that attribute remains unchanged. If the Buzz application settings prevent students from updating their own email address or profile picture, those restrictions will be enforced here. ## Request **Method:** POST **Rights:** UpdateUser@userid, or the currently signed-on user can update their own account with an unscoped token: data is always allowed; first name, last name, and username only where the domain permits self username changes; email only where the domain permits self email changes; reference and flags always require UpdateUser. **Content-Type:** application/json **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updateusers` | **Request body (JSON):** ```json { "requests": { "user": [ { "userid": "id", "domainid": "id", "username": "string", "firstname": "string", "lastname": "string", "email": "string", "reference": "string", "flags": "EntityFlags", "data": {} } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `user.userid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | The ID of the user. | | `user.domainid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | No | ID of the domain to move the user to. If supplied, caller must have DeleteUser@userid and CreateUser@domainid. | | `user.username` | string | No | The username of the user account. End-users enter this name to login. | | `user.firstname` | string | No | User’s first name. | | `user.lastname` | string | No | User’s last name. | | `user.email` | string | No | User’s e-mail address. | | `user.reference` | string | No | Field reserved for any data the caller wishes to store. We recommend it be a unique reference, such as from an external SIS system. | | `user.flags` | [EntityFlags](https://api.agilixbuzz.com/docs/entry/Enum/EntityFlags.md) | No | Bitwise OR of EntityFlags to set on the user. | | `user.data` | object | No | Optional free-form structured data. See User Data and Free Form Data for more details. | > **Free-form data:** values inside a free-form object (such as `data`) are XML elements — encode each as `{"$value": ...}`; a bare scalar like `"field": "value"` becomes an XML attribute and is silently dropped. See [Free-form Data](https://api.agilixbuzz.com/docs/entry/Concept/FreeFormXml.md). ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code", "message": "string" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | | `message` | string | *(optional)* | ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [AuthAdminContactInfoChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/AuthAdminContactInfoChanged.md) | During the request | The request changed the email address of an account holding an active Administrator role. | | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | Once for each user the request actually modifies, including changes that only remove notification subscriptions. | | [UserSessionEnded](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserSessionEnded.md) | During the request | Only when the request deactivates the user, which ends all of their sessions immediately. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example **URL:** `?cmd=updateusers` **Request body:** ```json { "requests": { "user": [ { "userid": "589", "firstname": "Sally", "lastname": "Johnson", "email": "sally.johnson@myschool.edu", "reference": "12345678" } ] } } ``` **Response** (code: `OK`): ```json { "response": { "code": "OK", "responses": { "response": [ { "code": "OK" } ] } } } ``` ## See Also - [CreateUsers](https://api.agilixbuzz.com/docs/entry/Command/CreateUsers.md) - [DeleteUsers](https://api.agilixbuzz.com/docs/entry/Command/DeleteUsers.md) - [GetUser](https://api.agilixbuzz.com/docs/entry/Command/GetUser.md) - [GetUserList](https://api.agilixbuzz.com/docs/entry/Command/GetUserList.md) - [GetEntityRights](https://api.agilixbuzz.com/docs/entry/Command/GetEntityRights.md) - [UpdatePassword](https://api.agilixbuzz.com/docs/entry/Command/UpdatePassword.md) - [UpdatePasswordQuestionAnswer](https://api.agilixbuzz.com/docs/entry/Command/UpdatePasswordQuestionAnswer.md) --- # UpdateWikiPageViewed This command updates a user’s viewed state of one or more wiki pages. ## Request **Method:** POST **Rights:** ReadCourse@entityid **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `updatewikipageviewed` | **Request body (JSON):** ```json { "requests": { "wikipage": [ { "entityid": "id", "itemid": "string", "groupid": "string", "slug": "string", "version": "string", "viewed": "boolean" } ] } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `wikipage.entityid` | [id](https://api.agilixbuzz.com/docs/entry/Concept/EntityIds.md) | Yes | ID of the user's enrollment or the entity that contains the wiki page. | | `wikipage.itemid` | string | Yes | ID of the threaded discussion item from the Course Manifest. | | `wikipage.groupid` | string | No | Optional group ID to which the wiki page belongs. | | `wikipage.slug` | string | Yes | Slug, or ID, of the wiki page. | | `wikipage.version` | string | No | The version of the wiki page viewed. | | `wikipage.viewed` | boolean | Yes | Updated viewed state for the wiki page. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string", "responses": { "response": [ { "code": "code" } ] } } } ``` ### responses #### response | Attribute | Type | Description | |-----------|------|-------------| | `code` | code | | ## See Also - [PutWikiPage](https://api.agilixbuzz.com/docs/entry/Command/PutWikiPage.md) - [GetWikiPage](https://api.agilixbuzz.com/docs/entry/Command/GetWikiPage.md) --- # VerifyUserEmail This command verifies a messaging account associated with a user. Administrators should only verify an account that is owned by the institution (e.g., school email address) and has confirmed that the account is associated with the correct user. All other accounts must be verified by the user. ## Request **Method:** POST **Rights:** userid is the signed-on user or (ReadUser@user.domainid and UpdateUser@user.domainid) **Query-string parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | `cmd` | string | Yes | Fixed value: `verifyuseremail` | | `type` | string | Yes | The type of address to verify Possible values are: - *email* - The user's email address - *notificationsemail* - The user's notification email address | | `code` | string | No | The verification code that was sent to the user's messaging account | | `userid` | string | No | The user whose address should be verified. When *userid* has a value, *type* must be *email*. When *code* has a value, *VerifyUserEmail* ignores the value for *userid*, and uses the currently signed on user. | ## Response **Response body (JSON):** ```json { "response": { "code": "OK", "message": "string" } } ``` ## Data Stream Events A domain configured to receive a [data stream](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/Overview.md) may receive the following events as a result of this command. An event is only delivered if the domain (or one of its ancestor domains) has a data stream target whose event filter includes that event type. | Event | Sent | Conditions | |-------|------|------------| | [UserEntityChanged](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/UserEntityChanged.md) | During the request | Verification updates the email verification state on the user record. | *During the request* means the event is sent before this command returns its response. *Background* means the command records a change that [background processing](https://api.agilixbuzz.com/docs/entry/Concept/DataStream/EventSources.md) picks up afterward, so the event arrives some time after the response — typically within minutes, depending on how the deployment schedules that work. ## Example This example would attempt to verify a user's own email address because it includes a code. **URL:** `?cmd=verifyuseremail&type=email&code=123456789` **Response** (code: `OK`): ```json { "response": { "code": "OK" } } ``` ## See Also - [UserData](https://api.agilixbuzz.com/docs/entry/Schema/UserData.md) ---