Description

The JSONFileMaskReceiver takes an existing JSON file as a template and replaces the sensitive node with a synthetic value into a new JSON file.
 

This Receiver uses a JSON configuration file, which defines the element within the template file to replicate. It also defines a set of tags used within the template file as placeholders where generated test data will be inserted during the replication process. 


In this Article


When Should This Receiver be Used?

  • It should be used when sensitive data values in flat or nested JSON file(s) must be masked with synthetic test data. 


How Many Files Can Be Masked?

  • It can be used to mask values in a single file or multiple files within a specified directory.


How to Mask a Flat or Nested JSON File

Note: Use cases are provided later in this article.

  1. Select a Project and Project Version.
  2. Create a Domain with Attributes (i.e., Values) to be masked.
  3. Change the Domain's loopCount (see next section for more information).
  4. Create a Configuration file and place it in the appropriate directory.
  5. (Optional) Modify assigned Generators. 
  6. Assign the JSONFileMaskReceiver to the Domain.
  7. Configure the Receiver's Parameters.
  8. Configure the Receiver Attributes Property Keys.
  9. Create a Scenario for the Domain and download it.
  10. Run the command at the command line to generate a masked JSON file. 

 

Domain loopCount

  • Masking Single File - set to the maximum number of replacements within the file. 
    • Example - 4 elements will be masked in the file. The Domain loopCount should be '4'.

  • Masking Multiple Files - the number of replacements in one file must be multiplied by the number of files.
    • Example - 4 elements will be masked per file, and 5 files will be masked. The Domain loopCount should be '20' (e.g., 4 x 5 = 20).

  • Alternatively, a user can set the loopCount higher than the maximum number of replacements to ensure that all sensitive values are masked within the generated output file(s).


Receiver Parameters

The following parameters may be configured for the JSONFileMaskReceiver. Items with an asterisk* are required. 

  • sourcePath* - The location of the JSON source file. 
  • sourceSubDirectory - The subdirectory under the sourcePath directory where the JSON file is stored. 
  • sourceFileName - The name of the JSON source file. Only enter a value if a single JSON file will be masked. 
  • destPath* - The location to store the newly generated JSON output file. 
  • destSubDirectory - Defines an optional subdirectory under destPath where the clean masked file will be stored. If no value is entered, it will overwrite the source file since it uses the same name. 
  • configPath* - The location of the JSON configuration file. This file contains the information allowing the Receiver to parse the template JSON file and perform synthetic data replacement.
  • configSubDir - The subdirectory under the configPath directory where configuration and template files are stored. 
  • configName*- The name of the JSON configuration file. 


Receiver Attribute Property Keys

The Receiver defines one property key that can be modified on any of its associated Domain Attributes:

  • include - Defines whether the Domain Attribute will be used for masking.


File and Directory Config Tabs

The File and Directory Config Tabs are used to configure the event that triggers file or directory creation and the naming configuration for generated files or directories. Please click here for more information on how to use the File and Directory Config Tabs. 



Note: You can configure the Dynamic File Name for this Receiver before executing the Scenario through the GMUS API. Please refer to these pages to learn more:


Configuration File

The configuration file defines the path within the JSON file containing the sensitive values to be masked and the Domain Attribute that will be used to mask these values. Three pieces of information must be included in the configuration file: 

  • tag nodeIdentifier - Path to the sensitive data value within the JSON file. 
  • attributeIdentifier - Domain Name and Attribute that will be used to generate synthetic data and mask sensitive data values. 
  • useQuotes - Determines if quotes are needed in the generated output or not.
    • false - Quotes are not needed in the generated output file. When set to "false," the Attribute should only generate numbers, boolean (true/false), or null.
    • true -  Quotes are needed in the generated output file. The Attribute can generate any type of data.


<template>
      <tags>
            <tag nodeIdentifier='path in JSON template file' attributeIdentifier="@DomainName.AttributeName@" useQuotes="true or false"/>
      </tags>
</template>


Here is an example configuration file: 

<template>
  <tags>
    <tag nodeIdentifier='name' attributeIdentifier="@shipOrder.name@" useQuotes="true"/>
    <tag nodeIdentifier='shiporder.items.item.itemNumber' attributeIdentifier="@shipOrder.itemNumber@" useQuotes="false"/>
    <tag nodeIdentifier='shiporder.billTo.name' attributeIdentifier="@shipOrder.name@" useQuotes="true"/>
    <tag nodeIdentifier='shiporder.items.item.productId' attributeIdentifier="@shipOrder.productId@" useQuotes="true"/>
  </tags>
</template>


Sample JSON Template File

One or more JSON files containing sensitive data values must be present within the sourceSubDirectory parameter in the JSONFileMaskReceiver. Below is an example JSON file: 


[{ 
   "name":"AAA",
  "shiporder": {
    "shipto": {
      "name": "Acme Co",
      "address": "123 Road Runner Dr",
      "city": "Tuson",
      "country": "USA"
    },
    "items": {
      "item": [
        {
          "itemNumber": 10000000,
          "productId": 10010,
          "note": "Handle with care",
          "quantity": 3,
          "price": 10.95
        },
        {
          "itemNumber": 10000001,
          "productId": 88005,
          "note": "Handle with care",
          "quantity": 9,
          "price": 31.5
        },
        {
          "itemNumber": 10000002,
          "productId": 23422,
          "note": "Handle with care",
          "quantity": 5,
          "price": 57.35
        },
        {
          "itemNumber": 10000002,
          "productId": 23422,
          "note": "Handle with care",
          "quantity": 5,
          "price": 57.35
        }
      ]
    },
    "billTo": {
      "name": "Acme Co",
      "address": "123 Road Runner Dr",
      "city": "Tuson",
      "country": "USA"
    }
  }
}]


Use Case 1 - Mask Sensitive Values in a Single Template File

A tester wants to mask sensitive values within a JSON file with synthetically generated data. The JSONFileMaskReceiver can be used to accomplish this. 


Note: This example uses the sample configuration file and JSON template file provided above in this article. 


Prerequisites

  • The user has installed GenRocket Runtime.
  • The user has selected (or created) a Project/Project Version.


Step 1 - Create a Domain with Attributes for Masking Values

A ShipOrder Domain has been created with these Attributes: id, name, itemNumber, and productId. The id Attribute is created automatically. 



Step 2 - Change the Domain loopCount

The Domain Loop Count must be set to the maximum number of replacements within the file. For this example, the loopCount will be '4'.

This is because four values will be masked within the template file: name, item id, billing name, and product id. 



Step 3 - Create the Required Configuration File

This example uses the same configuration file shown earlier in this article. It should be placed in the location defined within the Receiver Parameters. Please see the next section for more information. 


Step 4 - Add the JSONFileMaskReceiver and Configure Parameters

Add the JSONFileMaskReceiver to the ShipOrder Domain. 



For this example, the following parameters have been modified within the JSONFileMaskReceiver:

  • sourceFileName - The name of the single JSON template file is 'SampleJSONFile.json'. 
  • destSubDirectory - The generated output file will be in a 'maskedOutput' subdirectory. 
    • Important: If a value is not entered for this parameter, the original file will be overwritten.  
  • configSubDir - The configuration file will be stored in a 'config' subdirectory. 
  • configName - The configuration file is named 'JSONConfig.xml.'



Step 5 - Configure Receiver Attributes Property Keys

Change the include parameter to 'false' for the id Attribute, as it is not needed for the generated output file. 



Step 6 - Create and Download a Scenario

Create a Scenario for the Domain and then use the Cloud icon to download it.



Step 7 - Run the genrocket -r Command to Generate Test Data

Open a Command Prompt or Terminal window and use the following command to generate the masked output file: 

genrocket -r <ScenarioName.grs>


Note: Make sure the directory path is correct before running the command. For example, if the Scenario is in your Downloads Folder, it should be there. 



Masked JSON Output File

[
    {
        "name": "JRWidgets.mobi",
        "shiporder": {
            "shipto": {
                "name": "Acme Co",
                "address": "123 Road Runner Dr",
                "city": "Tuson",
                "country": "USA"
            },
            "items": {
                "item": [
                    {
                        "itemNumber": 10000,
                        "productId": "VQZWRL",
                        "note": "Handle with care",
                        "quantity": 3,
                        "price": 10.95
                    },
                    {
                        "itemNumber": 10001,
                        "productId": "N2HYDK",
                        "note": "Handle with care",
                        "quantity": 9,
                        "price": 31.5
                    },
                    {
                        "itemNumber": 10002,
                        "productId": "1278TI",
                        "note": "Handle with care",
                        "quantity": 5,
                        "price": 57.35
                    },
                    {
                        "itemNumber": 10003,
                        "productId": "DRQBH4",
                        "note": "Handle with care",
                        "quantity": 5,
                        "price": 57.35
                    }
                ]
            },
            "billTo": {
                "name": "JRWidgets.mobi",
                "address": "123 Road Runner Dr",
                "city": "Tuson",
                "country": "USA"
            }
        }
    }
]


Use Case 2 - Mask Multiple JSON Template Files

Note: This use case has the same project setup as the previous one. It uses the same sample JSON template file (copied 5 times), configuration file, Domain, Attributes, Scenario, etc. The Receiver Parameters and loopCount will be different. 


Five files need to be masked in this use case and have been placed in a 'JSON Templates' subdirectory at the path defined for the resource.output.directory resource.  



Domain loopCount

The Domain loopCount will be '20' since 4 elements will be masked in each of the 5 files. Please note that if the loopCount is too low, not all masked output files will be generated.



JSONFileMaskReceiver Configuration

For this example, the following parameters have been modified within the JSONFileMaskReceiver:

  • sourceSubdirectory - JSON template files are in a subdirectory titled "JSONTemplates." 
  • destSubDirectory - Generated output files will be within a "maskedOutput" subdirectory. 
    • Important: If a value is not entered for this parameter, the original files will be overwritten. 
  • configSubDrectory - The configuration file will be stored in a "config" subdirectory. 
  • configName - The name of the configuration file has been entered.


Note: If multiple JSON template files are to be masked, the sourceFileName parameter should be blank.


Masked JSON Output Files

The same values will be masked for each file as in Use Case 1; however, it will be done for five files. These files will be created within the maskedOutput directory (shown below). 



Use Case 3 - Masking a List of Values (Array)

This example demonstrates how a list of values can be masked in a simple JSON file. In the JSON file below, the user wants to mask the full name and a list of account numbers for each customer: 


[
  { 
    "customer":[
      {
        "fullname": "April T Jones",
        "address": "123 Road Runner Dr",
        "city": "Tucson",
        "state": "AZ",
        "zipcode": "85071",
        "acctnumbers":[
          "108564",
          "206435"
        ]
       },
       {
        "fullname": "Sam E Willis",
        "address": "500 Nowhere St",
        "city": "Chicago",
        "state": "IL",
        "zipcode": "60607",
        "acctnumbers":[
          "108964",
          "306935"
        ]
      }
    ]
  }
]


Project Setup

A single Domain has been added to the Project and will be used for masking the JSON file. The Domain has two Attributes: name and acctNumber. 




The Domain's loopCount has been set to "4" because four items in the file need to be masked (2 per record).



The JSONFileMaskReceiver has been added, and a Scenario has been created for the Domain. 



JSONFileMaskReceiver Configuration

The following parameters have been configured for this example: 


Configuration File

The following configuration file will be used for this example:

<template>
  <tags>
    <tag nodeIdentifier='customer.fullname' attributeIdentifier="@JsonMask.name@" useQuotes="true"/>
    <tag nodeIdentifier='customer.acctnumbers' attributeIdentifier="@JsonMask.acctNumber@" useQuotes="true"/>
  </tags>
</template>


Masked Output

The generated file is shown below with the fullName and account numbers being masked with synthetic data: 

[
    {
        "customer": [
            {
                "fullname": "Basil S. Kizer",
                "address": "123 Road Runner Dr",
                "city": "Tucson",
                "state": "AZ",
                "zipcode": "85071",
                "acctnumbers": [
                    "10000",
                    "10001"
                ]
            },
            {
                "fullname": "Alla O. Goss",
                "address": "500 Nowhere St",
                "city": "Chicago",
                "state": "IL",
                "zipcode": "60607",
                "acctnumbers": [
                    "10002",
                    "10003"
                ]
            }
        ]
    }
]



Error 1 - Source and Destination Directories Must Be Different

This error occurs because the JSONFileMaskReceiver configuration is set up to create the masked file in the same path as the source file. GenRocket requires that the file(s) be generated in a different location than the source file to prevent a file overwrite. When the paths are the same, you will receive an error. 


Error Text

Source and Destination Directory must be different.


Reason

This error will occur if:

  • The sourcePath and destPath values are identical, with no additional subdirectory values.
  • The sourcePath and destPath values are identical, and the sourceSubDirectory and destSubDirectory values are identical.


Possible Solutions

  • Enter a value for the destSubDirectory parameter. 
    • You can create the folder if it does not exist. 
    • If not present in the defined path, it will be created automatically during test data generation (as long as you have the right permissions). 
  • Choose a different destPath and enter a subdirectory if required for the generated masked file(s). 


Error 2 - <Path>/File Name (The system cannot find the file specified)

This error occurs when the file is either not located in the specified directory or has been named incorrectly in the JSONFileMaskReceiver configuration. The file causing the error can be the source file or the configuration file. 


Error Example

C:\Users\username\output\config\jsonConfig.xml (The system cannot find the file specified)


Possible Solutions

  • Check the file name in the JSONFileMaskReceiver configuration to ensure it is correct. 
    • If not, change the file name and save the configuration. 
    • Then download the Scenario again and try to generate the masked data. 

  • Ensure the file resides in the specified path and directory. 
    • If not, either move the file or update the path/subdirectory information in the JSONFileMaskReceiver.