Installation and Runtime Flows

High Level Installation Flow

1. Your application will ask the user for the URL of the Blackboard Learn server and the optional tool registration password as well as a separate shared secret for this Blackboard Learn server inside your application. The new installation flow involves getting information such as the URL for the server from the Tool Consumer Profile.
2. Your application will then call the ContextWS.registerTool method with your application's XML descriptor of your proxy tool.
3. The Blackboard Learn System Administrator will then login to their system and make the tool 'available'. They will also set the shared secret on the webservice agent for your tool - this will enable tool specific logins.

Runtime Flow

1. A Blackboard Learn user clicks a link which is the passthrough to the tool.
2. If you have configured a Ping request then Blackboard Learn sends a simple-xml-response to confirm that the tool is active. If the ping request fails then the user is directed to an error page.
3. The user's browser will then POST all the arguments applicable to the specific request as well as a MAC (see Proxy Tool SSO) to the proxy tool's configured URL.
4. The proxy tool is responsible for validating the MAC with all of the posted arguments. This is to assure that the parameters received are correct (i.e. the user has not intercepted at the browser and changed anything).
5. Continue as appropriate for the touch point. (Refer to the XML description for details on what to expect at each touch point.) Refer to Maintaining Look-and-Feel inside Proxy Server for directions on how to get an appropriate stylesheet for your pages.

Web Service Support

There are two modes of Web Service operation that can be used in the proxy tool:

1. Connect as the Blackboard Learn user currently logged in
2. Connect as 'your tool'

If you wish to perform actions on behalf of the current user then use the first approach. If you need to perform raised-privilege actions (i.e. update the Grade Center with a student's mark) then use your tool's authentication. One of the SSO parameters passed through each touch point is a 'ticket' for the current user. This can be used in the ContextWS.ticketLogin() method to authenticate a webservice session for the current user.

Authenticating Proxy Tool Requests

Refer to the sample proxy server code for a recommended implementation of the authentication logic for a request to your proxy server from Blackboard Learn (or from the browser as redirected by Blackboard Learn). This works in conjunction with GenericParameters.java which builds up the required data from the request. Apply this validation to every authenticated request to make sure that the data received is the data Blackboard Learn intended to send.
While the sample source code is the best description of the logic to be applied here, a text description can be found here.

Note that while the rule is that 100% of the parameters (except mac) are included in the generation of the mac, there are a few that will be excluded. Refer to the sample code for the exclusion list.

Deferred Event Delivery

Events are deferred if they are generated at a point in time when the logically available proxy server is physically not available, perhaps shut down for maintenance. These deferred events will be sent the next time any action occurs which requires communication with the proxy tool and when the server is physically available.

There are a few events which may not be delivered at the same time as the event occurs. Currently this only applies to a few events. Each applicable event will be noted in the documentation for that event. The following situations result in the deferred delivery of an event:

1. Restoring/importing a course which uses a proxy tool that is not installed.
2. Restoring/importing a course which uses a proxy tool that is installed but not available.
3. Restoring/importing a course which uses a proxy tool that is installed and available but not responding to requests.
4. Copying a course which uses a proxy tool that is installed but not available.
5. Copying a course which uses a proxy tool that is installed and available but not responding to requests.
6. Copying a content item (without delete) whose content handler is a proxy tool that is installed but not available.
7. Copying a content item (without delete) whose content handler is a proxy tool that is installed and available but not responding to requests.
8. Copying a content item (with delete, to a different course) whose content handler is a proxy tool that is installed but not available.
9. Copying a content item (with delete, to a different course) whose content handler is a proxy tool that is installed and available but not responding to requests.

The deferred events are sent to the proxy tool when it is installed (if required) and made available. As part of this action, any deferred events are sent to the proxy tool.

There is a chance that you may receive deferred events multiple times; the proxy tool must be able to deal with this. The scenario that would produce this is as follows: T0: Your server is down T1: Events A, B, C are deferred T2: Your server is brought up again T3: The administrator saves the tool to activate sending the deferred events T4: After sending event A successfully, your server goes down again. At this point we will stop attempting to send the deferred events, but later on when we try to send them we will start with event A again.

If the proxy tool uses tool settings then the deferred event will record the tool settings appropriate for the event at the time it was originally attempted to be sent. When it is eventually sent those original settings will be used regardless of the current settings at the time of the actual send.

Deploying Multiple Concurrent Versions

It is possible to run multiple versions of a proxy tool server against the same Blackboard Learn instance. Since many components of the proxy tool are uniquely identified within Blackboard Learn this is not possible without some adjustments. To execute run-in-parallel mode, change these values to be unique within a different instance of your tool:

• program id (i.e. add a '-trial' to the end of the name)
• content handler handle (again, try adding -trial to the end of the handle)

Optional changes would be to alter these fields to make it easier to distinguish between the production and trial versions of your tool:

• content-handler name
• link name
• link description

Generic Proxy Tool Request Arguments

All authenticated requests to your proxy tool server will contain these arguments. Granted, in some cases these arguments do not apply, but you should look for them in all requests (but it is not an immediate failure if they are not found). You can refer to GenericParameters.java for a sample of how we're reading these parameters.

• ourguid - This is the GUID returned to you as part of tool registration.
• tcbaseurl - This is the basic scheme/host/port portion of the URL into the Tool Consumer for the current user session. Use this when generating the returnurl as well as when generating the css url.
• returnurl - This is an appropriate return-to-academic suite URL for the given operation. Once you have finished the workflow within your tool you should forward the user's browser to this URL. The value specified here will be relative to the tcbaseurl.
• locale - This is the current locale for the user's session. It is in java's string representation of a locale (lang_COUNTRY_variant). You should adjust the language in your tool's UI to reflect this locale.
• direction - This is the current html direction for the user's session. You should adjust the direction in your tool's UI to reflect this value : <html dir="(direction)"... - the value will be either ltr or rtl.
• timestamp - This is a timestamp field. It is used in the validation of the request.
• ticket - This is a ticket representing a webservice session for the currently logged in user. It can be used with the ContextWS.ticketLogin() method to get a valid webservice session. When you want to perform operations as the currently logged in user you must use this method. The ticket is only valid for a short time (currently 5 minutes) after it is generated so if you do not use it right away it may not be valid anymore. For example, if you plan on going through a series of pages with the user before you end up needing a webservice session for the user then you must do the ticketLogin first, before returning pages to the end user, or they might take 'too long' to fill in the pages resulting in the ticket not being valid anymore. Failure to follow this pattern could result in use cases "working in dev but not in production" because you might click through too quickly while testing your tool.
• userid - This is the userid of the current user. It is in an internal-id format specific to Academic Suite and is used in various calls into webservices to identify the user.
• role - This is the role of the current user within the current context. Possible values for this field are: COURSE:INSTRUCTOR, COURSE:TEACHING_ASSISTANT, COURSE:COURSE_BUILDER, COURSE:GRADER, COURSE:STUDENT, COURSE:GUEST, SYSTEM:ADMIN, and SYSTEM:NONE.
  The COURSE: roles will be sent while the user is within a course context. The SYSTEM: roles are sent outside (i.e. on a portal tab not a course tab).
• tcrole - This is the role of the current user within the current context. Currently this is identical to the role field for SYSTEM roles and is everything after the : for COURSE roles, but the intention is for the role field to be restricted to whatever we define as LTI roles in the LTI specification and this field is going to be defined as 'whatever we want' in the spec so this will reflect a larger range of potential roles eventually.
• mac - This is the generated MAC for the current request. Refer to authenticating requests for details on how to use this.
• ...settings... - If the tool has used the settings service methods (UtilWS.saveSetting()) then any settings it has stored
  will be passed as generic arguments. Settings can be set at the system, course, or content item level. System settings will be sent to all operations on the proxy server. Course settings will be sent to all operations within a course. Content item settings will be sent for operations on a specific content item. Each setting will be passed using the key exactly as it was set in the saveSetting call. This means that it is the responsibility of the proxy tool developer to make sure they are not creating settings with names that conflict with any of the generic or action-specific arguments.

Content Exchange and Proxy Tools

The following Use Cases are outlined here:

When a content item is created, the Proxy Tool provides an External ID during the creation. This is hidden inside the text body of the content item as a comment <!-ExternalId->. The Content.WS deals with encoding/decoding of this external ID so the remote system sees it separate from the description.

In all of these cases, the content items are copied normally; the framework takes care of generating all the new internal IDs but the content body remains the same. Any gradebook columns that are associated with the content items are copied as required with all Content-ID relationships maintained.

The remote system is responsible for creating new content instances on access by comparing the ID requested and the courseid/contentid/ASguid to the data it has recorded for that piece of content. If it receives a request for a piece of content with different ID information then it is responsible for performing the on-demand copying of the content item and updating it in Blackboard Learn. Refer to the sample code: ProxyUtil.fixContentAfterCopy(...) (and callers).

In addition, if a proxy tool has implemented a Tool Link type, this implements a single pass-through link to the remote system for the course.

Other issues involve point-in-time snapshots. While a proxy tool can try to perform on-access fix-ups (see ProxyUtil.fixContentAfterCopy) if they only focus on the definition (i.e. willing to always lose per-user data), they may not receive the correct version of the data in the copy.

General Failure Note for the Following Use Cases: If a callback has been specified for any of these touch points and it fails then the operation should be rolled back and failed.

Copy Content-Item Inside Course

The rules are:

• Copy content definition
• Copy associated per-user information
• Tool Data is not applicable for this use case

If the callback is not specified then this can be handled on-demand but the point-in-time state is lost. This only works if the user did not choose delete-after-copy OR the user did not implement the content-deleted callback in the proxy tool.

Copy Content-Item Between Courses

The rules are:

• Copy content definition
• Do not copy associated per-user information
• Tool Data is n/a for this use case

If the callback is not specified then this can be handled on-demand but we the point-in-time state is lost. This only works if the user did not choose delete-after-copy OR the user did not implement the content-deleted callback in the proxy tool.

Course Copy - Not an Exact Copy

The rules are:

• Copy content definition
• Do not copy per-user information
• Tool Data should be copied but without any per-user information

If the callback is not specified then the fixContentAfterCopy stage in the proxy server is only be allowed to copy the shell of content items. This means other use cases will fail, or at least not retain all the required information.

If the proxy tool is not available then the copy is performed as though there was no callback configured for the proxy tool. (Same for exact copy.)

The course-copied callback is performed as part of the settingcloneoperator (when the course_application table is copied which is the definition of these course-level tools).

Course Copy - Exact Copy

The rules are:

• Copy content definition
• Copy per-user information
• Tool Data should be copied with all per-user information

If the callback is not specified then the fixContentAfterCopy stage in the proxy server should only be allowed to copy the shell of content items. What this means is that THIS use case will not work (exact copy without a callback configured). The copy is not exact since it is missing all the per-user information.

The course-copied callback is called as part of the settings clone.

Export Course + Import

The rules are:

• Copy content definition
• Do not retain per-user information
• Maintain point-in-time state for the content definition
• Tool Data should be maintained without any per-user information

If the export/import callbacks are not specifed then the content/course can still be exported/imported but the point-in-time state is lost. The default fixContentAfterCopy logic will be allowed to copy the content description on demand which is the default rule for this use case.

If the proxy tool is not available then the export/archive/import/restore is performed as if there was no callback configured for the proxy tool.

FAILURE Exception: For archive and export operations, if the content-exported callback is specified and fails then the operation still succeeds but the detailed log reflects the error that occurred.

Archive Course + Restore

The rules are:

• Copy content definition
• Copy per-user information
• Maintain point-in-time state for the content definition
• Tool Data should be maintained with all per-user information

If the contentexported/imported callbacks are not specified for the content handler then this use case will not work. The fallback logic that must be implemented by the vendor is not allowed to copy per-user data. The default fixContentAfterCopy logic will be allowed to copy the content description "on demand" so we lose point-in-time but do at least get the raw content description which is a partial solution.

Archive Course + Import

The rules are:

• Copy content definition
• Do not copy per-user information
• Maintain point-in-time state for the content definition
• Tool Data should be maintained without any per-user information

If the export/import callbacks are not specified then the content/course can still be archived/imported but the point-in-time state will be lost. The default fixContentAfterCopy logic will be allowed to copy the content description "on demand" which is the default rule.

Archive course + Restore/Import on system connected to a different proxy server

In this case the rules are the same as Archive + Restore with one difference: the proxy server that handled the given content type is different on the new system.

Consider this scenario: Vendor A sells a proxy tool server that is installed on each customer's site. Customer X creates a course with content-handler A, backs it up, and restores it onto Customer Y's system that also uses content-handler A. But content-handler A is served using a different proxy server, one that is installed on Customer Y's site. During the restore, the proxy tool server will not have any knowledge of the declared backup and can therefore not link up the content.

The options for dealing with this situation are:

1. FAD: You can only successfully restore/import with content+userdata/content if your target Blackboard Learn server is using the same proxy tool server as the source Blackboard Learn server. If it is different your content becomes unlinked, or becomes linked to new unpopulated content in the new proxy server.
2. Add a proxy-tool-server-instance-id to the framework. This way a backup can identify itself by backupid and by proxy-tool-server-instance-id.

Exporting Proxy Tool Server Identification

When a course is archived/exported another resource is added to the file if any proxy tool callbacks are included:

<resource bb:file="resXXXXX.dat" bb:title="ProxyTool Instance Data" identifier="resXXXXX" type="course/x-bb-proxytoolinstance" xml:base="resXXXXX" />

The exported resource file will contain a small outline of each proxy tool instance that is defined on the current server:

<?xml version="1.0" encoding="UTF-8"?>
<PROXYTOOLS>
 <PROXYTOOL>
  <BASEURL value="http base url of proxytool"/>
  <VERSION value="version of proxytool in use"/>
  <VENDOR value="vendorid for proxytool"/>
  <PROGRAM value="programid for proxytool"/>
 </PROXYTOOL>
</PROXYTOOLS>

Grade Center Integration Caveat

The sample proxy server includes Grade Center integration for content items. This proxy tool server requires some effort to add error checking, reviews, and other elements to prepare for a full-fledged Grade Center Web Service. This proxy tool server may have to be recreated for future Blackboard Learn releases.

Maintaining Look-and-Feel

While your Proxy Server will be responsible for rendering all of its own user interface pages, it is desirable for them to have the same 'look and feel' as the interface they navigated away from. To accomplish this there is a single css servlet which you can use in your pages to get an appropriate stylesheet for the user's current state. The path to this servlet is identified in the Tool Consumer Profile. You build up the full path using the tcbaseurl from the general arguments and then add on the following attributes:

• user_id (from general arguments)
• course_id (from general arguments if specified)
• ourguid (from general arguments)
• group_id (from Group Tool Action if specified)
• direction (optional: 'rtl' or 'ltr' if specified. If not specified will be based on the user's context. Only use this if you are not honouring the locale and direction passed to you in the original request).

Example Implementation: css.jspf and ProxyUtil.getCssPath

This example generates HTML on the page that looks like this:

<link rel="stylesheet" type="text/css" href="http://your.network.address:80/webapps/blackboard/execute/
proxyCSS?user_id=_1_1&course_id=_603_1">

Proxy Tool XML Elements

Baseurl

Required?: YES (http, https and server-to-server are optional)

This is the root URL of the web site of the proxy tool server. Requests from both the Blackboard Learn servers and all of the end-users who use the tool come through this site.

Specify the http URL; specifying the https URL forces the proxy tool into using SSL via the Blackboard Learn interface. If an https URL is configured then all simple XML response requests will be sent via SSL.

If the SSL handshake fails then an error is logged and the proxy server falls back to the non-ssl URL for the request (the fallback is not shown in the user interface).

A server-to-server URL can also be specified. If the configuration of the network path from the Blackboard Learn server to the proxy tool server is different than the path from the external world to the proxy tool server then specify a different URL for the Blackboard Learn server to use for the simple XML response requests. This alternate URL is attempted first; if it fails due to an SSL handshake error then Blackboard Learn falls back to the https URL (if configured) and then to the http URL if necessary.

If https is not supported then either do not specify the https URL OR specify a http URL. Blackboard Learn does not force the https URL to be https. Conversely, Blackboard Learn does not force the http URL to be http. To force 100% of communication to be SSL then set them both to https URLs.

Do not use fake certificates to test this because the server-server simple XML response requests fail.

All URL values in the other parts of this XML descriptor is relative to this URL.It is also possible to serve up all of the icons from a different server. If this is desired, add two more baseurls of type="icon-http" and "icon-https". If specified then all images are served up relative to this baseurl instead of the standard baseurls (type="http" and type="https").

Bundle

Required?: NO
Authenticated Request?: NO
Request Arguments: locale, ourguid
Sample Implementation: GetBundleAction.java

The bundle url is provides localized language strings to be used for the proxy tool touch-points in Blackboard Learn (i.e. link names, descriptions).

This URL is called without MAC validation instead using the http URL (always - the https baseurl is not used for the bundle). It provides two arguments:

1. locale
2. ourguid

The locale field is the java locale represented as a string: lang_COUNTRY_Variant (i.e. "en_US"). The ourguid field represents the GUID of the Blackboard Learn instance returned during tool registration.

Refer to GetBundleAction.java in the sample proxy tool for a sample implementation and more direction. Some of the things to consider (commented in the code as well) are:

• Have different bundles for each locale.
• Branding per-Blackboard Learn instance (different langauge strings can be served depending on the guid of the Blackboard Learn server).
• Deal with locale fallbacks appropriately in the case where you are asked for a locale you do not support.
• Properly escape non-iso-8859-1 characters. Observe how the sample users Properties.store to ensure the correct character escaping.

Language if bundle not specified

If a bundle URL is not specified then the proxy tool cannot be localized. Instead, all of the name and description fields must contain the raw text to be displayed. Specifying a bundle URL is strongly recommended.

Can Copy

Required?: NO (within a content-handler block)
Default Value: YES
Possible values: YES, NO

If Yes then the content item will have a Copy option in its contextual menu. If No then it will not.

If content copy is supported then the external-id + content-id must be checked on each access and new content items created in the system with a new external id (unless all copies pointing to the same item in the system is desired).

Config Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments
Legal Roles: SYSTEM:ADMIN
Sample Implementation: ConfigAction.java

The config action is presented to the Blackboard Learn System Administrator as an operation to perform for the proxy tool instance. This page provides per-install configuration options to the Blackboard Learn System Administrator.

If a pay-for-use service is being offered then this is a place where payment information can be requested for your service.

Contact Information

Required?: NO

This can be used to convey contact information about the administrator of the specific instance of the proxy tool server. This is not the contact information for the vendor.

Content Copied

Required?: NO
Authenticated Request?: YES
Request Arguments: [Generic Proxy Tool Request Arguments||Generic Proxy Tool Request Arguments], type, oldId, newId, oldCourseId, newCourseId, external_content_id
Sample Implementation: ContentHandlerAction.java ?action=content-copied
Action on Failure return: Copy operation will log an error at this point and continue. The operation as a whole will be reported as being successful though. Event is NOT queued for later delivery.
Action on Communications error: Same as failure (Error logged to file) plus Event is queued up to be delivered later (Deferred Event Delivery).
Action when proxy tool not available: Event queued for later delivery.

This request is called as a simple XML response method. The extra arguments passed are:

• type: exact or shallow
• oldId: The content id of the original piece of content being copied.
• newId: The content id of the new piece of content being created.
• oldCourseId: The course id where the original content lives.
• newCourseId: The course id where the new content lives.
• external_content_id: The external content id specified when the content was originally created.

Refer to ContentHandlerAction.handleContentCopiedAction for sample implementation.

In response to this request a point-in-time copy of the content associated with oldCourseId+oldId +generic.ourguid must be made and associated with newCourseId+newId+generic.ourguid. The new external ID of the new content item cannot be updated because it is being called within a transaction on Blackboard Learn so the new content id does not exist yet. It is not created until after it has been returned.

Refer to OurContentDao.loadContent and ProxyUtil.fixContentAfterCopy for the two places where Blackboard Learn loads the content from the snapshot through a fallback. When the content is first accessed after it has been copied, call ContentWS.saveContent to update the external ID associated with the content in the Blackboard Learn server.

The type that is passed into this request controls how much information that is permitted to copy from the old to the new (the snapshot copy). If it is exact then all of the per-user data is copied. If it is shallow then only the description/configuration of the content item can be copied, not any per-user data.

If any per-course data is stored that is expected to be backed up as part of the course-copied handler and it is required for the content item make sure that the logic reflected in this handler. This is because this content may be copied to another course by itself (i.e. single content item copy and not a full course copy).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

Content Deleted

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, content_id, course_id, external_content_id
Sample Implementation: ContentHandlerAction.java ?action=content-deleted
Action on Failure Return: If called as part of a copy operation then copy operation logs an error at this point and continue. The operation as a whole will be reported as being successful though. The Event is NOT queued to be delivered later. If called as part of a recycle course or delete-item then the result is ignored and the operation continues.
Action on Communications Error: Same as failure (Error logged to file) plus Event is queued up to be delivered later (Deferred Event Delivery).
Action when Proxy Tool not Available: Event is queued up to be delivered later (Deferred Event Delivery).

If specified then this request is called as a simple xml response method. The extra arguments passed are:

• content_id: The id of the content being deleted.
• course_id: The course in which the content lives.
• external_content_id: The external content id specified when the content was originally created.

Unlike the remove action, this call does not offer the chance to stop the deletion. This is called by Blackboard Learn after it has decided to delete the content entry. Specifically can happen in the following situations:

• When a user copies a content item and selects the Delete After Copy option.
• When a user chooses the Recycle Course option and selects a content area that contains an instance of your proxy tool's content item.
• When a user deletes a folder that contains instances of proxy tool content.

  Once the deletion is complete, clean up any data associated with the deleted content item.

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger content exchange picture.

Content Exported

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, content_id, course_id, backup_id, type
Sample Implementation: ContentHandlerAction.java ?action=content-exported
Action on Failure Return: Error added to export log; Export continues.
Action on Communications Error: Same as failure (Error logged to file)
Action when proxy tool not available: Event ignored and assumed to have succceeded.

If specified then this request is called as a simple xml response method. This request is called during course Export and Archive operations to let you take an appropriate copy of your tool-specific data to be associated with the export/archive file.

The extra arguments are:

• content_id: The ID of the content item being exported.
• course_id: The course being exported.
• backup_id: A unique identifier for the export/archive file being generated. Use this to link up the data you save when the user restores/imports the file later on.
• type: exact or shallow. exact allows the snapshot of per-user data to be saved. shallow saves the metadata of the content, not the per-user data.

To make sure the per-course data is backed up as part of the course exported handler make sure that the logic is reflected in the handler. Content may be exported by itself without the settings.

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

Content Handler listitem icon

Required?: YES (Within a content-handler block)
Max Length: 100 characters
Legal Characters: us-ascii only

The listitem icon is displayed on a content area page.

When naming this icon, create two versions, one with _on in the name and one with _non in the name. Configure the _on version in the XML. If the item is unavailable it is displayed using the _non icon.

If the locale:key is provided as well as a basic path inside the element then the locale:key value is used and the element text is ignored. This key is located in the bundle of the current locale per bundle action to localize images if required.

Content Handler Type

Required?: YES (Within a content-handler block)
Max Length: 65 characters
Legal Characters: us-ascii only

This is the handle for the content type. Use this when creating content items via ContentWS.saveContent(). This handle must be globally unique; if anyone else tries to create a content handler for the same content type then a conflict occurs at runtime. Only the first application to register a content handler can handle content of that type.

Content Imported

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, content_id, course_id, backup_id, type
Sample Implementation: ContentHandlerAction.java ?action=content-imported
Possible Deferred Event: YES
Action on Failure Return: Error message added to import log file; Import continues; event is NOT queued for later delivery.
Action on Communications error: Error message added to import log file; Import continues; Error logged to application log file; Event is queued up to be delivered later (see Deferred Event Delivery).
Action when proxy tool not available: Event queued for later delivery
Action when proxy tool not present on system but locator XML included in backup: Event queued for later delivery.

If specified then this request is called as a simple XML response method. This request is called during course Import and Restore operations to let you link up an appropriate copy of your tool-specific data to be associated with the export/archive file (that you made during the content-exported callback).

The extra arguments are:

• content_id: The new ID of the content item being imported.
• course_id: The course being imported.
• backup_id: A unique identifier for the export/archive file being imported/restored. Use this to link up the data you saved when the user exported/archived the file originally.
• type: exact or shallow. exact means the per-user data for this item can be restored, shallow means that only metadata for your content can be restored, not the per-user data.

To restore per-course data as part of the courseimported handler and is required for the content item, make sure the logic is reflected in this handler. This content can be imported by itself (user chooses to export content areas but not settings and then uses that file to import).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

Course Copied

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, type, oldCourseId, newCourseId
Sample Implementation: CourseOperationsAction.java ?action=course-copied
Action on Failure return: Warning message added to log file and email notifies user of warnings during the copy. Event is NOT queued for later delivery.
Action on Communications error: Same as failure plus the Event is queued up to be delivered later (Deferred Event Delivery).
Action when proxy tool not 'available': Event queued for later delivery.

If specified then this request is called as a simple xml response method. The extra arguments passed are:

• type: exact or shallow.
• oldCourseId: The course id being copied.
• newCourseId: The course id of the new course.

  Some of the generic arguments are not valid in this request: ticket, user_id, and role. Ignore these.

Use this callback to copy any course-level data (i.e. data persisted as part of the coursetool, tool, communication links).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the contentexchange picture.

Course Deleted

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id
Sample Implementation: CourseOperationsAction.java ?action=course-deleted
Action on Failure return: Ignored (no error message displayed to user)
Action on Communications error: Same as failure (Error logged to file)
Action when proxy tool not available: Event ignored and assumed to have succceeded

If specified then this request is called as a simple XML response method. The extra argument passed is course_id: the course being deleted.

Some of the generic arguments are not valid in this request: ticket, user_id, and role. Ignore these.

Use this callback to clean up all data related to the given course, including course-level data as well as data for any content items within the course. DO NOT delete any snapshots of the data taken as a result of archives/exports, those can still be restored/imported at a future date.

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the contentexchange picture.

Course Exported

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, type, course_id, backup_id
Sample Implementation: CourseOperationsAction.java ?action=course-exported
Action on Failure return: Export operation continues but an error added to the export log
Action on Communications error: Same as failure (Error logged to file)
Action when proxy tool not available: Event ignored and assumed to have succeeded.

If specified then this request is called as a simple XML response method. The extra arguments passed are:

• type: exact or shallow.
• course_id: The course id being exported (or archived).
• backup_id: The unique id of the export/archive file being generated.

  Some of the generic arguments are not valid in this request: ticket, user_id, and role.

Use this callback to backup any course-level data (data persisted as part of the coursetool, tool, communication links).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

Create Content

Required?: YES (Within a content-handler block)
Max Length: 255 characters
Legal Characters: us-ascii only
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id, content_id
Sample Implementation: ContentHandlerAction.java, content/create.jsp, CreateContentAction.java
Legal Roles: COURSE:INSTRUCTOR, COURSE:COURSE_BUILDER

This link is called when a course builder chooses the proxy tool from the Other Items drop-down list in a content area. The specific arguments for this request are:

• course_id: This is the id of the course in which the content item is being created.
• content_id: This is the id of the folder in which the piece of content is being created.

In response to this request, login a ticket-based Web Service session and keep it on the Proxy Server (ContentHandlerAction.java). Then take whatever steps are required to ask the user your custom information about your piece of content (create.jsp).

After gathering the required information (including payment information if you are selling a pay-per-use service where you expect each course to pay separately), then create a ContentVO and call ContentWS.saveContent(...) (CreateContentAction.java). This call returns the internal ID of the content as created in Blackboard Learn. Save this id along with the custom information so this content can be loaded later (see OurContentVO.java).

Keep track of a number of pieces of information to identify a content item (All of these are fields in OurContentVO): externalId: You generate this before creating the content - this is your unique identifier for this piece of content, separate from Academic Suites. courseId: This is the id of the course the content was created in. contentId: This is the academic suite's id of the content item it created. ourguid: This is the guide of the academic suite server as returned to the proxy tool server during the registertool operation. These are all required so that you can properly support Blackboard Learn operations for content-copy, course copy (both simple and exact), course export, and course archive. Refer to Content Exchange and Proxy Tools for more information.

To associate a Grade Center column with a content item, create a ColumnVO after creating the content item and call GradebookWS.saveColumn(...) (also shown in CreateContentAction.java). Then persist the Grade Center column id in your local data (see OurContentVO.gradebookColumnId).

Refer to Grade Center Integration Caveat.

Description

Required?: NO

This is the text description of the proxy tool. It appears on the Properties page for the proxy tool in the Blackboard Learn UI. Describe the purpose of the proxy tool here so the System Administrator can make an informed decision about activation.

Group Copied Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, type, oldCourseId, newCourseId, oldId, newId
Sample Implementation: CourseOperationsAction.java ?action=group-copied
Action on Failure return: Copy operation will log an error at this point and continue. The operation as a whole will be reported as being successful though. The Event is NOT queued to be delivered later.
Action on Communications error: Same as failure (Error logged to file) plus Event is queued up to be delivered later (see Deferred Event Delivery).
Action when proxy tool not available: Event is queued up to be delivered later (Deferred Event Delivery).

If specified then this request is called as a simple XML response method. The extra arguments passed are:

• type: exact or shallow.
• oldCourseId: The course id being copied.
• newCourseId: The course id of the new course.
• oldId: The group id being copied.
• newId: The new group id.

  Some of the generic arguments are not valid in this request: ticket, user_id, and role.

  Use this callback to copy any group-level data (data persisted as part of the grouptool link).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

Group Exported Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, type, course_id, backup_id, group_id
Sample Implementation: CourseOperationsAction.java ?action=group-exported
Action on Failure return: Error message added to export log file and the export continues.
Action on Communications error: Same as failure (Error logged to file).
Action when proxy tool not available: Event ignored and assumed to have succceeded.

If specified then this request is called as a simple XML response method. The extra arguments passed are:

• type: exact or shallow.
• course_id: The course id being exported (or archived).
• backup_id: The unique id of the export/archive file being generated.
• group_id: The group id being exported (or archived).

  Some of the generic arguments are not valid in this request: ticket, user_id, and role.

Use this callback to backup any group-level data (data persisted as part of the grouptool link).

Refer to Content Exchange and Proxy Tools for an outline of how this fits into the bigger contentexchange picture.

http-actions

http-actions sections appear in several places in the proxy tool descriptor:

1. At the top level: These provide singleton actions for your tool.
2. Inside content-handlers: There are a number of per-content-type actions defined.
3. Inside menu-links: A single action is defined per menu link.

In all cases, the http-actions section contains 1 or more <action> elements. An action element is defined as follows:

<action type="action-type" path="/path/to/action/servlet">
<param name="parameter-name" fixed="parameter-value"/>
... more params
</action>

The maximum length of the path + all the params concatenated together into a string of

/path/to/action/servlet?parameter-name=parameter-value&paramname=value&...

must not exceed 512 characters. This will not be used as the single URL address sent. All parameters are used as POST parameters on the page posted by the browser (or in the page posted by the simple-xmlresponse request).

Link Description

Required?: Yes (Inside a link)

This is the name to be displayed for the long description of the link in the UI. It is a key to a property in the page returned by the bundle URL. If no bundle URL has been specified then this is the raw text displayed. The actual rendering of this text depends on the link type, so check there for details.

Link Icon

Required?: YES (Inside a link)

This is the name of the icon to be displayed for this link. The actual required size and rendering location of this icon depends on the link type, so check there for details.

If the locale:key is provided, as well as a basic path inside the element, then the locale:key value is used and the element text ignored. This key is located in the current locale's bundle as per bundle action so the images can be localized.

Link Name

Required?: YES (Inside a link)

This is the name that to be displayed for the link in the UI. It is a key to a property in the page returned by the bundle URL. If bundle URL is not specified, then this is the raw text displayed. The actual rendering of this text depends on the link type, so check there for details.

Link Type

The following link types are currently supported:

The following link types are NOT supported: communication, cs_action, cs_tool, cs_modify_file, cs_modify_folder, cs_manage_portfolio, cs_my_portfolios.

communication

Request Arguments: Generic Proxy Tool Request Arguments, course_id
Sample Implementation: ToolAction.java, tool.jsp (?type=communication)
Legal Roles: COURSE:*
Placement: This link displays on the Tools page in a course.
Name: Displays as the name of the link.
Description: Displays as the long description on the tools page under the linked Name.
Icon Size: 50 x 50 pixels
Icon Placement: Beside the name on the Tools page.

The communication link provides a Course-level single-instance tool entry point for a communicationstyle tool. Store the data keyed on guid+course_id.

course_tool

Request Arguments: Generic Proxy Tool Request Arguments + course_id
Sample Implementation: CourseToolAction.java, courseTool.jsp
Legal Roles: COURSE:INSTRUCTOR, COURSE:COURSE_BUILDER
Placement: This link shows in the Course Tools part of the Control Panel in a course.
Name: Shows as the name of the link in the control panel.
Description: N/A
Icon Size: N/A
Icon Placement: N/A

The course_tool provides a control panel entry point into a single-instance of the tool per course.
Store the data keyed on guid+course_id. This page is used by an Instructor to configure their course-level tool. The tool link type is used to display the tool to students.

group_tool

Request Arguments: Generic Proxy Tool Request Arguments, course_id, group_id
Sample Implementation: ToolAction.java, tool.jsp (?type=group)
Legal Roles: COURSE:*
Placement: This link shows on the Groups pages in a course.
Name: Shows as the name of the link.
Description: Shows as the long description on the group page under the linked Name.
Icon Size: TBD
Icon Placement: TBD

The group_tool link provides a Group-level single-instance (per group) tool entry point. Store the data keyed on guidcourse_idgroup_id.

system_tool

Request Arguments: Generic Proxy Tool Request Arguments
Sample Implementation: SystemToolAction.java, systemTool.jsp
Legal Roles: SYSTEM:ADMIN
Placement: This link shows in the Tools and Utilites module on the System Admin tab.
Name: Shows as the name of the link
Description: N/A
Icon Size: N/A
Icon Placement: N/A

The system_tool link is designed for global per-academic-suite-instance configuration. Store any data here keyed on guid.

tool

Request Arguments: Generic Proxy Tool Request Arguments, course_id
Sample Implementation: ToolAction.java, tool.jsp
Legal Roles: COURSE:*
Placement: This link shows on the Tools page in a course.
Name: Shows as the name of the link.
Description: Shows as the long description on the tools page under the linked Name.
Icon Size: 50 x 50 pixels
Icon Placement: Beside the name on the Tools page.

The tool link provides a Course-level single-instance tool entry point. Store the data keyed on guid+course_id.

user_tool

Request Arguments: Generic Proxy Tool Request Arguments
Sample Implementation: UserToolAction.java, userTool.jsp
Legal Roles: SYSTEM:NONE
Placement: This link is used in the Tools module on your My Institution module. It must be manually added there by the Blackboard Learn System Administrator on *System Admin/Community System-Management/
Tabs* and Modules/Tool Panel.
Name: Shown in drop list of tools on the Add Tool page.
Description: N/A
Icon Size: 12x12 pixels
Icon Placement: Beside the clickable name on the tools module.

The user_tool link is designed for a global per-user tool. You would store your data keyed on guid+userid. The return_url here is not valid for a direct return. As it stands today you need to specify a target="_top" for the return to work properly here (See userTool.jsp)

Link URL

Required?: YES (Inside a link)
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments + per-link type
Sample Implementation: Depends on link type.
Legal Roles: Depends on link type.

This is the relative URL that the browser will be directed to for this link. Refer to link type for per-link-type specifics.

Links

Required?: NO

The links section contains both content-handler and menu-link sub elements for each content type or menu-link to support in your proxy tool.

A content-handler provides the ability to create content items within content areas in a section. Define 0 or more content handlers to be provided by the proxy tool.

A menu-link provides the ability to place links at various specifically-named points within the Blackboard Learn interface. Define 0 or more menu-links to be provided by the proxy tool (and each named point may have 0 or more instances defined as well).

LTI Version

While we are making attempts to deliver proxy tool support that matches what we expect LTI 2.0 to define, we are implementing and delivering before the LTI specification will be complete. As such, specify an ltiVersion of 2.0-July08 to indicate the fact that your tool profile is implemented to our current interpretation of where the spec will be. XXX

Modify Content

Required?: YES (Within a content-handler block)
Max Length: 512 characters (Well, actually probably shorter due to auto-added data - TODO Fill in based on testing + walking through code) XXX
Legal Characters: us-ascii only
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id, content_id
Sample Implementation: ContentHandlerAction.java, modify.jsp, CreateContentAction.java
Legal Roles: COURSE:INSTRUCTOR, COURSE:COURSE_BUILDER

In the modify operation, the extra arguments passed in have this meaning:

• course_id: The course in which the content exists.
• content_id: The id of the CONTENT that is being modified. (note how it actually is the content here, unlike the create action where it was the folder/parent id)

Note here how a webservice session (ClientWrapper) is established before forwarding to the Modify page. This is due to the short lifetime of a ticket for login and the unpredictable amount of time the user may spend on the Modify page. In CreateContentAction, observe how it distinguishes between create and update based on the existence of a content-id in the post. It calls the same ContentWS.saveContent method as an insert/update routine. Make sure the original contentid is set on the ContentVO to perform an update.

Operation

Required?: NO

This is an optional element where specific operations can be listed per Web Service that your tool needs when logged in as a tool. Each operation must be the exact name of the Web Service operation the tool calls. Operations not found are ignored.

If operations are not specified here then they must be programatically requested through the Tool Registration process.

Ping Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments
Sample Implementation: PingAction.java
Action on Failure return: User is presented with a server-unavailable message.
Action on Communications error: Same as failure (Error logged to file).

If specified then this request is called as a simple XML response method. The ping request is sent by Blackboard Learn prior to generating the redirect page in the user's browser. If the ping returns successfully then the page redirects the user. If it fails then the user is presented with a Proxy tool server unavailable message. If a ping action is not specified and the server is down, users that attempt to access the tool are redirected and receive a standard browser-generated server-not-found error.

Program

Required?: YES

The program field identifies the program, it must be unique among all programs to develop as a vendor (vendor + program must be unique on a system). It can be up to 128 characters long (BUT possibly limited to far less - see note below about http-action links), but again, the shorter the better for a cleaner UI.

Hard-code this value into each of the programs, with the one exception of a run-inparallel-for-trial use-case. If you plan on deploying your application in such a way as to let multiple instances (and versions) of it be connected to the same academic suite instance then you should refer to Deploying multiple concurrent versions for directions.

The sum of the lengths of the vendor identifier and program identifier must be less than or equal to 63 characters in length to support any links elements. To support links elements then these must be us-ascii characters only.

Remove Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments
Sample Implementation: StateChangeAction.java (+ hard-coded argument of ?state=unregistered in this case)
Action on Failure return: Ignored (warning displayed to user but operation completes successfully)
Action on Communications error: Same as failure (Error logged to file).
Action when proxy tool not available: Event sent

When the Blackboard Learn System Administrator removes a proxy tool from the server, this URL is called in as a simple XML response method.

In this case the state change action is reused and a state that is not normally sent as part of the state change action is hard-coded.

Remove Content

Required?: YES (Within a content-handler block)
Max Length: 512 characters (Well, actually probably shorter due to auto-added data - TODO Fill in based on testing + walking through code) XXX
Legal Characters: us-ascii only
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id, content_id
Sample Implementation: ContentHandlerAction.java
Legal Roles: COURSE:INSTRUCTOR, COURSE:COURSE_BUILDER

In the remove operation, the extra arguments passed have this meaning: course_id: The course in which the content exists content_id: The id of the CONTENT that is being removed. (note how it actually is the content here, unlike the create action where it was the folder/parent id)

Refer to ContentHandlerAction.doRemoveContent for some sample logic on how to handle removing your content.

This callback is for a user-facing web page to display confirmation for the removal prior to actually removing it if you want. Note the difference between this and the Content Deleted Details.

Reregister Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, regpass, tcprofileurl
Sample Implementation: ReRegisterAction.java
Action on Failure return: Error message displayed to user and proxy tool left in unavailable state.
Action on Communications error: Same as failure (Error logged to file).
Action when proxy tool not available: Event sent.

If specified, the Blackboard Learn System Administrator has a reregister option associated with the tool. When chosen, a simple XML response request is sent to this method. Before calling this URL, the tool is put into an allowreregistration
state on the Blackboard Learn server. This allows a one-time re-registration of the tool
without having to clear the password; the registerTool operation is not permitted if the password is set for the tool.

If the tcprofileurl is specified then it can be used to load the current version of the Tool Consumer Profile and update the local configuration as required before calling the registerTool operation.

The servlet has to re-call ContextWS.registerTool and then return a success result (or failure of course - if the registerTool fails).

There is no automatic way to let the Blackboard Learn System Administrator know there is a new version of the proxy tool server. The current mechanisms for this notification include: Internal: If the Blackboard Learn System Administrator also manages the proxy tool server then they can tell themselves that they updated it. Include this step in the Proxy Tool Server installation documentation to remind them. Email/Regular Mail: If you are hosting a shared proxy tool server then notify all your subscribers that they must hit the reregister button via some notification mechanism of your own. Consider backwards-compatability when upgrading the server. Never assume everyone will hit the reregister at the same point in time when you upgrade your server.

Security Profile

Required?: NO

The security profile lets you declare which digest algorithm you wish to use. If you are using the tcprofileregistration method then you can get a list of valid digest algorithms supported by the server from the tc profile in the tool-consumer-info section:

<security-profile>
<digest-algorithms>
<algorithm>MD5</algorithm>
<algorithm>SHA</algorithm>
</digest-algorithms>
</security-profile>

The only supported algorithms are MD5 or SHA; MD5 is used by default.

Service

Required?: NO

The required-webservices section is an informational section where to declare the names of the Web Services that the tool will be using. If all of the declared webservices are not available on the Blackboard Learn server then the System Administrator cannot make the proxy tool available. The current Web Services available for use can be found on Blackboard Learn and newer Web Service Names, but check your Academic Suite server at release time for the most up-to-date list. Only list the services that the tool uses.

Even if this element is not provided any Web Services can still be used. The only caveat is that the Blackboard Learn System Administrator does not know beforehand which services are in use and Blackboard Learn will make the tool available even if required services are not present or not available.

It is recommended this element be utilized so the tool is only available when the required Web Services are available. If this element is not provided then you must specify the operations you plan on using in your registerTool method call or you will not be granted the entitlements required.

State Change Action

Required?: NO
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, state
Sample Implementation: StateChangeAction.java
Action on Failure return: If going to 'available' then the state change will be blocked in AS. Otherwise failure is ignored and a warning message is displayed (but the AS operation completes successfully).
Action on Communications error: Same as failure (Error logged to file).
Action when proxy tool not available: Event sent since this is a result of changing the state.

If specified then this request is called as a simple XML response method. The extra argument passed is state with one of the following values:

• available
• inactive
• unavailable

These states correspond to the three state options for the tool on the tool properties page in the academic suite UI. For inactive and unavailable, this is a purely informative step. If Blackboard Learn fails to make this call or you return a failure result then it is ignored. Conversely, the available state transition will fail if the state change operation is configured and the request fails.

Tool Login Operation

Required?: NO

The tool-login section lists the Web Services and operations which will be used while logged in as your tool (i.e. via the ContextWS.loginTool(...) method).

The Proxy Tool framework resolves your requested operations into Blackboard Learn entitlements and displays them to the System Administrator so they know what entitlements are being granted to your tool before they make it available.

If you do not specify this section then you must specify your list of desired operations in the registerTool method call or you will not have any entitlements when using Web Services while logged in as your tool.

Tool Provision

Required?: NO
Authenticated Request?: NO
Request Arguments: tcprofileurl, regpass, returnurl
Sample Implementation: TcProfileRegistration.java

The tool-provision action is a way to make the tool easier to install. This can be either a relative URL like all the other actions or it can be a fully qualified URL.

This action will be used by the System Administrator during initial registration of your tool. They will navigate to Administrator Panel > Building Blocks > Proxy Tools and select the Register Proxy Tool/Create Proxy Tool with Placements option. On this page they will either select your tool from a drop-down list or manually enter the full path to the tool's location. For the sample server this means they would enter the following:

http://your.sample.server:9080/ws.sample.proxyserver/tcProfileRegistration

as the URL. The browser will be redirected to this page with the arguments:

In response to this page, prompt the user for whatever information you need and then call registerTool to register your Proxy Tool.

tcprofileurl

This is a fully qualified URL pointing to the Tool Consumer Profile for the Blackboard Learn system where you are installed your tool.

regpass

This is the tool registration password. You will be given a single-use registration password to be used
when calling the registerTool method

returnurl

This is a fully qualified URL you can use to redirect the user back into Blackboard Learn after you have
registered your tool. This servlet accepts a parameter of ?jump_to_guid=XXXX where XXXX is the
ourguid returned by the registerTool method. If you include this parameter then the System Administrator will be taken directly to the edit-proxy-tool page for your newly registered tool. If you leave the parameter off then they will be presented with a list of all the proxy tools on their system (from which they will have to find and edit your newly registered one to make it available).

locale

This is the java string representation of the current locale for the user. If possible, present the registration UI to them in using this locale.

direction

This is the direction attribute for the current UI (ltr or rtl). If possible, present the registration UI using this direction attribute.

vendor

This is an optional parameter to indicate the expected vendor for this registration request. This should match your vendor/code element from your tool-profile, and if you end up registering anything other than this then the Blackboard Learn system will not get what it is expecting.

program

This is an optional parameter to indicate the expected program for this registration request. Typically
this should match your tool-info/code element from your tool-profile, and if you end up registering
anything other than this then the Blackboard Learn system will not get what it is expecting. If your proxy tool server implements multiple different proxy tool programs then this can be used to determine which one is expected to be registered at this point in time.

Vendor

Required?: YES

The vendor field describes you, as a vendor. It should ideally be a short string similar to the 4-character vendorid used in building block development, but can be longer (up to 128 characters; see the note below about http-action links). Longer names will make the UI appear cluttered, so try to keep this short.

This is a constant value to use for all of your products. It should be unique so that nobody else will end up using the same value.

The sum of the lengths of your vendor identifier and program identifier must be less than or equal to 63 characters in length to support any links elements. Also, to support links elements then these must be us-ascii characters only.

Vendor URL

Required?: NO

Use this to specify the homepage where you are equal to the company writing the proxy tool server application.

Version

Required?: YES

This is a version identifier for the version of the proxy tool server that generated the XML. When you update your proxy tool server in a way that changes the XML you should update the version in this XML. If you merely update your server internals without changing this XML then there is no need to change the version.

While there are no rules governing the contents of this version aside from length (cannot be greater than 32 characters), it is recommended to keep the version numeric and incremental.

View Attempt

Required?: YES (within a content-handler block)
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id, content_id, target_userid, attempt_id, courseMembershipId, outcomeDefinitionId, source
Sample Implementation: ContentHandlerAction.java, viewattempt.jsp
Legal Roles: COURSE:INSTRUCTOR, COURSE:GRADER, COURSE:TEACHING_ASSISTANT

In the view attempt operation, the extra arguments passed in have this meaning:

• course_id: The course in which the content exists.
• content_id: The id of the CONTENT for which an attempt is being viewed.
• target_userid: The id of the user whose attempt you are viewing.
• attempt_id: Id of the attempt (can ignored for now).
• courseMembershipId: Can be ignored (for now) as it has already been translated to target_userid.
• outcomeDefinitionId: The id of the gradebook column being viewed.
• source: Can be ignored for now (TODO - document the purpose for this arg).

TODO: If we end up supporting this then the sample will have to be expanded and more details put here

View Content

Required?: NO (Within a content-handler block)
Max Length: 512 characters (Well, actually probably shorter due to auto-added data - TODO Fill in based on testing + walking through code)
Legal Characters: us-ascii only
Authenticated Request?: YES
Request Arguments: Generic Proxy Tool Request Arguments, course_id, content_id
Sample Implementation: ContentHandlerAction.java, view.jsp
Legal Roles: COURSE:*

In the view operation, the extra arguments passed in have this meaning:

• course_id: The course in which the content exists.
• content_id: The id of the CONTENT that is being viewed. (note how it actually is the content here, unlike the create action where it was the folder/parent id).

Usage: The title for any content items handled by the associated content handler will be a clickable link that will pass through to this page. If not specified then the title will not be clickable.

Sample Proxy Tool

The following is a sample XML description that would be provided to the registerTool method. Click the links for detailed information on the particular element.

<?xml version="1.0" encoding="ISO-8859-1"?>
<tool-profile ltiVersion="2.0-July08" xmlns:locale="http://www.ims.org/lti/localization">
<vendor>
  <code>Vendor</code>
  <name>Name Not Used</name>
  <description>Description not used</description>
  <url>http://www.your.url</url>
  <contact><email>vendor contact not used.John.q.Admin@proxy.server.host</email></contact>
</vendor>
<tool-info>
  <code>Program</code>
  <name>Name Not Used</name>
  <version>1</version>
  <description>Text Description</description>
<tool-info>
<tool-instance>
  <base-urls>
    <base-url type="http">http://your.server.com/proxyApp</base-url>
    <base-url type="https">https://your.server.com/proxyApp</base-url>
    <base-url type="server-to-server">https://your.server.com/proxyApp</base-url>
  </base-urls>
  <contact><email>John.q.Admin@proxy.server.host</email></contact>
  <security-profile>
    <digest-algorithm>SHA</digest-algorithm>
  </security-profile>
</tool-instance>
<required-webservices>
  <tool-login>
    <service name="Context.WS">
      <operation>logout</operation>
... More <operation/> rows as required
    </service>
... More <service ... elements as required for tool-authentication
  </tool-login>
  <ticket-login>
    <service name="Context.WS">
      <operation>logout</operation>
    </service>
... More <service ... elements as required for ticket-authentication
  </ticket-login>
</required-webservices>
<http-actions>
  <action type="tool-provision" path="/tcProfileRegistration"/>
  <action type="bundle" path="/getBundle"/>
  <action type="remove" path="/removeAction"/>
  <action type="config" path="/configAction"/>
  <action type="state-change" path="/stateChangeAction"/>
  <action type="reregister" path="/reregisterAction"/>
  <action type="ping" path="/ping"/>
  <action type="course-deleted" path="/courseHandler">
    <param name="action" fixed="course-deleted"/>
  </action>
  <action type="course-copied" path="/courseHandler">
    <param name="action" fixed="course-copied"/>
  </action>
  <action type="course-exported" path="/courseHandler">
    <param name="action" fixed="course-exported"/>
  </action>
  <action type="course-imported" path="/courseHandler">
    <param name="action" fixed="course-imported"/>
  </action>
  <action type="group-copied" path="/courseHandler">
    <param name="action" fixed="group-copied"/>
  </action>
  <action type="group-exported" path="/courseHandler">
    <param name="action" fixed="group-exported"/>
  </action>
  <action type="group-imported" path="/courseHandler">
    <param name="action" fixed="group-imported"/>
  </action>
</http-actions>
<links>
  <content-handler>
    <name locale.key="resource/x-my.content.type.name">Content Type Name</name>
    <handle value="resource/x-my.content.type"/>
    <http-actions>
      <action type="create" path="/contentHandler">
       <param name="action" fixed="create">
      </action>

      <action type="modify" path="/contentHandler">
       <param name="action" fixed="modify">
      </action>

      <action type="remove" path="/contentHandler">
       <param name="action" fixed="remove">
      </action>

      <action type="view" path="/contentHandler">
       <param name="action" fixed="view">
      </action>

      <action type="viewattempt" path="/contentHandler">
       <param name="action" fixed="viewattempt">
      </action>

      [<action type="content-copied" path="*/contentHandler*">]
       <param name="action" fixed="content-copied">
      </action>

      <action type="content-exported" path="/contentHandler">
       <param name="action" fixed="content-exported">
      </action>

      <action type="content-imported" path="/contentHandler">
       <param name="action" fixed="content-imported">
      </action>

      [<action type="content-deleted" path="*/contentHandler*">]
       <param name="action" fixed="content-deleted">
      </action>

    </http-actions>
    <can-copy value="true"/>
    <icons>
      <icon>unused default lti icon</icon
      <icon platform="blackboard" style="toolbar" locale:key="icon.lang.key">/images/icon1_on.gif</icon>
      <icon platform="blackboard" style="listitem" locale:key="icon.lang.key">/images/icon1_on.gif</icon>
    </icons>
  </content-handler>
... More <content-handler>...</content-handler> sections
  <menu-link>
    <category-choice>
      <category>TBD - LTI defined generic category currently unused</category>
      <category platform="blackboard">course_tool</category>
    </category-choice>
    <name locale:key="course_tool.name.key">Link Name</name>
    <http-actions>
    <action type="menu-view" path="/courseTool"/>
    </http-actions>
    <description locale:key="course_tool.link.description.key">Link Desription</description>
    <icons>
      <icon>unused default lti icon</icon
      <icon platform="blackboard" style="listitem" locale:key="icon.lang.key">/images/icon1.gif</icon>
    </icons>
  </menu-link>
... More <menu-link>...</menu-link> sections
</links>
</tool-profile>

Sample Application Development Environment

Follow these steps to prepare a proxy tool server development environment:

1. Login as administrator to a current AS install.
2. Go to System Admin/Building Blocks/Proxy Tools.
3. Select Download Sample Tools.
4. Unzip into a directory on your hard drive.
5. Read LICENSE_for_samples.txt.
6. Read readme.txt.
7. Read proxy/java/readme.txt.

SSL support is centered on Tomcat; Blackboard directs users to refer to the following web site for information regarding SSL support:

• Apache Tomcat 6.0 SSL Configuration HOW-TO

Simple XML Response Proxy Server Pages

Several of the touch-points between Blackboard Learn and the proxy tool server are through server-to-server posts. These are authenticated requests and require the normal MAC validation, but the response is a simple XML response instead of a resulting HTML page. There are only two possible responses to any simple XML request.

Success:

<result>SUCCESS<result>

Failure:

<result>ERROR<result>

When implementing the proxy server, these requests respond should within a reasonable time period (sub-second if possible). There is a timeout of 2 minutes applied to the socket so if the request takes longer, the callback is assumed to have failed. If more time is needed then edit the timeout setting in bb-config.properties as follows:

bconfig.proxy.server.socket.timeout=timeout in ms

This must be set to at least a value of 1000 (1 second) and applies to all proxy tools.

Tool Consumer Profile

As part of LTI compatability, a Tool Consumer Profile is generated which describes Blackboard Learn from the perspective of tool interoperability. This is a fixed URL on any given Blackboard Learn instance:

webapps/ws/wsadmin/tcprofile

The System Administrator can disable the generation of this profile on the Proxy Tool Global Properties page. This returns an XML description that includes the following items:

• http url of this system
• https url of this system
• css url
• webservices offered (including url of webservice reflecting ssl choice), operations offered per Web Service

Here is the Tool Consumer Profile:

<?xml version="1.0" encoding="UTF-8" ?>
<tool-consumer-profile ltiVersion="2.0-July08">
  <tool-consumer-info>
    <name>Blackboard Learn</name>
    <version>9.0.236.0</version>
    <description>The Blackboard Learning System(TM) is a family of software applications designed to enhance teaching and learning. Intuitive and easy-to-use for instructors, the Blackboard Learning System helps instructors to build course materials online and engage with students in an interactive way.</description>
    <security-profile>
      <digest-algorithms>
        <algorithm>MD5</algorithm>
        <algorithm>SHA-1</algorithm>
      </digest-algorithms>
    </security-profile>
  </tool-consumer-info>
  <tool-consumer-instance>
    <guid>6b9de60425e243fba3bfbd283158864d</guid>
    <contact>
      <email>TODO - what email do we want to expose here?</email>
    </contact>
  </tool-consumer-instance>
  <vendor>
    <code>blackboard</code>
    <name>Blackboard Inc.</name>
    <description>Blackboard Inc. (Nasdaq: BBBB) is a global leader in enterprise technology and innovative solutions that improve the experience of millions of students and learners around the world every day. Blackboard's solutions allow thousands of higher education, K-12, professional, corporate, and government organizations to extend teaching and learning online, facilitate campus commerce and security, and communicate more effectively with their communities. Founded in 1997, Blackboard is headquartered in Washington, D.C., with offices in North America, Europe, Asia and Australia.</description>
    <url>http://www.blackboard.com</url>
    <contact>
      <email>sales@blackboard.com</email>
    </contact>
  </vendor>
  <http-actions>
    <action type="css" path="/webapps/blackboard/execute/proxyCSS" />
  </http-actions>
  <services-offered>
    <service name="Content.WS" url="http://lance.bbbb.net/webapps/ws/services/Content.WS" wsdl="http://lance.bbbb.net/webapps/ws/services/Content.WS?wsdl">
    </service>
... More <service></service> blocks
  </services-offered>