Annotation Audit Events
Endpoint
If audit_url
is specified in the session launch request,
the DocViewer server will send annotation Creates, Updates and Deletes to that url.
The request will be formatted as such:
POST {AUDIT_URL}
Content-Type: application/json
{
token: string // See Authentication, below
canvas_user_id: string // The ID of the user that triggered the event
document_id: string // The ID of the document on which the event occurred
docviewer_audit_event: {
event_type: string // One of: "point_created", "point_updated", "point_deleted", "highlight_created", "highlight_updated", "highlight_deleted", "strikeout_created", "strikeout_updated", "strikeout_deleted", "free_draw_created", "free_draw_updated", "free_draw_deleted", "free_text_created", "free_text_updated", "free_text_deleted", "area_created", "area_updated", "area_deleted", "comment_created", "comment_updated", "comment_deleted"
annotation_id: string // The ID of the annotation
context: string // The context of the annotation
related_annotation_id: string // Present for event_type: "comment_created", "comment_updated" and "comment_deleted". It is the ID of the annotation the comment is attached to
annotation_body: {
type: string // The type of the annotation. One of: "point", "highlight", "strikeout", "free_draw", "free_text", "area", "comment"
page: number // The page number (0 indexed) on which the annotation exists
content: string // Contains the text contents of a "comment" or "free_text" annotation
color: string // The color of the annotation. Present for all event types except "comment_created", "comment_updated" and "comment_deleted"
created_at: string // Timestamp of when the annotation was created
modified_at: string // Timestamp of when the annotation was last updated
}
}
}
DocViewer just expects a 200
in response.
Errors
If an audit_url
is specified, and DocViewer sends audit events, the DocViewer server
will wait to actually save the annotation Create, Update, or Delete to the database
until the call to the audit_url
returns.
If the URL called returns a successful code (i.e. 200
) DocViewer will save/delete
the annotation.
If the URL called returns a 406
status code, DocViewer will ignore the error,
save/delete the annotation, and continue sending audit events.
If the URL called returns any other status code, DocViewer will not save/delete
the annotation, and will return a 403
to the client that sent DocViewer the PUT or DELETE.
If the DocViewer Client receives a 403
from an annotation PUT, it will display an
error reading Grader limit has been reached. No further feedback is required.
When the error modal is dismissed, the DocViewer Client will switch to readonly mode.
Authentication
DocViewer uses a shared secret to authenticate with the audit_url
. DocViewer
encodes a empty object (i.e. {}
) with a JWT, using the secret. This is then sent
as the token
parameter. It is expected that the server providing the audit_url
do the same, and compare against the incoming token
. To get this secret, speak
to the DocViewer team.