Sessions
{
type: string // Always contains "session"
id: string // The session jwt - This contains all the important session information
expires_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
}
Intro
When a user wishes to view a document in DocViewer, they must first
launch a session. This will return a session id
that
the client will then use for all future API calls. The session id
includes
authentication information, document id, user information, etc. With that
session id
in hand, the user can then Launch the DocViewer Client.
Create a Session
POST /1/sessions
Takes in several user-provided parameters and packages them together into a
jwt (referred to often as the session_id
) for use in future API calls, such
as in all of the Annotation Endpoints. The parameters
passed in will determine what session type will be launched,
and what the context will be. See Anonymizing & Hiding Annotations
for an explanation of the user_filter
, user_role
, restrict_annotations_to_user_filter
,
and anonymous_instructor_annotations
parameters. See Reading Annotation Events
for an explanation of the audit_url
parameter.
Parameters
This endpoint requires authorization
Headers:
Content-Type: application/json
Authorization: Token KEY_HERE
Body:
{
document_id: string // The ID of the document this session is to view
url: string // The url to a file that will be used to convert this document to a pdf if there are no valid renders of this document to be returned in the session
render_id: string // The render ID specified on the Document Object
render_plugin: string // The renderer to use. The only supported value is 'pdfjs'. If not present, defaults to 'pdfjs'
duration: number // Duration of session in minutes. If not present, defaults to 600 minutes.
annotation_context: string // This is the context. Not required if permissions are not provided
permissions: string // If not present, defaults to 'read'
user_id: string // The user id of a session. Annotations created in this session will have this user_id as the creator.
// If a session's user_id matches an annotation's user_id, that session will be able to manipulate that annotation.
// Not required if permissions are not provided
user_name: string // The user name of a session. Annotations created in this session will have this user_name as the creator.
// user_name is for display purposes only and not used to determine annotation ownership. Not required if
// permissions are not provided
user_anonymous_id: string // The anonymous user id of a session. Annotations created in the session will have this user_anonymous_id as the creator.
// If a session's user is only allowed to see anonymous annotations by a given creator, annotations will be returned with user_anonymous_id in place of user_id.
locale: string // Locale code, used for internationalization. Supported locales are: ar, cy, da, de, en, en_AU, en_GB, es, fr,
// fr_CA, ht, is, it, ja, mi, nb, nl, pl, pt, pt_BR, ru, sv, zh, zh_HK. If not present, defaults to 'en'.
region: string // The AWS region the call is originating from. Used in conjunction with Canvas to identify records that are in different Canvas and DocViewer regions.
anonymous_instructor_annotations: boolean // Pass true to force all annotations created during this session to be saved anonymously, so other users cannot see who created the annotation.
user_role: string // The role of the user - teacher, ta, or student
enrollment_type: string // An alternative way to send user role - teacher, ta, or student. Used by Canvas.
user_filter: [
{
id: string // The ID (real or anonymous) of the user who's annotations should be displayed
type: string // Either 'real' or 'anonymous'. Specifies if the ID is a real ID or anonymous ID, and if the annotations that match the ID should be anonymized or not
role: string // Ex: 'teacher', 'student', 'ta'.
name: string // Not required if 'type' is 'real'. For 'type' 'anonymous', this is the name that will be shown instead of the real name
}
]
restrict_annotations_to_user_filter: boolean // Pass false to display annotations not specified in the user_filter. Pass true to restrict annotations shown to just those defined by the user_filter
audit_url: string // Specifies the URL annotation events should be sent to
// All parameters below are used for sending notifications about annotations
canvas_base_url: string // The domain of the canvas instance notifications should be sent to
submission_user_id: string // The Canvas user id of the user who uploaded the document
course_id: string // The id of the Canvas course
assignment_id: string // The id of the Canvas assignment
submission_id: string // The id of the Canvas submission
post_manually: string // Whether the instructor in Canvas has chosen to have grades post automatically. If post_manually is false, notifications will be sent. If post_manually is true, notifications will only be sent if posted_at is not null
posted_at: string // Used in the logic for sending notifications to Canvas. See post_manually definition above
assignment_name: string // The name of the Canvas assignment
}
Responses
201
Returns a Session Object
Example Call
POST http://canvadocs.docker/1/sessions
Content-Type: application/json
Authorization: Token apikey
{
"document_id":"ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
"render_id":"ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ-pdfjs",
"render_plugin":"pdfjs",
"annotation_context":"canvadocs_admin",
"permissions":"readwrite",
"user_id":"standard_user",
"user_name":"Standard User",
"locale": "en",
"region": "us-east-1"
}
201 Created
{
"type": "session",
"id": "eyJhbGci...",
"expires_at": "2018-04-12T07:26:41.448Z"
}
Get a Session
GET /1/sessions/{session_id}
This endpoint returns information about the session: file urls, document information, session settings, etc. It is not currently being used, and as such, detailed documentation is not given here.
Launch the DocViewer Client
GET /1/sessions/{session_id}/view
Launches the DocViewer Client. This is usually loaded in an iframe so
as to load the app within another webpage. There is an example on the
Using the DocViewer Client page. This will
load the document and settings specified by the session id
.
Parameters
Query:
session_id: string // This jwt contains all the important session information
Responses
200
Loads the DocViewer Client
Example Call
GET http://canvadocs.docker/1/sessions/eyJhbGc.../view
200 OK
Returns the DocViewer Client