Aleph 18: X-Server Martin Büscher 2008/12/16

2 Copyright Statement and Disclaimer All of the information and material, including text, images, logos and product names, is either the property of, or used with permission by, Ex Libris Ltd. The information may not be distributed, modified, displayed or reproduced – in whole or in part – without the prior written permission of Ex Libris Ltd. TRADEMARKS Ex Libris, the Ex Libris logo, Aleph, SFX, SFXIT, MetaLib, DigiTool, Verde, Primo, Voyager, MetaSearch, MetaIndex and other Ex Libris products and services referenced herein are trademarks of Ex Libris, and may be registered in certain jurisdictions. All other product names, company names, marks and logos referenced may be trademarks of their respective owners. DISCLAIMER The information contained in this document is provided on an "AS IS" basis for general information purposes only without any representations or warranties, whether express or implied, including any implied warranties of satisfactory quality, completeness, accuracy or fitness for a particular purpose. Ex Libris, and its subsidiaries and related corporations disclaim any and all liability for use of this information, even if advised of the possibility that loss, damage or expenses may arise. © Ex Libris Ltd., 2008

3 Agenda Introduction General Access Control Translate Selected Services: Requesting BIB-data Requesting patron-data Other useful circulation services Authentification of staff users

4 Agenda Introduction General Access Control Translate Selected Services: Requesting BIB-data Requesting patron-data Other useful circulation services Authentification of staff users

5 Introduction – General – 1 URL/XML based API Commonly used for interoperability between Ex Libris products as well as external application. Ex Libris Products which make use of the Aleph X-Server are MetaLib, Verde, PDS and Web ILL.

6 Introduction – General – 2 The data is well structured, and supports data hierarchy (while still readable by humans). The solution is simple, familiar, and plenty of commercial parsers are available. Aleph GUI Client Browser HTML Proprietary format XML Client XML

7 Introduction – General – 3 Syntax to call up a X-Service : /X?op= & =<param_valuehttp:// : /X?op= & = In general all services are using the GET-mechanism to transfer data, this means that the needed parameters are part of the URL. Exceptions: The services „update-bor“ and „update- doc“ are using the POST-mechanism. For these services the creation of a CGI-script is needed.

8 Introduction – Explain – 1 Calling up : /X?op=explain&file=intro you get the built-in X-Services Documentation:

9 Introduction – Explain – 2 As opposed to real XML services, the op=explain does not reply with a structured XML, but with static HTML pages Besides service specific information, the explain feature contains tutorial pages about the X-Server in general, for example Types of services Error messages setup Licenses Permissions

10 Introduction – List of available X- services bor-auth bor-by-key bor-course bor-info circ-status find find-doc get-holding get-sort-codes hold-req hold-req-cancel item-data present renew sort-set update-bor update-doc explain login user-auth ill-arrive-copy ill-arrive-loan ill-bor-auth ill-bor-info ill-build-loan ill-create-pat ill-get-doc ill-get-doc-short ill-get-set ill-loan-return ill-print-holdings ill-print-items ill-holds-delete ill-in-loc ill-in-loc-preview ill-item-by-bc ill-item-delete ill-item-due-date ill-item-info ill-loan-info ill-loan-lost ill-loan-recall ill-loan-renew

11 Access Control – server_ip_allowed Global access can be defined by IP using $alephe_tab/server_ip_allowed. The table allows multiple definitions including and excluding specific IP or IP masks. !-!-!!!!!!!!!!!!!!!> X D X A *

12 Access Control – Staff Privileges – 1 Each service requires a staff privilege. If the service does not send a user/password, WWW-X/WWW-X is assumed. This is used to grant permissions to anonymous users. The services find, find-doc and present are open for all. Note: Do NOT change the password of staff user WWW-X.

13 Access Control – Staff Privileges – 2 If you want to block specific services for anonymous users, you should deny the relevant permission for user WWW-X. Then you can create a new user having the relevant permission.

14 Access Control – Staff Privileges – 3 There are two different ways to use the created staff user: Option 1: Add the parameters „user_name“ and „user_password“ to each X-service-call. Example: info&borid=P8&library=USM50&user_name=XBOR&user_password =BLUE info&borid=P8&library=USM50&user_name=XBOR&user_password =BLUE

15 Access Control – Staff Privileges – 4 Option 2: Workflow: 1) Use the service “login” with parameters “user_name” and “user_password”. 2) If the data is correct, the X-server will send a session-ID in the response. 3) Now add this ID as parameter “session” to each X- service-call. Example: rd=BLUE&library=USM50 rd=BLUE&library=USM50

16 Access Control – Staff Privileges – 5 Option 2 - Example: Request: rd=BLUE&library=USM50 rd=BLUE&library=USM50 Response: - 2DN4F8AKJBYREH2M441H2NMKGVJBV86LUAHHTIS1A54YABD7PP

17 Access Control – Staff Privileges – 6 Option 2 – Example (cont.): Request for service bor-info: id=P8&library=USM50&session=2DN4F8AKJBYREH 2M441H2NMKGVJBV86LUAHHTIS1A54YABD7PP

18 Translate – General Each output goes through the translation mechanism. The translation is executed on the tags as well as on the data. This allows to eliminate some sections from the XML as well as formatting the structure. There are two different translation mechanism: 1) The data will be handled according to the *trn-files placed under $alephe_root/www_x_eng. (This mechanism is similar to the translation-mechanism for XML-printouts in GUI.) 2) The content of the data will be handled according to the *tag- files placed under $alephe_root/www_x_eng. There is one additional filter-mechanism (currently only available for bor-info).

19 Translate – trn-Mechanism – 1 For all services the files global.trn and.trn are checked. Example (without translated data): Response: + […] − P8 01 […]

20 Translate – trn-Mechanism – 2 Example (with translated data): Setup in $alephe_root/www_x_eng/bor-info.trn: z304-date-to DATE S Request: Response: + […] − […] /02/2007

21 Translate – tag-Mechanism – 1 For all services the files global.tag and.tag are checked. The tag-mechanism can be used for three purposes: Changing the captions of tags Eliminating of tags Eliminating of data records Note: Eliminating data from the output can improve the response-time of X-server-requests.

22 Translate – tag-Mechanism – 2 Example (without tag-mechanism): P8 01 […] − P8 ALEPH 26/01/2007 …

23 Translate – tag-Mechanism – 3 Example (with tag-mechanism): Setup of $alephe_root/www_x_eng/bor-info.tag z304 DELETE z305-id DELETE z305-sub-library TRANSLATE sublib ALEPH 26/01/2007 …

24 Translate- filter-Mechanism – 1 Exclusively for service bor-info an additional mechanism is available. With this optional filter it is possible to define which fields SHOULD be displayed. To use this filter, add a file into directory $alephe_root/www_x_eng (for example tab_bor_info_filter). This file should contain the data fields that should be displayed. Example-file tab_bor_info_filter: Z303-NAME Z304-TELEPHONE

25 Translate - filter-Mechanism – 2 Now add parameter &filter_data= to the X -server-request: info&bor_id=00141&verification=0028&library=usm50&f ilter_data=tab_bor_info_filter In this case only the name and the telephone number will be displayed.

26 Agenda Introduction General Access Control Translate Selected Services: Requesting BIB-data Requesting patron-data Other useful circulation services Authentification of staff users

27 Requesting BIB-data - General To retrieve bibliographic data there are two options: The service „find-doc“ can be used to call up the data if you already know the system number of the record: doc&doc_num= &base=USM01 doc&doc_num= &base=USM01 The service „find“ can be used to perform a CCL-search: &base=USM01 &base=USM01

28 Requesting BIB-data – “find” The X-server will transmit a set_number and the number of found records as a response for a „find“- request:

29 Requesting BIB-data – “sort-set” The service „sort-set“ may be used to sort the result set: set&library=MAB01&set_number=022058&sort_code_1=01& sort_order_1=A&sort_code_2=02&sort_order_2=A set&library=MAB01&set_number=022058&sort_code_1=01& sort_order_1=A&sort_code_2=02&sort_order_2=A You may use all sort codes that are defined in tab_sort of the relevant library. Note: You must send at least two sort codes in your X- server-request. Your are not allowed to use more than four sort codes.

30 Requesting BIB-data – “present” To display full bibliographic data of the records in the set use the service „present“. &set_number=022058&base=USM01 Note: In each response from the present-command exactly one record is displayed.

31 Requesting patron-data – “bor-auth” The service „bor-auth“ can be used to check the password of a patron: auth&bor_id=P8&verification=GREEN&library=USM50 auth&bor_id=P8&verification=GREEN&library=USM50 If the password is not ok, an error message will be called up: Error in Verification If the password is ok, the global and local patron information plus the adress record (Z303, Z305 and Z304) will be displayed.

32 Requesting patron-data – “bor-info” – 1 Using the service „bor-info“ you will get detailed patron information: Global patron record (Z303) Local patron records (Z305) Adress record (Z304) Loans – including item and title information (Z36) Hold requests – including item and title information (Z37) Cash records (Z31) The system performs the checks defined in section X- GBL in./[lib]/tab/tab_check_circ. If problems are found error messages will be reported in section.

33 Requesting patron-data – “bor-info” - 2 You may use filters in order not to display all circulation data. Possible values for filter: Parameter „loans“: Y (default) -> all loan information is displayed. N -> NO loan information is displayed. P -> only the title information plus due date of each loan is displayed. Parameter „holds“: Y (default) -> all hold information is displayed. N -> NO hold information is displayed. P -> only the title information plus "pickup location", "date of interest" and "status" are displayed per hold request.

34 Requesting patron-data – “bor-info” - 3 Possible values for filter (cont.): Parameter „cash“: Y (default) -> all cash information is displayed. N -> NO cash information is displayed. B -> only the balance of all cash records is displayed as a sum. O -> only open cash transactions are displayed. F -> only cash transactions with a specific type are displayed. You need to add this type as parameter „filter_cash“.

35 Requesting patron-data – “bor-info” - 4 Some examples of bor-info-requests: Requesting all data: info&bor_id=BAR8&library=USM50 info&bor_id=BAR8&library=USM50 Requesting the data without any loan information: info&bor_id=BAR8&library=USM50&loans=N info&bor_id=BAR8&library=USM50&loans=N Requesting the patron data without loan and hold information. Only the balance of the cash records is displayed: info&bor_id=BAR8&library=USM50&loans=N&holds=N&cash =B info&bor_id=BAR8&library=USM50&loans=N&holds=N&cash =B

36 Other useful circulation services – 1 The service “circ-status” can be used to call up item and loan information for a specific title record: status&sys_no= &library=USM01 status&sys_no= &library=USM01 You can place hold-requests using service “hold-request”: req&item_barcode=BAR7&bor_id=P9&library=USM50 req&item_barcode=BAR7&bor_id=P9&library=USM50 Note: The system performs the checks from section XML-CIRC in./[lib]/tab/tab_hold_request when creating a hold via the X-server.

37 Other useful circulation services – 2 To renew loan periods the service “renew” may be used: rary=USM50 Note: The system performs the checks from section X-RNW in./[lib]/tab/tab_check_circ when renewing items via X-server.

38 Authentification of staff users Using the service user-auth the passwords of staff users may be checked: user=CIRCSTAFF&staff-pass=YELLOW&library=USM50 user=CIRCSTAFF&staff-pass=YELLOW&library=USM50 If the password is correct, the X-server will send the information of the staff user record (Z66) in the response.

Thank you!