Repository Export and Import

Sentinet provides Export and Import capabilities for any Repository entity registered in the Repository. For example, Export and Import allows administrators to copy any Repository entity from one environment (for example: staging) to another (for example: production).

Note

Sentinet provides a separate feature of cloning selected service versions under the same service, or cloning service agreements. This feature is not related to Export/Import, because it always operates within the same Sentinet environment and applies only to service versions and service agreements. Select service version in the Repository tree and click Clone toolbar button. A new service version or service agreement is always created in Draft state, regardless of the state of the cloned object.

Repository Export/Import capability is meant to synchronize different Sentinet environments to support API solutions lifecycle management. Even though it is not required, it is recommended to plan ahead for possible export and import procedures.

Export and Import Mechanics

Every entity in the Repository has a globally unique identifier, a GUID, which is called entity Key. Repository entity is exported in the Sentinet Export Package along with its Key, associated properties and all dependent entities along with their own Keys and properties.

An export package is a single flat file that typically contains a complete copy of all dependent entities recorded with their unique identifiers. By default, an export package is saved with the extension .sentinet even though it is in XML format. Sentinet XML export packages can be post-processed after export, or pre-processed before import by any external XML processing script or tools.

When a Sentinet export package is imported into a new environment, the import process follows these steps:

  1. Entities, identified by Keys in the export package, not found are created.

  2. Entities, identified by Keys in the export package, that exist are updated.

  3. Any possible conflict, causing a potential inconsistent state in the Sentinet Repository, will cause an abort of the import process with errors, and without altering the Sentinet Repository. Sentinet Administrators can resolve conflicts by changing either target environment or by changing the export package content and repeating the import process until it succeeds.

Any Sentinet Repository object can be directly exported and imported, except for two object types:

  1. Sentinet Users. Export/Import of Sentinet users can potentially compromise security and is restricted to interactive management only.

  2. Sentinet Nodes. Sentinet Nodes are logical Repository entities tightly connected with the physical deployments of Sentinet Nodes. When Nodes are in different environments, these physical deployments usually have different properties associated with Nodes, such as Node base addresses and X.509 certificate identities.

    Sentinet Nodes which are meant to be synchronized (linked) over different environments, must have exact same Node Key (GUID), even though their other properties can be different. Sentinet export/import process of the virtual services has all the intelligence to automatically replace virtual services' addresses, once virtual services are imported in a new environment.

Note

To ensure Sentinet Nodes in different environments are synchronized, make sure to register them with the exact same Node Key (GUID). The first Node can be registered with auto-generated Node Key. All other Nodes should be assigned the same Node Key:

Assigning Node Id
Figure. Assigning Node Key to a new Sentinet Node to make it logically related to a Node in a different environment.
Note

In some cases, when exported objects’ Keys or Node Keys do not match related exported and imported environments, Sentinet users may use advanced techniques to change objects’ Key using Sentinet Administrative Console to “pre-synchronize” environments:

  1. For example, the Sentinet Node in the source environment was created with a different Key as in the target environment. At some later point, the Sentinet user realizes, that the Sentinet Nodes in these environments cannot be used for virtual services export/import, because their Node Keys are different. Sentinet user can change the Sentinet Node Key in either environment to “pre-synchronize” both environments. Changing Node Key from the Sentinet Administrative Console will require re-registration of the physical Node using Node Configuration Wizard.
  2. Another (better) option is to use User Interactive mapping between Nodes in different environments when Nodes’ Keys are not the same (described in Mapping Unresolved Nodes chapter).
Important

Typically, export packages are meant be used between Sentinet instances of the same version. Importing export package created with older version of Sentinet into the newer version of Sentinet does not guarantee complete accuracy or success of the import process.

Export

Sentinet export package file can be produced in two ways:

  1. Using Sentinet Administrative console.

  2. Using Sentinet Export.exe command-line utility installed with the Sentinet Repository Application in the root of the Sentinet installation.

Export using Sentinet Administrative Console

  1. Select Repository object to be exported in the Sentinet Export package and click EXPORT toolbar button or right-click Export popup menu option.

    EXPORT toolbar button and Export popup menu option
    Figure. EXPORT toolbar button and Export popup menu option.

  2. The Administrative Console sends a request to the Repository Web Services application to build the object’s dependencies tree. While the request is being processed, the Sentinet Administrative console may briefly show an animated screen “Building dependencies”. Once dependencies are built, the user can select all or some of the dependent objects to be included in the export package by placing check-mark in the checkbox located next to a tree element. Placing check-mark against the Repository root element of the tree, automatically places check-marks on all tree elements, effectively instructing Sentinet to include all dependencies of the exported object. References to dependent objects are always a part of the export package regardless whether these dependent objects are included in the export package or not.

    When a package is exported to a different Sentinet Repository, all existing objects referenced in the export package will be updated in the destination Repository. If an object from a package is not found in the destination Repository, it will be created. If dependent object is not included in the export package (while it is referenced as dependency), and it is not found in the destination Repository, the import process will abort with an error. Object which is being exported, is always check-marked and cannot be unchecked.

    Dependency tree for the export package
    Figure. Dependency tree for the export package with checkmarked Repository root element (which includes all dependencies).

  3. Provide Package File Name and Click Finish button. Export package file with the extension .sentinet will be downloaded by the browser.

Export using command-line utility

Export.exe utility uses the Sentinet Web Services Management API to export Sentinet Repository objects into the Sentinet export package.

Before running Export.exe utility make sure that:

  1. Export.exe.config file is located in the same directory as Export.exe file.

  2. Export.exe.config file defines Repository Web Service endpoint address for the destination Repository (typically only the machine host address must be changed in the default endpoint address, https://localhost/Sentinet/RepositoryService.svc/repository/username).

Unlike Sentinet Administrative Console, Export utility can export more than one Repository object at a time (including all dependencies of the exported object). Run Export.exe from the command prompt with no command line arguments to see its arguments list, arguments description and examples. If /u or /p arguments for username and password are not specified in a command-line, user will be prompted to enter them.

Note

Export.exe utility command arguments:

Usage: Export.exe <key>... [/f:<file name>] [/u:<user name>] [/p:<password>] [/np] [/d]

<key> - unique key of the entity to be exported. More than one key can be provided separated by space. /f:<filename> - export package file name (if not provided, then file named "<key>.sentinet" will be created in the current directory). /u:<username> - username to be used for service authentication (can include realm or domain name, example: "DOMAIN\user"). /p:<password> - password to be used for service authentication; /np - do not prompt for username and password; /d - include in the package dependent entities (entities that are dependencies of those entities listed by the <key> argument).

Examples:

Export 53E58E64-C08F-4F8C-A3FF-10287A54F46B Export 53E58E64C08F4F8CA3FF10287A54F46B /u:admin /f:"c:\temp\export.sentinet" Export 53E58E64-C08F-4F8C-A3FF-10287A54F46B /u:TEST\admin /p:mypassword Export 53E58E64C08F4F8CA3FF10287A54F46B 982D942217B242F2A66BE4CFC4F2E792 /d

Import

Sentinet export package file can be imported in two ways:

  1. Sentinet Administrative console.

  2. Using Sentinet Import.exe command-line utility installed with the Sentinet Repository Application located in the root directory of the Sentinet installation.

Import using Sentinet Administrative Console

  1. Select Sentinet root Repository tree element and click IMPORT toolbar button or right-click and select Import popup menu option.

    IMPORT toolbar button
    Figure. IMPORT toolbar button and Import popup menu option.

  2. In the File Open dialog box select a Sentinet export package file. Import to Repository dialog box shows all objects included in the export package. By default, all objects will be imported (check-marked). Unselect objects, which you would like not to be imported. Click Test Import button to test the destination Repository for consistency by mimicking an import (no changes are made during Test Import even if consistency is identified). Click Finish button to import the export package and change the Repository if consistency is preserved.

    Test Import and Finish buttons
    Figure. Test Import and Finish buttons.

Mapping Unresolved Nodes

When Sentinet Administrative Console loads an export package for import, it may identify that some Sentinet Nodes in the export package have different Nodes Keys in the source and target environments. That means that Sentinet will not be able to import this package, because it will not know how to find matching Sentinet Node in the target environment given Node Key of the Sentinet Node in the source environment. Import to Repository dialog box in this case shows the list of Nodes (with their Node Type and original Node Key), which were not found in this target environment (see more in the Export and Import Mechanics chapter).

Unresolved Node
Figure. Unresolved Node of Mixed Transport mode Type with Node Key cf904c3f-954f-4587-846f-68e3b66c5f83 and Resolve button.

Click Resolve button to navigate through Repository tree to select the Node in this target environment that original Node will be mapped to during the import process (see figure above). Sentinet will automatically show only those Nodes that can be selected based on their matching Node Type.

Selecting Node
Figure. Selecting Node for import mapping.

Once the Node is selected, the Import to Repository dialog box shows the mapping between the Node in the export package and the Node in this target environment. You can now proceed with the import.

Mapped Sentinet Nodes
Figure. Mapped Sentinet Nodes.

Import using command-line utility

Import.exe utility uses the Sentinet Web Services Management API to import Sentinet export package(s) to the Repository identified by its Web Service endpoint address configured in the Import.config file.

Before running Import.exe utility make sure that:

  1. Import.exe.config file is located in the same directory as Import.exe file.

  2. Import.exe.config file defines Repository Web Service endpoint address for the destination Repository (typically only the machine host address must be changed in the default endpoint address, https://localhost/Sentinet/RepositoryService.svc/repository/username

Unlike Sentinet Administrative Console, the Import utility can import more than one package at a time. Run Import.exe from the command prompt with no command line arguments to see its arguments list, arguments description and examples. If /u or /p arguments for username and password are not specified in a command-line, user will be prompted to enter them.

Note

Import.exe utility command arguments:

Usage: Import.exe <file name>... [/u:<user name>] [/p:<password>] [/np] [/v]

<file name> - Sentinet Repository Export Package file name (*.sentinet). More than one file name can be provided separated by space. /u:<username> - username to be used for service authentication (can include realm or domain name, example: "DOMAIN\user"). /p:<password> - password to be used for service authentication; /np - do not prompt for username and password; /v - validate Test import package and do not change Repository.

Examples: Import "My Package.sentinet" Import "My Package.sentinet" /u:admin Import MyPackage.sentinet /u:TEST\admin /p:mypassword Import "Package 1.sentinet" "Package 2.sentinet" /u:admin /p:mypassword /v