Import¶
Contents¶
Asks the server to enumerate the files in a compressed zip file that was uploaded for importing.
Only available to hosted SaaS clients
HTTP Request¶
To retrieve files in an archive:
POST /icweb.dll/import/contents/{file}
Request Body¶
Contains information on how to parse the import file to detect the columns.
| Name | Required | Type | Description | Default |
file |
Yes | String | Specifies the import file previously uploaded. |
Files¶
The Files object, contains a list of files in the uploaded archive.
| Name | Type | Description | Optional |
files |
string [] | List of files found in the uploaded archive. | No |
Detect Columns¶
Asks the server to detect the columns in the import sheet, the server will attempt to match each column with an associated business object field. A base business object needs to be specified.
Only available to hosted SaaS clients
HTTP Request¶
To retrieve detected columns from import file:
POST /icweb.dll/import/columns
Request Body¶
Contains information on how to parse the import file to detect the columns.
| Name | Required | Type | Description | Default |
file |
Yes | String | Specifies the import file previously uploaded. | |
files |
Yes | String[] | Specifies a number of import files that have previously been uploaded. This can be used instead of file where there are multiple zip files (exceeding 500mb) to allow larger uploads. |
|
fileName |
No | String | If the import file was a zip file, this specifies a file within the zipfile that is used as the import file. (Where multiple zipfiles are specified in files this file can be in any of them) |
|
businessObject |
Yes | String | The base business object for the server to use to perform column detection with. The server will attempt to match columns in this table first. | |
headerRows |
Yes | Integer | The number of rows that relate to column headers in the import file. | 1 |
delimiter |
Yes | String | Column delimiter | ‘,’ |
qualifier |
Yes | String | String qualifier to denote start/end of strings, possible values, ‘quote’, ‘doubleQuote’, ‘none’ | quote |
consecutiveAsOne |
No | Boolean | Treat consecutive delimiter as a single delimiter. | False |
columnMaps |
No | Column Map [] | Contains a list of desired column mappings as a starting point for the detection of further columns, and/or receiving a list of required fields for these mappings. | [] |
ignoreColumns |
No | integer[] | List of column indexes from source file that should be ignored. | Yes |
ignoreBlanks |
No | Boolean | Lets the importer know whether to ignore blank cells from the import sheet and not modifying existing data, or (the default) when a blank is found, to set the existing data to null. | False |
Responses¶
| Name | Type | Description |
| 200 OK | Import Columns | Contains a list of columns detected in the import sheet, mappings that are detected based on those columns as well as required fields. |
| 400 | Validation Error | Configuration provided for import is invalid, further information on what part was invalid is provided. |
| 404 | Not found | Either the blob id was not found or the businessObject specified was not found. |
Import Columns¶
The Import Columns object, contains information about the auto-detected columns from the import sheet, as well as a list of column maps to business object fields that have been detected.
| Name | Type | Description | Optional |
sourceColumns |
Source Column [] | List of columns detected | No |
columnMaps |
Column Map [] | List of column maps detected | No |
requiredFields |
Required Field [] | List of fields that are required to be provided, either via a static value, or a mapping for the import, based on other fields that have been mapped. | Yes |
ignoreColumns |
integer[] | List of column indexes from soure file that should be ignored. | Yes |
preview |
Source Row [] | Contains at most 50 rows from the source row, converted to a json object. | No |
commonFields |
Common Category [] | This contains a list of common fields that can be used as a destination for column mappings. | No |
Source Column¶
The source column object, contains information about the columns detected in the import sheet.
| Name | Type | Description | Optional |
columnIndex |
Integer | Column index, 0 is the first, left-most column. | No |
columnName |
string | Name of the column that was detected from the header rows, where there are no header rows in the import sheet, this will be blank. | Yes |
Column Map¶
Contains information to map a column in the import sheet, with a business object field.
| Name | Type | Description | Optional |
businessObject |
string | Name of the business object | No |
fieldName |
string | Field name of the field to map this column to. | No |
path |
string | Path to join from the base businessObject to the destination businessObject. Effectively when businessObject is not in the base table, NEXUS may not be able to correctly determine a path to the destination field. path helps NEXUS decide on the best path to join between the businessObjects. |
Yes |
columnIndex |
Integer | Column index, 0 is the first, left-most column. | Yes |
staticValue |
any | This will provide a static value for the business object to be imported with, use this instead of a columnIndex to provide the same value to be imported for each row created in the business object. |
Yes |
optional |
Boolean | Determines if this field mapping should create a row, a new row won’t be inserted if it only contains values for ‘optional’ field mappings, default value is False. |
Yes |
Required Field¶
Contains information about fields that are required to be provided, either by a column mapping or static value for the import to succeed.
| Name | Type | Description | Optional |
businessObject |
string | Name of the business object | No |
fieldName |
string | Field name of the field to map this column to. | No |
isMapped |
Boolean | Specifies if a mapping exists for this field, default False |
Yes |
Source Row¶
Contains a preview of up to 50 rows from the source row, as parsed using the submitted settings.
Each column will have a property in the JSON object, the name of the JSON pair will be columnX, where X is a zero based index, and the value will be of type string and contain the raw characters from the source file.
Common Category¶
Contains a list of categories, and a list of business objects and fields for each category.
| Name | Type | Description | Optional |
category |
string | Name of the category of business objects. | No |
businessObjects |
commonObject [] | Details on each business object in this category. | No |
Common BusinessObject¶
Contains a reference to a business object, and a list of fields in that business object that can be chosen as a destination field map for importing.
| Name | Type | Description | Optional |
name |
string | Display Name of the business objects. | No |
businessObject |
string | Name of the business objects. | No |
fields |
commonField [] | Details on field that can be imported to in this business object. | No |
Common Field¶
Contains a reference to a field in a business object.
| Name | Type | Description | Optional |
fieldName |
string | Field Name | No |
name |
string | Display Name of the field, not returned if it is the same as fieldName. | Yes |
path |
string | Path helper for the import, to return if this column is provided. | Yes |
Import¶
Import data into 1 or more tables from a previously posted blob, the blob must be a text file containing data in a tabulated format, such as TSV or CSV.
Only available to hosted SaaS clients
HTTP Request¶
To start a new import job:
POST /icweb.dll/import
To retrieve detail on an existing import job, see Job Status
URI Parameters¶
| Name | In | Required | Type | Description |
fileId |
Path | Yes | String | Specifies the import file previously uploaded. |
fileName |
Path | No | String | If the import file was a zip file, this specifies a file within the zipfile that is used as the import file. |
Request Body¶
This contains parameters for how to import the the data from the blob.
| Name | Type | Description | Optional | Default |
file |
String | Contains an identifier previously returned by a Post Blob call. | No | |
fileName |
String | Where the blob is a compressed zipfile containing multiple files, this is the name of the actual text file containing the import data. | Yes | null |
businessObject |
String | Name of the primary business object that the import is to be performed on. This forms the basis of the rows in the text file, other objects can be mapped using column mappings. | No | |
dateFormat |
String | Date format used when converting dates in the import sheet, acceptable values: ‘dd/MM/yyyy’, ‘MM/dd/yyyy’, ‘yyyy/MM/dd’, ‘dd-MM-yyyy’, ‘MM-dd-yyyy’, ‘yyyy-MM-dd’. | Yes | yyyy/mm/dd |
timeFormat |
String | Time format used when converting times in the import sheet, acceptable values: ‘hh:nn:ss AM’, ‘HH:nn:ss’, ‘HH:nn:ss.zzz’, ‘hh:nn AM’, ‘HH:nn’. | Yes | HH:nn:ss |
timeZoneOffset |
String | Timezone offset of date/times when being imported, a shift will be performed to convert it to UTC for Date & Time fields, Date or Time fields won’t have any conversion performed. | Yes | 0 |
headerRows |
Integer | The number of rows that relate to column headers in the import file. | Yes | 1 |
delimiter |
String | Column delimiter | Yes | , |
qualifier |
String | String qualifier to denote start/end of strings, possible values, ‘quote’, ‘doubleQuote’, ‘none’ | Yes | quote |
consecutiveAsOne |
No | Boolean | Treat consecutive delimiter as a single delimiter. | False |
startRow |
Integer | Start row of data to import, row numbers start at 0, after the header rows. So if there are 2 header rows, and the 3rd line in the file is the first data row, that is considered row 0. | Yes | 0 |
endRow |
Integer | End row of data to import, omit this field to import until the end of rows. The importer determines the end of rows by either the end of file, or a blank line. | Yes | |
columnMaps |
Column Map [] | List of columns for the import sheet, mapping to business object fields. This is optional, and recommended that you rely on the auto-detect columns, and only pass column maps you want to override in the detection. | Yes | |
ignoreColumns |
integer[] | List of column indexes from soure file that should be ignored. | Yes | |
ignoreBlanks |
No | Boolean | Lets the importer know whether to ignore blank cells from the import sheet and not modifying existing data, or (the default) when a blank is found, to set the existing data to null. | False |
test |
Boolean | Run a test of the import as a job. | Yes | False |
Responses¶
| Name | Type | Description |
| 200 OK | serverJob | Import job created, response contains information on the job. |
| 400 | Validation Error | Configuration provided for import is invalid, further information on what part was invalid is provided. |
| 404 | Not found | Either the blob id was not found or the businessObject specified was not found. |
Example¶
Example to submit an import job for the Task business object.
Request¶
POST /icweb.dll/import
Request Body¶
{
"file": "{69EA081E-84ED-4504-B15D-14BC7A020E49}",
"businessObject": "Task",
"qualifier": "quote",
"dateFormat": "dd/mm/yyyy",
"timeFormat": "HH:mm:ss"
}
Response¶
{
"id": "{7945AE0D-BB7D-4D7C-AF68-175C74CF02D5}",
"percentComplete": 0
}
An example to detect the columns in a CSV file, using Header as the base business object.
POST /icweb.dll/importColumns`
Request Body¶
{
"file": "{A29C4D22-214C-4DD6-9ED1-8F7FE084E1AA}",
"fileName": "Rest - Multi Header - Events - Multimedia.csv",
"businessObject": "Header",
"headerRows": 1
}
Response¶
{
"columnMaps": [{
"businessObject": "View_Node",
"fieldName": "Full_Location",
"columnIndex": 0
}, {
"businessObject": "View_Node",
"fieldName": "Full_Location",
"columnIndex": 1
}, {
"businessObject": "Comp_Type",
"fieldName": "Name",
"path": "Component",
"columnIndex": 2
}, {
"businessObject": "Workpack",
"fieldName": "Name",
"columnIndex": 3
}, {
"businessObject": "Table_Def",
"fieldName": "Name",
"path": "TD_ID",
"columnIndex": 4
}, {
"businessObject": "EVT_Span",
"fieldName": "Length",
"columnIndex": 5
}, {
"businessObject": "SDT_STD_KP",
"fieldName": "KP",
"path": "Start_Clock_SD_ID",
"columnIndex": 6
}, {
"businessObject": "SDT_STD_KP",
"fieldName": "KP",
"path": "End_Clock_SD_ID",
"columnIndex": 7
}, {
"businessObject": "Multimedia",
"fieldName": "Name",
"columnIndex": 8
}, {
"businessObject": "Repository",
"fieldName": "UNC",
"path": "Multimedia",
"columnIndex": 9
}
],
"sourceColumns": [{
"columnName": "Asset Location.Full Location",
"columnIndex": 0
}, {
"columnName": "Asset Location.Full Location",
"columnIndex": 1
}, {
"columnName": "Asset.Asset Type",
"columnIndex": 2
}, {
"columnName": "Workpack.Name",
"columnIndex": 3
}, {
"columnName": "Event.Event Type",
"columnIndex": 4
}, {
"columnName": "Span.Length",
"columnIndex": 5
}, {
"columnName": "Start - Survey - Pipeline.KP",
"columnIndex": 6
}, {
"columnName": "End - Survey - Pipeline.KP",
"columnIndex": 7
}, {
"columnName": "Multimedia.Name",
"columnIndex": 8
}, {
"columnName": "Multimedia.Image",
"columnIndex": 9
}
],
"requiredFields": [{
"businessObject": "View_Node",
"fieldName": "CV_ID"
}, {
"businessObject": "EVT_Span",
"fieldName": "Header_ID",
"isMapped": true
}, {
"businessObject": "Multimedia",
"fieldName": "Name",
"isMapped": true
}
],
"commonFields": [{
"category": "Event",
"businessObjects": [{
"businessObject": "EVT_Span",
"name": "Span",
"fields": [{
"fieldName": "Length"
}
]
}
]
}, {
"category": "Continuous Event",
"businessObjects": [{
"businessObject": "EVT_Pipeline_Profile",
"name": "PL - Profile",
"fields": [{
"fieldName": "Top_Of_Pipe",
"name": "Top of Pipe"
}, {
"fieldName": "Bottom_Of_Pipe",
"name": "Bottom of Pipe"
}, {
"fieldName": "Left_Seabed",
"name": "Left Seabed"
}, {
"fieldName": "Right_Seabed",
"name": "Right Seabed"
}
]
}
]
}, {
"category": "Sub Event",
"businessObjects": [{
"businessObject": "SET_Cross_Profile",
"name": "PL - Cross Profile",
"fields": [{
"fieldName": "Header_ID"
}, {
"fieldName": "X"
}, {
"fieldName": "Y"
}
]
}
]
}, {
"category": "System Table",
"businessObjects": [{
"businessObject": "Commentary",
"name": "Commentary",
"fields": [{
"fieldName": "Header_ID",
"name": "Event"
}, {
"fieldName": "Notes"
}
]
}, {
"businessObject": "Signoff",
"name": "Event Review",
"fields": [{
"fieldName": "Signed",
"name": "Date \/ Time"
}, {
"fieldName": "Description"
}, {
"fieldName": "SU_ID",
"name": "Personnel"
}
]
}, {
"businessObject": "Finding",
"name": "Finding",
"fields": [{
"fieldName": "Finding_ID"
}, {
"fieldName": "Header_ID",
"name": "Event"
}, {
"fieldName": "Anomaly_ID",
"name": "Anomaly"
}, {
"fieldName": "Bound_ID",
"name": "Trigger"
}, {
"fieldName": "Code_ID",
"name": "Code"
}, {
"fieldName": "Is_Bound",
"name": "Is Auto Generated"
}, {
"fieldName": "Remedial_Action",
"name": "Remedial Action"
}, {
"fieldName": "Anomaly_Required",
"name": "Anomaly Required"
}, {
"fieldName": "Severity_ID",
"name": "Severity"
}, {
"fieldName": "Reason"
}, {
"fieldName": "Is_Finding_Reviewed",
"name": "Is Finding Reviewed"
}, {
"fieldName": "Finding_Number",
"name": "Finding Number"
}, {
"fieldName": "Has_Comments",
"name": "Has Review Comments"
}
]
}, {
"businessObject": "View_Node",
"name": "Asset Location",
"fields": [{
"fieldName": "CV_ID",
"name": "Asset View"
}, {
"fieldName": "Component_ID",
"name": "Asset"
}, {
"fieldName": "Is_Dynamic",
"name": "Is Dynamic"
}, {
"fieldName": "Dynamic_Filter",
"name": "Dynamic Filter"
}, {
"fieldName": "Link_ID",
"name": "Parent"
}
]
}, {
"businessObject": "BookMark",
"name": "Bookmark",
"fields": [{
"fieldName": "Header_ID",
"name": "Event"
}, {
"fieldName": "Description"
}
]
}, {
"businessObject": "Multimedia",
"name": "Multimedia",
"fields": [{
"fieldName": "Name"
}, {
"fieldName": "Can_Report",
"name": "Can Report"
}, {
"fieldName": "Repository_ID",
"name": "Image"
}, {
"fieldName": "X"
}, {
"fieldName": "Y"
}, {
"fieldName": "pppX",
"name": "Pixels per Point (X)"
}, {
"fieldName": "pppY",
"name": "Pixels per Point (Y)"
}
]
}
]
}, {
"category": "Survey Data",
"businessObjects": [{
"businessObject": "SDT_STD_KP",
"name": "Survey - Pipeline",
"fields": [{
"fieldName": "KP"
}
]
}, {
"businessObject": "SDT_STD_NORM",
"name": "Survey - Standard",
"fields": [{
"fieldName": "Easting"
}, {
"fieldName": "Northing"
}, {
"fieldName": "Depth"
}, {
"fieldName": "Elevation"
}
]
}, {
"businessObject": "SDT_STD_KP",
"name": "Survey - Pipeline",
"fields": [{
"fieldName": "KP"
}
]
}, {
"businessObject": "SDT_STD_NORM",
"name": "Survey - Standard",
"fields": [{
"fieldName": "Easting"
}, {
"fieldName": "Northing"
}, {
"fieldName": "Depth"
}, {
"fieldName": "Elevation"
}
]
}
]
}
],
"preview": [{
"Column0": "Pipelines",
"Column1": "10\" Production Pipeline",
"Column2": "Flexible Pipe",
"Column3": "2012 ILI Inspection",
"Column4": "Span",
"Column5": "0.012",
"Column6": "3.56",
"Column7": "3.61",
"Column8": "Logo",
"Column9": "Logo.png"
}, {
"Column0": "Pipelines",
"Column1": "10\" Production Pipeline",
"Column2": "Flexible Pipe",
"Column3": "2012 ILI Inspection",
"Column4": "Span",
"Column5": "0.0253",
"Column6": "3.77",
"Column7": "3.78",
"Column8": "",
"Column9": ""
}, {
"Column0": "Pipelines",
"Column1": "10\" Production Pipeline",
"Column2": "Flexible Pipe",
"Column3": "2012 ILI Inspection",
"Column4": "Span",
"Column5": "0.0043",
"Column6": "4.8",
"Column7": "4.93",
"Column8": "WGIM",
"Column9": "wgim.bmp"
}, {
"Column0": "Pipelines",
"Column1": "10\" Production Pipeline",
"Column2": "Flexible Pipe",
"Column3": "2012 ILI Inspection",
"Column4": "Span",
"Column5": "0.122",
"Column6": "7.12",
"Column7": "7.35",
"Column8": "",
"Column9": ""
}, {
"Column0": "Pipelines",
"Column1": "10\" Production Pipeline",
"Column2": "Flexible Pipe",
"Column3": "2012 ILI Inspection",
"Column4": "Span",
"Column5": "",
"Column6": "7.42",
"Column7": "7.85",
"Column8": "",
"Column9": ""
}, {
"Column0": "",
"Column1": "",
"Column2": "",
"Column3": "",
"Column4": "",
"Column5": "",
"Column6": "",
"Column7": "",
"Column8": "",
"Column9": ""
}
]
}