Sync Environments with Async Export and Async Import (KBA9955)
KBA
KBA# 9955Applicable Delphix Versions
- Click here to view the versions of the Delphix engine to which this article applies
-
Date Release Feb 13, 2023 8.0.0.0 Jan 12, 2023 7.0.0.0 Releases Prior to 2023 Major Release All Sub Releases 6.0 6.0.14.0, 6.0.15.0, 6.0.16.0, 6.0.17.0, 6.0.17.1, 6.0.17.2
Async Export/Import of Environments using the Masking API
This technical note focuses on using the Masking API (async export & async import) to sync environments between masking engines.
Prerequisites
You have source and target masking engines already configured, and you want to export the objects within the environment from the source engine and import them to a target engine. An environment must previously exist on the target engine to receive the environment objects being exported. Please refer to the documentation for further information on Managing Environments.
To export a source environment
- Exporting the Environment from the Source Masking Engine using Async Export.
- Review the Env details of the environment to be exported. The simplest way to find this information is to go to the Source Masking Engine GUI Environments page as can be seen below:
From the list, take a note of the Environment ID you want to export.
- Log in into the Source engine via the Masking API Client (and Authorize). For information on logging into the Masking API Client, see Logging into and Connecting to the Masking API Client (KBA5754).
- The following steps are to be executed while logged into or connected to the Source Engine with the Masking API Client.
- Expand the sync section (by clicking on sync) and then expand GET /syncable-objects.
- From the
object_type
list, select Environment, as below, then click on
A successful 'get' will return a Response Body similar to:
For this example, you are interested in the environment with the objectIdentifier id of 22.
Copy or take a note of the string required for the next step:
Note: The export call in the next step takes a JSON object that is a list of the objects to export. While you only need a single object for the task at hand, it is written to handle multiple objects if needed. In JSON, lists are denoted with square brackets ([
and ]
) so you will see that the desired object above is wrapped in square brackets in the export call below because the export call is expecting a list.
- Export the environment using POST /export async from under sync.
- You will see the format of the expected input under the Parameters block, in the Model Example Value provided in the lower part of the screenshot below.
- Click on the block with the Example value (the block with the yellow background). This will automatically copy the Input format into the Parameter body (the block that contains the string
(required)
. - Add the 'object identifier' string copied earlier (from 1.e.), into the Parameter Value field, overwriting any text string in between '[' and ']' , then click as seen below:
A successful execution of the export request should return a Response Code of 200 and a Response Body similar-looking to the screenshot below, indicating that an async task has been started.
- You will see the format of the expected input under the Parameters block, in the Model Example Value provided in the lower part of the screenshot below.
The duration of the async export task is dependent on the number of environments and its objects that are being exported.
- To get the current status of the async task, take a note of the asyncTaskId as above. Navigate to
- Enter the async task id you noted earlier and click Execute API Request.
The status of the Async Export task should be returned, with a 'SUCCEEDED' status as below:
- Download the export into a file that can be imported into the Target masking engine. For this you need to take note of the export reference above, which is the value returned as reference. In this example it is:
EXPORT-ZXhwb3J0X2RvY3VtZW50X0tzRjdjZ3VRLmpzb24=
This value would be the same value as that returned as 'reference' when 'Post export-async' was initiated.- Navigate to:
- Provide input parameter expected in the
fileDownloadID
field:
Paste or copy in the 'EXPORT-xxxxxxx' reference noted earlier, as the Value for thefileDownloadId
, and click on
- Clicking on the Execute should return a 'success' response code of 200 and a Response body similar to:
- Click on the active link/string that starts with Download, a file will get downloaded to your desktop with the a filename similar to the following:
You can rename this file if you wish.
- Navigate to:
Note: A video demonstrating Async export of an Environment is provided below:
To Import the Environment on the Target Masking Engine
Complete the following procedure to import the Environment into the Target Masking Engine using the Masking Client API:
- On the Target masking engine, create a new environment into which the exported environment definitions will be imported.
(An existing environment can also be used).
Note: When performing an environment sync as described here, you must first find or create a destination environment on the target Engine. The import process will populate objects into the selected environment rather than automatically recreating the old environment name.
Make a note of the environment ID of the environment that you will be using to import into.
- Log in to the Target masking engine using the Masking API client and Authorize.
- Navigate to sync then
- Input or paste in the export file name generated via Async export from the source or master masking engine using Choose File.
- Decide on desired value for
force-overwrite
: true or false. - Add the environment Id of the environment (existing or pre-created) that you are importing into.
- Source-environment_id is required if there are ON-THE-FLY masking jobs in the environment being imported. If that is the case, another environment needs to be pre-created on the target engine prior to the import.
From the docs:
Example:
- Click Execute API Request to start the Async import. Take a note of the
asyncTaskId
for the Async task initiated for this import, as seen in this example of Response Body returned:
Dependent on the size of the file and number of objects being imported, this import may take a few minutes. Check the status of the async import task using the asyncTaskid returned by the import, and
.
A successful and completed import returns a similar response to the one below with statusSUCCEEDED
.
Note: The following is a video demonstrating Async import of an Environment:
How to handle errors during environment import
During the environment import, it is possible that you receive an algorithm-related error as seen below.
In this case one of the following extra actions is required before attempting another import of the environment:
- A Sync or Async export of the referenced algorithm and its related domain from the Source masking engine and import into the Target engine.
- If on the subsequent import, further algorithm-related errors get reported suggesting 'Try syncing the original object', then do an Async export of the Global Object from the source masking engine and async import it into the Target Engine. There is an example video of how to do this in the Global Object: Async Export (From Source Masking Engine) and Async Import (into Target engine) section.
Sync export of the referenced algorithm and related domain from the Source engine and import into the Target engine
- Return to the source Masking Engine and export the domain that is related to the algorithm referenced in the error. The domain Sync export will also include the masking key for the referenced algorithm.
- Use object_type=DOMAIN, to get the object Id/information to use for exporting the domain:
In this example, you are interested in the domain linked with the algorithm in the error, domain 'DOB':
{
"objectIdentifier": {
"id": "DOB"
},
"objectType": "DOMAIN",
"revisionHash": "6dc0a42038c40842d80ab0ccd5ce64a2d7d5f926"
}
- Provide this information in the Parameter
body
value field for Sync - Export Masking Object as seen in the image below.
- Click on .
If successful (Response Code 200), theexportResponseMetadata
for the domain will be found under Response Body as seen below:
- Copy the information in the Response Body, this will be used to import the domain into the target masking engine.
- Use object_type=DOMAIN, to get the object Id/information to use for exporting the domain:
- Go to the target engine.
- On the target engine, navigate to and click Post - Import Masking Objects.
- Paste in the copied domain-related information into the Parameter Value field.
- Click Execute API Request. A successful domain import will return a response body as per example below.
Async export and async import of a domain can also be done for a domain if preferred.
Global Object: Async Export (From Source Masking Engine) and Async Import (into Target engine)
If there are too many errors related to other algorithms then it maybe more time-efficient to do a Sync export and import of the Global_Object. As per the Continuous Compliance Engine documentation:
"When a user requests to export GLOBAL_OBJECT, every syncable algorithm, profile set, profile expression and domain on the engine will be exported as the bundle".
The following video demonstrates async export of a Global Object from a source masking engine.
The following video demonstrates async import of a Global Object to a target masking engine.
Checking Masking Debug Logs
The following video demonstrates the occurrence of an import error and how to check masking debug logs when an Async Import fails , here:
Related Articles
The following articles may provide more information or related information to this article: