Import via webservice
The main difference between an import via webservice and via watchfolder is the way of passing the files to the importer. After the files to import are handed over to the Importer, the process is mostly identical. The webservice offers the same functionality as the watchfolder mechanism. In addition to the watchfolder mechanism, the webservice returns a JSON description of the import status instead of just writing message to the log. It is also possible to send parameters along with the data to import, which can be accessed by preprocessor scripts or XSL transformations.
First of all, the webservice has to be activated and configured in the base configuration file application.yml. It is not recommended to switch on the webservice if not needed. The webservice can also be disabled for specific instances in the instance configuration. Then, an error will be thrown when trying to import documents via webservice using this instance.
To secure the webservice you can enable basic authentication using the configuration option importer.webService.authenticationRequired. The usernames and passwords must be configuration using the option importer.webService.logins.
Once the webservice is configured and running, you may use the POST request method at the URL /v1/import/<instanceKey> with following information:
| Data | Description |
|---|---|
<instanceKey> | Path variable to define the importer instance the data is sent to. <instanceKey> refers to the instance key from the instance configuration. |
| Request body | The data enclosed in the body of the request message is passed to the selected instance. |
| Query parameters | Optional request parameters in the URL as key-value paars (?key1=value1&key2=value2) are passed to the preprocessor scripts and XSL transformation of the selected instance. |
Webservice Response
The webservice returns a JSON description of the import status. A webservice response might look like the following example:
{
"successful": true,
"importDeferred": false,
"importDate": "2023-06-18T13:11:32.083+00:00",
"duration": 0.262,
"importFilePath": "/cms/importer/my-instance/success/ws_1687093891817_0.xml",
"preprocessedFilePath": "/cms/importer/my-instance/success/ws_1687093891817_0_preProcessed.xml",
"documents": [
{
"sophoraId": "rest-import100",
"externalId": "rest-import",
"uuid": "a5aa1680-bf10-499b-afe7-bc4f00362043",
"newlyCreated": false,
"successfullySaved": true
"resourceDocuments": [
{
"sophoraId": "rest-import-resource100",
"externalId": "rest-import-resource",
"uuid": "182aff73-a898-4a3d-bdc4-57402e3e1e4e",
"newlyCreated": true,
"successfullySaved": true,
"resourceDocuments": [ ... ]
}
]
}
]
}
In the example above, two sophora documents were imported: a main document and a document referenced as resource (<resourceList> in the sophora XML of the main document).
Information about the import process:
| Property | Description |
|---|---|
successful | Indicates if the import process was altogether successful. This means that any content that should be imported has been imported. Note: In any case there may have been warnings occurred during the import process which are collected in the property errorText. |
importDeferred | If the result import XML contained the forceLock-Element with a timeout, the importer might defer the import if the respective document is locked. In this case, the POST method call returns before the import finishes and contains this attribute set to true. |
errorText | Text with errors and warnings which occurred during the import process of documents. Can be omitted if no problems occurred. |
importDate | Shows the time of the import in the time format "ISO 8601" - "2010-07-29T15:11:54.568+02:00" for instance. |
duration | Shows the duration (in seconds) of the import process. |
importFilePath | The complete path of the file with data from the request body. This file is located either in the successful or in the failure folder of the importer instance. |
preprocessedFilePath | The complete path of the file after the preprocessor script modified the data. This file is located either in the successful or in the failure folder of the importer instance. |
transformedImportFilePath | The complete path of the transformed file (if an xsl transformation was made). This file is located either in the successful or in the failure folder of the importer instance. |
documents | Information about sophora documents which were handled during the import process (see next table). |
Information about a particular document import:
| Property | Description |
|---|---|
newlyCreated | Shows if the sophora document was newly created (true) or if an existing document was updated (false). Note: If the import of the document was not successful (i.e. the property successfullySaved is false), this property has no informative value. |
successfullySaved | Indicates whether the document was successfully saved in the repository. |
sophoraId | The sophora id of the processed document. Note: If the import of the document was not successful (i.e. the property successfullySaved is false), this property may be empty or only set with the provided id stem of the document to be imported. |
externalId | The external id of the processed document. Note: If the import of the document was not successful (i.e. the property successfullySaved is false), this property may be empty. |
uuid | The uuid of the processed document. Note: If the import of the document was not successful (i.e. the property successfullySaved is false), this property may be empty. |
resourceDocuments | Information about documents which are placed in the element <resourceList> of the result sophora import XML. |
Please keep in mind that the importer aborts the import process if the import of a single content failed. Therefore some documents may not occur in the property
documents if a previous content of the xml failed to import.Note: This is only relevant if you try to import several documents (or other content) within one sophora xml document!
