Import Document Service
Warning
This service has been deprecated and is expected to be replaced by a new API.
Import Document Service🔗
Search supports importing external documents through the API when importing is enabled for your environment. The following flowchart illustrates the setup.
The methods of Import Document Service can be categorized into 2 sections:
- Importing external document
- Managing user's import inbox (list, update, delete, deleteAll).
Method import🔗
Method call🔗
import(accessToken, searchEngine, reference, documentID, title, ip ,uuid)
Description🔗
The method creates an import operation entry with Processing status, downloads the external document, sends it to the Textkernel Parser to extract and returns response. This method does not update the status of the import operation with extraction status. The status of the import operation is expected to be updated by calling update endpoint. This endpoint is responsible from the numbered steps in the flowchart above.
- Import endpoint is called with accessToken, searchEngine, reference (id or url of the external document), document id and title (used when listing import operations) parameters
- Search downloads the external document
- Downloaded binary file is sent to the Textkernel Parser for extraction
- Search returns downloaded raw document + parsed document in customer specific template
This endpoint works synchronously, and may take several seconds to return response.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | access token that corresponds to the current session. |
| searchEngine | string | searcher for which to retrieve the document. |
| reference | string | External id or URL of the document. This value can be read from "import_reference" field of search service response. |
| documentID | string | Document id. |
| title | strings | Title of the document. Will be displayed in the imports inbox. |
| ip | strings | Optional, only required when importing from BroadBean channels. IP address of the request origin. |
| uuid | strings | Optional, only required when importing from BroadBean channels. Unique persistent identifier for the user's browser or device. |
Returns🔗
| Type | Description |
|---|---|
| ImportDocumentResponse | See description of ImportDocumentResponse in chapter Object Structures |
Pre-Condition🔗
The environment has importing enabled.
Post-Condition🔗
None
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
| SEARCHER_NOT_FOUND | The searcher with the given searchEngine name is not found. |
| SEARCHER_ACCESS_DENIED | The user is not authorized to access searcher. |
| EXTERNAL_ERROR | An exception occurred when downloading external document. |
| IMPORTER_NOT_AVAILABLE | No importer is configured for the environment. |
| IMPORTER_EXECUTION_ERROR | An exception occurred when importing document. |
Method list🔗
Method call🔗
list(accessToken, searchEngine)
Description🔗
The method returns user's import inbox for requested searcher. Records are sorted by created time descending and only top 1000 are returned.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | access token that corresponds to the current session. |
| searchEngine | string | Optional. The name of the external searcher for which the endpoint will filter import operations. |
Returns🔗
| Type | Description |
|---|---|
| list of ImportOperation | See description of ImportOperation in chapter Object Structures |
Pre-Condition🔗
None.
Post-Condition🔗
None.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
Method update🔗
Method call🔗
update(accessToken, importId, link, message, status)
Description🔗
The method updates a record in user's inbox. link, message, isViewed and status parameters are optional and overrides the data if present.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | access token that corresponds to the current session. |
| importId | string | The ID of the record to be updated |
| link | string | Optional. External ID or trxml ID to generate link to open the document in the ATS or Textkernel Sourcebox for editing. The link may have a url template that is pre-configured for the environment and is generated on client side by using importing field in the metadata response. |
| message | string | Message returned from customer when indexing document. The message is untranslatable and is shown only if there is an error or action required. |
| status | string | Optional. Status of the import operation; PROCESSING, OK, FAIL, DUPLICATE_FOUND, VALIDATION_ERROR. |
Returns🔗
| Type | Description |
|---|---|
| ImportOperation | Updated ImportOperation object |
Pre-Condition🔗
None.
Post-Condition🔗
The Import Operation is updated.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
| IMPORT_NOT_FOUND | Import Operation not found. |
| IMPORT_ACCESS_DENIED | User is not the owner of the import operation. |
Method delete🔗
Method call🔗
delete(accessToken, importId)
Description🔗
The method deletes a record in user's inbox. Only records that belong to requesting user and not in PROCESSING status can be removed.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | access token that corresponds to the current session. |
| importId | string | The ID of the record to be deleted |
Returns🔗
| Type | Description |
|---|---|
| boolean | returns if the record is removed or not. |
Pre-Condition🔗
None.
Post-Condition🔗
The Import Operation is deleted.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
Method deleteAll🔗
Method call🔗
deleteAll(accessToken, status)
Description🔗
The method deletes all records of the user with given status.
Parameters🔗
| Parameter Name | Type | Description |
|---|---|---|
| accessToken | string | access token that corresponds to the current session. |
| status | string | Records with this status will be removed. Status CANNOT be PROCESSING. |
Returns🔗
| Type | Description |
|---|---|
| integer | Number of records removed. |
Pre-Condition🔗
None.
Post-Condition🔗
All Import Operations of the user are deleted.
Error Handling🔗
| Error Code | Description |
|---|---|
| EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
| ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
| IMPORT_INVALID_REQUEST | Import operations in PROCESSING status cannot be removed! |