How To Add a Borrower Via Web Services API

Transcription

1 How To Add a Borrower Via Web Services API Summary This document outlines the use of the Web Services API available in the version 5(v5) knowledge content and library management (KCLM) solution for adding, querying, updating and viewing borrower records. It is intended to be read by system integration developers (Analyst/Programmers) familiar with Web Services in any application language. A registration module is required to access Web Services features. The Web Services offering has four main components: Generic entity API (since v4.2 build 7) OPAC specific API (since v4.2 build 6.0 RC 1) Federated Search specific API (since v5 build 1) An implementation of the Open Search API (since v4.2 build 6.0 patch 9) The generic entity API allows you to query or perform create, read, update and delete operations on any system entity. A system entity is defined as a record type in the v5 solution. Examples of these include but are not limited to Borrowers, resources, loans, orders and reservations. For the purposes of this document, the Borrower record is defined in the 'Client' entity. Requirements General Analyst/Programmer skills A Licenced v5 solution with the Web Services Module included A current Softlink Support Agreement Consultation time with Softlink Technical Support Analysts is strongly recommended. This time can be used assist you to troubleshoot and to determine SOAP request parameters to suit your requirements Administrative access to the v5 solution Administrative access to the v5 Application server for the purpose of reviewing system log files Access to the SQL database where the v5 database is installed. This will include the ability to run queries on the database Configuring the Web Services API in the v5 Solution To utilise the Softlink Web Services API the v5 solution must have the Web Services API module included in its registration. Please contact Softlink Sales to arrange for the inclusion of this module in the v5 registration code. Web Services APIs cannot be accessed without this module. The Web Services username and password is required to be RSA encrypted by default in the v5 solution. This is configurable by setting the System Parameter No webservicesencryptcredentials which is controlled by Softlink Support. Please have Softlink Support set this parameter to false to allow the Username and Password to be sent as plain text for the purpose of troubleshooting the Web Services API during configuration

2 and setup. The parameter can then be reset to true after configuration and testing of Web Services API integration with your third party system (e.g. Moodle, MS SharePoint, Student Admin Systems or web-based portals) as is suitable for the security configuration of your implementation. With webservicesencryptcredentials turned on, the clientaliasenc and clientpasswordenc must have their values encrypted independently by your implementation to ensure the security of these credentials. Information required to generate encrypted Alias and Password values is provided in the Security section of this document. For further assistance with encryption of web services credentials please contact Softlink. The built-in Web Services Borrower record is provided for accessing the Web Services API. The account is pre-configured with the Web Services User Role. The role is linked to a set of User Privileges allowing the availability of API operations to be controlled. When deploying web services, you should modify the privilege settings to only allow operations you intend to use. For the purposes of adding a Borrower record enable the User Privileges for browse, create, delete, query, and update. Click on each of the blue text privilege groups in the /webservices/entity/ /* groups to expand them and disable features in each group that you do not wish to allow through API calls (e.g. creating, deleting, updating catalogue entity elements). Figure 1 - webservices User Privileges settings Note: If you do not wish to allow OPAC queries through the Web Services API the User Privilege 'Must be enabled for OPAC Web Services API function calls' or its component items can be disabled. While this function is not used when adding a Borrower record, it can be left on if desired. The Web Services API is now configured in the v5 solution. You can logout of v5. Testing the Web Services API A method of sending API requests and receiving responses for testing and troubleshooting purposes now and in the future will be needed. Use a tool you are familiar with that can send SOAP requests and receive the responses. There are a number of utilities and test suites available including the open source tool, SoapUI 1 ( If you prefer, a PHP script or other method can be used to test SOAP requests and replies. This will require that you are familiar with preparing and 1 Softlink does not endorse or support this product.

3 sending SOAP requests. Softlink does not support configuration of scripting languages or third party tools for testing/troubleshooting SOAP requests. Now that the v5 solution is configured for the Web Services API it can be tested to confirm that API calls are being received and responded to correctly. To test and troubleshoot the web service you must have access to the v5 server.log file located on the application server in the v5 installation directory, for example: /softlink international/server/sahara/log/server.log). To test that the API is functioning prepare a simple SOAP request to query the Borrower records in the v5 solution (there should be 5 default Borrower records already present). Enter the following URL in a browser that can access the v5 solution: * Replace Oliver with Liberty for a Liberty system. This should return a browser page with the XML formatted definition of the elements of the Web Services API that are accessible using the EntityAccess API. If your browser does not return this type of page, contact Softlink Support for assistance. Figure 2 - Sample output of /EntityAccess?wsdl definition Follow the instructions in the following sections of this guide to find a Borrower, browse a Borrower and add a Borrower record. Once you have this successfully working with your third party product you can systematically remove 'webservices' User Privileges that you do not require to be accessible through the API. If you are unable to successfully query or browse the v5 solution, check the Troubleshooting guide at the end of this document or contact Softlink to arrange for a consultant to assist you. Note: The following sections assume that Parameter 1390 'webservicesencryptcredentials' is set to false and the Web Services borrower credentials can be sent as plain text. Accessing Borrower Data with the API To access a Borrowers information using the API, you will need to use two of the EntityAccess?wsdl functions called 'Query' and 'Browse'. The Query request allows you to search for a field value contained in an entity. The entity type for Borrower records in v5 is 'Client'. This request will return a list of the Universally Unique Identifiers (UUID values) of the Borrower records matching your search. The Browse request returns the contents of the records contained in an entity type. It must contain the UUID of each record whose details you wish to view.

4 Finding a Borrower To find a Borrower record s UUID value you must send a Web Services API request containing a valid Borrower record search. This means a search that will return the required result when searched in the "any words" search field in the product s Borrower search screen. For example to find a borrower whose Surname is 'Bloggs' the search query Familyname = "Bloggs" will return the UUIDs of all Borrower records with a Family name of "Bloggs". This query can therefore be used in a SOAP request. The SOAP request to perform this search looks like this: <soapenv:envelope xmlns:soapenv=" xmlns:ent=" <soapenv:header/> <soapenv:body> <ent:query> <corpalias>corporationalias</corpalias> <clientaliasenc>webservices</clientaliasenc> <clientpasswordenc>password</clientpasswordenc> <entityname>client</entityname> <search>familyname = "bloggs"</search> <maxresultcount>100</maxresultcount> </ent:query> </soapenv:body> </soapenv:envelope> The fields highlighted in yellow define the v5 Web Services details and the query to be performed. <corpalias> can be found by navigating in v5 (Build or greater) to the Management > About screen. The Alias is displayed at the top of this page. If you are unable to locate it contact Softlink Support for assistance. <clientaliasenc> is the Web Services borrowers alias. The default is 'webservices' <clientpasswordenc> is the password for the webservices borrower record. The default is 'password' but this can be changed if you prefer. <entityname> defines the v5 entity type. In this case the Borrower records have an entity type of 'Client' <search> defines the search to be performed you can use any valid v5 "any words" search here that will return the Borrower UUIDs that you wish to view the details of. A blank search will return all borrower records. <maxresultcount> determines the maximum number of results to be returned. Setting this number too high can negatively impact performance and response times on the v5 solution. Submitting this SOAP request to the v5 solution should return a SOAP reply similar to the following: <S:Envelope xmlns:s=" <S:Body> <ns2:queryresponse xmlns:ns2=" <return>d44585e6c0a8145a b8dc</return> <return>d4491b94c0a8145a00df53e b9</return> </ns2:queryresponse> </S:Body> </S:Envelope> The value appearing between each <return> tag pair is a UUID identifying a unique borrower record in the Borrower list. These values can be used in the following SOAP request to return the actual contents of the borrower record.

5 Browsing Borrower Details To get the details of the Borrower for a UUID you have determined using the query request you must send a Browse request to the v5 solution. A Browse request looks like this: <soapenv:envelope xmlns:soapenv=" xmlns:ent=" <soapenv:header/> <soapenv:body> <ent:browse> <corpalias>corporationalias</corpalias> <clientaliasenc>webservices</clientaliasenc> <clientpasswordenc>password</clientpasswordenc> <entityname>client</entityname> <!--1 or more repetitions:--> <uuids>abece0a3c0a8145a0070e3f0c22bf466</uuids> <loadconstant></loadconstant> </ent:browse> </soapenv:body> </soapenv:envelope> <entityname> is the name of the entity containing the type of information you wish to browse. In this case it is 'Client'. <uuids> contains the UUID of the borrower record you wish to view. There can be multiple <uuids></uuids> in the browse request. The reply will contain borrower details for each borrower UUID requested. <loadconstant> is blank in this instance but can be defined to return specific data related to the UUID. This is the subject of another How To Guide. Submitting this request will return a SOAP formatted reply containing the Borrower details for the Borrower whose record UUID was requested. <S:Envelope xmlns:s=" <S:Body> <ns2:browseresponse xmlns:ns2=" turn><![cdata[<net.softlink.libraryserver.webservice.common.entity.entityac cessimpl_-browseresult> <valueobjects class="list"> <Client> <uuid>abece0a3c0a8145a0070e3f0c22bf466</uuid> <updatesearchindex>true</updatesearchindex> <alias>jbloggs</alias> <allocation>0.00</allocation> <allocationspent>0.00</allocationspent> <allowbookreviews>false</allowbookreviews> <altmailtitle></altmailtitle> <amountowing>0.00</amountowing> <avatar>m1.png</avatar> <background>default.png</background> <birthday class="sql-timestamp"> :00:00.0</birthday> <deposit>0.00</deposit> <expirydate class="sql-timestamp"> :59:59.997</expiryDate> <familyname>bloggs</familyname> <mailtitle></mailtitle> <membersince class="sql-timestamp"> :00:00.0</memberSince>

6 <middleinitial>p</middleinitial> <motherphone></motherphone> <narrowtofavourites>false</narrowtofavourites> <notes></notes> <notifyupdates>true</notifyupdates> <opacdefaultoperator>and</opacdefaultoperator> <opacdefaultsearch></opacdefaultsearch> <personalname>joseph</personalname> <sortablename>joseph P Bloggs</sortableName>... </Client> </valueobjects> </net.softlink.libraryserver.webservice.common.entity.entityaccessimpl_- BrowseResult>]]></return> </ns2:browseresponse> </S:Body> </S:Envelope> (The above reply has had some fields removed for brevity) Now you should be able to find a Borrower in v5, and access the details of a Borrower (or Borrowers), using a SOAP request. Adding a Borrower Now that you can find and view a Borrower record from the v5 solution, this section provides the steps required to add a Borrower record to it. The minimum fields you should set for a Borrower record are: Alias * Family Name Personal Name Borrower Type * Borrower Loan Category * User Role * Branch *These fields are mandatory for any Borrower record to be successfully added to v5. To add a Borrower, use the create entity function of the entityaccess API. To add a basic Borrower to the Borrower list, a SOAP request like the following can be submitted: <soapenv:envelope xmlns:soapenv=" xmlns:ent=" <soapenv:header /> <soapenv:body> <ent:create> <corpalias>corporationalias</corpalias> <clientaliasenc>webservices</clientaliasenc> <clientpasswordenc>password</clientpasswordenc> <entityname>client</entityname> <valueobjectxml> <![CDATA[<net.softlink.libraryserver.data.ClientValueObject> <alias>jdoe</alias> <personalname>jane</personalname> <familyname>doe</familyname> <studentcode>54321</studentcode> <BorrowerLoanCategoryUuid>d3688f41c0a8145a00bed434fff2ea9b

7 </BorrowerLoanCategoryUuid> <BorrowerTypeUuid>d3688faac0a8145a01a9ffde8737d8f3</BorrowerTypeUuid> <userroleuuid>d3686ef5c0a8145a0112cae4124a2c9b</userroleuuid> <branchuuid>d3686a22c0a8145a019d cd</branchuuid> </net.softlink.libraryserver.data.clientvalueobject>]]> </valueobjectxml> </ent:create> </soapenv:body> </soapenv:envelope> The Web Services parameters remain the same as in previous requests. To specify the data to be entered for a Borrower record you must specify the following: <entityname> For adding general Borrower information this is set to 'Client'. <valueobjectxml> This contains and XML formatted list of the data to be entered, wrapped in the tag name for the destination field. This XML must be wrapped as CDATA and contain the Entity Value Object to be populated. In this case the Entity Value Object is 'net.softlink.libraryserver.data.clientvalueobject' for borrower records. Determining Field Aliases To determine which fields can be populated, when adding a Borrower record, create a Borrower record in the v5 solution interface that contains examples of the data that you are intending to add using the Web Services API and perform a Borrower entity browse request for that Borrower. The tags listed with the data you entered can be used in the create Borrower requests to assign data to these fields when creating a new Borrower. (See the browse Borrower reply below as an example of the available fields). Determining UUID Values If a field you wish to populate requires a UUID instead of a term, you will have to perform a search for the UUID of the term you wish to set. This will require querying the entity type for that field to retrieve the UUID to use in place of the term you wish to enter. An example of this is the User Role value which must be set for all borrowers. This field requires the UUID of the User Role rather than its name. To find the UUID for the User Role 'OPAC Only' the following SOAP request can be sent to the v5 solution. <soapenv:envelope xmlns:soapenv=" xmlns:ent=" <soapenv:header/> <soapenv:body> <ent:query> <corpalias>default_corp</corpalias> <clientaliasenc>webservices</clientaliasenc> <clientpasswordenc>password</clientpasswordenc> <entityname>userrole</entityname> <search>alias = "OPAC Only"</search> <maxresultcount>100</maxresultcount> </ent:query> </soapenv:body> </soapenv:envelope> The UUID that is returned can be used to set the borrowers User Role to "OPAC Only". E.G. <userroleuuid>ab898f9ac0a8145a01be f570</userroleuuid>.

8 To determine a suitable search to find the UUID you require, go to System > FieldAlias and search for Entity co "UserRole" or the entity type you are looking for. The resulting list will have Aliases for the fields that you can search. Use the Alias in your search for the term you are looking for. E.G. for Borrower type the search will be term = "OPAC Only". Now that you have a working SOAP request to add a Borrower you can use this as a template for your third party system to populate and send the appropriate data. Security 1. SSL Web Services may be deployed using SSL over HTTPS to enhance security by ensuring network messages are not exchanged as plain text. The mechanisms to deploy Web Services with SSL are much the same as those for deploying the application user interface with SSL. Please refer to JBOSS documentation for further details. 2. Borrower Details Encryption As an alternative to using SSL, Borrower details passed into the API can be protected with the use of RSA encryption. This will simplify the deployment configuration at the expense of a more complicated client implementation. The following information is required in order to create the encrypted Web Services API arguments. Public key modulus: Public key exponent: Example Borrower encryption using PHP: The following demonstrates how Borrower encryption could be implemented in the PHP language. Note that the application RSA decryption function expects a series of numeric characters represented as a hex string. <?php include("rsa.class.php"); $RSA = new RSA(); $exponent = "65537"; $modulus = " " $client_alias = strhex($rsa->encrypt("administrator", $exponent, $modulus)); $client_pw = strhex($rsa->encrypt("password", $exponent, $modulus)); $client = new SoapClient(" $result = $client->query($corp_alias, $client_alias, $client_pw, $search, 25);...

9 Notes I. Remember to get Softlink Support to turn on Parameter No again to use encrypted Web Services Credentials if your implementation requires this. II. If you encounter errors when making SOAP requests refer to the server log and review the error message. This can often point to the parameter within the request packet that is failing or preventing the request from succeeding. III. Check the User Privileges for the 'webservices' Borrower and confirm the correct privileges are turned on. IV. Check the server log at the time code when you issued the SOAP request to see if an error message is present that identifies the problem. V. For troubleshooting the API, it may be beneficial to leave all 'webservices' User Privileges turned on until you are satisfied that it is working. Troubleshooting Messages that may display; what they mean and steps to take: INFO [EntityAccessImpl.isPermitted:358] permissiondenied: no web services registration. /webservices/entity/query/client The v5 Solution may not have the Web Services Module enabled in its product licence. Contact Softlink to arrange for the module to be added to the product licence. INFO [EntityAccessImpl.query:269] Corporation alias <default_cop> not found The <corpalias> value is incorrect. Correct the value in the request. ERROR [GeneratedMethodAccessor634.invoke:?] Query [>alias = "administrat*"] failed: net.softlink.search.parseexception The search query is incorrectly formatted. Ensure that the query as entered returns the expected result when searched in the "any words" search field in the products user interface. Correct the search query in the request. java.lang.runtimeexception:???webservice.error.create.exists??? at... ERROR [NativeMethodAccessorImpl.invoke0:?] Create [Client] failed: javax.ejb.ejbexception: RuntimeException The record being created has been identified as a duplicate of an existing record. In the case of Borrowers this can be due to the alias, username, or student code being the same as another Borrower records alias, username, or student code. The web services API enforces all data requirements that would need to be met when adding a Borrower through the UI. DefaultException: You must assign a user role to this user. at net.softlink.libraryserver.exceptions.exceptionutil.addexception(exceptionutil.java:59)... ERROR [NativeMethodAccessorImpl.invoke0:?] Create [Client] failed: javax.ejb.transactionrolledbacklocalexception: You must assign a user role to this user. The userroleuuid value is missing or incorrect. Correct this UUID value to that of the required UserRole. INFO [EntityAccessImpl.browse:65] For input string: "we" WARN [NativeMethodAccessorImpl.invoke0:?] Invalid login provided to browse

10 Or INFO [EntityAccessImpl.browse:65] For input string: "pa" WARN [GeneratedMethodAccessor639.invoke:?] Invalid login provided to browse The clientaliasenc and/or clientpasswordenc is in plain text when it is expected to be encrypted. Replace the clientaliasenc and/or clientpasswordenc with encrypted values. java.lang.illegalargumentexception: Could not locate fieldalias with name <term> on entity <Client>. Check that the <entityname> field in your query is set to the entity type of the UUID you are searching for. E.G. <userroleuuid> is found in the Entity 'UserRole'. Where as <BorrowerTypeUuid> is found in the Entity 'BorrowerType'. Also check that the search you are using in the <Search> tag is a valid query that returns the required result from the "any words" search field in the products search interface. java.lang.illegalstateexception: A default field group has not been set for entity <BorrowerType> corporation <d367c6aec0a8145a01fbe09b8208d7e4> The error, identified above, indicates that the search is not suitably defined. Try searching for the required result in the "any words" search field in the products search interface.

11 IMPORTANT INFORMATION Web Services API is very powerful and must be used with care. The Web Services API allows for direct manipulation of v5 database records. CAUTION should be used when creating, updating or deleting records using the API, as alteration or removal of some types of records and data can interfere with normal operation of the v5 solution. In some cases access to and regular use of the v5 solution may be compromised. All scripts/soap Requests that are to be executed against a production v5 solution MUST be checked by Softlink. Consultation with Softlink is strongly encouraged before implementing the Web Services API on a production v5 solution. Use of scripts/soap requests that have not been reviewed could unintentionally de-stabilise your v5 solution or render it unusable. Before commencing any design and testing of Web Services API requests, backup the v5 SQL Database. As Softlink advise that some security provisions are removed when developing and implementing the Web Services API for your purposes, please be aware that Data and Network security provisions when using the v5 Web Services API are your responsibility. Web Services credentials can be encrypted for transmission by your implementation. Please refer to the 'Security' section of this document for more information. Note that the Web Services module has not yet been evaluated in a performance sensitive environment. Web Services incur similar system resource consumption to a client browser interaction for a similar type of request. Frequent polling may impact system performance in a similar way to running multiple frequent system interactions. The impact will be dependent on the interaction performed.

12