Data & Automation API: GetTableImport

GetTableImport

Overview

This method is used to get the status of the data import job to check if the job has finished validating data and it is ready to import.

This method requires the ImportTable permission to be associated with your role.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Input Fields (Header)

• Header should contain the 'Accept' Key with the Value = 'application/json' or 'application/vnd.catch-e-api.v1+json'.

Input Fields (Path)

Input URL Examples

Single table:https://api.catch-e.com/gb/import/table/{table_import_id}ORMultiple tables:https://api.test.catch-e.com/gb/import/table?table_import_id={table_import_id},{table_import_id},{table_import_id},{table_import_id}

(Successful) Output Example

{ "table_import_id": "a5f5b489d019521eb16f5c579faa9e15afc7a4bb", "table_name": "qt_variant_profiles", "sha256_checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "status": "validated", "rows_valid": 50, "rows_invalid": 0, "rows_imported": 0, "rows_updated": 0, "rows_inserted": 0}

Error Codes

Example error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Invalid supplier id"}

GetTablesAuthorisedForExport

Overview

Allows you to retrieve a list of tables authorised for data export.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

This method requires the ExportTable permission to be associated with your role.

Input URL Examples

For a tables:

https://api.test.catch-e.com/gb/export/table/authorised

(Successful) Output Example (sample)

[ "qt_quote_budgets", "qt_quote_tyres", "qt_variant_residuals", "qt_variant_state_reg_ctp", "gl_controls"]

Error Codes

Example error output

{ "status": 404, "title": "Not Found", "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "API endpoint not found"}

GetTablesAuthorisedForImport

Allows you to retrieve a list of tables authorised for data import.

This check is done during the Import Table Data and Insert or update a record with auditing processes.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on ImportTable.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Input URL Examples

For a tables:

https://api.test.catch-e.com/gb/import/table/authorised

(Successful) Output Example (sample)

[ "qt_quote_budgets", "qt_quote_tyres", "qt_variant_residuals", "qt_variant_state_reg_ctp", "gl_controls"]

Error Codes

Example error output

{ "status": 404, "title": "Not Found", "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "API endpoint not found"}

ExecuteImportTableData

Use this method to update a table when this can be done from a query using defined rules.

Audit records for these updates will be marked as external.

It uses the same functionality as the Import Table Data screen.

Visit the Import Table Data → Data File page and check that the query you create meets those requirements or the job will fail.

See User Defined Queries for instructions on writing queries for the Scheduler.

Parameters

These are the different parameter settings that you can set up on the Scheduler / Job tab

• Query ID — Lookup or enter the Query ID you want to use for this import. The query description is shown below.
• Module — Select the module that the table you want to import belongs to. E.g. will be in 'fm - Fleet Management'
• Table — Select the table you want to import. Some tables cannot be imported.
• Error If No Data — Un-checked by default. If the query returns no data when the job is run, no email will be sent and the queue message will be blank. If checked, an email will be sent.
• Validate — Checked by default. Checks the linked query data to ensure its correct before the actual table import. Uncheck the checkbox to skip validation for long running but consistent jobs. Access to Super users only.

Mail

• Send Mail — This field is checked by default. Un-check this if you don't want to receive any emails about this job.
• Sender — The stored sender will be used to create the required audit records. We recommend creating and using a user called 'scheduler'. The audit records are marked as 'X' ( external).

Recipients

• Recipient — Nominate a recipient to monitor this job.

Validations and Alerts

Messages

The messages below are shown on Scheduler / Schedule as "Last Message" and also on Scheduler / Queue as "Message".

Support Notes

If a job like this fails, run the query in Workbench and then upload it via the Import Table Data screen.

Use the Error Report as the first step in diagnosing issues.

ExportTable

Overview

Download data for an existing table data export request in Request a table data export.

This method requires the ExportTable permission to be associated with your role.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Input Fields (Header)

• Header should contain the 'Accept' Key with the Value = 'application/vnd.catch-e-api.v1+json'.

Input Fields (Path)

Input URL Examples

https://api.catch-e.com/gb/import/table/{table_import_id}

(Successful) Output Example

{ "table_export_id": "0eb06f50-4210-4ed2-9723-2c2e24df4670", "uri": "https://catch-e-api-table-exports.s3.ap-southeast-2.amazonaws.com/example/0eb06f50-4210-4ed2-9723-2c2e24df4670?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ZKIBIA46LLA7H5KN5S4Q%2F20190201%2Fap- southeast-2%2Fs3%2Faws4_request&X-Amz-Date=20190201T045824Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Signature=6dcb136a7e0d285419ec8f88602785df41dc0036df8657bbc6e20309d3f3d5ba", "uri_expiry": "2019-02-01T16:03:24+11:00"}

Error Codes

Example error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Invalid supplier id"}

CancelTableImport

Overview

Allows you to cancel a table data import.

HTTP Method

Use the HTTP Method 'DELETE' for consuming this web service.

This method requires the ImportTable permission to be associated with your role.

Input URL Examples

https://api.catch-e.com/gb/import/table/{table_import_id}

(Successful) Output Example (sample)

A successful deletion will only return a Body Status '204 No Content'.

Error Codes

Example error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "The specified driver asset does not exist"}

ImportPublicHolidays

If you are Salary Packaging, you may need to import new public holiday records as one of your annual tasks.

Import public holidays data into the table . Currently, this will only import data from the data.gov.au website.

Use the API resource id from Australian Public Holidays Dates Machine Readable Dataset to import the public holidays data.
Each resource id will have a specific date range. Only select and run the API using selected links for the dates you want.

Warning: data.gov.au is no longer maintaining the Australian Public Holidays Dates Machine Readable Dataset.
Records for 2021 - 2025 are still available (except for the 2025 Friday before Grand Final Day, this date is missing from the dataset).

Permissions

If you want to use this API in your system, enable ImportPublicHolidays 1. Go to System Roles and select the 'web_services' role

2. Navigate to the Roles / APIs tab
3. Find the ImportPublicHolidays permission and check it's check box

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.catch-e.com/gb/import/public-holidays

Input Fields (Header)

• Header should contain the 'Accept' Key with the Value = 'application/vnd.catch-e-api.v1+json'.

Input Fields (Body)

Holidays import Range(data.gov.au)

Input Fields Body

data_source=data.gov.au&resource_id=33673aca-0857-42e5-b8f0-9981b4755686

Successful Output Example

A successful import will only return a Body Status '204 No Content'.

Response Details

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 404 - Not Found | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Client error:..."}

| Incorrect datasource or resourceid specified. |

RequestTableImport

This web service allows you to request a table data import.

This API delivers a function that is similar to Setup / Import Table Data.

Dependent Records

You can use a UUID placeholder in the import files to manage data where there are child records that have a key field dependency,
E.g. .
Visit the Dependent Records page for the details of how to use this feature.

Permissions

The permission for this api is stored in as ImportTable.

Only roles with a stored link to this permission in can run this api.

API access to this function is provided to the roles 'admin' and 'web-services' as the default setting.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

Input Example

https://api.test.catch-e.com/gb/import/table

Input Fields (Header)

• Header should contain the 'Content-Type' Key with the Value = 'application/x-www-form-urlencoded'.

• Header should contain the 'Content-Type' Key with the Value = 'application/json' or 'application/hjson'.

Input Fields (Body)

Output Example (Sucessful)

{ "table_import_id": "a5f5b489d019521eb16f5c579faa9e15afc7a4bb", "format": "csv"}

Error Codes

error output

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}