Skip to main content
Delphix

Environment Export and Import using Masking Sync (KBA6164)

 

KBA

KBA# 6164

Applicable Delphix Versions

This document is relevant to the Masking Engine 6.0.2 and upwards
Major Release All Sub Releases
6.0 6.0.2.0

How to Export Using the Masking API

In 6.0.2, there are currently two methods of exporting an environment for import into another masking engine.

Method 1:  Environment export/import from the Masking GUI, as below.  

                  This method is xml-based.

Screenshot 2020-07-15 at 14.10.44.png

This method is being deprecated in favor of method 2.

 


Method 2:  Environment Sync using the Masking API

Screenshot 2020-07-15 at 14.18.07.png


This technical note focuses on the second method, using the Masking API to sync environments.

 

Note

Note:

Environment Sync APIs  are the preferred way of handling environment export/import versus  XML-based transfer.
 Please refer to the Delphix Masking documentation (maskingdocs.delphix.com) for  further information on the terms and functionalities used in this document.

https://maskingdocs.delphix.com/Managing_Multiple_Engines_for_Masking/Masking_API_Call_Concepts/

 

 

Prerequisites

You already have source and target masking engines configured, and you seek to export the objects within the environment from the source engine and import them to a target engine. An environment must exist or be created on the target engine to receive the environment objects being exported. Please refer to the documentation for further information on Managing Environments.

To export and import an environment:
  1. Exporting the Environment from the Source Masking Engine using the Masking Client API.

This example uses the following URL to access the masking api client front-end of the source engine:  Screenshot 2020-07-15 at 16.39.23.png

a) Log in into the Source engine via the Masking API Client (and Authorize). For information on logging into the Masking API Client please see our document Logging into and Connecting to the Masking API Client (KBA5754)

b) Get the object-id details of the environment to be exported. To do this, expand the sync section and then expand the GET /syncable-objects call.

Screenshot 2020-07-15 at 17.10.52.png

 

   From the object_type list, select 'Environment', as below,  then click on Screenshot 2020-07-15 at 14.23.21.png

Screenshot 2020-07-15 at 14.23.16.png

 

A successful 'get' will return a Response Body similar to:

Screenshot 2020-07-15 at 14.23.53.png

For our example we are interested in the environment with the objectIdentifier id of 2.

We take a note of the string required for the next step:

    {
      "objectIdentifier": {
        "id": 2
      },
      "objectType": "ENVIRONMENT",
      "revisionHash": "644e28d1404ac3494d3caef5980ac5e7800ad29b"
    }

The export call takes a JSON object that is a list of the objects to export.  While we 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 note that the desired object above is wrapped in square brackets in the export call below because the export call is expecting a list.

c)  Export the environment using Screenshot 2020-07-15 at 17.20.19.png

Add the 'object identifier' block from above, into the Parameter value field, then click Try it Out.

Screenshot 2020-07-15 at 14.36.42.png

A successful export should return a Response Body similar-looking to :

 

Screenshot 2020-07-15 at 14.36.59.png

Copy the whole block of data from the Response Body, this will be used to import the environment objects into the target engine.

 

2) Importing the Environment into the Target Masking Engine using the Masking Client API

 

a)  Log in into the Masking API client of the target engine, and Authorize
   
b)  Navigate to Screenshot 2020-07-15 at 14.53.55.png

Scroll down to:Screenshot 2020-07-15 at 14.54.40.png

 

Paste or copy into the Parameter value field the block of data gathered from the Environment export. Enter the environment_id that will be used to import the environment objects into. 

 

Note

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 re-creating the old environment name.

 

Screenshot 2020-07-15 at 14.55.59.png

 

Click Try it out to execute the import. If there are no errors and you get a 'Response Code' of 200 then the task is completed.


c)  It is possible that during the environment import you will get an algorithm-related error as per the sample error below.

Screenshot 2020-07-15 at 15.01.26.png

 

In this case you should also do a Sync export of the referenced algorithm and its related domain.


To do this 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.

i) Use  , Screenshot 2020-07-15 at 17.50.15.png , object_type=DOMAIN, to get the object Id/information to use for exporting the domain:

Screenshot 2020-07-15 at 15.16.34.png

In this scenario we are interested in the domain linked with the algorithm in the error, domain 'DOB':  
      {
      "objectIdentifier": {
        "id": "DOB"
      },
      "objectType": "DOMAIN",
      "revisionHash": "6dc0a42038c40842d80ab0ccd5ce64a2d7d5f926"
    }
    
 

ii) Provide this information in the Parameter value field for 'Sync - Export Masking Object', as below:

Screenshot 2020-07-15 at 15.19.43.png

 

Click on Try it out. If successful (Response Code 200),the exportResponseMetadata for the domain will be found under "Response Body" as per example below:

Screenshot 2020-07-15 at 15.20.54.png

Copy the information in the Response Body, this will be used to import the domain into the target masking engine.

 

iii) At the target engine, click Post - Import Masking Objects, paste in the copied domain-related information into 
the Parameter Value  field, click Try it out. A successful domain import will return a  response body as per example below.

Screenshot 2020-07-15 at 15.25.55.png

 

iv) Now attempt to import the Environment again. This time a successful Environment import will return a response body  whereby an import status of "SUCCESS'  returned.

Screenshot 2020-07-15 at 15.48.48.png

 

 

Note

Note:

It is possible that you may instead get further similar errors referencing other algorithms, for example:

"objectType": "ALGORITHM_REFERENCE", 
"importStatus": "FAILED", 
"failureMessage": "Inconsistent dependency ALGORITHM_REFERENCE AL_PXS_CUSTOM_EMAIL. Try syncing the original object." 

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 masking docs: "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". 

 

 

 

Related Articles

The following articles may provide more information or related information to this article:

  • link
  • link
  • link