itk-demo-dashboard¶

ITk demonstrator GUI Dashboard to show the status of all services.

Normally service information is read automatically from etcd, but it can also be provided manually.

Include Service data file¶

External files are read from ${DOCKER_DIR}/extraFiles. All files that should be included must be specified in a config.json file in the directory. The config.json must contain an array named "include". All File names specified in "include" will be read in the Dashboard.

e.g. The ui/extraFilesfolder contains three files: ´´´ config.json
test6.json
test.json ´´´ test.json, test6.json are Service data files. The config.json only specifies one file:

JSON

{
    "include": ["test.json"]
}

The Dashboard will show all services specified in test.json. The test.6.json, will not be displayed.

Service data file¶

Services must be provided in a json file containing an array (named 'cards') consisting of the services. The Dashboard will display each service in a card.

Each service should be an object with the following structure (required keys marked with *):

{\ type*: string - the category in which the service is sorted.\ name*: string - name of the service.\ icon: string - path or url to an icon for the service.\ description: string - a short description of the service.\ protocol = 'http': string - protocoll of the communication used to construct the url to the service\ host: string - hostname used to construct the url to the service. If no hostname is given, the url on which the dashboard runs will be used.\ hostport: string - the port on which the service runs.\ apiPrefix = '': string - url extension to the backend ui.\ health: string - health endpoint of the service. If provided regular requests will be made to monitor the status of the service. Requires 'hostport' to function.\ url: string - url to the gui of the service.\ }

### Example

{\ "cards": [\ {\ "type": "Microservices",\ "name": "itk-demo-configdb",\ "description": "configdb backend",\ "protocol": "http",\ "host": "localhost",\ "hostport": 5000,\ "url_prefix": "/api",\ "health": "/health",\ "icon": "https://example.org/picture.png",\ "url": "http://localhost:5000/api/ui"\ },\ {\ "type": "Microservice-UI",\ "name": "itk-demo-configdb-ui",\ "description": "configdb ui",\ "host": "localhost",\ "hostport": 3000,\ "icon": "https://example.org/picture.png",\ "url": "http://localhost:3000"\ }\ ]\ }

Configuration topology view¶

The topology view can be configured with different files.

topologyConfig/treeConfig.json¶

The file describes the style of the topology. It provides a per type configuration for the shown nodes. Available styles are: - shape: "ellipse" | "rect" | "rhombus" | "trapezoid" | "hexagon" | "octagon" | "stadium". - width: number - height: number, - labelSuffix: string | undefined - Specifies a field to look up in the metadata of the object, that is used as a suffix of the label. If it is not set a unique id will be generated. - label: boolean - If true a label will be generated in the form '[type] [suffix]' and shown under the node. If false a uniquely generated id in the form '[type] [number]' will be used in place of the label, but not shown under the node. - icon: "Icon1" | "Icon2" | null, - defaultStatus: "default" | "info" | "warning" | "danger" - By default every component whose status can not be determined will be set to "danger". This property allows to set the default value to something else. This is usefull for components who don't have a microservice, to manage their stauts. The recommended value in this case is "default". - chainChildren: boolean - If true the children of the component are displayed in series instead of being faned out on the same level. Should only be at the end of the graph.

A 'default' type must be provided as a base type. Every other types config will be merged with the 'default' one. So only unique styles must be configured for each type. Additionally a type can just point to another one instead of defining its own config. For a example see './example/docker/topologyConfig/treeConfig.json'.

topologyConfig/services.json¶

The files describes additional Microservices, that should be displayed in the topology independent of the connectivity. Their styles are described in the 'topologyConfig/treeConfig.json' as the 'services' type. The file contains a keyPrefix field, that describes a common prefix between all keys in the service registry and a services field, that contains a array of all services to be included. A service consist of: - name: string - Is used as the label of the node - status: string - Prefix of the keys in the service registry neccessary to find the health endpoint of the microservice e.g. 'itk-demo-configdb/api' will locate the health endpoint as 'itk-demo-configdb/api/url' + 'itk-demo-configdb/api/health' - uis: array - Each entry is a object, that specifies a link to be included in the sidebar, that is shown when selecting the service. The objects consist of: - urlKey: string - The base url to link to will be requested from the service registry as 'keyPrefix' + 'urlKey'. - postfix: string - Postfix to append to the base url - label: string - label to describe the link in the sidebar

For a example see './example/docker/topologyConfig/services.json'.

sidebarContent/¶

The location of the sidebar content for each node will be requested from the service registry under 'demi/dashboard/files/[label of the node]'. This directory provides a convenient place to place static files. A file describing the sidebarContent of a node must contain: - content: string - A string to display at the end of the sidebar content - buttons: array - Each entry will generate a button at the top of the sidebar content, that allows the execution of a HTTP request. A button is described by the following fields: - label: string - endpoint: string - url to call, when the button is pressed - body: object | null - body of the request. If null a GET request will be made. If body is an object it will be used as the body for a POST request to endpoint

For a example see './example/docker/sidebarContent/felixDevice1.json'. To see this example in action the service registry must contain 'demi/dashboard/files/felixDevice 1': 'sidebarContent/felixDevice1.json'.

Use multiple service registries¶

The Dashboard has the ability to read from multiple service registries. For that the aditional registries will be located in the primary registry. The Dashboard will request all keys starting with 'demi/sr' from the primary registry. The value should be url to the additional registry. Example:

Text Only

{
  "key": "demi/sr/secondary",
  "value": "http://secondaryHost:5111/api"
}

Status of hardware components¶

The status of the hardware components gets requested from the service registry under 'demi/dashboard/status/[serial]'. 'default' should be used if everything is fine. 'info'/'warning'/'danger'/'success' highlights the component in blue/yellow/red/green.