BW6.X - How to use the Hawk 6.X REST API in a BusinessWorks context - TIBCO ActiveMatrix BusinessWorks

An interesting feature introduced by Hawk 6.X is the capability to invoke available Hawk methods using a generic REST API.

In a BusinessWorks context this allows to easily collect KPI’s available in Hawk and integrate them into custom dashboards or reports.

Note that you need to have a valid Hawk licence to be able to use the Hawk component exposing the REST API in both BusinessWorks 6.X and BusinessWorks 5.X environments.

For BusinessWorks 5.X you have to use BusinessWorks 5.15 or higher while previous releases are not using the Hawk 6.X version.

This new article explains how to use the Hawk REST API to invoke methods exposed by both the BusinessWorks 6.X and BusinessWorks 5.X microagents.

Architecture

The Hawk REST API is exposed by a new component introduced in Hawk 6.X that is the Hawk Console.

To be able to use the Hawk REST API an instance of this component should be running on one of the server of the configuration.

When a method of the Hawk REST API is called the Hawk Console forward the call to the target Hawk Agent that itself send it to the target micro-agent, once the micro-agent replies the Hawk Agent forward the reply to the Hawk Console that finally put it in a generic JSON format and returns it to the caller.

Prerequisites to use the Hawk REST API

You need to make sure there is an Hawk Console running in your target environment and you have the following elements:

. The hostname and port to use to access the Hawk Console

. A username and password allowing to connect to the Hawk Console

By default the Hawk Console is available on the following URL:

http://<host>:8083/HawkConsole

For example:

http://server1:8083/HawkConsole

By default you can connect with the usual admin/admin.

The Hawk Console should also be configured to access the target Hawk domain.

If needed this can be done with the following:

. Click the “+’ button on the right of the page (in the middle)

. Enter the details for your target domain

All details of the target Hawk domain have to be entered, you may need to scroll to see all parameters.

. Click ‘Configure’ once all details have been entered.

Checking the Hawk REST API

The Hawk Console is managing a page in Swagger UI format where can be found the list of available Hawk REST API methods and details on the methods. It also possible to test the methods on line.

By default this page is available on the following URL:

http://<host>:8083/HawkConsole/v1/docs

For example: http://server1:8083/HawkConsole/v1/docs

The available REST methods are available in Swagger UI format:

Calling the Hawk REST API — Getting needed details on the target domain

This is generally useful to call the GET {domain}/agent API to get details about the target domain.

This can be done from the Swagger UI page:
. First select the GET /{domain}/agent method

. Enter the name of the target domain (‘default’ in the example below)

. Click ‘Try it Out’

Enter the username / password that you have to connect to the HawkConsole.

. Check the output

In the output we can see the value of the ‘dns’ parameter that is useful to do further calls.

Calling the Hawk REST API — Listing available micro-agents for a given Hawk Agent

. This can be done with the following method GET /{domain}/{dns}/{agent}/Microagent

We have to use the domain, dns and agent name we got from the previous call.

. Click ‘Try it Out’

. Check the target appnode Hawk micro-agent is present in the output

For example:

In the screen shot above we can see the microagent ‘name’ and ‘nameWithInstance’.

Calling the Hawk REST API — Calling an Hawk method for a given BW 6.X Hawk micro-agent

. This can be done with the following method POST /{domain}/{dns}/{agent}/invoke

. Calling the method

We have to use the domain, dns and agent name we got from the previous call.

We also have to create a body for the call, for example to call the ‘GetApplicationDetails’ method of the BW 6.X Hawk microagent we have to create the following body (note that we have to use the microagent ‘nameWithInstance’ we got from the previous call):

{
“microagent”: “AS04-AN02-HMA:0”,
“method”: “GetApplicationDetails”,
“param”: {
}
}

. Click ‘Try it Out’

. Check the output

In a generic JSON format we have the list of deployed applications in the target appnode and details for each application including its name, version and state.

Calling the Hawk REST API — Calling an Hawk method for a given BW 5.X Hawk micro-agent

. This can be done with the following method POST /{domain}/{dns}/{agent}/invoke (as for BW 6.X)

. Calling the method

We have to use the domain, dns and agent name using the approach explained earlier.

We also have to create a body for the call, for example to call the ‘GetExecInfo’ method of the BW 5.X Hawk microagent we have to create the following body (note that we have to use the microagent ‘nameWithInstance’ we got using the approach explained earlier):

{
“microagent”: “ COM.TIBCO.ADAPTER.bwengine.bw514.HelloWorld.HelloWorld:0”,
“method”: “GetExecInfo”,
“param”: {
}
}