logoBack to home screen

Importing Contents into Repository via REST

ADx offers a content import service via REST. You can use this feature to import contents into repositories based on their previously exported specification.

Constraints

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 ADx 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.

Preparation

We want to migrate the contents of a repository - let's call it Repository 1. Repository 1 has been running on ADx 1 using Database 1, but this database has crashed without the slightest hope of recovery. Thus, we want Repository 1 and its contents to run on newly installed ADx 2 using Database 2. To achieve this, we need to perform the following operations:

  1. Enable content metadata export on Repository 1 in ADx 1. For information on how to do it, see Exporting Repository Entry Metadata. When done, content specifications will be exported (as JSON files) into {INSTALLATION_DIR_ADx_1}/../repository-resources/content/_meta (this is the default location set in the settings file - if it's 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!

  2. Migrate Repository 1 configuration from ADx 1 to ADx 2. You can either do it from the interface or with our REST API:

  3. Copy Repository 1 resources (both content and cache folders) to the storage used by target repository (to which you'll be importing contents). Assuming Repository 1 on ADx 1 stores resources under {INSTALLATION_DIR_ADx_1}/../repository-resources, you need to copy this directory into {INSTALLATION_DIR_ADx_2}/../repository-resources. You won't be able to import the contents otherwise, because the JSON specifications are inside the /content folder.

    Skip this step if repository storage paths won't change.

  4. Now you can use the import service to bring the contents back into your new ADx installation. Proceed as described in accordance with Importing Contents into Repository.

Importing Contents into 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 Open API page of the repository.

Content metadata files can be found in 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_ADx}/../repository-resources.

Endpoints

Endpoints below are responsible for content import.

Request typeService descriptionEndpointRequest query parametersRequest body parametersReturns
POSTImport multiple entries into repositoryhttps://host:port/tribefire-services/api/v1/access.adx.content.repositoryname/v1/entries/importsessionIdresourcesCreated contents metadata
POSTImport single entry into repositoryhttps://host:port/tribefire-services/api/v1/access.adx.content.repositoryname/v1/entry/importsessionIdresourceCreated content metadata

Parameters

Import endpoints take the sessionId and either resource (single import) or resources (multiple file import).

ParameterData typeDescription
sessionIdstringSession ID returned by authentication
resourcestring (binary)Path to the content metadata resource
resourcesarrayArray of content metadata resources (used when you import multiple contents)

Import Single Content - cURL Example

This is a practical example showing how you could import single content via the /entry/import endpoint.

# open session to ADx host
ADX_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 content
curl --location --request POST 'https://adx-dev:8443/tribefire-services/api/v1/access.adx.content.forexport/v1/entry/import?sessionId=${ADX_SESSION_ID}' \
--header "accept: application/json" \
--form 'resource=@/path/to/repository-resources/content/_meta/2004/0217/1204/0919fb72-f902-493a-b888-92e6e77fb1d9'

Import Multiple Contets - 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:

# open session to ADx host
ADX_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 contents
curl --location --request POST 'https://adx-local:8443/tribefire-services/api/v1/access.adx.content.forexport/v1/entries/import?sessionId=${ADX_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'

Expected Response

ADx 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 ADx Explorer that the contents have been created.

Try it Out with OpenAPI/Swagger

All of the above endpoints are documented and exposed in our OpenAPI and Swagger pages, where you can try them out.

  1. Log in to ADx. 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:

  2. Find the Entries section, where the endpoints are available:

  3. Expand and try out the endpoints yourself, following the guidelines provided in OpenAPI/Swagger.