Import API

Import API

With this API you can import .xls, .xlsx, and .csv files into subjects. As a rule of thumb, files that are exported by Indicium through the export API can be imported using the import API, barring unique constraints on data.

note

This is an initial, basic version of the API that does not yet support all the import features currently available in the Windows GUI.

• Each record in the import file is treated as a separate insert made by the user that is calling the API. Meaning:
  • Users need insert permissions.
  • Default and layout logic apply and are called with default_mode=0, layout_mode=0, and import_mode=0.
    • The layout is called once before the import to ensure that the add_button_type is regular.
    • The default and layout procedures are called after every cell if the corresponding property has default/layout input checked.
    • The layout procedure is called after processing the last cell to determine if the confirm_button_type is regular.
  • Users cannot circumvent column-level authorization through the import API. Readonly, Hidden and Unauthorized columns present in the import file will be ignored.
• Context values cannot be changed. This means that if an import is performed on the sub_project table in the context of a project parent record with project_id 1, that all records from the import file will be imported with project_id 1 as well.
• Expressions will be evaluated, but only if they are an input parameter for the default or layout procedure, otherwise they serve no purpose. Unchecking the default/layout input checkboxes for expression columns greatly improves performance.

Prerequisites

The following prerequisites apply:

• The rows to be imported need to be in the import file's first worksheet.
• The import file must contain column headers. These must be in the first row.
• The column headers must be translated into the language of the user calling the API.
• The data must start on the second row, right below the headers.
• In the import file, lookup columns should have their display value instead of their database value.
• In the import file, columns with domain elements should have their element translations, not their database values. The elements must be translated into the language of the user calling the API.
• Columns are mapped automatically based on their translation, this cannot be altered.
• The Import permissions checkbox in IAM does not affect this API at the moment, but the Insert permissions box must be checked for at least one of the user's user group roles. These checkboxes are available in the menu Authorization > User groups > tab Effective group rights > tab Table rights > tab List.

1. Stage an import resource

note

This API is similar to Resource staging.

A new import resource can be staged by sending a POST request with the import file in the request body.

Request example

Request	Method	URL	Response	Location header
Stage an import resource	POST	/iam/my_appl/my_table/stage_import	201 Created	/iam/my_appl/_staged_import_my_table(\<guid\>)
Stage an import resource to import into a detail subject in the context of a parent record	POST	/iam/my_appl/my_parent_table(1)/detail_my_detail_table/stage_import	201 Created	/iam/my_appl/_staged_import_my_table(\<guid\>)

Parameters

note

• At least one of the parameters below needs to be true.
• You can download failed records into a new Excel file.

Description	Parameter	Request example
Insert new rows.	add_new_rows (default: true)	/iam/my_appl/my_table/stage_import?add_new_rows=true /iam/my_appl/my_parent_table(1)/detail_my_detail_table/stage_import?add_new_rows=true
Update existing rows (do not insert new rows).	update_existing_rows (default: false)	/iam/my_appl/my_table/stage_import&update_existing_rows=false /iam/my_appl/my_parent_table(1)/detail_my_detail_table/stage_import&update_existing_rows=true /iam/my_appl/my_table/stage_import?add_new_rows=true&update_existing_rows=false

2. Start the import

The import can then be started by calling the commit action on the import resource.

Request example

Request	Method	URL	Response
Import the resource	POST	/iam/my_appl/_staged_import_my_table(<guid>)/commit	200 OK

Response example

Indicium will give the following response after the import has completed:

200 OK

{
   "successful_records": 293,
   "failed_records": 1,
   "errors": [
       "Failed to import row 187. <some reason>"
   ]
}