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>