Rendering static topologies via UI-API

You can use the UI-API to render a static topology view via cURL command, which you then download as an image. You use the resourceId parameter to seed the topology, and then define a number of additional parameters to generate a static server-side topology image.

To define a cURL string that renders a topology via the UI-API, you must know the URL for your core host, the resource ID for your seed resource, as well as the Agile Service Manager basic access authentication credentials.

The Agile Service Manager UI-API is available on the following endpoints:
https://<ASM CORE HOST>/1.0/ui-api/render/svg
https://<ASM CORE HOST>/1.0/ui-api/render/png

You construct your cURL command as described in this procedure, then use it to download a static topology view as an image (either PNG or SVG).

In addition to the resourceId parameter, you use a Basic authentication header when calling the UI-API. This lets you call the API without having to log into the Agile Service Manager UI first.
PNG example
curl -X GET "https://asm.example.host.com/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
SVG example
curl -X GET "https://asm.example.host.com/1.0/ui-api/render/svg?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/svg+xml" -H "authorization: Basic YXNtOmFzbQ=="
Where:
  • The Agile Service Manager core host is asm.example.host.com
  • The resourceId that identifies the seed resource is sl1RQ5NCR_ykgciQCTkFGA
  • The output format is specified by either png or svg
  • The authorization method is specified as Basic
  • The encrypted user credentials (username and password) are YXNtOmFzbQ==
Tips:
  • You can use the width and height URL parameters (exclusively for use with the UI-API) to set the size of the image produced; the default size is 1000 x 700.
  • The hideToolbar and hideSearch parameters are not available when constructing an UI-API call. Parameters are listed here.
  • You can include advanced resource or relationship filters in your URL by specifying 'type'. Topology filtering is described here.
  • You can change the label length for your resource types, should the default label legibility be less than optimal in your topology image. Resource labels are described here.
  1. Obtain your resource ID, authentication credentials, and core Agile Service Manager host URL.
  2. Define a cURL call by editing the parameters, as shown in the following examples.
    Specify a seed resource by ID
    The following cURL call example renders a simple Agile Service Manager topology view with a host URL of asm.example.host.com and a port number of 3080. The view is based on the resourceId parameter with the value of sl1RQ5NCR_ykgciQCTkFGA. It returns a png image, and performs Basic access authentication using the encrypted Agile Service Manager username and password credentials (YXNtOmFzbQ==).
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify the hop numbers and types
    The image returned by this cURL call has the same seed resource as before, but now with the number of hops set at 3, and a hopType of host. The hopType parameter is only required if you wish to use the host-to-host hop type (element-to-element is the default).
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&hopType=host" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify focus areas for large topologies
    The image returned by this cURL call has the same seed resource as before (now with a hop count of three), but now zooms in on the area specified by the focusId parameter, thereby preventing very large topologies from being displayed with potentially too much information on view. 
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&focusId=<resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify additional resources to be highlighted
    The image returned by this cURL call has the same seed resource as before with a hop count of three, but now uses the selectedIds parameter to specify additional non-seed resources (via their IDs) to highlight when the image is rendered.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&selectedIds=<resource_id> <resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify 'get neighbor' expansion
    The image returned by this cURL now includes a neighbourRequests parameter that gathers a number of additional neighboring resources for display, each identified by its resource ID.
    The neighbourRequests parameter expects an array of space-separated id strings.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&neighbourRequests=<resource_id> <resource_id>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify advanced resource filters
    The image returned now includes a resourceFilter parameter that filters out all resources of a specified type.
    The resourceFilter parameter expects an array of space-separated, previously defined resource types.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&resourceFilter=<Type1> <Type2>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify advanced relationship filters
    The image returned includes the relation filter parameter (relationFilter) to filter out all rlationships of a specified type.
    The relationFilter parameter expects an array of space-separated, previously defined resource types.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&relationFilter=<Type1> <Type2>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify time point
    The image returned reflects the state of the topology at a specific point in history (in unixtime).
    The time parameter expects the time entered in unixtime.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&time=<unixTimeMilliseconds>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
    Specify delta history mode
    The image returned shows the topology in delta history mode, with the specified time as a reference point and the deltaTime parameter as the point to delta against.
    curl -X GET "https://asm.example.host.com:3080/1.0/ui-api/render/png?resourceId=sl1RQ5NCR_ykgciQCTkFGA&hops=3&time=<unixTimeMilliseconds>&deltaTime=<unixTimeMilliseconds>" -H "accept: image/png" -H "authorization: Basic YXNtOmFzbQ=="
Having created topology images, you can save them for quick access to specific views, or share them with others to provide them with specific, instant information.