Creating a new question using the API

A programmer is required to use this functionality to allow a new question to be created in RefTracker using this API. 
For example you may have an existing application that gathers information about statutory deposits of new publications, where one of the steps is to request the provision of an ISBN.  With this API you can send the information gathered in that application to RefTracker as a request to your ISBN issuing department (that uses RefTracker for handling ISBN issuing), and receive a RefTracker request number to record in your application, all without a RefTracker request form or confirmation screen showing (so the process appears totally integrated!). 

An important note about security: For simplicity, these examples presume that the appropriate API method has been enabled in the 9.x parameters, and that a key has NOT been set for them (as might be the case for implementation in a secure in-house environment). If you are implementing in an open environment, please ensure that you set APIkeys and include them in all calls, in order to ensure that the API methods that you enable, can ONLY be used by authorised users.

Click here to see more information about the individual API functions used in this process.

In summary the process for creating a question in RefTracker using this API uses the following functions.  How the programmer uses these functions is up to them given the environment in which they are programming:

  1. The AvailableForms function can be used to return a list of valid RefTracker form keys that can be used to determine that the key for the form about to be used to submit the new request, is valid.
  2. The RequestFormXSD function provides a definition of all of the valid fields for a form and the valid values that can be submitted for each of those fields, that can be used to present valid options in a form of your own design, and against which data to be submitted in each field can be validated.
  3. The RequestFormXMLExample function provides example XML that will create a valid question in RefTracker for that form, when presented to RefTracker using the API AddQuestion web service, and given the field information provided by the XSD. 
  4. An AddQuestion function allows valid XML to be submitted to create the question, and the created request number to be received as confirmation.

To use the API to create a question in RefTracker there must be a Request form in RefTracker that this process uses to accept the question.  The Preview mode screen for every form in RefTracker provides links that show the information that an API programmer needs to be able to send requests into RefTracker using that form.  Go to System>Request forms summary and click the Preview link for the form you are using, to see these links.

View XSD schema, shows the XML definition of the valid fields and values for this form – assisting those wanting to create their own form.
View parsed XSD, shows eye readable, field by field information about the valid values that can be submitted.
View sample XML, shows sample XML for submitting a request using this form.

How the programmer uses these functions is up to them given the environment in which they are programming.

An example of how to use the New question creation function of the API

This API is used by the RefChatter to RefTracker integration so that the RefChatter operator can choose the RefTracker form to which a RefChatter transcript needs to be submitted when follow up research is required.

This example uses Postman (freeware app available from https://www.getpostman.com/ ) and the RefTracker site Expresstrial30.

Overview

Each RefTracker system makes a number of Request forms available for submitting details of requests of different types.  The programmer first needs to establish which form from that specific RefTracker system, will be used to submit the question. (requestForms API function)

Each Request form provides a number of fields with valid values for those fields so the next step is to determine what fields are available for that form and what the valid values for those fields are, in that form.  (requestFromXSD API function)

The requestFormXMLExample API function provides example XML for creating a valid question in RefTracker for that form, given the field information provided by the previous XSD step. 

The addQuestion function allows the valid XML, as determine by the previous step, to be POSTed to create the question, and the created request number to be received as confirmation.

Details of how to use the API

1. The requestForms function can be used to return a list of valid RefTracker form keys, and to determine that the key for the form about to be used to submit the new request, is valid.

The API (api.asmx) is normally found in the exchange directory in the RefTracker installation.

So the full URL for our test example becomes:   https://expresstrial30.altarama.com/exchange/api.asmx/requestForms

Use this URL with a GET request to return a list of available RefTracker forms –

This example will use the RefChatter Integration form, with key RCintegration as highlighted above.

2. The requestFormXSD function provides a definition of all of the valid fields for a form and the valid values that can be submitted for each of those fields.  This information can be used to present valid options in a form of your own design, against which data to be submitted in each field can be validated.

Using the example form key from above as a parameter, construct the URL: https://expresstrial30.altarama.com/exchange/api.asmx/requestFormXSD?key=RCintegration

Submit this as a GET request and a full XML Schema Definition (XSD) file for that form will be returned –

The information in this file can then be used to determine data types, element names and data restrictions applicable to this form.

You do not have to submit data for all data elements in the form however you must provide data for all fields in the Control division and all other fields defined as “Must occurs”.  At a minimum the other fields will be at least:  Question text <question_text> and enough client contact details to be able to contact the client if that is required (usually at least <client_email>).

3. The requestFormXMLExample function provides example XML that will create a valid question in RefTracker for that form, when presented to RefTracker using the API addQuestion web service, and given the field information provided by the XSD. 

Using the example form key from above as a parameter, construct the URL: https://expresstrial30.altarama.com/exchange/api.asmx/ requestFormXMLExample?key=RCintegration

Submit this as a GET request and a full example XML file for that form will be returned –

4. The addQuestion function allows valid XML to be submitted to create the question, and the created request number to be received as confirmation.

Copy the complete XML text from above and paste into a text editor (e.g. Notepad), and remove the superfluous and example text highlighted below –


Replace it with the question specific text as highlighted below –

N.B. Due to the size limitation on GET requests, it is necessary to use a POST request for this operation. i.e. the request must be in the body of the request html.

Using Postman, select POST, Body and x-www-form-urlencoded.

In the URL text box, paste the full addQuestion method location.

In the KEY column, type in “XMLRecord“.

In the VALUE column, paste the entire edited XML record from above.

This generates a valid example POST in the format required for the specific Request form used he

Click Send and a response will be returned with the newly created question number.

This is an example of the response you will receive from a valid addQuestion –

If access to the RefTracker application is available:

View the Details screen (under Summary) for that question number in RefTracker and the full entry for the question created in RefTracker will be displayed –