Managing Links

You can manage links in Oracle Communications Unified Assurance Vision using the REST API.

Links are markers on the Vision map that represent physical connections between an interface on one entity and another interface on the same entity or a different entity. They contain information about the start and end device, interface, and entity, as well as carrier, circuit, and bandwidth information.

You can use the REST API for the following tasks:

Creating links:
- Creating a Single Link: Create links one at a time, as JSON objects in a POST request body.
- Creating Links in Bulk from JSON: Create links in bulk, as an array of JSON objects in a POST request body.
- Creating Links in Bulk from CSV: Create links in bulk, from a binary string representing a CSV file.
Updating links:
- Updating Links Completely: Replace the entire link definition.
- Updating Link Fields: Updating only certain link fields.
Finding Links: Get existing links for a variety of purposes, including to use in dashboards and for event streaming.
Deleting Links
Managing Links on Dashboards

This use case provides example API calls for managing links. The examples use cURL commands, but you can use any REST API client of your choice.

Prerequisites

The examples in this document assume the following:

You have installed Unified Assurance and Vision. See Vision Installation Overview in Unified Assurance Installation Guide.
You have created entities in Vision and linked them to Unified Assurance devices. See the following for full details about the endpoints:
You can also create entities for discovered devices with geolocations using the Create Vision Data application. See CreateVisionData in Unified Assurance Implementation Guide.
You include the required certificate information in your request headers. See Authenticate and Authorization Header.

Identifying Valid Devices, Interfaces, and Entities

When you create links, you must use devices, interfaces, and entities that have been added to Vision. You can identify them by submitting GET requests to the following endpoints:

To get a list of devices that you can use as link starting and ending points, submit the following GET request:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/entities/findDeviceIds/1
```
In this request, 1 is the source ID, representing the Assure1 database. This is the only supported source.

The response body contains an array of Unified Assurance devices that are associated with Vision entities. The following example omits the columns and links for simplicity:
```
{
  "columns": [
    ...
  ],
  "content": [
    {
      "deviceId": 1,
      "entityName": "Entity 123",
      "zoneId": 1
    },
    {
      "deviceId": 2,
      "entityName": "Entity 456",
      "zoneId": 1
    },
  ],
  "links": [
    ...
  ]
}
```
See Get Entities with Device IDs for full details about this endpoint.

To get a list of interfaces for a device, submit the following GET request, where <deviceID> is the relevant device ID:

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/deviceInterfaces?deviceId=<deviceID>

The response body contains an array of interfaces. The following example omits the columns and links for simplicity:

{
  "columns": [
    ...
  ],
  "content": [
    {
       "ifAlias": "Interface123",
       "ifDescription": "Interface 123",
       "ifName": "interface123"
    },
    {
       "ifAlias": "Interface456",
       "ifDescription": "Interface 456",
       "ifName": "interface456"
    }
  ],
  "links": [
    ...
  ]
}

See Get Interfaces for a Device for full details about this endpoint.

To get a list of Vision entities that you can use as link starting and ending points, submit the following GET request:

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/entities/usedInDashboards

The response body contains an array of Vision entities that have the useInDashboard property set to true. The following example omits the columns and links for simplicity:

{
  "columns": [
    ...
  ],
  "content": [
    {
       "id": "381",
       "name": "Entity123"
       "displayName": "Entity123;z1",
       "zoneId": "1"
    },
    {
       "id": "985",
       "name": "Entity653"
       "displayName": "Entity653;z1",
       "zoneId": "1"
    }
  ],
  "links": [
    ...
  ]
}

Creating a Single Link

For each link you create, you must have the following information:

The carrier ID and name
The bandwidth
The starting device, interface, and entity
The ending device, interface, and entity

To create a single link:

Using valid devices, interfaces, and entities identified as described in Identifying Valid Devices, Interfaces, and Entities, create a JSON document called createlink.json to contain the link definition. For example:
```
{
  "carrier": "MyCarrier",
  "cid": "12345",
  "endDeviceId": 1,
  "endEntityId": 11,
  "endPort": "interface111",
  "endSourceId": 1,
  "mbps": 1000,
  "startDeviceId": 2,
  "startEntityId": 22,
  "startPort": "interface222",
  "startSourceId": 1
}
```
Note:

This example contains only the minimum parameters. You can optionally specify other parameters, such as a description, circuit, and metadata, and some parameters are automatically populated when you submit the request. See the Create a Link endpoint description for the full list of parameters.

Send a POST request to the linkData endpoint, passing createlink.json as the request body by specifying it in the -d option.

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @createlink.json https://<hostFQDN>:9443/vision/api/linkData

See Create a Link for full details about this endpoint.

The API response body contains the specified definition, along with auto-populated fields, such as id. The following example omits the columns and links for simplicity:

{
    "content": [
        {
            "id": 1,
            "carrier": "MyCarrier",
            "cid": "12345",
            "startSourceId": 1,
            "startEntityId": 22,
            "startDeviceId": 2,
            "endSourceId": 1,
            "endEntityId": 11,
            "endDeviceId": 1,
            "startSourceName": "Assure1",
            "endSourceName": "Assure1",
            "startEntityName": "entity22",
            "endEntityName": "entity11",
            "startDeviceName": "server2",
            "endDeviceName": "server1",
            "ckt": "",
            "mbps": 1000,
            "startPort": "interface222",
            "startPortFacingCkt": "",
            "endPort": "interface111",
            "endPortFacingCkt": "",
            "startMetaData": {},
            "endMetaData": {}
        }
    ],
    "links": [
        ...
    ],
    "columns": [
        ...
    ]
}

Creating Links in Bulk from JSON

Create a JSON document called createbulklinks.json to contain the array of link definitions using valid devices, interfaces, and entities:

[
  {
    "carrier": "MyCarrier",
    "cid": "56332",
    "endDeviceId": 3,
    "endEntityId": 33,
    "endPort": "interface33",
    "endSourceId": 1,
    "mbps": 1000,
    "startDeviceId": 4,
    "startEntityId": 44,
    "startPort": "interface44",
    "startSourceId": 1
  },
 {
    "carrier": "MyCarrier",
    "cid": "54321",
    "endDeviceId": 5,
    "endEntityId": 55,
    "endPort": "interface55",
    "endSourceId": 1,
    "mbps": 1000,
    "startDeviceId": 6,
    "startEntityId": 66,
    "startPort": "interface66",
    "startSourceId": 1  
  }
]

Send a POST request to the linkData/import endpoint, passing createbulklinks.json as the request body by specifying it in the -d option.

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @createbulklinks.json https://<hostFQDN>:9443/vision/api/linkData/import

See Create Multiple Links for full details about this endpoint.

The API returns a 200 response code and success message.

Creating Links in Bulk from CSV

Create a CSV file containing the required link information.
Convert the CSV to a binary string and save it as createbulklinks.bin.

Send a POST request to the linkData/importCsv endpoint, passing the binary string -F option.

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -F @createbulklinks.bin https://<hostFQDN>:9443/vision/api/linkData/import

See Create Multiple Links from a CSV File for full details about this endpoint.

The API returns a 200 response code and success message.

Updating Links Completely

You send PUT requests to update links completely. Because the PUT request replaces the entire resource, any fields that were previously specified for the link but not specified in the PUT request are replaced with empty values.

For example, to change a number of fields for a link:

Create a JSON document called UpdateLinkCompletely.json to contain the new definition. This example adds the circuit IDs for the link and interfaces. Even though most of the required properties, such start and end IDs, are the same as what already exists for the link, you must include them in the PUT request. Not including them would replace the values with empty strings, which would fail validation.
```
{
  "carrier": "MyCarrier",
  "cid": "12345",
  "ckt": "ABC12/ABC/ABCDEFG/ABCDEFGH",
  "endDeviceId": 1,
  "endEntityId": 11,
  "endPort": "interface111",
  "endSourceId": 1,
  "mbps": 1000,
  "startDeviceId": 2,
  "startEntityId": 22,
  "startPort": "interface222",
  "startSourceId": 1
  "startPortFacingCkt": "XYZ13/ZYZ/ZYXK/XYXZYYS"
  }
}
```
Send a PATCH request to the linkData/{id} endpoint, specifying the ID of the link you want to update in the path and passing UpdateLinkCompletely.json as the request body by specifying it in the -d option. For example, to update the link with ID 1:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X PUT -d @UpdateLinkCompletely.json https://<hostFQDN>:9443/vision/api/linkData/1
```
See Update a Link for full details about this endpoint.

The API response body contains the entire link definition. The following example omits the columns and links for simplicity:

{
    "content": [
{
            "id": 1,
            "carrier": "MyCarrier",
            "cid": "12345",
            "startSourceId": 1,
            "startEntityId": 22,
            "startDeviceId": 2,
            "endSourceId": 1,
            "endEntityId": 11,
            "endDeviceId": 1,
            "startSourceName": "Assure1",
            "endSourceName": "Assure1",
            "startEntityName": "entity22",
            "endEntityName": "entity11",
            "startDeviceName": "server2",
            "endDeviceName": "server1",
            "ckt": "ABC12/ABC/ABCDEFG/ABCDEFGH",
            "mbps": 1000,
            "startPort": "interface222",
            "startPortFacingCkt": "",
            "endPort": "interface111",
            "endPortFacingCkt": "XYZ13/ZYZ/ZYXK/XYXZYYS",
            "startMetaData": {},
            "endMetaData": {}
        }
    ],
    "links": [
        ...
    ],
    "columns": [
        ...
    ]
}

Updating Link Fields

You send PATCH requests to update only specified fields for a link. For example, to change the circuits for the link but leave everything else the same:

Create a JSON document called updatelinkfields.json to contain the fields to update:
```
{
  "ckt": "NEW12/ABC/ABCDEFG/ABCDEFGH",
  "startPortFacingCkt": "NEW13/ZYZ/ZYXK/XYXZYYS"
}
```
Send a PATCH request to the linkData/{id} endpoint, specifying the ID of the link you want to delete in the path and passing UpdateLinkFields.json as the request body by specifying it in the -d option. For example, to update the link with ID 1:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X PATCH -d @UpdateLinkFields.json https://<hostFQDN>:9443/vision/api/linkData/1
```
See Update Fields for a Link for full details about this endpoint.

The API response body contains the entire link definition. The following example omits the columns and links for simplicity:

{
    "content": [
        {
            "id": 1,
            "carrier": "MyCarrier",
            "cid": "12345",
            "startSourceId": 1,
            "startEntityId": 22,
            "startDeviceId": 2,
            "endSourceId": 1,
            "endEntityId": 88,
            "endDeviceId": 8,
            "startSourceName": "Assure1",
            "endSourceName": "Assure1",
            "startEntityName": "entity22",
            "endEntityName": "entity88",
            "startDeviceName": "server2",
            "endDeviceName": "server8",
            "ckt": "NEW12/ABC/ABCDEFG/ABCDEFGH",
            "mbps": 1000,
            "startPort": "interface222",
            "startPortFacingCkt": "NEW13/ZYZ/ZYXK/XYXZYYS",
            "endPort": "interface888",
            "endPortFacingCkt": "",
            "startMetaData": {},
            "endMetaData": {}
        }
    ],
    "links": [
        ...
    ],
    "columns": [
        ...
    ]
}

Finding Links

You can find links by sending GET requests to a variety of endpoints, depending on what you need the link for. You can use different endpoints to get:

A single link, all links, or all links for a specific dashboard
Responses that include geographical coordinates of start and end points for geographical dashboards, logical pixel x/y image coordinates of start and end points for logical dashboards, and event severity, and responses to be used in event streaming. These different response types are typically used when displaying links on the map.

You use either the link ID or a dashboard ID in the path of the request, depending on your need. The following table shows some examples. For information about all of the endpoints, see the Links REST Endpoints descriptions.

Use Case	Documentation	Example Request
Get all links in the system.	Get Links	`curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/linkData`
Get the link with ID 1, and include the geographical coordinates for its start and end points in the response.	Get a Link by ID and Show Geographical Location	`curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/linkData/withLocationInfo/1`
Get all of the links for the dashboard with ID 9, to be used for event streaming, and include the logical coordinates for its start and end points, and event severity.	Get Links by Dashboard ID for Event Streaming and Show Pixel Location and Severity	`curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/linkData/withPixelAndSeverityInfo/9/forEventStreaming`
Get all links that have been added to geographical dashboards.	Get Geographical Dashboard Links	`curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/dashboardsLinkData`

Deleting Links

To delete a link, send a DELETE request to the linkData/{id} endpoint, specifying the ID of the link you want to delete in the path. For example, to delete the link with ID 1:

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X DELETE https://<hostFQDN>:9443/vision/api/linkData/1

When the link is deleted successfully, the API returns a 204 response with no content.

See Delete a Link for full details about this endpoint.

You can confirm that the link no longer exists by attempting to retrieve it:

curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X GET https://<hostFQDN>:9443/vision/api/linkData/1

If the link does not exist, the API returns a 404 response.

Managing Links on Dashboards

In order for markers for links to appear on the Vision map, you must add them to dashboards. You use different endpoints, depending on whether you are adding links to geographical or logical dashboards.

To manage links on geographical dashboards:

Add a single link:
1. Create a JSON document called AddLinktoDashboard.json to contain the dashboard to add the link to, and the link to add:
```
{
  "dashboardId": 1,
  "linkDataId": 123
}
```
2. Send a POST request to the dashboardsLinkData endpoint, passing AddLinktoDashboard.json as the request body by specifying it in the -d option. For example:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @AddLinktoDashboard.json https://<hostFQDN>:9443/vision/api/dashboardsLinkData
```
  See Add a Link to a Geographical Dashboard for full details about this endpoint.
The API response body contains the dashboard and link IDs. The following example omits the columns and links for simplicity:
```
{
    "content": [
        {
            "dashboardId": 1,
            "linkDataId": 123
        }
    ],
    "links": [
        ...
    ],
    "columns": [
        ...
    ]
}
```
Add multiple links:
1. Create a JSON document called AddMultipleLinkstoDashboards.json to contain the dashboards and links to add to them:
```
[
  {
    "dashboardId": 1,
    "linkDataId": 123
  },
  {
    "dashboardId": 12,
    "linkDataId": 42
  }
}
```
  This example shows adding different links to different dashboards, but you could add the same link to multiple dashboards, or different links to the same dashboard.
2. Send a POST request to the dashboardsLinkData/import endpoint, passing AddMultipleLinkstoDashboards.json as the request body by specifying it in the -d option. For example:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @AddMultipleLinkstoDashboards.json https://<hostFQDN>:9443/vision/api/dashboardsLinkData/import
```
  See Add Multiple Links to Geographical Dashboards for full details about this endpoint.
The API response body contains an overall status:
```
{
  "csrfToken": "12345",
  "message": "The dashboard links were added successfully.",
  "reason": "OK",
  "status": 200
}
```
Remove a single link from a dashboard by specifying the dashboard ID and link to remove in the query parameters:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X DELETE https://<hostFQDN>:9443/vision/api/dashboardslinkData?dashboardId=1&linkDataId=123
```
When the link is removed successfully, the API returns a 204 response with no content.
Remove all links from a dashboard by specifying the dashboard ID in the path parameter:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X DELETE https://<hostFQDN>:9443/vision/api/dashboardslinkData/1
```
When the link is removed successfully, the API returns a 204 response with no content.

To manage links on logical dashboards:

Add a single link:
1. Create a JSON document called AddPixelLinktoDashboard.json to contain the dashboard to add the link to, the link to add, and the X and Y locations for the link starting and ending points:
```
{
  "dashboardId": 20,
  "linkDataId": 2
}
```
2. Send a POST request to the dashboardLinkPixels endpoint, passing AddPixelLinktoDashboard.json as the request body by specifying it in the -d option. For example:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @AddPixelLinktoDashboard.json https://<hostFQDN>:9443/vision/api/dashboardLinkPixels
```
  See Add a Link to a Logical Dashboard for full details about this endpoint.
The API response body contains the dashboard and link IDs and pixel locations for the starting and ending points. The following example omits the columns and links for simplicity:
```
{
    "content": [
        {
          "dashboardId": 20,
          "endX": 100,
          "endY": 250,
          "linkDataId": 2,
          "startX": 12,
          "startY": 50  
        }
    ],
    "links": [
        ...
    ],
    "columns": [
        ...
    ]
}
```
Add multiple links:
1. Create a JSON document called AddMultiplePixelLinkstoDashboards.json to contain the dashboards and links to add to them:
```
[
  {
    "dashboardId": 20,
    "linkDataId": 21
  },
  {
    "dashboardId": 10,
    "linkDataId": 33 
  }
}
```
  This example shows adding different links to different dashboards, but you could add the same link to multiple dashboards, or different links to the same dashboard.
2. Send a POST request to the dashboardLinkPixels/import endpoint, passing AddMultiplePixelLinkstoDashboards.json as the request body by specifying it in the -d option. For example:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @AddMultiplePixelLinkstoDashboards.json https://<hostFQDN>:9443/vision/api/dashboardLinkPixels/import
```
  See Add Multiple Links to Logical Dashboards for full details about this endpoint.
The API response body contains an overall status:
```
{
  "csrfToken": "16498",
  "message": "The links were added successfully.",
  "reason": "OK",
  "status": 200
}
```
Remove specified links from a dashboard: by specifying the dashboard ID in the path parameter and listing the links to remove in the body:
1. Create a JSON document called DeletePixelLinksfromDashboard.json to contain the links to remove:
```
[1,2]
```
2. Send a DELETE request to the dashboardLinkPixels/deletePixels endpoint with the dashboard ID in the path, passing DeletePixelLinksfromDashboard.json as the request body by specifying it in the -d option. For example:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X POST -d @DeletePixelLinksfromDashboard.json https://<hostFQDN>:9443/vision/api/dashboardLinkPixels/deletePixels/1
```
The API returns a 204 response with no content.

See Delete Links from a Dashboard for full details about this endpoint.
Remove all links from a dashboard by specifying the dashboard ID in the path parameter:
```
curl --cacert $A1BASEDIR/etc/ssl/BundleCA.crt --cert $A1BASEDIR/etc/ssl/User-api.crt --key $A1BASEDIR/etc/ssl/User-api.key -X DELETE https://<hostFQDN>:9443/vision/api/dashboardlinkPixels/123
```
When the link is removed successfully, the API returns a 204 response with no content.

See Delete All Links from a Logical Dashboard for full details about this endpoint.