RefTracker API Documentation

Introduction

The RefTracker API allows RefTracker customers (a programmer’s skills are required) to access up to the minute RefTracker data and use it in their webpages. Altarama has created easy to embed widget functionality that allows you to add a Recent questions list, FAQ list, Advanced search capability and more to your web pages with a few lines of code and pre-built templates. For information regarding the API Widgets please see the page about RefTracker API Widgets. API widgets are not available for all RefTracker API functionality, so please be sure to review the documentation below that describes the entire set of API methods.

The API can also be used to create a RefTracker question from information collected elsewhere (such as in another application, or in a form of your own design), and to insert the “View all my requests” functionality into your web pages securely.

Feel free to use your imagination and share your ideas and creations with the rest of the Altarama community via our Support pages

The API Operations

A list of available API functions is accessible to System Administrators logged into your RefTracker system, at System>Utilities>Information>API Methods (it goes to http://{YourRefTrackerDomain}/exchange/api.asmx. The page looks like the screenshot below.

Clicking on each of the links in the exchange/api page will take you to a page where you can enter the associated parameters, test different API operations in your browser, and obtain information about the operation – for example.

HINT: Many API opertions require brackets and quotes to be entered in the box in this screen. Make sure you type those brackets and quotes into this box – cutting and pasting them from Word processing or this documentation does not generate the same characters and will result in an error instead of the results that you want.

API information about forms

You can find information about the API for each RefTracker form by going to System>Request form summary>Requester service, and clicking the Preview link for the form that you want to use. Click the appropriate “View” link.

Security

Be sure to set your security requirements! See API use security for details.

You can secure access to the API functions in the exchange/api page, by securing access to this exchange/api page. Allow IP access to this page for only the users that you want to use the functions in this page.

However, for use of the API itself you will need to enable the appropriate 9.x parameters and the api.xml file in the config/settings directory. Until you enable the appropriate API method/s in the 9.x parameters, API use will be prevented for security reasons. Further, the 9.x parameters allow an APIkey to be set for each method. The methods can be used without the API but are not secure without an APIkey, so they should only be used in this way in secured environments. For all other uses it is critically important, for security reasons, that an APIkey is set and used for each API method.

For this reason, each API method below has a section about security, to ensure that the correct 9.x parameter is set up and used.

If you are developing an API application, we recommend that you enable just the required API methods using the appropriate 9.x parameters and set keys for each, then choose one key value and copy it to all of the 9.x parameters that you need so that you can use the same APIkey value for this application, and any other future applications.

Response format

JSONP is required if you are making API requests via Ajax from your organization’s website/domain. If you are creating server-side requests in PHP, .NET, etc. then you can use either JSON or XML (as specified in the information about each API function below).

More about the API functions – the documentation for each

This operation documentation is grouped by similar or related functionality. They are not in alphabetical order (as they are in the exchange/api.asmx screen. So, go to the right functionality documentation by searching this page for the operation name or function that you are interested in.

Available requestForms:-

The available requestForms operation will return the Key and Name of all the Forms that are configured for Client availability in this RefTracker system (both General availability and External (URL only) availability. You might use this to insert a list of RefTracker forms in your web pages (as opposed to inserting a single form that can be inserted using its URL), or, or more usually, to validate that a particular form key is valid. The list returned will always contain all of the forms that are currently available for clients to use. You may not want to publish the availability of some forms that have only been made available for External (URL only) access.

Method: requestForms

Format: JSON

Type: GET

Description: gets a list of available request forms

Security: Enable parameter 9.56 and, for security, set a key for it (unless you are operating in a total secure environment). If you set a key, ensure that the apikey parameter in parameter 9.56 is included in all calls to this method

Response: JSON string

Parameter	Description
{none}
apikey	Obtain the key for parameter 9.56

Example call

https://currentrelease.altarama.com/exchange/api.asmx/requestForms?parameters={"apikey":"vDxzDLvz7kO7AUBbyTsp6Q"}

Example response – successful

[{“reqform_desc”:”Ask a Librarian Widget”,”reqform_key”:”Widget”},{“reqform_desc”:”Ask a Librarian: Research Request”,”reqform_key”:”HuntRQ”},{“reqform_desc”:”Basic Shortest Request Form”,”reqform_key”:”Basic”},{“reqform_desc”:”Booking form”,”reqform_key”:”Booking”},{“reqform_desc”:”Comments \u0026 Suggestions”,”reqform_key”:”Comment”},{“reqform_desc”:”Copied form”,”reqform_key”:”RefShort_copy_01″},{“reqform_desc”:”Database access problem”,”reqform_key”:”DBAccess”},{“reqform_desc”:”Desktop sharing session request”,”reqform_key”:”Desktop”},{“reqform_desc”:”Digitisation request”,”reqform_key”:”Digitise”},{“reqform_desc”:”Inter Library Loan request”,”reqform_key”:”ILL”},{“reqform_desc”:”Journal article request”,”reqform_key”:”DocDel”},{“reqform_desc”:”Literature search”,”reqform_key”:”LitSearch”},{“reqform_desc”:”Lost question request”,”reqform_key”:”Lost”},{“reqform_desc”:”New item recommendation”,”reqform_key”:”NewItem”},{“reqform_desc”:”Pro-Active Widget”,”reqform_key”:”proactive”},{“reqform_desc”:”Quick Question Widget”,”reqform_key”:”QuickQuestion”},{“reqform_desc”:”RefChatter Integration form”,”reqform_key”:”RefChatterINT”},{“reqform_desc”:”Request General”,”reqform_key”:”ReqGen”},{“reqform_desc”:”Survey form”,”reqform_key”:”Survey”},{“reqform_desc”:”Training Requests by Library Staff”,”reqform_key”:”TrainingStaff”},{“reqform_desc”:”Training Requests by Students, Faculty, Others”,”reqform_key”:”TrainingOthers”},{“reqform_desc”:”Training Statistics”,”reqform_key”:”TrainingStat”},{“reqform_desc”:”USC Faculty Research”,”reqform_key”:”USCFacResearch”},{“reqform_desc”:”USC Legal Research”,”reqform_key”:”USCLegal”},{“reqform_desc”:”USC Reference”,”reqform_key”:”USCRef”}]

RequestFormXSD:-

The RequestFormXSD will return a definition of the fields available in the form with the specified key, and the valid values for each of those fields. It can be used to create a form of your own design, or to check that values being provided by your application, are valid to be provided to RefTracker using RequestFormXMLExample, so that a valid new question will be created when you submit the XML.

Note that this information can also be obtained from within RefTracker by going to System>Request form summary>Requester service> and the request form that you want this information for. Then choose Preview mode in the top right of the screen and in that screen, on the same line as the Request form name, you will see a [View XSD Schema] link that shows this information (as well as two other helpful links re API information – [View parsed XSD] and [View sample XML])

Method: requestFormXSD

Format: JSN

Type: GET

Description: gets the XSD schema for specified request form key

Response: XSD Schema (XML)

Parameter	Description
key	RefTracker request form key

Examples

https://currentrelease.altarama.com/exchange/api.asmx/requestFormXSD?parameters={"formkey":"basic","apikey":"vDxzDLvz7kO7AUBbyTsp6Q"}

Example response

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:tns="https://currentrelease.altarama.com/config/exchange/reftracker/schema/rqform_basic.xsd" targetNamespace="https://currentrelease.altarama.com/config/exchange/reftracker/schema/rqform_basic.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="basic">
        <xs:annotation>
            <xs:documentation>Basic Shortest Request Form</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:sequence>
                <xs:element name="control">
                    <xs:annotation>
                        <xs:documentation>control</xs:documentation>
                    </xs:annotation>
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element minOccurs="1" maxOccurs="1" fixed="40" name="record_type">
                                <xs:annotation>
                                    <xs:documentation>Record type</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="2" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="1" maxOccurs="1" fixed="basic" name="request_form">
                                <xs:annotation>
                                    <xs:documentation>Request form key</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="20" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="1" maxOccurs="1" fixed="2" name="schema_version">
                                <xs:annotation>
                                    <xs:documentation>Schema version</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="3" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="source">
                    <xs:annotation>
                        <xs:documentation>source</xs:documentation>
                    </xs:annotation>
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element minOccurs="0" maxOccurs="1" name="address">
                                <xs:annotation>
                                    <xs:documentation>Web address (URL)</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="0" maxOccurs="1" name="contact_email">
                                <xs:annotation>
                                    <xs:documentation>Contact email</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="0" maxOccurs="1" name="contact_name">
                                <xs:annotation>
                                    <xs:documentation>Contact name</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="0" maxOccurs="1" name="contact_phone">
                                <xs:annotation>
                                    <xs:documentation>Contact phone</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="0" maxOccurs="1" name="organisation">
                                <xs:annotation>
                                    <xs:documentation>Organisation</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element minOccurs="0" maxOccurs="1" name="record_number">
                                <xs:annotation>
                                    <xs:documentation>Record number</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
                <xs:element name="division_1">
                    <xs:annotation>
                        <xs:documentation>Basic Request</xs:documentation>
                    </xs:annotation>
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element id="clname" minOccurs="1" maxOccurs="1" name="client_name">
                                <xs:annotation>
                                    <xs:documentation>Name</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="200" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element id="cleml" minOccurs="1" maxOccurs="1" name="client_email">
                                <xs:annotation>
                                    <xs:documentation>Please enter your email address</xs:documentation>
                                </xs:annotation>
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:maxLength value="2000" />
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                            <xs:element id="qntext" minOccurs="1" maxOccurs="1" name="question_text" type="xs:string">
                                <xs:annotation>
                                    <xs:documentation>Please describe how we can help you</xs:documentation>
                                </xs:annotation>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Example response – failed (status=200)

<?xml version=”1.0″ encoding=”utf-8″?>

<result>Request form is unavailable.xbasic</result>

</RefTrackerResponse>

RequestFormXMLExample:-

The RequestFormXMLExample will return a set of XML that will create a valid question for the form key provided in the parameter (the form key can be validated using AvailableForms). The values that are valid for each field in this XML can be determined using RequestFormXSD.

Note that this information can also be obtained from within RefTracker by going to System>Request form summary>Requester service> and the request form that you want this information for. Then choose Preview mode in the top right of the screen and in that screen, on the same line as the Request form name, you will see a [View sample XML] link that shows this information (as well as two other helpful links re API information – [View parsed XSD] and [View XSD Schema])

Method: requestFormXMLExample

Format: JSON

Type: GET

Description: gets an example XML record for specified request form key

Response: XML Record

Parameter	Description
apikey	get from parameter 9.56
key	RefTracker request form key

Example call

Example response – success

<?xml version=”1.0″ encoding=”utf-8″?>

<record_type>40</record_type>

<request_form>basic</request_form>

<schema_version>2</schema_version>

</control>

<address>address1</address>

<contact_email>contact_email1</contact_email>

<contact_name>contact_name1</contact_name>

<contact_phone>contact_phone1</contact_phone>

<organisation>organisation1</organisation>

<record_number>record_number1</record_number>

</source>

<division_1 xmlns=””>

<client_name>client_name1</client_name>

<client_email>client_email1</client_email>

<question_text>question_text1</question_text>

</division_1>

</basic>

Example response – failed (status=200)

<?xml version=”1.0″ encoding=”utf-8″?>

<result>No request form found for this key xbasic</result>

</RefTrackerResponse>

AddQuestion:-

The RefTracker API web service accepts a new question in the format defined by the RequestFormXSD and RequestFormXMLExample definitions for Request form that you want to use (see the link to this information in System>Request form summary and Preview mode for that form).

AddQuestion should be used when you need to create a question with a lot of different sorts of data, via the API. If you only need to create a simple question, the quickQuestion operation (see the separate definition for quickQuestion below in this page) might be all that you need.

Posting a record to RefTracker using AddQuestion

Use the addQuestion method to GET or POST the XML record. It creates a RefTracker question using the data provided in your XML record.

We highly recommend the use of POST as addQuestion may require large amounts of data to be sent, that are not supported for GET (as the querystring for GET may exceed the maximum length specified by IIS).

Diagnosing issues with AddQuestion

There are hyperlinks to

View XSD schema View parsed XSD and View sample XML

in the top of each Request form design page Preview mode in RefTracker, showing the direct relationship between the form and these API functions.

Method: addQuestion

Format: XML

Type: GET or (preferrably) POST

Security: Enable parameter 9.51 and, for security, set a key for it (unless you are operating in a total secure environment). If you set a key, ensure that the apikey parameter in parameter 9.51 is included in all calls to this method
NB APIkey must be added as a field anywhere in the XML record. In the green location NOT the yellow location.

Response: XML record confirming the record number created, or error detected

Parameter	Description
XMLRecord	XML record formatted to match structure required by RefTracker request form see: requestFormXSD & requestFormXMLExample

Here is an example of a record being added using POST (the recommended method)

POST /{YourRefTrackerDomain}/exchange/api.asmx/addQuestion HTTP/1.1

Host: localhost

Content-Type: application/x-www-form-urlencoded

Cache-Control: no-cache

Postman-Token: 65509af0-f10e-bdcc-c464-d7f3daf6afad

XMLRecord= %3CRefShort+xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22+xmlns%3D%22http%3A%2F%2Flocalhost%2FTrunk%2Fconfig%2Fexchange%2Freftracker%2Fschema%2Frqform_RefShort.xsd%22%3E+%3Ccontrol+xmlns%3D%22%22%3E+%3Crecord_type%3E40%3C%2Frecord_type%3E+%3Crequest_form%3ERefShort%3C%2Frequest_form%3E+%3Cschema_version%3E2%3C%2Fschema_version%3E+%3C%2Fcontrol%3E+%3Csource+xmlns%3D%22%22%3E+%3Caddress%3Eaddress1%3C%2Faddress%3E+%3Ccontact_email%3Eopusinfo%40bigpond.com%3C%2Fcontact_email%3E+%3Ccontact_name%3EAlex%3C%2Fcontact_name%3E+%3Ccontact_phone%3E123%3C%2Fcontact_phone%3E++%3Crecord_number%3Erecord_number1%3C%2Frecord_number%3E+%3C%2Fsource%3E+%3Cdivision_1+xmlns%3D%22%22%3E+%3Cclient_email%3Ehollandiax%40gmail.com%3C%2Fclient_email%3E+%3Cclient_response%3E1%3C%2Fclient_response%3E+%3Cclient_name%3EAlex%3C%2Fclient_name%3E+%3Cquestion_useful_date%3E1900-01-01%3C%2Fquestion_useful_date%3E+%3Cclient_address2%3EThe+Pines%3C%2Fclient_address2%3E+%3C%2Fdivision_1%3E+%3Cdivision_2+xmlns%3D%22%22%3E+%3Cquestion_text%3EHow+many+miles+must+a+man%3C%2Fquestion_text%3E+%3Cquestion_request%3E123%3C%2Fquestion_request%3E+%3Cclient_email_cc%3Eaholland%40altarama.com%3C%2Fclient_email_cc%3E+%3C%2Fdivision_2%3E+%3C%2FRefShort%3E

Here is the same example of a record being added with a GET in a secure environment (no APIkey required)

GET /trunk/exchange/api.asmx/addQuestion?XMLRecord=<RefShort xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns=”http://localhost/Trunk/config/exchange/reftracker/schema/rqform_RefShort.xsd“> <control xmlns=””> <record_type>40</record_type> <request_form>RefShort</request_form> <schema_version>2</schema_version> </control> <source xmlns=””> <address>address1</address> <contact_email>opusinfo@bigpond.com</contact_email> <contact_name>Alex</contact_name> <contact_phone>123</contact_phone> <record_number>record_number1</record_number> </source> <division_1 xmlns=””> <client_email>hollandiax@gmail.com</client_email> <client_response>1</client_response> <client_name>Alex</client_name> <question_useful_date>1900-01-01</question_useful_date> <client_address2>The Pines</client_address2> </division_1> <division_2 xmlns=””> <question_text>How many miles must a man</question_text> <question_request>123</question_request> <client_email_cc>aholland@altarama.com</client_email_cc> </division_2> </RefShort> HTTP/1.1

Host: localhost

Cache-Control: no-cache

Postman-Token: 5a668f13-0c22-bc29-14d2-1d98f53c79f0

Example XML record with APIkey included

http://currentrelease.altarama.com/exchange/api.asmx/addQuestion?XMLRecord=<Digitise xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns=”https://currentrelease.altarama.com/config/exchange/reftracker/schema/rqform_Digitise.xsd”>

<record_type>40</record_type>

<request_form>Digitise</request_form>

<schema_version>2</schema_version>

</control>

<division_1 xmlns=””>

<apikey>DkfRSLZHGkEf2v2p5lQiCQ</apikey>

<client_name>Alex</client_name>

<client_email>opusinfo@bigpond.com</client_email>

<client_phone>123</client_phone>

<question_age>42</question_age>

<bib_title>Hard Times</bib_title>

<bib_author>Dickens</bib_author>

<bib_callno>ABC</bib_callno>

<question_usefor>Testing</question_usefor>

</division_1>

</Digitise>

Example response records – successful (status = 100)

<?xml version=”1.0″ encoding=”utf-8″?>

<result>Question PROB6564 added to Alex Library</result>

<question_id>5534</question_id>

<question_no>PROB6564</question_no>

<question_useful_date code=”101″>Date must be in the future ‘1900-01-01 00:00:00’ – ignored</question_useful_date>

</warning>

</RefTrackerResponse>

<?xml version=”1.0″ encoding=”utf-8″?>

<result>Question PROB6565 added to Alex Library</result>

<question_id>5535</question_id>

<question_no>PROB6565</question_no>

<client_response code=”103″>Replaced invalid code ’91’ with default value ‘1’ (Email)</client_response>

<question_useful_date code=”101″>Date must be in the future ‘2016-12-01 00:00:00’ – ignored</question_useful_date>

</warning>

</RefTrackerResponse>

Example response – failed validation (status=200)

<?xml version=”1.0″ encoding=”utf-8″?>

<result>Unable to add question – input data does not pass validation | Critical errors found – question could not be created</result>

<client_response code=”103″>Replaced invalid code ’91’ with default value ‘1’ (Email)</client_response>

<question_useful_date code=”101″>Invalid date ignored ‘2016-13-01′</question_useful_date>

</warning>

<error>

<question_text code=”100″>Required field missing ‘question_text'</question_text>

<client_email code=”35″>Email address field contains spaces (use ; to separate more than one address)</client_email>

<question_text code=”40″>Required field is missing</question_text>

</error>

</RefTrackerResponse>

Encoding

Please note: if any of the fields submitted via the AddQuestion API contain HTML, that field must first be HTML encoded, and then URL encoded prior to submission, in order for RefTracker to accept the HTML as part of the field.

Example:

HTML

<html lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset="utf-8" /> <title>Test Title</title> <script>console.log('hello')</script> </head> <body> <p>Hello world</p> </body> </html>

HTML Encoded

%26lt%3Bhtml%20lang%3D%26quot%3Ben%26quot%3B%20xmlns%3D%26quot%3Bhttp%3A%2F%2Fwww.w3.org%2F1999%2Fxhtml%26quot%3B%26gt%3B%

20%26lt%3Bhead%26gt%3B%20%26lt%3Bmeta%20charset%3D%26quot%3Butf-8%26quot%3B%20%2F%26gt%3B%20%26lt%3Btitle%26gt%3BTest Title%26lt%3B%2Ftitle%26gt%3B%20%26lt%3Bscript%26gt%3Bconsole.log(%27hello%27)%26lt%3B%2Fscript%26gt%3B%20%26lt%3B%2Fhead%26gt%3B%20%26lt%3Bbody%26gt%3B%20%26lt%3Bp%26gt%3BHello%20world%26lt%3B%2Fp%26gt%3B%20%26lt%3B%2Fbody%26gt%3B%20%26lt%3B%2Fhtml%26gt%3B

URL Encoded

<html lang="en" xmlns="http:

//www.w3.org/1999/xhtml&quot;&gt; &lt;head&gt; &lt;meta charset=&quot;utf-8&quot; /&gt; &lt;title&gt;Test Title&lt;/title&gt; &lt;script&gt;console.log('hello')&lt;/script&gt; &lt;/head&gt; &lt;body&gt; &lt;p&gt;Hello world&lt;/p&gt; &lt;/body&gt; &lt;/html&gt;

The XML record submitted would look something like this:

Now that the data has been encoded, RefTracker can then import/display the data as originally intended:

QuickQuestion:-

The QuickQuestion method was created for the RefTracker API, but it can be used for submitting any simple question that uses only the fields allowed for by the QuickQuestion widget request form.
Programmers can use this new API function without using the RefTracker provided QuickQuestion widget – they just need to use an HTTP get call to httpx://{domain}/exchange/api.asmx/quickQuestion and pass the parameters in a JSON string like this –

$.get(rtqqwidgethost + ‘/exchange/api.asmx/quickQuestion’, { parameters: {“client_email”:”aholland@altarama.com“,”client_name”:”Alex Holland”,”client_meetingroom_address”:”https://gotomeet.me/Alex Holland”,”question_subject”:”Test subject”,”question_text”:”Test Request text”} },

This creates a question using the Quick Question Widget form, that is used with the widget. These are the only available parameters, and some may not be applicable if not in use by the Quick Question Widget form in your RefTracker system.

Please see the RefTracker widget setup help page for further information about setting up the QuickQuestion widget. Use the above information in place of the RefTracker widget.

The input is a parameter named parameters which must be a JSON string
Output is a JSON string
The APIkey required is set in parameter 9.50

Example quickQuestion call:

https://currentrelease.altarama.com/exchange/api.asmx/quickQuestion?parameters={"client_email":"opusinfo@bigpond.com","client_name":"Alex","question_subject":"Test","question_text":"Test question","mode":"2","sims":"0","apikey":"12345abcdef"}

Example output:

[{"content":"","result":"AC2365","status":"100"}]

Available Categories:-

The availableCategories operation will return the category Name, ID, and Number of questions assigned to that category for all of the enabled Categories. An example use for this function might be to include a word wheel into your web site that provides a visual way to access the KB entries in your RefTracker database.

Method: categories

Format: JSON

Type: GET

Description: gets a list of category records with associated count of questions (KB Only)

Response: JSON string

Parameter	Description
{none} other than APIkey from parameter 9.56

Example call

https://patchaus.altarama.com/exchange/api.asmx/categories?parameters={"apikey":"6NqumTb3CkOVGEPa5ykuXQ"}

Example response – successful

[{"category_count":"7","category_desc":"Applied science","category_id":"23"},{"category_count":"13","category_desc":"Arts","category_id":"3"},{"category_count":"9","category_desc":"Australian History","category_id":"26"},{"category_count":"8","category_desc":"Education","category_id":"13"},{"category_count":"5","category_desc":"History of the world","category_id":"25"},{"category_count":"3","category_desc":"Humanities","category_id":"24"},{"category_count":"1","category_desc":"Physical sciences","category_id":"22"},{"category_count":"2","category_desc":"Staff FAQ","category_id":"10"}]

ClientAction:-

The clientAction operation will return either confirmation that the client has previously submitted requests, or a link that will show all the client’s previously submitted requests if they have submitted them. An example use for this function might be to allow the “View all my request” screen to be integrated into a library’s client interface.

Method: clientAction

Format: JSON

Type: GET

Description: shows if requests already exist for this client and can provide a URL that links to the “View all my requests” page

Security: Enable parameter 9.55 and, for security, set a key for it (unless you are operating in a total secure environment). If you set a key, ensure that the apikey parameter in parameter 9.55 is included in all calls to this method

Response: JSON string

Parameter	Description
{apikey}	from parameter 9.55
{action} with possible values: questionsemail questionslink	returns 100 if previous requests exist returns the URL of the “View all my request” page for that client based on thier email address
{email address}	client’s email address

Example call using questionsemail parameter

https://patchaus.altarama.com/exchange/api.asmx/clientAction?parameters={"apikey":"eZb4QWW3YU63qrXEHxlGhQ","action":"questionsemail","emailaddress":"opusinfo@bigpond.com"}

Example response – successful

[{"result":"","status":"100"}]

https://patchaus.altarama.com/exchange/api.asmx/clientAction?parameters={"apikey":"eZb4QWW3YU63qrXEHxlGhQ","action":"questionslink","emailaddress":"opusinfo@bigpond.com"}

Codetable:-

The codetable API call can be used to retrieve the codetable values for any of the Code tables in RefTracker. An example use of this API operation is to automatically build the advanced search feature like we have provided in the API Widget.

Method: codetable

Format: JSON

Type: GET

Description: gets a list of records for specified code table

Response: JSON string

Parameter	Description
codetable	Code table name
apikey	Get the key from parameter 9.56

Example call

https://patchaus.altarama.com/exchange/api.asmx/codetable?parameters={"apikey":"6NqumTb3CkOVGEPa5ykuXQ","codetable":"location"}

Example response – successful

[{“code”:”1″,”default”:”1″,”description”:”Sydney”},{“code”:”60″,”default”:”0″,”description”:”United Kingdom”},{“code”:”45″,”default”:”0″,”description”:”Perth”},{“code”:”44″,”default”:”0″,”description”:”New Zealand/大會堂公共圖書館”},{“code”:”43″,”default”:”0″,”description”:”Altarama West USA”},{“code”:”37″,”default”:”0″,”description”:”Casablanca”},{“code”:”17″,”default”:”0″,”description”:”Cairo”},{“code”:”39″,”default”:”0″,”description”:”Altarama East USA”},{“code”:”41″,”default”:”0″,”description”:”NLA Reference team”},{“code”:”42″,”default”:”0″,”description”:”Altarama Mountain USA”}]

Extract:-

This Extract API method allows the parameter set in a Saved Data extract to be started by a JSON parameter string submitted to the RefTracker API, and the resulting data to be reported back as an XML string. This has been provided in order to allow RefTracker data extracts to be provided at any time, to other applications running on other computer systems. It is often used to allow analysis of data held in RefTracker full question records, or DeskStats, by other applications such as corporate Business intelligence applications e.g. Power BI.

Not that the timeout for this API method is 20 minutes, so it can be used to extract large files of data (for example, for year of year comparisons).

How to set up your Data extract for use with this API Data extract function

Here is an example saved Data extract with key m3EKMMkijdyuBQr5

Choose your Data extract parameters as normal in order to obtain the records you want to extract (see the Reporting – Data extract help pages for more details about selecting these parameters). Pay special attention to the following parameters that are particularly relevant to this use:

Unformatted: Choose Formatted to bring across the descriptions of code table entries, or Unformatted to just have the code table numbers included.
Formatted (default) data provides code table information using the description for the relevant code table entry. This option is the one to use when the output data needs to be viewed by humans!
Unformatted data just provides the code table’s numerical value. You may want to use this option when the output data will be used by another application. It also results in a smaller data set because the code table fields will just contain a number, not a description.

Sample only: Tick the “Sample only” box to limit the displayed output to the first 25 records only. This is very helpful when testing this extract processs, so you don’t have to wait for large data sets to download! Its also useful for displaying scheduled reports/extracts where you don’t want to have the entire report run before you see what it does! It is only applicable when Output method is display, and will not stop the full data output from being sent via the API.

Convert HTML to text: This parameter allows you to determine if you want the HTML in fields like Question and Answer, included in the output, or whether you would rather see plain text. Excel can format the HTML nicely and for Excel output the default unticked option is the right selection here. But CSV will display the HTML code rather than formatting it. Further, HTML formatted output can take more room than standard text and that may also be a reason why you may want your Data extract output in text format rather than HTML. If you are exporting the data for use in another HTML compliant system you may want to include the HTML and so leave the “Convert HTML to text” reporting parameter unticked, but if you want a human readable output you may prefer to tick the new “Convert HTML to text” parameter.

How to use this API Data Extract method

When you save a Data extract definition – it is assigned a unique Extract key.

This API Extract web method will accept a JSON formatted parameter string, that uses a stored Data extract definition with the specified key, via the following parameters:

APIkey – Get the API security key from parameter 9.54
Key – Mandatory – this is the key for the Data extract saved parameters set, as shown in the screen above at the yellow highlighted position. The saved parameters are found at Reporting>Data Extract>and then the name of the saved Data extract report that you want to be able to run remotely.
If no Startdate and Enddate parameters are specified in the API call, the date parameters in this saved parameter set will be used. If Startdate and Enddate parameters are specified in the API call, they will override the date parameters saved in this parameter set.
The output data will be formatted according to the location of the user that owns this saved extract defined in the specified key, so dates and times will be in that user’s time zone, and any Startdate and Enddate parameters will be taken to be in that user’s time zone.
Startdate – Optional – The Startdate (and optionally time) for this run of these parameters. If Startdate is provided, Enddate must also be provided. The specified date and time will be presumed to be in the time zone of the staff member who saved the Data extract stored parameters. Startdate should be provided in ISO format.
Enddate – Optional – The Enddate (and optionally time) for this run of these parameters. If Enddate is provided, Startdate must also be provided. The specified date and time will be presumed to be in the time zone of the staff member who saved the Data extract stored parameters. Enddate should be provided in ISO format.

Example parameters for this API type:

https://patchaus.altarama.com/exchange/api.asmx/extract?parameters={"apikey":"kRjqsFe0v06wpxV0qw3D2g","key":"BBHaVVlRke8smHdR"}

. . . {“key”:”ukey419″,”startdate”:”2021-02-01″,”enddate”:”2021-02-28″}
. . . {“key”:”ukey419″,”startdate”:”2021-02-01″,”enddate”:”2021-02-28 15:30″}

Output
You can test this function at:
https://{YourRefTrackerDomain}/exchange/api.asmx then choose the Extract option in that screen.

Calling this method will result in a JSON formatted data set – using the parameters associated with the specified key (and any Startdate and Enddate parameters).

The dataset contains two data tables.

The first data table (named “Columns”) contains a value for each field in the Extract data and the caption (label) for that RefTracker field name. Use the Caption for your data column headings.

The second table (named using the name these Data extract saved parameters were saved under) holds the actual data – RefTracker field name and data value.

Dates and times in the report will be in the Time zone of the user who saved the parameters for the Data extract key being run.

Here is an example using the POSTMAN tool – which can display the JSON string indented.

You can see a sample of the “Columns” data table:

and a sample of the “Example_Alpha” data table that goes with it because the name of the extract with this key is Alpha:

Search:-

The search operation can be used to retrieve questions by category, request type, request group, or location.

The search operation has an additional parameter that has to be included in order to specify the subset of questions that should be returned. This parameter should be a JSON formatted string. While none of the fields specified in the JSON string are required, the results returned are directly affected by the parameters provided in this JSON string.

Method: search

Format: JSON

Type: GET

Description: gets a list of records for specified code table

Security: Enable parameter 9.53 and, for security, set a key for it (unless you are operating in a total secure environment). If you set a key, ensure that the apikey parameter in parameter 9.53 is included in all calls to this method

Response: JSON record

Parameter	Description
parameters	JSON string of parameters

Parameter keys

Key	Description	Example
apikey	Security key	get from parameter 9.53
Address	get all questions where client address fields contain search term	“address”:”braidwood”
Category	get all questions associated with the specified categories Id(s)	“category”:”10\|3″
ClientLocation	get all questions where client location is specified id	“clientLocation”:”40″
ClientName	get all questions where client name fields contain search term	“clientName”:”alex”
Database	Specifies database 1=work, 2=KB, 3=FAQ	“database”:”1″
dateclass	Specifies receipt date range relative to now. today=1000, yesterday=1100, thisweek=2000, lastweek=2100, thismonth=3000, lastmonth = 3100, thisquarter=4000, lastquarter=4100, thisyear=6000, lastyear=6100	“dateclass”:”3000″
Email	get all questions where client email fields contain search term	“email”:”aholland”
Phone	get all questions where client phone fields contain search term	“phone”:”123″
QuestionNo	get all questions where question number matches specified parameters. Beginning question No, part question number with wild card, beginning and end question no	“questionNo”:”PROB1234″ “questionNo”:”PROB12*” “questionNo”:”PROB1234\|PROB3333″
requestForm	get all questions with specified request form ID(s)	“requestform”:”7\|3″
RequestGroup	get all questions with specified request group ID(s)	“requestgroup”:”5\|1″
RequestType	get all questions with specified request type ID(s)	“requesttype”:”114\|120″
staff	get all question for specified staff ID	“staff”:”25″
StaffLocation	get all questions where staff location is specified id	“staffLocation”:”1″
status	get all questions for specified status ID	“status”:”010″
statusCategory	get all questions for specified statusGroup ID(s)	“statusgroup”:”100\|600″
ScopeList	question = 100 answer = 200 client = 300 bib_ill = 400 Note = 500	“scopelist”:”100\|200″
Text	search term for full-text searching – scope is determined by setting scope flags	“text”:”book”
columnList	specifies list of columns to be returned (from question,client,bib,ill tables)	“columnList”:”client_address1\|client_address2\|client_email\|client_name\|question_no\|question_text\|question_answer”
expansweratts	Include answer attachments	“expansweratts”:”1″
expcategories	Include categories string	“expcategories”:”1″
expjournaltotals	Include journal total fields	“expjournaltotals”:”1″
expquestionatts	Include question attachments	“expquestionatts”:”1″
expresources	Include resources string	“expresources”:”1″
expnotes	Include notes	“expnotes”:”1”
pageNumber	Which page to retrieve	“pagenumber”:”1″
pageSize	Number of records per page	“pagesize”:”10″
SortBy	ResponseDate = 1 ReceivedDate = 2 ClosedDate = 3 FAQDate = 8 KBDate = 9 questionNo = 50	“sortby”:”50″
SortOrder	Order of sort ASC DESC	“sortorder”:”ASC”

Example call

https://currentrelease.altarama.com/exchange/api.asmx/search?parameters={"expresources":"1","pagesize":"10","db":1,"text":"test","expcategories":"1","pagenumber":"1","expansweratts":"0","scopeanswer":"1","scopequestion":"1","columnList":"question_no|question_text|question_answer|staff_name|reqform_key|question_datetime","expjournaltotals":"1","apikey":"onG1WoSxHE2i7b0l69s0pA"}

Example response – successful

{

“question_answer”: “CLOSED\r\n”,

“question_categories”: “”,

“question_datetime”: “2015-06-09 20:39:25.0-04:00”,

“question_journalamount”: “”,

“question_journaltime”: “00:00”,

“question_no”: “AC2124”,

“question_resources”: “”,

“question_text”: “test”,

“reqform_key”: “HuntRQ”,

“search_page”: “1”,

“search_page_size”: “10”,

“search_row”: “1”,

“search_score”: “15240”,

“search_total”: “55”,

“staff_name”: “Shirley Forster”

{

“question_answer”: “.Test”,

“question_categories”: “”,

“question_datetime”: “2022-12-19 14:57:48.0-05:00”,

“question_journalamount”: “$0.00”,

“question_journaltime”: “00:01”,

“question_no”: “AC2362”,

“question_resources”: “Books in Print “,

“question_text”: “Test”,

“reqform_key”: “Record”,

“search_page”: “1”,

“search_page_size”: “10”,

“search_row”: “2”,

“search_score”: “10224”,

“search_total”: “55”,

“staff_name”: “Sausage Sandwich”

getQuestion:-

The getQuestion API call can be used to retrieve the details of a specific question.

Method: getQuestion

Format: JSON

Type: GET

Description: gets a record for a specific question

Security: Enable parameter 9.52 and, for security, set a key for it (unless you are operating in a total secure environment). If you set a key, ensure that the apikey parameter in parameter 9.52 is included in all calls to this method

Response: XML Record (default) or JSON if format parameter specifies JSON

Parameter	Description
parameters	JSON string of parameters

Parameter keys

Key	Description	Example
apikey	Security key	get this from parameter 9.52
key	Column name	“key”:”question_no” “key”:”question_id”
value	Search term	“value”:”PROB1234” “value”:”126549”
format	Response format json/XML	“format”:”json”“format”:”xml”
columnList	specifies list of columns to be returned (from question,client,bib,ill tables)If not specified all columns are returned	“columnList”:”client_address1\|client_address2\|client_email\|client_name\|question_no\|question_text\|question_answer”

Note

By default the exported record will include

Answer attachments
Question attachments
Categories
Resources
Journal totals
Notes

Examples

 https://patchaus.altarama.com/exchange/api.asmx/getQuestion?parameters={"apikey":"Fbo7iYKPUkuQMJurlVPwgA","key":"question_no","value":"PROB9600"} 

https://patchaus.altarama.com/exchange/api.asmx/getQuestion?parameters={"apikey":"Fbo7iYKPUkuQMJurlVPwgA","key":"question_no","value":"PROB9600","format":"json"}

/{YourRefTrackerDomain}/exchange/api.asmx/search?parameters={“key”:”question_no”,”value”:”PROB5784″,”format”:”json”,”columnList”:”question_no|question_text|question_answer|question_staff|question_reqform_id|question_datetime”}

/{YourRefTrackerDomain}trunk/exchange/api.asmx/search?parameters={“key”:”question_no”,”value”:”PROB5784″,”format”:”xml”}

Example response – successful

<?xml version=”1.0″ encoding=”utf-8″?>

<record_id>4768</record_id>

<record_type>30</record_type>

<record_version>3.3.4.0</record_version>

<schema_version>1</schema_version>

</control>

<address>localhost</address>

<organisation>Alex Library</organisation>

<record_number>PROB5784</record_number>

</source>

<answer label=”Answer”><span style=”color: #333333; font-family: ‘Guardian Text Egyptian Web’, Georgia, serif; font-size: medium;”>Researchers in Massachusetts this week captured footage of a great white shark feasting on a minke whale carcass, off the coast of Cape Cod. The sighting led to the temporary and precautionary </span><a href=”http://www.capecodtimes.com/news/20160805/sharks-feed-on-whale-off-truro-prompt-beach-closings” data-link-name=”in body link” class=”u-underline” style=”background-image: initial; background-position: initial; background-size: initial; background-repeat: initial; background-attachment: initial; background-origin: initial; background-clip: initial; touch-action: manipulation; color: #005689; cursor: pointer; border-bottom: 0.0625rem solid #dcdcdc; transition: border-color 0.15s ease-out; font-family: ‘Guardian Text Egyptian Web’, Georgia, serif; font-size: medium; text-decoration: none !important;”>closure of three popular tourist beaches</a><span style=”color: #333333; font-family: ‘Guardian Text Egyptian Web’, Georgia, serif; font-size: medium;”>.</span></answer>

<entry_status label=”Entry status”>Complete</entry_status>

<evaluation_date label=”Evaluation date”>2016-01-28T10:31:25+11:00</evaluation_date>

<expertise label=”Expertise test”>Specialised search</expertise>

<faq label=”FAQ Status”>Excluded</faq>

<item_summary label=”Item summary”>Current acoustic alerts used by the WA Department of Fisheries only pick up on tagged sharks and work alongside sightings and patrols.</item_summary>

<kbase label=”KB Status”>Excluded</kbase>

<location label=”Staff location”>Sydney</location>

<location_receipt label=”Receipt location”>Sydney</location_receipt>

<open_date label=”Open date”>2016-01-28T10:31:24+11:00</open_date>

<priority label=”Priority”>Normal</priority>

<progress label=”How complete”>Staff entered</progress>

<qtype label=”Question type”>Question</qtype>

<received label=”Received via”>In person</received>

<request label=”Request type”>Reference special service</request>

<response_date label=”Objective response date”>2016-01-28T11:30:00+11:00</response_date>

<state_flag label=”Archive flag”>1001000000</state_flag>

<status label=”Status”>Allocated</status>

<target_date label=”Target date”>2016-02-07T11:30:00+11:00</target_date>

<text label=”Question”><span style=”color: #111111; font-family: Arial, Helvetica, sans-serif; font-size: 15px; line-height: 16.0008px; background-color: #f9f9f9;”>The buoys’ sonar beams can detect any marine animal over two metres long, according to Perth-based developers, Shark Attack Mitigation Systems.</span></text>

<update_datetime label=”Last updated”>2017-01-24T17:34:23+11:00</update_datetime>

<useful_date label=”Last useful date”>2016-02-07T11:30:00+11:00</useful_date>

</question>

<department label=”Department/Group”>Department A</department>

<email label=”Client email”>aholland@altarama.com</email>

<location label=”Client location”>Sydney</location>

<response label=”Response method”>Email</response>

<udf_cl01 label=”Practice group”>Business law</udf_cl01>

</client>

<bib>

<copies_number label=”Number of copies”>1</copies_number>

<price_actual label=”Actual price”>0.1500</price_actual>

<title label=”Title”>Current acoustic alerts used by the WA Department of Fisheries only pick up on tagged sharks and work alongside sightings and patrols.</title>

</bib>

<name>ddTree_2_Capture.JPG</name>

<type>Question</type>

<location>http://localhost/Trunk/reft301.aspx?guid=0c96154a-a568-4dc5-a30f-4f7ff7ca886f</location>

</attachment>

<name>kinglear.pdf</name>

<type>Answer</type>

<location>http://localhost/Trunk/reft301.aspx?guid=9bd7eea9-2c98-40ed-bb7b-61f381850590</location>

</attachment>

</attachments>

</RefTrackerRecord>

Error response

Some information about API responses that might help to diagnose issue, is logged to the Service log, if that log is turned on (at parameter 80.54)

If a call to the API method is unavailable a response message will be returned

Where possible the HTTP status code will be set to one of the following

200 – OK

400 – Bad request – used then the request to the API method can not be parsed

403 – Access forbidden

404 – Not found – used when a record/object can not be found

500 – Internal server error – used when RefTracker traps an unexpected error

503 – Service unavailable

Examples

<html lang=”en” xmlns=”http://www.w3.org/1999/xhtml“> <head> <meta charset=”utf-8” /> <title>Test Title</title> <script>console.log(‘hello’)</script> </head> <body> <p>Hello world</p> </body> </html>

< Previous Page

List Widget API

Next Page >

Creating a new question using the API