REST API for Unified Assurance Core

Create a Topology Tool

post

/api/topology/Tools

Creates a new topology tool.
The minimum required properties in the request body are:

ToolName
ToolTypeID
ToolPath
ToolPathTypeID
ToolTarget
Width
Height

You can use the following three properties to specify the context the tool is available in:

ContextElement
ContextEdgeType
ContextVertexType

If you do not specify any, the tool is available in all topology graph contexts. If any of the properties are set, the tool applies only to the specified context.
The most inclusive selection applies. This means that if you set ContextElement to Edge, the tool is available for all edges, regardless of what you set in ContextEdgeType.

Request

There are no request parameters for this operation.

Supported Media Types

application/json

Root Schema : schema

Type: object

Show Source

ContextEdgeType: string

The edge type that the tool is available for. When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.

Example: ConnectsInterface
ContextElement: string
The graph elements that the tool is available for.
Allowed values are:
- Edge
- Vertex
When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context. The setting in ContextElement overrides any more specific settings in the other two context properties. This means that if ContextElement is set to Edge, the tool is available for all edges, regardless of what is set in ContextEdgeType.
Example: Edge
ContextVertexType: string

The vertex type that the tool is available for. When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.

Example: Device
Height: integer

Used when toolTarget is set to window. The height of the pop-up window. Any value between 10 and 90 is treated as a percentage of the overall browser height. Any value greater than 100 is treated as an absolute pixel value.

Example: 80
Icon: string

The icon used for the tool in menus.

Example: fugue/heart--exclamation.png
ToolName: string

The topology tool name.
To avoid confusion with numeric IDs, the name value cannot be integers only or integers prefixed with the + or - symbols only. It must contain letters or other characters. For example, 1234, +1234, and -1234 are not valid, but US1234, US+1234 and US_1234 are.

Example: Device Overview
ToolPath: string
The path to the web page to open, or script or function to run, depending on the value of Path Type.
If the value starts with a string and ://, such as https://, this is an absolute path. Otherwise, the path is relative to the $A1BASEDIR/www/tools/topology/ directory.
You can use tokens in the path in the format <Property> to represent object properties. When the tool is run, tokens are replaced with actual values. For example, <DeviceID> is replaced with the value from the object's DeviceID property. Common tokens include:
- <DeviceID>
- <ObjectID>
- <OwnerUserID>
- <OwnerUserGroupID>
Example: dashboard/Device%20Overview?DeviceName=<DeviceName>&FilterType=DeviceName&FilterValue=<DeviceName>&DeviceZoneID=<DeviceZoneID>
ToolPathTypeID: integer
The ID of the tool path type.
Possible values are:
- 1: Local
- 2: Internal
- 3: Hybrid
- 4: Remote
- 5: Function
Example: 2
ToolTarget: string
How the tool opens new pages.
Possible values are:
- window: Opens in a pop-up window.
- currenttab: Opens in the current browser tab.
- newtab: Opens in a new browser tab.
Example: window
ToolTypeID: integer

The ID of the tool type. For topology tools, this is always 1 for the View type.

Example: 1
Width: integer

Used when toolTarget is set to window. The width of the pop-up window. Any value between 10 and 90 is treated as a percentage of the overall browser width. Any value greater than 100 is treated as an absolute pixel value.

Example: 80

{
    "properties":{
        "ContextElement":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ContextElement"
        },
        "ContextEdgeType":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ContextEdgeType"
        },
        "ContextVertexType":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ContextVertexType"
        },
        "ToolName":{
            "description":"The topology tool name.\n<br>To avoid confusion with numeric IDs, the name value cannot be integers only or integers prefixed with the + or - symbols only. It must contain letters or other characters. For example, <b>1234</b>, <b>+1234</b>, and <b>-1234</b> are not valid, but <b>US1234</b>, <b>US+1234</b> and <b>US_1234</b> are.",
            "type":"string",
            "example":"Device Overview"
        },
        "Icon":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/Icon"
        },
        "ToolPath":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ToolPath"
        },
        "ToolPathTypeID":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ToolPathTypeID"
        },
        "ToolTarget":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ToolTarget"
        },
        "Width":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/Width"
        },
        "Height":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/Height"
        },
        "ToolTypeID":{
            "$ref":"#/components/schemas/topologyToolsRead/properties/ToolTypeID"
        }
    },
    "type":"object"
}

Response

Supported Media Types

application/json

200 Response

Successful operation

Root Schema : schema

Match All

Show Source

object SuccessfulAddOperation

The response body for a successful add operation.
object type

{
    "allOf":[
        {
            "$ref":"#/components/schemas/SuccessfulAddOperation"
        },
        {
            "type":"object",
            "properties":{
                "total":{
                    "description":"The total number of results regardless of paging.",
                    "type":"integer",
                    "example":"1"
                },
                "data":{
                    "type":"array",
                    "items":{
                        "$ref":"#/components/schemas/topologyToolsRead"
                    }
                }
            }
        }
    ]
}

Nested Schema : SuccessfulAddOperation

Type: object

The response body for a successful add operation.

Show Source

message: string

The response message.

Example: Added record
success: boolean

Whether the operation was a success (true) or a failure (false).

Example: true

{
    "description":"The response body for a successful add operation.",
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"true"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Added record"
        }
    },
    "type":"object"
}

Nested Schema : type

Type: object

Show Source

data: array data
total: integer

The total number of results regardless of paging.

Example: 1

{
    "type":"object",
    "properties":{
        "total":{
            "description":"The total number of results regardless of paging.",
            "type":"integer",
            "example":"1"
        },
        "data":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/topologyToolsRead"
            }
        }
    }
}

Nested Schema : data

Type: array

Show Source

Array of: object topologyToolsRead

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/topologyToolsRead"
    }
}

Nested Schema : topologyToolsRead

Type: object

Show Source

ContextEdgeType: string

The edge type that the tool is available for. When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.

Example: ConnectsInterface
ContextElement: string
The graph elements that the tool is available for.
Allowed values are:
- Edge
- Vertex
When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context. The setting in ContextElement overrides any more specific settings in the other two context properties. This means that if ContextElement is set to Edge, the tool is available for all edges, regardless of what is set in ContextEdgeType.
Example: Edge
ContextVertexType: string

The vertex type that the tool is available for. When ContextElement, ContextEdgeType, and ContextVertexType are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.

Example: Device
Height: integer

Used when toolTarget is set to window. The height of the pop-up window. Any value between 10 and 90 is treated as a percentage of the overall browser height. Any value greater than 100 is treated as an absolute pixel value.

Example: 80
Icon: string

The icon used for the tool in menus.

Example: fugue/heart--exclamation.png
ObjectTypeID: integer

The object type ID for the tool.

Example: 1
ToolID: integer

The tool ID.

Example: 1
ToolName: string

The name of the tool.

Example: Device Overview
ToolPath: string
The path to the web page to open, or script or function to run, depending on the value of Path Type.
If the value starts with a string and ://, such as https://, this is an absolute path. Otherwise, the path is relative to the $A1BASEDIR/www/tools/topology/ directory.
You can use tokens in the path in the format <Property> to represent object properties. When the tool is run, tokens are replaced with actual values. For example, <DeviceID> is replaced with the value from the object's DeviceID property. Common tokens include:
- <DeviceID>
- <ObjectID>
- <OwnerUserID>
- <OwnerUserGroupID>
Example: dashboard/Device%20Overview?DeviceName=<DeviceName>&FilterType=DeviceName&FilterValue=<DeviceName>&DeviceZoneID=<DeviceZoneID>
ToolPathTypeID: integer
The ID of the tool path type.
Possible values are:
- 1: Local
- 2: Internal
- 3: Hybrid
- 4: Remote
- 5: Function
Example: 2
ToolPathTypeName: string

The name of the tool path type.

Example: Internal
ToolTarget: string
How the tool opens new pages.
Possible values are:
- window: Opens in a pop-up window.
- currenttab: Opens in the current browser tab.
- newtab: Opens in a new browser tab.
Example: window
ToolTargetName: string

The name of the tool target.

Example: window
ToolTypeID: integer

The ID of the tool type. For topology tools, this is always 1 for the View type.

Example: 1
ToolTypeName: string

The name of the tool type. For topology tools, this is always View.

Example: View
Width: integer

Used when toolTarget is set to window. The width of the pop-up window. Any value between 10 and 90 is treated as a percentage of the overall browser width. Any value greater than 100 is treated as an absolute pixel value.

Example: 80

{
    "properties":{
        "ContextElement":{
            "description":"The graph elements that the tool is available for.<br>Allowed values are&colon;\n<ul><li>Edge</li><li>Vertex</li></ul>\nWhen <b>ContextElement</b>, <b>ContextEdgeType</b>, and <b>ContextVertexType</b> are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context. The setting in <b>ContextElement</b> overrides any more specific settings in the other two context properties. This means that if <b>ContextElement</b> is set to <b>Edge</b>, the tool is available for all edges, regardless of what is set in <b>ContextEdgeType</b>.",
            "type":"string",
            "example":"Edge"
        },
        "ContextEdgeType":{
            "description":"The edge type that the tool is available for.\nWhen <b>ContextElement</b>, <b>ContextEdgeType</b>, and <b>ContextVertexType</b> are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.",
            "type":"string",
            "example":"ConnectsInterface"
        },
        "ContextVertexType":{
            "description":"The vertex type that the tool is available for.\nWhen <b>ContextElement</b>, <b>ContextEdgeType</b>, and <b>ContextVertexType</b> are all unset, the tool is available in all topology graph contexts. When any of the context properties are set, the tool is available only in the specified context.",
            "type":"string",
            "example":"Device"
        },
        "ToolID":{
            "description":"The tool ID.",
            "type":"integer",
            "example":"1"
        },
        "ToolName":{
            "description":"The name of the tool.",
            "type":"string",
            "example":"Device Overview"
        },
        "ToolTypeName":{
            "description":"The name of the tool type. For topology tools, this is always <b>View</b>.",
            "type":"string",
            "example":"View"
        },
        "Icon":{
            "description":"The icon used for the tool in menus.",
            "type":"string",
            "example":"fugue/heart--exclamation.png"
        },
        "Width":{
            "description":"Used when <b>toolTarget</b> is set to <b>window</b>. The width of the pop-up window. Any value between <b>10</b> and <b>90</b> is treated as a percentage of the overall browser width. Any value greater than <b>100</b> is treated as an absolute pixel value.",
            "type":"integer",
            "example":"80"
        },
        "Height":{
            "description":"Used when <b>toolTarget</b> is set to <b>window</b>. The height of the pop-up window. Any value between <b>10</b> and <b>90</b> is treated as a percentage of the overall browser height. Any value greater than <b>100</b> is treated as an absolute pixel value.",
            "type":"integer",
            "example":"80"
        },
        "ToolTypeID":{
            "description":"The ID of the tool type. For topology tools, this is always <b>1</b> for the <b>View</b> type.",
            "type":"integer",
            "example":"1"
        },
        "ToolPath":{
            "description":"The path to the web page to open, or script or function to run, depending on the value of <b>Path Type</b>.<br>\nIf the value starts with a string and <b>://</b>, such as <b>https://</b>, this is an absolute path. Otherwise, the path is relative to the <b>$A1BASEDIR/www/tools/topology/</b> directory.\n<br>You can use tokens in the path in the format <b>&lt;Property></b> to represent object properties. When the tool is run, tokens are replaced with actual values. For example, <b>&lt;DeviceID></b> is replaced with the value from the object's <b>DeviceID</b> property. Common tokens include:\n<ul>\n  <li>&lt;DeviceID&gt;</li>\n  <li>&lt;ObjectID&gt;</li>\n  <li>&lt;OwnerUserID&gt;</li>\n  <li>&lt;OwnerUserGroupID&gt;</li>\n</ul>",
            "type":"string",
            "example":"dashboard/Device%20Overview?DeviceName=<DeviceName>&FilterType=DeviceName&FilterValue=<DeviceName>&DeviceZoneID=<DeviceZoneID>"
        },
        "ToolPathTypeID":{
            "description":"The ID of the tool path type. <br>Possible values are:\n<ul>\n<li><b>1</b>: Local</li>\n<li><b>2</b>: Internal</li>\n<li><b>3</b>: Hybrid</li>\n<li><b>4</b>: Remote</li>\n<li><b>5</b>: Function</li>\n</ul>",
            "type":"integer",
            "example":"2"
        },
        "ToolPathTypeName":{
            "description":"The name of the tool path type.",
            "type":"string",
            "example":"Internal"
        },
        "ToolTarget":{
            "description":"How the tool opens new pages.<br>Possible values are:\n<ul>\n<li><b>window</b>: Opens in a pop-up window.</li>\n<li><b>currenttab</b>: Opens in the current browser tab.</li>\n<li><b>newtab</b>: Opens in a new browser tab.</li>\n</ul>",
            "type":"string",
            "example":"window"
        },
        "ToolTargetName":{
            "description":"The name of the tool target.",
            "type":"string",
            "example":"window"
        },
        "ObjectTypeID":{
            "description":"The object type ID for the tool.",
            "type":"integer",
            "example":"1"
        }
    },
    "type":"object"
}

Default Response

Failed operation

Root Schema : schema

Type: object

Show Source

errors: array errors

The list of errors reported. Validation errors will be keyed by record field.
message: string

The response message.

Example: Exception thrown
success: boolean

Whether the operation was a success (true) or a failure (false).

Example: false

{
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"false"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Exception thrown"
        },
        "errors":{
            "description":"The list of errors reported. Validation errors will be keyed by record field.",
            "type":"array",
            "items":{
                "description":"An error.",
                "type":"object"
            }
        }
    },
    "type":"object"
}

Nested Schema : errors

Type: array

The list of errors reported. Validation errors will be keyed by record field.

Show Source

Array of: object items

An error.

{
    "description":"The list of errors reported. Validation errors will be keyed by record field.",
    "type":"array",
    "items":{
        "description":"An error.",
        "type":"object"
    }
}

Nested Schema : items

Type: object

An error.