Skip to main content
Version: 2.8

Exporting and importing repository configuration via REST

This page explains how to execute Document.One (D1) REST API calls allowing you to export and import repositories.

General

D1 provides REST API services allowing you to export and import repository configuration. All export services allow you to export all repositories, but you can also retrieve configuration by any of the following categories:

  • Repository ID (/export/configuration/ endpoint)
  • Repository name (/export/configuration/by-names endpoint)
  • Repository technical name (/export/configuration/by-technical-names endpoint)

Import is always done through the /import/configuration endpoint. Check Endpoints for detailed information on what each endpoint can do.

You can get all of the export parameters in the Administration Area in the user interface. Name and technical name are visible in the preview:

Repository names in the Administration Area user interface

The ID is visible in the detailed view of the repository (select Details to open):

Repository ID

Repository migration between hosts

cURL example

The example below shows a typical workflow consisting of four cURL requests, where you export a configuration from one host and import it into another one.

Adapt the following parts of the below requests:

  • https://[HOST]:[PORT] Adjust the protocol (http or https) and host name.
  • [USER_NAME] Replace with your user name.
  • [PASSWORD] Replace with your password.
  • repositoryNames Replace with real repository names, as in -F repositoryNames=["Real name 1","Real name 2"].
  • @/path/to/myrepo-export.zip Replace with the actual path (for example, @/mnt/c/Downloads/myrepo-export.zip).
  1. Open a session to the D1 host.
ADX_DEV_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://[HOST]:[PORT]/tribefire-services/api/v1/authenticate?user=[USER_NAME]&password=[PASSWORD]' --header 'Content-Type: application/json' | cut -d '"' -f 2)
  1. Export the repository from D1-dev to myrepo-export.zip.
curl --insecure --request GET  "https:///[HOST]:[PORT]/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-names?sessionId=${ADX_DEV_SESSION_ID}" --header "accept: application/json" -F repositoryNames="[Real name 1,Real name 2]" --output /path/to/myrepo-export.zip
  1. Open a session to the D1 host. (Ignore this step, if you are calling the same D1 instance.)
ADX_TEST_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://[host]:[port]/tribefire-services/api/v1/authenticate?user=admin&password=password' --header 'Content-Type: application/json' | cut -d '"' -f 2)
  1. Import the repository from myrepo-export.zip to D1.
curl --insecure --request POST "https://[host]:[port]/tribefire-services/api/v1/access.adx.admin/v1/import/configuration?sessionId=${ADX_TEST_SESSION_ID}" --header "accept: application/json" --header "Content-Type: multipart/form-data" --form "autoSync=true" --form "importRepositoryOption=full" --form "importUsersOption=none" --form "useRuntimeValues=false" --form "resource=@/path/to/myrepo-export.zip;type=application/zip"

The video below shows how to send adopted cURL requests to D1:

Video version

Note that some of the UI components shown in this video might have changed as the video was created based on an older version of the D1.

Endpoints

You can use three different endpoints to export repositories (by ID, by name or by technical name). Importing is always done via the import/configuration endpoint. Export query parameters are optional if you do not enter them, all repositories will be exported. Check Parameters below for information on request parameters and their values.

NOTE

You need to authenticate before using any of the below endpoints the session ID must be passed as a query parameter.

HTTP requestEndpointService descriptionRequest query parametersForm dataReturns
GEThttps://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/Export repository configuration by IDssessionId, repositoryIds (array)none.zip file with repository configuration.
GEThttps://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-namesExport repository configuration by namessessionId, repositoryNames (array)none.zip file with repository configuration.
GEThttps://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-technical-namesExport repository configuration by technical namerepositoryTechnicalNames (array)none.zip file with repository configuration.
POSThttps://host:port/tribefire-services/api/v1/access.adx.admin/v1/import/configurationImport repository configurationnoneautoSync, importRepositoryOption, importUsersOption, resource, useRuntimeValues

Parameters

The following table lists the parameters and their descriptions:

NameData typeDescription
sessionIdstringThe session ID returned when you authenticate.
repositoryIdsarrayArray of one or more repository IDs, for example ["ab-cd-1234", "ef-gh-5678"].
repositoryNamesarrayArray of one or more repository names, for example ["Repository name 1", "Repository name 2"].
repositoryTechnicalNamesarrayArray of one or more repository technical names, for example ["Technical name 1", "Technical name 2"].
autoSyncbooleanIndicates whether affected repositories should be automatically synchronized after import.
importRepositoryOptionstringSpecifies option for repository import. delta import only missing configuration, full do a full import, none do not import repository configuration (in case you only want to import users).
importUsersbooleanIndicates whether users/roles/groups should be imported.
resourcestringThe file system path to the previously exported .zip archive with repository configuration to be imported.
useRuntimeValuesbooleanIndicates whether environment specific runtime values should be used instead of the values from the export package.

Try It Out in OpenAPI

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

  1. Log in to Document.One (D1). Open the Administration API from the landing page:

    Administration API

    A list of repository endpoints is exposed. Switch to Swagger 2.0 in case of any issues with the default page:

    Swagger 2.0

  2. Find the Export/Import section (on the top of the page):

    Export/Import section

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

Exporting via D1 user interface

You can execute the services described above via the D1 Administration user interface.

See Exporting and importing repository configuration via D1 user interface for more information.

OpenAPI

For code samples, see

Export configuration by repository IDs
Export configuration by repository names
Export configuration by repository technical names
Import configuration