{info:title=Please feel free to contribute to this tutorial by clicking the Edit->Edit this page link} {info} {section} {column:width=50%} 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. {column} {column:width=50%} {panel:borderStyle=solid|title=Tutorial Contents} * [About template variables|#ABOUT] ** [What they are|#WHATTHEYARE] ** [How they work|#HOWTHEYWORK] * [Using template variables|#USING] ** [Securing the context values|#SECURING] * [Resources|#RESOURCES] {panel} {column} {section}{anchor:ABOUT}
h2. 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.
---- {anchor:WHATTHEYARE}
h3. 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. Within the GUI, they can be used in portal modules and within the body of content items in courses.
---- {anchor:HOWTHEYWORK}
h3. How template variables work
There are several ways to use context variables when designing your Blackboard integration.
h4. 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.
h4. 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.
h4. 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. {code:Java|borderStyle=solid} BbSession bbSession = BbServiceManager.getSessionManagerService().getSession( request ); //blackboard.platform.session.BbSession.encodeTemplateURL() String encodedUrl = bbSession.encodeTemplateUrl( request, request.getParameter("target") ); {code}
---- {anchor:USING}
h2. 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 full name | \@X\@user.full_name\@X\@ | the BbLocale.Name.LONG format | John Smith | | 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 |
h3. 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. {code:Java|borderStyle=solid} 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... } {code}
---- {anchor:RESOURCES}
h2. Resources
[Blackboard codes die je kan gebruiken in 6.3|http://www.e-learn.nl/2006/07/26/p124]
