API for UI Users

Creating and Editing Virtual Locations

Creating and editing virtual locations in the UI requires three steps as described below.

To create or edit a virtual location from the UI:

  1. Set Location: this API call should be executed before opening the UI; the input for this API is an object containing the following sub-objects.

    • newLocationData: represents a new location and contains these parameters:

      • id: the virtual locations ID (optional). If the parameter is not passed, the ID will be generated by the Location Editor and returned in the response
      • name: the virtual locations name (mandatory).
      • description: a description for the virtual locations (optional).
    • existingLocation: represents an existing location; contains the locationMetadata of a previously created location.

      Note: Only newLocationData or existingLocation should be included.

    • globalConfig: this object represents the global configurations which refer to all locations, see Editing Global Configurations. This object is passed when editing a location for display only. It can't be changed while editing a location.

      Note: For the Location's Capture Packets option to be configurable in the GUI, the Global Configuration object (globalConfig) must be included, and the Global Capture Packets parameter within it (isCaptureClientPl) must be set to "True".

    The API returns an ID which is used in Step 2 to open the UI and later to get the edited virtual location object.

    See Set Location Examples.

  2. Open the Location Editor GUI with the following URL:

    http://ip:port/shunra/locationeditor?tempdirid=<id from step 1>&readonly=<true/false>

    Query parameters:

    • tempdirid: the ID that was received in Step 1.
    • readonly: indicates whether the GUI will be editable or read only.
  3. Finish editing: After the edit is finished and "OK/Cancel" is clicked, the UI calls the javascript function "locationEditCompleted" which is expected to be part of the opener of the UI, see Public JavaScript API for UI Openers. This function should call another API "Finish editing" which clears all data related to edited location and returns the result of the edit – the new location.

    Query parameter:

    tempDirId: the ID returned in the "setLocation" API.

    See Finish Edit Location Examples.

Set Location Examples

Request

JSON

URL http://ip:port/shunra/api/locationeditor/location
HTTP Method POST
HTTP Headers

Content-Type: application/json

Accept: application/json

Authorization: See Web Services Authentication.

Body (New Location)
{
    "newLocationData": {
        id: "76c29fc2538d4de7a9a839bc18dc6b4f",
        name: "location name",
        description: "location description"
    },
    "existingLocation": null,
    "globalConfig": {
        "settings": {
            "isCaptureClientPl": false,
            "packetListMaxSizeMB": 300,
            "isPacketListCaptureCyclic": false
        },
        "excludeIps": [{
            "from": "172.30.2.150",
            "to": "172.30.2.150",
            "protocol": 0,
            "port": 0
        }]
    }
}
Body (Existing Location)
{
    "newLocationData": null,
    "existingLocation": {
        "srcIp": null,
        "destIp": null,
        "srcIpRange": null,
        "destIpRange": {
            "include": [],
            "exclude": []
        },
        "id": "76c29fc2538d4de7a9a839bc18dc6b4f",
        "name": "location name",
        "type": "CUSTOM",
        "description": "location description",
        "ntx": null,
        "selectedFlow": null,
        "latency": 113,
        "packetloss": 0.1,
        "bandwidthIn": 2000.0,
        "bandwidthOut": 1000.0,
        "isCaptureClientPl": false,
        "sharedBandwidth": true,
        "ntxMetadata": null,
        "glMetadata": null
    },
    "globalConfig": {
        "settings": {
            "isCaptureClientPl": false,
            "packetListMaxSizeMB": 300,
            "isPacketListCaptureCyclic": false
        },
        "excludeIps": [{
            "from": "172.30.2.150",
            "to": "172.30.2.150",
            "protocol": 0,
            "port": 0
        }]
    }
}

XML

URL http://ip:port/shunra/api/locationeditor/location
HTTP Method POST
HTTP Headers

Content-Type: application/xml

Accept: application/xml

Authorization: See Web Services Authentication.

Body (New Location)
<locationData>
    <newLocationData>
        <id>76c29fc2538d4de7a9a839bc18dc6b4f</id>
        <name>location name</name>
    </newLocationData>
    <globalConfig>
        <settings>
            <isCaptureClientPl>false</isCaptureClientPl>
            <packetListMaxSizeMB>300</packetListMaxSizeMB>
            <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic>
        </settings>
        <excludeIps>
            <From>172.30.2.51</From>
            <To>172.30.2.51</To>
            <Protocol>0</Protocol>
            <Port>0</Port>
        </excludeIps>
    </globalConfig>
</locationData>
Body (Existing Location)
<locationData>
    <existingLocation>
        <destIpRange>
            <exclude>
                <from>172.30.2.50</from>
                <to>172.30.2.50</to>
                <port>0</port>
                <protocol>0</protocol>
            </exclude>
        </destIpRange>
        <id>76c29fc2538d4de7a9a839bc18dc6b4f</id>
        <name>new location</name>
        <type>CUSTOM</type>
        <latency>113</latency>
        <packetloss>0.1</packetloss>
        <bandwidthIn>2000.0</bandwidthIn>
        <bandwidthOut>1000.0</bandwidthOut>
        <isCaptureClientPl>false</isCaptureClientPl>
        <sharedBandwidth>true</sharedBandwidth>
    </existingLocation>
    <globalConfig>
        <settings>
            <isCaptureClientPl>false</isCaptureClientPl>
            <packetListMaxSizeMB>300</packetListMaxSizeMB>
            <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic>
        </settings>
        <excludeIps>
            <From>172.30.2.51</From>
            <To>172.30.2.51</To>
            <Protocol>0</Protocol>
            <Port>0</Port>
        </excludeIps>
    </globalConfig>
</locationData>

 

Response

JSON

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/json; charset=UTF-8
HTTP Body
{
    error: null,
    errorCode: 0,
    data: "76c29fc2538d4de7a9a839bc18dc6b4f"
}

XML

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/xml; charset=UTF-8
HTTP Body
<error />
<errorCode>0</errorCode>
<data>76c29fc2538d4de7a9a839bc18dc6b4f</data>

Finish Edit Location Examples

Request

JSON

URL http://ip:port/shunra/api/locationeditor/location/{tempDirId}
HTTP Method DELETE
HTTP Headers

Content-Type: application/json

Accept: application/json

Authorization: See Web Services Authentication.

Body None

XML

URL http://ip:port/shunra/api/locationeditor/location/{tempDirId}
HTTP Method DELETE
HTTP Headers

Content-Type: application/xml

Accept: application/xml

Authorization: See Web Services Authentication.

Body None

 

Response

JSON

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/json; charset=UTF-8
HTTP Body
{
    "error": null,
    "errorCode": 0,
    "data": {
        "id": "76c29fc2538d4de7a9a839bc18dc6b4f",
        "locationMetadata": {
            "srcIp": null,
            "destIp": null,
            "srcIpRange": null,
            "destIpRange": {
                "include": [],
                "exclude": [{
                    "from": "172.30.2.50",
                    "to": "172.30.2.50",
                    "port": 0,
                    "protocol": 0
                }]
            },
            "id": "76c29fc2538d4de7a9a839bc18dc6b4f",
            "name": "new location",
            "type": "CUSTOM",
            "description": null,
            "ntx": null,
            "selectedFlow": null,
            "latency": 113,
            "packetloss": 0.1,
            "bandwidthIn": 2000.0,
            "bandwidthOut": 1000.0,
            "isCaptureClientPl": false,
            "sharedBandwidth": true,
            "ntxMetadata": null,
            "glMetadata": null
        }
    }
}

XML

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/xml; charset=UTF-8
HTTP Body
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<serverResponse>
    <errorCode>0</errorCode>
    <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="generatedLocation">
        <id>76c29fc2538d4de7a9a839bc18dc6b4f</id>
        <locationMetadata>
            <destIpRange>
                <exclude>
                    <from>172.30.2.50</from>
                    <to>172.30.2.50</to>
                    <port>0</port>
                    <protocol>0</protocol>
                </exclude>
            </destIpRange>
            <id>76c29fc2538d4de7a9a839bc18dc6b4f</id>
            <name>new location</name>
            <type>CUSTOM</type>
            <latency>113</latency>
            <packetloss>0.1</packetloss>
            <bandwidthIn>2000.0</bandwidthIn>
            <bandwidthOut>1000.0</bandwidthOut>
            <isCaptureClientPl>false</isCaptureClientPl>
            <sharedBandwidth>true</sharedBandwidth>
        </locationMetadata>
    </data>
</serverResponse>

Back to top

Editing Global Configurations

Global Configurations are configurations which affects all the tests running on Network Virtualization.

Editing the Global Configurations in the UI requires three steps as described below.

To edit the Global Configuration from the UI:

  1. Set Configuration: This API should be called before opening the UI. The request body can be either empty for creating a new Global Configurations object, or contain the "data" of a Global Configurations object previously created for editing it.

    It returns an ID which is used in Step 2 to open the GUI and later to get the edited Global Configuration object.

    See Set Configuration Examples.

  2. Open the Configuration Editor GUI with the following URL:

    http://ip:port/shunra/configeditor?tempdirid=<id from step 1>&readonly=<true/false>

    Query parameters:

    • tempdirid: the id that was received in Step 1.
    • readonly: indicates whether the GUI will be editable or read only.
  3. Finish Editing: After the editing is comleted and "OK/Cancel" is clicked, the UI calls a javascript function " configurationEditCompleted " which is expected to be part of the opener of the UI, see Public JavaScript API for UI Openers. This function should call another API "Finish editing" which clears all data related to edited configuration and returns the result of the edit – the new configuration object. Query parameter:

    tempDirId: the ID that was returned in "Set Configuration"

    See Finish Edit Configuration Examples.

Set Configuration Examples

Request

JSON

URL http://ip:port/shunra/api/locationeditor/config
HTTP Method POST
HTTP Headers

Content-Type: application/json

Accept: application/json

Authorization: See Web Services Authentication.

Body (New Configuration) None
Body (Existing Configuration)
{
    "isCaptureClientPl": false,
    "packetListMaxSizeMB": 300,
    "isPacketListCaptureCyclic": true,
    "excludeIps": [{
        "from": "172.30.2.150",
        "to": "172.30.2.150",
        "protocol": 0,
        "port": 0
    }]
}

XML

URL http://ip:port/shunra/api/locationeditor/config
HTTP Method POST
HTTP Headers

Content-Type: application/xml

Accept: application/xml

Authorization: See Web Services Authentication.

Body (New Configuration) None
Body (Existing Configuration)
<?xml version="1.0" encoding="UTF-8" ?>
<configuration>
    <settings>
        <isCaptureClientPl>false</isCaptureClientPl>
        <packetListMaxSizeMB>300</packetListMaxSizeMB>
        <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic>
    </settings>
    <excludeIps>
        <From>172.30.2.50</From>
        <To>172.30.2.50</To>F
        <Protocol>0</Protocol>
        <Port>0</Port>
    </excludeIps>
</configuration>

 

Response

JSON

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/json; charset=UTF-8
HTTP Body
{
    error: null,
    errorCode: 0,
    data: "76c29fc2538d4de7a9a839bc18dc6b4f"
}

XML

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/xml; charset=UTF-8
HTTP Body
<error />
<errorCode>0</errorCode>
<data>81f64d6bc97f4430b9165772197835c7</data>

Finish Edit Configuration Examples

Request

JSON

URL http://ip:port/shunra/api/locationeditor/config/{tempDirId}
HTTP Method DELETE
HTTP Headers

Content-Type: application/json

Accept: application/json

Authorization: See Web Services Authentication.

Body None

XML

URL http://ip:port/shunra/api/locationeditor/config/{tempDirId}
HTTP Method DELETE
HTTP Headers

Content-Type: application/xml

Accept: application/xml

Authorization: See Web Services Authentication.

Body None

 

Response

JSON

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/json; charset=UTF-8
HTTP Body
{
    "error": null,
    "errorCode": 0,
    "data": {
        "settings": {
            "isCaptureClientPl": false,
            "packetListMaxSizeMB": 300,
            "isPacketListCaptureCyclic": false
        },
        "excludeIps": [{
            "from": "172.30.2.150",
            "to": "172.30.2.150",
            "protocol": 0,
            "port": 0
        }]
    }
}

XML

HTTP Response Code 200 - OK
HTTP Headers Content-Type: application/xml; charset=UTF-8
HTTP Body
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<serverResponse>
    <errorCode>0</errorCode>
    <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="configuration">
        <settings>
            <isCaptureClientPl>false</isCaptureClientPl>
            <packetListMaxSizeMB>300</packetListMaxSizeMB>
            <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic>
        </settings>
        <excludeIps>
            <From>172.30.2.50</From>
            <To>172.30.2.50</To>
            <Protocol>0</Protocol>
            <Port>0</Port>
        </excludeIps>
    </data>
</serverResponse>

Using the Global Configuration Object

The configuration parameters stored in the global configuration object can be used for the Set Configuration for Location Based Emulation.

The Global Packet Capture parameter "isCaptureClientPl" should be passed in the Location Based Mode Start Test request; refer to Start Test, Location Based Mode.

Note: Starting a test with "isCaptureClientPl" set to False will stop the Packet capture for all users.

Back to top

Public JavaScript API for UI Openers

The "Openers" of the UIs should implement the following API in javascript:

  • configurationEditCompleted(okClicked): for Configuration Editor opener

    • okClicked: is a boolean indicating whether the Configuration Editor was closed by clicking the "OK" button or the editing was canceled ("cancel" button).
    • Is called after the editor is closed.
  • locationEditCompleted(okClicked): for Location Editor opener

    • okClicked: is a boolean indicating whether the Location Editor was closed by clicking the "OK" button or the editing was canceled ("cancel" button).
    • Is called after the editor is closed.

Back to top