10 Webservice engine

10.3.1 JSON paths#

A path says how to reach a value from the root of the JSON document. It is made of steps separated by colons (:):

An item’s path must end at a simple value (text, number, boolean or null). Given this document:

{
  "server":   { "name": "ent01", "state": "RUNNING", "up": true },
  "jobs": [
    { "id": 1, "name": "backup", "status": "OK",     "duration": 120 },
    { "id": 2, "name": "purge",  "status": "FAILED", "duration": 30 }
  ],
  "counters": { "cpu": 12.5, "memory": 2048 },
  "note": null
}

In the not supported cases, if the item has a default attribute, that value is sent. With type="INT", booleans are turned into 1 and 0.

10.3.2 Parameters in the URL#

Each <parameter> with urlparameter adds to the URL a parameter with that name and the key value. The query runs once for each distinct key:

<query name="JDEInstanceState" module="JDE" type="REST" transport="GET" encode="Json">
    <url>instancestate</url>
    <parameter urlparameter="instanceName" order="1" type="STRING"/>
    <item name="ts.jde.instance.state" path="instanceState" type="STRING"/>
</query>

On each call the service answers, for example, {"instanceState":"RUNNING"}, and the path instanceState extracts the value.

10.3.3 Filtering the response#

When the service returns the list of all objects at once, it is more efficient to make a single call and pick the element in the response, just like a Database FILTER query. To do so:

• <base path="…"> gives the array to iterate (its path ends in []);

• each <parameter path="…"> gives a field of each element that is compared with a key parameter;

• item paths are relative to the selected element.

<query name="LocalJobs" module="API" type="REST" transport="GET" encode="Json">
    <url>status</url>
    <base path="jobs:[]"/>
    <parameter path="name" order="1" type="STRING"/>
    <item name="local.api.job.status"   path="status"   type="STRING" default="UNKNOWN"/>
    <item name="local.api.job.duration" path="duration" type="INT"/>
</query>

With the document of the previous section as the response:

The five keys are resolved with a single call to the service. With type="INT" in the <parameter>, the comparison is numeric (for example, parameter path="id" and the key …[2]).

10.3.4 REST discoveries#

The path of a discovery’s <item> iterates over an array ([]) or over the members of an object (*). Each element iterated is a discovered entity, and the <field> paths are relative to it:

<query name="LocalJobDiscovery" module="API" type="REST"
       transport="GET" encode="Json" discovery="yes">
    <url>status</url>
    <item name="local.api.job.discovery" path="jobs:[]"/>
    <field name="JOB"    path="name"/>
    <field name="JOBID"  path="id"/>
</query>

With the document of section 10.3.1, the item value is:

{"data":[ {"{#JOB}":"backup", "{#JOBID}":"1"},
          {"{#JOB}":"purge",  "{#JOBID}":"2"} ]}

{ "clusters": [
    { "name": "A", "nodes": [ {"host": "a1"}, {"host": "a2"} ] },
    { "name": "B", "nodes": [ {"host": "b1"} ] }
] }

<query name="LocalNodeDiscovery" module="API" type="REST"
       transport="GET" encode="Json" discovery="yes">
    <url>clusters</url>
    <script language="Javascript"><![CDATA[
        function flatten(status_code, result) {
            if (status_code != 200) throw "ZBX_NOTSUPPORTED";
            var res = { nodes: [] };
            for (var i = 0; i < result.clusters.length; i++) {
                var c = result.clusters[i];
                for (var j = 0; j < c.nodes.length; j++)
                    res.nodes.push({ cluster: c.name, host: c.nodes[j].host });
            }
            return res;
        }
        ]]>
    </script>
    <transform language="Javascript" function="flatten"/>
    <item name="local.api.node.discovery" path="nodes:[]"/>
    <field name="CLUSTER" path="cluster"/>
    <field name="HOST"    path="host"/>
</query>

{"data":[ {"{#CLUSTER}":"A","{#HOST}":"a1"}, {"{#CLUSTER}":"A","{#HOST}":"a2"},
          {"{#CLUSTER}":"B","{#HOST}":"b1"} ]}

10.4.1 Converting the SOAP response to JSON#

Databbix converts into JSON the method response element, that is, the first child of <Body>. That element is the root of the JSON: its name is not part of the paths. The conversion follows these rules:

1. An element with child elements becomes an object. Each child is a member with its local name, without the namespace prefix.

2. If an element has several children with the same name, that member is an array with all their values, in order.

3. An element without children becomes a string, even if its content is a number or a boolean, and even if it has an xsi:type attribute.

4. XML attributes are ignored.

5. The order of the object’s members may not match the XML order. This does not affect paths.

Since all simple values are strings, transformation functions must convert them to operate on them (Number(r.sessions) in JavaScript, int(r[’sessions’]) in Python). Items do not need this: type="INT" sends the text as is and turns true/false into 1/0.

Example. Service response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <ns2:getCurrentUserProfileResponse xmlns:ns2="http://oracle.e1.bssv.JP000000/">
      <addressNumber>4242</addressNumber>
      <active xsi:type="xsd:boolean">true</active>
      <sessions xsi:type="xsd:int">3</sessions>
      <userProfile>
        <language>E</language>
        <dateFormat>MDY</dateFormat>
      </userProfile>
      <role>ADMIN</role>
      <role>USER</role>
    </ns2:getCurrentUserProfileResponse>
  </soap:Body>
</soap:Envelope>

Resulting JSON (which the <transform> function receives, if there is one):

{
  "addressNumber": "4242",
  "active": "true",
  "sessions": "3",
  "userProfile": { "language": "E", "dateFormat": "MDY" },
  "role": [ "ADMIN", "USER" ]
}

<soap:Body>
  <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring>User not authorized</faultstring>
  </soap:Fault>
</soap:Body>

{ "faultcode": "soap:Server", "faultstring": "User not authorized" }

10.4.2 Transforming SOAP responses#

The <transform> function receives (status_code, result), as in REST, but status_code is always 0 and result is the JSON obtained with the rules above. This example detects Faults, normalises role so that it is always an array and computes derived values:

<query name="LocalUserProfile" module="golive" type="SOAP" transport="POST">
    <url>FoundationEnvironmentManager</url>
    <method uri="http://oracle.e1.bssv.JP000000/" name="getCurrentUserProfile" action=""/>
    <script language="Javascript"><![CDATA[
        function profile(status_code, r) {
            if (r.faultcode !== undefined) {
                log_info("SOAP Fault:", r.faultstring);
                throw "ZBX_NOTSUPPORTED";
            }
            var roles = r.role;
            if (roles === undefined)
                roles = [];
            else if (!(roles instanceof Array))
                roles = [ roles ];                 // a single <role>
            return {
                address:  Number(r.addressNumber),
                nroles:   roles.length,
                admin:    roles.indexOf("ADMIN") >= 0,
                language: r.userProfile ? r.userProfile.language : ""
            };
        }
        ]]>
    </script>
    <transform language="Javascript" function="profile"/>
    <item name="local.golive.address"  path="address"  type="INT"/>
    <item name="local.golive.nroles"   path="nroles"   type="INT"/>
    <item name="local.golive.admin"    path="admin"    type="INT"/>
    <item name="local.golive.language" path="language" type="STRING"/>
</query>

The same function in Python:

def profile(status_code, r):
    if 'faultcode' in r:
        log_info("SOAP Fault:", r.get('faultstring'))
        raise Exception("ZBX_NOTSUPPORTED")
    roles = r.get('role', [])
    if not isinstance(roles, list):
        roles = [roles]
    return {
        'address':  r.get('addressNumber'),
        'nroles':   len(roles),
        'admin':    'ADMIN' in roles,
        'language': r.get('userProfile', {}).get('language', '')
    }

10.6.1 Authentication engines and methods#

Two things must be distinguished:

Authentication engine.

Written in C++ inside Databbix, it implements a complete mechanism: how credentials are sent, how a token is obtained and renewed, etc. There are four: HTTPAuth, RESTToken, JDE and Oasis.

Authentication method.

Defined in a query file with <authentication>. It takes an engine (type attribute) and customises it for a particular service with JavaScript or Python functions and other elements (login URL, headers, where the token goes…). It is identified by its name attribute.

10.6.2 How the authentication is chosen#

The Webservice.Authenticator parameter of the .conf contains a name. Databbix looks it up in this order:

1. An authentication method in the monitor’s query files: an <authentication> whose name matches. If found, it uses the engine given by its type, customised with the method’s functions.

2. An authentication engine with that name. If found, it is used directly, without customisation, with the credentials from the .conf. (The name with the Authenticator suffix is also accepted, such as HTTPAuthAuthenticator.)

3. If neither is found, the monitor cannot connect and logs the error.

10.6.3 Examples#

Engine used directly: there is no method called JDE in the XML files, so the JDE engine is used as is.

[Webservice]
BaseURL = http://jdesm.example.com:8999/manage/mgmtrestservice/
Authenticator = JDE
UserName = jde_admin
Password = secret

Authentication method: the XML file defines AISAuth, which customises the RESTToken engine, and the .conf uses it by name.

<Queries engine="Webservice">
    <authentication type="RESTToken" name="AISAuth">
        <script language="Javascript"> ... </script>
        <login type="JsonPost"> ... </login>
        <token type="Header" name="jde-AIS-Auth"/>
        <verify-call language="Javascript" function="verifyCall"/>
    </authentication>
    <query ...> ... </query>
</Queries>

[Webservice]
Authenticator = AISAuth

Programming the functions of an authentication method is described in section 12.7.