Importing contents into D1 repository via REST
Document.One (D1) offers a content import service via D1 REST API. You can use this feature to import contents into repositories based on their previously exported specification.
You cannot import content from exported specification into any repository, because the exported specification files refer to content and cache resources — they do not work stand-alone! Please keep the following restrictions in mind:
- Import is allowed between different repositories only if these repositories share content and cache storage.
- You can import contents into a repository migrated from one D1 2.x installation into another. If the repository uses different storage after migration, you need to copy the content and cache folders into the new storage as well. This is explained in the example migration scenario below.
Preparing for content migration
The following example scenario describes the process of preparing your contents for migration from one repository to another.
Repository 1 contains the contents you want to migrate. Repository 1 has been running on D1 1 using Database 1, but this database has crashed without the slightest hope of recovery. Thus, you want Repository 1 and its contents to run on a newly installed D1 2 using Database 2. To achieve this, you need to perform the following operations:
- Enable content metadata export on Repository 1 in D1 1 (and export existing files if necessary). For information on how to do it, see Exporting and importing repository contents. When done, content specifications will be exported (as JSON files) into
{INSTALLATION_DIR_D1_1}/../repository-resources/content/_meta(this is the default location set in the settings file — if it is different in your organization, please adapt the path accordingly).
If metadata export is not enabled, content specifications are not written, and content import is not possible!
Migrate Repository 1 configuration from D1 1 to D1 2. You can either do it from the interface or with the D1 REST API:
Copy Repository 1 resources (both content and cache folders) to the storage used by target repository (to which you will be importing contents). Assuming Repository 1 on D1 1 stores resources under
{INSTALLATION_DIR_D1_1}/../repository-resources, you need to copy this directory into{INSTALLATION_DIR_D1_2}/../repository-resources. You will not be able to import the contents otherwise, because the JSON specifications are inside the/contentfolder.
Skip this step if the repository storage paths will not change.
- Now you can use the import service to bring the contents back into your new D1 installation. Proceed as described in accordance with Importing contents into a repository.
Importing contents into a repository
Importing contents is done via the /entries/import (for multiple contents) and /entry/import (for single content) endpoints. See the endpoint description and cURL examples below to get an idea on how to import contents. You can also check the endpoints in the Open API page of the repository.
Content metadata files can be found in the repository-resources/content/_meta directory (they are only written when metadata export is enabled on repository!). By default, this directory is created in {INSTALLATION_DIR_D1}/../repository-resources.
Endpoints
Endpoints below are responsible for content import.
| HTTP request | Endpoint | Service description | Request query parameters | Request body parameters | Returns |
|---|---|---|---|---|---|
| POST | https://host:port/tribefire-services/api/v1/access.adx.content.repositoryname/v1/entries/import | Import multiple entries into repository | sessionId | resources | Created contents metadata |
| POST | https://host:port/tribefire-services/api/v1/access.adx.content.repositoryname/v1/entry/import | Import single entry into repository | sessionId | resource | Created content metadata |
Parameters
Import endpoints take the sessionId and either resource (single import) or resources (multiple file import).
| Parameter | Data type | Description |
|---|---|---|
sessionId | string | The session ID returned by authentication. |
resources | array | Array of content metadata resources (used when you import multiple contents). |
resource | string (binary) | The path to the content metadata resource. |
Task 1: Import single content - cURL example
This is a practical example showing how you could import single content via the /entry/import endpoint. You need to adapt the following items in the call to match your environment:
- Protocol and URL (
https://adx-dev:8443in the example). - User name and password (
user=admin&password=passwordin the example). - Access ID (
access.adx.content.repositorynamein the example) - it is the same as theaccessIdparameter, shown in the URL in your browser when you open the repository. - Resource path (
resource=@/path/to/repository-resources/content/_meta/2004/0217/1204/0919fb72-f902-493a-b888-92e6e77fb1d9in the example).
- Open a session to the D1 host.
D1_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://adx-dev:8443/tribefire-services/api/v1/authenticate?user=admin&password=password' --header 'Content-Type: application/json' | cut -d '"' -f 2)
- Import the content.
curl --location --request POST 'https://adx-dev:8443/tribefire-services/api/v1/access.adx.content.repositoryname/v1/entry/import?sessionId=${D1_SESSION_ID}' \
--header "accept: application/json" \
--form 'resource=@/path/to/repository-resources/content/_meta/2004/0217/1204/0919fb72-f902-493a-b888-92e6e77fb1d9'
Please check the video below, where the whole process is shown (the call is executed from the OpenAPI page):
You can generate a cURL call in OpenAPI, as shown in the video.
Note that some of the UI components shown in this video might have changed as the video was created based on a older version of the D1.
Task 2: Import multiple contents - cURL example
This is a practical example showing how you could import multiple contents via the /entries/import endpoint. Note that multiple resource paths are provided in the call. You need to adapt the following items in the call to match your environment:
- Protocol and URL (
https://adx-dev:8443in the example) - User name and password (
user=admin&password=passwordin the example) - Access ID (
access.adx.content.repositorynamein the example) - it's the same as theaccessIdparameter, shown in the URL in your browser when you open the repository. - Resource paths (
resources=@/path/to/repository-resources/content/_meta/2004/0217/1204/0919fb72-f902-493a-b888-92e6e77fb1d9in the example)
- Open a session to the D1 host.
D1_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://adx-dev:8443/tribefire-services/api/v1/authenticate?user=admin&password=password' --header 'Content-Type: application/json' | cut -d '"' -f 2)
- Import the contents.
curl --location --request POST 'https://adx-local:8443/tribefire-services/api/v1/access.adx.content.forexport/v1/entries/import?sessionId=${D1_SESSION_ID}' \
--header "accept: application/json" \
--form 'resources=@/path/to/repository-resources/content/_meta/2004/0217/1204/0919fb72-f902-493a-b888-92e6e77fb1d9' \
--form 'resources=@/path/to/repository-resources/content/_meta/2004/0217/5934/88b3e635-895e-4ca6-800c-168de2dda9ce'
Response message
The D1 response should present the metadata of contents created by the import service, similar to the one below:
{
"_type": "tribefire.adx.model.content.service.v1.request.crud.EntriesResponse",
"count": 2,
"duration": 395,
"entries": [
{
"_type": "tribefire.adx.model.content.Content",
"active": true,
"chronicalId": "194b92ef-0a6b-4a38-8096-727732456db2",
"createdAt": "2020-04-06T16:33:54.077+0200",
"createdBy": "grzegorz",
"entryType": "CONTENT",
"id": "194b92ef-0a6b-4a38-8096-727732456db2",
"lastModifiedAt": "2020-04-06T16:33:54.077+0200",
"lastModifiedBy": "grzegorz",
"name": "filename1",
"owner": "grzegorz",
"partition": "access.adx.content.import",
"resource": {
"_type": "com.braintribe.model.resource.Resource",
"created": "2020-04-06T16:33:53.928+0200",
"creator": "grzegorz",
"fileSize": 305728,
"id": "f7b3e5d0-bdcc-4ba6-9ec4-70caba7975d4",
"md5": "1b6b2672a9194e66648870869247ef80",
"mimeType": "application/pdf",
"name": "filename1.pdf",
"partition": "access.adx.content.import",
"resourceSource": {
"_type": "com.braintribe.model.resource.source.FileSystemSource",
"id": "3449dcc6-2495-4248-ba8a-3c6b9949a534",
"partition": "access.adx.content.import",
"path": "2004/0616/3353/ae2e2811-bf4e-4f6f-9326-4450557344d1"
}
},
"version": "1.0",
"versionStatus": "WORKING_COPY"
},
{
"_type": "tribefire.adx.model.content.Content",
"active": true,
"chronicalId": "d7ee2d82-78bd-4fbb-bbd8-340b4bac3736",
"createdAt": "2020-04-06T16:32:56.131+0200",
"createdBy": "grzegorz",
"entryType": "CONTENT",
"id": "d7ee2d82-78bd-4fbb-bbd8-340b4bac3736",
"lastModifiedAt": "2020-04-06T16:32:56.131+0200",
"lastModifiedBy": "grzegorz",
"name": "filename2",
"owner": "grzegorz",
"partition": "access.adx.content.import",
"resource": {
"_type": "com.braintribe.model.resource.Resource",
"created": "2020-04-06T16:32:55.949+0200",
"creator": "grzegorz",
"fileSize": 68851,
"id": "d62479c2-9be4-4545-b79d-08bd5654deab",
"md5": "b01837a39e088962870194a6ba73133e",
"mimeType": "application/pdf",
"name": "filename2.pdf",
"partition": "access.adx.content.import",
"resourceSource": {
"_type": "com.braintribe.model.resource.source.FileSystemSource",
"id": "00c7a764-df49-4fca-aa66-743b806536c0",
"partition": "access.adx.content.import",
"path": "2004/0616/3255/490c6560-0c19-42c7-960b-81402e72b343"
}
},
"version": "1.0",
"versionStatus": "WORKING_COPY"
}
]
}
After receiving this response, you can verify in D1 Explorer that the contents have been created.
Try it Out with OpenAPI
All of the above endpoints are documented and exposed in our OpenAPI pages, where you can try them out.
Log in to Document.One (D1). Open Repository API from the landing page:
A list of repository endpoints is exposed. Switch to Swagger 2.0 in case of any issues in the default page:
Find the Entry section, where the endpoints are available:
Expand and try out the endpoints yourself, following the guidelines provided in OpenAPI.
For code samples, see