POST LTI: Create a Bookshelf Launch

This API will accept POST requests in IMS Global LTI 1.0 format using VitalSource Launch as the LTI tool. 

Example Launch from the IMS Global Specification

VitalSource Launch will consume your request, provision the VitalSource Bookshelf user account, add the book your are passing and respond with an SSO URL that will open this user account, at the location you seek.

To complete this request you MUST be previously setup in VitalSource Launch by an Integrations Mgr.

LTI 1.0 relies upon oAuth 1.0 as the authentication protocol. You must utilize this mechanism when making an LTI request. Below we are describing how to complete this request using Postman, but other development environments are acceptable. Your request header must contain an oAuth 1.0 HMAC-SHA1 authorization. This will include the VitalSource Launch Key and VitalSource Launch Secret sent to you by the Integration Mgr who set you up at VitalSource. As a separate item in the request header you will also need to pass "X-VitalSource-API-Key" which is the API key that allows you to make RESTful requests to VitalSource. 

The Postman example can be found here

Verb/URI

POST https://bc.vitalsource.com/books/book

Data Definitions

Name
Usage
Description
Data Type
Example
Required
user_id Query param Uniquely identifies the user. This should not contain any identifying information for the user. string

123abc456def789ghi

Yes 
roles Query param LTI role in this context. Note: Instructor launch will change the presentation within VitalSource Bookshelf. string 

Learner, Instructor, Administrator, TeachingAssistant, ContentDeveloper, and Mentor

No, Highly recommended
launch_presentation_document_target Query param This field communicates the kind of browser window/frame where the TC has launched the tool. string

frame, iframe or window

Yes 
custom_vbid Query param  The custom book identifier for SSO. This sends a user directly to a piece of content.  string

L-999-70103

No
custom_book_location Query param Allows the redirect to take a user to a "deep link" or specific location in the content. string

Go here to learn how

/cfi/6/6!/6/2/2@0:0 which is Chap. 2 when sent with the title above

No
context_id Query param  Value for the context of a launch, could be a course code, section number something unique to the calling system string 

abc-123

Recommended
context_type Query param This string is a comma-separated list of URN values that identify the type of context string

CourseSection

No
context_label Query param A label for the context string

ENG101-01

No
context_title Query param A title of the context string

English 101

No
lti_version Query param This indicates which version of the specification is being used for this particular message. string

LTI-1p0

Yes
lti_message_type Query param  This indicates that this is a Basic LTI Launch Message. string

basic-lti-launch-request

Yes
lis_person_name_full Query param  User full name string 

Test User 

No, not required by VitalSource
lis_person_name_family Query param  User last name  string 

Test

No, not required by VitalSource 
lis_person_name_given Query param User first name  string 

User

No, not required by VitalSource 
lis_person_contact_email_primary Query param  User email  string 

test.user@school.edu

No, not required by VitalSource 
tool_consumer_info_product_family_code Query param  Your product name  string 

PostmanRequest

No 

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
Content-Type
: application/x-www-form-urlencoded
Accept: application/html

Request header - default example (using urlencoded)

Region_capture_80.png

 

Success

HTTP: 200

A success will redirect the user automatically into the bookshelf account and book specified including the other specific parameters around deep link or presentation method.

Failure

HTTP Code: 403 Forbidden

See full list of error codes and messages. 

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.