Description

Even though GenRocket is designed to run on a tester's or engineer's individual laptop or workstation, sometimes it is desirable to have users access GenRocket via a central application on a single computer.  The GenRocket Multi-User Server (GMUS) allows many users to generate data via a central client application. The GMUS gives client application's the ability to let multiple users simultaneously run GenRocket Scenarios and generate synthetic data.  The GMUS manages user requests by launching multiple instances of the GenRocket runtime engine, via the GenRocket API, to run multiple GenRocket Scenarios simultaneously.  The GMUS guards against Scenario collision when two or more user request to run the same Scenario whose Scenario state is set to true.  



GMUS Startup

The GMUS must be launched within a command lin terminal with the minimum of a port number.  The different options for launching the GMUS are defined below.


Running GMUS REST Server with PortNumber Only

The GMUS may be launched with its default settings via the -gmusr option:


genrocket -gmusr <portNumber>


Example

The following example launches the GMUS REST Server on port 8070:

genrocket -gmusr 8070


Running GMUS REST Server for secured requests with PortNumber Only

The GMUS may be launched with its default settings in the secured mode for https requests via the -gmussr option:


genrocket -gmussr <portNumber>


Example

The following example launches the GMUS REST Server for secured requests on port 8443:

genrocket -gmussr 8443


Running GMUS Socket Server with PortNumber Only

The GMUS may be launched with its default settings via the -gmuss option:

genrocket -gmuss <portNumber>


Example

The following example launches the GMUS Socket Server on port 4445:

genrocket -gmuss 4445


Launching GMUS with Properties File and Port Number

The GMUS allows for configuration options to be defined within a properties file and loaded via the -gmusp option:


REST

genrocket -gmusp <propertiesFileWithPath> -gmusr <portNumber>


REST for secured requests

genrocket -gmusp <propertiesFileWithPath> -gmussr <portNumber>


Socket

genrocket -gmusp <propertiesFileWithPath> -gmuss <portNumber>


The GMUS configuration options are the following:

  • sendMail=true - defines whether or not to send mail on completion of Scenario runs (Default is false).
  • memoryLimit=100 - defines whether Memory available to run a scenario should be minimum 100 MB, else scenario will go into the queue (Default = 50 MB).
  • cpuUsage=0.99 - defines the CPU usage limit after which Scenarios should not be immediately run, but place into the queue. The cpuUsage value should lie within an interval of 0.0 - 1.0 (Default 0.95).   
    • A value of 0.0 means that all CPUs are actively idle during the recent period of time observed 
    • A value of 1.0 means that all CPUs are actively running at max capacity 100% of the time during the recent period being observed
  • scenarioSizeLimit=1000 - Defines the maximum number of rows a Scenario is allowed to keep in memory when the inMemory flag is set to true (Default 5000000).
    • GenRocket checks the scenarioSizeLimit by multiplying the number of Attributes by the loopCount (loopCount * number of Attributes)
    • If the scenarioSizeLimit is exceeded, GenRocket will not run the Scenario and respond with the following message:
      • Scenario Size exceeds the limit to run in memory. Hence, Can not generate data in memory. Please set inMemory to false

Examples Properties File


sendMail=true
memoryLimit=100
cpuUsage=0.90
scenarioSizeLimit=100000


Launching GMUS with Properties File

The following example launches the GMUS with a properties file and on port 8070:


 genrocket -gmusp /home/jDoe/Desktop/gmusprop.properties -gmusr 8070


Registering Client Application with GenRocket

In order to use the GMUS, your client application must first be registered within your GenRocket organization. To register your application go to your "My Organization" page.  At the bottom of the page, select the New Application button.



Enter your application name, a brief description (optionally), and click the Save button.  


  

Once saved, GenRocket will receive your request for an application ID.  When your client application is successfully registered, it will be given a unique UUID and you will be notified by email of your successful registration. Your client application will use this UUID when makes requests to run Scenarios via the GMUS. The GMUS will use the client application UUID to validate the client application can run GenRocket Scenarios and generate synthetic test data.


Registering a Client Application User with GenRocket

Users that will use your GenRocket Registered Client Application must be registered through your client application.  When the user is successfully registered with the Client Application, a UUID will be assigned to the user and passed back to the client application.  The client application must store the user's GenRocket UUID.



A User Generating Synthetic Data via the Client Application

Once a user is registered with your GenRocket Registered Client Application, they can access their client application to select a Scenario and have the application use the GMUS to run a Scenario and generate synthetic data.



User Registration REST Request

The example below shows the URL and payload to send when making a RESTful request to register a User with your GenRocket Client Application.


Parameters (with example values):

{
    "username":"jane.doe@gmail.com", 
    "password":"???", 
    "clientAppId": "5d4f326e-1e47-abcd-ba66-7c2aaa86d445"
}

 

GMUS REST Examples 


Run a Scenario when inMemory parameter is False

A REST request is made to the GMUS to run a Scenario with the inMemory parameter set to false.   When inMemory is false, all active Receivers will output data to their respective destinations. 


Parameters (with example values):

{

  "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",
  "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",
  "username"    : "jane.doe@gmail.com",
  "scenario"    : "UserScenario.grs",
  "scenarioPath": "/home/jDoe/Download/output",
  "inMemory"    : false

}


Run a Scenario when inMemory parameter is True

A REST request is made to the GMUS to run a Scenario with the inMemory parameter set to false.   When inMemory is false, all active Receivers will output data to their respective destinations. 


Parameters (with example values):

{
    "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",
    "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",
    "username"    : "jane.doe@gmail.com",
    "scenario"    : "TestScenario.grs",
    "scenarioPath": "/home/jDoe/Downloads/output",
     "inMemory"   : true
}


Use the API to Modify a Scenario Before Execution

The GMUS can modify any Scenario, in real-time, prior to its execution, by adding GenRocket API commands to the request payload. The following example adds API sub-elements to the request payload to take the following actions on the loaded Scenario before execution:

  • scenarioClear
  • domainAdd
  • attributeAdd
  • generatorAdd
  • receiverAdd
  • domainSetLoopCount

The loading of the Scenario and running of the Scenario will be taken care of by GMUS.


{
    "clientAppId": "b13b53ba-487e-41e2-8245-d505b767576f",
    "clientUserId": "16aa678b-0777-426f-be33-ea0a930af0ae",
    "username": "jane.doe@gmail.com",
    "scenario": "UserScenario.grs",
    "scenarioPath": "/home/UserName/Downloads/output",
    "inMemory": false,
    "api": [
        {"methodName": "scenarioClear"},
        {
            "methodName": "domainAdd",
            "parameters": {
                "domainName": "User",
                "primary": true
            }
        },
        {
            "methodName": "attributeAdd",
            "parameters": {"attributeName": "User.ssn"}
        },
        {
            "methodName": "generatorAdd",
            "parameters": {
                "attributeName": "User.ssn",
                "generatorName": "com.genRocket.generator.RangeConstantGen",
                "requiredGeneratorParameters": {
                    "suffix": "firstName",
                    "prefix": "#{User.id}"
                }
            }
        },
        {
            "methodName": "receiverAdd",
            "parameters": {
                "domainName": "User",
                "canonicalName": "com.genRocket.receiver.XMLFileReceiver",
                "receiverName": "XMLFileReceiver",
                "parameterMap": {
                    "path": "#{resource.output.directory}",
                    "fileName": "User.xml"
                }
            }
        },
        {
            "methodName": "domainSetLoopCount",
            "parameters": {
                "domainName": "User",
                "loopCount": "100000"
            }
        }
    ]
}


Run multiple scenarios

A REST request is made to the GMUS to run multiple scenarios.  When running multiple scenarios, the inMemory parameter is ignored.


URL:  http://localhost:8070/rest/scenarios


Parameters (with example values):

{
    "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",
    "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",
    "username"    : "jane.doe@gmail.com",
    "scenarios"   : ["DepartmentScenario.grs","UserScenario.grs", "AddressScenario.grs"],
    "scenarioPath": "/home/jDoe/Downloads/output"
}



Run multiple scenarios by Directory

A REST request is made to the GMUS to run all the scenarios present in a directory.  When running multiple scenarios, the inMemory parameter is ignored.


URL:  http://localhost:8070/rest/scenariosByDir


Parameters (with example values):

{  
  "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",   
  "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",   
  "username"    : "jane.doe@gmail.com",    
  "scenarioPath": "/home/jDoe/Downloads/output" 
}


Run a ScenarioChain 

A REST request is made to the GMUS to run a ScenarioChain.  When running a ScenarioChain, the inMemory parameter is ignored.


URL:  http://localhost:8070/rest/scenarioChain


Parameters (with example values):

{
    "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",
    "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",
    "username"    : "jane.doe@gmail.com",
    "scenario"    : "AllScenarioChain.grs",
    "scenarioPath": "/home/jDoe/Downloads/output"
}


GMUS Localhost Web Management Options


Monitoring the GMUS Queue

You can monitor the GMUS queue with the following localhost web command.


http://localhost:<portNumber>/rest/listQueue


Example: http://localhost:8070/rest/listQueue


Clearing the GMUS Queue


http://localhost:<portNumber>/rest/clearQueue  


Example: http://localhost:8070/rest/clearQueue  


Clearing the Queue by ID


http://localhost:<portNumber>/rest/clearQueueById


 Example: http://localhost:8070/rest/112


GMUS REST for secured requests 

In order to run GMUS for secured requests, your request URL must have the domain, genrocket.com instead of localhost. If you are on Windows, you need to add the domain name in C:\Windows\System32\Drivers\etc\hosts file. If you are on Linux/Mac, you need to add the domain name in /etc/hosts file. You need to update line that starts with 127.0.0.1 to something like 


127.0.0.1 localhost test.genrocket.com


Run a Scenario from a secured request:

A secured REST request is made to the GMUS to run a Scenario on port 8443.  


Parameters (with example values):

{

  "clientAppId" : "5d4f326e-1e47-abcd-ba66-7c2aaa86d445",
  "clientUserId": "9dd4094a-abcd-4284-aa45-fdcc8c38d6b5",
  "username"    : "jane.doe@gmail.com",
  "scenario"    : "UserScenario.grs",
  "scenarioPath": "/home/jDoe/Download/output",
  "inMemory"    : false

}