Page Comparison - Template variables (v.15 vs v.16) - EduGarage (Blackboard Developers Network)

Access Keys:: Skip to content (Access Key - 0)

     ViewThis pageNormal view
  Printable view
  
 Other pagesHome page
  Dashboard
   
  News
  Recent updates
  RSS feed builder
   
  Index
  Site map
  Labels
   
  Attachments index
  
  People Directory
 
  
 AccountLog in
  Change Password
   
  History
  
 
  
Show comments (8)


Log In

    


 
                                  Home >
Tutorials >
… >
Template variables >
Information >
Page Comparison
 
                            
                        
                    
                    
                        
                            
                                
                                    
                                        
                                            
    
    
        
    
    
                    
    





    
    
    
    
    


    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
        























        
        
        
        
        
        









                     
    
    

                
                
                    
                    
                    
                        
                            
                                
                                Version 15 by George Kroner
 on 22 Apr 2011 01:12 AM.
                                

                            
                                                                                    
                                
                                                                                << Changes from 14 to 15 
                                

                            
                                                    
                    
                    compared with
                    
                        
                            
                                

                                                                            Version 16 by Wayne Twitchell
 on 29 Apr 2011 03:39 PM.
                                    
                                

                                                            
                                                                                    
                                
                                                                        Changes from 16 to 17 >>
                                

                            
                                                    
                    
                    
                    
                

            
            
                Key

                This line was removed.
                This word was removed. This word was added.
                This line was added.
            
            

              
      Comment:
      

  


                            Changes (31)
                View Page History

                                                    
    

            
            ...
{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\@. @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@ 

            /webapps/blackboard/launch_external.jsp?encrypt=y&target=[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\@ @X@user.batch_uid@X@ | blackboard.data.user.User.getBatchUid() | 123-45-6789 | 

            | User username (user id) | \@X\@user.id\@X\@ @X@user.id@X@ | blackboard.data.user.User.getUserName() | jsmith | 

            | User full name | \@X\@user.full_name\@X\@ @X@user.full_name@X@ | the BbLocale.Name.LONG format | John Smith |   

            | User primary key identifier | \@X\@user.pk_string\@X\@ @X@user.pk_string@X@ | blackboard.data.user.User.getId().toExternalString() | \_521_1 | 

            | User locale | \@X\@user.locale\@X\@ @X@user.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | User system role(s) | \@X\@user.role\@X\@ @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\@ @X@user.institution_role@X@ or \@X\@user.primary_institution_role\@X\@ @X@user.primary_institution_role@X@ | blackboard.data.user.User.getPortalRole().getRoleID() | student | 

            | User secondary institution role(s) | \@X\@user.secondary_institution_role\@X\@ @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\@ @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\@ @X@course.batch_uid@X@ | blackboard.data.course.Course.getBatchUid() | ABC123ABC | 

            | Course course id | \@X\@course.id\@X\@ @X@course.id@X@ | blackboard.data.course.Course.getCourseId() | BIO101 | 

            | Course name | \@X\@course.course_name\@X\@ @X@course.course_name@X@ | | | 

            | Course primary key identifier | \@X\@course.pk_string\@X\@ @X@course.pk_string@X@ | blackboard.data.course.Course.getId().toExternalString() | | 

            | Course URL | \@X\@course.url\@X\@ @X@course.url@X@ | "/courses/1/" + \\ 

            blackboard.data.course.Course.getCourseId() + "/" | /courses/1/BIO101/ | 

            | Course membership role | \@X\@course.role\@X\@ @X@course.role@X@ | blackboard.data.course.CourseMembership.getRole()toExternalString() | student | 

            | Course locale | \@X\@course.locale\@X\@ @X@course.locale@X@ | blackboard.data.course.Course.getLocale() | | 

            | Content primary key identifier | \@X\@content.id\@X\@ @X@content.id@X@ or \@X\@content.pk_string\@X\@ @X@content.pk_string@X@ | blackboard.data.content.Content.getId().toExternalString() | \_23_1 | 

            | Content URL | \@X\@content.url\@X\@ @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|http://www.opengroup.org/onlinepubs/009629399/apdxa.htm] | \@X\@request.id\@X\@ @X@request.id@X@ | | 35853280-A77A-11D8-83D5-9CAA2FE644E1 | 

            | Request locale | \@X\@request.locale\@X\@ @X@request.locale@X@ | blackboard.platform.BbServiceManager.getLocaleManager() \\ 

            .getLocale().getLocale() | | 

            | Request return URL | \@X\@request.return\@X\@ @X@request.return@X@ | | http:/localhost/webapps/ \\ 

            bbgs-bbqa-context-bb_bb60/\\ 

            tool_1/tool.jsp?course_id=_2_1 | 

             tool_1/tool.jsp?course_id=_2_1 | 

            | System host name | \@X\@system.site_id\@X\@ @X@system.site_id@X@ | blackboard.platform.context.ContextManagerFactory.getInstance(). \\ 

            getContext().getVirtualHost().getHostname() | | 

            | System locale | \@X\@system.locale\@X\@ @X@system.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | Session ID | \@X\@session.session_id\@X\@ @X@session.session_id@X@ | blackboard.platform.session.BbSession.getBbSessionIdMd5() | 8f14e45fceea167a5a36dedd4bea2543 | 

             
---- 

            ...
{anchor:SECURING} 
 
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]
     ViewThis pageNormal view
  Printable view
  
 Other pagesHome page
  Dashboard
   
  News
  Recent updates
  RSS feed builder
   
  Index
  Site map
  Labels
   
  Attachments index
  
  People Directory
 
  
 AccountLog in
  Change Password
   
  History
  
 
  
Show comments (8)


Log In

    


 
                                  Home >
Tutorials >
… >
Template variables >
Information >
Page Comparison
     ViewThis pageNormal view
  Printable view
  
 Other pagesHome page
  Dashboard
   
  News
  Recent updates
  RSS feed builder
   
  Index
  Site map
  Labels
   
  Attachments index
  
  People Directory
 
  
 AccountLog in
  Change Password
   
  History
  
 
  
Show comments (8)


Log In
     ViewThis pageNormal view
  Printable view
  
 Other pagesHome page
  Dashboard
   
  News
  Recent updates
  RSS feed builder
   
  Index
  Site map
  Labels
   
  Attachments index
  
  People Directory
 
  
 AccountLog in
  Change Password
   
  History
  
 
  
Show comments (8)


Log In
   Home >
Tutorials >
… >
Template variables >
Information >
Page Comparison
                                 Version 15 by George Kroner
 on 22 Apr 2011 01:12 AM.
                                

                            
                                                                                    
                                
                                                                                << Changes from 14 to 15 
                                

                            
                                                    
                    
                    compared with
                    
                        
                            
                                

                                                                            Version 16 by Wayne Twitchell
 on 29 Apr 2011 03:39 PM.
                                    
                                

                                                            
                                                                                    
                                
                                                                        Changes from 16 to 17 >>
                                

                            
                                                    
                    
                    
                    
                

            
            
                Key

                This line was removed.
                This word was removed. This word was added.
                This line was added.
            
            

              
      Comment:
      

  


                            Changes (31)
                View Page History

                                                    
    

            
            ...
{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\@. @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@ 

            /webapps/blackboard/launch_external.jsp?encrypt=y&target=[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\@ @X@user.batch_uid@X@ | blackboard.data.user.User.getBatchUid() | 123-45-6789 | 

            | User username (user id) | \@X\@user.id\@X\@ @X@user.id@X@ | blackboard.data.user.User.getUserName() | jsmith | 

            | User full name | \@X\@user.full_name\@X\@ @X@user.full_name@X@ | the BbLocale.Name.LONG format | John Smith |   

            | User primary key identifier | \@X\@user.pk_string\@X\@ @X@user.pk_string@X@ | blackboard.data.user.User.getId().toExternalString() | \_521_1 | 

            | User locale | \@X\@user.locale\@X\@ @X@user.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | User system role(s) | \@X\@user.role\@X\@ @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\@ @X@user.institution_role@X@ or \@X\@user.primary_institution_role\@X\@ @X@user.primary_institution_role@X@ | blackboard.data.user.User.getPortalRole().getRoleID() | student | 

            | User secondary institution role(s) | \@X\@user.secondary_institution_role\@X\@ @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\@ @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\@ @X@course.batch_uid@X@ | blackboard.data.course.Course.getBatchUid() | ABC123ABC | 

            | Course course id | \@X\@course.id\@X\@ @X@course.id@X@ | blackboard.data.course.Course.getCourseId() | BIO101 | 

            | Course name | \@X\@course.course_name\@X\@ @X@course.course_name@X@ | | | 

            | Course primary key identifier | \@X\@course.pk_string\@X\@ @X@course.pk_string@X@ | blackboard.data.course.Course.getId().toExternalString() | | 

            | Course URL | \@X\@course.url\@X\@ @X@course.url@X@ | "/courses/1/" + \\ 

            blackboard.data.course.Course.getCourseId() + "/" | /courses/1/BIO101/ | 

            | Course membership role | \@X\@course.role\@X\@ @X@course.role@X@ | blackboard.data.course.CourseMembership.getRole()toExternalString() | student | 

            | Course locale | \@X\@course.locale\@X\@ @X@course.locale@X@ | blackboard.data.course.Course.getLocale() | | 

            | Content primary key identifier | \@X\@content.id\@X\@ @X@content.id@X@ or \@X\@content.pk_string\@X\@ @X@content.pk_string@X@ | blackboard.data.content.Content.getId().toExternalString() | \_23_1 | 

            | Content URL | \@X\@content.url\@X\@ @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|http://www.opengroup.org/onlinepubs/009629399/apdxa.htm] | \@X\@request.id\@X\@ @X@request.id@X@ | | 35853280-A77A-11D8-83D5-9CAA2FE644E1 | 

            | Request locale | \@X\@request.locale\@X\@ @X@request.locale@X@ | blackboard.platform.BbServiceManager.getLocaleManager() \\ 

            .getLocale().getLocale() | | 

            | Request return URL | \@X\@request.return\@X\@ @X@request.return@X@ | | http:/localhost/webapps/ \\ 

            bbgs-bbqa-context-bb_bb60/\\ 

            tool_1/tool.jsp?course_id=_2_1 | 

             tool_1/tool.jsp?course_id=_2_1 | 

            | System host name | \@X\@system.site_id\@X\@ @X@system.site_id@X@ | blackboard.platform.context.ContextManagerFactory.getInstance(). \\ 

            getContext().getVirtualHost().getHostname() | | 

            | System locale | \@X\@system.locale\@X\@ @X@system.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | Session ID | \@X\@session.session_id\@X\@ @X@session.session_id@X@ | blackboard.platform.session.BbSession.getBbSessionIdMd5() | 8f14e45fceea167a5a36dedd4bea2543 | 

             
---- 

            ...
{anchor:SECURING} 
 
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]
                                 Version 15 by George Kroner
 on 22 Apr 2011 01:12 AM.
                                

                            
                                                                                    
                                
                                                                                << Changes from 14 to 15 
                                

                            
                                                    
                    
                    compared with
                    
                        
                            
                                

                                                                            Version 16 by Wayne Twitchell
 on 29 Apr 2011 03:39 PM.
                                    
                                

                                                            
                                                                                    
                                
                                                                        Changes from 16 to 17 >>
                                

                            
                                                    
                    
                    
                    
                

            
            
                Key

                This line was removed.
                This word was removed. This word was added.
                This line was added.
            
            

              
      Comment:
      

  


                            Changes (31)
                View Page History

                                                    
    

            
            ...
{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\@. @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@ 

            /webapps/blackboard/launch_external.jsp?encrypt=y&target=[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\@ @X@user.batch_uid@X@ | blackboard.data.user.User.getBatchUid() | 123-45-6789 | 

            | User username (user id) | \@X\@user.id\@X\@ @X@user.id@X@ | blackboard.data.user.User.getUserName() | jsmith | 

            | User full name | \@X\@user.full_name\@X\@ @X@user.full_name@X@ | the BbLocale.Name.LONG format | John Smith |   

            | User primary key identifier | \@X\@user.pk_string\@X\@ @X@user.pk_string@X@ | blackboard.data.user.User.getId().toExternalString() | \_521_1 | 

            | User locale | \@X\@user.locale\@X\@ @X@user.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | User system role(s) | \@X\@user.role\@X\@ @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\@ @X@user.institution_role@X@ or \@X\@user.primary_institution_role\@X\@ @X@user.primary_institution_role@X@ | blackboard.data.user.User.getPortalRole().getRoleID() | student | 

            | User secondary institution role(s) | \@X\@user.secondary_institution_role\@X\@ @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\@ @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\@ @X@course.batch_uid@X@ | blackboard.data.course.Course.getBatchUid() | ABC123ABC | 

            | Course course id | \@X\@course.id\@X\@ @X@course.id@X@ | blackboard.data.course.Course.getCourseId() | BIO101 | 

            | Course name | \@X\@course.course_name\@X\@ @X@course.course_name@X@ | | | 

            | Course primary key identifier | \@X\@course.pk_string\@X\@ @X@course.pk_string@X@ | blackboard.data.course.Course.getId().toExternalString() | | 

            | Course URL | \@X\@course.url\@X\@ @X@course.url@X@ | "/courses/1/" + \\ 

            blackboard.data.course.Course.getCourseId() + "/" | /courses/1/BIO101/ | 

            | Course membership role | \@X\@course.role\@X\@ @X@course.role@X@ | blackboard.data.course.CourseMembership.getRole()toExternalString() | student | 

            | Course locale | \@X\@course.locale\@X\@ @X@course.locale@X@ | blackboard.data.course.Course.getLocale() | | 

            | Content primary key identifier | \@X\@content.id\@X\@ @X@content.id@X@ or \@X\@content.pk_string\@X\@ @X@content.pk_string@X@ | blackboard.data.content.Content.getId().toExternalString() | \_23_1 | 

            | Content URL | \@X\@content.url\@X\@ @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|http://www.opengroup.org/onlinepubs/009629399/apdxa.htm] | \@X\@request.id\@X\@ @X@request.id@X@ | | 35853280-A77A-11D8-83D5-9CAA2FE644E1 | 

            | Request locale | \@X\@request.locale\@X\@ @X@request.locale@X@ | blackboard.platform.BbServiceManager.getLocaleManager() \\ 

            .getLocale().getLocale() | | 

            | Request return URL | \@X\@request.return\@X\@ @X@request.return@X@ | | http:/localhost/webapps/ \\ 

            bbgs-bbqa-context-bb_bb60/\\ 

            tool_1/tool.jsp?course_id=_2_1 | 

             tool_1/tool.jsp?course_id=_2_1 | 

            | System host name | \@X\@system.site_id\@X\@ @X@system.site_id@X@ | blackboard.platform.context.ContextManagerFactory.getInstance(). \\ 

            getContext().getVirtualHost().getHostname() | | 

            | System locale | \@X\@system.locale\@X\@ @X@system.locale@X@ | blackboard.platform.BbServiceManager. \\ 

            getLocaleManager().getLocale().getLocale() | | 

            | Session ID | \@X\@session.session_id\@X\@ @X@session.session_id@X@ | blackboard.platform.session.BbSession.getBbSessionIdMd5() | 8f14e45fceea167a5a36dedd4bea2543 | 

             
---- 

            ...
{anchor:SECURING} 
 
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]
-                                Version 15 by George Kroner
 on 22 Apr 2011 01:12 AM.
                                

                            
                                                                                    
                                
                                                                                << Changes from 14 to 15 
                                

                            
                                                    
                    
                    compared with
                    
                        
                            
                                

                                                                            Version 16 by Wayne Twitchell
 on 29 Apr 2011 03:39 PM.
                                    
                                

                                                            
                                                                                    
                                
                                                                        Changes from 16 to 17 >>
+                Key

                This line was removed.
                This word was removed. This word was added.
                This line was added.
-                                Version 15 by George Kroner
 on 22 Apr 2011 01:12 AM.
                                

                            
                                                                                    
                                
                                                                                << Changes from 14 to 15
+                                                                            Version 16 by Wayne Twitchell
 on 29 Apr 2011 03:39 PM.
                                    
                                

                                                            
                                                                                    
                                
                                                                        Changes from 16 to 17 >>
 ...
{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\@. @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@
+/webapps/blackboard/launch_external.jsp?encrypt=y&target=[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\@ @X@user.batch_uid@X@ | blackboard.data.user.User.getBatchUid() | 123-45-6789 |
 | User username (user id) | \@X\@user.id\@X\@ @X@user.id@X@ | blackboard.data.user.User.getUserName() | jsmith |
 | User full name | \@X\@user.full_name\@X\@ @X@user.full_name@X@ | the BbLocale.Name.LONG format | John Smith |
 | User primary key identifier | \@X\@user.pk_string\@X\@ @X@user.pk_string@X@ | blackboard.data.user.User.getId().toExternalString() | \_521_1 |
 | User locale | \@X\@user.locale\@X\@ @X@user.locale@X@ | blackboard.platform.BbServiceManager. \\
 getLocaleManager().getLocale().getLocale() | |
 | User system role(s) | \@X\@user.role\@X\@ @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\@ @X@user.institution_role@X@ or \@X\@user.primary_institution_role\@X\@ @X@user.primary_institution_role@X@ | blackboard.data.user.User.getPortalRole().getRoleID() | student |
 | User secondary institution role(s) | \@X\@user.secondary_institution_role\@X\@ @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\@ @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\@ @X@course.batch_uid@X@ | blackboard.data.course.Course.getBatchUid() | ABC123ABC |
 | Course course id | \@X\@course.id\@X\@ @X@course.id@X@ | blackboard.data.course.Course.getCourseId() | BIO101 |
 | Course name | \@X\@course.course_name\@X\@ @X@course.course_name@X@ | | |
 | Course primary key identifier | \@X\@course.pk_string\@X\@ @X@course.pk_string@X@ | blackboard.data.course.Course.getId().toExternalString() | |
 | Course URL | \@X\@course.url\@X\@ @X@course.url@X@ | "/courses/1/" + \\
 blackboard.data.course.Course.getCourseId() + "/" | /courses/1/BIO101/ |
 | Course membership role | \@X\@course.role\@X\@ @X@course.role@X@ | blackboard.data.course.CourseMembership.getRole()toExternalString() | student |
 | Course locale | \@X\@course.locale\@X\@ @X@course.locale@X@ | blackboard.data.course.Course.getLocale() | |
 | Content primary key identifier | \@X\@content.id\@X\@ @X@content.id@X@ or \@X\@content.pk_string\@X\@ @X@content.pk_string@X@ | blackboard.data.content.Content.getId().toExternalString() | \_23_1 |
 | Content URL | \@X\@content.url\@X\@ @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|http://www.opengroup.org/onlinepubs/009629399/apdxa.htm] | \@X\@request.id\@X\@ @X@request.id@X@ | | 35853280-A77A-11D8-83D5-9CAA2FE644E1 |
 | Request locale | \@X\@request.locale\@X\@ @X@request.locale@X@ | blackboard.platform.BbServiceManager.getLocaleManager() \\
 .getLocale().getLocale() | |
 | Request return URL | \@X\@request.return\@X\@ @X@request.return@X@ | | http:/localhost/webapps/ \\
 bbgs-bbqa-context-bb_bb60/\\
-tool_1/tool.jsp?course_id=_2_1 |
+ tool_1/tool.jsp?course_id=_2_1 |
 | System host name | \@X\@system.site_id\@X\@ @X@system.site_id@X@ | blackboard.platform.context.ContextManagerFactory.getInstance(). \\
 getContext().getVirtualHost().getHostname() | |
 | System locale | \@X\@system.locale\@X\@ @X@system.locale@X@ | blackboard.platform.BbServiceManager. \\
 getLocaleManager().getLocale().getLocale() | |
 | Session ID | \@X\@session.session_id\@X\@ @X@session.session_id@X@ | blackboard.platform.session.BbSession.getBbSessionIdMd5() | 8f14e45fceea167a5a36dedd4bea2543 |
 ----
 ...
{anchor:SECURING} 
 
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]
             Adaptavist Theme Builder (4.1.3) Powered by Atlassian Confluence 3.3, the Enterprise Wiki

Copyright © 1997-2011. Blackboard Inc. All rights reserved. Blackboard, the Blackboard logo, BbWorld, Blackboard Learn, Blackboard Transact, Blackboard Connect, Blackboard Mobile, the Blackboard Outcomes System, Behind the Blackboard, and Connect-ED are trademarks or registered trademarks of Blackboard Inc. or its subsidiaries in the United States and/or other countries. U.S. Patent Numbers: 6,988,138; 7,493,396, 7,558,853.