Core Concepts
importOK provides several different approaches to import the records once they are ready.
This is by far the simplest approach where the records are passed one by one, in a row. If you already have an API in place, it is recommended to start with this approach. Once you have it working, you can switch to batch processing to improve the performance.
In the following example, a callback is registered for onRecordReady
and it will be called one time for each record. Note that the meta object is passed for your convenience.
1{ 2 fields: {...}, 3 meta: {...}, 4 onRecordReady: async function (record, meta) { 5 return await fetch('https://your-api.com', { 6 method: 'POST', 7 headers: { 8 'Content-Type': 'application/json' 9 },10 body: JSON.stringify(record.getProperties())11 });12 }13}
Every time a callback is completed the progress bar on the user interface will be updated accordingly, demonstrating the progress.
To improve performance, you can define how many API calls can be executed concurrently. Similar to above scenario, a callback is registered for onRecordReady
and it will be called one time for each record but with up to 100 calls in parallel.
1{ 2 fields: {...}, 3 meta: {...}, 4 throttle: 100, 5 onRecordReady: async function (record, meta) { 6 return await fetch('https://your-api.com', { 7 method: 'POST', 8 headers: { 9 'Content-Type': 'application/json'10 },11 body: JSON.stringify(record.getProperties())12 });13 }14}
Every time a callback is completed the progress bar on the user interface will be updated accordingly, demonstrating the progress.
It is also possible to receive the full set which is useful when you want to process the records in the backend.
In the following example, we register a callback for onImportReady
and it will be called only once.
1{ 2 fields: {...}, 3 meta: {...}, 4 onImportReady: async function (records, meta) { 5 return await fetch('https://your-api.com', { 6 method: 'POST', 7 headers: { 8 'Content-Type': 'application/json' 9 },10 body: JSON.stringify(records.getProperties())11 });12 }13}
When a non-successful response status is returned (e.g., 400 Bad Request), the component automatically marks the corresponding records as failed. If you’re sending records individually, only the specific failed record will be marked. For batch or full-set submissions, all failed records in the set will be marked accordingly.
The component displays the failed records and prompts the end-user to download them, helping with troubleshooting and allowing re-upload after the issues are resolved. To include a custom error message for each failed record, use the markAsRejected
method. This message will appear as the last column in the downloaded file.
Here’s an example of how to use markAsRejected
to mark a record as failed with a custom error message:
1{ 2 fields: {...}, 3 meta: {...}, 4 onRecordReady: async function (record, meta) { 5 const response = await fetch('https://your-api.com', { 6 method: 'POST', 7 headers: { 8 'Content-Type': 'application/json' 9 },10 body: JSON.stringify(record)11 });12 13 if (!response.ok) {14 // Mark the record as failed with a custom error message15 record.markAsRejected(record, 'Custom error message'); 16 }17 return response;18 }19}
The meta object is passed to all callbacks and it contains the following properties:
Property | Description |
---|---|
importok.filesize |
The size of the uploaded file in bytes. |
importok.filename |
The name of the uploaded file, including extension but not the path. |
importok.filetype |
The MIME type of the uploaded file. |
import.withHeader |
Indicates whether the option "First line includes field names" has been selected. |
In addition to the predefined meta data described above, you can also pass your own metadata as part of the available props.