Working with the Voyager APIs
The purpose of this Blog Post is to bring together some of the information about using the Voyager APIs into a simple document that shows examples of using them.
API stands for “Application Programming Interface” and the available open interfaces allow interaction between Voyager and other applications.
There are two “types” of interfaces (sometimes called “web services”): the “older” Voyager XML over HTTP Web Services and the “newer” RESTful Web Services.
Both types of Web Services go through the Voyager VXWS port.
Check the XSDs for required encoding. Typically it is UTF-8.
The VXWS port is port xx14 on your Voyager server.
The first thing you need to know is your database’s port series. This is often, but not always 70xx. Consult a working VOYAGER.INI file on a staff workstation to confirm your port series. Note that some Voyager installations have more than one production port series.
Once you know your VXWS port, you may need to open access to that port. This is done, in part, via firewall modifications (that is beyond the scope of this Blog Post). It is also done, in part, by modifying the server.xml file that you will find in your database’s directory (where xxxdb is your database): /m1/voyager/xxxdb/tomcat/conf> (See this Article for more information:
While you are doing your work with the Web Services, you may want to increase the level of logging as configured in the log4j.properties file that you will find on your Voyager server here: /m1/voyager/xxxdb/tomcat/vxws/context/vxws/WEB-INF/classes. Comment or uncomment the appropriate lines. For example to increase logging:
- log4j.logger.com.endinfosys=DEBUG, LOGFILE
To set logging back to its normal state, comment out the first two lines in the above example and uncomment the third line.
The log4j.properties file will include a line of code (log4j.appender.LOGFILE.File=) telling you where the log file is located on the system.
Typically it is found here: m1/voyager/xxxdb/tomcat/vxws/logs/
In the vxws.log file(s).
Note that some failures may not appear in the log file because the error happened at the top of the stack, and thus not making its way down to the vxws service to be logged. See: https://knowledge.exlibrisgroup.com/Voyager/Knowledge_Articles/Required_encoding_for_Voyager_API_XSDs
Once you know your VXWS port, you should next determine what your DBKEY value is. To determine your DBKEY, you will need to “run” your first API “Call” — the “DB InfoService” web service. You can learn more about this web service here: https://developers.exlibrisgroup.com/voyager/apis/xmloverhttpwebservices/dbinfoservice/
Open up your browser and paste in a URL that looks like this:
Where you replace 10.100.3.999 with your Voyager server’s IP address and 8114 with your VXWS port (e.g., 7014).
If your “Call” is successful, your response will look something like this:
<?xml version="1.0" encoding="ISO-8859-1"?> <dbInfoCollection xmlns=http://www.exlibris.com/Voyager/dbinfo> <info> <reply> <reply-text>Success</reply-text> <reply-code>SUCCESS</reply-code> </reply> </info> <dbInfo> <dbKey>MAST20001DB20020910109999</dbKey> <version>2010.1.0</version> <dbName>Local Database</dbName> </dbInfo> </dbInfoCollection>
In this case the string:
Is the DBKey for my database “Local Database”.
Note that when you use your DBKey in a call, you must add the “1@” prefix to the DBKey string. For example:
This prefix is required.
Not all Calls require the DBKey string, but many do and it is a critical piece of information you must obtain.
Many Calls can be run simply from your web browser and require no additional information other than the correct parameters. The syntax of these Calls is documented in the individual API web service descriptions.
But other Calls are more complicated and require input from an xml file. Don’t let this discourage you if you want to test such a web service. You can use the Chrome ARC (Advanced REST client) Extension to create service requests.
STEP 1: Install Chrome ARC
STEP 2: Click on the Apps Icon on the tool bar
STEP 3: Open ARC
As an example, we’ll use ARC to submit a POST command to the Course Reserves API (https://developers.exlibrisgroup.com/voyager/apis/xmloverhttpwebservices/coursereservepropertiesservice/).
STEP 4: Determine what your URL syntax should look like from the web service description.
For example. for the Course Reserve Properties Service I would use this syntax:
STEP 5: Create your xml input file.
My xml input file that I will select from within ARC looks like this. Note it includes my DBKey, which is a required parameter (don’t forget the prefix!):
<?xml version="1.0" encoding="UTF-8"?> <ser:serviceParameters xmlns:ser="http://www.endinfosys.com/Voyager/serviceParameters"> <ser:parameters> <ser:parameter key="clusterId"> <ser:value>1@MAST20001DB20020910109999</ser:value> </ser:parameter> <ser:parameter key="locationId"> <ser:value>0</ser:value> </ser:parameter> <ser:parameter key="browseFlag"> <ser:value>N</ser:value> </ser:parameter> </ser:parameters> </ser:serviceParameters>
STEP 6: Configure your request in ARC. Use the Body tab to select content type and specify your input file.
STEP 7: Click the “SEND” button.
STEP 8: My test Output in Chrome ARC, which returns information for one Course, looks like this:
<?xml version=”1.0″ encoding=”UTF-8″ ?> <ser:voyagerServiceData> <ser:serviceData xsi:type=“sear:courseReservePropertiesType”> <sear:selectedClusterId> 1@MAST20001DB2002091010999 </sear:selectedClusterId> <sear:selectedClusterName> Voyager Library Training Database </sear:selectedClusterName> <sear:reserveData> <sear:activeCourses> <sear:course> <sear:id> 1 </sear:id> <sear:name> Human Biology </sear:name> <sear:number> BIO:700 </sear:number> <sear:clusterId> 1 </sear:clusterId> </sear:course> </sear:activeCourses> <sear:activeDepartments> <sear:department> <sear:id> 1 </sear:id> <sear:name> Biology </sear:name> <sear:code> BIO </sear:code> <sear:clusterId> 1 </sear:clusterId> </sear:department> </sear:activeDepartments> <sear:activeInstructors> <sear:instructor> <sear:id> 13 </sear:id> <sear:lastName> Hall </sear:lastName> <sear:firstName> Monty </sear:firstName> <sear:title> Dr. </sear:title> <sear:clusterId> 1 </sear:clusterId> </sear:instructor> </sear:activeInstructors> <sear:activeSections /> </sear:reserveData> </ser:serviceData> </ser:voyagerServiceData>
Summary: This is a fairly simple example. All the “pieces” of the web service “puzzle” need to be in place to successfully run the example API. This Blog Post goes over those requirements and then shows you how in Chrome ARC you can send an API Call that uses an input file and have data returned appropriately.