
= Business Service Monitoring

Every aspect of the Business Service Monitoring feature can be controlled via a REST API.
The API's endpoint for managing business services is located at `/opennms/api/v2/business-services`.
It supports XML content to represent the business services.
The schema file describing the API model is located in `$\{OPENNMS_HOME}/share/xsds/business-service-dto.xsd`.
The responses generated by the REST API do also include `location` elements that contain references to other entities managed by the API.
The Business Service response data model for the ReST API has the following basic structure:

.Sample Business Service details response XML representation
[source,XML]
----
<business-service>
  <id>42</id>
  <name>Datacenter North</name>
  <attributes/>
  <ip-service-edges>
    <ip-service-edge>
      <id>23</id>
      <operational-status>WARNING</operational-status>
      <map-function>
        <type>Identity</type>
      </map-function>
      <location>/api/v2/business-services/2/edges/23</location>
      <reduction-keys>
        <reduction-key>uei.opennms.org/nodes/nodeLostService::12:10.10.10.42:ICMP</reductionKey>
        <reduction-key>uei.opennms.org/nodes/nodeDown::12</reductionKey>
      </reduction-keys>
      <weight>1</weight>
    </ip-service-edge>
  </ip-service-edges>
  <reduction-key-edges>
    <reduction-key-edge>
      <id>111</id>
      <operational-status>INDETERMINATE</operational-status>
      <map-function>
        <type>Identity</type>
      </map-function>
      <location>/api/v2/business-services/42/edges/111</location>
      <reduction-keys>
        <reduction-key>my-reduction-key1</reduction-key>
      </reduction-keys>
      <weight>1</weight>
    </reduction-key-edge>
  </reduction-key-edges>
  <child-edges>
    <child-edge>
      <id>123</id>
      <operational-status>MINOR</operational-status>
      <map-function>
        <type>Identity</type>
      </map-function>
      <location>/api/v2/business-services/42/edges/123</location>
      <reduction-keys/>
      <weight>1</weight>
      <child-id>43</child-id>
    </child-edge>
  </child-edges>
  <parent-services><parent-service>144</parent-service></parent-services>
  <reduce-function><type>HighestSeverity</type></reduce-function>
  <operational-status>INDETERMINATE</operational-status>
  <location>/api/v2/business-services/146</location>
</business-service>
----

.Sample Business Service creation request XML representation
[source,XML]
----
<business-service>
  <name>Datacenter North</name>
  <attributes/>
  <ip-service-edges>
    <ip-service-edge>
      <ip-service-id>99</ip-service-id>
      <map-function>
        <type>Identity</type>
      </map-function>
      <weight>1</weight>
    </ip-service-edge>
  </ip-service-edges>
  <reduction-key-edges>
    <reduction-key-edge>
      <reduction-key>my-reduction-key1</reduction-key>
      <map-function>
        <type>Identity</type>
      </map-function>
      <weight>1</weight>
    </reduction-key-edge>
  </reduction-key-edges>
  <child-edges>
    <child-edge>
      <child-id>43</child-id>
      <map-function>
        <type>Identity</type>
      </map-function>
      <weight>1</weight>
    </child-edge>
  </child-edges>
  <reduce-function><type>HighestSeverity</type></reduce-function>
</business-service>
----

The whole model is defined in `jetty-webapps/opennms/WEB-INF/lib/org.opennms.features.bsm.rest.api-*.jar`, which can be used as a dependency for a Java program to query the API.

== GETs (reading data)

[caption=]
.Business Service API GET functions
[options="autowidth"]
|===
| Resource  | Description

| /opennms/api/v2/business-services
| Provides a brief list of all defined business services.

| /opennms/api/v2/business-services/\{id}
| Returns the business service identified by `id`, including the current operational state.

| /opennms/api/v2/business-services/egdes/\{edgeid}
| Returns the edge of the business service identified by `edgeid`.

| /opennms/api/v2/business-services/functions/map
| Provides a list of supported map function definitions.

| /opennms/api/v2/business-services/functions/map/\{name}
| Returns the definition of the map function identified by `name`.

| /opennms/api/v2/business-services/functions/reduce/
| Provides a list of supported reduce function definitions.

| /opennms/api/v2/business-services/functions/reduce/\{name}
| Returns the definition of the reduce function identified by `name`.
|===

== PUT (modifying data)

[caption=]
.Business Service API PUT function
[options="autowidth"]
|===
| Resource  | Description

| /opennms/api/v2/business-services/\{id}
| Modifies an existing business service identified by `id`.
|===

== POSTs (adding data)

[caption=]
.Business Service API POST functions
[options="autowidth"]
|===
| Resource  | Description

| /opennms/api/v2/business-services
| Creates a new business service.

| /opennms/api/v2/business-services/\{id}/ip-service-edge
| Adds an edge of type IP service to the business service identified by `id`.

| /opennms/api/v2/business-services/\{id}/reduction-key-edge
| Adds an edge of type reduction key to the business service identified by `id`.

| /opennms/api/v2/business-services/\{id}/child-edge
| Adds an edge of type business service to the business service identified by `id`.

| /opennms/api/v2/daemon/reload
| Reload the configuration of the business service daemon.
|===

== DELETEs (removing data)

[caption=]
.Business Service API DELETE functions
[options="autowidth"]
|===
| Resource  | Description

| /opennms/api/v2/business-services/\{id}
| Deletes the business service identified by `id`.

| /opennms/api/v2/business-services/\{id}/edges/\{edgeid}
| Removes an edge with the identifier `edgeid` from the business service identified by `id`.
|===
