Getting Started with Talis Keystone

Talis Keystone provides two standard interfaces: SOAP and REST. In the following sections we show you how you can access the borrower account details using these Web interfaces. For a detailed discussion, please see View My Account Web Service API Reference Manual (PDF).

For the following demonstrations, we will be using the Talis Keystone instance running on the Talis Keystone sandbox to access the View My Account (VMA) Web Service. We have setup twelve test borrowers for you to experiment with, which are listed here.

Direct REST API access via HTTP GET

A REST request represents a HTTP GET request to the service end-point. The end-point where VMA requests must be sent to is:

http://<servername>:<port>/TalisKeystone/ViewMyAccountRESTService

The REST request is simply a set of HTTP parameters sent to the REST end-point as a set of HTTP URL query arguments.

The first query argument represents the borrower whose account is being requested. This is structured as a name value pair query, where the 'value' is the unique identifier for the borrower and the 'name' is the type of the unique identifier. There are currently three types of borrower identifier: Barcode, InstitutionIdNumber and UserId. For more details, please refer to View My Account Web Service API Reference Manual (PDF).

Query arguments which follow the borrower identifier represents items desired from the borrower's account. These arguments are a set of ampersand (&) delimited String literals. The table below shows the desired parameters:

Display the Borrower Account Summary

To retrieve the borrower account summary of a borrower whose Barcode is 19734689, enter the following URL in your favourite Web browser's address prompt or simply click the link:

http://sandbox.talis.com/TalisKeystone/ViewMyAccountRESTService?Barcode=19734689&Summary

You should be able to see the borrower name, charges summary, loaned items count, reserved items count, requested items count and booked items count.

Display the Borrower Account Summary and the AccessURL

To display the borrower account summary and the access url (Talis Prism OPAC single sign-on link) of a borrower whose InstitutionIdNumber is G78LST, simply enter the following URL in your browser or click the link:

http://sandbox.talis.com/TalisKeystone/ViewMyAccountRESTService?InstitutionIdNumber=G78LST&Summary&AccessURL

You should see the account summary and the Prism OPAC single sign-on link. The single sign-on link is time limited and will take you directly into the "My Account" page of Prism in a logged in state.

To log into Prism, copy the access url and paste it in your Web browser's address prompt.

The Prism "My Account" page provides various functionalities such as renew loans and cancel bookings.

Display the Summary, Fiscal Account, Loaned Items and Reserved Items

The REST request to retrieve the Summary, Fiscal Account, Loaned Items and Reserved Items of a borrower whose Barcode is 12593486 looks like this:

http://sandbox.talis.com/TalisKeystone/ViewMyAccountRESTService?Barcode=12593486&Summary&FiscalAccount&LoanedItems&ReservedItems

Direct SOAP Access

In this section we will demonstrate the SOAP API using a tool called soapui. We will provide step-by-step guide to installing soapui and then invoking the VMA Web Service:

1. Launch the latest stable version of soapui using the WebStart from http://www.soapui.org/
2. Create a new soapui project:
     a. File--->New WSDL Project
     b. Enter a suitable project name and then click OK.
     c. State where you would like to save the project and then click on Save.
3. Right click on your project and click on Add WSDL from URL.
4. Enter the following URL:

http://sandbox.talis.com/TalisKeystone/ViewMyAccountSOAPService/TalisKeystoneViewMyAccount.wsdl

This will add the ViewMyAccount Web Service to this project.
5. Click OK.
6. You will be asked if you want to create default requests for all operations, select Yes.
7. Right click on ViewMyAccount and select Service Endpoints.
8. Select the endpoint and click on Edit.
9. Change the service endpoint to:

http://sandbox.talis.com/TalisKeystone/services/ViewMyAccount

10. Click on OK to close the Input dialog box
11. Click on OK to close the Interface Service Endpoints.
12. Expand ViewMyAccount and double click on Request 1. This will open the request editor.
13. The left hand pane shows the default SOAP request to ViewMyAccount Web Service and the right side shows the SOAP response(initailly empty).

The default request has ? for all the parameters that is accepted by this Web Service. We must change the default values to acceptable values to form a valid request:
     a. Set VisibleUserIdentifierType to Barcode
     b. Set VisibleUserIdentifier to 1550770x
     c. Set Summary to true
     d. Set all other values to false

14. Now send the SOAP request by pressing the left-most toolbar button (a green arrow).

On the right hand pane you will see the SOAP response.

In summary, what we have done is created a SOAP request to get the borrower account summary of a borrower whose Barcode is 1550770x.

You can now change the SOAP Request to request for different information by simply changing the request parameters to true/false. You can also select a different borrower by simply changing the VisibleUserIdentifierType and VisibleUserIdentifier to appropriate values (refer to the test borrowers). Try the REST examples given above but this time use SOAP to retrieve the same information and then compare the outputs.

If you have any questions, comments, suggestions, or a contribution to make, please use the forum.