Woolf Airlock
Woolf Airlock
📓

Airlock 0.1

Airlock 0.1

🧑‍🚀
Build seamless experiences for students with a custom course library, easy enrollment, guided onboarding, and much more. Ensure 24/7 compliance by integrating with the Woolf Accreditation Management System (AMS) using Airlock. Explore API 0.1

Environments

Production

Woolf has the following main domain: https://woolf.university/

API request URL: https://api.woolf.university/public

A Member College has a separate workspace that is available under its alias link: <<<<https://[alias].woolf.university/>>>>

Courses and Degrees offered by a Member College will be exclusively available within its designated workspace.

Sandbox

Our sandbox provides colleges with an environment identical to production. This allows Colleges to integrate our API and SDK without the risk of corrupting or damaging production data. You can obtain access to our sandbox from our support team directly via support@woolf.university.

Sandbox ENV: https://ams.x.university/

Sandbox API: https://api.x.university/public

API Explorer in GraphiQL: https://api.x.university/public/graphiql

By default, each member college receives its own instance in our sandbox after signing the contract with Woolf. If you are not a member college but are interested in testing our product and its integration with your LMS, you can request access to our sandbox via support@woolf.university.

Course Library and Resources Tracking

A Degree is a set of Courses divided into Tiers that students need to complete in order to earn a certain amount of credits and become eligible for a Degree. Courses can be connected to specific Tiers inside of a Degree. One Course can be part of a few degrees.

Course content is formed using the Course Library. The Course Library contains a list of resources.

Students consume these resources (e.g., lectures, articles, meetings, assignments) while enrolled in a Course.

Courses need to meet certain requirements in order to be verified and accredited.

Requirements depend on the course accreditation level. Courses may accordingly require some adjustments in the Woolf AMS.

Common requirement for all courses is that the total workload of all verified resources should be equal to or higher than the Course-required workload.

Tracking

  • General Resources: Lectures, videos, podcasts, links to articles, and other materials that are relevant to the course but do not fit into any other category. The Airlock SDK tracks consumption whenever a student watches, listens, downloads, opens, or reads such resources. This consumption must always be actor-based and tracked in real-time.
  • Peer-reviewed Publications: The Airlock SDK tracks consumption when a student downloads or reads a publication. This consumption must always be actor-based and tracked in real-time.
  • Regular Assignments: The Airlock SDK must verify each assignment submission, grading, and feedback to ensure activity attribution. This is achieved by gathering information about the place, time, and author of the activity. Activity must be logged using the SDK at the time of occurrence, but submitted data can be uploaded to the AMS using the API within 24 hours after the activity. Students are allowed to retake an assignment and improve their grade according to the college's policy. The last grade sent is considered final and will be used in the calculation of running and final average scores.
  • Meetings: At least 20% of the course workload must be completed through face-to-face teaching. This can include live lectures, one-on-one or group meetings, stand-ups, and Q&A sessions. Attendance at these events must be submitted via the Airlock API and proven with meeting recording. Attendance must be recorded in the AMS at the time of occurrence, but evidence can be submitted within 12 hours after the activity. If students miss a live session, they can catch up by reviewing the meeting recording and related materials to complete their workload.
  • Summative Assignments: A final project or exam that requires students to demonstrate their mastery of learning objectives. These assignments are cumulative, meaning that they should include or build upon all the intended learning outcomes of the course. Summative assignments must be graded. Students are allowed to retake an assignment and improve their grade according to the college's policy. The last grade sent is considered final and will be used in the calculation of running and final average scores. Summative assignments are tracked in the same way as regular assignments. However, if they occur off-platform, such as when using an external proctoring tool where Airlock cannot be installed, please inform our accreditation team beforehand. We will provide personalized guidelines for tracking such cases.

Reusing the same resource

If a Member College provides group learning—not individual learning—and forms classes or cohorts, resources can be reused in several groups if the content is not changed. We recommend reusing them, as any changes in resources will need to be verified again.

If a resource is not changed, it can and should be reused multiple times.

Consumed content is compared to Course Library on Woolf platform

Airlock SDK will track if the content that the student consumes is the same as the content that was originally verified by the Woolf Accreditation team.

This requires a Member College to track any changes that are made to any resource content and to manage those changes accordingly.

College Access Token and Secret

User Token

This kind of token acts on behalf of a user. It can be signed using the organization's secret directly from your codebase or by us using authorizeOAuth mutation.

import jwt from "jsonwebtoken"

const userId = "so-me-uu-id"
const orgId = "so-me-uu-id"
const orgSecret = "secret"

const token = jwt.sign(
  {
    id: userId,
    iss: "urn:WoolfUniversity:server/service/access",
    isVerified: true,
    kind: "oauth",
    org: {
      groups: [],
      id: orgId,
    },
    scope: "*",
  },
  orgSecret
);

console.log("OAuth Token:", token)
Authorization: Bearer %token%

Using authorizeOAuth mutation

authorizeOAuth will return access and refresh token fields. The access token acts as a bearer token. You can use the refresh token to regenerate the access token.

Submit your programs

Our GraphQL API enables you to categorize your content library based on compliance requirements and submit it for accreditation review. Related webhooks will notify you in real-time if any of your resources are verified or rejected by our accreditation team.

The primary goal of this milestone is to automate content synchronization between your LMS and our AMS using the Airlock API, and to fully populate at least one Course Library.

Fetch information

Fetch information about identifiers, grade weights of your college courses. This information will be used for content population purposes.

1. Get degree ID with query college

Use this query to get data about your Member College, a list of Degrees, and Degree IDs. Degree ID you need to query a list of Courses in a degree.

2. Get courses ID with query listCourses

Use this query to get a list of Courses and their IDs. With Course ID you can submit resources to the Course Library. Fetch the course grade weighs IDs.

Submit the necessary resources

Submit the necessary resources for each category, upload or import their assets, and ensure that the total workload of all resources exceeds the required amount.

To create and submit resources for verification, you need to use the createResource API mutation. After the submission, the Woolf Accreditation team will review and either verify or reject it.

Resources can contain text and/or assets (attached files).

Before you start, make sure you are familiar with resources here.

You can use the workload property to specify the required amount of time, in minutes, for each resource to be completed. If workload is not specified, the default value defined by our accreditation team for the category will apply. Default workload for generic resources can be found within the course workload property.

Assignments and summative assessments must be connected to their grade weights. You must use the weightIds property to assign them.

Mutation:

createResource(
courseId: ID!
resource: ResourceCreate!
): AMSResource
Field
Explanation
courseId
ID of the course to which you are adding resource
resource
ResourceChange - Object with resource data
input ResourceCreate {
name: String!
kind: AMSResourceKind!
weightIds: [ID!]
descr: String
workload: Int
airlockExtensions: Json
}

Example of API request for creating a resource for lesson notes:

mutation {
    createResource(
        courseId: $courseId
        resource: {
            name: "Lecture topic"
            kind: GENERAL
            descr: $content # content rendered in the LMS using markdown
            workload: 60
        }
    ) { id }

If inside your text there are links make sure they are publicly available and use proper markdown syntax for links.

[Displayed name](https://link)

Manage the storage of resource ID on your end.

To manage your resources Airlock API requires to store resource ID. Resource ID is needed to view information of that resource, modify it (change, delete, archive, unarchive), manage webhooks related to resources, or send Woolf student's and teacher's submissions related to the resource.

You will use Resource ID to tag resources in your College LMS, so that Airlock SDK can track consumption of it.

So having on your end proper management of resource ID that we return when you createResource is crucial for the implementation.

Get notified about resource rejection

Get notified about resource rejection with Woolf webhooks

Course content that Member College uses should be verified by Woolf Accreditation Team.

Woolf blocked consumption of rejected content, so make sure you apply changes to your content per Accreditation Request.

Woolf can notify you when a resource has been rejected by the Woolf Accreditation team:

  • REJECTED_RESOURCE

You can find more details in the Airlock Webhooks guide.

Modify resource

Mutation modifyResource

Use this mutation to modify a previously submitted resource. You can only modify resources if they are not verified.

Archive resource

Mutation archiveResource

Use as a soft delete. If a resource is not needed and you are unsure if you want to use again in the future, you can archive the resource instead of deleting it. It won't be visible to your students or teachers.

How to tag resources in your LMS

Our SDK automatically tracks the accredited HTML resources consumed by students on your platform, such as PDFs, videos, audios, or plain markup and images. However, to enable tracking, you must add the data-resource-woolf="<ResourceId>" attribute to the container that renders the related content. Make sure you add it as close to the content as possible. Otherwise, SDK scanning of the page may cause performance issues and downgrade the user experience.

No need to add data attributes to all resource types.

There is no need to add data attributes to all resource types because we track them differently. Only "General", "Publication" and "Peer-reviewed publication" (if it contains text, not an asset) resources require tagging on your platform with data-resource-woolf="<ResourceId>".

You may split resources across different sections and pages. Ensure that all parts of the content are wrapped with properly tagged containers. Our SDK will automatically grab those chunks and calculate the percentage of resource consumption.

HTML elements must be tagged with

<div data-resource-woolf="<ResourceId>">
    Markup of accredited content or its sections.
</div>

Assets must be tagged with


<a href="https://cdn.example" data-resource-woolf="<ResourceId>">...</a>


<div data-resource-woolf="<ResourceId>">
    Link to accredited assets such as PDFs, videos, audios, etc.
</div>

Enroll your students

Begin adding students

You can begin adding students to your college on our platform. If you have already integrated the Airlock SDK into your LMS, adding students using the addStudentsToCollege mutation will automatically enable consumption tracking of all previously submitted resources, even if they have not been verified.

Tracking will occur even if students have not yet purchased a degree or passed the onboarding process. This allows you to start building their educational records immediately and gives your success team a strong argument when converting these students to degree purchases in the future.

You can optionally link a student with their ID on your platform using the externalId property.

  • email - the only mandatory field.
mutation {
    addStudentsToCollege (
        students: [{ 
            email: "user@email.example"
            nameFirst: "Virginia"
      nameLast: "Woolf"
            externalId: $externalId
        }]
    ) { id }
}

Invite students to degree

Once a student has purchased a degree, you must add them to the related program on our platform using the addDegreeStudent mutation. This mutation works for any student, regardless of whether or not they were previously added to the AMS.

When a student is added to a degree, they will receive a notification on their dashboard about the need to complete onboarding. The Woolf widget displays an indicator for any pending tasks and provides students with access to their dashboard.

  • email and degree ID - the only mandatory fields.
mutation {
    mutation {
  addDegreeStudent(
    degreeId: "degree_id"
    email: "email@email.com"
    nameFirst: "Virginia"
    nameLast: "Woolf"
  ) {
    userId
  }
}

Student enrollment to Degree

In order to start enrolling students to Degree the College and Degree should be verified in the Woolf platform.

Students can be invited only to verified degrees from verified college.

In order to enroll in a Degree, a student must pass degree application (Woolf's 5-step onboarding) flow:

  • Identity verification step: student passes the ID verification with 3-rd party Persona, and provides necessary legal data like full legal name, date of birth etc.
  • Qualification step: Student is required to enter his highest degree level. Student needs to provide the name of the degree, institution that issued the degree. Upload photo/scan of the degree.
  • Statement of motivation: a short answer application (“why am I enrolling in this degree?“)
  • Sign an enrollment agreement. These steps are completed with flow.

Use SDK DegreeApplicationModal for onboarding students to degrees with Woolf's widget.

image

After the Member College adds a student to a degree with API mutation addDegreeStudent, the student will appear in the Woolf AMS with status invited.

The Member College generates Auth Token to initialize SDK to start onboarding for the student via the Woolf widget. Learn more about working with the Airlock SDK in our guide.

image

After the student has been added to a Degree, he/she has to see Woolf's FAB (Floating Action Button with Woolf logo). This button opens the Woolf Dashboard widget.

When the student commences the onboarding flow, their status changes to onboarding. After the student finishes the onboarding flow, their status becomes submitted. This status means that the enrollment agreement has been signed and that all onboarding steps have been completed. If the student declines to sign the enrollment agreement, their status changes to declined.

In the Woolf AMS, the Member College's Academic Board or College Admin needs to approve the student application. Woolf Team needs to approve student's education level.

After the degree application is approved and education is verified, the student will update to status active. If the Board or Admin reject the student, the status will update to rejected.

Only active students can earn credits.

Once the student's status becomes active in a Degree, student is eligible to complete courses, earn credits and obtain a degree.

Payment details

To invite a student to a degree you use mutation addDegreeStudent that incudes 2 optional fileds:

  • paymentStatus - student degree payment status, PAID or UNPAID. By default is UNPAID. The value in this field is a subject for billing and student access to earn credits. So make sure to synchronise with you payment and financial system or you can do it manually in Woolf's invoice management tool.
  • price - price that student paid for the degree. By default it is a Degree Price, that you specify on degree creation step. The value in this filed is a subject for billing, so make sure you specify the price student actually paid.

It's impossible to change payment status from PAID to UNPAID or change a price when status is already PAID.

So if you do not know the price student paid for a degree when you invite student to a degree with mutation addDegreeStudent- mark payment status as UNPAID or leave it as default. Later you can change payment status to PAID and specify the price.

Get notified about student status with Airlock webhooks

Students of Member Colleges can begin studying in accredited programs that offered by Woolf only after their degree application has been approved.

Use webhooks to get updates about student onboarding status.

Woolf can notify a Member College when a student's:

  • education and ID verification has been approved or rejected.
  • degree application was submitted.
  • degree application was approved or rejected.

You can find more details in the Airlock Webhooks guide.

Students are added to course automatically

Students are auto-added to the course after their first course activity is tracked by Woolf.

After student enrolled in degree, student is auto-added to course after first activity in course was tracked.

The activities inside a course are: consumed resource, submit assignment, receive grade and feedback. After any of these happen the student is auto-added to the that course and appears on course student lists. All events will be recorded in the Woolf AMS and reflected in Student Course Activity History.

Course must be compliant and verified by Woolf prior to any student engagement with this course content.

Student flow and statuses inside the course

After a student was added to a course, he/she appears on the list of course students with the status in progress. That means that the student can start consuming resources, submitting assignments, receive grades and feedback. All of this activity goes into the student's academic record.

After the student completed all learning activities: submitted required assignments, consumed all required resources, received grades, and reached the minimum workload that is required for a course, the teacher should submit this student for approval. The student's status is changed to submitted. After that action student's record becomes immutable: no one can change course requirements for that student, add or remove consumed workload, etc. College Academic Board must review this student and approve his/her final grade or reject it.

After the approval student receives the status passed or failed.

Track educational paths

To be compliant courses have to meet certain requirements:

  • minimum workload hours.
  • a minimum number of resources: peer-reviewed publications, meetings, regular assignments and summative assignments.
  • number of teachers

These Course requirements are connected with the required data that Woolf collects about student learning inside this course.

Each course has a required total workload that needs to be consumed by a student. Student needs to consume the required workload to be eligible for graduation.

In order to provide accreditation and build a strong record for regulators, Woolf must collect and log the following data from Member Colleges in its Accreditation Management System (AMS):

  1. Resource consumption
  2. Student assignment submissions: regular and summative
  3. Grades and teacher's feedback

Resource consumption has to contain:

  • peer-reviewed publications consumption (mandatory)
  • meetings consumption (mandatory)
  • general materials consumption (these resources are not mandatory but their consumption contributes towards the total workload student must consume)

Resource consumption is an actor-based real-time event that Airlock SDK tracks. It is proof that the student consumed the resource, and that it was the same resource that was originally verified by Woolf.

In the next section, we describe each of these resources and howtheirs consumption should be tracked.

Resource consumption tracking

First, you must authorize the Airlock SDK for all students who were previously added to AMS when they login to your LMS. Students must have permanent access to the Woolf Widget in all of your apps throughout their educational journey. Not complying with this requirement may lead to loss of accreditation.

Learn more in the SDK guide.

Airlock SDK automatically tracks the consumption of general resources and peer-reviewed publications.

To capture proof that a student has consumed all required content in a Member College's LMS, Woolf must log specific data in the AMS. This is accomplished using the Airlock SDK and API.

To collect the required data, a Member College needs to:

  1. Build a Course Library in Woolf and establish resource connectivity. Explained in guide.
  2. Integrate and install the Airlock SDK.

Woolf logs and stores student learning activity as a part of a student’s educational record.

It is crucial for accreditation that we build a connection between an actual student and his/her resource consumption.

image

When a student triggers the event of consuming that resource in a Member College's LMS, the Airlock SDK performs a check of that resource:

  • Is the consumed text the same as the one originally submitted to Course Library?
  • Does the asset (attachment) have the same hash-based signature?

What we do not support at the moment:

  1. Content in iFrame
  2. Custom watermarked files

General materials

Tech name of the resource kind:GENERAL

This resource kind is used for course content like: lecture notes, reading materials, any study materials that form part of a student’s curriculum, not included in the other categories, like slide presentations, videos, and links to articles.

In order to track peer-reviewed publications College needs:

  1. Create resource with kind GENERALin Course Library. Content can be added in a form of file attached (for example pdf) and/or text(markdown). Learn about uploading asset in dedicated guide.
  2. When student downloads the file or reads a text, Airlock SDK tracks this activity and adds it to student academic record.

Resource is counted as consumed and workload is added to total consumed after it was tracked by Airlock SDK.

Peer-reviewed publications

Tech name of the resource kind: PUBLICATION_REVIEWED

Peer-reviewed publications consumption is tracked with Airlock SDK.

Peer-reviewed publications is a peer-reviewed academic literature published in the last 5 years.

In order to track peer-reviewed publications College needs:

  1. Create resource with kind PUBLICATION_REVIEWED in Course Library. Add a publication in a form of file attached (for example pdf). You may also add publication as text (markdown). Learn about uploading asset in dedicated guide.
  2. When student downloads the file or view the text, Airlock SDK tracks this activity and adds it to student academic record.

Resource is counted as consumed and workload is added to total consumed after it was tracked by Airlock SDK.

Meetings

Tech name of the resource kind:MEETING.

Meeting consumption is tracked with Airlock API, SDK is not involved in this activity.

If during course your student are attending live lectures, synchronous meetings, 1on1 with a teacher, group meetings like standups or Q&A sessions - all this student work should be logged as meeting consumption.

In order to track live attendance in meeting College needs:

  1. Create resource with kind meeting in Course Library. You may add description in a resource what is this meeting about, the agenda, etc.
  2. When student joins the meeting College sends API request to Woolf, that specific student joined this meeting.
  3. After meeting is finished College must upload meeting recoding as asset to meeting resource.

Make sure your API request is real-time.

Woolf collects the timestamps of students joining the meeting. It's crucial for compliance to receive addEvidence request as soon as student joins meeting. Ideally student action of joining meeting should trigger API call on your side.

If student missed the meeting and may review a recording of it - it is also considered as meeting consumption.

When student reviewed recording College sends API request (same method as live attendance).

1 Step. College create evidence

College create evidence (activity) with API mutation addEvidence.

To create evidence College needs to provide resource ID, user ID of a student, confirmation URL optionally.

In response you'll receive type Activity with id.

addEvidence(
resourceId: ID!
studentId: ID!
): Activity

As result: activity is created. Student meeting consumption event is recorded in student activity history and will be visible in AMS.

2 Step. College uploads meeting recording

College uploads meeting recording as asset to the meeting resource.

Use mutation importAsset .

importAsset(
parentModel: AssetParentModel!
parentId: ID!
assetURLs: [String!]
playlistURL: String
): [Asset!]
  • parentModel: AMSResource
  • parentId: resource ID of the meeting

To learn more about uploading assets read our guide.

Consuming meeting resource in async form.

If student was not present on live meeting, it is also possible to consume meeting resource by reviewing meeting recording. Use the same mutation as you you for live attendance record: addEvidence.

When student reviewed meeting recording (that was added as asset to meeting resource) use mutation addEvidence to send Woolf this activity.

Resource is counted as consumed and workload is added to total consumed after API request addEvidence was successfully sent. .

Student Assignment Submissions

During course student must take at least 1 Summative Assignment and 1 Regular Assignment.

  • Regular Assignment: Quizzes, essays, status reports, and other assignments.
  • Summative Assignment: Every course requires students to complete at least one cumulative assignment. It should include or build upon all the learning objectives of the course.

The general flow of assignments contain 3 steps:

  1. Adding the resource with kind ASSIGNMENT (for Regular Assignment) or kind ASSIGNMENT_SUMMATIVE (for Summative Assignment) to Course Library.
  2. Student submission. When student finished working on assignment and submits the results Airlock SDK should be triggered. Airlock SDK will track that action, make a screenshot of a screen and create an activity. Student submission should be send to Woolf with Airlock API. Submission can be in a firm of text, file or both.
  3. Student receives grade and/or feedback for this assignment.

Add Regular and Summative Assignment resources to Course Library

Adding the resource with kind ASSIGNMENT (for Regular Assignment) or kind ASSIGNMENT_SUMMATIVE (for Summative Assignment) to Course Library.

To create a resource use usual API mutation createResource.

Besides standard for all kinds of resources fields like name, kind and workload, you need to specify:

  • Description of a task (what student must do), and any instructions that are provided to student. This can be send in a form of text (markdown in field descr) or in a form of file (asset attached to a resource)
  • Assign grade weight category to that resource: provide ID of the grade weight category in field weightIds.

Assigning grade weight category to that resource is very important, as later the grade will be sent not just to a resource, but to a specific grade weight category also.

You may assign a multiple grade weight categories to one assignment. For example, teacher may provide few grades for one assignments, estimating separately overall performance, innovative approach to a project, presentational skills etc.

Student submission

Student submission should be sent to Woolf when student is uploading it on College LMS.

Use API mutation studentSubmitAssignment(with oauth student token) to send a submission.

When student finished working on assignment and submits the results in College LMS - Airlock SDK should be triggered. Airlock SDK will track that action, make a screenshot of a screen and create an activity. Student submission should be send to Woolf with Airlock API. Submission can be in a form of text, file or both.

image
  1. A resource with kind assignment or summative assignment was created and verified.
  2. Member College gets resourceId from the Woolf AMS in return. This resource ID should be used when sending submission for that resource.
  3. When a student triggers the event of submitting an assignment in a Member College's LMS, the Airlock SDK will capture screenshots as proof that the actual student triggered the event.
  4. The screenshots are then sent to the Woolf AMS, where a record of student activity is logged.
  5. The Airlock SDK returns activityId of that record to the Member College, which should later be used in an API request.
  6. A Member College with Airlock API method studentSubmitAssignment sends the student submission (in a form of file or text) to Woolf with following data activityId, resourceId.

Resource with kind assignment or summative assignment is counted as consumed and workload is added to total consumed after student submission was successfully sent to Woolf via Airlock API.

Case when student is making a submission not inside College LMS.

If your courses contain assignments that student take in external Proctoring Software outside College LMS, where Airlock SDK can not be installed, we offer you a possibility to send student submission without SDK.

Please contact our support team and we will provide you a guide.

Student receives grade and feedback

After student submission was send, student may receive a grade for the submission and feedback.

Teacher's feedback is mandatory for summative assignment and project, added as regular assignment. For other types of assignments like quizzes feedback is optional. We will describe how to send feedback in next sections.

Grades may be submitted by a teacher or provided by a College.

Process of sending a grade, that is provided by a teacher is similar to sending student submission. It is done with Airlock SDK and API.

Grade that is provided by College does not require Airlock SDK.

It's allowed to send grade on behalf of College for auto-graded quizzes or assignments that are take place in external software, outside College LMS.

Grades and feedback

Students must receive grades for assignments from either a teacher or college. These grades are used to calculate Running and Final Average Scores.

Assignments may have multiple grade weight categories. Therefore, when sending a grade, colleges must specify the weight ID in addition to student ID and resource ID.

Woolf provides a system to manage assignment retakes and grade improvements. When a student receives multiple grades for an assignment, the last grade provided is considered final. Colleges may have different policies for improving grades.

Colleges may provide grades and feedback on behalf of the college in rare cases, but only after obtaining prior agreement from our accreditation team. Typically, such cases should not exceed 20% of all grades.

Grades and grade weights

Student can receive grades for assignments. The grade can be provided by a teacher or by college (in case grades are calculated automatically).

All received grades for assignments are used in calculation of Running Average Score and Final Average Score.

Student allowed to retake the assignment and improve grade. The policy is up to the Member College. Woolf provides a possibility to manage assignment retakes and grade improvements for specific assignment.

Student can receive more than one grade for assignment. We always consider the last grade you provide as final. It means that College can have a custom policy for improving grades: consider the highest grade as final, or the last one, or averaging the grades. Just make sure you send the final grade for assignment (according to your policy) as last one before student's course grades are submitted for approval.

Also, in case of assignments retakes make sure that the last grade sent matches the last feedback sent and last student's assignment submission sent. In student academic record we show last ones as final, and it's important that Regulator and Woolf Accreditation Team have grades and feedback that are related to the assignment submission.

Student can retake the assignment. College can send multiple student's submissions, grades and feedback for one assignment.

  1. The last grade sent is considered as final. Final grade is used in calculation of Running and Final Average Scores.
  2. The last grade sent should match with last feedback and last student's submission sent to a specific assignment.

Note: Grades are provided for assignment and grade weight. As assignment can have more than one grade weight category assigned to it. Feedback and student's submissions are provided just for assignments (resource with kind assignment or assignment summative).

  • Feedback and student's submission - for resource.
  • Grade - for resource and grade weight assigned to the resource.

That is why when sending grade, College need to specify not just resource ID, but also weight ID.

Send grade and feedback provided by a teacher

API Mutations:

  • Send Woolf grade added by teacher: teacherAddGrade
  • Send Woolf feedback added by teacher: teacherAddFeedback

In the event of teacherAddGrade, the Member College sends : activityId, resourceId, grade, grade weight ID, and student ID.

In the event of teacherAddFeedback, the Member College sends : activityId, resourceId , student ID, text and/or assets of that feedback.

Adding a teacher to the Course happens in AMS manually. By College admin during the Course setup process

Only teachers registered in Woolf can provide grade or feedback (that will be captured via SDK).

If some grades or feedback needs to be provided by people that for some reason can not be registered in Woolf - you may send these grades and feedback with just API addGrade addFeedback . But this can not be a summative assignment.

You may get IDs of teachers in queries (teacher added to the courses with query listCourses -> field tutors)

Send grade and feedback on behalf of college

College is allowed to provide grades and feedback on behalf of college, not a teacher. The API request are made with API Token and do not require any activityId or SDK launched for the moment of submission. On student record it is marked as feedback or grade provided by college.

Grade provided with API Token

If you have an assignment that is graded automatically, not by a teacher, you can send grade on behalf of the college with API Token

Send grade for the assignment (with API Token token) with mutation addGrade

addGrade(
resourceId: ID!
score: Float!
studentId: ID!
weightId: ID!
): AMSScore

What is weightId?

Resources with kind assignment or assignmentSummative have grade weight categories assigned to them. Each resource can have one or more grade weights categories assigned.

College can fetch weightId with query listResources or showResource . Both of these queries contain field weights that returns object AMSWeight.

In AMSWeight you can find weightId, name of grade weight category and percentage of that category.

You can learn more about Grade Weights and how running average is calculated here.

Feedback provided with API Token

If you have a feedback for student assignment submission not from actual course teacher, but from quest lecturer or generated automatically, you can send this feedback on behalf of the college with API Token.

Send feedback for the assignment (with API Token) with mutation addFeedback

addFeedback(
descr: String!
resourceId: String!
studentId: ID!
): AMSFeedback

If feedback is just a text, send it as markdown in field descr. If feedback is a video or file attached, use field descr for name or description on attachments (assets). You can also leave this field empty by sending descr: "" if you have just attachments and it is inconvenient for you to generate any naming or description for that feedback.

Archive grade

College has the ability to mark some grades that student received as ones that should not influence the Running and Final Average, only before student get submitted for Academic Board approval to finalize grades.

This feature can be used if student needs to retake exam with different resource, or start the course fresh with no Average.

Given Conditions:

  • Archiving grade is not allowed for submitted or completed students in the course.
  • Event with archived grade remain on the student course activity history.

To archive grade use API mutation archiveGrade.

College needs to specify resource, student and grade weight. As a result all grades that student received for specific resource and grade weight will be deleted. This action can not be undone.

archiveGrade(
resourceId: ID!
studentId: ID!
weightId: ID!
): Boolean

Fetch data of course progress, grades, submissions, feedbacks.

Woolf offers 2 queries for fetching student activity data.

  • query showStudentCourseProgressget student course status, Running and Final Average Grade, workload hours consumed in course and required, required resources consumed.
  • query showStudentResourceProgress - get submitted for specific resource list of student's assignments, list of provided feedbacks and grades. Get evidence of activities with this resource. Note that records are sorted chronological, and the first item in a lists is always the last one received from College. We treat the last grade, submission and feedback sent as final.

Explore the queries with our GraphiQL.

How Woolf counts consumed workload?

Each course has a required total workload that needs to be consumed by a student. Student needs to consume required workload to be eligible for graduating.

For resources with kind assignment and assignmentSummative Woolf counts workload as consumed only when a student submitted an assignment. So just reading the assignment description does not count as consumed resource and this hours of resource workload are not added to total consumed .

For other kinds of resources (publication, publicationReviewed, meeting, general) resource is counted as consumed and workload is added to total consumed after it was tracked by Airlock SDK.

Course graduation

Ensure that you constantly monitor the educational progress

First, ensure that you constantly monitor the educational progress of your students in courses. Use the query showStudentCourseProgress to fetch educational requirements and determine if students are complying with them.

With API query showStudentCourseProgress where you'll get:

  • Final Average scoreFinal
  • Running Average scoreRunning
  • Student status in course status
  • Consumed workload and required workload workloadPassed workloadRequired
  • Number of passed and required kinds of resources:assignmentPassed: Int!assignmentRequired: Int!assignmentSummativePassed: Int!assignmentSummativeRequired: Int!meetingPassed: Int!meetingRequired: Int!publicationReviewedPassed: Int!publicationReviewedRequired: Int!

You may also check student compliance manually in Woolf AMS in course students table.

Submit students who meet the course graduation requirements

To submit students who meet the course graduation requirements for College Board approval, use the submitStudentsForEvaluation mutation. This action can be also done by a Teacher in Woolf AMS manually.

The College Board will approve or reject the graduation asynchronously using the AMS interface.

API method submitStudentsForEvaluation

Provide course ID and student ID (user ID of a student).

submitStudentsForEvaluation(
courseId: ID!
studentIds: [ID!]!
): [ID]

We run few checks in a background to allow student to be submitted. Student is compliant when all this checks are passed:

  1. student course status is "in progress" (in API status name is "active"). Student has "in progress" status only if course is in a degree, where student finished onboarding and is "active".
  2. student consumed all required workload
  3. student consumed all required resources

If all checks are passed, we submit student.

In response you will get list of student IDs that were successfully submitted. Their status will be changed to "submitted". Those who didn't match compliance requirements will stay in their current statuses and won't be submitted.

To get a final grade on an official transcript, a student must complete a Course. Once the Academic Board approves the grade, it becomes final and appears in the student's official transcript.

image

Webhooks

Airlock also includes the following webhooks, so you can know right away when a student's final grades are submitted for approval, as well as when final grades are approved or rejected by a member of the Member College's Academic Board:

  • COLLEGE_SUBMITTED_STUDENTS_FOR_EVALUATION
  • STUDENT_PASSED_COURSE
  • STUDENT_FAILED_COURSE

Learn more about Airlock webhooks in our webhook guide.

Degree graduation

Each student must complete the required number of ECTS in the degree.

Each student must complete and pass each specifically required course in a degree.

To complete a degree, a student must complete all Tiers.

Each Tier has a required number of hours that a student must put in during their study, as well as a list of Courses that the students can choose to complete.

Students can apply to obtain a completed degree (i.e., convert earned credits into an official degree) in the Woolf AMS:

  1. In the Woolf AMS, navigate to the Degrees page and click apply to obtain a degree.
  2. Submit the short degree application form.

This application is reviewed and approved by the Woolf Accreditation team. Following approval, the student will receive a certificate that can be shared with a link.

Airlock SDK

Woolf SDK contains Widget:

  • Degree Application Modal
  • Dashboard Modal

and Trackers:

  • Resource Consumption Tracker
  • Assignment Submission Tracker
  • Grade Submission Tracker
  • Feedback Submission Tracker

Installing SDK

Installing SDK using NPM

npm i -S @woolfteam/client graphql

import { Woolf } from "@woolfteam/client"

const token = 'oauth jwt token'

const woolf = await Woolf.create(token)

Installing SDK using script tag

To install the Woolf SDK using a script tag, you can use the following code:

HTML

<script src="https://unpkg.com/@woolfteam/client@latest/build/vanilla.js" data-woolf-token="your_oauth_jwt_token"></script>

Replace "your_oauth_jwt_token" with your actual OAuth JWT token.

After including the script tag in your HTML file, the window.woolf object will expose the Woolf instance.

A woolf:created event will be published on a document object to signal that woolf object finished loading:

document.addEventListener('woolf:created', (woolf) => {
      console.log('woolf:created', woolf)
})

SDK UI Controls

Dashboard Modal

const modal = woolf.openDashboardModal()

modal.close()

modal.open()

modal.opened // Boolean

Degree Application Modal

const modal = woolf.openDegreeApplicationModal(degreeId)

modal.close()

modal.open()

modal.opened // Boolean

FAB

woolf.fab.show()

woolf.fab.hide()

woolf.fab.shown // Boolean

Custom styling

  • You can pass an object with custom CSS classes configuration as an optional second argument to Woolf.create call to change alter SDK styling.

    • Assuming that you have the following CSS classes defined:

    CSS

    global modal styling
.custom-classname.woolf-modal-overlay {}
.custom-classname .woolf-modal {}
.custom-classname .woolf-modal-header {}
.custom-classname .woolf-modal-close {}

fab styling
.custom-classname.woolf-fab {}
.custom-classname .woolf-fab-indicator {}

    Apply using:

    Woolf.create(_, { 
    fabClassName: 'custom-classname', 
    modalClassName: 'custom-classname' 
})

SDK default styling that you can use for available classes reference:

.woolf-modal-overlay {
  position: fixed;
  left: 0;
  top: 0;
  width: 100%;
  height: 100%;

  display: flex;
  align-items: center;
  justify-content: center;
}

.woolf-modal {
  max-width: 1200px;
  width: 100%;
  max-height: 960px;
  height: 100%;
  background-color: #fff;

  z-index: 999;
  overflow: auto;
  border: none;
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 60px 0 rgba(0, 0, 0, 0.19);
  border-radius: 8px;
}

.woolf-modal-header {
  padding-bottom: 1rem;
  padding-left: 1rem;
  padding-right: 1rem;
  padding-top: 1rem;

  border-bottom-color: #DADDE2;
  border-bottom-width: 1px;
  border-bottom-style: solid;
}

.woolf-modal-close {
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: #DADDE2;
  border-radius: 100%;
  border-style: none;
  width: 2.25rem;
  height: 2.25rem;
  margin-left: auto;
  font-size: 1.5rem;
}

.woolf-modal-close > div {
  font-size: inherit;
  height: 100%;
}

.woolf-modal-close:hover {
  cursor: pointer;
}

.woolf-modal-iframe {
  border-style: none;
  width: 100%;
  height: 100%;
}

.woolf-fab {
  position: relative;
  width: 55px;
  height: 55px;
  border-radius: 50%;
  background: black;
  color: white;
  padding: 16px;
  z-index: 9999;
  position: fixed;
  bottom: 30px;
  right: 30px;
  cursor: pointer;
  box-shadow: 0px 2px 10px rgba(0, 0, 0, 0.1);
  display: flex;
  justify-content: center;
  align-items: center;
  aspect-ratio: 16/9;
}

.woolf-lab-indicator {
  align-items: center;
  background: #84B9EF;
  border-radius: 100%;
  display: flex;
  font-size: 0.625rem;
  font-weight: bold;
  height: 1.25rem;
  justify-content: center;
  position: absolute;
  right: 0;
  text-align: center;
  top: -0.1875rem;
  width: 1.25rem;
}

User data

After initialisation a user property will be available for SDK instance which will contain corresponding educations & degreeStudents.

You can manually update data by running the syncUser.

Tracking

Use the id that you get after creating a resource through API as a data-resource-woolf attribute on an HTML element that will include content for this resource on your pages.

Initialized SDK will recognize such elements automatically and send tracking events to fulfill student academic records on a Woolf side.

Learn more in guide

Generating Activity ID

There are three main pieces of academic activity that Woolf's platform needs to be preserved: student submissions, teacher feedback, and grades.

To verify user interaction during any of these actions, use the corresponding SDK methods (no arguments required):

  • studentSubmitAssignment()
  • teacherAddFeedback()
  • teacherAddGrade()

You will get an activity id and, as a result, pass it in the related API request.

Airlock Webhooks

Listen for events on your Woolf College account, so your integration can automatically trigger reactions.

Airlock uses webhooks to notify your application when an important event happens in your College. Webhooks are particularly useful for asynchronous events like when a Woolf Accreditation team verifies a student or resource, a student submits a degree application, or the College Academic board approves a student's final grade.

Events related to student enrollment in degree

  • ADDED_DEGREE_STUDENT
  • REJECTED_DEGREE_STUDENT
  • SUBMITTED_DEGREE_STUDENT
  • APPROVED_DEGREE_STUDENT

Events related to education verification

  • REJECTED_EDUCATION

Events related to resource verification

  • REJECTED_RESOURCE

Events related to student course graduation

  • COLLEGE_SUBMITTED_STUDENTS_FOR_EVALUATION
  • STUDENT_PASSED_COURSE
  • STUDENT_FAILED_COURSE

IMPORTED_ASSETS

On Success

data will include an array of assets with id, name, meta, parentId, parentModel, and few other less important fields.

{
    "deliveryId": "uuid",
    "signature": "JWT",
    "event": "IMPORTED_ASSETS",
    "data": {
        "id": "uuid",
        "name": "Name of the file",
        "meta": {
            "field": "value"
        }
    },
}

On Error

data will include message, and meta. message is an error message. meta includes referenceId, parentId, and parentModel fields

{
    "deliveryId": "uuid",
    "signature": "JWT",
    "event": "IMPORTED_ASSETS",
    "data": {
        "message": "This went wrong",
        "meta": {
            "referenceId": "uuid",
            "parentId": "uuid",
            "parentModel": "parentModel"
        }
    }
}

How to work with webhooks

  1. Identify the events you want to monitor.
  2. Create a webhook endpoint as an HTTP (URL) on your local server.

/:information_source: Only HTTPS URLs are allowed.

  1. Subscribe to webhooks

Add your publicly accessible HTTPS URL with Airlock API mutation addWebhook. In the request, you need to specify webhook event and URL.

There are three mutations that you can use to manage webhooks:

addWebhook

This example shows how to subscribe to events:

QueryVariables

mutation addWebhook($url: String!, $events: [WebhookEvent!]!) {
  addWebhook(url: $url, events: $events) {
    id
    url
    events
    inflection
    deliveries {
      id
      state
      request
      response
      code
      tries
      created
      updated
    }
    created
    updated
  }
}

changeWebhook

It is possible to change webhook as well.

removeWebhook

This example shows how to unsubscribe from events:

QueryVariables

mutation removeWebhook($id: ID!) {
  removeWebhook(id: $id) 
}

Handle requests from Airlock

As soon as an event happens, we send you an HTTP POST request to the URL you provided.

Secure your webhooks

Use secret key to verify that webhook request originated from Woolf server. Webhook request will include a signature field with request json body signed by your secret token as json web token. So, to verify the request you can run jwt.verify(request.body, secret) and receive a valid json body as a result.

Limitations

GraphQL gives enormous power to clients, but with great power comes great responsibility.

Since clients have the possibility to craft very complex queries, Woolf servers must be ready to handle them properly. A client can potentially take down your GraphQL server.

We have certain limitations in place to mitigate such risks.

Maximum Query Depth

The Woolf server is configured with a Maximum Query Depth of 15.

A depth above 15 is considered too deep, and the query will be invalid.

Request Rate Limit

We have a limit on the number of requests that can be made within a specific time period. This limit is in place to prevent abuse of the service and to ensure that all users have equal access to the resources.

The current request rate limit is set at 20 requests per second.

Uploading assets

Some of our mutations allow adding attachments to created instances: resources in Course Library, students’ submissions, or feedback. These attachments (assets) can be added using a separate mutation importAsset .

Add attachments(assets)

importAsset allows to add assets by providing an URL, so Woolf downloads assets from this URL and uploads them to the AMS. You do not need to upload files to our system, just provide us with the URL, where we download a file ourselves.

The request should be made with API token.

importAsset(
parentModel: AssetParentModel!
parentId: ID!
assetURLs: [String!]
playlistURL: String
): [Asset!]
AssetParentModel Enum Values
Description
AMSResource
Used when you want to add assets to a resource
AMSFeedback
Used when you want to add assets to a feedback
AMSAssignment
Used when you want to add assets to a student submission
Activity
Used when you want to add an asset to a activity that you generated by API (used in rare cases and with approval from Woolf Accreditation Team)
  • parentId - ID of the entity to are uploading asset to. Example: if parent model is AMSResource, then in parentId you must provide resource ID.
  • playlistURL must provide a playlist in m3u8 format.
  • In assetURLs send one or multiple URLs, each should contain one file. Files uploaded must be 50 MB or less. Type of the file we support:
    • Images (png, jpg, jpeg, gif, heic, svg+xml)
    • Documents (pdf, plain, csv)
    • Audio (any)
    • Video (any)

With one request you can send only playlistURL  or  assetURLs, not both.

If you need to add assetURLs and playlist, do two separate requests.

Async request

After sending a request to mutation importAsset import of assetURLs or playlistURL starts asynchronously, and the client gets the message about starting importing assets in response. After the completion of importing assets or playlists, the client will get a webhook containing data about the new asset.

You must add a new webhook with mutation addWebhook and pass data in parameters that contain the URL of the webhook and event IMPORTED_ASSETS.

image

Limits

The maximum file size is 1 GB.

Playlists should be imported sequentially after receiving a response from the server as a webhook. Other assets you can import in array. You can import files up to 1 Gb. It will take around ten minutes for us to upload a 1 GB file.

How assetURLs works?

Let’s imagine you need to add few images as assets to a resource A.

  1. First request: Submit a resource A with createResorce without an asset. In response you will get resorceId. Save it in your system, as you will need it to upload assets or simply modify that resource or query details.
  2. Second request: Send the URLs with images using importAsset mutation.

      3. In the request, you must specify a parentModel and parentId. The parent is a created instance that you want to add assets to.

      It can be:

    1. a resource in the course library(AMSResource)
    2. teacher’s or college’s feedback (AMSFeedback)
    3. student’s submission of an assignment (AMSAssignment).

      4. In our example parentModel is AMSResource, parentId is resourceId from first request.

How to import HLS video?

Let’s imagine that course final exam is executed during 3 hours meeting. You need to send it as evidence of student activity. In that case you need to add a long meeting recording to the student assignment submission as asset. We recommend uploading it as playlist (HLS) using field playlistURL in mutation.

  1. First request: Create a submission with studentSubmitAssignment mutation without an asset. In response, you will get id of that submission. Save it in your system, as you will need this id to add assets.
  2. Second request: Send the URL with playlist using importAsset mutation. In the request, you must specify a parentModel and parentId.

    3. In our example parentModel is AMSAssignment, parentId is Id from the first request.

Webhook IMPORTED_ASSETS

After asset is successfully imported you may receive webhook.

Payload example:

{
  "data": [
    {
      "id": "",
      "kind": "DEFAULT",
      "parentModel": "",
      "parentId": "",
      "path": "",
      "isPresent": true,
      "isTranscoded": false,
      "meta": {
        "type": "",
        "url": ""
      },
      "name": "",
      "createdAt": "2023-02-23T09:50:40.894Z",
      "field": "assets",
      "updatedAt": "2023-02-23T09:50:40.894Z",
      "rootId": null
    }
  ],
  "event": "IMPORTED_ASSETS",
  "deliveryId": "",
  "signature": ""
}

How to query assets?

For querying assets of a resource use the API method showResource where you will find the type Asset with all the data.

For querying assets of a student assignment submission, teacher's feedback use the API method showStudentResourceProgress. Each type include AssetList.

How to remove asset?

When you add an asset using mutation importAsset in response we send type Asset which contains removeToken . This token is needed to delete asset.

Use removeAsset mutation to delete asset.

removeAsset(token: String!): Boolean