Export API

The Export API makes it possible to download update records from ITRP in batches. The behavior of this API is similar to the Export functionality as exposed via the GUI.

Exporting records in batches through the API is the preferred way of building (one-way) integrations with, for example, a corporate data warehouse. It allows for easily managed integrations and performs better compared to sending separate GET REST API requests for each record.

This page is organized as follows:

Generating an export file

Data can be exported from ITRP in UTF-8 encoded comma-separated values (CSV) files.

Each record in such a CSV export file is defined on a separate line. Each line of text is essentially a row of a spreadsheet. The first line of text is reserved for the column headers. Each column header references a field of the record type.

Relations to different accounts

When a trust relation has been established between two ITRP accounts, it is possible for certain records of these accounts to be linked together. For example, Widget Data Center may be providing their Expense Reporting service to the Widget North America organization. After these organizations have established a trust relation between their accounts, Widget Data Center is able to register a Service Level Agreement and relate an Organization record of Widget North America to it as its customer. If the id of Widget North America’s account is “wna”, then an export of Widget Data Center’s SLAs will show the name of the customer’s Organization record followed by the @ symbol and the id of the customer’s account.

This will then look as follows:

Widget North America @wna

Initiating an export

The example below shows how an export of the Sites and Team records can be extracted from an account which id is “wdc”, and how this export can be limited to records that were created or updated after December 31, 2012.

$ curl -u "api-token:x" -X POST -H "X-ITRP-Account: wdc" \
       -F "type=sites,teams" -F "from=20121231" \
       "https://api.itrp.com/v1/export"

The response from the Export API is a token that acts as the unique identifier for the export job. This token can be used to retrieve information about the progress of the export job.

Status: 200 OK
{
  "token": "68ef5ef0f64c012f2...e4598cdb41e68"
}

In case the from parameter is provided and there are no created or updated records since that time no export will be scheduled. The following response will be provided:

Status: 204 No Content

It is important to note that the API user needs to have the Account Administrator role to be able to export files using the API. In the example above, the API user specifically needs to have the Account Administrator role of the account which id is “wdc”. The Authentication section describes how the api-token of the API user can be found.

In the example above it would not be necessary to specify -H "X-ITRP-Account: wdc" provided that the Person record of the API user belongs to the acccount which id is “wdc”.

Parameters

The following parameters are supported:

type
Required enum — The type of the file to export. Valid values are:
  • requests
  • request_templates
  • knowledge_articles
  • problems
  • releases
  • changes
  • tasks
  • task_approvals
  • change_templates
  • task_templates
  • services
  • service_categories
  • service_instances
  • service_offerings
  • standard_service_requests
  • slas
  • flsas
  • affected_slas
  • product_categories
  • products
  • cis
  • ci_relations
  • contracts
  • project_categories
  • project_risk_levels
  • projects
  • project_tasks
  • project_task_assigments
  • project_templates
  • project_task_templates
  • project_task_template_assigments
  • organizations
  • organizations_contact_details
  • organizations_time_allocations
  • teams
  • people
  • people_contact_details
  • people_roles
  • sites
  • calendars
  • holidays
  • time_allocations
  • time_entries
  • timesheet_settings
  • short_urls
  • system_logs

Apart from the above types, the Export API also supports the type all. When the type all is used, a separate CSV file will be prepared for each of the above-mentioned record types, with the exception of short_urls and system_logs. This option is especially useful for organizations that want to perform incremental exports of all their ITRP records. It allows them to export all records that were created or updated since the last time they performed such an export. The export files can then be used for upload into their corporate data warehouse.

from
Optional date — The date after which a record needs to have been created or updated in order to be included in the export.

Examples

This defines the start of the day on May 24, 2013 in the timezone of the API user: from=20130524

This also defines the start of the day on May 24, 2013 in the timezone of the API user: from=20130524T00:00:00

This is equal to 11pm on May 01, 2013 in Sydney (i.e. in the AEST time zone): from=20130501T23:00:00-10:00

This is the start of the day on May 01, 2013 in UTC (coordinated universal time): from=20130501T00:00:00Z

Export progress

The export process runs as a background job. The token received from the export response can be used to retrieve information on the progress.

Five minutes after the job is completed, the progress information is not available anymore through the API.

Example:

$ curl -u "api-token:x" -X GET \
       https://api.itrp.com/v1/export/68ef5ef0f64c012f2...e4598cdb41e68

Depending on the state of the export job, one of the following responses is returned:

Queued

Status: 200 OK
{
  "state": "queued"
}

The job is scheduled for execution.

Processing

Status: 200 OK
{
  "state": "processing",
  "type": "sites",
  "line": 32
}

The job is being processed and the line attribute shows how much progress has been made.

Done

Status: 200 OK
{
  "state": "done",
  "url": "https://...export.zip?AWSAccessKeyId...",
  "expires_at": "2016-06-28T02:56:11-06:00"
}

The job is complete and the response includes meta information about the export. The url attribute will contain a link to the CSV file in case a single type was exported. When multiple types are exported at once, a ZIP file will be created with a separate CSV file for each type. The expires_at attribute shows when the url will expire. By default this is 2 days after the export job completed.

Not Found

Status: 404 Not Found

The job was completed more than 5 minutes ago, so no progress information is available anymore. Information on the completed job can still be found in the Export Log.

Downloading an export file

It was already mentioned above that, when the Export API is used to start an export, the immediate response from the Export API is a token that acts as the unique identifier for the export job.

Once the export has been completed, an email is sent to the API user. This email contains the hyperlink with which the export file can be downloaded. The header of this email contains the token that is the unique reference to the export job. This token makes it possible for automated scripts to find the correct email.

For example:

X-Mailer: ITRP Mailer
X-ITRP-Export: 68ef5ef0f64c012f2...e4598cdb41e68
Auto-Submitted: auto-generated

Export log

Each export job that is complete is entered in the System Logs of the Settings console. Log into ITRP as an Account Administrator and go to Settings => System Logs and select the Export Log view to see them all.