Template variables

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

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. Within the GUI, they can be used in portal modules and within the body of content items in courses.

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

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