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:

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

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)

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

3. 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)

4. 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 request	Endpoint	Service description	Request query parameters	Form data	Returns
GET	https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/	Export repository configuration by IDs	sessionId, repositoryIds (array)	none	.zip file with repository configuration.
GET	https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-names	Export repository configuration by names	sessionId, repositoryNames (array)	none	.zip file with repository configuration.
GET	https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-technical-names	Export repository configuration by technical name	repositoryTechnicalNames (array)	none	.zip file with repository configuration.
POST	https://host:port/tribefire-services/api/v1/access.adx.admin/v1/import/configuration	Import repository configuration	none	autoSync, importRepositoryOption, importUsersOption, resource, useRuntimeValues

Parameters

The following table lists the parameters and their descriptions:

Name	Data type	Description
sessionId	string	The session ID returned when you authenticate.
repositoryIds	array	Array of one or more repository IDs, for example ["ab-cd-1234", "ef-gh-5678"].
repositoryNames	array	Array of one or more repository names, for example ["Repository name 1", "Repository name 2"].
repositoryTechnicalNames	array	Array of one or more repository technical names, for example ["Technical name 1", "Technical name 2"].
autoSync	boolean	Indicates whether affected repositories should be automatically synchronized after import.
importRepositoryOption	string	Specifies 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).
importUsers	boolean	Indicates whether users/roles/groups should be imported.
resource	string	The file system path to the previously exported .zip archive with repository configuration to be imported.
useRuntimeValues	boolean	Indicates 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:

   

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

   

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

   

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