This webpage serves as a repository for all of the available database calls available to developers of herd recording systems. The provided endpoints can be used to send data for animal events.
In short, each link on the left has a resource URL to make a POST request to. With the exception of the 'Auth/Logon' procedure, which provides an authentication token, each call will require the following:
An authorization token. Most calls will reject a request unless this is provided and valid.
Send this as a Authorization header with the value Bearer $authToken, where `$authToken` is the value returned upon logging in.
Each call has a set of input parameters, listed under the input parameters table.
The datatype represents what kind of value you should send. Typings are generally not rigidly enforced, however.
The only exception to this is the `array` value type, which expects an array of data. Most http libraries will handle this automatically. If it does not, you'll need to send post data as such: ($param being the parameter)
This document provides a convenient how-to on connecting to the PICTraq API, authenticating with the service, and testing calls before implementing them in your application. This tutorial will take you through a very basic walkthrough of logging in, getting an authentication token, then making other calls to the API.
Contents
Installing an API Testing Tool
For the purposes of this tutorial, we will be using a tool called the Advanced REST Tool,
herein referred to as "ARC". It's an application in Google Chrome that simplifies testing
requests to the web service before implementing them in your application.
Get the ARC here. Follow the prompts to add the application to Chrome.
Your browser should automatically open a new tab at chrome://apps. Navigate there otherwise if it doesn't. You should see a blue icon with a white arrow pointing up, and a darker arrow pointing down titled ARC. Click it to launch ARC.
Using ARC
When you launch ARC for the first time, the application will notify you of new changes. You can either view them or skip it via the "Skip" button at the bottom.
Once you skip this, you'll be greeted with the following:
Key
Most work is done in this tab, as this lets you issue requests.
Requests you save for easy usage later will end up here.
The application keeps a history of what requests you have made here
Click this button to save your request. Useful if you want to quickly test multiple requests later.
Request URL goes here. These are under the "Resource URL" section on each documentation page.
Request Type information is here. This should be set to POST.
The content type for the request. The following table shows the return types for each type in the drop-down list:
Content Type
Response Format
application/x-www-form-urlencoded
JSON. Recommended as it allows the use of the data form for testing purposes.
application/xml
XML
application/json
JSON
Any other type
JSON
A form for setting HTTP headers. Only a few of these are needed, namely the Content-Type header (which is set automatically by the dropdown at (7)), and the Authorization header.
The payload form. Allows you to send data to the server in two forms: As a key-value-paired form, or as a raw payload. If sent as a raw payload, send it in the following format: key1=value1&key2=value2&key3=value3...
Send button. Click this button to submit the request.
Understanding the Documentation
Before you can use the API, it is useful to understand the documentation this site provides. Before continuing to do other calls, we need to log in first. The documentation for this procedure is under the Auth/ grouping in the sidebar as the Logon/ item. Clicking Auth/Logon/ gives the following:
Each sidebar item, when clicked, has the following items:
Header
Description
Resource URL
The URL that API calls need to be made to
Description
Short description of what the procedure does.
Input Parameters
A listing of input parameters that should be sent to the url. Check the appendix for a description on these fields.
Returned Parameters
A listing of parameters that the server responds with. Check the appendix for a description on these fields.
Input Example
An example request body sent to the server. Check the appendix for the proper format. Not yet implemented.
Output Example
An example response the server will respond with. Not yet implemented
Logging into the API
Nearly all endpoints on the API require a valid authorization token, or else they wll reject the request. By logging in with the Auth/Logon procedure, you can then access other database calls.
Fill out the Request tab in the ARC as follows:
Key
The URL to which you'll be sending login details
Headers needed. This is probably set automatically by choosing the content type from the drop-down menu.
Username and Password fields. As the documentation requires a username and password variable, we set those variables with their respective values. For sending it as a raw payload, see the "Sending Data via POST" section in the appendix.
Submit button. Once everything is set, click this to submit the login request.
Once you submit the request, if a valid username and password was sent, you'll get a response similar to this:
If the login was successful, it'll return an authentication token. This will need to be stored in memory and used in future calls, described in the next section. If the login failed, however, the API will respond with a message as to why it failed. Usually this is due to an incorrect password.
Example API Calls: Uploading new Matings into PICTraq.
Get Farm Events
Now that you have logged in and received an authentication token, you can make calls to other endpoints in the API. The first step in uploading data to the events tab is getting all available events, via Herd/Events/getFarmEvents
Clicking on Herd/Events/getFarmEvents will show everything smilar to the example given in the "Understanding the Documentation" section of this tutorial.
Using the same approach as from before, we can set up the call as follows. For demonstration purposes, we are calling the events for farm 6802, which is a test farm:
There is two differences, however. We've added a new header: Authorization. Any non-login endpoint calls need the Authorization header set to the value Bearer $authorizationToken, where $authorizationToken is the token received in the login procedure. The server will return a 401 error (Unauthorized) if you do not send this. We have also checked the "Use XHR" switch at the top of the application, as we need to send this as an http request. Every call forward must be sent as such.
In any case, if the call is successful, you'll get this kind of response that has all of the farm's available events:
Get a Farm Event's Traits
Now that we have all of the events available for farm 6802, we would like to enter new matings into this farm. In order to do this, we need to update traits for a record. Traits could be anything like a farrow date, pedigree identifier, biological sex, etc. With this in mind, we need to retrieve traits for farmID 6802, our test farm, and eventID 1, which would be matings. After looking at the documentation for Herd/Events/getEventFarmTraits, the request will look like the following in ARC:
If the call is successful, you'll get traits back in the following format:
Enabling Missing Traits
Before we get the records, we might need to add additional traits so we can enter all of the data we need. This takes two steps: Get all possible traits for the event, and setting needed traits as active.
In order to get all traits, we're going to use a similar call as the previous section. The only difference is that the endpoint is Herd/Events/getEventTraits, and we don't need the farmID. Call this procedure the same way as the previous one, and you'll get a larger list of traits. The response will look very similar to Herd/Events/getEventFarmTraits.
Now that we have all of the traits, we will need to look at the list and compare it with the response from Herd/Events/getEventFarmTraits.
Any missing traits that you need will need to be added via Herd/Events/insertEventFarmTrait. For example, in our matings example, we might want to add the BOTTLES trait, as we'd want to note bottles used in a given mating. Looking at the response, we see an EV_TRAIT_ID of 15, which corresponds with BOTTLES. We then make a call to Herd/Events/insertEventFarmTrait that looks like this:
In any case, usually you'll get a message of SUCCESS back, indicating that the trait was successfully added. If not, usually the trait is already there, or a trait ID wasn't sent.
Get a Farm Event's Records
Now that we have the traits, we can get any active records waiting to be saved for the same farm and event. For this, we use the Herd/Events/getEventValues endpoint of the API. After checking the documentation, the request will look like the following in ARC:
If successful, you'll get a response like this:
At this point, you either get no records back (getting just a record with all the possible response keys with null values), or more than one record, which indicates that there are pending records already there. Inside this response is an EVENT_VALUES_PARSED, which, for each record, has an array of a record's traits and values. We will be using those to update a record (or create a new one).
Update Farm Event's Record / Creating a New Record
We now have all of the available traits for a given farm and event, and all of it's current records. From here, there's two options available: Adding a New Record, or Updating an Existing Record.
The same database call is used for either operation. As this is data entry being updated, we need to look at the endpoint for this: Herd/Events/updateEvent.
After reviewing the parameters, regardless of the next step, we know the farmID (6802) and the eventID (1).
The recordID will either be 0 (zero), indicating a new record, or a pre-existing recordID that was returned from Herd/Events/getEventValues.
The last two things we need are a traitID and traitValue.
For example, we would like to create a new record with a new DAM_PED_IDENT, as we want to create a new mating for a given dam. Looking at the traits returned from the previous section, that trait's ID would be 23. We now have the traitID (23). The traitValue is the last thing we need, which the user will supply. With all of that being provided, the request to the endpoint will look as follows:
If the record is considered valid by the database, the message of the response will say VALID. Otherwise, it will return a message stating actions needed to make the record valid. An example response is below:
Notably, the API returned a new REC_ID, or record ID. If you wanted to update the new record, you would use this new REC_ID. Anyways, this step is repeated until you have valid records and would like to save them. As an example, create one record using the following trait IDs and trait values: (First request will use a record ID of 0, following requests will use the record ID the API responds with).
Trait ID
Value
2
T0420
5
16541
7
3
9
2
Removing Uploads
For any number of reasons, an unsaved upload might need to be deleted. To do this:
Invoke the Herd/Events/getEventLoads endpoint, sending your farmID and the eventID. Each row in the response that has a non-null EXCEL_LOAD_ID can be deleted. A load ID of "0" is manually entered data on PICTraq 2.0
Once you have created at least one valid record in total, you will need to save the record, or commit it to the API.
Records are not considered saved until they have been saved via the Herd/Events/saveRecordsDataEntry endpoint.
With this call, the only parameters we need are the farmID and the eventID (6802 and 1, respectively.) In order to test this endpoint, we can just call the endpoint like so:
Send it, and it should return SUCCESS if there are valid records. If you get that message, all valid records have been successfully saved in the API. At this point, it's recommended that another call to Herd/Events/getEventValues is made to update your program's local state and to continue with remaining invalid records.
Uploading Farm Records directly into PICTraq
This section will detail uploading already gathered data directly from your software to an event, e.g. matings. In order for this to work, we need to pair up data into a key-value format the API accepts for this purpose.
Understanding the Upload Data Format
PICTraq's website allows users to upload data to an event directly via Excel files.
The server uses the file's column names to get the proper trait ID's,
then the API pairs them up with each row's values into a string in the following format:
For each record you upload, you will need to have all traits for the event in your dataset enabled. Refer to the instructions in the sections "Get a Farm Event's Traits" and "Enabling Missing Traits" of the tutorial for details on how to do this. Enable the traits you need before going forward.
Creating Trait Strings
For each record, you will need to create trait strings to upload data directly to the database. For each and every row of data, you should do the following:
Look at the corresponding column for each part of the record (such as pedigree ident, sex, mating day, etc) and get the appropriate trait ID. Concatenate it with the value of that field in id@val format.
Join the array of id/value pairings with a @.
Uploading Trait Strings
Finally, after we have constructed the trait strings, we can upload them to the API. While the farm ID and event ID are known in this case, we need to POST an array of values in this case. An easy way to do this is to postfix [] onto the end of the variable name for each entry in the POST data. The API will treat that as an array. A call to Herd/Events/uploadRecordDB will look like this:
The response will either be SUCCESS, meaning the upload worked, or it will return an error message. If successful, you can then make a call to Herd/Events/getEventValues to see the results of the upload.
Case Studies
This section of the documentation has examples on various corner cases.
Contents
Example 1: Correcting an Incorrect Record
The PICTraq Web Service is designed to be herd-recording-system-agnostic and doesn't use primary keys from other systems that connect to it. In order to modify events already entered into the system, a developer can retrieve the existing events for the animal in question, isolate the particular event to modify, retrieve the UPD_KEY for the record in question, and then modify the event using that key.
Example Case
For this example, let's assume that your farm ID is 6802. Sow 100 is mated on 01-DEC-2019. You have a unique ID for the animal in your software. The event is then uploaded to PICTraq. The UPD_KEY for this event is 999.
At this point, one of the two events occur:
The data is wrong and is deleted from your software. A new mating event is entered for 15-DEC-2019.
The data is wrong and changed in your software. The new mating day is 15-DEC-2019.
The event is then uploaded into PICTraq again. In both cases, we need to change the mating date on sow 100. PICTraq sees both cases as the same; the event will need to be deleted from PICTraq and reuploaded with the event corrected.
Get Farm Events
First we need to retrieve all events available for a farm. Since we want to change a mating event, we need the event ID for matings, which is '1', highlighted below.
The response for this, namely the event IDs and names, should never change, so the results of this query can be cached in your application safely.
Explanation: See the documentation in the link above for a full explanation of the columns. Columns to note are the EV_TRAIT_ID and whether EDIT is 0 or 1. If 0, the trait cannot be modified, and the event will need to be deleted/re-entered into PICTraq. For this example we need the following traits:
DAM_STIG (traitID: 2, edit: 0)
MATING_DAY (traitID: 5, edit: 0)
MATING_TYPE (traitID: 7, edit: 1) < required field
SIRE_STIG (traitID: 9, edit: 1) < At least one form of SIRE identification is required.
Upload records to the database
Load up all the trait/value pairs for the events; up to 500 events can be loaded per call. Example:
Explanation: You should get a SUCCESS message back every time confirming the record was successfully uploaded. The next calls are for determining validity of the entered events
Retrieve the uploaded records
This step should be done after the previous step each time for speed reasons.
Explanation: Each record should have a G_MSG of VALID; any records whose G_MSG does not equal "VALID" should be displayed to the user for correction. Once all records are valid, they can be saved in the next step.
Save the uploaded records
All records, and only records with a G_MSG of VALID can now be saved; Example:
Explanation: You should get a SUCCESS message back every time unless one of the parameters are not formatted correctly. At this point, the record is saved in PICTraq and can only be modified through the getVerify and editEvent endpoints.
Get records to edit/verify.
Once step 5 has been completed and the record is in PICTraq, changes to these events are done through the getVerify and editEvent endpoints. The event to edit must first be located, however. In this case study, we realize that the mating entered for 01-DEC-2019 needs to be corrected, so we need to locate that event specifically.
Explanation:
In the startFilter specify the SOW_ID equal to 100; this will return all of the matings for that sow. In the example; we only have one result; but there can be multiple matings. If the trait being edited is true in getEventFarmTraits defined in step #2 above; then you can change that value using the editEvent endPoint. In the case study; you are wanting to edit the mating date which cannot be updated. So; search the mating dates returned and compare against the mating dates in your system. Find the event that does not match and get the UPD_KEY for this event.
Mark records for deletion.
Now that we have the UPD_KEY for the record in question, we can mark it for deletion. Example:
recordID: 0 <-- this will be something else if the row has been edited and a new record_id has been sent back to associate with the update_key. Defaults to 0 if not sent.
updateKey: 70365413:1:1
Results: {"message":"Prepared for deletion","data": [{"REC_ID": "8675309", "G_MSG": "Prepared for deletion"}]}
Explanation: If you are able to delete the record, you should get a response like this; otherwise you may need to delete records that have occurred after this one and re-upload back in order. That is a more involved process, however.
Save the edit/verify records
Last order of business: saving the edit/verify records, including handling rows marked for deletion. Example:
Explanation: You should get a message similar to the one above. There should also be a response parameter stating how many records were saved as well. In this case, the removal was saved to the database.
Repeat Steps 3-5 for the new mating date
Appendix
This section of the API has miscellaneous useful information for using the API. Frequently asked questions can be found here.
When updating your application to work with the API, namely the Auth/Logon/ procedure, the user should provide their own username and password used to log into PICTraq.
Developers needing a test set of login details should contact PICTraq.Support@genusplc.com for a set of login details.
API Status Codes
Each call in the API returns a status code corresponding to standard HTTP status codes. Generally, this will be "200," or "Request OK". In the event any other status code is raised (due to the authentication token expiring, not providing a token, or an access-level issue on a farm or user), a `message` property is returned in the repsonse body in addition to that status code detailing exactly what went wrong. This should be displayed to the user.
API Data Types
On each page of documentation, there are various data types mentioned for the input parameters. These data types describe the expected input type. Below is a table of data types and an explanation of each.
Data Type
Description
Notes
string, number
Respectively, both are sent as plaintext strings.
Spaces should be encoded as a + character.
array
Data should be sent as an array of expected values.
When sent as raw data, each entry should be formatted as parameterName[]=parameterValue. The aforementioned code block is sent for each individual record. Some endpoints will allow a comma-delimited string in addition; those endpoints will indicate if this is the case.
boolean
Data should be sent as a 0 (zero) or 1 (one) for false/true, respectively.
Sending Data via POST
When the API was first created, data was sent via POST through an HTML form. Data should be sent in that format, and there's two ways to re-create this format:
Using a library to handle POSTing to the API.
For example, in Java, the Apache HttpComponents is a library of low level Java components focused on simplifying HTTP requests.
It is STRONGLY recommended you use this approach, as it eliminates most of the guesswork in preparing requests. It is very easy to make a mistake using other methods. Regardless of language and library, making a request needs to have support for the following:
Setting HTTP headers. You will need to set the Content-type and Authorization headers.
Encoding data properly to send via POST. Some languages support this natively, others will need to use a library to simplify this.
Sending raw data directly to the endpoint in the following format: parameter=value¶meter2=value2¶meter3=value3.... Notably, space characters should be encoded as a + character.
Special POST variables
A few special variables exist that can be POSTed over to the API to modify how the API response is generated. They are as follows:
None yet!
Formatting startFilter/endFilter Parameters in Herd/Events/getVerify
The endpoint Herd/Events/getVerify requires two parameters: startFilter and endFilter. The formatting for this is as such:
This string is constructed by first calling Herd/Events/getEventFarmTraits, and setting the verify parameter to 1. Each returned trait is used in the filter parameters in the format traitID@traitValue, joined with a | character.
For reference, the following is the first four traits that are returned for the above procedure in this example:
# Only the relevant keys in this case are displayed
{
"message":"END",
"data":[
{"EV_TRAIT_ID":"54","TRAIT_NAME":"DAM_PED_IDENT"},
{"EV_TRAIT_ID":"32","TRAIT_NAME":"DAM_STIG"},
{"EV_TRAIT_ID":"34","TRAIT_NAME":"DAM_TATTOO"},
{"EV_TRAIT_ID":"35","TRAIT_NAME":"FARROW_DAY"},
]
}
For example, the above filters are for the farrowing event, and the filters are for traitID 35 (FARROW_DAY), from 1 January, 2019 to 7 January, 2019.
Once you skip this, you'll be greeted with the following: 
Each sidebar item, when clicked, has the following items:
If the login was successful, it'll return an authentication token. This will need to be stored in memory and used in future calls, described in the next section. If the login failed, however, the API will respond with a message as to why it failed. Usually this is due to an incorrect password.
Using the same approach as from before, we can set up the call as follows. For demonstration purposes, we are calling the events for farm 6802, which is a test farm:
There is two differences, however. We've added a new header: Authorization. Any non-login endpoint calls need the Authorization header set to the value 
If the call is successful, you'll get traits back in the following format: 
In any case, usually you'll get a message of SUCCESS back, indicating that the trait was successfully added. If not, usually the trait is already there, or a trait ID wasn't sent.
If successful, you'll get a response like this: 
At this point, you either get no records back (getting just a record with all the possible response keys with null values), or more than one record, which indicates that there are pending records already there. Inside this response is an EVENT_VALUES_PARSED, which, for each record, has an array of a record's traits and values. We will be using those to update a record (or create a new one).
If the record is considered valid by the database, the message of the response will say VALID. Otherwise, it will return a message stating actions needed to make the record valid. An example response is below: 
Notably, the API returned a new REC_ID, or record ID. If you wanted to update the new record, you would use this new REC_ID. Anyways, this step is repeated until you have valid records and would like to save them. As an example, create one record using the following trait IDs and trait values: (First request will use a record ID of 0, following requests will use the record ID the API responds with).
Send it, and it should return SUCCESS if there are valid records. If you get that message, all valid records have been successfully saved in the API. At this point, it's recommended that another call to Herd/Events/getEventValues is made to update your program's local state and to continue with remaining invalid records.
The response will either be SUCCESS, meaning the upload worked, or it will return an error message. If successful, you can then make a call to