Skip navigation
 

Template variables
Added by George Kroner, last edited by George Kroner on 06 Nov 2007 04:18 AM
(None)

Please feel free to contribute to this tutorial by clicking the Edit->Edit this page link

Template variables allow for integration with other systems by exposing information about the user's context in a way that makes creating URLs to pass information to these systems easy.
Tutorial Contents

About template variables

The context passing APIs allow the Blackboard Learning System to pass data to other systems by embedding data into a URL. Context passing is especially useful when implementing Building Blocks that require content from Blackboard Learning System to generate a URL.

What template variables are

Template variables are represented by a series of values given a special syntax. This syntax is @X@object.attribute@X@. When used, these variables are expanded when rendered into their corresponding values.

How template variables work

There are several ways to use context variables when designing your Blackboard integration.

Course Document expansion

When rendered in a course document, variables will be expanded as the content is displayed. The benefit of this approach is that no intermediate step is required between the display of the template and navigating the link.

Deferred expansion

A slightly different syntax can be used if Course Document expansion is not desired Instead, have the link reference the URL /webapps/blackboard/launch_external.jsp and include a URL template in the url parameter.

Below is an example of a deferred expansion URL:
/webapps/blackboard/launch_external.jsp?encrypt=y&url=http://example.com/page?uid=@X@user.user_id@X@
The benefit of this approach is that there is an intermediate step to invoke the launch_external.jsp. This allows the developer to specify that the URL should be encrypted. This step creates a temporary key that external systems (with live database access to the Blackboard Learning System), can use to verify requests. More information on encrypting this information can be found below. Navigate to /blackboard/webapps/blackboard/launch_external.jsp on your development server to see what happens in this JSP.

Run-time expansion

Developers can also have provided templates expanded at runtime by the Session object. The templates are the same, but instead are processed in the context of a method call.

BbSession bbSession = BbServiceManager.getSessionManagerService().getSession( request );
//blackboard.platform.session.BbSession.encodeTemplateURL()
String encodedUrl = bbSession.encodeTemplateUrl( request, request.getParameter("target") );

Using context variables

Context item Context variable Java equivalent Example output
User external person key @X@user.batch_uid@X@ blackboard.data.user.User.getBatchUid() 123-45-6789
User username (user id) @X@user.id@X@ blackboard.data.user.User.getUserName() jsmith
User primary key identifier @X@user.pk_string@X@ blackboard.data.user.User.getId().toExternalString() _521_1
User locale @X@user.locale@X@ blackboard.platform.BbServiceManager.
getLocaleManager().getLocale().getLocale() 		 
User system role(s) @X@user.role@X@ blackboard.data.user.User.getSystemRole() System Roles
C- Course Administrator
U- Guest
N- None
O- Observer
Y- Community Administrator
R- Support
Z- System Admin
H- System Support
A- User Administrator
User primary institution role @X@user.institution_role@X@ or @X@user.primary_institution_role@X@ blackboard.data.user.User.getPortalRole().getRoleID() student
User secondary institution role(s) @X@user.secondary_institution_role@X@ blackboard.persist.role.PortalRoleDbLoader
.loadSecondaryRolesByUserId( blackboard.data.user.User.getId()) 		student,faculty
Course membership role @X@membership.role@X@ blackboard.data.course.CourseMembership.getRole() Course/Organization Roles
B- Course Builder/Organization Builder
G- Grader/Grader
U- Guest/Guest
P- Instructor/Leader
S- Student/Participant
T- Teacher's Assistant/Assistant
Course external course key @X@course.batch_uid@X@ blackboard.data.course.Course.getBatchUid() ABC123ABC
Course course id @X@course.id@X@ blackboard.data.course.Course.getCourseId() BIO101
Course primary key identifier @X@course.pk_string@X@ blackboard.data.course.Course.getId().toExternalString()  
Course URL @X@course.url@X@ "/courses/1/" +
blackboard.data.course.Course.getCourseId() + "/" 		/courses/1/BIO101/
Course membership role @X@course.role@X@ blackboard.data.course.CourseMembership.getRole()toExternalString() student
Course locale @X@course.locale@X@ blackboard.data.course.Course.getLocale()  
Content primary key identifier @X@content.id@X@ or @X@content.pk_string@X@ blackboard.data.content.Content.getId().toExternalString() _23_1
Content URL @X@content.url@X@ "/courses/1/" + blackboard.data.content.Content.getCourseId() + "/content/" + blackboard.data.content.Content.getId().toExternalString() /courses/1/BOB101/content/_221_1
Request UUID @X@request.id@X@   35853280-A77A-11D8-83D5-9CAA2FE644E1
Request locale @X@request.locale@X@ blackboard.platform.BbServiceManager.getLocaleManager()
.getLocale().getLocale() 		 
Request return URL @X@request.return@X@   http:/localhost/webapps/
bbgs-bbqa-context-bb_bb60/
tool_1/tool.jsp?course_id=_2_1
System host name @X@system.site_id@X@ blackboard.platform.context.ContextManagerFactory.getInstance().
getContext().getVirtualHost().getHostname() 		 
System locale @X@system.locale@X@ blackboard.platform.BbServiceManager.
getLocaleManager().getLocale().getLocale() 		 
Session ID @X@session.id@X@ blackboard.platform.session.BbSession.getBbSessionIdMd5() 8f14e45fceea167a5a36dedd4bea2543

Securing the context while passing to an external system

To protect the transfer of possibly sensitive data as part of a context passing function, context encryption using Cryptix (Blowfish) can be used to secure the data transfer instead of the standard Base64Encoding.

After downloading a context encryption key it must be made available to the URL that will receive encrypted data through context-passing. The code example below shows how to programmatically decipher encrypted context data on the external URL when it is passed. The object indicated by the target URL (in this case, index.jsp) could decrypt the context as follows (importing blackboard.client.decryption.*)

See the chapter titled "Authentication and Integration" in the Blackboard Learning System Administrator Manual to learn more about how to manage the context encryption keys.

String context = request.getParameter("context");
//if isEncryptionEnabled = false, base 64 encoding will be used instead of encryption
boolean isEncryptionEnabled = true;
ContextDecryptor bfd = ContextDecryptorFactory.getContextDecryptor(isEncryptionEnabled );

// retrieve the Blackboard encryption key as a File or InputStream
File key = new File( strKeyLocation );
// or InputStream key = // implementation detail...
// to simply decrypt the context string

String decryptedContext = bfd.decrypt( context, key );
// or, to get a HashMap of all key-value pairs
HashMap map = bfd.parseEncryptedContext( context, key );

// then search the HashMap for an expected value, and continue.
if (map.containsKey( "user" )
{
  // execute...
}

Resources

Blackboard codes die je kan gebruiken in 6.3

Adaptavist Theme Builder Powered by Atlassian Confluence

By accessing the Knowledge Base, you agree to the following: Blackboard makes no representations or warranties as to the accuracy of any information in the Knowledge Base. Blackboard is not responsible in any way for information provided to the Knowledge Base by third parties. Information in the Knowledge Base is not documentation for any Blackboard product. Nothing in the Knowledge Base shall be deemed to modify your license in any way to any Blackboard product. Blackboard reserves the right to use your name and the name of your institution in reference to any information submitted by you to the Knowledge Base. Blackboard may modify, distribute, republish in any format, delete, incorporate or use in any way the information that you contribute to the Knowledge Base.