Zementis microservice API - Cumulocity IoT Guides

Overview

This guide provides users with a comprehensive set of API (Application Programming Interface) to interact with the Zementis microservice using REST (Representational State Transfer) over HTTP (Hypertext Transfer Protocol). The Zementis microservice API allows users to perform operations on models and custom resources, and process data by issuing a simple request using any HTTP client such as a web browser.

URI

A full path to the Zementis microservice API resource consists of a base path and a resource path.

The base path URI (Uniform Resource Identifier) for the Zementis microservice API is http://domain:port/service/zementis, where http or https is the protocol name, domain is the internet domain or network address, port is a non-negative integer representing the port number, and service/zementis represents the application context path. The base path is static and does not change between requests; it merely identifies the server with an application on the network.

Following the base path is the resource path. It may contain path or query parameters depending on the type of the request and available resources on the server. For example, a resource path /model/Iris_NN/source?annotated=true contains static path definitions such as model or source, path parameter Iris_NN for a dynamically allocated resource, and a query parameter annotated=true.

In the following examples, http://domain:port is represented as {{ url }}.

Request

The HTTP request is a combination of a simple URI, HTTP verb GET, POST, PUT, or DELETE, request parameters, which can be in the form of a path variable, query, body, or header parameters, and message body (content).

The path variable is a variable part of otherwise static URI that denotes a set of possible resource names on the server and is denoted with curly braces. For example, /model/{model_name}/source resource path specifies the PMML file for an arbitrary model denoted as {model_name}. Thus, the request path for the PMML file of model Iris_NN should be constructed as /model/Iris_NN/source.

Query parameters are appended to the URI with a question mark followed by a list of key/value pairs. A query variable annotated with the value true in the /model/Iris_NN?annotated=true resource path specifies that the returned PMML file should contain annotations as placed by Zementis Server, in case of errors or warnings.

Header parameters are HTTP message metadata in the form of key/value pairs containing information about the message such as content type, message encoding type, authorization, etc.

Body parameters appear only in POST or PUT requests and need to be encoded by the HTTP client.

In the following examples, {{ auth }} represents the base64-encoded tenant/username:password or username:password sent as Basic Authorization headers with HTTP requests.

Response

The HTTP response message is composed of a message header and a message body. All Zementis microservice response content types implement standard UTF-8 character set encoding.

The header contains response status code and header fields represented as list of key/value pairs, i.e. Content-Type:application/json. Every response from Zementis microservice contains a Content-Type header entry with one of following internet media types (aka MIME) as value.

application/json
application/xml
text/plain
application/zip

Errors

In error cases, standard HTTP response codes are returned. The response body can contain more information about the error, see the error media type definition below.

The error interpretations are:

Code	Name	Description
400	Bad Request	Invalid PMML or resource file was provided for uploading.
401	Unauthorized	Authentication has failed, or credentials were required but not provided.
404	Not Found	Model or resource was not found.
409	Conflict	Model or resource already exists.
500	Internal Server Error	An internal error has occurred and the request could not be processed.

Models

Operations on AI/Machine Learning models.

Info

An active subscription of the Onnx microservice is required to perform operations on ONNX models by leveraging the ONNX APIs.

GET - List available PMML models

{{url}}/service/zementis/models

Retrieves the model names of all the available PMML models. Use these model names as identifiers for all operations requiring the model_name path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/models" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": [
     "Iris_CT",
     "Iris_ME_Classification",
     "Iris_NN"
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/models"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get PMML model information

{{url}}/service/zementis/model/{{model_name}}

Get model name, description, and information about input, output, or derived fields.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName": "Iris_ME_Classification",
  "description": "Model Ensemble (Decision Tree, Neural Network and Multinomial Logistic Regression) using the Iris dataset.",
  "creationDate": "Sep 29, 2011",
  "isActive": true,
  "inputFields": [
    {
      "usage": "ACTIVE",
      "name": "petal_length",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "petal_width",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "sepal_length",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "sepal_width",
      "type": "DOUBLE"
    }
  ],
  "outputFields": [
    {
      "usage": "OUTPUT",
      "name": "class",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Probability_setosa",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Probability_versicolor",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Probability_virginica",
      "type": "DOUBLE"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/model/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

GET - Get PMML model source

{{url}}/service/zementis/model/{{model_name}}/source

Get annotated or original PMML file. Annotated source may contain warning or error messages embedded in XML comments that are useful for verifying that the PMML code is correct.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name
annotated (Boolean)	optional query parameter used to request the annotated version of the PMML file

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/model/Iris_CT/source?annotated=true" --header "Authorization: {{auth}}"

Example Response

200 - OK

<?xml version="1.0" encoding="UTF-8"?>
<!--(Comment generated by ADAPA) PMML processed by ADAPA (Version : 4.4)--><PMML version="4.0" xsi:schemaLocation="http://www.dmg.org/PMML-4_0 http://www.dmg.org/v4-0/pmml-4-0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.dmg.org/PMML-4_0">
  <Header copyright="Copyright (c) 2008-2014 Zementis, Inc. (www.zementis.com)" description="Classification Tree using the Iris dataset">
    <Timestamp>Jun 15, 2008</Timestamp>
  </Header>
  <DataDictionary numberOfFields="5">
    <DataField dataType="double" name="sepal_length" optype="continuous"/>
    <DataField dataType="double" name="sepal_width" optype="continuous"/>
    <DataField dataType="double" name="petal_length" optype="continuous"/>
    <DataField dataType="double" name="petal_width" optype="continuous"/>
    <DataField dataType="string" name="target_class" optype="categorical">
      <Value property="valid" value="Iris-setosa"/>
      <Value property="valid" value="Iris-versicolor"/>
      <Value property="valid" value="Iris-virginica"/>
    </DataField>
  </DataDictionary>
  <TreeModel algorithmName="CART" functionName="classification" modelName="Iris_CT">
    <MiningSchema>
      <MiningField name="petal_length" usageType="active" invalidValueTreatment="asMissing"/>
      <MiningField name="petal_width" usageType="active" invalidValueTreatment="asMissing"/>
      <MiningField name="sepal_length" usageType="active" invalidValueTreatment="asMissing"/>
      <MiningField name="sepal_width" usageType="active" invalidValueTreatment="asMissing"/>
      <MiningField name="target_class" usageType="predicted"/>
    </MiningSchema>
    <Output>
      <OutputField dataType="string" feature="predictedValue" name="class" optype="categorical" />
      <OutputField dataType="double" feature="probability" name="Probability_setosa" optype="continuous" value="Iris-setosa"/>
      <OutputField dataType="double" feature="probability" name="Probability_versicolor" optype="continuous" value="Iris-versicolor"/>
      <OutputField dataType="double" feature="probability" name="Probability_virginica" optype="continuous" value="Iris-virginica"/>
    </Output>
    <Node id="0" recordCount="150" score="Iris-setosa">
      <True/>
      <ScoreDistribution recordCount="50" value="Iris-setosa"/>
      <ScoreDistribution recordCount="50" value="Iris-versicolor"/>
      <ScoreDistribution recordCount="50" value="Iris-virginica"/>
      <Node id="1" recordCount="50" score="Iris-setosa">
        <CompoundPredicate booleanOperator="surrogate">
          <CompoundPredicate booleanOperator="and">
            <True/>
            <SimplePredicate field="petal_length" operator="lessOrEqual" value="2.45"/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <True/>
            <SimplePredicate field="petal_width" operator="lessOrEqual" value="0.8"/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <True/>
            <SimplePredicate field="sepal_length" operator="lessOrEqual" value="5.45"/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <SimplePredicate field="sepal_width" operator="greaterThan" value="3.35"/>
            <True/>
          </CompoundPredicate>
          <False/>
        </CompoundPredicate>
        <ScoreDistribution recordCount="50" value="Iris-setosa"/>
        <ScoreDistribution recordCount="0" value="Iris-versicolor"/>
        <ScoreDistribution recordCount="0" value="Iris-virginica"/>
      </Node>
      <Node id="2" recordCount="100" score="Iris-versicolor">
        <CompoundPredicate booleanOperator="surrogate">
          <CompoundPredicate booleanOperator="and">
            <SimplePredicate field="petal_length" operator="greaterThan" value="2.45"/>
            <True/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <SimplePredicate field="petal_width" operator="greaterThan" value="0.8"/>
            <True/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <SimplePredicate field="sepal_length" operator="greaterThan" value="5.45"/>
            <True/>
          </CompoundPredicate>
          <CompoundPredicate booleanOperator="and">
            <True/>
            <SimplePredicate field="sepal_width" operator="lessOrEqual" value="3.35"/>
          </CompoundPredicate>
          <True/>
        </CompoundPredicate>
        <ScoreDistribution recordCount="0" value="Iris-setosa"/>
        <ScoreDistribution recordCount="50" value="Iris-versicolor"/>
        <ScoreDistribution recordCount="50" value="Iris-virginica"/>
        <Node id="3" recordCount="54" score="Iris-versicolor">
          <CompoundPredicate booleanOperator="surrogate">
            <CompoundPredicate booleanOperator="and">
              <True/>
              <SimplePredicate field="petal_width" operator="lessOrEqual" value="1.75"/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <True/>
              <SimplePredicate field="petal_length" operator="lessOrEqual" value="4.75"/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <True/>
              <SimplePredicate field="sepal_length" operator="lessOrEqual" value="6.15"/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <True/>
              <SimplePredicate field="sepal_width" operator="lessOrEqual" value="2.95"/>
            </CompoundPredicate>
            <True/>
          </CompoundPredicate>
          <ScoreDistribution recordCount="0" value="Iris-setosa"/>
          <ScoreDistribution recordCount="49" value="Iris-versicolor"/>
          <ScoreDistribution recordCount="5" value="Iris-virginica"/>
          <Node id="5" recordCount="48" score="Iris-versicolor">
            <CompoundPredicate booleanOperator="surrogate">
              <CompoundPredicate booleanOperator="and">
                <True/>
                <SimplePredicate field="petal_length" operator="lessOrEqual" value="4.95"/>
              </CompoundPredicate>
              <CompoundPredicate booleanOperator="and">
                <True/>
                <SimplePredicate field="sepal_length" operator="lessOrEqual" value="7.1"/>
              </CompoundPredicate>
              <True/>
            </CompoundPredicate>
            <ScoreDistribution recordCount="0" value="Iris-setosa"/>
            <ScoreDistribution recordCount="47" value="Iris-versicolor"/>
            <ScoreDistribution recordCount="1" value="Iris-virginica"/>
          </Node>
          <Node id="6" recordCount="6" score="Iris-virginica">
            <CompoundPredicate booleanOperator="surrogate">
              <CompoundPredicate booleanOperator="and">
                <SimplePredicate field="petal_length" operator="greaterThan" value="4.95"/>
                <True/>
              </CompoundPredicate>
              <CompoundPredicate booleanOperator="and">
                <SimplePredicate field="sepal_length" operator="greaterThan" value="7.1"/>
                <True/>
              </CompoundPredicate>
              <False/>
            </CompoundPredicate>
            <ScoreDistribution recordCount="0" value="Iris-setosa"/>
            <ScoreDistribution recordCount="2" value="Iris-versicolor"/>
            <ScoreDistribution recordCount="4" value="Iris-virginica"/>
            <Node id="9" recordCount="3" score="Iris-virginica">
              <CompoundPredicate booleanOperator="surrogate">
                <CompoundPredicate booleanOperator="and">
                  <True/>
                  <SimplePredicate field="petal_width" operator="lessOrEqual" value="1.55"/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <True/>
                  <SimplePredicate field="sepal_width" operator="lessOrEqual" value="2.65"/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <True/>
                  <SimplePredicate field="sepal_length" operator="lessOrEqual" value="6.5"/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <True/>
                  <SimplePredicate field="petal_length" operator="lessOrEqual" value="5.7"/>
                </CompoundPredicate>
                <True/>
              </CompoundPredicate>
              <ScoreDistribution recordCount="0" value="Iris-setosa"/>
              <ScoreDistribution recordCount="0" value="Iris-versicolor"/>
              <ScoreDistribution recordCount="3" value="Iris-virginica"/>
            </Node>
            <Node id="10" recordCount="3" score="Iris-versicolor">
              <CompoundPredicate booleanOperator="surrogate">
                <CompoundPredicate booleanOperator="and">
                  <SimplePredicate field="petal_width" operator="greaterThan" value="1.55"/>
                  <True/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <SimplePredicate field="sepal_width" operator="greaterThan" value="2.65"/>
                  <True/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <SimplePredicate field="sepal_length" operator="greaterThan" value="6.5"/>
                  <True/>
                </CompoundPredicate>
                <CompoundPredicate booleanOperator="and">
                  <SimplePredicate field="petal_length" operator="greaterThan" value="5.7"/>
                  <True/>
                </CompoundPredicate>
                <False/>
              </CompoundPredicate>
              <ScoreDistribution recordCount="0" value="Iris-setosa"/>
              <ScoreDistribution recordCount="2" value="Iris-versicolor"/>
              <ScoreDistribution recordCount="1" value="Iris-virginica"/>
            </Node>
          </Node>
        </Node>
        <Node id="4" recordCount="46" score="Iris-virginica">
          <CompoundPredicate booleanOperator="surrogate">
            <CompoundPredicate booleanOperator="and">
              <SimplePredicate field="petal_width" operator="greaterThan" value="1.75"/>
              <True/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <SimplePredicate field="petal_length" operator="greaterThan" value="4.75"/>
              <True/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <SimplePredicate field="sepal_length" operator="greaterThan" value="6.15"/>
              <True/>
            </CompoundPredicate>
            <CompoundPredicate booleanOperator="and">
              <SimplePredicate field="sepal_width" operator="greaterThan" value="2.95"/>
              <True/>
            </CompoundPredicate>
            <False/>
          </CompoundPredicate>
          <ScoreDistribution recordCount="0" value="Iris-setosa"/>
          <ScoreDistribution recordCount="1" value="Iris-versicolor"/>
          <ScoreDistribution recordCount="45" value="Iris-virginica"/>
          <Node id="7" recordCount="3" score="Iris-virginica">
            <CompoundPredicate booleanOperator="surrogate">
              <CompoundPredicate booleanOperator="and">
                <True/>
                <SimplePredicate field="petal_length" operator="lessOrEqual" value="4.85"/>
              </CompoundPredicate>
              <False/>
            </CompoundPredicate>
            <ScoreDistribution recordCount="0" value="Iris-setosa"/>
            <ScoreDistribution recordCount="1" value="Iris-versicolor"/>
            <ScoreDistribution recordCount="2" value="Iris-virginica"/>
          </Node>
          <Node id="8" recordCount="43" score="Iris-virginica">
            <CompoundPredicate booleanOperator="surrogate">
              <CompoundPredicate booleanOperator="and">
                <SimplePredicate field="petal_length" operator="greaterThan" value="4.85"/>
                <True/>
              </CompoundPredicate>
              <True/>
            </CompoundPredicate>
            <ScoreDistribution recordCount="0" value="Iris-setosa"/>
            <ScoreDistribution recordCount="0" value="Iris-versicolor"/>
            <ScoreDistribution recordCount="43" value="Iris-virginica"/>
          </Node>
        </Node>
      </Node>
    </Node>
  </TreeModel>
</PMML>

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification/source?annotated=true"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/model/dummy/source" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

GET - Get serialized source of PMML model

{{url}}/service/zementis/model/{{model_name}}/serialized

Get binary file containing serialized representation of the model.

Note that this binary file downloaded from a particular version of Zementis microservice can only be uploaded back to a Zementis microservice of the same version.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification/serialized" --header "Authorization: {{auth}}"

Example Response

200 - OK

Binary file

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification/serialized"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/model/dummy/serialized" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

GET - Model metrics information of PMML model

{{url}}/service/zementis/model/{{model_name}}/metrics

Get the memory metrics and prediction metrics of an uploaded PMML model.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification/metrics" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelSize": ".04 MB",
  "usedMemory": "460.845 MB",
  "freeMemory": "2346.49 MB",
  "totalMemory": "2807.375 MB",
  "predictionMetrics": {
    "Iris-versicolor": 156,
    "Iris-virginica": 144,
    "Iris-setosa": 159
  }
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/model/Iris_ME_Classification/metrics"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/model/dummy/metrics" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

POST - Upload new PMML model

{{url}}/service/zementis/model

Upload new PMML model. If the PMML file is large, such as Random Forest model, we recommend you to compress the file with ZIP/GZIP before uploading. This will reduce the upload time drastically. Note that the size of the uploaded PMML file/zip must not exceed 500 MB.

If the model name contains any unsafe characters, all such characters will be converted to underscore automatically. Hence, all subsequent calls should refer to the converted name as listed in the properties of the model.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file	required query parameter for PMML file name, if Content-Type is application/octet-stream or a body parameter for PMML file, if Content-Type is multipart/form-data
applyCleanser (Boolean)	optional parameter used to automatically perform comprehensive syntactic and semantic checks, correct known issues and convert your PMML file to version 4.4 (default is true)

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/model?applyCleanser=false" --header "Authorization: {{auth}}" --form "file=@Iris_KM.pmml"

Example Response

200 - OK

<?xml version="1.0" encoding="UTF-8"?>
<!--(Comment generated by ADAPA) There is at least 1 error in this PMML document.
 Detailed information can be found as comments embedded in the appropriate locations within this document.-->
<pmml:PMML version="4.1" xsi:schemaLocation="http://www.dmg.org/PMML-4_1 http://dmg.org/v4-1/pmml-4-1.xsd" xmlns="http://www.dmg.org/PMML-4_1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:pmml="http://www.dmg.org/PMML-4_4">
    <pmml:Header copyright="Copyright (c) 2009-2014 Zementis Inc. (www.zementis.com)" description="K-means Cluster Model using normalized Iris dataset">
        <pmml:Timestamp>Feb 26, 2009</pmml:Timestamp>
    </pmml:Header>
    <pmml:DataDictionary numberOfFields="5">
        <pmml:DataField dataType="double" name="SEPAL_LE" optype="continuous">
            <pmml:Interval closure="closedClosed" leftMargin="0.53" rightMargin="0.99"/>
        </pmml:DataField>
        <pmml:DataField dataType="double" name="SEPAL_WI" optype="continuous">
            <pmml:Interval closure="closedClosed" leftMargin="0.4" rightMargin="0.88"/>
        </pmml:DataField>
        <pmml:DataField dataType="double" name="PETAL_LE" optype="continuous">
            <pmml:Interval closure="closedClosed" leftMargin="0.2" rightMargin="1.38"/>
        </pmml:DataField>
        <pmml:DataField dataType="double" name="PETAL_WI" optype="continuous">
            <pmml:Interval closure="closedClosed" leftMargin="0.03" rightMargin="0.84"/>
        </pmml:DataField>
        <pmml:DataField dataType="string" name="CLASS" optype="categorical">
            <pmml:Value value="Iris-setosa"/>
            <pmml:Value value="Iris-versic"/>
            <pmml:Value value="Iris-virgin"/>
        </pmml:DataField>
    </pmml:DataDictionary>
    <pmml:ClusteringModel functionName="clustering" modelClass="centerBased" modelName="Iris_KM" numberOfClusters="3">
        <pmml:MiningSchema>
            <pmml:MiningField name="SEPAL_LE" invalidValueTreatment="asMissing"/>
            <pmml:MiningField name="SEPAL_WI" invalidValueTreatment="asMissing"/>
            <pmml:MiningField name="PETAL_LE" invalidValueTreatment="asMissing"/>
            <pmml:MiningField name="PETAL_WI" invalidValueTreatment="asMissing"/>
            <pmml:MiningField name="CLASS" usageType="predicted"/>
        </pmml:MiningSchema>
        <pmml:Output>
            <pmml:OutputField dataType="string" feature="predictedValue" name="CLASS" optype="categorical">
                <!--(Comment generated by ADAPA) Error: Field name duplicates existing [MiningField] name-->

            </pmml:OutputField>
            <pmml:OutputField dataType="string" feature="clusterId" name="Cluster ID" optype="categorical"/>
            <pmml:OutputField dataType="double" feature="clusterAffinity" name="Cluster Affinity for predicted" optype="continuous"/>
            <pmml:OutputField dataType="double" feature="clusterAffinity" name="Cluster Affinity for setosa" optype="continuous" value="Iris-setosa"/>
            <pmml:OutputField dataType="double" feature="clusterAffinity" name="Cluster Affinity for versic" optype="continuous" value="Iris-versic"/>
            <pmml:OutputField dataType="double" feature="clusterAffinity" name="Cluster Affinity for virgin" optype="continuous" value="Iris-virgin"/>
        </pmml:Output>
        <pmml:ComparisonMeasure kind="distance">
            <pmml:squaredEuclidean/>
        </pmml:ComparisonMeasure>
        <pmml:ClusteringField compareFunction="absDiff" field="SEPAL_LE"/>
        <pmml:ClusteringField compareFunction="absDiff" field="SEPAL_WI"/>
        <pmml:ClusteringField compareFunction="absDiff" field="PETAL_LE"/>
        <pmml:ClusteringField compareFunction="absDiff" field="PETAL_WI"/>
        <pmml:Cluster id="Iris-versic" size="51">
            <pmml:Array n="4" type="real">0.7398039215686276 0.548235294117647
                0.8541176470588238 0.4403921568627449</pmml:Array>
        </pmml:Cluster>
        <pmml:Cluster id="Iris-virgin" size="49">
            <pmml:Array n="4" type="real">0.8291836734693881 0.6016326530612247
                1.1134693877551018 0.6812244897959185</pmml:Array>
        </pmml:Cluster>
        <pmml:Cluster id="Iris-setosa" size="50">
            <pmml:Array n="4" type="real">0.6277999999999999 0.6836000000000001
                0.29280000000000006 0.08239999999999997</pmml:Array>
        </pmml:Cluster>
    </pmml:ClusteringModel>
</pmml:PMML>

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/model" --header "Authorization: {{auth}}" --form "file=@Iris_KM.pmml"

Example Response

201 - Created

{
  "modelName": "Iris_KM",
  "description": "K-means Cluster Model using normalized Iris dataset",
  "creationDate": "Feb 26, 2009",
  "isActive": true,
  "inputFields": [
    {
      "usage": "ACTIVE",
      "name": "SEPAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "SEPAL_WI",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_WI",
      "type": "DOUBLE"
    }
  ],
  "outputFields": [
    {
      "usage": "OUTPUT",
      "name": "predictedValue_CLASS",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster ID",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for predicted",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for setosa",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for versic",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for virgin",
      "type": "DOUBLE"
    }
  ]
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/model" --header "Authorization: {{auth}}" --form "file=@Invalid.pmml"

Example Response

400 - Bad Request

{
  "errors": [
    "Invalid XML format."
  ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/model"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/model" --header "Authorization: {{auth}}" --form "file=@Iris_KM.pmml"

Example Response

409 - Conflict

{
  "errors": [
    "A model with the name 'Iris_KM' already exists."
  ]
}

PUT - Activate an existing PMML model

{{url}}/service/zementis/model/{{model_name}}/activate

Activates the PMML model with name model_name if it was inactive. Activating an active model has no effect. After activation, the model is immediately available for handling data processing requests. Note that an active model consumes runtime resources, especially Heap.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request PUT "{{url}}/service/zementis/model/Iris_KM/activate" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName": "Iris_KM",
  "description": "K-means Cluster Model using normalized Iris dataset",
  "creationDate": "Feb 26, 2009",
  "isActive": true,
  "inputFields": [
    {
      "usage": "ACTIVE",
      "name": "SEPAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "SEPAL_WI",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_WI",
      "type": "DOUBLE"
    }
  ],
  "outputFields": [
    {
      "usage": "OUTPUT",
      "name": "predictedValue_CLASS",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster ID",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for predicted",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for setosa",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for versic",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for virgin",
      "type": "DOUBLE"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request PUT "{{url}}/service/zementis/model/Iris_KM/activate"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/model/dummy/activate" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

PUT - Deactivate an existing PMML model

{{url}}/service/zementis/model/{{model_name}}/deactivate

Deactivates the PMML model with name model_name by making it inactive. After deactivation, the model is still available, but it no longer consumes runtime resources, especially Heap. Deactivating an inactive model has no effect.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request PUT "{{url}}/service/zementis/model/Iris_KM/deactivate" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName": "Iris_KM",
  "description": "K-means Cluster Model using normalized Iris dataset",
  "creationDate": "Feb 26, 2009",
  "isActive": false,
  "inputFields": [
    {
      "usage": "ACTIVE",
      "name": "SEPAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "SEPAL_WI",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_LE",
      "type": "DOUBLE"
    },
    {
      "usage": "ACTIVE",
      "name": "PETAL_WI",
      "type": "DOUBLE"
    }
  ],
  "outputFields": [
    {
      "usage": "OUTPUT",
      "name": "predictedValue_CLASS",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster ID",
      "type": "STRING"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for predicted",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for setosa",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for versic",
      "type": "DOUBLE"
    },
    {
      "usage": "OUTPUT",
      "name": "Cluster Affinity for virgin",
      "type": "DOUBLE"
    }
  ]
}

Example Request

401 Unauthorized

curl --request PUT "{{url}}/service/zementis/model/Iris_KM/deactivate"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/model/dummy/deactivate" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

DEL - Remove PMML model

{{url}}/service/zementis/model/{{model_name}}

Remove the specified PMML model and list the remaining models.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/model/Iris_KM" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": [
     "Iris_CT",
     "Iris_ME_Classification",
     "Iris_NN"
  ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/model/Iris_KM"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/model/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

DEL - Remove all PMML models

{{url}}/service/zementis/models

Remove all available PMML models and list the remaining models.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 OK

curl --request DELETE "{{url}}/service/zementis/models" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/models"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - List available ONNX models

{{url}}/service/zementis/onnx/models

Retrieves the model names of all the available ONNX models. Use these model names as identifiers for all operations requiring the model_name path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/models" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": [
    "resnet50",
    "8635e4b85c51485b93e2d8d9483291f7"
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/models"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get ONNX model information

{{url}}/service/zementis/onnx/models/{{model_name}}

Get model name, model version, onnx version, producer name, producer version and information about inputs and outputs of the ONNX model. Here, the onnx version property actually corresponds to the onnx format version (ir version) and not the release version.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/models/resnet50" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName" : "resnet50",
  "modelVersion" : 0,
  "onnxVersion" : 6,
  "opsetVersions" : "ai.onnx v11",
  "producerName" : "keras2onnx",
  "producerVersion" : "1.6.0",
  "isActive": false,
  "inputs" : [ {
    "name" : "input_3",
    "shape" : [ "N", 224, 224, 3 ],
    "type" : "tensor(float)"
  } ],
  "outputs" : [ {
    "name" : "fc1000",
    "shape" : [ "N", 1000 ],
    "type" : "tensor(float)"
  } ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/models/resnet50"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/onnx/models/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

GET - Get ONNX model source

{{url}}/service/zementis/onnx/models/{{model_name}}/source

Get original ONNX file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/models/resnet50/source" --header "Authorization: {{auth}}"

Example Response

200 - OK

ONNX file

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/models/resnet50/source"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/onnx/models/dummy/source" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

POST - Upload new ONNX model

{{url}}/service/zementis/onnx/models

Upload new ONNX model. Note that the size of the uploaded ONNX file must not exceed 500 MB.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file (file)	ONNX file. Only applicable when Content-Type is multipart/form-data.

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/onnx/models" --header "Authorization: {{auth}}" --form "file=@iris.onnx"

Example Response

201 - Created

{
  "modelName" : "39c9f725699e4c9988ff55b8561db7fe",
  "modelVersion" : 0,
  "onnxVersion" : 6,
  "opsetVersions" : "ai.onnx v9, ai.onnx.ml v1",
  "producerName" : "skl2onnx",
  "producerVersion" : "1.6.0",
  "isActive": true,
  "inputs" : [ {
    "name" : "float_input",
    "shape" : [ null, 4 ],
    "type" : "tensor(float)"
  } ],
  "outputs" : [ {
    "name" : "output_label",
    "shape" : [ 1 ],
    "type" : "tensor(int64)"
  }, {
    "name" : "output_probability",
    "shape" : [ ],
    "type" : "seq(map(int64,tensor(float)))"
  } ]
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/onnx/models" --header "Authorization: {{auth}}" --form "file=@Invalid.file"

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid onnx format."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/onnx/models"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/onnx/models" --header "Authorization: {{auth}}" --form "file=@resnet50.onnx"

Example Response

409 - Conflict

{
    "errors": [
        "A model with the name 'resnet50' already exists."
    ]
}

PUT - Activate an existing ONNX model

{{url}}/service/zementis/onnx/models/{{model_name}}/activate

Activates the ONNX model with name model_name if it was inactive. Activating an active model has no effect. After activation, the model is immediately available for handling data processing requests. Note that an active model consumes runtime resources, especially heap.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request PUT "{{url}}/service/zementis/onnx/models/resnet50/activate" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName" : "resnet50",
  "modelVersion" : 0,
  "onnxVersion" : 6,
  "opsetVersions" : "ai.onnx v11",
  "producerName" : "keras2onnx",
  "producerVersion" : "1.6.0",
  "isActive": true,
  "inputs" : [ {
    "name" : "input_3",
    "shape" : [ "N", 224, 224, 3 ],
    "type" : "tensor(float)"
  } ],
  "outputs" : [ {
    "name" : "fc1000",
    "shape" : [ "N", 1000 ],
    "type" : "tensor(float)"
  } ]
}

Example Request

401 - Unauthorized

curl --request PUT "{{url}}/service/zementis/onnx/models/resnet50/activate"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/onnx/models/dummy/activate" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

PUT - Deactivate an existing ONNX model

{{url}}/service/zementis/onnx/models/{{model_name}}/deactivate

Deactivates the ONNX model with name model_name by making it inactive. After deactivation, the model is still available, but it no longer consumes runtime resources, especially heap. Deactivating an inactive model has no effect.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request PUT "{{url}}/service/zementis/onnx/models/resnet50/deactivate" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "modelName" : "resnet50",
  "modelVersion" : 0,
  "onnxVersion" : 6,
  "opsetVersions" : "ai.onnx v11",
  "producerName" : "keras2onnx",
  "producerVersion" : "1.6.0",
  "isActive": false,
  "inputs" : [ {
    "name" : "input_3",
    "shape" : [ "N", 224, 224, 3 ],
    "type" : "tensor(float)"
  } ],
  "outputs" : [ {
    "name" : "fc1000",
    "shape" : [ "N", 1000 ],
    "type" : "tensor(float)"
  } ]
}

Example Request

401 Unauthorized

curl --request PUT "{{url}}/service/zementis/onnx/models/resnet50/deactivate"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/onnx/models/dummy/deactivate" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

DEL - Remove ONNX model

{{url}}/service/zementis/onnx/models/{{model_name}}

Remove the specified ONNX model and list the remaining models.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/onnx/model/resnet50" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": [
     "8635e4b85c51485b93e2d8d9483291f7"
  ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/models/resnet50"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/onnx/models/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

DEL - Remove all ONNX models

{{url}}/service/zementis/onnx/models

Remove all available ONNX models and list the remaining models.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 OK

curl --request DELETE "{{url}}/service/zementis/onnx/models" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "models": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/models"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Model groups

Operations on model groups.

Info

Currently, model groups can be used for grouping PMML models only.

GET - List PMML groups

{{url}}/service/zementis/pmml/groups

Retrieves all the available PMML model groups.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "next": null,
  "prev": null,
  "statistics": {
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 5
  },
  "groups": [
    {
      "groupName": "AnomalyDetectionModels",
      "models": [
        "IsolationForestV2",
        "IsolationForest",
        "IsolationForestV3",
        "IsolationForestV4"
      ],
      "primaryModel": "IsolationForestV4"
    },
    {
      "groupName": "IrisClassification",
      "models": [
        "Iris_NN_V1",
        "Iris_NN_V2"
      ],
      "primaryModel": "Iris_NN_V1"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/pmml/groups"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get PMML group information

{{url}}/service/zementis/pmml/groups/{{group_name}}

Get details of the PMML model group.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
group_name (string)	required path variable for existing group name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/pmml/groups/AnomalyDetectionModels" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "groupName": "AnomalyDetectionModels",
  "models": [
    "IsolationForestV2",
    "IsolationForest",
    "IsolationForestV3",
    "IsolationForestV4"
  ],
  "primaryModel": "IsolationForestV4"
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/pmml/groups/AnomalyDetectionModels"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/pmml/groups/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model group with name 'dummy' does not exist."
  ]
}

POST - Create PMML group

{{url}}/service/zementis/pmml/groups

Create new PMML model group.

Note that if the model group name contains any unsafe characters, all such characters will be converted to underscore automatically. Hence, all subsequent calls should refer to the converted name as listed in the properties of the model group.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with value as ‘application/json’

BODY

{
    "groupName": "<groupName>",
    "models": [
        "<ModelName1>",
        "<ModelName2>",
        "<ModelName3>"
    ],
    "primaryModel": "<ModelNameFromModelsList>"
}

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "groupName": "ActivityDetectionModels",
    "models": [
        "ActivityClassifier",
        "ActivityClassifier_V2"
    ],
    "primaryModel": "ActivityClassifier"
}

Example Response

201 - Created

{
    "groupName": "ActivityDetectionModels",
    "models": [
      "ActivityClassifier",
      "ActivityClassifier_V2"
    ],
    "primaryModel": "ActivityClassifier"
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "groupName": "GroupWithDuplicateModel",
    "models": [
        "DecisionTreeClassifier",
        "ActivityClassifier_V2"
    ],
    "primaryModel": "DecisionTreeClassifier"
}

Example Response

400 - Bad Request

{
    "errors": [
        "The model 'ActivityClassifier_V2' cannot be added to group because it is used in some other group."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/pmml/groups" --header "Content-Type: application/json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
   "groupName": "IrisClassification",
   "models": [
     "Iris_NN_V3",
     "Iris_NN_V4"
   ],
   "primaryModel": "Iris_NN_V3"
}

Example Response

409 - Conflict

{
    "errors": [
        "A model group with the name 'IrisClassification' already exists."
    ]
}

PUT - Update PMML group

{{url}}/service/zementis/pmml/groups

Update an existing PMML model group by editing the list of models which are part of it or by editing the group’s primary model or both.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

BODY

{
    "groupName": "<existingGroupName>",
    "models": [
        "<ModelName1>",
        "<ModelName2>",
        "<ModelName3>"
    ],
    "primaryModel": "<ModelNameFromModelsList>"
}

Example Request

200 - OK

curl --request PUT "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "groupName": "IrisClassification",
    "models": [
     "Iris_NN_V3",
     "Iris_NN"
    ],
    "primaryModel": "Iris_NN"
}

Example Response

200 - OK

{
    "groupName": "IrisClassification",
    "models": [
      "Iris_NN_V3",
      "Iris_NN"
    ],
    "primaryModel": "Iris_NN"
}

Example Request

401 - Unauthorized

curl --request PUT "{{url}}/service/zementis/pmml/groups" --header "Content-Type: application/json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "groupName": "Dummy",
    "models": [
     "Iris_NN_V3",
     "Iris_NN"
    ],
    "primaryModel": "Iris_NN"
}

Example Response

404 - Not Found

{
    "errors": [
        "Model group with name 'Dummy' does not exist."
    ]
}

DEL - Remove PMML group

{{url}}/service/zementis/pmml/groups/{{group_name}}

Remove the specified PMML model group and list the remaining groups.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
group_name (string)	required path variable for existing group name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/pmml/groups/IrisClassification" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "next": null,
  "prev": null,
  "statistics": {
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 5
  },
  "groups": [
    {
      "groupName": "AnomalyDetectionModels",
      "models": [
        "IsolationForestV2",
        "IsolationForest",
        "IsolationForestV3",
        "IsolationForestV4"
      ],
      "primaryModel": "IsolationForestV4"
    },
    {
      "groupName": "ActivityDetectionModels",
      "models": [
        "ActivityClassifier",
        "ActivityClassifier_V2"
      ],
      "primaryModel": "ActivityClassifier"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/pmml/groups/AnomalyDetectionModels"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/pmml/groups/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Model group with name 'dummy' does not exist."
    ]
}

DEL - Remove PMML groups

{{url}}/service/zementis/pmml/groups

Remove all available PMML model groups.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 OK

curl --request DELETE "{{url}}/service/zementis/pmml/groups" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "next": null,
  "prev": null,
  "statistics": {
    "currentPage": 1,
    "totalPages": 0,
    "pageSize": 5
  },
  "groups": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/pmml/groups"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Pipelines

Operations on pipelines.

Info

Currently, only ONNX pipelines are supported. An active subscription of the Onnx microservice is required to leverage these pipeline APIs.

GET - List ONNX pipelines

{{url}}/service/zementis/onnx/pipelines

Retrieves all the available ONNX pipelines.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "pipelines": [
    {
      "pipelineName": "DetectFabricOrientation",
      "preProcessing": "PreprocessFabricImage.py",
      "modelName": "e1f07d8cd1f64c97ae94fb55534565e7",
      "postProcessing": "ClassifyFabricFace.py"
    },
    {
      "pipelineName": "ClassifyManufacturingActivity",
      "preProcessing": "PreprocessCSVData.py",
      "modelName": "GradientBoostClassifier",
      "postProcessing": "StorePredictionsAsMeasurement.py"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/pipelines"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get ONNX pipeline information

{{url}}/service/zementis/onnx/pipelines/{{pipeline_name}}

Get details of the ONNX pipeline.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
pipeline_name (string)	required path variable for existing pipeline name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/pipelines/DetectFabricOrientation" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "pipelineName": "DetectFabricOrientation",
    "preProcessing": "PreprocessFabricImage.py",
    "modelName": "e1f07d8cd1f64c97ae94fb55534565e7",
    "postProcessing": "ClassifyFabricFace.py"
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/pipelines/DetectFabricOrientation"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/onnx/pipelines/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Pipeline 'dummy' not found."
    ]
}

POST - Create ONNX pipeline

{{url}}/service/zementis/onnx/pipelines

Create new ONNX pipeline.

Note that if the pipeline name contains any unsafe characters, all such characters will be converted to underscore automatically. Hence, all subsequent calls should refer to the converted name as listed in the properties of the pipeline.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with value as ‘application/json’

BODY

{
    "pipelineName": "<pipelineName>",
    "preProcessing": "<pre_processing_script.py>",
    "modelName": "<modelName>",
    "postProcessing": "<post_processing_script.py>"
}

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "pipelineName": "ClassifyFaultyWelds",
    "preProcessing": "PreprocessWeldImage.py",
    "modelName": "FaultyWeldClassifier"
}

Example Response

201 - Created

{
    "pipelineName": "ClassifyFaultyWelds",
    "preProcessing": "PreprocessWeldImage.py",
    "modelName": "FaultyWeldClassifier"
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "pipelineName": "PipelineDemo",
    "model": "FaultyWeldClassifier"
}

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid key 'model' found. Valid keys are - ['pipelineName', 'modelName', 'preProcessing', 'postProcessing']."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/onnx/pipelines" --header "Content-Type: application/json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request POST "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "pipelineName": "ClassifyWelds",
    "preProcessing": "PreprocessWeldImage.py",
    "modelName": "Dummy"
}

Example Response

404 - Not Found

{
    "errors": [
        "Model 'Dummy' not found."
    ]
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}" --header "Content-Type: application/json"

{
    "pipelineName": "DetectFabricOrientation",
    "preProcessing": "PreprocessWeldImage.py",
    "modelName": "FaultyWeldClassifier"
}

Example Response

409 - Conflict

{
    "errors": [
        "A pipeline with the name 'DetectFabricOrientation' already exists."
    ]
}

DEL - Remove ONNX pipeline

{{url}}/service/zementis/onnx/pipelines/{{pipeline_name}}

Remove the specified ONNX pipeline and list the remaining pipelines.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
pipeline_name (string)	required path variable for existing pipeline name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/onnx/pipelines/ClassifyFaultyWelds" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "pipelines": [
    {
      "pipelineName": "DetectFabricOrientation",
      "preProcessing": "PreprocessFabricImage.py",
      "modelName": "e1f07d8cd1f64c97ae94fb55534565e7",
      "postProcessing": "ClassifyFabricFace.py"
    },
    {
      "pipelineName": "ClassifyManufacturingActivity",
      "preProcessing": "PreprocessCSVData.py",
      "modelName": "GradientBoostClassifier",
      "postProcessing": "StorePredictionsAsMeasurement.py"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/pipelines/ClassifyFaultyWelds"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/onnx/pipelines/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Pipeline 'dummy' not found."
    ]
}

DEL - Remove ONNX pipelines

{{url}}/service/zementis/onnx/pipelines

Remove all available ONNX pipelines.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 OK

curl --request DELETE "{{url}}/service/zementis/onnx/pipelines" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "pipelines": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/pipelines"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Resources

Operation on resources.

Info

For PMML, the resources are typically JAR files or excel sheets containing custom functions and look up tables respectively.
For ONNX, the resources are typically python files containing some pre-processing or post-processing logic which can be embedded into a pipeline.

GET - List available PMML resources

{{url}}/service/zementis/resources

This operation retrieves information on all available resource files associated with PMML models. Use file names as identifiers for all operations requiring a file_name path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/resources" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "resources": [
    {
      "fileName": "custom-functions.jar",
      "resourceType": "Custom Functions",
      "resourceIdentifier": "Function Namespace",
      "resourceNames": [
        "fraud"
      ]
    },
    {
      "fileName": "customerAreaMappingTable.xls",
      "resourceType": "Lookup Tables",
      "resourceIdentifier": "Table Name",
      "resourceNames": [
        "AreaPoints"
      ]
    }
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/resources"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get PMML resource information

{{url}}/service/zementis/resource/{{file_name}}

Get information on the specified PMML resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
file_name (string)	required path variable for an existing resource file name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/resource/customerAreaMappingTable.xls" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "fileName": "customerAreaMappingTable.xls",
  "resourceType": "Lookup Tables",
  "resourceIdentifier": "Table Name",
  "resourceNames": [
    "AreaPoints"
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/resource/customerAreaMappingTable.xls"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/resource/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Resource file 'dummy' not found"
  ]
}

GET - Get PMML resource file

{{url}}/service/zementis/resource/{{file_name}}/source

Download a PMML resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
file_name (string)	required path variable for an existing resource file name

Example Request

200 OK

curl --request GET "{{url}}/service/zementis/resource/customerAreaMappingTable.xls/source" --header "Authorization: {{auth}}"

Example Response

200 - OK

Resource file

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/resource/customerAreaMappingTable.xls/source"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/resource/dummy/source" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Resource file 'dummy' not found"
  ]
}

POST - Upload new PMML resource file

{{url}}/service/zementis/resource

Upload a new resource file associated with a PMML model. The file name in the ‘file’ body parameter will be used to identify this resource. Note that the size of the uploaded resource file must not exceed 500 MB.

If the resource file name contains any unsafe characters, all such characters will be converted to underscore automatically. Hence, all subsequent calls should refer to the converted name as listed in the properties of the resource.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file	required query parameter for resource file name, if Content-Type is application/octet-stream, or a body parameter for resource file, if Content-Type is multipart/form-data

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/resource" --header "Authorization: {{auth}}" --form "file=@customerAreaMappingTable.xls"

Example Response

201 - Created

{
  "fileName": "customerAreaMappingTable.xls",
  "resourceType": "Lookup Tables",
  "resourceIdentifier": "Table Name",
  "resourceNames": [
    "AreaPoints"
  ]
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/resource" --header "Authorization: {{auth}}" --form "file=@Empty.jar"

Example Response

400 - Bad Request

{
  "errors": [
    "Empty input stream."
  ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/resource" --form "file=@custom-functions.jar"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/resource" --header "Authorization: {{auth}}" --form "file=@customerAreaMappingTable.xls"

Example Response

409 - Conflict

{
  "errors": [
    "A resource file with the name 'customerAreaMappingTable.xls' already exists."
  ]
}

DEL - Remove PMML resource file

{{url}}/service/zementis/resource/{{file_name}}

Remove the specified resource file and list all remaining PMML resources.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
file_name (string)	required path variable for an existing resource file name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/resource/customerAreaMappingTable.xls" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "resources": [
    {
      "fileName": "custom-functions.jar",
      "resourceType": "Custom Functions",
      "resourceIdentifier": "Function Namespace",
      "resourceNames": [
        "fraud"
      ]
    }
  ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/resource/customerAreaMappingTable.xls"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/resource/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Resource file 'dummy' not found"
  ]
}

DEL - Remove all PMML resource files

{{url}}/service/zementis/resources

Remove all available PMML resources and list the remaining ones, if any.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/resources" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "resources": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/resources"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - List available ONNX resources

{{url}}/service/zementis/onnx/resources

This operation retrieves information on all available resource files associated with ONNX pipelines. Use file names as identifiers for all operations requiring a file_name path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "resources": [
        "PreprocessFabricImage.py",
        "ClassifyFabricFace.py",
        "StorePredictionsAsMeasurement.py"
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/resources"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get ONNX resource

{{url}}/service/zementis/onnx/resources/{{file_name}}

Get contents of the specified ONNX resource file.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
file_name (string)	required path variable for an existing resource file name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/onnx/resources/PreprocessFabricImage.py" --header "Authorization: {{auth}}"

Example Response

200 - OK

def process(content):
    import numpy as np
    from PIL import Image
    import io
    im = Image.open(io.BytesIO(content))
    im = im.resize((224,224))
    x = np.array(im,dtype=np.float32)
    x = x[..., ::-1]
    mean = [103.939, 116.779, 123.68]
    x[..., 0] -= mean[0]
    x[..., 1] -= mean[1]
    x[..., 2] -= mean[2]
    x = np.expand_dims(x,0)
    return {"input_1":x}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/onnx/resources/PreprocessFabricImage.py"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/onnx/resources/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{    
	"errors": [
        "Resource file 'dummy' not found."
    ]
}

POST - Upload new ONNX resource file

{{url}}/service/zementis/onnx/resources

Upload a new resource file containing a pre-processing or post-processing script. The file name in the ‘file’ body parameter will be used to identify this resource. Note that the size of the uploaded resource file must not exceed 500 MB.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file	required query parameter for resource file name, if Content-Type is application/octet-stream, or a body parameter for resource file, if Content-Type is multipart/form-data

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}" --form "file=@PreprocessData.py"

Example Response

201 - Created

{
    "resources": [
        "PreprocessData.py",
        "PreprocessFabricImage.py",
        "ClassifyFabricFace.py",
        "StorePredictionsAsMeasurement.py"
    ]
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}" --form "file=@Invalid.txt"

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid python format."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/onnx/resources" --form "file=@PreprocessData.py"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

409 - Conflict

curl --request POST "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}" --form "file=@PreprocessData.py"

Example Response

409 - Conflict

{
  "errors": [
    "A resource file with the name 'PreprocessData.py' already exists."
  ]
}

DEL - Remove ONNX resource file

{{url}}/service/zementis/onnx/resources/{{file_name}}

Remove the specified resource file and list all remaining ONNX resources.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
file_name (string)	required path variable for an existing resource file name

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/onnx/resources/PreprocessData.py" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "resources": [
        "PreprocessFabricImage.py",
        "ClassifyFabricFace.py",
        "StorePredictionsAsMeasurement.py"
    ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/resources/PreprocessData.py"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/onnx/resources/dummy" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Resource file 'dummy' not found"
  ]
}

Example Request

500 - Internal Server Error

curl --request DELETE "{{url}}/service/zementis/onnx/resources/PreprocessFabricImage.py" --header "Authorization: {{auth}}"

Example Response

500 - Internal Server Error

{
    "errors": [
        "The resource [PreprocessFabricImage.py] is required by the Pipeline(s) [['ClassifyFabricFace']]. Please delete these pipeline(s) before deleting the resource [PreprocessFabricImage.py]."
    ]
}

DEL - Remove all ONNX resource files

{{url}}/service/zementis/onnx/resources

Remove all available ONNX resources and list the remaining ones, if any.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "resources": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/onnx/resources"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

500 - Internal Server Error

curl --request DELETE "{{url}}/service/zementis/onnx/resources" --header "Authorization: {{auth}}"

Example Response

500 - Internal Server Error

{
    "errors": [
        "The resource [PreprocessFabricImage.py] is required by the Pipeline(s) [['ClassifyFabricFace']]. Please delete these pipeline(s) before deleting the resource [PreprocessFabricImage.py]."
    ]
}

Prediction

Operations on applying model, model group, pipeline to input data.

GET - Apply PMML model to single record

{{url}}/service/zementis/apply/{{model_name}}?record={{record}}

Apply a PMML model to a single JSON input record.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name
record (string)	JSON Record - a map of model input fields and their respective values

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/apply/Iris_NN?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D" \
  --header "Authorization: {{auth}}"

Example Response

200 - OK

{
  "model": "Iris_ME_Classification",
  "outputs": [
    {
      "Probability_setosa": 1,
      "Probability_versicolor": 0,
      "Probability_virginica": 0,
      "class": "Iris-setosa"
    }
  ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/apply/Iris_NN?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/apply/dummy?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D" \
  --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

Example Request

500 - Internal server Error

curl --request GET "{{url}}/service/zementis/apply/Iris_NN?record=%7B" --header "Authorization: {{auth}}"

Example Response

500 - Internal server Error

{
  "timestamp": 1554299687990,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "com.fasterxml.jackson.core.io.JsonEOFException",
  "message": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: {; line: 1, column: 1])\n at [Source: {; line: 1, column: 3]",
  "path": "/apply/Iris_ME_Classification"
}

GET - Apply PMML model to single record and explain result

{{url}}/service/zementis/apply/{{model_name}}/explain?record={{record}}

Apply a PMML model to a single JSON input record and get the result with details of the performed computation in plain text.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for existing model name
record (string)	JSON Record - a map of model input fields and their respective values

Example Request

200 - OK

curl --request GET \
     "{{url}}/service/zementis/apply/Iris_NN/explain?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D" \  
     --header "Authorization: {{auth}}"

Example Response

200 - OK  

[petal_length] := 1.4 (DOUBLE)
[petal_width] := 0.2 (DOUBLE)
[sepal_length] := 5.1 (DOUBLE)
[sepal_width] := 3.5 (DOUBLE)

[MiningSchema]
[petal_length] := 1.4 (DOUBLE)
[petal_width] := 0.2 (DOUBLE)
[sepal_length] := 5.1 (DOUBLE)
[sepal_width] := 3.5 (DOUBLE)


[ModelEnsemble]

Process segment model [1]:
The predicate of segment model [1] evaluates [True]

[MiningSchema]
[petal_length] := 1.4 (DOUBLE)
[petal_width] := 0.2 (DOUBLE)
[sepal_length] := 5.1 (DOUBLE)
[sepal_width] := 3.5 (DOUBLE)


[DecisionTree]
Evaluation of node [0] is [True].
Evaluation of node [1] is [True].
The confidence of the category [Iris-versicolor (STRING)] is [0].
The confidence of the category [Iris-setosa (STRING)] is [1].
The confidence of the category [Iris-virginica (STRING)] is [0].

[Output]
The predicted value of segment model [1] is [Iris-setosa (STRING)]


Process segment model [2]:
The predicate of segment model [2] evaluates [True]

[MiningSchema]
[sepal_length] := 5.1 (DOUBLE)
[sepal_width] := 3.5 (DOUBLE)
[petal_length] := 1.4 (DOUBLE)
[petal_width] := 0.2 (DOUBLE)

[LocalTransformations]
[derived_sepal_length] := 0.22222222222222213 (DOUBLE)
[derived_sepal_width] := 0.6818181818181818 (DOUBLE)
[derived_petal_length] := 0.07017543859649121 (DOUBLE)
[derived_petal_width] := 0.04166666666666667 (DOUBLE)

[BackPropagationNetwork]
Value of neural input [0] is [0.222].
Value of neural input [1] is [0.682].
Value of neural input [2] is [0.07].
Value of neural input [3] is [0.042].
Value of hidden layer neuron [4] is [-1].
Value of hidden layer neuron [5] is [0.955].
Value of hidden layer neuron [6] is [0.996].
Value of hidden layer neuron [7] is [-0.886].
Value of hidden layer neuron [8] is [0.397].
Value of hidden layer neuron [9] is [-0.541].
Value of hidden layer neuron [10] is [-0.345].
Value of output neuron [11] in the last neural layer is [1].
Value of output neuron [12] in the last neural layer is [0].
Value of output neuron [13] in the last neural layer is [0].

[Output]
The predicted value of segment model [2] is [Iris-setosa (STRING)]


Process segment model [3]:
The predicate of segment model [3] evaluates [True]

[MiningSchema]
[sepal_length] := 5.1 (DOUBLE)
[sepal_width] := 3.5 (DOUBLE)
[petal_length] := 1.4 (DOUBLE)
[petal_width] := 0.2 (DOUBLE)

[LocalTransformations]
[derived_sepal_length] := 0.22222222222222213 (DOUBLE)
[derived_sepal_width] := 0.6818181818181818 (DOUBLE)
[derived_petal_length] := 0.07017543859649121 (DOUBLE)
[derived_petal_width] := 0.04166666666666667 (DOUBLE)

[Regression]
Processing [RegressionTable] [targetCategory: Iris-versicolor (STRING)]:
Applied [Intercept], the value is [-14.897].
Applied [NumericPredictor] [coefficient: 61.867, exponent: 1] on field(s) [derived_sepal_length], the value is [13.748].
Applied [NumericPredictor] [coefficient: -137.017, exponent: 1] on field(s) [derived_sepal_width], the value is [-93.421].
Applied [NumericPredictor] [coefficient: 90.432, exponent: 1] on field(s) [derived_petal_length], the value is [6.346].
Applied [NumericPredictor] [coefficient: 11.529, exponent: 1] on field(s) [derived_petal_width], the value is [0.48].

Processing [RegressionTable] [targetCategory: Iris-virginica (STRING)]:
Applied [Intercept], the value is [-202.201].
Applied [NumericPredictor] [coefficient: -120.94, exponent: 1] on field(s) [derived_sepal_length], the value is [-26.875].
Applied [NumericPredictor] [coefficient: -129.401, exponent: 1] on field(s) [derived_sepal_width], the value is [-88.228].
Applied [NumericPredictor] [coefficient: 284.914, exponent: 1] on field(s) [derived_petal_length], the value is [19.994].
Applied [NumericPredictor] [coefficient: 251.754, exponent: 1] on field(s) [derived_petal_width], the value is [10.49].

Processing [RegressionTable] [targetCategory: Iris-setosa (STRING)]:
Applied [Intercept], the value is [0].

The predicted value of the regression table with category [Iris-versicolor (STRING)] is [-87.743]. Value after normalization is [0].
The predicted value of the regression table with category [Iris-virginica (STRING)] is [-286.82]. Value after normalization is [0].
The predicted value of the regression table with category [Iris-setosa (STRING)] is [0]. Value after normalization is [1].

[Output]
The predicted value of segment model [3] is [Iris-setosa (STRING)]


[Output]
The [predictedValue] is [Iris-setosa (STRING)]
[class] := Iris-setosa (STRING)
The [probability] of [Iris-setosa (STRING)] is [1.0 (DOUBLE)]
[Probability_setosa] := 1.0 (DOUBLE)
The [probability] of [Iris-versicolor (STRING)] is [0.0 (DOUBLE)]
[Probability_versicolor] := 0.0 (DOUBLE)
The [probability] of [Iris-virginica (STRING)] is [0.0 (DOUBLE)]
[Probability_virginica] := 0.0 (DOUBLE)

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/apply/Iris_NN/explain?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/apply/dummy/explain?record=%7B%22petal_length%22:%221.4%22,%22petal_width%22:%220.2%22,%22sepal_length%22:%225.1%22,%22sepal_width%22:%223.5%22%7D" \
  --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

Example Request

500 - Internal server Error

curl --request GET "{{url}}/service/zementis/apply/Iris_NN/explain?record=%7B" --header "Authorization: {{auth}}"

Example Response

500 - Internal server Error

{
  "timestamp": 1554299924722,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "com.fasterxml.jackson.core.io.JsonEOFException",
  "message": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: {; line: 1, column: 1])\n at [Source: {; line: 1, column: 3]",
  "path": "/apply/Iris_ME_Classification/explain"
}

POST - Apply PMML model to multiple records

{{url}}/service/zementis/apply/{{model_name}}

Apply a PMML model to multiple records. This provides two kinds of operations. Generally, if a predictive model without binary type input is applied, this will be a batch ‘apply’ operation that streams multiple input records to Zementis microservice. Zementis microservice will automatically detect CSV (Comma Separated Value) or JSON records formatted input and stream results back in the same format unless otherwise specified in the Accept request header parameter with text/csv or application/json values. Compressing input data with ZIP will result in the same compression method for the returned output stream. In such a case, compression handling is implicit and the content within the compressed file (i.e. JSON or CSV) is handled via Accept request header parameter.

Note that if the records are specified in a file then the size of the uploaded file should not exceed 500 MB.

If a predictive model with a binary type input is applied, this will be a single ‘apply’ operation that processes a single binary source as input to Zementis Server.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data
Accept	optional header parameter for explicitly specifying text/csv or application/json output format

PARAMS
file (file)	data file in CSV with header format or as JSON array [Record]. Only applicable when Content-Type is multipart/form-data
model_name (string)	required path variable for the name of the model to be applied
maxThreads	optional query parameter for specifying the maximum number of concurrent threads (default value is twice the number of processor cores). No impact if a predictive model with a binary type input was applied
maxRecordsPerThread	optional query parameter for specifying the maximum number of records processed by a thread in batch (default value is 5000). No impact if a predictive model with a binary type input was applied

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/apply/Iris_ME_Classification " \
     --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --header "Accept: text/csv" \
     --form "file=@Iris_ME_Classification.csv"

Example Response

200 - OK

class,Probability_setosa,Probability_versicolor,Probability_virginica
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-setosa,1.0,0.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.2,0.8,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,0.8,0.2
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-virginica,0.0,0.3,0.7
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,0.5,0.5
Iris-versicolor,0.0,0.8,0.2
Iris-versicolor,0.2,0.8,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-versicolor,0.0,1.0,0.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-versicolor,0.0,0.5,0.5
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-versicolor,0.0,0.7,0.3
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-versicolor,0.0,0.5,0.5
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0
Iris-virginica,0.0,0.0,1.0

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/apply/Iris_ME_Classification " \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Invalid.csv"

Example Response

400 - Bad Request

{
  "errors": [
    "Failed to parse input at record 1."
  ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/apply/Iris_ME_Classification " \
     --header "Content-Type: multipart/form-data" --header "Accept: text/csv" \
     --form "file=@Iris_ME_Classification.csv"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request POST "{{url}}/service/zementis/apply/dummy " \
  --header "Authorization: {{auth}}" \
  --header "Content-Type: multipart/form-data" \
  --header "Accept: application/json" \
  --form "file=@dummy.csv"

Example Response

404 - Not Found

{
  "errors": [
    "Model 'dummy' not found."
  ]
}

POST - Apply PMML model group to multiple records

{{url}}/service/zementis/pmml/apply-group/{{group_name}}

Apply a PMML model group to multiple records. Note that the size of the uploaded file should not exceed 500 MB. If the operation is successful, the response will always be in ‘application/zip’ format whereas in case of errors it will be ‘application/json’. Compressing input data with ZIP will result in the same compression method for the returned output stream.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file (file)	data file in CSV with header format. Only applicable when Content-Type is multipart/form-data
group_name (string)	required path variable for the name of the model group to be applied
applyAllModels (Boolean)	optional parameter used to specify if the data needs to be processed against all the models in the group and not just the primary model (default is false)
maxThreads	optional query parameter for specifying the maximum number of concurrent threads (default value is twice the number of processor cores)
maxRecordsPerThread	optional query parameter for specifying the maximum number of records processed by a thread in batch (default value is 5000)

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification?applyAllModels=true" \
     --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Iris_NN.csv"

Example Response

200 - OK

Zip file

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification" \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Invalid.csv"

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid CSV File : Double quote character found in value not surrounded by double quotes (line 1, position 15)"
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification" \
     --header "Content-Type: multipart/form-data" --form "file=@Iris_NN.csv"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request POST "{{url}}/service/zementis/pmml/apply-group/dummy" \
  --header "Authorization: {{auth}}" \
  --header "Content-Type: multipart/form-data" \
  --form "file=@dummy.csv"

Example Response

404 - Not Found

{
    "errors": [
        "Model group with name 'dummy' does not exist."
    ]
}

POST - Apply PMML model group to multiple records and show details

{{url}}/service/zementis/pmml/apply-group/{{group_name}}/detail

Apply a PMML model group to multiple records and show the details. Details include the computed outputs alongside the expected outputs if the expected outputs are part of the input data. It also includes the information of the input record corresponding to the computed output.

Note that the size of the uploaded file should not exceed 500 MB. If the operation is successful, the response will always be in ‘application/zip’ format whereas in case of errors it will be ‘application/json’. Compressing input data with ZIP will result in the same compression method for the returned output stream.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file (file)	data file in CSV with header format. Only applicable when Content-Type is multipart/form-data
group_name (string)	required path variable for the name of the model group to be applied
applyAllModels (Boolean)	optional parameter used to specify if the data needs to be processed against all the models in the group and not just the primary model (default is false)
matchScore (Boolean)	optional parameter used to specify if score matching should be performed. If score matching is performed, the expected and actual outputs will be compared and a Match column will be added to the outputs (default is false)
maxThreads	optional query parameter for specifying the maximum number of concurrent threads (default value is twice the number of processor cores)
maxRecordsPerThread	optional query parameter for specifying the maximum number of records processed by a thread in batch (default value is 5000)

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification/detail?applyAllModels=true&matchScore=true" \
     --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Iris_NN.csv"

Example Response

200 - OK

Zip file

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification/detail" \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Invalid.csv"

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid CSV File : Double quote character found in value not surrounded by double quotes (line 1, position 15)"
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/pmml/apply-group/IrisClassification/detail" \
     --header "Content-Type: multipart/form-data" --form "file=@Iris_NN.csv"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request POST "{{url}}/service/zementis/pmml/apply-group/dummy/detail" \
  --header "Authorization: {{auth}}" \
  --header "Content-Type: multipart/form-data" \
  --form "file=@dummy.csv"

Example Response

404 - Not Found

{
    "errors": [
        "Model group with name 'dummy' does not exist."
    ]
}

POST - Apply ONNX model to multiple records

{{url}}/service/zementis/onnx/apply/{{model_name}}

Apply an ONNX model to multiple records. Note that the size of the uploaded file should not exceed 500 MB and the input should be in JSON format.

Info

An active subscription of the Onnx microservice is required to leverage this API.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file (file)	data file in JSON format.
model_name (string)	required path variable for the name of the model to be applied

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/onnx/apply/resnet50" \
     --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@data.json"

data.json
{"input_1": [[[[110.06099700927734, 87.22100067138672, 62.31999969482422], [109.06099700927734, 86.22100067138672, 61.31999969482422], [111.06099700927734, 88.22100067138672, 63.31999969482422], [109.06099700927734, 86.22100067138672, 61.31999969482422], [109.06099700927734, 86.22100067138672, 61.31999969482422], [110.06099700927734, 87.22100067138672, 62.31999969482422], [110.06099700927734, 87.22100067138672, 62.31999969482422], [110.06099700927734, 87.22100067138672, 62.31999969482422], [110.06099700927734, 87.22100067138672, 62.31999969482422] ....}

Example Response

200 - OK

{
  "fc1000": [
    [
      3.0144642551022116E-6,
      1.412209087447991E-7,
      1.0779075410027872E-6,
      6.253312108128739E-7,
      1.796032051970542E-6,
      4.547297066892497E-6,
      2.2596604765112716E-7,
      3.472631249223923E-7,
      2.402981920113234E-7,
      2.107677937601693E-5,
      4.451037582953177E-8,
      3.897369893479663E-8,
      1.407707230782762E-7,
      2.591128520634811E-7,
      5.4826028161869544E-8,
      2.6079766257680603E-7,
      9.300482162188928E-8,
      3.1244994147527905E-7,
	  .....
    ]
  ]
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/onnx/apply/resnet50" \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@Invalid.json"

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid json format."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/onnx/apply/resnet50" \
     --header "Content-Type: multipart/form-data" --form "file=@data.json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --location --request POST "{{url}}/service/zementis/onnx/apply/dummy" \
  --header "Authorization: {{auth}}" \
  --header "Content-Type: multipart/form-data" \
  --form "file=@data.json"

Example Response

404 - Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

POST - Apply ONNX pipeline to input data

{{url}}/service/zementis/onnx/apply-pipeline/{{pipeline_name}}

Apply an ONNX pipeline to input data. Note that the size of the uploaded file should not exceed 500 MB.

The ONNX format doesn’t provide a representation for pre-processing steps. For deep learning models like CNN which deal with image data, the necessary pre-processing steps must be applied to the images and the result should be sent in JSON format as an input to the ONNX model. In pipeline, the input data can be of any format as long as the pre-processing script of the pipeline can process it. However, if there is no pre-processing step in the pipeline then the input data must be in JSON format.

Info

An active subscription of the Onnx microservice is required to leverage this API.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with two accepted values: application/octet-stream or multipart/form-data

PARAMS
file (file)	data file
pipeline_name (string)	required path variable for the name of the pipeline to be applied

Example Request

200 - OK

curl --request POST "{{url}}/service/zementis/onnx/apply-pipeline/DetectFabricOrientation" \
     --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@data.jpeg"

Example Response

200 - OK

{
    "fabricFace": "front",
    "probability": "88.22"
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/onnx/apply-pipeline/DetectFabricOrientation" \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@"

Example Response

400 - Bad Request

{
    "errors": [
        "Empty input stream."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/onnx/apply-pipeline/DetectFabricOrientation" \
     --header "Content-Type: multipart/form-data" --form "file=@data.jpeg"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request POST "{{url}}/service/zementis/onnx/apply-pipeline/dummy" \
  --header "Authorization: {{auth}}" --header "Content-Type: multipart/form-data" --form "file=@data.jpeg"

Example Response

404 - Not Found

{
    "errors": [
        "Pipeline 'dummy' not found."
    ]
}

Time series

Operations for time series data/model.

Info

An active subscription of the Nyoka microservice is required to leverage the time series APIs.

Domain model

TimeSeries

Name	Type	Description
series	array	The time series data specified as an array of values representing multiple observations.
observationInterval	TimePeriod	The time interval between consecutive observations.
startDate	DateTime	The timestamp of the first observation in UTC format.
seasonality	TimePeriod	Optional parameter to specify the seasonal period in the data, if present.

TimePeriod

Name	Type	Description
timeUnit	ChronoUnit	The value must be a valid ChronoUnit – “SECONDS”, “MINUTES”, “HOURS”, “DAYS”, “MONTHS”, “YEARS” etc.
periodLength	Number	Length of the period.

POST – Generate time series model using time series data

{{url}}/service/zementis/train/timeseries

Upload the time series data to generate a model. This is an asynchronous call which returns a status URL that can be used to check the status of model creation.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with value application/json

PARAMS
autoDeploy (Boolean)	optional parameter used to determine whether or not the model should be deployed automatically once it is generated, default is true

BODY

{
    "series": [<value1>, <value2>, ...., <valueN>],
    "observationInterval": {
       "timeUnit": "<timeUnit>",
        "periodLength": <periodLength>
    },
    "startDate": "<startDate>",
    "seasonality": {
        "timeUnit": "<timeUnit>",
        "periodLength": <periodLength>
    }
}

Example Request

202 - ACCEPTED

curl --request POST "{{url}}/service/zementis/train/timeseries?autoDeploy=true --header "Authorization: {{auth}}" \
	--header "Content-Type: application/json"

{
    "series": [
       112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118, 115,
       126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140, 145, 150,
       178, 163, 172, 178, 199, 199, 184, 162, 146, 166, 171, 180, 193,
       181, 183, 218, 230, 242, 209, 191, 172, 194, 196, 196, 236, 235,
       229, 243, 264, 272, 237, 211, 180, 201, 204, 188, 235, 227, 234,
       264, 302, 293, 259, 229, 203, 229, 242, 233, 267, 269, 270, 315,
       364, 347, 312, 274, 237, 278, 284, 277, 317, 313, 318, 374, 413,
       405, 355, 306, 271, 306, 315, 301, 356, 348, 355, 422, 465, 467,
       404, 347, 305, 336, 340, 318, 362, 348, 363, 435, 491, 505, 404,
       359, 310, 337, 360, 342, 406, 396, 420, 472, 548, 559, 463, 407,
       362, 405, 417, 391, 419, 461, 472, 535, 622, 606, 508, 461, 390,
       432
    ],
    "observationInterval": {
       "timeUnit": "MONTHS",
       "periodLength": 1
    },
    "startDate": "2019-01-01T00:00:00+05:30",
    "seasonality": {
        "timeUnit": "YEARS",
        "periodLength": 1
    }
}

Example Response

202 - ACCEPTED

{
	"modelName": "Timeseries_19-10-2020_14-23-00_jJgQK",
	"statusUrl": "/service/zementis/train/timeseries/Timeseries_19-10-2020_14-23-00_jJgQK/status"
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/train/timeseries" --header "Authorization: {{auth}}" \
	--header "Content-Type: application/json"

{
    "series": [
       112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118, 115,
       126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140, 145, 150,
       178, 163, 172, 178, 199, 199, 184, 162, 146, 166, 171, 180, 193,
       181, 183, 218, 230, 242, 209, 191, 172, 194, 196, 196, 236, 235,
       229, 243, 264, 272, 237, 211, 180, 201, 204, 188, 235, 227, 234,
       264, 302, 293, 259, 229, 203, 229, 242, 233, 267, 269, 270, 315,
       364, 347, 312, 274, 237, 278, 284, 277, 317, 313, 318, 374, 413,
       405, 355, 306, 271, 306, 315, 301, 356, 348, 355, 422, 465, 467,
       404, 347, 305, 336, 340, 318, 362, 348, 363, 435, 491, 505, 404,
       359, 310, 337, 360, 342, 406, 396, 420, 472, 548, 559, 463, 407,
       362, 405, 417, 391, 419, 461, 472, 535, 622, 606, 508, 461, 390,
       432
    ],
    "observationInterval": {
       "timeUnit": "MONTHS",
       "periodLength": 1
    },
    "startDate": "2019-01-01T00:00:00+05:3012",
    "seasonality": {
        "timeUnit": "YEARS",
        "periodLength": 1
    }
}

Example Response

400 - Bad Request

{
    "errors": [
        "'startDate' must be specified in yyyy-MM-dd'T'HH:mm:ss.SSSXXX format."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/train/timeseries" --header "Content-Type: application/json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET – Get status of generation of the time series model

{{url}}/service/zementis/train/timeseries/{{model_name}}/status

Get the status of the generation of a specific time series model. The status can either be IN_PROGRESS, SUCCESS or FAILURE.
If the status is FAILURE, the errorMessage attribute in the response holds the reason for the failure.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for time series model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/train/timeseries/Timeseries_19-10-2020_14-23-00_jJgQK/status" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "status": "SUCCESS"
}

Example Request

401 – Unauthorized

curl --request GET "{{url}}/service/zementis/train/timeseries/Timeseries_19-10-2020_14-23-00_jJgQK/status"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 – Not Found

curl --request GET "{{url}}/service/zementis/train/timeseries/dummy/status" --header "Authorization: {{auth}}"

Example Response

404 – Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

GET – Get PMML source of the generated time series model

{{url}}/service/zementis/train/timeseries/{{model_name}}/pmml

Get the PMML file of the generated time series model.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for time series model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/train/timeseries/Timeseries_19-10-2020_14-23-00_jJgQK/pmml" --header "Authorization: {{auth}}"

Example Response

200 - OK

<?xml version="1.0" encoding="UTF-8"?>
<PMML xmlns="http://www.dmg.org/PMML-4_4" version="4.4">
    <Header copyright="Copyright (c) 2018 Software AG" description="State Space Model">
        <Application name="Nyoka" version="4.2.0"/>
        <Timestamp>2020-10-19 14:38:07.412179</Timestamp>
    </Header>
    <DataDictionary numberOfFields="2">
        <DataField name="value_0" optype="continuous" dataType="double"/>
        <DataField name="h" optype="continuous" dataType="integer"/>
    </DataDictionary>
    <TimeSeriesModel modelName="Timeseries_19-10-2020_14-23-00_jJgQK" functionName="timeSeries" bestFit="StateSpaceModel">...
...
...
...
</PMML>

Example Request

401 – Unauthorized

curl --request GET "{{url}}/service/zementis/train/timeseries/Timeseries_19-10-2020_14-23-00_jJgQK/pmml"

Example Response

401 - Unauthorised

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 – Not Found

curl --request GET "{{url}}/service/zementis/train/timeseries/dummy/pmml" --header "Authorization: {{auth}}"

Example Response

404 – Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

Matrix profile

Operations for matrix profile.

Info

An active subscription of the Nyoka microservice is required to leverage the matrix profile APIs.

GET – Generate matrix profile using historical time series data

{{url}}/service/zementis/matrixprofile

Get the matrix profile of a specific historical time series data.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ

HEADERS
Authorization	{{auth}}

PARAMS
windowSize (integer)	Optional query parameter to setup the size of the subsequence window size. The default subsequence window size is 5 if not provided. Note that: The window size must be less than or equal to the length of historical data that is retrieved according to the date range defined in `dateFrom` and `dateTo`. The window size must be greater than 2 when computing the z-normalized Euclidean distance. A windowSize=1 produces a standard deviation of zero. For windowSize=2, both the mean and standard deviation for any given subsequence are identical and hence the z-normalization for any sequence will either be [-1., 1.] or [1., -1.]. Thus, the z-normalized Euclidean distance will very likely be zero between any subsequence and its nearest neighbor assuming that the time series is large enough to contain both scenarios.
source (integer)	Required query parameter for source identifier
valueFragmentType (string)	Required query parameter for measurements based on fragment type
valueFragmentSeries (string)	Required query parameter for measurements based on fragment series
dateFrom (string)	Required query parameter for measurements from a start date
dateTo (string)	Required query parameter for measurements to an end date

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/matrixprofile?windowSize={{size}}&source={{id}}&valueFragmentType={{type}}&valueFragmentSeries={{series}}&dateFrom={{start}}&dateTo={{end}}" \
     --header "Authorization: {{auth}} \
     --header "Accept: application/json"

Example Response

200 - OK

{
  "time": [
    "2021-12-20T23:50:53.045Z",
    "2021-12-20T23:50:54.537Z",
    "2021-12-20T23:50:56.210Z",
    "2021-12-20T23:50:57.695Z",
    "2021-12-20T23:50:59.177Z",
    "2021-12-20T23:51:00.641Z",
    "2021-12-20T23:51:02.132Z",
    "2021-12-20T23:51:03.593Z",
    "2021-12-20T23:51:05.062Z",
    "2021-12-20T23:51:06.556Z",
    "2021-12-20T23:51:08.019Z",
    "2021-12-20T23:51:09.504Z",
    "2021-12-20T23:51:10.970Z",
    "2021-12-20T23:51:12.407Z",
    "2021-12-20T23:51:13.836Z",
    "2021-12-20T23:51:15.323Z",
    "2021-12-20T23:51:16.906Z",
    "2021-12-20T23:51:18.407Z"
  ],
  "matrix_profile": [
    0,
    0,
    0,
    "Infinity",
    0,
    0,
    0,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null
  ],
  "matrix_profile_index": [
    4,
    5,
    6,
    -1,
    0,
    1,
    2,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null
  ]
}

Info

The delta between the size of selected time series data (T) and generated matrix profile (mp) is shown as null values at the end of the matrix_profile. This delta occurs because of how sliding window (m) computation works. The size of matrix_profile is smaller than the size of historical time series data by windowSize.

size(mp) = size(T) - m + 1

Same delta applies to the size of matrix_profile_index.

Example Request

All the required parameters are not provided completely.

400 – Bad Request

curl --request GET "{{url}}/service/zementis/matrixprofile?source=110"

Example Response

400 – Bad Request

{
  "errors": [
    "Please provide ['valueFragmentType', 'valueFragmentSeries', 'dateFrom', 'dateTo'] in query parameters."
  ]
}

Example Request

The subsequence window size is larger than the length of historical time series data.

400 – Bad Request

curl --request GET "{{url}}/service/zementis/matrixprofile?source=110&valueFragmentType=c8y_Temperature&valueFragmentSeries=T&dateFrom=2021-12-20&dateTo=2021-12-21&windowSize=5000000"

Example Response

400 – Bad Request

{
  "errors": [
    "The window size must be less than or equal to the length of historical data. Please reduce window size or increase the date range to retrieve more historical data."
  ]
}

Clustering

Operations for identifying clusters in given data using clustering models.

Info

An active subscription of the Nyoka microservice is required to leverage the clustering APIs.

POST – Generate clustering model based on multiple time series

{{url}}/service/zementis/train/clustering

Upload multiple time series data to generate a clustering model. This is an asynchronous call which returns a status URL that can be used to check the status of model creation.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	required header parameter with value application/json

PARAMS
autoDeploy (Boolean)	optional parameter used to determine whether or not the model should be deployed automatically once it is generated, default is true

BODY

{
    "data": [
        <series1>:[<value1>, <value2>, ...., <valueN>],
        <series2>:[<value1>, <value2>, ...., <valueN>],
        <series3>:[<value1>, <value2>, ...., <valueN>],
        <series4>:[<value1>, <value2>, ...., <valueN>]
    ]
}

Example Request

202 - ACCEPTED

curl --request POST "{{url}}/service/zementis/train/clustering?autoDeploy=false" --header "Authorization: {{auth}}" \
	--header "Content-Type: application/json"

{
     "data": [
        "MAC000002": [ 1.945, 1.112, 0.6609999999999999, 0.23600000000000002, 0.20800000000000002, ... ],
        "MAC000003": [ 6.760999900000001, 6.884000099999999, 7.241000200000001, 6.3209999, 5.157000099999999, ... ],
        "MAC000004": [ 0.0, 0.175, 0.0, 0.0, 0.191, ... ],
        ...
    ]
}

Example Response

202 - ACCEPTED

{
    "modelName": "Clustering_19-10-2020_11-06-01_umGoj",
    "statusUrl": "/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj/status"
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/train/clustering" --header "Authorization: {{auth}}" \
	--header "Content-Type: application/json"

{
    "data": [
        "MAC000002": [ 1.945, 1.112, 0.6609999999999999, 0.23600000000000002, 0.20800000000000002, ... ],
        "MAC000003": [ 6.760999900000001, 6.884000099999999, 7.241000200000001, 6.3209999, 5.157000099999999, ... ],
        "MAC000004":   0.0, 0.175, 0.0, 0.0, 0.191, ... ],
        ...
}

Example Response

400 - Bad Request

{
    "errors": [
        "Invalid json format."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/train/clustering" --header "Content-Type: application/json"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET – Get status of generation of the clustering model

{{url}}/service/zementis/train/clustering/{{model_name}}/status

Get the status of generation of a specific clustering model. The status can either be IN_PROGRESS, SUCCESS or FAILURE.
If the status is FAILURE, the errorMessage attribute in the response holds the reason for the failure.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for clustering model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj/status" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "status": "SUCCESS"
}

Example Request

401 – Unauthorized

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj/status"

Example Response

401 - Unauthorised

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 – Not Found

curl --request GET "{{url}}/service/zementis/train/clustering/dummy/status" --header "Authorization: {{auth}}"

Example Response

404 – Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

GET – Get PMML source of the generated clustering model

{{url}}/service/zementis/train/clustering/{{model_name}}/pmml

Get the PMML file of the generated clustering model.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for clustering model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj/pmml" --header "Authorization: {{auth}}"

Example Response

200 - OK

<?xml version="1.0" encoding="UTF-8"?>
<PMML xmlns="http://www.dmg.org/PMML-4_4" version="4.4">
    <Header copyright="Copyright (c) 2018 Software AG" description="Default Description">
        <Application name="Nyoka" version="4.2.0"/>
        <Timestamp>2020-10-19 12:38:54.346416</Timestamp>
    </Header>
    <DataDictionary numberOfFields="168">
        <DataField name="X_0" optype="continuous" dataType="double"/>
        <DataField name="X_1" optype="continuous" dataType="double"/>
        <DataField name="X_2" optype="continuous" dataType="double"/>
        <DataField name="X_3" optype="continuous" dataType="double"/>
        <DataField name="X_4" optype="continuous" dataType="double"/>
        <DataField name="X_5" optype="continuous" dataType="double"/>
...
...
...
...
</PMML>

Example Request

401 – Unauthorized

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj/pmml"

Example Response

401 - Unauthorised

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 – Not Found

curl --request GET "{{url}}/service/zementis/train/clustering/dummy/pmml" --header "Authorization: {{auth}}"

Example Response

404 – Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

GET – Get cluster information

{{url}}/service/zementis/train/clustering/{{model_name}}

Get the information of clusters identified by the clustering model.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
model_name (string)	required path variable for clustering model name

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "numberOfClusters": 4,
    "clusters": [
        {
            "centroid": [ 0.33884722222222224, 0.41218055555555555, 0.5330694430555556, ... ],
            "members": [ "MAC000002", "MAC000003", "MAC000021", ... ]
        },
        {
            "centroid": [ 1.55143749375, 1.41018749375, 1.5678125, ... ],
            "members": [ "MAC000004", "MAC000008", "MAC000033", ... ]
        },
        {
            "centroid": [ 2.45056251875, 2.3903124937499998, 2.2459999999999996, ... ],
            "members": [ "MAC000009", "MAC000023", "MAC000051", ... ]
        },
        {
            "centroid": [ 6.81100004, 6.5565999999999995, 5.298800020000001, ... ],
            "members": [ "MAC000006", "MAC000007", "MAC000047", ... ]
        }
}

Example Request

401 – Unauthorized

curl --request GET "{{url}}/service/zementis/train/clustering/Clustering_19-10-2020_11-06-01_umGoj"

Example Response

401 - Unauthorised

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 – Not Found

curl --request GET "{{url}}/service/zementis/train/clustering/dummy" --header "Authorization: {{auth}}"

Example Response

404 – Not Found

{
    "errors": [
        "Model 'dummy' not found."
    ]
}

Jobs

Operations on jobs scheduled for processing device data.

Info

Currently, jobs can be scheduled using PMML models and model groups only. However, time series models must not be used for processing data in a scheduled manner.

Domain model

JobConfiguration

Name	Type	Description
jobName	String	Name of the job.
jobDescription	String	Description of the job.
groupOrDeviceId	Number	ID of the device or device group whose measurements will be processed when the job executes.
modelOrGroup	String	Name of the model or model group which will be used to process the device measurements.
applyAllModels	Boolean	Boolean value to specify if the data needs to be processed against all the models in a model group.
modelToDeviceMappings	Map	Map with the model’s inputs as the keys and the measurements as the corresponding values. These mappings ensure which measurement reading maps to which model input.
jobSchedule	JobSchedule	Information about when the job should be scheduled for executions.

JobSchedule

Name	Type	Description
frequency	String	Frequency of job execution. Can be either `periodic` or `once`.
cronExpression	String	CRON expression to specify the execution schedule for a periodic job. Follow http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html for more info on CRON.
dataFromPreviousNSeconds	Number	Number of seconds in the past from which data should be fetched for processing. The value must not exceed 86400 i.e. 24 hours.
timeZone	String	Time zone in which the periodic job should be scheduled.
scheduleAt	String	Datetime string in the future when the job should be scheduled.
dataFrom	String	Datetime string from the past which should be considered as the starting point for data to be fetched for processing.
dataTo	String	Datetime string from the past which should be considered as the ending point for data to be fetched for processing.

Info

For periodic frequency, cronExpression, dataFromPreviousNSeconds and timeZone fields are mandatory.
For once frequency, scheduleAt, dataFrom and dataTo fields are mandatory and should adhere to the ISO-8601 date-time format
i.e. “yyyy-MM-dd’T’HH:mm:ss.SSSXXX”, for instance “2019-12-30T22:59:50.235+05:30”.
The difference between dataFrom and dateTo must not exceed 24 hours.

POST - Create new job

{{url}}/service/zementis/job

Create a new job for scheduled data processing.

On creation, a jobId is automatically assigned to the job and jobCreationDate will also be added to the response.

Note that if the job name or description contain any unsafe characters, all such characters will be converted to underscore automatically.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}
Content-Type	application/json

BODY

{
   "jobName": "<jobName>",
   "jobDescription": "<jobDescription>",
   "groupOrDeviceId" : <groupOrDeviceId>,
   "modelOrGroup": "<modelOrGroup>",
   "applyAllModels": <true | false>,
   "modelToDeviceMappings": {
      "<Model_Input1>": "<measurementType>.<seriesName1>.value",
      "<Model_Input2>": "<measurementType>.<seriesName2>.value",
      "<Model_Input3>": "<measurementType>.<seriesName3>.value"
   },
   "jobSchedule": {
      "frequency": "<periodic | once>",
      "cronExpression": "<cronExpression>",
      "dataFromPreviousNSeconds": <dataFromPreviousNSeconds>,
      "timeZone":"<timeZone>",
      "scheduleAt": "<scheduleAt>",
      "dataFrom": "<dataFrom>",
      "dataTo": "<dataTo>"
   }
}

Example Request

201 - Created

curl --request POST "{{url}}/service/zementis/job" --header "Authorization: {{auth}}"

{
    "jobName": "ActivityDetectionJob",
    "jobDescription": "Detect activities",
    "modelOrGroup": "DecisionTreeClassifier",
    "groupOrDeviceId": 15889549,
    "applyAllModels": false,
    "modelToDeviceMappings": {
        "accelerationY": "c8y_Acceleration.accelerationY.value",
        "accelerationX": "c8y_Acceleration.accelerationX.value",
        "accelerationZ": "c8y_Acceleration.accelerationZ.value"
    },
    "jobSchedule": {
        "frequency": "once",
        "scheduleAt": "2020-03-18T17:42:00.000Z",
        "dataFrom": "2020-02-26T10:20:00.000Z",
        "dataTo": "2020-02-27T10:20:00.000Z"
    }
}

Example Response

201 - Created

{
    "jobId": 15898918,
    "jobName": "ActivityDetectionJob",
    "jobDescription": "Detect activities",
    "jobCreationDate": "2020-03-18T17:41:25.901Z",
    "modelOrGroup": "DecisionTreeClassifier",
    "applyAllModels": false,
    "groupOrDeviceId": 15889549,
    "modelToDeviceMappings": {
       "accelerationY": "c8y_Acceleration.accelerationY.value",
       "accelerationX": "c8y_Acceleration.accelerationX.value",
       "accelerationZ": "c8y_Acceleration.accelerationZ.value"
    },
    "jobSchedule": {
       "frequency": "once",
       "cronExpression": "",
       "timeZone": "Asia/Kolkata",
       "dataFromPreviousNSeconds": 0,
       "scheduleAt": "2020-03-18T17:42:00.000Z",
       "dataFrom": "2020-02-26T10:20:00.000Z",
       "dataTo": "2020-02-27T10:20:00.000Z"
    }
}

Example Request

400 - Bad Request

curl --request POST "{{url}}/service/zementis/job" --header "Authorization: {{auth}}"

{
    "jobName": "ActivityDetectionJob",
    "jobDescription": "Detect activities",
    "modelOrGroup": "DecisionTreeClassifier",
    "groupOrDeviceId": 15889549,
    "applyAllModels":false,
    "modelToDeviceMappings": {
        "accelerationY": "c8y_Acceleration.accelerationY.value",
        "accelerationX": "c8y_Acceleration.accelerationX.value",
        "accelerationZ": "c8y_Acceleration.accelerationZ.value"
    },
    "jobSchedule": {
        "frequency": "invalid",
        "scheduleAt": "2020-04-18T17:42:00.000Z",
        "dataFrom": "2020-02-26T10:20:00.000Z",
        "dataTo": "2020-02-27T10:20:00.000Z"
    }
}

Example Response

400 - Bad Request

{
    "errors": [
        "frequency can be either once or periodic."
    ]
}

Example Request

401 - Unauthorized

curl --request POST "{{url}}/service/zementis/job"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request POST "{{url}}/service/zementis/job" --header "Authorization: {{auth}}"

{
    "jobName": "ActivityDetectionJob",
    "jobDescription": "Detect activities",
    "modelOrGroup": "DecisionTreeClassifier",
    "groupOrDeviceId": 123456,
    "applyAllModels":false,
    "modelToDeviceMappings": {
        "accelerationY": "c8y_Acceleration.accelerationY.value",
        "accelerationX": "c8y_Acceleration.accelerationX.value",
        "accelerationZ": "c8y_Acceleration.accelerationZ.value"
    },
    "jobSchedule": {
        "frequency": "once",
        "scheduleAt": "2020-04-18T17:42:00.000Z",
        "dataFrom": "2020-02-26T10:20:00.000Z",
        "dataTo": "2020-02-27T10:20:00.000Z"
    }
}

Example Response

404 - Not Found

{
    "errors": [
        "Device or group with id 123456 does not exist or it is invalid"
    ]
}

GET - List available jobs

{{url}}/service/zementis/jobs

Retrieves all the available jobs. Use the jobId of these jobs as identifiers for all operations requiring the {{jobId}} path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
withTotalPages (Boolean)	optional request parameter for displaying total pages; default value is true.
currentPage (Number)	optional request parameter for navigating to a particular page; default value is 1.
pageSize (Number)	optional request parameter for specifying number of entries to be shown in a single page; default value is 5.

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/jobs" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "next": null,
    "prev": null,
    "statistics": {
      "currentPage": 1,
      "totalPages": 1,
      "pageSize": 5
    },
    "jobs": [
      {
        "jobId": 15898918,
        "jobName": "ActivityDetectionJob",
        "jobDescription": "Detect activities",
        "jobCreationDate": "2020-03-18T17:41:25.901Z",
        "modelOrGroup": "DecisionTreeClassifier",
        "applyAllModels": false,
        "groupOrDeviceId": 15889549,
        "modelToDeviceMappings": {
            "accelerationY": "c8y_Acceleration.accelerationY.value",
            "accelerationX": "c8y_Acceleration.accelerationX.value",
            "accelerationZ": "c8y_Acceleration.accelerationZ.value"
        },
        "jobSchedule": {
            "frequency": "once",
            "cronExpression": "",
            "timeZone": "Asia/Kolkata",
            "dataFromPreviousNSeconds": 0,
            "scheduleAt": "2020-03-18T17:42:00.000Z",
            "dataFrom": "2020-02-26T10:20:00.000Z",
            "dataTo": "2020-02-27T10:20:00.000Z"
        }
      },
      {
        "jobId": 15896925,
        "jobName": "AnomalyDetectionJob",
        "jobDescription": "Job involving many versions of Isolation Forest model to detect anomalies in devices",
        "jobCreationDate": "2020-02-27T14:23:16.557Z",
        "modelOrGroup": "AnomalyDetectionModels",
        "applyAllModels": true,
        "groupOrDeviceId": 15896385,
        "modelToDeviceMappings": {
            "rssi": "c8y_SignalStrengthWifi.rssi.value",
            "accelerationY": "c8y_Acceleration.accelerationY.value",
            "accelerationX": "c8y_Acceleration.accelerationX.value",
            "accelerationZ": "c8y_Acceleration.accelerationZ.value",
            "air_pressure": "c8y_Gyroscope.gyroX.value",
            "gyroX": "c8y_Gyroscope.gyroX.value",
            "gyroY": "c8y_Gyroscope.gyroY.value",
            "gyroZ": "c8y_Gyroscope.gyroZ.value",
            "lux": "c8y_Luxometer.lux.value",
            "compassX": "c8y_Compass.compassX.value",
            "compassY": "c8y_Compass.compassY.value",
            "compassZ": "c8y_Compass.compassZ.value"
        },
        "jobSchedule": {
            "frequency": "once",
            "cronExpression": "",
            "timeZone": "Asia/Calcutta",
            "dataFromPreviousNSeconds": 0,
            "scheduleAt": "2020-02-27T14:24:00.000Z",
            "dataFrom": "2020-02-26T12:30:00.000Z",
            "dataTo": "2020-02-27T12:30:00.000Z"
        }
      }
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/jobs"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

GET - Get job information

{{url}}/service/zementis/job/{{jobId}}

Get information about a specific job.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/job/15896925" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "jobId": 15896925,
    "jobName": "AnomalyDetectionJob",
    "jobDescription": "Job involving many versions of Isolation Forest model to detect anomalies in devices",
    "jobCreationDate": "2020-02-27T14:23:16.557Z",
    "modelOrGroup": "AnomalyDetectionModels",
    "applyAllModels": true,
    "groupOrDeviceId": 15896385,
    "modelToDeviceMappings": {
        "rssi": "c8y_SignalStrengthWifi.rssi.value",
        "accelerationY": "c8y_Acceleration.accelerationY.value",
        "accelerationX": "c8y_Acceleration.accelerationX.value",
        "accelerationZ": "c8y_Acceleration.accelerationZ.value",
        "air_pressure": "c8y_Gyroscope.gyroX.value",
        "gyroX": "c8y_Gyroscope.gyroX.value",
        "gyroY": "c8y_Gyroscope.gyroY.value",
        "gyroZ": "c8y_Gyroscope.gyroZ.value",
        "lux": "c8y_Luxometer.lux.value",
        "compassX": "c8y_Compass.compassX.value",
        "compassY": "c8y_Compass.compassY.value",
        "compassZ": "c8y_Compass.compassZ.value"
    },
    "jobSchedule": {
        "frequency": "once",
        "cronExpression": "",
        "timeZone": "Asia/Calcutta",
        "dataFromPreviousNSeconds": 0,
        "scheduleAt": "2020-02-27T14:24:00.000Z",
        "dataFrom": "2020-02-26T12:30:00.000Z",
        "dataTo": "2020-02-27T12:30:00.000Z"
    }
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/job/15896925"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/job/000000" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Zementis job ID '00000' not found."
    ]
}

GET - Get job status

{{url}}/service/zementis/job/{{jobId}}/status

Get status and execution duration of a specific job. If there are no ongoing executions, then the job’s last execution status and duration will be fetched.

Note that the unit of jobExecutionDuration is milliseconds.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/job/15896925/status" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "jobExecutionStatus": "Success",
    "jobExecutionDuration": "8930"
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/job/15896925/status"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/job/000000/status" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Zementis job ID '00000' not found."
    ]
}

GET - Job execution history

{{url}}/service/zementis/job/{{jobId}}/history

Get execution history of a particular job. Lists all executions of that specific job. Use the jobExecutionNumber of these executions as identifiers for all operations requiring the {{executionId}} path variable.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID
withTotalPages (Boolean)	optional request paramter for displaying total pages; default value is false.
currentPage (Number)	optional request parameter for navigating to a particular page; default value is 1.
pageSize (Number)	optional request parameter for specifying number of entries to be shown in a single page; default value is 5.

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/job/15896925/history?withTotalPages=false" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "next": "/service/zementis/job/15896925/history?pageSize=5&currentPage=2",
    "prev": null,
    "statistics": {
        "currentPage": 1,
        "totalPages": null,
        "pageSize": 5
    },
    "jobExecutions": [
        {
            "jobId": 15896925,
            "jobExecutionNumber": 1,
            "isExecutionForDeviceGroup": true,
            "jobExecutionStartTime": "2020-02-27T14:24:00Z",
            "jobExecutionEndTime": "2020-02-27T14:24:08.930Z",
            "jobExecutionDuration": "8930",
            "jobExecutionStatus": "Success",
            "jobExecutionStatusMessage": []
        }
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/job/15896925/history"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request PUT "{{url}}/service/zementis/job/00000/history" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Zementis job ID '00000' not found."
    ]
}

GET - Job execution detail

{{url}}/service/zementis/job/{{jobId}}/history/{{executionId}}

Get details of a specific job execution.

Note that the unit of jobExecutionDuration is milliseconds.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID
executionId (string)	required path variable for execution ID

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/job/15896925/history/1" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "jobId": 15896925,
    "jobExecutionNumber": 1,
    "isExecutionForDeviceGroup": true,
    "jobExecutionStartTime": "2020-02-27T14:24:00Z",
    "jobExecutionEndTime": "2020-02-27T14:24:08.930Z",
    "jobExecutionDuration": "8930",
    "jobExecutionStatus": "Success",
    "jobExecutionStatusMessage": []
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/job/15896925/history/1"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/job/15896925/history/0" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Job Execution number 0 does not exist."
    ]
}

GET - Job execution results

{{url}}/service/zementis/job/{{jobId}}/history/{{executionId}}/inferences

Get the results/inferences generated in a single job execution. These inferences are the predictions of the machine learning model against the data from the associated device/device group.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_READ or ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID
executionId (string)	required path variable for execution ID
withTotalPages (Boolean)	optional request parameter for displaying total pages; default value is false.
currentPage (Number)	optional request parameter for navigating to a particular page; default value is 1.

Example Request

200 - OK

curl --request GET "{{url}}/service/zementis/job/15896925/history/1/inferences" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "next": "/service/zementis/job/15896915/history/1/inferences?currentPage=2",
    "prev": null,
    "statistics": {
        "currentPage": 1,
        "totalPages": null,
        "numberOfDevices": 2,
        "numberOfModels": 4
    },
    "inferenceCollection": [
        {
            "recordCollection": [
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525916, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038523208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.968584665454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForest"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525918, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709031523208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.962584665454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV2"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525816, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038323208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.969584645454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV3"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638526916, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038523208243, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.961584665424545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV4"
              }				
            ],
            "deviceId": 103030,
            "recordSize": 2000
        },
        {
            "recordCollection": [
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525916, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038523208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.968584665454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForest"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525918, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709031523208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.962584665454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV2"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638525816, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038323208043, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.969584645454545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV3"
              },
              {
                 "outputRecords": {
                    "normalizedAnomalyScore": [0.30919784638526916, 0.5981812541231656, 0.36394405330406093, 0.36394405330406093, 0.5981812541231656, ...],
                    "decisionFunction": [-0.30709038523208243, -0.237037401162047, -0.277037401162047, -0.277037401162047, -0.22561825856400746, ...],
                    "rawAnomalyScore": [4.68, 8.961584665424545, 5.52, 5.52, 9.205437462877498, ...],
                    "outlier": [false, true, false, false, true, ...],
                    "timestamp_15896925": ["2020-02-27T10:05:23.664Z", "2020-02-27T10:05:23.896Z", "2020-02-27T10:05:24.092Z", "2020-02-27T10:05:24.404Z", "2020-02-27T10:05:24.635Z", ...]
                 },
                 "modelName": "IsolationForestV4"
              }				
            ],
            "deviceId": 107742,
            "recordSize": 1500
        }
    ]
}

Example Request

401 - Unauthorized

curl --request GET "{{url}}/service/zementis/job/15896925/history/1/inferences"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request GET "{{url}}/service/zementis/job/15896925/history/0/inferences" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Job Execution number 0 does not exist."
    ]
}

DEL - Remove job

{{url}}/service/zementis/job/{{jobId}}

Remove the specified job and list the remaining jobs, if any.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

PARAMS
jobId (string)	required path variable for job ID

Example Request

200 - OK

curl --request DELETE "{{url}}/service/zementis/job/15898918" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "next": null,
    "prev": null,
    "statistics": {
        "currentPage": 1,
        "totalPages": 1,
        "pageSize": 5
    },
    "jobs": [
       {
           "jobId": 15896925,
           "jobName": "AnomalyDetectionJob",
           "jobDescription": "Job involving many versions of Isolation Forest model to detect anomalies in devices",
           "jobCreationDate": "2020-02-27T14:23:16.557Z",
           "modelOrGroup": "AnomalyDetectionModels",
           "applyAllModels": true,
           "groupOrDeviceId": 15896385,
           "modelToDeviceMappings": {
           	  "rssi": "c8y_SignalStrengthWifi.rssi.value",
           	  "accelerationY": "c8y_Acceleration.accelerationY.value",
           	  "accelerationX": "c8y_Acceleration.accelerationX.value",
           	  "accelerationZ": "c8y_Acceleration.accelerationZ.value",
           	  "air_pressure": "c8y_Gyroscope.gyroX.value",
           	  "gyroX": "c8y_Gyroscope.gyroX.value",
           	  "gyroY": "c8y_Gyroscope.gyroY.value",
           	  "gyroZ": "c8y_Gyroscope.gyroZ.value",
           	  "lux": "c8y_Luxometer.lux.value",
           	  "compassX": "c8y_Compass.compassX.value",
           	  "compassY": "c8y_Compass.compassY.value",
           	  "compassZ": "c8y_Compass.compassZ.value"
           },
           "jobSchedule": {
           	  "frequency": "once",
           	  "cronExpression": "",
           	  "timeZone": "Asia/Calcutta",
           	  "dataFromPreviousNSeconds": 0,
           	  "scheduleAt": "2020-02-27T14:24:00.000Z",
           	  "dataFrom": "2020-02-26T12:30:00.000Z",
           	  "dataTo": "2020-02-27T12:30:00.000Z"
           }
       }
    ]
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/job/15896925"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Example Request

404 - Not Found

curl --request DELETE "{{url}}/service/zementis/job/00000" --header "Authorization: {{auth}}"

Example Response

404 - Not Found

{
    "errors": [
        "Zementis job ID '00000' not found."
    ]
}

DEL - Remove all jobs

{{url}}/service/zementis/jobs

Remove all available jobs and list the remaining jobs, if any.

ROLES & PERMISSIONS: ROLE_MACHINE_LEARNING_ADMIN

HEADERS
Authorization	{{auth}}

Example Request

200 OK

curl --request DELETE "{{url}}/service/zementis/jobs" --header "Authorization: {{auth}}"

Example Response

200 - OK

{
    "next": null,
    "prev": null,
    "statistics": {
        "currentPage": 1,
        "totalPages": 0,
        "pageSize": 5
    },
    "jobs": []
}

Example Request

401 - Unauthorized

curl --request DELETE "{{url}}/service/zementis/jobs"

Example Response

401 - Unauthorized

{
    "error": "general/internalError",
    "message": "No auth information found",
    "info": "https://cumulocity.com/guides/reference/rest-implementation/#error_reporting"
}

Using Postman

Graphical REST clients such as Postman are a convenient way to explore REST interfaces and the Cumulocity IoT database content.

If you are already using the Cumulocity IoT API collection in Postman and the environment to access the collection for your tenant is setup, then you can directly import the Zementis microservice collection (see below).

If you are doing a fresh setup of Postman for using the Zementis microservice collection, first follow the steps described under “Using Postman” in Using the Rest interface in the Microservice SDK guide.

Import the Zementis microservice collection in Postman

Import the APIs as a JSON file.

Alternatively click: After importing, you will see a new collection “Zementis Microservice API” in the Collections tab in Postman.