Tool Registration is required to use the tool based authentication login method. It is also required by Proxy Tools to register their XML manifest. Follow these steps:

1. Prompt for the registration password if the Blackboard Learn System Administrator requests it during installation/registration.
2. Enter a description for a simple Web Service agent. The description field can be plain text. This will be shown in the properties page in AS for your program. If you are registering a proxy tool, refer to the Proxy Tools section below.

   When registering a Proxy Tool with an XML descriptor, specify the operations in the registerTool method or in the XML or both. If you specify in both places, the list of operations is merged together. Blackboard recommends specifying them in the XML because that is the only place where the list of 'webservices requested' is generated in the administrator UI.

3. Create a list (requiredToolMethods) of all the Web Service operations you intend to call as a tool (i.e. session authenticated with toolLogin)
4. Create a list (requiredTicketMethods) of all the Web Service operations you intend to call as a user via ticket-based authentication (i.e. session authenticated with ticketLogin).
5. Call ContextWS.registerTool(vendorid, programid, registrationPassword, description, requiredToolMethods, requiredTicketMethods). This creates an instance of your tool (aka 'webservice agent') on the Blackboard Learn server and register the list of Web Service operations that you are going to need.
6. Add the above code to your application installation program or to your initial application startup code. It only needs to be run once.

After you have run the tool registration, the Blackboard Learn System Administrator must login, go to the list of Web Service agents, edit the properties for your agent, review the list of entitlements that you have asked for (the list of entitlements requested is generated based on the Web Service operations you declared as being required), and setup a password for your agent. Use this password to authenticate your tool in subsequent loginTool calls. The tool installer will have to ask for a password as well - this is a shared secret that must be configured on both sides - with your tool and with Blackboard Learn.

Proxy Tools

When registering a Proxy Tool, the description field must be the Proxy Tool XML description for your tool. Refer to the sample Proxy Tool server code, ProxyUtil.buildToolDescription(...) for some sample code that builds an XML description for a proxy tool.

When registering a Proxy Tool the result will give you both a true/false success and a proxytoolguid field. This guid is a unique identifier generated by Academic Suite associated with this tool registration. You must record this GUID and use it to correlate future requests from the server with your local configuration (for example, you will need to store a shared secret per server to validate requests from the server - you would store this keyed on the GUID returned). Refer to RegisterAction.java + ProxyUtil.register() for a sample of tool registration and the storage of the GUID. In our sample program we have a local class ProxyClientVO.java which we use to represent an instance of an Academic Suite server from the perspective of the proxy tool server.