> ## Documentation Index > Fetch the complete documentation index at: https://docs.timeback.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an External TestOut > Creates or updates a ComponentResource to act as a TestOut lesson in a course. This allows integrating with external test-taking platforms (like Edulastic) for content delivery. The endpoint creates or updates (if they already exist) the following entities: - A CourseComponent for the course to hold the TestOut lesson - A Resource with lessonType = "test-out" and the external service details as metadata - A ComponentResource acting as the TestOut lesson A test assignment is mandatory in order to obtain access credentials for this test on the external platform, as well as to obtain the IDs necessary for fetching test results later on: - For test assignments, use the "makeExternalTestAssignment" endpoint. - For test results retrieval, use the "importExternalTestAssignmentResults" endpoint. This request fails if: - The course provided does not exist - An existing TestOut lesson in the course has a different toolProvider than the one provided (need to perform an update to the Resource first, altering the "toolProvider", before trying again) A 'Lesson' in this context is a ComponentResource object which has a Resource object with lessonType = "test-out" associated with it. ## OpenAPI ````yaml /openapi/beyond-ai/powerpath-api.yaml post /powerpath/createExternalTestOut openapi: 3.1.0 info: title: PowerPath API version: 1.0.0 description: > TimeBack PowerPath 100 API # Authentication All endpoints require authentication using the `Authorization: Bearer ` header. The token can be obtained with: ``` curl -X POST https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=&client_secret=" ``` Use the correct IDP server depending on the environment you're using: IDP Server for this environment: ``` https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com ``` Reach out to the platform team to get a client/secret pair for your application. # Pagination Our API uses offset pagination for list endpoints. Paginated responses include the following fields: - `offset`: Offset for the next page of results - `limit`: Number of items per page (default: 100, maximum: 3000) **Note:** While the OneRoster specification does not define a maximum limit, this implementation enforces a maximum of 3000 items per page to prevent abuse and ensure optimal performance. Example request: ``` GET /ims/oneroster/rostering/v1p2/users?offset=20&limit=20 ``` All listing endpoints support offset pagination. # Filtering All listing endpoints support filtering using the `filter` query parameter, following 1EdTech's filtering specification. The filter should be a string with the following format: ``` ?filter=[field][operator][value] ``` Example request: ``` GET /ims/oneroster/rostering/v1p2/users?filter=status='active' ``` Example request with multiple filters: ``` GET /ims/oneroster/rostering/v1p2/users?filter=status='active' AND name='John' ``` **Filtering by nested relations is not supported**. # Sorting All listing endpoints support sorting using the `sort` and `orderBy` query parameters, following 1EdTech's sorting specification Example request: ``` GET /ims/oneroster/rostering/v1p2/users?sort=lastName&orderBy=asc ``` # Proprietary Extensions This implementation includes proprietary extensions that extend beyond the official OneRoster 1.2 specification to provide additional functionality. ## Search Parameter In addition to the standard `filter` parameter, this implementation provides a `search` query parameter for simplified free-text searching: ``` GET /ims/oneroster/rostering/v1p2/users?search=john ``` **Purpose**: The `search` parameter enables convenient text-based queries across multiple fields simultaneously, whereas the standard `filter` parameter requires specifying exact field names and operators: ``` # Search parameter - searches across multiple fields automatically GET /ims/oneroster/rostering/v1p2/users?search=john # Equivalent using standard filter parameter GET /ims/oneroster/rostering/v1p2/users?filter=givenName~'john' OR familyName~'john' ``` The `search` parameter performs case-insensitive partial matching across predefined fields for each endpoint, providing a more user-friendly querying experience. ## OneRoster 1.2 Standard Parameters The official OneRoster 1.2 specification defines these standard parameters: - `limit` - pagination limit - `offset` - pagination offset - `sort` - field to sort by - `orderBy` - sort direction (asc/desc) - `filter` - filtering expression - `fields` - field selection ## Affected Endpoints The proprietary `search` parameter is available on the following endpoints: **Rostering API**: - `GET /ims/oneroster/rostering/v1p2/academicSessions/` - `GET /ims/oneroster/rostering/v1p2/classes/` - `GET /ims/oneroster/rostering/v1p2/classes/{classSourcedId}/students` - `GET /ims/oneroster/rostering/v1p2/classes/{classSourcedId}/teachers` - `GET /ims/oneroster/rostering/v1p2/courses/` - `GET /ims/oneroster/rostering/v1p2/courses/{courseSourcedId}/classes` - `GET /ims/oneroster/rostering/v1p2/demographics/` - `GET /ims/oneroster/rostering/v1p2/enrollments/` - `GET /ims/oneroster/rostering/v1p2/schools/{schoolSourcedId}/classes/{classSourcedId}/students` - `GET /ims/oneroster/rostering/v1p2/users/` **Gradebook API**: - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - `GET /ims/oneroster/gradebook/v1p2/assessmentResults/` - `GET /ims/oneroster/gradebook/v1p2/classes/{classSourcedId}/students/{studentSourcedId}/results` - `GET /ims/oneroster/gradebook/v1p2/results/` **Resources API**: - `GET /ims/oneroster/resources/v1p2/resources/` ## Parameter Usage Guide ### Filter Parameter The standard `filter` parameter provides precise control over queries using these operators: - `=` - Exact match - `!=` - Not equal - `~` - Contains (case-insensitive) - `>`, `>=`, `<`, `<=` - Comparison operators - `@` - In list (comma-separated values) ### Logical Operators Combine multiple conditions in filter expressions: - `AND` - Both conditions must be true - `OR` - Either condition must be true ### Usage Examples ```bash # Simple text search across multiple fields GET /users?search=john # Equivalent precise filtering GET /users?filter=givenName~'john' OR familyName~'john' # Complex filtering with multiple conditions GET /users?filter=status='active' AND givenName~'john' # Advanced filtering with different operators GET /users?filter=dateLastModified>'2023-01-01' AND status='active' ``` ## Search Fields by Endpoint Different endpoints search across these predefined fields: - **Users**: `givenName`, `familyName`, `email` - **Courses**: `title`, `courseCode` - **Classes**: `title` - **Organizations**: `name` ## Interoperability Notes The `search` parameter is a proprietary extension specific to this implementation. Other OneRoster-compliant systems may only support the standard `filter` parameter. When building applications that need to work with multiple OneRoster providers, consider using the standard filtering approach. ## Additional Schema Fields ### AssessmentLineItem Extensions The AssessmentLineItem schema includes two proprietary fields that extend curriculum mapping capabilities: #### Component Field - **Field**: `component` - **Type**: Object reference (`{ sourcedId: string }`) - **Purpose**: Direct association between assessment line items and course components, enabling enhanced curriculum mapping and learning pathway tracking. #### ComponentResource Field - **Field**: `componentResource` - **Type**: Object reference (`{ sourcedId: string }`) - **Purpose**: Direct association between assessment line items and specific learning resources, supporting detailed content-to-assessment relationships and adaptive learning features. **Example Usage**: ```json { "sourcedId": "assessment-123", "title": "Chapter 5 Quiz", "component": { "sourcedId": "component-456" }, "componentResource": { "sourcedId": "resource-789" } } ``` ## Affected Endpoints ### Schema Extensions Availability The proprietary schema fields are available in: **Gradebook API**: - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - Returns assessmentLineItems with `component` and `componentResource` fields - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/{sourcedId}` - Returns individual assessmentLineItem with extended fields - `POST /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - Accepts `component` and `componentResource` in request body - `PUT /ims/oneroster/gradebook/v1p2/assessmentLineItems/{sourcedId}` - Accepts extended fields for updates servers: - url: https://api.alpha-1edtech.ai description: PowerPath API security: - OAuth2: [] tags: - name: Course Mastery - name: Course Sequence description: >- Manage course sequences and query course sequence to get the next stage in the student learning path - name: Lesson Mastery description: >- Track and manage student mastery of lesson objectives, through PowerPath 100 lessons - name: Lesson Plans description: Manage lesson plans and instructional content - name: Placement - name: Test Assignments - name: Test Out description: >- Self-elected test-out endpoints for students to verify mastery and advance to the next grade level paths: /powerpath/createExternalTestOut: post: tags: - Course Mastery summary: Create an External TestOut description: > Creates or updates a ComponentResource to act as a TestOut lesson in a course. This allows integrating with external test-taking platforms (like Edulastic) for content delivery. The endpoint creates or updates (if they already exist) the following entities: - A CourseComponent for the course to hold the TestOut lesson - A Resource with lessonType = "test-out" and the external service details as metadata - A ComponentResource acting as the TestOut lesson A test assignment is mandatory in order to obtain access credentials for this test on the external platform, as well as to obtain the IDs necessary for fetching test results later on: - For test assignments, use the "makeExternalTestAssignment" endpoint. - For test results retrieval, use the "importExternalTestAssignmentResults" endpoint. This request fails if: - The course provided does not exist - An existing TestOut lesson in the course has a different toolProvider than the one provided (need to perform an update to the Resource first, altering the "toolProvider", before trying again) A 'Lesson' in this context is a ComponentResource object which has a Resource object with lessonType = "test-out" associated with it. operationId: createExternalTestOut requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateExternalTestOutInput' - $ref: '#/components/schemas/CreateExternalPlacementInput' discriminator: propertyName: lessonType mapping: test-out: $ref: '#/components/schemas/CreateExternalTestOutInput' placement: $ref: '#/components/schemas/CreateExternalPlacementInput' responses: '200': description: Success content: application/json: schema: type: object properties: lessonType: type: string enum: - powerpath-100 - quiz - test-out - placement - unit-test - alpha-read-article lessonId: type: string description: >- The sourcedId of the created external test reference (ComponentResource) courseComponentId: type: string description: The sourcedId of the component (unit) containing the test resourceId: type: string description: >- The sourcedId of the resource representing the external test launchUrl: type: string description: The URL to the external test system toolProvider: type: string description: The tool provider id vendorId: type: string description: The ID of the test in the spreadsheet courseIdOnFail: type: - string - 'null' description: >- The courseId to enroll the student in if they fail the placement test (optional) grades: type: array items: allOf: - $ref: '#/components/schemas/GradeEnum' description: The grades of the course enum: - '-1' - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' description: The grades for the resource required: - lessonType - lessonId - courseComponentId - resourceId - toolProvider '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedRequestResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: Unprocessable Entity / Validation Error content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' components: schemas: CreateExternalTestOutInput: type: object properties: courseId: type: string description: The sourcedId of the Course to create the external test for lessonTitle: type: string description: The title of the external test reference launchUrl: type: string description: The URL to the external test system (e.g., Edulastic, QTI, etc.) toolProvider: type: string enum: - AlphaTest - edulastic - mastery-track description: 'The type of external service (e.g.: ''edulastic'')' unitTitle: type: string description: The title of the unit containing the external test courseComponentSourcedId: type: string description: >- The sourcedId of an existing CourseComponent (unit) for the test. If not provided, a new unit will be created. vendorId: type: string description: The ID of the test in the spreadsheet description: type: string description: >- Description of the external test that will be added to the Resource entity's metadata resourceMetadata: type: 'null' description: Additional metadata for the external test resource grades: type: array items: type: string description: The grades of the course enum: - '-1' - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' description: The grades for the resource lessonType: type: string const: test-out xp: type: number description: The XP value for the resource required: - courseId - toolProvider - grades - lessonType - xp description: Input for creating an external test-out lesson CreateExternalPlacementInput: type: object properties: courseId: type: string description: The sourcedId of the Course to create the external test for lessonTitle: type: string description: The title of the external test reference launchUrl: type: string description: The URL to the external test system (e.g., Edulastic, QTI, etc.) toolProvider: type: string enum: - AlphaTest - edulastic - mastery-track description: 'The type of external service (e.g.: ''edulastic'')' unitTitle: type: string description: The title of the unit containing the external test courseComponentSourcedId: type: string description: >- The sourcedId of an existing CourseComponent (unit) for the test. If not provided, a new unit will be created. vendorId: type: string description: The ID of the test in the spreadsheet description: type: string description: >- Description of the external test that will be added to the Resource entity's metadata resourceMetadata: type: 'null' description: Additional metadata for the external test resource grades: type: array items: type: string description: The grades of the course enum: - '-1' - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' description: The grades for the resource lessonType: type: string const: placement courseIdOnFail: type: - string - 'null' description: >- The courseId to enroll the student in if they fail the placement test (optional) xp: type: number description: The XP value for the resource required: - courseId - toolProvider - grades - lessonType description: Input for creating an external placement test GradeEnum: type: string enum: - '-1' - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' description: >- Grade levels. -1 is Pre-K, 0 is Kindergarten, 1-12 are grades 1-12, 13 is AP. example: '3' BadRequestResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: invaliddata description: The field value for the minor code example: invaliddata required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor UnauthorizedRequestResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: unauthorisedrequest description: The field value for the minor code example: unauthorisedrequest required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor ForbiddenResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: forbidden description: The field value for the minor code example: forbidden required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor NotFoundResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: unknownobject description: The field value for the minor code example: unknownobject required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor UnprocessableEntityResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: invaliddata description: The field value for the minor code example: invaliddata required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor TooManyRequestsResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: server_busy description: The field value for the minor code example: server_busy required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor InternalServerErrorResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: internal_server_error description: The field value for the minor code example: internal_server_error required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: scopes: https://purl.imsglobal.org/spec/or/v1p1/scope/admin: Admin access to the API https://purl.imsglobal.org/spec/or/v1p2/scope/admin.own: Admin access restricted to own resources https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly: Read access to roster core https://purl.imsglobal.org/spec/or/v1p1/scope/roster.readonly: Read access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster.createput: Create and update access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster.delete: Delete access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.readonly: Read access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.createput: Create and update access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.delete: Delete access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/resource.readonly: Read access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/resource.createput: Create and update access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/resource.delete: Delete access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.readonly: Read access to gradebook https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.createput: Create and update access to gradebook https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.delete: Delete access to gradebook https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.readonly: Read access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.createput: Create and update access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.delete: Delete access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.admin: Admin access to powerpath https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.readonly: Read your issued badges https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.upsert: Store new badges in your account https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.delete: Delete access to open badges https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.admin: Administrative access to open badges https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.readonly: Read access to CLR https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.upsert: Create and update access to CLR https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.admin: Administrative access to CLR https://api.alpha-1edtech.ai/edubridge/progression.readonly: Browse lesson catalog via progression proxy https://api.alpha-1edtech.ai/edubridge/progression.createput: Create hole-filling courses via progression proxy tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token ````