Import Documents
Description
The document import does both create and update documents. The import remembers theexternalId
/ systemName
pair and if an import matches an existing pair, it will update (Hint: consider how to rebuild the externalId when you want to update documents). The document import in Livingdocs is asynchronous. You post a batch of documents that you want to import and get back an id with which you can query later to get your result.Endpoint
POST api/v1/import/documents
Parameters
Name | Type | Rquired | Notes |
---|---|---|---|
systemName | string | x | Identifier for the system you are importing from, e.g. an archive |
webhook | uri | Endpoint at the importing system that gets notified by POST when import job is done. Notification contains the id of the import job, the state and an overview. | |
context | object | An object that is passed as context in the body of the request to the webhook. Limited to 8192 Bytes. | |
documents | array | x | An array of documents to import. Each entry is an object with the following keys: id: a unique id (stored as externalId in Livingdocs) that identifies the document on your end, must be unique within your project. title: the title that the document should get in livingdocs checksum: string to identify changes, e.g. an updated_at timestamp contentType: the content type that the document should get in livingdocs publicationDate: sets the date of a publication. ‘autoPublish’ flag must be set for this to have an effect. livingdoc: A valid livingdoc declaration (content / design), must conform to your channel-config otherwise throws a validation error / release-2022-07: if no design is set it takes the design of the Project Config. metadata: An object of metadata, must conform to your channel-config otherwise throws a validation error flags: (optional) define additional import logic: ‘autoPublish’: publishes imported documents immediately ‘unpublish’: unpublishes imported documents immediately (release-2022-07) ‘onlyOverwriteUntouched’: only update documents that have no manual changes in livingdocs ‘neverOverwrite’: never update documents through the import API |
Example Request
{
"systemName": "identifier-for-your-system",
"webhook": "https://my-domain.com/webhooks/document-import",
"context": {
"myIdentifier": "some-identifier-sent-to-the-webhook"
},
"documents": [
{
"id": "123abc",
"title": "test import",
"contentType": "article",
"checksum": "xyz456",
"publicationDate": "1999-03-18T17:27:00.107Z",
"livingdoc": {
"content": [
{
"identifier": "header",
"content": {
"catchline": "imported catchline",
"title": "imported title",
"author": "imported author"
}
}
],
"design": {
"name": "living-times",
"version": "1.0.1"
}
},
"metadata": {
"description": "foo"
},
"flags": {
"autoPublish": true
}
}
]
}
Response
Check Import Status for Documents
Description
You can use this endpoint to check for the status and/or result of a document import.Endpoint
GET api/v1/import/documents/status
Parameters
Name | Type | Required | Notes |
---|---|---|---|
?id | string | x | The id that Livingdocs provided you for your prior call to “/import/documents” |