Deprecation of Machine Learning Engine and Machine Learning Workbench
As of Cumulocity IoT 10.16, Machine Learning Engine and Machine Learning Workbench are deprecated, and we will end further development of these components. After Cumulocity IoT 10.17, both will be removed from the platform. If you have existing (production) projects which rely on MLE and/or MLW applications, then Software AG is committed to working together with you to find an appropriate transition path. If we have not yet been in contact for this matter, feel free to contact us at c8y_mlw_mle_sunsetting@softwareag.com.
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}}"
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}}"
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."
]
}
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"
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}}"
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}}"
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 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}}"
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}}"
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}}"
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’
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’
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}}"
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"
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}}"
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"
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}}"
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.
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
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
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)"
]
}
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)"
]
}
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.
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.
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
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=@"
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
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
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"
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
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
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.
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.
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}}"
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}}"
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
