NAV

Introduction

Welcome to the the TCUP Portal. You can use our APIs to access the TCUP Services API endpoints.

You can view the code examples on the right side of the page.

Sensor Observation Service

1. Introduction

Sensor Observation Service (SOS) enables data ingestion from sensors, devices and IoT gateways to backend IoT data stores. It provides a rich set of queries to discover and use those data. It provides facility for registering new sensors and “things” to the platform and insert observations and measurements from various types of sensors into the data store. This service allows virtually any type of sensor and observations to be supported. SOS can be used for both streaming data as well as batch data. SOS is deployed in TCUP cloud. This is a RESTful web-service which accepts JSON payload.

2. Reference Documents

Sensor Observation Service Concept Guide

Sensor Observation Service User’s Guide

3. What are the RESTful resources in SOS?

  1. Feature of interest
  2. Sensor
  3. Observed property
  4. Observation
  5. Capability
  6. Feed
  7. Files
  8. User

3.1 Request Headers

Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
x-routing “db” or “mq” or “both” N Insert Observation call

3.2 Response Code

Every POST and PUT operation will send HTTP 200 irrespective of the actual status unless there is an internal error (HTTP 500). The actual HTTP status code and message for POST operations will be part of the response JSON.

3.3 Supported Time Format

The following timestamp formats are supported. SOS can store time-stamp up to millisecond level. All incoming time-zone is converted into UTC and stored.

dd-MMM-yyyy HH:mm:ss
dd-MMM-yyyy HH:mm:ss.SSS
dd-MMM-yyyy HH:mm:ss z
dd-MMM-yyyy HH:mm:ss.SSS z

Example 03-JUL-2015 13:10:00 IST

3.4 Version

‘version’ is optional in all POST and PUT request JSON and it won’t be stored/ persisted as of now.

3.5 Supported Data Types

For all the Feature properties, Sensor Output, Sensor Metadata, Observation Metadata(e.g. parameter, quality, meta-data etc.) ‘type’ should be from the list of supported datatypes mentioned in the response of GET Capabilities(supported-datatypes section); otherwise in POST or PUT request it will raise validation error. Data Types are case insensitive throughout.

3.6 Special Characters

3.7 Length Restriction

4. Capability

A sensor, a feature of interest or any kind of output is the capability of Sensor Observation services.

Supported parameters are :

4.1 Get the Capabilities of SOS

This API will return the basic information about all the features, sensors along with the output properties of the sensors which were inserted earlier.

HTTP Request

GET http://[domain]/api/sos/v2.0/capabilities/
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Reason
200 Operation succeeded
401 x-api-key header value is invalid

-

Response JSON

Response Body:

{
  "version": "1.0.1",
  "count": {
    "features": 2,
    "sensors": 3,
    "output": 3
  },
  "sosInterfaces": [
    {
      "supportedUrlendpoints": [
        {
          "featureUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/features"
          ],
          "sensorUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/sensors"
          ],
          "observationUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/observations"
          ],
          "filesUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/files"
          ],
          "feedUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/feed"
          ],
          "outputUrlEndPoints": [
            "http://[domain]/api/sos/v2.0/sensor-output"
          ]
        }
      ],
      "supported-operations": [
        "All"
      ],
      "supported-mimetype": [
        "application/json"
      ],
      "supported-jsonversion": [
        "1.0.1"
      ],
      "supported-datatypes": [
        "text",
        "decimal",
        "integer",
        "float",
        "double",
        "boolean",
        "time",
        "date",
        "timestamp",
        "long"
      ],
      "supported-timestamp": [
        "dd-MMM-yyyy HH:mm:ss Z",
        " dd-MMM-yyyy HH:mm:ss.SSS Z",
        " dd-MMM-yyyy HH:mm:ss",
        " dd-MMM-yyyy HH:mm:ss z",
        " dd-MMM-yyyy HH:mm:ss.SSS",
        " dd-MMM-yyyy HH:mm:ss.SSS z",
        " dd-MMM-yyyy"
      ],
      "default-pagesize-get-observation": 100,
      "default-pagesize-download-observation-file": 10000
    }
  ],
  "feature": [
    "bus-1",
    "bus-2"
  ],
  "sensor": [
    "accelerometer-1",
    "accelerometer-2",
    "s1"
  ],
  "output": [
    "humidity",
    "speed",
    "temp"
  ],
  "sensorOutput": {
    "accelerometer-2": [
      "speed"
    ],
    "accelerometer-1": [
      "speed"
    ],
    "s1": [
      "humidity",
      "temp"
    ]
  },
  "featureSensor": {
    "bus-1": [
      "accelerometer-1",
      "accelerometer-2",
      "s1"
    ]
  }
}

Note: Currently SOS doesn’t support ‘number’ data type.

4.2 Get Feature Capabilities

This API will return the basic information about the feature which was inserted earlier. The JSON also contains all association details of the sensors which were attached to this feature at different periods of time.

HTTP Request

GET http://[domain]/api/sos/v2.0/capabilities?list=feature
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Response Body:

{  
“version”: “1.0.1”,  
“feature”:  
\[  
“Room1A”,  
“Temperature”,  
“f1”,  
“Kolkata-EcoSpace-1B-4D”,  
“bus11”  
\]  
}
Status Codes Message
200 Operation succeeded
401 x-api-key header value is invalid
404 capability not found

4.3 Get Sensor Capabilities

This API will return the basic information about the sensor which was inserted earlier.

HTTP Request

GET http://[domain]/api/sos/v2.0/capabilities?list=sensor
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Reason
200 Operation succeeded
401 x-api-key header value is invalid

-

Response JSON

The above API call will return the following JSON document which contains the basic information about the sensor which was earlier inserted.

Response Body:

{
    "version": "1.0.1",
    "sensor": [
        {
          "TItag_mul_json",
          "bus1",
          "Sensor-4",
          "Sensor-5",
          "testSensor2",
          "Sensor-6"
        }
    ]
}

4.4 Get Output Capabilities

All the observed properties which has been registered along with the sensors can be seen using this API call.

HTTP Request

GET http://[domain]/api/sos/v2.0/capabilities?list=output
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message
200 Operation succeeded
401 x-api-key header value is invalid

Response

Response Body:

{  
“version”: “1.0.1”,  
“output”: \[  
“time”,  
“speed”,  
“Temp”  
\]  
}

4.5 Get Count Capabilities

Get Capability API with ‘count’ parameter will give the number of records for feature,sensor & output of the corresponding tenant.

HTTP Request

GET http://[domain]/api/sos/v2.0/capabilities?list=count
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message
200 Operation succeeded
401 x-api-key header value is invalid

-
Response JSON

The above API call will return the JSON block which contains the basic count information about the sensor, feature and output for this tenant.

Response Body:

{
  "version": "1.0.1",
  "count": {
    "features": 2,
    "sensors": 3,
    "output": 3
  }
}

5. Feature

Feature can be also named as Thing. This is the real-world entity which is normally attached to a sensor to measure an attribute of the feature. For example, a room is a feature. A thermometer (sensor) can measure temperature (observed property) of a room and post that value as sensor observation to SOS. SOS provides APIs to create, read, update and delete features.

A feature can exists in SOS even if there is no sensor.

5.1 Insert/ Register New Feature

This API enables to create new features.

HTTP Request

POST http://[domain]/api/sos/v2.0/features
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call

A JSON payload is to be sent in HTTP request body

Request Body:

{
    "version": "1.0.1",
    "features": [
        {
            "feature": "bus-1"              
        }
    ]   
}
Response Body:

[
    {
        "entity": "bus-1",
        "message": "CREATED",
        "httpStatus": 201
    }
]

If multiple feature are posted, the response will contain status for all individual features.

Status Codes Message Reason
200 OK Operation succeeded
201 CREATED Feature is successfully created
400 Bad Request JSON payload contains error
401 Unauthorized x-api-key header value is invalid
409 Provided parent feature does not exist Given parent feature needs to be created first
409 Feature already exists Given feature name already exists

5.2 Create a New Feature with Properties

This API enables to create features with multiple properties

Request Body:

{
    "version": "1.0.1",
    "features": [
        {
            "feature": "bus-1",
            "parentFeature": "bus-0",
            "privacy": "public",
            "geometry": {
                "name": "line-string",
                "point": [
                    {
                        "x": "-30.93005561828613",
                        "y": "117.6666412353516"
                    }
                ]
            },
            "property": [
                {
                    "name": "description",
                    "value": "4-wheeler for public transport",
                    "type": "TEXT",
                    "unit": ""
                }
            ]
        }
    ]   
}

Important:

-

JSON Property Type Description Mandatory
version string Version of JSON No
Feature string Feature name of the json Yes
privacy string Privacy of this json No
parentFeature string Shows the parent featurename of this json. No
Geometry Composed of line-string name and an Array[0..unbounded] of points Geometry information of the feature No
Property Array[0 to unbounded] Property of the feature No
name string Name of the Property Yes
value string Value of the Property Yes
type string Type of the Property No
unit string Unit of the Property No

5.3 Create Multiple Features in a Single API Call

This API enables to create multiple features in a single API call.

Request Body:

{
    "version": "1.0.1",
    "features": [
        {
            "feature": "bus-1, bus-2, bus-3"                
        }
    ]   
}

If the features have different properties, then the following JSON can be used for reference.

Request Body:

{
    "version": "1.0.1",
    "features": [
        {
            "feature": "bus-1", 
            "property": [
                {
                    "name": "description",
                    "value": "4-wheeler for public transport",
                    "type": "TEXT",
                    "unit": ""
                }
            ]            
        },
        {
            "feature": "room-1", 
            "property": [
                {
                    "name": "size",
                    "value": "100",
                    "type": "INTEGER",
                    "unit": "sqFt"
                }
            ]            
        }
    ]   
}

5.4 Feature Hierarchy

A new element called associateFeatures has been added in Feature JSON to designate relationship amongst features. Refer to the following table for examples of allowed relations between features:

Relation Example
is-a Bus is a vehicle
has-a Bus has a driver
located-in Bus is located in Mumbai

-
In the above example, there are four different feature-of-interests. Among which Vehicle is a generic feature and created in SOS once. Multiple types of vehicles namely a Bus is then created whose JSON contains the relationship to vehicle. Another independent feature called Driver which may or may not be a generic feature, could be created and associated to Bus. Finally the location Mumbai is added as a feature in SOS and associated with the bus. In this way a hierarchy and mesh of relations can be defined amongst features while creating the features in SOS. Refer to the the below feature JSON for more clarity.

Request Body:

{
    "version": "2.0.0",
    "features": [
    {
        "feature": "bus1",
        "associateFeatures": [
        {           
            "relation": "is_a",
            "feature" : ["vehicle"]
        }
        ],
        "privacy": "public",
        "geometry": {
            "name": "line-string",
            "point": [
                {
                    "x": "-30.93005561828613",
                    "y": "117.6666412353516"
                }
            ]
        },
        "position-local": [
            {
                "name": "floor",
                "value": "4A",
                "type": "text",
                "unit": ""
            }
        ],
        "property": [
            {
                "name": "description",
                "value": "4-wheeler for public transport",
                "type": "text",
                "unit": ""
            }
        ]
    }
    ]
}

Feature JSON may optionally contain position-local element.

Important Notes

5.5 Search Feature

This API enables to search the features which were inserted earlier.

HTTP Request

GET http://[domain]/api/sos/v2.0/features/{feature}
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Reason
200 Operation succeeded
401 x-api-key header value is invalid
404 Feature not found

-
Response JSON

The above API call will return the JSON document which contains the basic information about the feature which was inserted earlier. The JSON also contains all association details of the sensors which were attached to this feature during different periods of time.

Response Body:

{
    "version": "1.0.1",
    "features": [
        {
            "feature": "bus-1",
            "privacy": "public",
            "geometry": {
                "name": "line-string",
                "point": [
                    {
                        "x": "-30.93005561828613",
                        "y": "117.6666412353516"
                    },
                    {
                        "x": "-40.0",
                        "y": "102.0"
                    }
                ]
            },
            "property": [
                {
                    "name": "description",
                    "value": "4-wheeler for public transport",
                    "type": "TEXT"
                }
            ],
            "sensors": [
                {
                    "associatedOn": "02-MAY-2014 17:14:39 IST",
                    "sensor": "T-Sensor-2"
                },
                {
                    "associatedOn": "02-MAY-2015 14:45:12 IST",
                    "sensor": "T-Sensor-1"
                }
            ]
        }
    ]
}

Note

5.6 Search Feature by Meta-data

Features can be searched using the property names and values.

HTTP Request

GET http://[domain]/api/sos/v2.0/features?meta=size(>100)
GET http://[domain]/api/sos/v2.0/features?meta=description(like transport)
Query Parameters Description
meta Value of the “meta” will be name of any property of the feature (e.g. “description” or “size” etc) and a logical operator on the value.

-
Supported Logical Operators: =, <, >, <=, >=, !=,like

Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message
200 Operation succeeded
401 x-api-key header value is invalid
404 Feature not found

5.7 Update Details of Existing Feature

Except the name of the feature, all other properties of feature can be updated. To update the details of a feature, the complete new description of the feature has to be sent to SOS. A feature can be updated with new parent feature, privacy settings, geometric and all other properties.

HTTP Request

PUT http://[domain]/api/sos/v2.0/features
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message Reason
200 - Operation succeeded
205 UPDATED Feature is successfully updated
400 Bad Request JSON payload contains error
401 Unauthorized x-api-key header value is invalid
404 Feature does not exist Given feature needs to be created first
409 Parent feature does not exist Given parent feature needs to be created first

5.8 Delete Feature

A feature can’t be deleted if there is a sensor associated with it.

HTTP Request

DELETE http://[domain]/api/sos/v2.0/features/{feature}
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message
204 DELETED
401 x-api-key header value is invalid
404 Feature not found
409 Sensor exists
Response Body:

{  
    "entity": "bus-1", 
    "message": "DELETED",
    "httpStatus": 204
}

Note
The query string must be URL encoded before sending to SOS.

6. Sensor

Sensor can be a physical sensor or a soft-sensor. Sensor can be atomic or composite. In SOS a sensor can be created, updated, deleted and searched based on various conditions.

6.1 Register a New Sensor

Sensor registration is a mandatory operation before someone tries to insert observations generated by that sensor in SOS. To register the sensor, following API can be used.

HTTP Request

POST http://[domain]/api/sos/v2.0/sensors
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call

The JSON payload is to be sent in HTTP request body

Request Body:

{
    "version": "1.0.1",
    "sensors": [
        {
            "sensor": "accelerometer-1",
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ]               
        }
    ]   
}

Sensor contains one or more observed properties which is also called output. Output refers to all parameters that the sensor can measure. At least one output has to be mentioned during sensor registration.

Apart from sensor name and at least one output, everything else is optional in sensor JSON.

Important: White-space characters are not allowed in sensor name as well as in output name. If emply string (“”) is used as value for any JSON key, it is considered as null and the key is altogether ignored.

If the given request JSON once posted, the following response will be sent from SOS.

Response Body:

[
    {
        "entity": "accelerometer-1",
        "message": "CREATED",
        "httpStatus": 201
    }
]

If multiple sensor is posted, the response will contain status for all individual sensors.

Status Codes Message Reason
200 - Operation succeeded
201 CREATED Sensor is successfully created
400 (validation message) JSON payload contains error
401 - x-api-key header value is invalid
409 The comprising sensors does not exist Parent sensors need to be created
409 Sensor already exists Given sensor name already exists
409 Feature does not exist Feature need to created first

6.2 Associate a Feature During Sensor Registration

A sensor can be associated with only one feature at a given point of time.

Request Body:

{
    "version": "1.0.1",     
    "sensors": [
        {
            "sensor": "accelerometer-1",
            "feature": "bus-1",
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ]               
        }
    ]   
}

If feature “bus-1” is not created prior to the sensor registration, SOS will return HTTP 409 (Feature does not exist).

A single feature can be associated with multiple sensors at the same time. For example, a room can have both humidity and temperature sensor at a given time.

6.3 Register a New Sensor With Location Details

Sensors can have two types of locations. They are local positions and global positions. Latitude, longitude, altitude are good example of global position of a sensor. However, custom local positions can also be defined for the sensor.

Request Body:

{
    "version": "1.0.1",
    "sensors": [
        {
            "sensor": "accelerometer-1",
            "isMobile": "y",
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ],  
            "position-global": {
                "latitude": "87",
                "longitude": "57",
                "altitude": "2m"
            },
            "position-local": [
                {
                    "name": "city",
                    "value": "kolkata",
                    "type": "text",
                    "unit": ""
                }
            ]            
        }
    ]   
}

6.4 Register a Composite Sensor

One or more atomic sensors can be referred in a sensor definition to create a composite sensor. For example, a weather station can be modeled as a composite sensor which is composed of atomic sensors like temperature, humidity, pressure and wind-speed sensors.

Request Body:

{
    "version": "1.0.1",     
    "sensors": [
        {
            "sensor": "station-1",
            "isComposite": "y",
            "composedOfSensors": "sensor-1,sensor-2",
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ]               
        }
    ]   
}

6.5 Register a New Sensor with Meta-data

One or more meta-data can be custom defined during registration of a sensor. As per OGC SOS models, there can be the following meta-data groups along with a sensor:

Meta-data Name Description
identifier uniqueId, offering, keywords, shortName, longName, acronym, serialNumber, manufacturerID, partNumber etc
classifier sensorType, observableType, processType, intendedApplication, missionID
capability drift, sensitivity, selectivity, accuracy, measurementRange, detectionLimit, precision, responseTime, frequency, latency, resolution etc
characteristics weight, diameter, length etc
interface network interfaces, application interfaces, mechanical interfaces etc
parameter anything beyond the above classifications
input output of one sensor can be input of the other thus creating a sensor system
Request Body:

{
    "version": "1.0.1",
    "sensors": [
        {
            "sensor": "sensor-1",
            "feature": "bus-1",
            "offering": "bus-tracking",
            "isMobile": "y",
            "isComposite": "y",
            "composedOfSensors": "sensor-0,sensor-2",
            "validUpto": "23-JUL-2023 15:30:00 IST",
            "privacy": "public",
            "sensorType": "motion",
            "position-global": {
                "latitude": "87",
                "longitude": "57",
                "altitude": "2m"
            },
            "position-local": [
                {
                    "name": "floor",
                    "value": "4A",
                    "type": "text",
                    "unit": ""
                }
            ],
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ],
            "input": [
                {
                    "name": "acceleration",
                    "type": "float",
                    "unit": "m/s2"
                }
            ],
            "parameter": [
                {
                    "name": "traffic",
                    "value": "heavy",
                    "type": "text",
                    "unit": ""
                }
            ],
            "identifier": [
                {
                    "name": "make",
                    "value": "ConnectProX5",
                    "type": "text",
                    "unit": ""
                }
            ],
            "classifier": [
                {
                    "name": "sensortype",
                    "value": "accelerometer",
                    "type": "text",
                    "unit": ""
                }
            ],
            "capability": [
                {
                    "name": "responseTime",
                    "value": "3",
                    "type": "text",
                    "unit": "ms"
                }
            ],
            "characteristics": [
                {
                    "name": "weight",
                    "value": "30",
                    "type": "text",
                    "unit": "gm"
                }
            ],
            "interface": [
                {
                    "name": "network",
                    "value": "rs232",
                    "type": "text",
                    "unit": "ms"
                }
            ]
        }
    ]
}

The newly introduced sensorType field is an optional field.

6.6 Update Existing Sensors

A sensor can be updated using the unique sensor name.

HTTP Request

PUT http://[domain]/api/sos/v2.0/sensors

Input JSON example

Request Body:

{
"version": "1.0.1",
"sensors": [
    {
        "sensor": "s22",
        "feature": "f15",
        "output": [
            {
                "name": "speed",
                "type": "double"
            }
        ]
    }
  ]
}
Response Body :

[
    {
    "entity": "s22",
    "message": "UPDATED",
    "httpStatus": 205
     }
]

Response Code

200

Status Codes Reason
205 Updated
200 Operation Succeeded
400 JSON payload contains error
401 Unauthorized
404 Sensor is not present
409 Observation exists for the given sensor

6.7 Search a Sensor by Sensor ID

A sensor can be searched by using the unique sensor name using this API.

HTTP Request

GET http://[domain]/api/sos/v2.0/sensors/{sensor}
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Reason
200 Operation succeeded
401 x-api-key header value is invalid
404 Sensor not found

-
Response JSON
The above API call will return the sensor JSON. The response JSON will contain all other location, meta-data etc if they exists.

Response Body:

{
    "version": "1.0.1",
    "sensors": [
        {
            "sensor": "accelerometer-1",
            "output": [
                {
                    "name": "speed",
                    "type": "float",
                    "unit": "km/hr"
                }
            ]               
        }
    ]   
}

Note: In reactive sos (also known as sos-hbase) the user will get an additional field ‘readinessStatus’ along with it’s value(boolean value - true or false) in GET sensor response. Here the ‘readinessStatus’ value ‘true’ means the corresponding sensor is ready for the observation data ingestion(posting) and the user can POST the observation data to be persisted otherwise it will give validation error.

6.8 Get Details of Multiple Sensors Using Single Call

HTTP Request

GET http://[domain]/api/sos/v2.0/sensors?sensor={sensor1,sensor2}

Note
The query string must be URL encoded before sending to SOS.

6.9 Search Sensor Using Multiple Parameters

Sensors can be searched using various parameters. They are described below.

Query Parameter Description URL
sensor one or more comma-separated sensor names /sensors?sensor=S1,S2
recordTime This is a Temporal Filter based on time of sensor registration in SOS /sensors?recordTime=latest
meta Any meta-data of sensor can be used as Result Filter to search sensors /sensors?meta=make(=TI)
isMobile Search all mobile sensors. Allowed values are true or false /sensors?isMobile=true
privacy Search all sensors whose privacy settings is set to public /sensors?privacy=public
parent Find parent sensor of S2 /sensors?parent=S2
child Search child sensors of S3 /sensors?child=S3
sensorType Find temperature sensors only. Allows comma-separated multiple values in query. /sensors?sensorType=temperature
geometry This is Spatial Query based on the initial geographical position of the sensors. * sensors?geometry=G

The above parameters can be used in any combination.

Example HTTP Request


1. To get details of sensors S1 and S2, use following URL.
   GET http://[domain]/api/sos/v2.0/sensors?sensor=S1,S2

2. To get the 100 last registered sensor, use following URL  
   GET http://[domain]/api/sos/v2.0/sensors?recordTime=latest(100)

3. To get sensors registered in last 2 days  
   GET http://[domain]/api/sos/v2.0/sensors?recordTime=last2d

4. To get all sensors having accuracy more than 90%  
   GET http://[domain]/api/sos/v2.0/sensors?meta=accuracy(>90)

Comma-separated values must be URL encoded before sending

Note:

6.10 Delete Sensor By ID

A sensor can be deleted if there is no observation associated with it.

HTTP Request

DELETE http://[domain]/api/sos/v2.0/sensors/{sensor}
Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
Status Codes Message
204 DELETED
401 x-api-key header value is invalid
404 Sensor not found
409 Observation exists
Response Body:

{  
    "entity": "S1", 
    "message": "DELETED",
    "httpStatus": 204
}

Note: The query string must be URL encoded before sending to SOS.

6.11 Update Sensor Feature Mapping

A sensor feature mapping can be updated using the sensor name and feature name.

Status Codes Reason
205 Updated
200 Operation Succeeded
400 JSON payload contains error
401 Unauthorized
404 No sensor was found
409 Feature does not exist
**HTTP Request**

PUT http://tcup.web2labs.net/api/sos/v2.0/sensors/sensor_1/Bike

> **Request Headers:** x-api-key, accept=application/json  
> **HTTP Response Code:** 200


Response Body

{
“entity”: “sensor_1”,
“message”: “UPDATED”,
“httpStatus”: 205
}



**Response Code**


200




**HTTP Request**

PUT http://tcup.web2labs.net/api/sos/v2.0/sensors/s1/Bike


> **Request Headers:** x-api-key, accept=application/json  
> **HTTP Response Code:** 200



Response Body

{
“entity”: “s1”,
“message”: “No sensor was found”,
“httpStatus”: 404
}


**Response Code**

200


**HTTP Request**

PUT http://tcup.web2labs.net/api/sos/v2.0/sensors/sensor_1/f1


> **Request Headers:** x-api-key, accept=application/json  
> **HTTP Response Code:** 200




Response Body

{
“entity”: “sensor_1”,
“message”: “Feature does not exist”,
“httpStatus”: 409
}


**Response Code**

200




## 7. Observed Property

### 7.1 Search Sensor Output

This API is used to get the sensor outputs along with sensor name by observed property name.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/sensor-output/speed

Here the observed property 'speed' is the input parameter.


* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call



* **Status Codes**

| Status Codes     | Description    |
| :-------:                 | :----         |
| 200                   |  OK    |
| 401                   |  **x-api-key** header value is invalid  |
| 404                   |  Not found  |


-

Response Body:

[
{
“name”: “speed”,
“sensor”: “accelerometer-1,accelerometer-2”,
“type”: “float,float”,
“unit”: “km/hr,km/hr”
}
]


## 8. Observation

An observation is a value of an observed property (output) of a sensor at a specific time.

### 8.1 Insert Observations Produced by Sensors

This API enables to insert sensor observations.

**HTTP Request**

POST http://[domain]/api/sos/v2.0/observations


* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call
|x-routing      | "db" or "mq" or "both" | N | Insert Observation call


The JSON payload is to be sent in HTTP request body

Request Body:

{
“version”: “1.0.1”,
“observations”: [
{
“sensor”: “sensor-1”,
“feature”: “bus-1”,
“record”: [
{
“starttime”: “16-JUL-2011 15:15:00 IST”,
“output”: [
{
“name”: “speed”,
“value”: “40.0”,
“type”: “decimal”,
“unit”: “kmph”
}
]
}
]
}
]
}


On successful insertion into database, a unique observation ID is generated and returned in response.

Response Body:

[
{
“entity”: “ID: 958052”,
“message”: “CREATED”,
“httpStatus”: 201
}
]


Another input payload sample to create Observation

Request Body:

{
“version”: “1.0.1”,
“observations”: [
{
“sensor”: “sensor-1”,

    "offering": "bus-tracking",
    "validUpto": "23-JUL-2023 15:30:00 IST",
    "privacy": "public",
    "record": [
        {
            "starttime": "23-JUL-2013 15:30:00 IST",
            "endtime": "23-JUL-2013 15:30:00 IST",
            "associatedObservation": "O_209",
            "position-global": {
                "latitude": "87",
                "longitude": "57",
                "altitude": "2m"
            },
            "position-local": [
                {
                    "name": "floor",
                    "value": "4A",
                    "type": "text",
                    "unit": ""
                }
            ],
            "output": [
                {
                    "name": "speed",
                    "value": "40.0",
                    "type": "decimal"
                }
            ]
        }
    ],
    "parameter": [
        {
            "name": "traffic",
            "value": "heavy",
            "type": "text",
            "unit": ""
        }
    ],
    "quality": [
        {
            "name": "accuracy",
            "value": "99",
            "type": "double",
            "unit": "%"
        }
    ],
    "meta-data": [
        {
            "name": "speedometer-version",
            "value": "3.0",
            "type": "double",
            "unit": ""
        }
    ]
}

]
}




* **Status Code**

| Status Codes     | Message | Reason       |
| :-------:                 | :----         | :---          |
| 200                   | - |  Operation succeeded    |
| 201                   | CREATED   |  Sensor is successfully created   |
| 400                   | (validation message)    |  JSON payload contains error  |
| 401                   | -    |  **x-api-key** header value is invalid  |
| 404                   |   No sensor was found  |  Sensor need to be registered |
|404 | Feature does not exist | Feature is not registered in SOS |
| 404 | Provided feature is not mapped with the provided sensor | Sensor is not attached with this feature currently
| 409                   | Invalid output name    |  Sensor was not registered with given output  |

-
**Important**  
* If no ‘type’ is provided ,SOS will try to inherit the ‘type’ from the sensor output(provided during sensor registration).But if SOS cannot cast the ‘value’ to that ‘type’ then it will give validation error.  
* If a ‘type is provided SOS will validate that ‘type’ but if the ‘value’ cannot be cast to that ‘type’, SOS will give validation error.  

* If the data type (type) is provided during insert observation, it will be validated from the corresponding sensor definition.In case if that datatype is not found in the sensor definition or if the value is not compatible with the datatype it will give a validation error.


**Observations**

| JSON Property         | Type          | Description       | Mandatory
| :-------              | :----         | :---              | :---- 
|version                |string         | Version of JSON   | No 
| observations | Array[1..unbounded] | Observations of json string | Yes


-
**Observation**

| JSON Property     | Type          | Description    | Mandatory
| :-------          | :----         | :---           | :---- 
|   sensor          |   string      |   Senor name   |   Yes 
|   feature     |   string  |   Feature name    |   No  
|   validUpto   |   timestamp   |   Validity of observation |   No  
|   privacy     |   string  |   Privacy settings    |   No  |
|   record  |   Array[1..unbounded] |   Time, value, location   |   Yes 
|   parameter   |   string  |   Observation parameter   |   No  
|   quality     |   string  |   Observation quality |   No  
|   meta-data   |   string  |   Any other meta-data |   No  

-
**Record**

| JSON Property         | Type          | Description               | Mandatory
| :-------              | :----         | :---                      | :----
|starttime              |timestamp      | Start time of observation | Yes 
| endtime | timestamp | End time of observation. Null for instantaneous observation. | No
| associatedObservation | string | Related observation id inserted earlier | No
| position-global | object | Latitude, longitude and altitude | No
| position-local | Array[0..unbounded] | Any user define multi-dimensional location system | No
| output | Array[1..unbounded] | Output name, value, data type and unit | Yes

**Observation Routing**

It is possible to route the observation data by default to both database and message queue or to any of the two. The header `x-routing` is used for the same.



| Value                 | Description 
| :-------              | :----         
|'db' | Observation only goes to database
|'mq'| Observation only goes to message queue(currently in reactivesos/sos-hbase)
|no value| Observation goes both to database and message queue

-
**_Effect on Get Observation Queries_**  
When `x-routing` is set to `mq` then no data goes to database. The get observation query (except latest) cannot find the observation from database because get latest observation is served from cache, this query will fetch data even if the data is not going to database.

**Observations recorded at different times from different sensors can be sent using a single JSON payload. When multiple observations are sent, the response contains multiple HTTP status codes**


### 8.2 Get Observations by Observation ID

A unique observation ID is generated and returned to client during every insert observation. The same ID can be used to retrieve the observation by using the following API.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations/{id}

* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call


### 8.3 Search Observations

Observations can be searched by many other parameters. The following table gives the details of all such query parameters.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?sensor=S1&feature=F1&field=speed


* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call



**Example URL**


| Query     | URL | 
| :-------              | :----         
|Observations of a sensor | `observations?sensor=S1`
|Observations of many sensors | `observations?sensor=S1,S2,S3`
|Observations of a feature | `observations?feature=F1`
|Observations of many features | `observations?feature=F1,F2`
|Observations of a feature hierarchy(HAS A)| `observations?associatedFeatureHierarchyLevel=3&associatedFeatureRelationshipType=has_a&feature=room1`
|Observations of a feature hierarchy(IS A)| `observations?associatedFeatureHierarchyLevel=3&associatedFeatureRelationshipType=is_a&feature=room1`
|Observations of a feature hierarchy(LOCATED IN)| `observations?associatedFeatureHierarchyLevel=3&associatedFeatureRelationshipType=located_in&feature=room1`
|Observations containing any of the outputs | `observations?fields=speed,temperature`
|Observations containing any of the outputs with AND condition | `observations?andOrFieldsQuery=/max-speed/ and /speed/`
|Observations containing any of the outputs with OR condition | `observations?andOrFieldsQuery=/max-speed/ or /speed/`
|Observations containing any of the outputs with AND , OR condition | `observations?andOrFieldsQuery=(/max-speed/ and /speed/) or /velocity/`

-
**Important:** Query which contains characters like comma (,) needs to be URL encoded before sending to SOS.

### 8.4 Find Observations Using Result Filter

A result filter is a logical operation on the value of an output in an observation. Currently it supports observed property fields.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?field=speed(=40)


In the above query all observations will be returned which contains an output called speed and where the value of the speed is equal to 40. The operator and the value must be inside brackets.

* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call



The following operators are allowed:


=,>,<,>=,<=,!=,like


**Example URL**


| Query     | URL | 
| :-------              | :----         
|Where speed is greater than 40 | `observations?field=speed(>40)`
|All observations having either speed > 40 **or** temp < 25 | `observations?field=speed(>40),temp(<25)`
|All observations having either speed > 40 **or** have an output called temp | `observations?field=speed(>40),temp`
|All observations having speed equal to 40 | observations?field=speed(=40)
|All observations having temp not equal to 0 | observations?field=temp(!=0)
|All observations having Ring like beep | observations?field=Ring(like beep)
|All observations having either max-speed > 200 **and** speed > 40, or temp > 30 | `observations?andOrFieldsQuery=(/max-speed > 200/ and /speed = 40/) or /temp > 30/`

### 8.5 Find Observations Using Temporal Filter

Each observation from a sensor contains a unique time-stamp with it. It is called event time. The search conditions to fetch observations based on their time of occurrence is called Temporal Filter.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?time=T


Here T can be the following:


| Query     | URL | 
| :-------              | :----         
|An exact time | `observations?time=23-Feb-2014 12:34:11 IST`
|Between a time range | `observations?time=23-Feb-2014 12:34:11 IST, 23-Feb-2014 12:34:22 IST`
|A time expression | `observations?time=last1d2h5m10s`
|Latest N observations | `observations?time=latest(100)`
|First N observations | `observations?time=first(10)`
-
* When time stamp is provided in query parameter, it must be URL encoded.
* In time expression query (e.g. time=last1d2h5m10s) 'd' means day(max 4 digits),'h' means hour(max 2 digits),'m' means minutes(max 2 digits),'s' means seconds(max 2 digits).

**Syntax for Time Expression**  
Time expression can be used in temporal query in the following manner:


| Query     | URL | 
| :-------              | :---- 
|Last 1 year | `observations?time=last365d`
|Last 1 day and 15 hours | `observations?time=last1d15h`
|Last 10 minutes  | `observations?time=last10m`
|Last 5 seconds  | `observations?time=last5s`


Any syntactical error in time value will cause SOS to throw **400** _Bad Request_.

### 8.6 Observation Count

Count of observations can be fetched using this API. Count can be accommodated with other queries also.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?f=COUNT


The above query will return the count of total observations. The following query returns count of observations for a specific sensor:

GET http://[domain]/api/sos/v2.0/observations?f=COUNT&sensor=S1


Response Body:

{
“version”: “1.0.1”,
“observations”: [
{
“record”: [
{
“output”: [
{
“name”: “COUNT(1)”,
“value”: “25”
}
]
}
]
}
]
}


If there is no observation, SOS will return HTTP 404 status code.

Note : Latest** and **count** can not be used in single API call

### 8.7 Find Aggregate Result on Observation Values

Aggregate functions like sum, average, minimum, maximum etc. can be applied on the value of observation output.

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?f=MAX&field=speed&sensor=Speedometer


**Important**  
* At least one field name must be provided along with SUM, AVG, MAX, MIN, DISTINCT function names.
* Currently SOS does not support any aggregate,query(SUM, AVG, MAX, MIN, DISTINCT,COUNT) on multiple fields(ie. multiple observed properties).It will five 'Invalid query' error.
* SOS-RDBMS specific note:Also exact one sensor is required directly or indirectly(in this case sensor name will be derived from feature or field).The aggregate function value will be calculated on the numeric fields where it will not differentiate the supported numeric data types.Updating a sensor(adding some new observed properties) which already has pre-existing observation data may produce wrong aggregate result during GET observation call wiyh aggregare function. 


| Query     | URL | 
| :-------              | :---- 
|Max speed of my car in last 12 hours | `observations?time=last12h&feature=MyCar&field=speed&f=MAX`
|Min temperature in Kolkata  | `observations?field=city(=Kolkata),temperature&f=MIN`
|Sum of total calory intake  | `observations?feature=Me&field=calory&f=SUM`


-
**JSON Response**

Response Body:

{
“version”: “1.0.1”,
“observations”: [
{
“record”: [
{
“output”: [
{
“name”: “MAX(speed)”,
“value”: “65”
}
]
}
]
}
]
}


If an aggregate function is applied on an output which has incompatible data-type (e.g. Text), the following error will be thrown from SOS.

{
“message”: “Invalid query”,
“httpStatus”: 400
}


### 8.8 Find Observations Based on Spatial Query

A spatial query is the capability to find an observation based on the observation’s global position (latitude and longitude). If an observation was inserted with a global position which contains the latitude and longitude, it is possible to find the observation using the following API:

**HTTP Request**

GET http://[domain]/api/sos/v2.0/observations?geometry=G



Here **G** is a geometric shape like circle or polygon (triangle, rectangle etc) represented in terms of set of co-ordinates. Following shapes are supported as of current version:

| Query           | URL                         | description                          |
| :-------        | :----                       | :---------------------               | 
| POLYGON  | `observations?geometry=POLYGON((88.414106 22.590655, 88.419192 22.589645,88.421981 22.585465, 88.418634 22.583583, 88.411735 22.584702, 88.409729 22.588060, 88.414106 22.590655))` | here latitude and longitude is separated by a space and such coordinates are separated by comma (,) forming multiple corners of the polygon where the starting and end coordinates must be same.
| CIRCLE  | `observations?geometry=CIRCLE((144.947503,-37.816484),0.4683)` | here first two decimal numbers are the center coordinate of the circle and third decimal number is the radius of the circle in Kilometer.

-
**JSON Response**

Response Body:

{
“version”: “1.0.1”,
“observations”: [
{
“record”: [
{
“associatedObservation”: 209,
“position-global”: {
“altitude”: “2m”,
“latitude”: 87,
“longitude”: 27
},
“position-local”: [
{
“type”: “text”,
“unit”: “”,
“name”: “floor”,
“value”: “4A”
}
],
“starttime”: “23-JUL-2013 15:30:00 IST”,
“endtime”: “23-JUL-2013 15:40:00 IST”,
“output”: [
{
“type”: “decimal”,
“name”: “speed”,
“value”: “40.0”
}
]
}
]
}
]
}


* Along with Geometry at least one of the parameter (sensor/feature/time/fields) is mandatory for searching.
* Any syntactical error in Spatial Query will raise validation error.

    {  
    “message”: “Geometry should contain CIRCLE or POLYGON”,  
    “httpStatus”: 400  
    }
* Any invalid query(which needs multiple parameter to proceed successfully) will raise validation error.  
    {  
    “message”: “Invalid query combination. “,  
    “httpStatus”: 400  
    }

#### 8.8.1 Why am I getting 100 observations only?

In many get observation queries, the amount of data transfer will be too huge to cause HTTP connection time-out. In such cases, although the service request runs in background but the application server throws **HTTP 500** exception as soon time-out occurs. This can also happen for other APIs of SOS.  
The get observation API is specially equipped to handle this. By default, the number of observations returned by the get observation API is **100** which is also called the **default page size**. To overwrite this behavior, if needed, one can send pageSize parameter along with the any of the above get observation calls and get the desired number of observations. It looks like the following:

`GET http://[domain]/api/sos/v2.0/observations?sensor=S1&pageSize=10`  

Now the above call returns only 10 observations.

* `pageSize=100` is kind of silently appened with all get observation queries unless it is mentioned explicitly.  

* If the user queries SOS for latest(500) observations and do not pass pageSize, SOS will return 100 unless `pageSize=500` is mentioned.

#### 8.8.2 Pagination in Get Observation

The get observation API supports pagination. The first page of observations (set of 100 observations by default) is numbered as **0**. To fetch the next pages, one can issue the same query again and append the query with a pageNo parameter with value 1, 2, 3 etc.

Let us assume there are 50,000 observations from sensor S1. 

To get all 500 observations in single call, one should use:

`GET http://[domain]/api/sos/v2.0/observations?sensor=S1&pageSize=50000`  

This is not a good practice as there is a risk of HTTP connection timeouts.
Therefore one should use the following query and get the first 100 observations of 50,000. This is page **0**.  

`GET http://[domain]/api/sos/v2.0/observations?sensor=S1`  

Next page can be fetched by using:

`GET http://[domain]/api/sos/v2.0/observations?sensor=S1&pageNo=1`  

This way the 50,000 observations can be fetched in 50 pages of 100 observations each where the page number is 0 to 49. If someone gives a page number which is out of range, lets say 50, SOS will return HTTP **404** (Not Found) exception.

 * The order of observations returned in a paged query is the natural order of observation insertion.
 * Use `time=latest(50000)` and `pageNo` both to retrieve the latest observations first

### 8.9 Update Observation

An observation once inserted can never be updated. If an updated value is available in another time, another new observation must be inserted rather than updating the previous observation.

### 8.10 Delete Observation by Observation ID

An observation can be deleted using the observation ID.

Note : Observation ID is system generated and returned after successful Insert Observation call.

**HTTP Request**

DELETE http://[domain]/api/sos/v2.0/observations/134908


* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call


**Response JSON**

Response Body:

{
“entity”: “ID: 134908”,
“message”: “DELETED”,
“httpStatus”: 204
}


If there was no observation by that ID, or that observation is already deleted, then the following response JSON is returned:

Response Body:

{
“entity”: “ID: 134908”,
“httpStatus”: 404
}

**Note** : The query string must be URL encoded before sending to SOS.

### 8.11 Delete Observation by Sensor Name and Time

Multiple observations can be deleted in single API call by using sensor name(s) and/or temporal filters in query parameter.

**HTTP Request**

DELETE http://[domain]/api/sos/v2.0/observations?sensor=S1&time=latest


**Response JSON**

Response Body:

[
{
“entity”: “10 observation(s)”,
“message”: “DELETED”,
“httpStatus”: 204
}
]


If no observation is found to delete, SOS returns **404** Http status code in response header.

### 8.12 Observation Bulk Insert

This API is used for inserting bulk observations with optimized JSON payload. Only advantage is lesser JSON payload to post multiple observation data in a single API call compared to POST observations API (POST http://[domain]/api/sos/v2.0/observations).

**HTTP Request**

http://{sos-endpoint}/observations/bulk

* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call
|x-routing      | "db" or "mq" or "both" | N | Insert Observation call


Sample JSON payload,

Request Body:

[
[
“sensor,starttime, output/temp”,
“s1,26-JUL-2015 15:30:00 IST,50.5”,
“s1,26-JUL-2015 15:31:00 IST,51”
],
[
“sensor,starttime, output/speed”,
“s2,26-JUL-2015 16:30:00 IST,150.5”,
“s2,26-JUL-2015 16:31:00 IST,151”
]
]

**Payload Construction Rules**

* The JSON payload will be started and ended with ‘[’ and ‘]’ correspondingly.
* Observations are grouped by the similar observed properties.
* Each observation group will be started and ended with ‘[’ and ‘]’ and are separated by comma.
* In each observation group the first line will be the attribute name header separated by comma.One exception is for “name” attribute of output,position-global,position-local,parameter,quality,meta-data elements where use “/” as separator for the header name .For example output/temp where output is the element and temp is the name of that output.The same logic will be applied to position-global,position-local,parameter,quality,meta-data elements.
* In each observation group the subsequent lines after the header line contain the observation data values where each data line represents one observation ruled by the header of that group.
* All the header and data lines will be started and ended with double quotation and separated by comma.
* All the data values in a particular data line(observation) will be separated by comma.
* The data lines in each observation group will contain the data values corresponding to the header of that group.In the above example s1 is the value of ‘sensor’ , 26-JUL-2015 15:30:00 IST is the value ‘starttime’ and 50.5 is the value of ‘output/temp’.

## 9. Feed

### 9.1 Listen to Observation Feed

Observation data feed API is a real-time push API from SOS to receive the latest observation. The result of the call will return the last observation inserted in SOS for that particular sensor. The returned observation JSON will be preceded with a string `data:`. Irrespective of how many clients accessing the same feed URL, all will receive same observation data. A client can call multiple feed URLs at the same time.


**HTTP Request**
> GET http://{sos-endpoint}/feed/{sensor}

> curl -X GET "http://{sos-endpoint}/api/sos/v2.0/feed/{sensor}?key={apikey}" -H "accept: text/event-stream" -H "x-api-key: {apikey}"

Client must send in feed URL a valid API Key as HTTP header named `x-api-key`. If there is no API key or invalid API Key, a HTTP 401 unauthorized error will be returned. When there is no new data available to push to clients, SOS will try to send a string `data:` in order to check if the client is alive. Ignore these string at the client-side.

### 9.2 Get Active Feed List

This API is used to get the active feed list.

**HTTP Request**
> GET http://{sos-endpoint}/api/sos/v2.0/feeds

> curl -X GET "http://{sos-endpoint}/api/sos/v2.0/feeds" -H "accept: */*" -H "x-api-key: {apikey}"

**Important** Feed URL cannot be tested through API Sandbox. To access the data, hit the feed URL in SSE supported browsers or write a client in JavaScript, Java etc.

If the observation inserted in SOS have an older event time, that observation will not appear in feed URL as already a newer observation has been sent to clients.

Note: Both the feed APIs are marked as deprecated.


## 10. Files

### 10.1 Upload Files

Observation  csv (comma separated) data file with  predefined column name format can be uploaded to SOS.
Check download observation file to get the column name format.



**Sample CSV file content 1**


"sensor","time","feature","privacy","offering","validUpto","speed2__float__"
"accelerometer-2","11-Jul-2011 15:15:00.000 IST",,,,,50.1



**Sample CSV file content 2**


"sensor","time","feature","privacy","offering","validUpto","speed__float__km/hr","lattitude","longitude","altitude","position-local:floor__text__","parameter:traffic__text__","quality:accuracy__float__%","meta-data:speedometer-version__double__"
"accelerometer-1","11-Jul-2011 15:15:00.000 IST",,,,,1050.1,,,,,,,
"accelerometer-1","23-Jul-2018 15:30:00.000 IST",,,,"23-Jul-2023 15:30:00.000 IST",1051.0,"87","57","2m","4A","heavy","99","3.0"


> http://{sos-endpoint}/files/observations

> curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json'  --header 'x-api-key: {avalidkey}'  'https://{sos-endpoint}/files/observations' -F 'observation=@{avalidcsvfile};type=text/csv'
> 
Parameter: observation
Value: {select the file}

**Note:**  
* csv file size limit is 2MB.
* If the file content-type is not csv, SOS will give validation error.
* If the csv file size is more than 2 MB, SOS will give validation error.

### 10.2 Download Files

Observation data can be searched using various parameter (eg. sensor,feature,time,fields & geometry) and the output will be a csv file if record founds.

**Sample endpoint:**
> http://{sos-endpoint}/files/observations?sensor={sensor}

### 10.3 Import Features Zip File

Features data can be imported for particular tenant.

**Constraints:**
* Imported file must be in .zip format.
* The zip file must contain a features json file namely features.json which will contain the features in json format(as same as POST feature json format) for importing.
* The default max file size limit is 10 MB which is configurable during build & deployment.

**HTTP Request**
> http://{sos-endpoint}/api/sos/v2.0/files/import/features

Parameter name for selecting zip file for exporting:
featuresFile

**Request Headers:** x-api-key, Content-Type=multipart/form-data
**HTTP Response Code:** 200

**CURL command:**

> curl -X POST "http://{sos-endpoint}/api/sos/v2.0/files/import/features" -H "accept: */*" -H "x-api-key: {a_valid_api_key}" -H "Content-Type: multipart/form-data" -F "featuresFile=@sos_feature_2019-09-06T12_39_59.439313Z.zip;type=application/zip"

**HTTP Response**

Sample Response 1:

Response Body:

[
{
“entity”: “WB123”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “room_x1”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “b1”,
“message”: “Already registered”,
“httpStatus”: 409
}
]

Sample Response 2:

Response Body:
[
{
“entity”: “WB1”,
“message”: “CREATED”,
“httpStatus”: 201
},
{
“entity”: “room_x2”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “b2”,
“message”: “CREATED”,
“httpStatus”: 201
}
]


### 10.4 Export Features Zip File

Features' data of any valid tenant can be exported in a zip file.The zip file will contain the actual features JSON file. If the search parameters find any feature data for that tenant, the feature data in JSON format will be written to a json file (features.json) and will be compressed in a zip file(For example, sos_feature_2019-09-09T11:42:14.273801Z.zip) for download.

**Note:**
 If no feature data founds then the zip file won't contain any JSON file.


**HTTP Request**
> http://{sos-endpoint}/api/sos/v2.0/files/export/features


* **Request Headers**

| Header Name     | Value         | Mandatory       | When
| :-------        | :----         | :---            | :---- 
|x-api-key      | Valid api key of the tenant | Y | In every API call
|Content-Type       | "application/json" | N | In every API call



Parameter: Feature query JSON containing either feature names in array or empty array to denote all features.

**Sample Request 1: To export the feature definition of the features feature1 and feature2**

{
  "feature": [
    "feature1", "feature2"
  ]
}

**Sample Request 2: To export all the feature definition of a tenant use empty array for feature element.**

{
  "feature": [

  ]
}

**CURL command:**

> curl -X POST "http://localhost:9001/api/sos/v2.0/files/export/features" -H "accept: */*" -H "x-api-key: test1" -H "Content-Type: application/json" -d "{ \"feature\": [ \"feature1\", \"feature2\" ]}"

> curl -X POST "http://localhost:9001/api/sos/v2.0/files/export/features" -H "accept: */*" -H "x-api-key: test1" -H "Content-Type: application/json" -d "{ \"feature\": [ ]}"

**HTTP Response**

**Sample Response 1:**

A zip file containing features.json file
The zip file name syntax is sos_feature_<TimeInstance in GMT>.zip(Eg. sos_feature_2019-09-09T11:46:41.254415Z.zip)

**Sample Response 2:**

A zip file containing no file in case no features data found.



### 10.5 Import Sensors Zip File

Sensors data can be imported for a particular tenant.

**Constraints:**

* Imported file must be in .zip format.
* The zip file must contain a sensors json file namely sensors.json which will contain the sensors in json format(as same as POST sensor json format) for importing.
* The default max file size is limit is 10 MB which is configurable during build & deployment.

**HTTP Request**
> http://localhost:9001/api/sos/v2.0/files/export/sensors

Parameter name for selecting zip file for exporting:
sensorsFile


**Request Headers:** x-api-key, Content-Type=multipart/form-data
**HTTP Response Code:** 200

**CURL command:**

> curl -X POST "http://{sos-endpoint}/api/sos/v2.0/files/import/sensors" -H "accept: */*" -H "x-api-key: {a_valid_api_key}" -H "Content-Type: multipart/form-data" -F "sensorsFile=@sos_sensor_2019-09-06T12_40_59.439313Z.zip;type=application/zip"

**Sample Response 1:**

Response Body:

[
{
“entity”: “sensor1”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “sensor2”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “sensor3”,
“message”: “Already registered”,
“httpStatus”: 409
}
]

**Sample Response 2:**

Response Body:

[
{
“entity”: “temp_sensor1”,
“message”: “CREATED”,
“httpStatus”: 201
},
{
“entity”: “sensor_x2”,
“message”: “Already registered”,
“httpStatus”: 409
},
{
“entity”: “speed_sensor1”,
“message”: “CREATED”,
“httpStatus”: 201
}
]

```

10.6 Export Sensors Zip File

Sensors data of any valid tenant can be exported in a zip file. The zip file will contain the actual sensors JSON file. If the search parameters find any feature data for that tenant, the feature data in JSON format will be written to a JSON file (sensors.json) and will be compressed in a zip file(For example, sos_feature_2019-09-09T11:42:14.273801Z.zip) for download.

Note: If no feature data is found then the zip file won’t contain any JSON file.

HTTP Request

http://{sos-endpoint}/api/sos/v2.0/files/export/sensors

Header Name Value Mandatory When
x-api-key Valid api key of the tenant Y In every API call
Content-Type “application/json” N In every API call
x-routing “db” or “mq” or “both” N Insert Observation call

Parameter: Feature query JSON containing either feature names in array or empty array to denote all sensors.

Sample Request 1: To export the feature definition of the sensors feature1 and feature2

{
“feature”: [
“feature1”, “feature2”
]
}

Sample Request 2: To export all the feature definition of a tenant use empty array for feature element.

{
“feature”: [

]
}

CURL Command:

curl -X POST “http://localhost:9001/api/sos/v2.0/files/export/sensors“ -H “accept: /“ -H “x-api-key: test1” -H “Content-Type: application/json” -d “{ \”feature\”: [ \”feature1\”, \”feature2\” ]}”

curl -X POST “http://localhost:9001/api/sos/v2.0/files/export/sensors“ -H “accept: /“ -H “x-api-key: test1” -H “Content-Type: application/json” -d “{ \”feature\”: [ ]}”

HTTP Response

Sample Response 1:

A zip file containing sensors.json file
The zip file name syntax is sosfeature.zip(Eg. sos_feature_2019-09-09T11:46:41.254415Z.zip)

Sample Response 2:

A zip file containing no file in case no sensors data found.

Message Routing

1. Introduction

TCUP’s Message Routing Service uses the AMQP protocol. The data comes via SOS/DM/SendRequest() API/Websocket and then the routing module redirects the data to a specific topic exchange with a topic based upon the routing rules conditions.

Message router rules takes the messages from direct type exchange, topic type exchange or queue and then routes the data to topic exchange with a topic based on the routing rules condition.

Effective TCUP 11 queue and topic exchange support are provided.

Direct Type Exchange

Users do not have to create a direct exchange separately. It gets created automatically (if it does not exist) once the rule is created with direct type exchange and started.

Topic Type Exchange

Users do not have to create a topic exchange separately. It gets created automatically with transient durability and non auto deletion feature (if it does not exist) once the rule is created with topic type exchange and is started. Users can also create topic exchange separately using APIs.

MQ

Users can create a queue separately using “MQ” service. It gets created automatically with durable feature (if it does not exist) once the rule is created with the queue and is started. Users can also create queues separately using APIs with different parameters and use in the rule.

2. Reference Documents

Message Routing Service Concept Guide

Message Routing Service User’s Guide

2.1 RESTful Resources Available in Message Routing

  1. Topic Exchange
  2. Routing Channel
  3. Routing Rules
  4. Send Request
  5. User
  6. Statistics
  7. Versions

3. Authentication

MR expects the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=

Request Headers

Header Description Sample Value
x-user-key Valid user key of the user under a valid tenant. It is also mandatory in every call. keydemo
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

4. Topic Exchange

4.1. Create Topic Exchange

It creates the exchange of type topic. Different tenants can create different topic exchanges for their use with unique exchange names.

HTTP Request
POST http://<domainname>/MessageRouting/v2.0/topicExchanges

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="
--data @body.json
http://<domain name>/MessageRouting/v2.0/topicExchanges
Request Body:
body.json contains input like below

{
    "exchangeName": "testExchange",
    "Type": "topic"
}

Body Parameters

Parameter Required Values Description
exchangeName true string name of the topic exchange
Type true string type of the exchange as topic
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

4.2. Get List of Exchange

It describes (lists) all the exchanges created by a particular tenant.

HTTP Request
GET http://<domain name>/MessageRouting/v2.0/topicExchanges

curl -X GET "http://<domain name>/MessageRouting/v2.0/topicExchanges"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Exchange List": [
        {
            "Exchange Name": "topic.exchange1",
            "Exchange Type": "topic",
            "Exchange Id": 21
        },
        {
            "Exchange Name": "topic.exchange2",
            "Exchange Type": "topic",
            "Exchange Id": 22
        },
        {
            "Exchange Name": "topic.exchange3",
            "Exchange Type": "topic",
            "Exchange Id": 23
        }
    ]
}
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

4.3. List of Topics of a Topic Exchange

It describes (lists) all the topics created by a particular tenant.

HTTP Request
GET http://<domain name>/MessageRouting/v2.0/topicExchanges/topics/{exchange}

curl -X GET "http://<domain name>/MessageRouting/v2.0
/topicExchanges/topics"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Topic Lists": [
        {
            "Rule Id": 1,
            "topicExchangeName": "DMexchange",
            "topicName": "DMS.*"
        },
        {
            "Rule Id": 22,
            "topicExchangeName": "cepTest",
            "topicName": "cep1.*"
        },
        {
            "Rule Id": 21,
            "topicExchangeName": "cepTest",
            "topicName": "cep.*"
        }
    ]
}

Query Parameters

Parameter Required Values Description
exchange false string Name of the exchange for which topics are created by a particular tenant
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

4.4. Delete a Topic Exchange

It deletes the exchanges created by a particular tenant. The exchange can only be deleted by the owner of the exchange.

curl -X DELETE "http://<domain name>/MessageRouting/v2.0
/topicExchanges/{exchangeName}"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Message": "Exchange successfully deleted!!"
}

HTTP Request

DELETE http://<domain name>/MessageRouting/v2.0/topicExchanges/{exchangeName}

URL Parameters

Parameter Required Values Description
exchangeName true string Deletes the given exchange name

-
Note - The URL must contain the name of the exchange to be deleted and the tenant ID of the owner of the exchange.

Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

5. Routing Channel

5.1. Start the Send/Receive Channel

It starts the send/ receive channel against the particular rule ID.

curl -X POST "http://<domain name>/MessageRouting/v2.0
/routingChannel/512/start"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Message": "Routing Channel Started"
}

HTTP Request

POST http://<domain name>/MessageRouting/v2.0/routingChannel/{rule_id}/start

URL Parameters

Parameter Required Values Description
rule_id true string Starts the MR routing rule with the given rule_id
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

5.2. Stop the Send/Receive Channel

It stops the send receive channel for a particular rule.

curl -X POST "http://<domain name>/MessageRouting/v2.0
/routingChannel/512/stop"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{  
  "Message": "Routing Channel Stopped"
}

HTTP Request

POST http://<domain name>/MessageRouting/v2.0/routingChannel/{rule_id}/stop

URL Parameters

Parameter Required Values Description
rule_id true string Stops the MR routing rule with the given rule_id
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

5.3. Get Associated Routing Keys

It describes (lists) the associated routing keys available for a tenant.

curl -X GET "http://<domain name>/MessageRouting/v2.0
/routingChannel/RoutingKeys"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Routing Keys": [
        {
            "Rule Id": 21,
            "directExchangeName": "Direct.Exchange",
            "routingKey": "cep"
        },
        {
            "Rule Id": 44,
            "directExchangeName": "Direct.Exchange",
            "routingKey": "cep1"
        }
    ]
}

HTTP Request

GET http://<domain name>/MessageRouting/v2.0/routingChannel/RoutingKeys

URL Parameters

Parameter Required Values Description
RoutingKeys true string Lists all associated routing keys available for a tenant
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

6. Routing Rules

6.1. Create a Routing Rule

It creates the MR routing rule for a tenant.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
--data @body.json http://<domain name>/MessageRouting/v2.0
/routingRules

body.json contains input JSON request like below :

{
    "RuleName": "MR demo rule",
    "RuleDescription": "MR demo rule for API",
    "parallelismFactor": "2",
    "input": {
        "DirectExchange": "Direct.Exchange",
        "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc="
    },
    "params": [
        {
            "name": "feature",
            "value": "room1"
        },
        {
            "name": "sensorID",
            "value": "NEXUS1"
        },
        {
            "name": "time",
            "value": {
                "starttime": "1-JAN-2014 15:30:00 IST",
                "endtime": "31-DEC-2014 15:30:00 IST"
            }
        },
        {
            "name": "expression",
            "value": {
                "if": "systolic>80",
                "then": "return \"high\";",
                "else": "if ( systolic< 80 && systolic > 50 ) {return \"medium\";} else {if (systolic > 20){return \"low\";}"
            }
        },
        {
            "name": "position",
            "type": "rectangle",
            "geoFencing": "NO",
            "value": {
                "points": [
                    {
                        "x": "5",
                        "y": "5"
                    },
                    {
                        "x": "20",
                        "y": "20"
                    }
                ]
            }
        },
        {
            "name": "ObservedProperties",
            "value": [
                {
                    "name": "systolic",
                    "type": "quantity",
                    "value": "(40,150)",
                    "operator": ""
                }
            ]
        },
        {
            "name": "meta-data",
            "value": [
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        },
        {
            "name": "parameter",
            "value": [
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        },
        {
            "name": "quality",
            "value": [
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        }
    ],
    "output": {
        "TopicExchange": "testExchange",
        "Topic": "android1"
    }
}

Note : In case the direct exchange does not exist, it will get created as durable with non-auto deletion feature when the rule is started. Direct type of exchange should exist or will be created under the admin vhost.

body.json contains input JSON request like below for topic exchange as input:

{
    "RuleName": "",
    "RuleDescription": "",
    "parallelismFactor": "2",
    "input": {
        "type": "topic",
        "DirectExchange": "testTopic",
        "RoutingKey": "testRouting",
        "MQName": ""
    },
    "params": [{
            "name": "feature",
            "value": ""
        },
        {
            "name": "sensorID",
            "value": ""
        },
        {
            "name": "time",
            "value": {
                "starttime": "",
                "endtime": ""
            }
        },
        {
            "name": "expression",
            "value": {
                "if": "",
                "then": "",
                "else": ""
            }
        },
        {
            "name": "position",
            "type": "rectangle/circles/polygon",
            "geoFencing": "NO",
            "value": {
                "points": [{
                        "x": "",
                        "y": ""
                    },
                    {
                        "x": "",
                        "y": ""
                    }
                ]
            }
        },
        {
            "name": "ObservedProperties",
            "value": [{
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                },
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                },
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        }
    ],
    "output": {
        "TopicExchange": "",
        "Topic": ""
    }
}

Note : In case the topic does not exist, a topic will get created with transient durability and non auto deletion feature when the rule is started. Topic exchange should exist or will be created under the tenant’s vhost.

body.json contains input JSON request like below for queue as input:

{
    "RuleName": "",
    "RuleDescription": "",
    "parallelismFactor": "2",
    "input": {
        "type": "MQ",
        "DirectExchange": "",
        "RoutingKey": "",
        "MQName": "Q10"
    },
    "params": [{
            "name": "feature",
            "value": ""
        },
        {
            "name": "sensorID",
            "value": ""
        },
        {
            "name": "time",
            "value": {
                "starttime": "",
                "endtime": ""
            }
        },
        {
            "name": "expression",
            "value": {
                "if": "",
                "then": "",
                "else": ""
            }
        },
        {
            "name": "position",
            "type": "rectangle/circles/polygon",
            "geoFencing": "NO",
            "value": {
                "points": [{
                        "x": "",
                        "y": ""
                    },
                    {
                        "x": "",
                        "y": ""
                    }
                ]
            }
        },
        {
            "name": "ObservedProperties",
            "value": [{
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                },
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                },
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        }
    ],
    "output": {
        "TopicExchange": "",
        "Topic": ""
    }
}

Note : In case a queue does not exist, it it will get created with durable and non- auto deletion features when the rule is started. Queue should exist or will be created under the tenant’s vhost.

HTTP Request

POST http://<domain name>/MessageRouting/v2.0/routingRules

Body Parameters

Parameter Required Values Description
RuleName true string RuleName should be unique for every rule
RuleDescription true string It should be a short description of the rule functionality
parallelismFactor true numeric value it should be in the range of 1-10 which defines the parallelism factor
Input:type false string Type of the exchange through which the input json is received in MR. It can be Direct/Topic/MQ. Default is Direct.
Input:DirectExchange false string Name of the direct/topic exchange depending on type. Default is Direct.Exchange.
Input:RoutingKey false string It is the routing/topic key through which the data is routed to direct/topic exchange of MR depending on the type. Default is unique key assign to per tenant.
Input:MQName false string It is the queue name in case type is MQ.
feature false string It is the name of observation feature on which feature based filtering is done
sensorID false string It is the name of observation sensor on which sensor based filtering is done
start time false time with date format It is the start time for input JSON
end time false time with date format It is the end time for input JSON
expression false if,then,else if then else condition like “if”: “systolic>80”, “then”: “return “high”;” “else”:”return “low”;”.It can also have nested if else condition like: “if(systolic< 80 && systolic> 50 ) {return “medium”;} else {if(systolic> 20){return”low”;}}”
position rectangle false cordinates with north east and south west It is position based filtering of rectangle geographical area
position circle false coordinates of circle center and radius in mt,mile,km It is position based filtering of circle geographical area
position polygon false coordinates of all polygon points It is position based filtering of polygon geographical area
position geoFencing true YES/NO It is an additional feature which creates an alert on first exit(breach) or entry in enclosed area(above 3) for input SOS JSON.
ObservedProperties false string It is observation output property filtering of type test, quanity and count type
meta-data false string It is observation meta data property filtering of type test, quanity and count type
parameter false string It is observation parameter property filtering of type test, quantity and count type
quality false string It is observation quality property filtering of type test, quantity and count type
output:TopicExchange true string It is the topic exchange to which the output of MR is posted.Output should always be posted to a topic exchange.
output:Topic true string It is the topic name associated with Topic Exchange to which the output of MR is routed.

-
Note:- In the above JSON, the following are the mandatory fields.

One can always choose to leave the feature, sensor and properties field as blank. In this case it will check on these two fields.
If there is no user define Topic name, it will be created automatically as following convention:

Note- “parallelismFactor” is an optional field. If not defined it takes the default value as 1. It accepts value in between 1 to 10. It helps to increase the throughput of the rule if it takes a long time.

Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

6.3. Get List of Routing Rules

It describes (lists) all the routing rules created by a particular tenant.

curl -X GET "http://<domain name>/MessageRouting/v2.0/routingRules"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

[{
        "Status": "Created",
        "rule_id": 461,
        "RuleName": "TEST RULE",
        "RuleDescription": "TEST RULE",
        "parallelismFactor": 1,
        "input": {
            "DirectExchange": "Direct.Exchange",
            "RoutingKey": "key#test"
        },
        "params": [{
                "name": "feature",
                "value": "health*"
            },
            {
                "name": "sensorID",
                "value": "^[a-zA-Z0-9]*$"
            },
            {
                "name": "time",
                "value": {
                    "starttime": "23-JUL-2013 15:30:00 IST",
                    "endtime": "24-JUL-2013 15:30:00 IST"
                }
            },
            {
                "name": "expression",
                "value": {
                    "if": "",
                    "then": "",
                    "else": ""
                }
            },
            {
                "name": "ObservedProperties",
                "value": [{
                    "name": "systolic",
                    "value": "!(10,20)",
                    "type": "quantity",
                    "operator": ""
                }]
            }
        ],
        "output": {
            "TopicExchange": "testTopic",
            "Topic": "test.*"
        }
    },
    {
        "Status": "Stopped",
        "rule_id": 341,
        "RuleName": "R99",
        "RuleDescription": "R99",
        "parallelismFactor": 1,
        "input": {
            "DirectExchange": "Direct.Exchange",
            "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc="
        },
        "params": [{
                "name": "feature",
                "value": ""
            },
            {
                "name": "sensorID",
                "value": "sensor2"
            },
            {
                "name": "time",
                "value": {
                    "starttime": "",
                    "endtime": ""
                }
            },
            {
                "name": "expression",
                "value": {
                    "if": "temp>80",
                    "then": "return \"high \";",
                    "else": "return \"low \";"
                }
            },
            {
                "name": "ObservedProperties",
                "value": [{
                        "name": "diastolic",
                        "value": "90",
                        "type": "quantity",
                        "operator": ">"
                    },
                    {
                        "name": "systolic",
                        "value": "80",
                        "type": "quantity",
                        "operator": "!="
                    }
                ]
            }
        ],
        "output": {
            "TopicExchange": "test123",
            "Topic": "test"
        }
    }
]

HTTP Request

GET http://<domain name>/MessageRouting/v2.0/routingRules?RuleName={RuleName}&RuleDescription={RuleDescription}

Parameter Required Values Description
RuleName false string Filter by rule name.
RuleDescription false string Filter by rule description.
Status Codes Message
200 Ok
400 Inavalid request
403 Forbidden:Invalid API Key

6.4. Describe a Routing Rule

It describes a routing rule based upon a particular rule ID.

curl -X GET "http://<domain name>/MessageRouting/v2.0
/routingRules/10821"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Status": "Created",
    "rule_id": 462,
    "RuleName": "testMeta25",
    "RuleDescription": "testMeta25",
    "parallelismFactor": 3,
    "input": {
        "DirectExchange": "Direct.Exchange",
        "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc="
    },
    "params": [{
            "name": "feature",
            "value": "health*"
        },
        {
            "name": "sensorID",
            "value": "testSMeta"
        },
        {
            "name": "time",
            "value": {
                "starttime": "23-JUL-2013 15:30:00 IST",
                "endtime": "24-JUL-2013 15:30:00 IST"
            }
        },
        {
            "name": "expression",
            "value": {
                "if": "",
                "then": "",
                "else": ""
            }
        },
        {
            "name": "ObservedProperties",
            "value": [{
                "name": "temp",
                "value": "30",
                "type": "quantity",
                "operator": ">"
            }]
        },

        {
            "name": "meta-data",
            "value": [{
                    "name": "speedometer-version1",
                    "value": "^abc$",
                    "type": "text",
                    "operator": ""
                },
                {
                    "name": "speedometer-version",
                    "value": "^xyz$",
                    "type": "text",
                    "operator": ""
                }
            ]
        }
    ],
    "output": {
        "TopicExchange": "testExchange",
        "Topic": "testMeta25.*"
    }
}

HTTP Request

GET http://<domain name>/MessageRouting/v2.0/routingRules/{rule_id}

URL Parameters

Parameter Required Values Description
rule_id true string List the routing rules with the given rule ID created by a tenant

Note - “parallelismFactor” shows how many routes are running in parallel. If there are no meta-data defined in the rule, its tag will not appear in the JSON.

Status Codes Message
200 Ok
400 Inavalid request
403 Forbidden:Invalid API Key

6.5. Update a Routing Rule

This will update a rule based on the rule ID. A tenant can update his/her routing rules for future use.

curl -X PUT -H "Content-Type: application/json" 
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
--data @body.json http://<domain name>/MessageRouting/v2.0
/routingRules/141

body.json contains input JSON request like below (same as create JSON)

{
    "RuleName": "MR demo rule",
    "RuleDescription": "MR demo rule for API",
    "parallelismFactor": "2",
    "input": {
        "DirectExchange": "Direct.Exchange",
        "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc="
    },
    "params": [
        {
            "name": "feature",
            "value": "room1"
        },
        {
            "name": "sensorID",
            "value": "NEXUS1"
        },
        {
            "name": "time",
            "value": {
                "starttime": "1-JAN-2014 15:30:00 IST",
                "endtime": "31-DEC-2014 15:30:00 IST"
            }
        },
        {
            "name": "expression",
            "value": {
                "if": "systolic>80",
                "then": "return \"high\";",
                "else": "if ( systolic< 80 && systolic > 50 ) {return \"medium\";} else {if (systolic > 20){return \"low\";}"
            }
        },
        {
            "name": "position",
            "type": "rectangle",
            "geoFencing": "NO",
            "value": {
                "points": [
                    {
                        "x": "5",
                        "y": "5"
                    },
                    {
                        "x": "20",
                        "y": "20"
                    }
                ]
            }
        },
        {
            "name": "ObservedProperties",
            "value": [
                {
                    "name": "systolic",
                    "type": "quantity",
                    "value": "(40,150)",
                    "operator": ""
                }
            ]
        },
        {
            "name": "meta-data",
            "value": [
                {
                    "name": "length",
                    "type": "count",
                    "value": "50",
                    "operator": ""
                }
            ]
        },
        {
            "name": "parameter",
            "value": [
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        },
        {
            "name": "quality",
            "value": [
                {
                    "name": "",
                    "type": "Text/quantity/count",
                    "value": "",
                    "operator": ""
                }
            ]
        }
    ],
    "output": {
        "TopicExchange": "testExchange",
        "Topic": "android1"
    }
}

HTTP Request

PUT http://<domain name>/MessageRouting/v2.0/routingRules/{rule_id}

URL Parameters

Parameter Required Values Description
rule_id true string Updates routing rules with the given rule_id created by a tenant

Body Parameters

Parameter Required Values Description
RuleName true string RuleName should be unique for every rule
RuleDescription true string It should be a short description about the rule functionality
parallelismFactor true numeric value it should be in the range of 1-10 which defines the parallelism factor
Input:type false string Type of the exchange through which the input JSON is received in MR. It can be Direct/Topic/MQ. Default is Direct.
Input:DirectExchange false string Name of the direct/topic exchange depending on type. Default is Direct.Exchange.
Input:RoutingKey false string It is the routing/topic key through which the data is routed to direct/topic exchange of MR depending on the type. Default is unique key assign to per tenant.
Input:MQName false string It is the queue name in case type is MQ.
feature false string It is the name of observation feature on which feature based filtering is done
sensorID false string It is the name of observation sensor on which sensor based filtering is done
start time false time with date format It is the start time for input JSON
start time false time with date format It is the end time for input JSON expression false if,then,else if then else condition like “if”: “systolic>80”, “then”: “return “high”;” “else”:”return “low”;”.It can also have nested if else condition like: “if(systolic< 80 && systolic> 50 ) {return “medium”;} else {if(systolic> 20){return”low”;}}”
position rectangle false cordinates with north east and south west It is position based filtering of rectangle geographical area
position circle false coordinates of circle center and radius in mt,mile,km It is position based filtering of circle geographical area
position polygon false coordinates of all polygon points It is position based filtering of polygon geographical area
position geoFencing true YES/NO It is an additional feature which creates an alert on first exit(breach) or entry in enclosed area(above 3) for input SOS JSON.
ObservedProperties false string It is observation output property filtering of type test, quanity and count type
meta-data false string It is observation meta data property filtering of type test, quanity and count type
parameter false string It is observation parameter property filtering of type test, quantity and count type
quality false string It is observation quality property filtering of type test, quantity and count type
output:TopicExchange true string It is the topic exchange to which the output of MR is posted. Output should always be posted to a topic exchange.
output:Topic true string It is the topic name associated with Topic Exchange to which the output of MR is routed.

-
Note: If the rule is in started condition, then it first stops the rule, updates and starts it automatically. Incase the rule is in created or stopped condition, it would just update the rule. If the user keeps any non mandatory field as blank then during rule update, those particular fields would not be updated.

Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

6.6. Get Looping Status amongst the List of Rules

Rules can take input, queue from topic along with direct type. There is a chance of loop forming amongst rules where input and output endpoints are of topic type.

It detects such loops and enables the user to stop the rules which causes such loop formation. Internally it creates a DAG graph among all the rules and then runs DFS (Depth First Search) algorithm to detect the loop.

curl -X GET "http://<domain name>/MessageRouting/v2.0
/routingRules/loop/status"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
    "Result": "Rules does not contains cycle"
}

HTTP Request

GET http://<domain name/MessageRouting/v2.0/routingRules/loop/status?rule_id=[]

URL Parameters

Parameter Required Values Description
rule_id true string List of comma-separated rule id created by a tenant.
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

6.7. Delete a Routing Rule

It deletes a MR routing rule based on the rule ID. The user needs to provide the rule ID in the URL itself. The rules can be deleted only by the owner (tenant) and the owner gets identified by the tenant ID/ API key.

curl -X DELETE "http://<domain name>/MessageRouting/v2.0
/routingRules/141"
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc="

The above command returns the following output JSON response:

{
  "Message": "routing rule successfully deleted!!"
}

HTTP Request

DELETE http://<domain name>/MessageRouting/v2.0/routingRules/{rule_id}

URL Parameters

Parameter Required Values Description
rule_id true string Deletes the routing rule with given rule ID 141

-
Note: If the rule is in started condition, then it first needs to be stopped and then deleted.

Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

7. Statistics

These APIs are used to get the statistic of rules.

7.1. Get Rules Overview

Users can get the details of the number of rules in running, stoped and created state.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/overiew"

The above command returns the following output JSON response:

{
 "Created": 26,
 "Started": 2,
 "Stopped": 4
}

HTTP Request

GET http://<domainname>/MessageRouting/v2.0/overiew

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

7.2. Get Aggregated Statistics for Rules

User can get the detailed statistics of messages processed by a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/statistics?rule_id={rule_id}&start_time={start_time}&end_time={end_time}"

The above command returns the following output JSON response:

{
  "MessageCount": 10,
  "SuccessCount": 5,
  "FailureCount": 5
}

HTTP Request

GET http://<domainname>/MessageRouting/v2.0/statistics?rule_id={rule_id}&start_time={start_time}&end_time={end_time}

Parameter Description
rule_id rule ID of the rule for which the user wants to get the details
start_time starting time of interval for which the user requires statistics
end_time end time of the interval for which the user require statistics

-
Note

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

7.3. Get Statistics for a Rule

Users can get the detailed statistics of messages processed by a specific rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/statistics/{rule_id}"

The above command returns the following output JSON response:

{
 "MessageCount": 5,
 "SuccessCount": 0,
 "FailureCount": 5,
 "AvgHourlyMessageRate": 0.014970059880239521
}

HTTP Request

GET http://<domainname>/MessageRouting/v2.0/statistics/{rule_id}

Parameter Description
rule_id rule ID of the rule for which the user wants to get the details
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

8. Versions

These APIs are used to get the versions of rules.

8.1. Get All Matching Rules

Users can get all the matching rules version for the given conditions.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}"

The above command returns the following output JSON response:


[{
     "rule_id": 61,
     "user_id": null,
     "status": "DELETED",
     "applied_at": "22-Apr-2019 18:01:45.711",
     "version": 2,
     "metadata": null,
     "routingRules": {
         "input": {
             "type": "",
             "MQName": "",
             "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc=",
             "DirectExchange": "Direct.Exchange"
         },
         "rule_id": 61,
         "Status": "Created",
         "output": {
             "Topic": "test1.*",
             "TopicExchange": "testEx2"
         },
         "params": [{
                 "name": "feature",
                 "value": "abc"
             },
             {
                 "name": "sensorID",
                 "value": ""
             },
             {
                 "name": "time",
                 "value": {
                     "endtime": "",
                     "starttime": ""
                 }
             },
             {
                 "name": "expression",
                 "value": {
                     "if": "",
                     "else": "",
                     "then": ""
                 }
             },
             {
                 "name": "ObservedProperties",
                 "value": []
             }
         ],
         "RuleName": "test5",
         "RuleDescription": "test5 for temp",
         "parallelismFactor": 1
     }
 },
 {
     "rule_id": 61,
     "user_id": "abc",
     "status": "CREATED",
     "applied_at": "19-Apr-2019 12:27:53.735",
     "version": 1,
     "metadata": null,
     "routingRules": {
         "input": {
             "type": "",
             "MQName": "",
             "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc=",
             "DirectExchange": "Direct.Exchange"
         },
         "rule_id": 61,
         "Status": "Created",
         "output": {
             "Topic": "test1.*",
             "TopicExchange": "testEx2"
         },
         "params": [{
                 "name": "feature",
                 "value": "abc"
             },
             {
                 "name": "sensorID",
                 "value": ""
             },
             {
                 "name": "time",
                 "value": {
                     "endtime": "",
                     "starttime": ""
                 }
             },
             {
                 "name": "expression",
                 "value": {
                     "if": "",
                     "else": "",
                     "then": ""
                 }
             },
             {
                 "name": "ObservedProperties",
                 "value": []
             }
         ],
         "RuleName": "test5",
         "RuleDescription": "test5 for temp",
         "parallelismFactor": 1
     }
}]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used , kept for future use
routingRules JSON Routing rule JSON.

HTTP Request

http://<domainname>/MessageRouting/v2.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}

Parameter Required Values Description
search_text false string text search based on rule name and description.
start_time false string Applied start datetime (DD-MMM-YYYY HH:mm:ss zzz). Default value Epoch time.
end_time false string Applied end datetime (DD-MMM-YYYY HH:mm:ss zzz). Default is current date and time.

Note: It displays the versions in descending manner based on update time.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

8.2. Get a Version of a Rule

User can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/versions/{rule_id}"

The above command returns output JSON response structured like this:


[
  {
      "rule_id": 1,
      "user_id": "abcd",
      "status": "UPDATED",
      "applied_at": "17-Apr-2019 15:56:03.094",
      "version": 2,
      "metadata": null,
      "routingRules": {
          "input": {
              "type": "",
              "MQName": "",
              "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc=",
              "DirectExchange": "Direct.Exchange"
          },
          "rule_id": 1,
          "Status": "Created",
          "output": {
              "Topic": "test1.*",
              "TopicExchange": "testEx2"
          },
          "params": [{
                  "name": "feature",
                  "value": "abc"
              },
              {
                  "name": "sensorID",
                  "value": ""
              },
              {
                  "name": "time",
                  "value": {
                      "endtime": "",
                      "starttime": ""
                  }
              },
              {
                  "name": "expression",
                  "value": {
                      "if": "",
                      "else": "",
                      "then": ""
                  }
              },
              {
                  "name": "ObservedProperties",
                  "value": []
              }
          ],
          "RuleName": "test1",
          "RuleDescription": "test1-test2",
          "parallelismFactor": 1
      }
  },
  {
      "rule_id": 1,
      "user_id": "abcd",
      "status": "CREATED",
      "applied_at": "17-Apr-2019 12:21:09.831",
      "version": 1,
      "metadata": null,
      "routingRules": {
          "input": {
              "type": "",
              "MQName": "",
              "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc=",
              "DirectExchange": "Direct.Exchange"
          },
          "rule_id": 1,
          "Status": "Created",
          "output": {
              "Topic": "test1.*",
              "TopicExchange": "testEx2"
          },
          "params": [{
                  "name": "feature",
                  "value": "abc"
              },
              {
                  "name": "sensorID",
                  "value": ""
              },
              {
                  "name": "time",
                  "value": {
                      "endtime": "",
                      "starttime": ""
                  }
              },
              {
                  "name": "expression",
                  "value": {
                      "if": "",
                      "else": "",
                      "then": ""
                  }
              },
              {
                  "name": "ObservedProperties",
                  "value": []
              }
          ],
          "RuleName": "test1",
          "RuleDescription": "test1",
          "parallelismFactor": 1
      }
  }
]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON.

HTTP Request

http://<domainname>/MessageRouting/v2.0/versions/{rule_id}

Parameter Required Values Description
rule_id true number routing rule id.

-
Note - It displays the versions in descending manner based on
update time.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

8.3. Get All Versions of a Rule

Users can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/MessageRouting/v2.0/versions/{rule_id}/{version}"

The above command returns the following output JSON response:

{
  "rule_id": 1,
  "user_id": "abcd",
  "status": "UPDATED",
  "applied_at": "17-Apr-2019 15:56:13.211",
  "version": 3,
  "metadata": null,
  "routingRules": {
      "input": {
          "type": "",
          "MQName": "",
          "RoutingKey": "uKK6WjaZZnnYBj1G6rONQgNAIuc=",
          "DirectExchange": "Direct.Exchange"
      },
      "rule_id": 1,
      "Status": "Created",
      "output": {
          "Topic": "test1.*",
          "TopicExchange": "testEx2"
      },
      "params": [{
              "name": "feature",
              "value": "abc"
          },
          {
              "name": "sensorID",
              "value": ""
          },
          {
              "name": "time",
              "value": {
                  "endtime": "",
                  "starttime": ""
              }
          },
          {
              "name": "expression",
              "value": {
                  "if": "",
                  "else": "",
                  "then": ""
              }
          },
          {
              "name": "ObservedProperties",
              "value": []
          }
      ],
      "RuleName": "test1",
      "RuleDescription": "test1-test3",
      "parallelismFactor": 1
  }
}

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON.

HTTP Request

http://<domainname>/MessageRouting/v2.0/versions/{rule_id}/{version}

Parameter Required Values Description
rule_id true number routing rule ID.
version true number routing rule’s version number.
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

9. Files

These APIs are used to export and import rules in a file (JSON/ zipped format).

9.1. Download Rule Files

Users can download all or selective rules in a file.

curl -X GET --header 'Accept: application/zip' --header 'x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****' 'http://<domainname>/MessageRouting/v2.0/files/export/rules?rule_id={rule_id}&format={format}'

The above command returns the download file link
http://%3Cdomain%3E/mr_rules_06-Sep-2019_18:47:59.zip

HTTP Request

http://<domainname>/MessageRouting/v2.0/files/export/rules?rule_id={rule_id}&format={format}

Parameter Required Values Description
rule_id false Array[int] List of comma-separated rule ID. Default is all the rules.
format false string File format (zip or JSON). Default format is zip.

-
Note: List of rule IDs are passed as query parameters, its default size is 8192 bytes. In case it does not fit the size, the below HTTP POST method based download API can be used.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

9.2. Create and Download File based on List of Rule IDs

Users can download all or selective rules in a file. Here the list of rule IDs have to be passed as JSON payload. It downloads the rule file in zipped format.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/zip' --header 'x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****' -d '{"rule_id": [ ] }' 'http://<domain>/MessageRouting/v2.0/files/export/rules'

The above command returns download file link
file download link

HTTP Request

http://<domainname>/MessageRouting/v2.0/files/export/rules

body.json contains the input JSON request like below :

{
  "rule_id": [
  ]
}

Body Parameters

Parameter Required Values Description
rule_id true Array[int] List of comma-separated rule ID. Keep it blank for all.
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

9.3. Upload Rules File

Users can import all or selective rules from a file. It accept both JSON or zipped file downloaded above.

curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'x-api-key: NZOlaIbIQikF9FodbLsOwNbK****' {"type":"formData"} 'http://<domain>/MessageRouting/v2.0/files/import/rules?rule_id={rule_id}&option={option}'

On success - Output JSON response below:

[
  {
    "rule_id": 41,
    "RuleName": "test3",
    "Status": "Success",
    "Message": "Rules created successfully with rule id: 581 and topic: test1.*"
  },
  {
    "rule_id": 1,
    "RuleName": "test1",
    "Status": "Success",
    "Message": "Rules created successfully with rule id: 582 and topic: test1.*"
  }
]

On error - Output JSON response below:

[
  {
    "rule_id": 41,
    "RuleName": "test3",
    "Status": "Error",
    "Message": "Rule name already exist"
  },
  {
    "rule_id": 1,
    "RuleName": "test1",
    "Status": "Error",
    "Message": "Rule name already exist"
  }
]

Body Parameters

Parameter Required Values Description
rule_id true string Rule ID as in the file to be imported
RuleName true string Rule name as in the file to be imported
Status true string Status of the import. Possible values are error or success.
Message true string Message with imported rule ID in case of success.

-
HTTP Request

http://<domain>/MessageRouting/v2.0/files/import/rules?rule_id={rule_id}&option={option}

Body Parameters

Parameter Required Values Description
rule_id false Array[int] List of comma-separated rule ID. Keep it blank for all.
option false String Possible values are overwritten or skipped. In case of overwrite, if same rule name exist, it will be deleted and the new rule with the same name will be created. In case of skip, the same rule name will be skipped.
rules true file Downloaded file either zipped or JSON format.

-
Note: Rule import checks only rule name, if exists it will be deleted
and a new one with the same name will be created. Rule ID will be
different.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

10. Send Request

10.1. Sends JSON

It allows to publish any valid JSON to direct/topic type of exchanges and also to a queue. It can send single or array of JSON documents. In case of an array of JSON, it streams them internally one by one.

The header of the web service must set to content type application/json along with DirectExchangeName and RoutingKey. There is also type query parameter which specify type of exchange i.e direct or topic or queue.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
-H "RoutingKey: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
-H "DirectExchangeName: Direct.Exchange" 
--data @body.json http://<domain name>/MessageRouting/v2.0
/sendRequest

body.json contains input JSON request like below (as per SOS observation JSON)

{
    "sensor": "TcsApp.22222222.101001111000101",
    "feature": "TCS.111111",
    "position": {
        "referencedFrame": "0",
        "x": "21",
        "y": "11",
        "z": "23"
    },
    "record": [
        {
            "time": "28-Jan-2014 20:15:56 +0530",
            "output": [
                {
                    "name": "session_id",
                    "value": "TCS.111111.28-Jan-2014:19:15"
                },
                {
                    "name": "session_start_time",
                    "value": "28-Jan-2014 19:15:56 +0530"
                },
                {
                    "name": "session_end_time",
                    "value": "28-Jan-2014 20:15:56 +0530"
                },
                {
                    "name": "walk_duration",
                    "value": 1800
                },
                {
                    "name": "running_duration",
                    "value": 1800
                },
                {
                    "name": "walk_distance",
                    "value": 1500
                },
                {
                    "name": "running_distance",
                    "value": 2500
                },
                {
                    "name": "walk_calorie",
                    "value": 10.1
                },
                {
                    "name": "running_calorie",
                    "value": 16.1
                },
                {
                    "name": "walk_steps",
                    "value": 1400
                },
                {
                    "name": "running_steps",
                    "value": 2000
                },
                {
                    "name": "gps_sampling_interval",
                    "value": 100
                }
            ]
        }
    ]
}

Array of JSON document can be send as below:

[
  {
    "version": "1.0.1",
    "observations": [
      {
        "sensor": "NEXUS1",
        "feature": "room1",
        "record": [
          {
            "starttime": "22-AUG-2019 15:30:01 IST",
            "output": [
              {
                "name": "temp",
                "value": "99",
                "type": "quantity"
              }
            ]
          }
        ]
      }
    ]
  },
  {
    "version": "1.0.1",
    "observations": [
      {
        "sensor": "NEXUS1",
        "feature": "room1",
        "record": [
          {
            "starttime": "22-AUG-2019 15:40:01 IST",
            "output": [
              {
                "name": "temp",
                "value": "100",
                "type": "quantity"
              }
            ]
          }
        ]
      }
    ]
  }
]

HTTP Request

POST http://<domain name>/MessageRouting/v2.0/sendRequest

Custom Header Parameters

Parameter Required Values Description
x-api-key true string A mandatory header to pass along with every API call
DirectExchangeName true string Direct Exchange name as mentioned in the routing rule. Default is Direct.Exchange used by SOS
RoutingKey false string Binding key for the message to be published. Default is tenant api-key. Consumer binding key should match with the publisher in order to get the message.
type false string type of exchange and queue , possible values are direct,topic and mq. Default is direct.
Content Type true string application/json

-
Note: MR does not have any control on the input JSON data. The user must check if the date and time format is correct, in case it
does not conform to the format, it will not be be processed. If the time format(00-MMM-YY) is input JSON, MR will be able to process date data
(checking is lenient) as it conform to the correct format after spill
over date & time. Date mentioned with 00 of any month will be treated as the first day of the month and similarly if the hour, minute
and second exceeds their maximum value, it will automatically fall in
the next value of their time stamp.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

10.2. Sends Bulk JSON

It allows to publish SOS formatted JSON (single/bulk) to direct/ topic type of exchanges and also to a queue. It can send single or array of JSON documents. In case of an array of JSON, it streams them internally one by one.

The header of the web service must set to content type application/json along with DirectExchangeName and RoutingKey. There is also type query parameter which specify the type of exchange i.e direct or topic or queue.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
-H "RoutingKey: uKK6WjaZZnnYBj1G6rONQgNAIuc=" 
-H "DirectExchangeName: Direct.Exchange" 
--data @body.json http://<domain name>/MessageRouting/v2.0
/sendRequest

body.json contains input JSON request like below (as per SOS observation JSON)

{
  "version": "1.0.1",
  "observations": [
    {
      "sensor": "NEXUS1",
      "feature": "room1",
      "record": [
        {
          "starttime": "1-JAN-2014 15:30:01 IST",
          "output": [
            {
              "name": "temp",
              "value": "99",
              "type": "quantity"
            }
          ]
        }
      ]
    }
  ]
}

Array of JSON document can be send as below :

{
  "version": "1.0.1",
  "observations": [
    {
      "sensor": "NEXUS1",
      "feature": "room1",
      "record": [
        {
          "starttime": "1-JAN-2014 15:30:01 IST",
          "output": [
            {
              "name": "temp",
              "value": "99",
              "type": "quantity"
            }
          ]
        }
      ]
    },
    {
      "sensor": "NEXUS1",
      "feature": "room1",
      "record": [
        {
          "starttime": "1-JAN-2014 15:30:01 IST",
          "output": [
            {
              "name": "temp",
              "value": "100",
              "type": "quantity"
            }
          ]
        }
      ]
    }
  ]
}

HTTP Request

POST http://<domain name>/MessageRouting/v2.0/sendRequest/bulk

Custom Header Parameters

Parameter Required Values Description
x-api-key true string A mandatory header to pass along with every API call
DirectExchangeName true string Direct Exchange name as mentioned in the routing rule. Default is Direct.Exchange used by SOS
RoutingKey false string Binding key for the message to be published. Default is tenant api-key. Consumer binding key should match with the publisher in order to get the message.
type false string type of exchange and queue, possible values are direct, topic and mq. Default is direct.
Content Type true string application/json
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

11. Limitation and Known Issues

The following are the limitations:

1) In memory DB support does not support multi-tenancy, user needs to form a unique URN based key in order to write to DB.
<api key>: <name space>:keyname

2) If-then-else condition parameters works on observed properties, sensor name, feature, start time, end time of a sensor. It does not work on meta-data/ quality/ parameters currently.

HTTP Response

This error section is stored in a separate file in includes/_errors.md. Whiteboard allows you to optionally separate out your documents into many files. Save them to the includes folder and add them to the top of your index.md‘s frontmatter. Files are included in the order listed.

Complex Event Processing

1. Introduction

Complex Event Processing (CEP) is a rule based service that allows data from multiple streams to combine and processes them in real time based on user-defined rules to detect patterns and produce events or alarms. It consumes data emitted by the Message Routing service based on routing rules and processes that data. The final output gets written to a message queue or topic exchange.

CEP not only makes it possible to process current data but also historical data. Event streams are collected in user defined ‘windows’ and conditions or aggregations are checked on these windows of data streams.

Below are the three module involved in any CEP services.

2. Reference Documents

Complex Event Processing Service Concept Guide

Complex Event Processing Service User’s Guide

Event selections

Operations Events

3. RESTful resources available in Complex Event Processing

  1. Compute Sources
  2. Compute Templates
  3. Compute Sinks
  4. Cluster Resources
  5. Compute Nodes
  6. User
  7. Statistics
  8. Versions

3.1. Authentication

CEP expects the API key to be included in all the API requests to the server in a header.

3.2. Request Headers

Header Description Sample Value
x-user-key Valid user key of the user under a valid tenant. It is also mandatory in every call. keydemo
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

4. Compute Sources

4.1. Get All Compute Sources

It lists all the available compute sources.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeSources"

The above command returns the following output JSON response:

{
    "sources": [
        {
            "streamName": "s1",
            "cepId": 1687,
            "exchange": "android",
            "topic": "acclight.*"
        },
        {
            "streamName": "s1",
            "cepId": 1759,
            "exchange": "cepTCUPV4",
            "topic": "pattern.*"
        },
        {
            "streamName": "s3",
            "cepId": 1759,
            "exchange": "cepTCUPV4",
            "topic": "pattern3.*"
        },
        {
            "streamName": "s2",
            "cepId": 1759,
            "exchange": "cepTCUPV4",
            "topic": "pattern2.*"
        },
        {
            "streamName": "s2",
            "cepId": 1764,
            "exchange": "android",
            "topic": "accsos23.*"
        }
    ]
}

HTTP Request

GET http://<domain name>/cep/v2.0/computeSources

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

4.2. Describe a Compute Source

It describes a compute source based on a given compute node ID

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeSources/{computeId}"

The above command returns the following output JSON response:

{
  "source": [
    {
      "streamName": "s1",
      "exchange": "patternMatch",
      "topic": "pattern.*",
      "property": "Systolic"
    },
    {
      "streamName": "s2",
      "exchange": "patternMatch",
      "topic": "pattern2.*",
      "property": "Systolic"
    },
    {
      "streamName": "s2",
      "exchange": "patternMatch",
      "topic": "pattern2.*",
      "property": "Pulse"
    }
  ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/computeSources/{computeId}

URL Parameters

Parameter Description
computeId The ID of the compute node

-
Note - Users can only view it. It is the output of the message router rules. i.e Topic exchange with topic

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

5. Compute Sinks

5.1. Get All Compute Sinks

It lists all the available compute sinks. This can either be message queue or topic exchange.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeSinks"

The above command returns the following output JSON response:

{
    "sinks": [
        {
            "cepId": 1687,
            "sinkType": "MQ",
            "QueueName": "aggregationMQ1"
        },
        {
            "cepId": 1761,
            "sinkType": "MQ",
            "QueueName": "MQcep2TCUPV4"
        },
        {
            "cepId": 1764,
            "sinkType": "Topic",
            "exchangeName": "android",
            "topicName": "accsosoutputbefore1.*"
        }
    ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/computeSinks

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

5.2. Describe a Sink based on Compute ID

It describes a compute sink based on a given compute node with ID by the user.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeSinks/{computeId}"

The above command returns the following output JSON response:

{
    "sink": [
        {
            "sinkType": "Topic",
            "exchangeName": "android",
            "topicName": "accsosoutputbefore1.*"
        }
    ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/computeSinks/{computeId}

URL Parameters

Parameter Description
computeId The ID of the compute node

-

Note - Users can only view it from here.
Message router service has to be used to create a topic exchange with a topic.
Message queue service has to be used to create a message queue.

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

6. Compute Templates

6.1. Get All Compute Templates

It lists all the available compute templates.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeTemplates"

The above command returns the following output JSON response:

{
  "compute-list": [
    {
      "templateName": "EventPatternMatching",
      "templateDesc": "Matches event pattern with situation  condition"
    },
    {
      "templateName": "MultipleStreamAggregation",
      "templateDesc": "Aggregation with multiple streams fields"
    },
    {
      "templateName": "MultipleStreamJoining",
      "templateDesc": "Joining multiple stream with common fields"
    }
  ]
}

HTTP Request

GET http://<domain name>/cep/v2.0/computeTemplates

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

6.2. Describe a Compute Template

It describes a compute template based on a given template name by the user.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeTemplates/{name}"

The above command returns the following output JSON response:

{
    "templatename": "MultipleStreamAggregation",
    "templatedesc": "Aggregation with multiple streams fields",
    "inputtype": "topic",
    "outputtype": "MQ/Topic",
    "function-list": [],
    "param-list": [
      {
        "argname": "windowType",
        "argdesc": "It can be time or count",
        "argtype": "Quantity"
    }, 
    {
        "argname": "windowUnit",
        "argdesc": "It describes the unit of window.It can be sec,min,hour",
        "argtype": "Quantity"
    }, 
    {
        "argname": "detectionProcess",
        "argdesc": "Process of detecting a situation condition",
        "argtype": "Quantity"
    }, 
    {
        "argname": "lifeSpanInitiator",
        "argdesc": "Event that initiates a lifespan",
        "argtype": "Quantity"
    }, 
    {
        "argname": "lifeSpanTerminator",
        "argdesc": "Event that closes lifespan",
        "argtype": "Quantity"
    }, 
    {
        "argname": "windowSize",
        "argdesc": "Describes the length of window",
        "argtype": "Quantity"
    }, 
    {
        "argname": "aggregationFunctions",
        "argdesc": "It describes the aggregation functions ",
        "argtype": "Quantity"
    }, 
    {
        "argname": "groupByField",
        "argdesc": "group By feature or sensor or featureAndSensor",
        "argtype": "Quantity"
    }, 
    {
        "argname": "windowEvictionPolicy",
        "argdesc": "sliding or tumbling",
        "argtype": "Quantity"
    }
   ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/computeTemplates/{name}

URL Parameters

Parameter Description
name The name of the compute template

-
Note - Templates are predefined by the TCUP administrator, users cannot create or delete it.

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

7. Cluster Resources

7.1. Get Cluster Summary Details

It lists a set of cluster resources. It shows the resources available in CEP cluster.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/clusterResources"

The above command returns the following output JSON response:

{
  "totalWorkerNumber": 20,
  "usedWorkerNumber": 14,
  "freeWorkerNumber": 6
}

HTTP Request

GET http://<domainname>/cep/v2.0/clusterResources

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

7.2. Get Compute Node Summary

It describes cluster resource based on a compute node ID given by user.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/clusterResources/{computeid}"

The above command returns the following output JSON response:

{
  "supervisorNodeNumber": 1,
  "currentParallelismFactor": 1,
  "maximumParallelismFactor": 2
}

HTTP Request

GET http://<domainname>/cep/v2.0/clusterResources/{computeid}

URL Parameters

Parameter Description
computeId The ID of the compute node

-

Note - Users can only view it. They cannot upgrade/degrade CEP cluster resources. If the cluster has free resources, users can add the free resources to a compute node using rebalance() API.

Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

8. Compute Nodes

8.1. Create a Compute Node

It creates a compute node based on a JSON format given by the user.

CEP functionality are provided in terms of templates. Currently three templates mentioned below are supported:

Multiple Stream Joining/ Filtering Template

This template helps to filter multiple streams and multiple fields’ events (data). It also helps to join multiple streams of data using a common field.

Event Pattern Matching Template

This template helps to detect the event patterns of multiple streams and then it detects situation if a pattern matches.

Multiple Stream Aggregation Template

This template helps to detect the event patterns of multiple streams and then it detects situations if the pattern matches.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json http://<domainname>/cep/v2.0/computeNodes

Example: body.json contains input JSON request like below:

{
    "compName": "MulStrmJoinTest1",
    "tmplname": "MultipleStreamJoining",
    "params": [
        {
            "name": "detectionProcess",
            "value": "immediate"
        },
        {
            "name": "lifeSpanInitiator",
            "value": "startup"
        },
        {
            "name": "lifeSpanTerminator",
            "value": "forever"
        },
        {
            "name": "situation",
            "value": "(Curr.s1.Systolic ==Curr.s2.Systolic) && (Curr.s1.Systolic == Curr.s3.Systolic)"
        },
        {
            "name": "windowSize",
            "value": "5"
        },
        {
            "name": "windowType",
            "value": "count"
        },
        {
            "name": "windowUnit",
            "value": ""
        },
        {
            "name": "groupByField",
            "value": "feature"
        },
        {
            "name": "windowEvictionPolicy",
            "value": "sliding"
        }
    ],
    "featurelist": [
        "4374734"
    ],
    "input": [
        {
            "streamName": "s1",
            "exchangeName": "patternMatch",
            "topicName": "pattern.*",
            "checkProperties": [
                "Systolic"
            ]
        },
        {
            "streamName": "s2",
            "exchangeName": "patternMatch",
            "topicName": "pattern2.*",
            "checkProperties": [
                "Pulse",
                "Systolic"
            ]
        },
        {
            "streamName": "s3",
            "exchangeName": "patternMatch",
            "topicName": "pattern3.*",
            "checkProperties": [
                "Diastolic",
                "Systolic"
            ]
        }
    ],
    "output": [
        {
            "outputType": "MQ",
            "QueueName": "joinMQ1"
        }
    ]
}

The above command returns the following output JSON response:

{
    "name": "MulStrmJoinTest1",
    "computeid": "101",
    "status": "200",
    "message": "successfully created"
}

HTTP Request

POST http://<domain name>/cep/v2.0/computeNodes

Input sample JSON for multiple stream joining template. Please refer to the user manual document for input JSON of other templates.

Body Parameters

Parameter Required Values Description
windowType true time/count window can be either time or count based
windowUnit true sec/min/hour/blank window unit is required for time based window,it will be blank for count based window
windowSize true numeric value value of time or count based window
lifeSpanInitiator true startup Lifespan will start once it is deployed & started on cluster
lifeSpanTerminator true at(60,sec)/forever lifespan will terminate after the specified time or never terminate in case of forever
detectionProcess true immediate/periodic/termination of life span detected immediately/periodically/on termination of life span
situation true any expression Depending on the situation expression content will be joined or filtered
groupByField true feature/sensor/featureAndSensor Output will be grouped by each unique field
windowEvictionPolicy true tumbling/sliding for tumbling whole window will be cleared once filled up,for sliding window will slide by one element once filled up
input true stream name,topicExchange,properties topic Exchange will be input of CEP
output true MQ/Topic output of CEP will be either MQ or TopicExchange
featurelist false list of features List of feature of interest against which situation will be detected.It is an optional field and rules can be created with empty featurelist

-
Note:

Status Codes Message
200 Success:Ok
201 Success:Created
400 Bad request
403 Forbidden:Invalid API Key

8.2. Get List of Available Compute Nodes

It can list all the compute nodes belonging to the user based on their status. Status can be either running/ created/ stopped/ queued.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeNodes"

The above command returns the following output JSON response:

[
    {
        "computeid": "666",
        "computename": "Test32",
        "templatename": "EventPatternMatching",
        "status": "Running",
        "output": 
        {
            "outputType": "MQ",
            "QueueName": "PatternMatchMultipleStrmMQ2"
        }
    },
    {
        "computeid": "667",
        "computename": "Test33",
        "templatename": "MultipleStreamAggregation",
        "status": "Running",
        "output": 
        {
            "outputType": "Topic",
            "exchangeName": "sosTopic",
            "topicName": "sdaf.*"
        }
    }
]

HTTP Request

GET http://<domain name>/cep/v2.0/computeNodes

Query Parameters

Parameter Required Values Description
status false string Lists all the compute nodes belonging to the user based on their status
RuleName false string Filters by rule name
Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

8.3. Describe Compute Node based on Compute ID

It describes a compute node based on a compute node ID given by the user.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeNodes/{computeid}"

The above command returns the following output JSON response:

{
    "compName": "MulStrmAggregationTest1",
    "Cluster": true,
    "tmplname": "MultipleStreamAggregation",
    "params": [
        {
            "name": "detectionProcess",
            "value": "immediate"
        },
        {
            "name": "lifeSpanInitiator",
            "value": "startup"
        },
        {
            "name": "windowSize",
            "value": "1"
        },
        {
            "name": "windowType",
            "value": "count"
        },
        {
            "name": "windowUnit",
            "value": ""
        },
        {
            "name": "lifeSpanTerminator",
            "value": "forever"
        },
        {
            "name": "aggregationFunctions",
            "value": " print(\"WindowMaxPulse\", WindowMax.s2.Pulse); print(\"WindowMinSystolic\", WindowMin.s1.Systolic); print(\"RunningSumDiastolic \",RunningSum.s3.Diastolic); "
        },
        {
            "name": "groupByField",
            "value": "feature"
        },
        {
            "name": "windowEvictionPolicy",
            "value": "tumbling"
        }

    ],
    "featurelist": [
        "4374734"
    ],
    "input": [
        {
            "streamName": "s1",
            "exchangeName": "patternMatch",
            "topicName": "pattern.*",
            "checkProperties": [
                "Systolic"
            ]
        },
        {
            "streamName": "s2",
            "exchangeName": "patternMatch",
            "topicName": "pattern2.*",
            "checkProperties": [
                "Pulse"
            ]
        },
        {
            "streamName": "s3",
            "exchangeName": "patternMatch",
            "topicName": "pattern3.*",
            "checkProperties": [
                "Diastolic"
            ]
        }
    ],
    "output": [
        {
            "outputType": "MQ",
            "QueueName": "aggregationMQ1"
        }
    ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/computeNodes/{computeid}

URL Parameters

Parameter Description
computeId The ID of the compute node
Status Codes Message
200 Ok
400 Invalid Request
403 Forbidden:Invalid API Key

8.4. Update a Compute Node for a Given Compute Node ID

This API is used to update a compute node based on a JSON format given by the user. User needs to stop the compute node if it is in running state before updating it and then needs to start the rule after updating.

curl -X PUT -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json http://<domain name>/cep/v2.0/computeNodes/{computeid}

Example: body.json contains the input JSON request like below:

{
    "params": [
        {
            "name": "detectionProcess",
            "value": "immediate"
        },
        {
            "name": "lifeSpanInitiator",
            "value": "startup"
        },
        {
            "name": "lifeSpanTerminator",
            "value": "forever"
        },
        {
            "name": "situation",
            "value": "(Curr.s1.Systolic ==Curr.s2.Systolic) && (Curr.s1.Systolic == Curr.s3.Systolic)"
        },
        {
            "name": "windowSize",
            "value": "5"
        },
        {
            "name": "windowType",
            "value": "count"
        },
        {
            "name": "windowUnit",
            "value": ""
        },
        {
            "name": "groupByField",
            "value": "feature"
        },
        {
            "name": "windowEvictionPolicy",
            "value": "sliding"
        }
    ],
    "featurelist": [
        "4374734"
    ],
    "input": [
        {
            "streamName": "s1",
            "exchangeName": "patternMatch",
            "topicName": "pattern.*",
            "checkProperties": [
                "Systolic"
            ]
        },
        {
            "streamName": "s2",
            "exchangeName": "patternMatch",
            "topicName": "pattern2.*",
            "checkProperties": [
                "Pulse",
                "Systolic"
            ]
        },
        {
            "streamName": "s3",
            "exchangeName": "patternMatch",
            "topicName": "pattern3.*",
            "checkProperties": [
                "Diastolic",
                "Systolic"
            ]
        }
    ],
    "output": [
        {
            "outputType": "MQ",
            "QueueName": "joinMQ1"
        }
    ]
}

The above command returns the following output JSON response:

{
    "name": "MulStrmJoinTest1",
    "computeid": "101",
    "status": "200",
    "message": "successfully updated"
}

HTTP Request

PUT http://<domainname>/cep/v2.0/computeNodes/{computeid}

URL Parameters

Parameter Description
computeId The ID of the compute node

Input sample JSON for multiple stream joining template. Please refer to the user manual document for input JSON of the other templates

Body Parameters

Parameter Required Values Description
windowType true time/count window can be either time or count based
windowUnit true sec/min/hour/blank window unit is required for time based window, it will be blank for count based window
windowSize true numeric value value of time or count based window
lifeSpanInitiator true startup Lifespan will start once it is deployed & started on cluster
lifeSpanTerminator true at(60,sec)/forever lifespan will be terminated after the specified time or never be terminated in case of forever
detectionProcess true immediate/periodic/termination of life span detected immediately/periodically/on termination of life span
situation true any expression Depending on the situation expression content will be joined or filtered
groupByField true feature/sensor/featureAndSensor Output will be grouped by each unique field
windowEvictionPolicy true tumbling/sliding for tumbling whole window will be cleared once filled up,for sliding window will slide by one element once filled up
input true stream name,topicExchange,properties Topic exchange will be input of CEP
output true MQ/Topic output of CEP will be either MQ or TopicExchange
featurelist false list of features List of feature of interest against which situation will be detected.It is an optional field and rules can be created with empty feature list
Status Codes Message
200 Success:Ok
201 Success:Created
400 Bad request
403 Forbidden:Invalid API Key

8.5. Delete a Node for a Given Compute ID

It deletes a compute node based on a compute node ID given by the user.

curl -X DELETE 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeNodes/{computeId}"

The above command returns the following output JSON response:

{
    "compName": "Test5",
    "computeid": "346",
    "message": "successfully deleted",
    "status": "200"
}

HTTP Request

DELETE http://<domainname>/cep/v2.0/computeNodes/{computeid}

URL Parameters

Parameter Description
computeId The ID of the compute node
Status Codes Message
200 Success:Deleted
400 Bad request
403 Forbidden:Invalid API Key

8.6. Start a Compute Node

It starts a compute node based on a compute node ID given by the user.
Maximum parallelism factor will always be set to the number of supervisor nodes present in the cluster at the time of starting of a rule.

curl -X POST
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeNodes/{computeid}/start"

The above command returns the following output JSON response:

{
        "name": "testname",
        "status": "200",
        "message" : "successfully started"
}

HTTP Request

POST http://<domainname>/cep/v2.0/computeNodes/{computeid}/start

URL Parameters

Parameter Description
computeId The ID of the compute node

-
Note:

Status Codes Message
200 Success:OK
201 Success:Started
400 Bad Request
403 Forbidden:Invalid API key

8.7. Stop a Compute Node

It stops a compute node based on a compute node ID given by the user.

curl -X POST
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domain name>/cep/v2.0/computeNodes/{computeid}/stop"

The above command returns the following output JSON response:

{
    "message": "successfully stopped",
    "cepid": "102",
    "status": "200"
}

HTTP Request

POST http://<domainname>/cep/v2.0/computeNodes/{computeid}/stop

URL Parameters

Parameter Description
computeId The ID of the compute node
Status Codes Message
200 Success:OK
201 Success:Started
400 Bad Request
403 Forbidden:Invalid API key

8.8. Rebalance a Compute Node

It rebalances a compute node based on a compute node ID given by user. It is required to upgrade/degrade a computeNode with more/less resources depending on the priority.

Parallelism can be achieved by using rebalance API. Data will be distributed among multiple workerNodes and threads based upon ‘groupByField’ parameter. For example if ‘groupByField’ is a feature then the data will be distributed based on feature and throughput will be increased significantly.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json http://<domainname>/cep/v2.0/computeNode
/{computeid}/rebalance

Example: body.json contains input JSON request like below:


{
     "parallelismFactor":"2"
}

The above command returns the following output JSON response:


{
  "message": "successfully rebalanced",
  "cepid": "1447",
  "status": "200"
}

HTTP Request

POST http://<domainname>/cep/v2.0/computeNodes/{computeid}/rebalance

URL Parameters

Parameter Description
computeId The ID of the compute node

-
Body Parameters

Parameter Required Values Description
parallelismFactor true integer value parallelism is achieved by distributing data among multiple nodes and threads

-
Note - parallelismFactor given by user must not be greater than maximumParallelismFactor which was set during start of compute node.

Status Codes Message
200 Success:OK
201 Success:Started
400 Bad Request
403 Forbidden:Invalid API key

9. Statistics

9.1. Get Rule Details

Users can get the details on number of rules running, stopped and in created state.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domainname>/cep/v2.0/overview"

The above command returns the following output JSON response:

{
   "Created": 34,
   "Running": 2,
   "Stopped": 4
}

HTTP Request

GET http://<domainname>/cep/v2.0/overview

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API key

9.2. Get Rule Statistics Details

Users can get the detailed statistics of messages processed by rules.

curl -X GET 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"
"http://<domainname>/cep/v2.0/statistics?computeid={computeid}"

The above command returns the following output JSON response:

{
   "topologyStatistics": [
   {
       "windowPretty": "10m 0s",
       "window": "600",
       "emitted": 3400,
       "acked": 1500,
       "failed": 0
   }, {
       "windowPretty": "3h 0m 0s",
       "window": "10800",
       "emitted": 30600,
       "acked": 16500,
       "failed": 0
   }, {
       "windowPretty": "1d 0h 0m 0s",
       "window": "86400",
       "emitted": 120500,
       "acked": 50500,
       "failed": 0
   }, {
       "windowPretty": "All time",
       "window": ":all-time",
       "emitted": 120500,
       "acked": 50500,
       "failed": 0
   }
 ]
}

HTTP Request

GET http://<domainname>/cep/v2.0/statistics?computeid={computeid}

URL Parameters

Parameter Description
computeid The ID of the compute node

-
Note:

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API key

10. Versions

10.1. Get All Matching Rules

Users can get all the matching rules version for the given conditions.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/cep/v2.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}"

The above command returns the following output JSON response:


   [{
        "rule_id": 63826,
        "user_id": null,
        "status": "CREATED",
        "applied_at": "16-Aug-2019 09:03:28.740 UTC",
        "version": 1,
        "metadata": null,
        "routingRules": {
            "input": [{
                "topicName": "android1.*",
                "streamName": "s1",
                "exchangeName": "android",
                "checkProperties": [
                    "Temparature"
                ]
            }],
            "output": [{
                "topicName": "aggregationslidingcount1",
                "outputType": "Topic",
                "exchangeName": "android"
            }],
            "params": [{
                    "name": "detectionProcess",
                    "value": "periodic"
                },
                {
                    "name": "lifeSpanTerminator",
                    "value": "forever"
                },
                {
                    "name": "lifeSpanInitiator",
                    "value": "startup"
                },
                {
                    "name": "windowEvictionPolicy",
                    "value": "sliding"
                },
                {
                    "name": "groupByField",
                    "value": "feature"
                },
                {
                    "name": "windowType",
                    "value": "time"
                },
                {
                    "name": "windowUnit",
                    "value": "sec"
                },
                {
                    "name": "windowSize",
                    "value": "60"
                },
                {
                    "name": "slidingInterval",
                    "value": "30"
                },
                {
                    "name": "aggregationFunctions",
                    "value": "print(\"WindowSumTemp\",WindowSum.s1.Temparature);"
                }
            ],
            "status": "Created",
            "Cluster": true,
            "compName": "AggregationSlidingTimeRule1",
            "tmplname": "MultipleStreamAggregation",
            "featurelist": []
        }
    },
    {
        "rule_id": 63825,
        "user_id": null,
        "status": "CREATED",
        "applied_at": "16-Aug-2019 08:57:43.469 UTC",
        "version": 1,
        "metadata": null,
        "routingRules": {
            "input": [{
                "topicName": "android1.*",
                "streamName": "s1",
                "exchangeName": "android",
                "checkProperties": [
                    "Temparature"
                ]
            }],
            "output": [{
                "topicName": "aggregationslidingcount2",
                "outputType": "Topic",
                "exchangeName": "android"
            }],
            "params": [{
                    "name": "detectionProcess",
                    "value": "periodic"
                },
                {
                    "name": "lifeSpanTerminator",
                    "value": "forever"
                },
                {
                    "name": "lifeSpanInitiator",
                    "value": "startup"
                },
                {
                    "name": "windowEvictionPolicy",
                    "value": "sliding"
                },
                {
                    "name": "groupByField",
                    "value": "feature"
                },
                {
                    "name": "windowType",
                    "value": "count"
                },
                {
                    "name": "windowUnit",
                    "value": ""
                },
                {
                    "name": "windowSize",
                    "value": "5"
                },
                {
                    "name": "slidingInterval",
                    "value": "2"
                },
                {
                    "name": "aggregationFunctions",
                    "value": "print(\"WindowSumTemp\",WindowSum.s1.Temparature);"
                }
            ],
            "status": "Created",
            "Cluster": true,
            "compName": "AggregationSlidingCountRule5",
            "tmplname": "MultipleStreamAggregation",
            "featurelist": []
        }
    }
]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used , kept for future use
routingRules JSON Routing rule JSON.

HTTP Request

http://<domainname>/cep/v2.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}

Parameter Required Values Description
search_text false string text search based on rule name and description.
start_time false string Applied start datetime (DD-MMM-YYYY HH:mm:ss zzz). Default value Epoch time.
end_time false string Applied end datetime (DD-MMM-YYYY HH:mm:ss zzz). Default is current date and time.

-
Note:
It displays the versions in a descending manner based on the update time.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API key

10.2. Get All Versions of a Rule

Users can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/cep/v2.0/versions/{rule_id}"

The above command returns the following output JSON response:


  [{
        "rule_id": 63685,
        "user_id": null,
        "status": "UPDATED",
        "applied_at": "10-Jul-2019 09:11:37.022 UTC",
        "version": 2,
        "metadata": null,
        "routingRules": {
            "input": [{
                "topicName": "android1.*",
                "streamName": "s1",
                "exchangeName": "cepdemo",
                "checkProperties": [
                    "temp"
                ]
            }],
            "output": [{
                "topicName": "filter.*",
                "outputType": "Topic",
                "exchangeName": "cepdemo"
            }],
            "params": [{
                    "name": "detectionProcess",
                    "value": "periodic"
                },
                {
                    "name": "windowSize",
                    "value": "2"
                },
                {
                    "name": "windowUnit",
                    "value": ""
                },
                {
                    "name": "windowType",
                    "value": "count"
                },
                {
                    "name": "groupByField",
                    "value": "feature"
                },
                {
                    "name": "lifeSpanInitiator",
                    "value": "startup"
                },
                {
                    "name": "lifeSpanTerminator",
                    "value": "forever"
                },
                {
                    "name": "windowEvictionPolicy",
                    "value": "sliding"
                },
                {
                    "name": "situation",
                    "value": "((Curr.s1.temp - Prev(1).s1.temp)>=0),print(\"prev1sttemp1\",Prev(1).s1.temp);"
                }
            ],
            "status": "Stopped",
            "Cluster": true,
            "compName": "ComponentFilteringSampleRule10719_2",
            "tmplname": "MultipleStreamJoining",
            "featurelist": []
        }
    },
    {
        "rule_id": 63685,
        "user_id": null,
        "status": "CREATED",
        "applied_at": "10-Jul-2019 08:39:22.904 UTC",
        "version": 1,
        "metadata": null,
        "routingRules": {
            "input": [{
                "topicName": "android1.*",
                "streamName": "s1",
                "exchangeName": "cepdemo",
                "checkProperties": [
                    "temp"
                ]
            }],
            "output": [{
                "topicName": "filter.*",
                "outputType": "Topic",
                "exchangeName": "cepdemo"
            }],
            "params": [{
                    "name": "detectionProcess",
                    "value": "periodic"
                },
                {
                    "name": "windowSize",
                    "value": "2"
                },
                {
                    "name": "windowUnit",
                    "value": ""
                },
                {
                    "name": "windowType",
                    "value": "count"
                },
                {
                    "name": "groupByField",
                    "value": "feature"
                },
                {
                    "name": "situation",
                    "value": "((Curr.s1.temp - Prev(1).s1.temp)>=0),print(\"prev1sttemp\",Prev(1).s1.temp);"
                },
                {
                    "name": "lifeSpanInitiator",
                    "value": "startup"
                },
                {
                    "name": "lifeSpanTerminator",
                    "value": "forever"
                },
                {
                    "name": "windowEvictionPolicy",
                    "value": "sliding"
                }
            ],
            "status": "Created",
            "Cluster": true,
            "compName": "ComponentFilteringSampleRule10719_2",
            "tmplname": "MultipleStreamJoining",
            "featurelist": []
        }
    }
]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used , kept for future use
routingRules JSON Routing rule JSON.

-
HTTP Request

http://<domainname>/cep/v2.0/versions/{rule_id}

Parameter Required Values Description
rule_id true number routing rule ID.

-
Note - It displays the versions in a descending manner based on update time.

Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API key

10.3. Get a Version of a Rule

Users can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/cep/v2.0/versions/{rule_id}/{version}"

The above command returns the following output JSON response:

  {
    "rule_id": 63685,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "10-Jul-2019 09:11:37.022 UTC",
    "version": 2,
    "metadata": null,
    "routingRules": {
        "input": [{
            "topicName": "android1.*",
            "streamName": "s1",
            "exchangeName": "cepdemo",
            "checkProperties": [
                "temp"
            ]
        }],
        "output": [{
            "topicName": "filter.*",
            "outputType": "Topic",
            "exchangeName": "cepdemo"
        }],
        "params": [{
                "name": "detectionProcess",
                "value": "periodic"
            },
            {
                "name": "windowSize",
                "value": "2"
            },
            {
                "name": "windowUnit",
                "value": ""
            },
            {
                "name": "windowType",
                "value": "count"
            },
            {
                "name": "groupByField",
                "value": "feature"
            },
            {
                "name": "lifeSpanInitiator",
                "value": "startup"
            },
            {
                "name": "lifeSpanTerminator",
                "value": "forever"
            },
            {
                "name": "windowEvictionPolicy",
                "value": "sliding"
            },
            {
                "name": "situation",
                "value": "((Curr.s1.temp - Prev(1).s1.temp)>=0),print(\"prev1sttemp1\",Prev(1).s1.temp);"
            }
        ],
        "status": "Stopped",
        "Cluster": true,
        "compName": "ComponentFilteringSampleRule10719_2",
        "tmplname": "MultipleStreamJoining",
        "featurelist": []
    }
}

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON.

-
HTTP Request

http://<domainname>/cep/v2.0/versions/{rule_id}/{version}

Parameter Required Values Description
rule_id true number routing rule ID.
version true number routing rule’s version number.
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API key

11. Known Issues & Limitations

Note- NZOlaIbIQikF9FoNbdbLsOwK** must be replaced with the user’s personal API key.

Action Service

1. Introduction

TCUP Action Service is a rule based service which allow users to execute or invoke different types of actions (such as web service invocation, sending notification or alert, storing events in the database etc.) when certain events or conditions are detected on incoming message data from Message Routing or Complex Event Processing services.
This service not only offers few predefined action types which can be invoked through rules but also custom action types which can be defined by the users depending on their respective use cases.

Actions will be configured through rules using REst based web service. Rules will be running as Akka actor on Akka cluster. Each rule will take the topic name with exchange as input or direct exchange or it can also take the message queue.

2. Reference Documents

Action Service Concept Guide

Action Service User’s Guide

3 RESTful resources available in Action Service

  1. Action Rules
  2. Action Type
  3. Mobile Device User
  4. Statistics
  5. User
  6. Versions

3.1. Authentication

Action Service expects the API key to be included in all the API requests to the server in a header.

3.2. Request Headers

Header Description Sample Value
x-user-key Valid user key of the user under a valid tenant. It is also mandatory in every call. keydemo
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

3.3. Status Code

Status Codes Message
200 OK
400 Invalid Request
403 Forbidden:Invalid API Key

4. Action Rules

4.1. Get List of Action Rules

It lists all the available action rules. It is also possible to get all the rule of any specific action type.

curl -X GET "http://<domain name>/ActionModule/v1.0/actionRules"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

Query Parameters

Parameter Required Values Description
action_type false string Lists all the rules specific to a action type

-
The above command returns the following output JSON response:

[
  {
    "RuleId": 2081,
    "RuleName": "ESRegister1",
    "Status": "stopped",
    "RuleDescription": "checking rule",
    "noOfInstance": 3,
    "input": {
      "type": "Direct",
      "exchange": "Direct.Exchange.Register",
      "topic": "testTopic.*",
      "MQName": null
    },
    "actions": [
      {
        "type": "ElasticSearchRegister",
        "parameter": [
          {
            "name": "connectorURL",
            "value": "elasticsearch:9200"
          },
          {
            "name": "connectionTimeout",
            "value": "6000"
          },
          {
            "name": "clusterName",
            "value": "cto_dev_cluster"
          },
          {
            "name": "mappingName",
            "value": "sensors:sensor"
          },
          {
            "name": "indexName",
            "value": "uKK6WjaZZnnYBj1G6rONQgNAIuc="
          },
          {
            "name": "schema",
            "value": "[{\"spec\":{\"sensors\":{\"*\":{\"output\":{\"*\":{\"@type\":\"[&3].output.properties.@name.type\"}}}}},
            \"operation\":\"shift\"},{\"spec\":{\"*\":{\"endtime\":{\"format\":\"dateOptionalTime\",\"type\":\"date\"},
            \"sensor\":{\"type\":\"string\"},\"position_global\":{\"properties\":{\"location\":{\"type\":\"geo_point\"},
            \"altitude\":{\"type\":\"string\"}}},\"starttime\":{\"format\":\"dateOptionalTime\",\"type\":\"date\"},
            \"validUpto\":{\"format\":\"dateOptionalTime\",\"type\":\"date\"},\"privacy\":{\"type\":\"string\"},
            \"composedOfSensors\":{\"type\":\"string\"},\"feature\":{\"type\":\"string\"},\"offering\":{\"type\":\"string\"},
            \"isMobile\":{\"type\":\"string\"},\"position-local\":{\"properties\":{\"name\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"},
            \"type\":{\"type\":\"string\"}}},\"isComposite\":{\"type\":\"string\"}}},\"operation\":\"default\"}]"
          }
        ]
      }
    ]
  },
  {
    "RuleId": 2101,
    "RuleName": "TestRule7",
    "Status": "stopped",
    "RuleDescription": "checking",
    "noOfInstance": 1,
    "input": {
      "type": "topic",
      "exchange": "testTopicExchange1",
      "topic": "testTopic.*",
      "MQName": null
    },
    "actions": [
      {
        "type": "SOS",
        "parameter": [
          {
            "name": "x-api-key",
            "value": "NZOlaIbIQikF9FoNbdbLsOwK9M=",
            "type": "header",
            "dataType": ""
          },
          {
            "name": "content-type",
            "value": "application/json",
            "type": "header",
            "dataType": ""
          },
          {
            "name": "payload",
            "value": "asInput"
          },
          {
            "name": "connectorURL",
            "value": "http://sos:8080/api/sos/v2.0/observations"
          },
          {
            "name": "connectionTimeout",
            "value": "5000"
          }
        ]
      }
    ]
  }
 ]

HTTP Request

GET http://<domain name>/ActionModule/v1.0/actionRules?action_type=<action type name>

4.2. Describe an Action Rule

It describes an action rule based on a given action rule ID.

curl -X GET 
"http://<domain name>/ActionModule/v1.0/actionRules/{rule_id}"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

{
    "RuleId": 2101,
    "RuleName": "TestRule7",
    "Status": "stopped",
    "RuleDescription": "checking",
    "noOfInstance": 1,
    "input": {
      "type": "topic",
      "exchange": "testTopicExchange1",
      "topic": "testTopic.*",
      "MQName": null
    },
    "actions": [
      {
        "type": "SOS",
        "parameter": [
          {
            "name": "x-api-key",
            "value": "NZOlaIbIQikF9FoNbdbLsOwK9M=",
            "type": "header",
            "dataType": ""
          },
          {
            "name": "content-type",
            "value": "application/json",
            "type": "header",
            "dataType": ""
          },
          {
            "name": "payload",
            "value": "asInput"
          },
          {
            "name": "connectorURL",
            "value": "http:sos:8080/api/sos/v2.0/observations"
          },
          {
            "name": "connectionTimeout",
            "value": "5000"
          }
        ]
      }
    ]
  }

HTTP Request

GET http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}

URL Parameters

Parameter Description
rule_id The ID of the action rule

-
Note: Rule ID must be an integer.

4.3. Create an Action Rule

It creates different action rules such as the following:

  1. RDBMS dumping
  2. Callback URL
  3. Push notification to android phone
  4. Posting SOS data to Elastic Search DB
  5. Event push to “syslog” Linux utility
  6. TCUP SOS
  7. Messaging through JMS/MQTT/AMQP
  8. SMS
  9. Email
  10. User plugin invoke (task)
curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json 
"http://<domainname>/ActionModule/v1.0/actionRules"

Example: body.json contains input JSON for RDBMS request as mentioned below:

{
    "RuleName": "TestRule7",
    "RuleDescription": "checking",
    "noOfInstance": "2",
    "input": {
        "type": "topic",
        "exchange": "testTopicExchange1",
        "topic": "testTopic.*",
        "MQName": ""
    },
    "actions": [
        {
        "type": "RDBMS",
        "parameter": [
            {
            "name": "Sensor",
            "value": "observation:sensor",
            "type": "columnName",
            "dataType": "String"
            },
            {
            "name": "Illumination",
            "value": "observations:record:output:Illumination",
            "type": "columnName",
            "dataType": "integer"
            },
            {
            "name": "dbName",
            "value": "ActionModuleTEST"
            },
            {
            "name": "username",
            "value": "postgres"
            },
            {
            "name": "password",
            "value": "postgres"
            },
            {
            "name": "tableName",
            "value": "actionmod333"
            },
            {
            "name": "connectorURL",
            "value": "<ipaddress>:5432"
            },
            {
            "name": "connectionTimeout",
            "value": "5000"
            }
            ]
        }
    ]
}

HTTP Request

POST http://<domainname>//ActionModule/v1.0/actionRules

Parameters

Parameter Description
RuleName It gives unique rule name
RuleDescription It gives the description of the action rule
input type Type of the input can be of three types namely topic,direct and MQ
exchange If the type is topic or direct then exchange name needs to be mentioned here
topic If input type is topic then topic name needs to be mentioned here
MQName If input type is MQ then MQ name needs to be mentioned here
action type action type name needs to be mentioned here
dbName Database name where we want to insert the data
tableName Table name where we want to insert the data
connectorURL Connection url as : where we want to insert data
connectionTimeout Action Service will try to connect database till the time mentioned
username user name of the database where we want to insert the data
password password of the database where we want to insert the data
columnName Column name of the database where we want to insert the data. It has four fields 1) name - It specifies the column name 2) value - mentions the path of the observation data in colon(:)format from where we need to get the data 3) type-columnName 4) dataType - Type of the column

Note:

{ "name": "name of the parameter", "value": "value of parameter / path of the json to find the value ", "type": " type of parameter", "dataType": "data type of parameter" }

4.4. Update an Action Rule

This updates a rule based on the rule ID. A tenant can update his/her routing rules for future use.

curl -X PUT -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json 
"http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}"

Example: Below is the rule JSON to dump topic/message queue data to RDBMS/SOS database.

Example JSON for RDBMS:

{
    "RuleName": "TestRule7",
    "RuleDescription": "checking",
    "noOfInstance": "2",
    "input": {
        "type": "topic",
        "exchange": "testTopicExchange1",
        "topic": "testTopic.*",
        "MQName": ""
    },
    "actions": [
        {
        "type": "RDBMS",
        "parameter": [
            {
            "name": "Sensor",
            "value": "observation:sensor",
            "type": "columnName",
            "dataType": "String"
            },
            {
            "name": "Illumination",
            "value": "observations:record:output:Illumination",
            "type": "columnName",
            "dataType": "integer"
            },
            {
            "name": "dbName",
            "value": "ActionModuleTEST"
            },
            {
            "name": "username",
            "value": "postgres"
            },
            {
            "name": "password",
            "value": "postgres"
            },
            {
            "name": "tableName",
            "value": "actionmod333"
            },
            {
            "name": "connectorURL",
            "value": "<ipaddress>:5432"
            },
            {
            "name": "connectionTimeout",
            "value": "5000"
            }
            ]
        }
    ]
}

HTTP Request

PUT http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}

URL Parameters

Parameter Description
rule_id The ID of the action rule

-

4.5. Delete an Action Rule

It deletes an action rule based on a rule ID given by the user.

curl -X DELETE 
"http://<domain name>/ActionModule/v1.0/actionRules/{rule_id}"
 -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

{
  "Message": "Deletion is successfull"
}

HTTP Request

DELETE http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}

URL Parameters

Parameter Description
rule_id The ID of the action rule

-

Note: The user needs to provide the rule ID in the URL itself. The rules can be deleted only by the owner and the owner can be identified by the tenant ID/ API key.

4.6. Start the Action Rule

It starts an action rule based on a rule ID given by the user.

curl -X POST 
"http://<domain name>/ActionModule/v1.0/actionRules/{rule_id}/start"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

{
  "Message": "Rule started sucessfully"
}

HTTP Request

POST http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}/start

URL Parameters

Parameter Description
rule_id The ID of the action rule

4.7. Stop the Action Rule

It stops an action rule based on a rule ID given by the user.

curl -X POST 
"http://<domain name>/ActionModule/v1.0/actionRules/{rule_id}/stop"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

{
  "Message": "Rule stopped sucessfully"
}

HTTP Request

POST http://<domainname>/ActionModule/v1.0/actionRules/{rule_id}/stop

URL Parameters

Parameter Description
rule_id The ID of the action rule

5. Action Type

5.1. Create an Action Type

This will create a new custom action type. This API will be used by the admin.

curl -X POST -H "x-api-key: admin" -H "Content-Type: application/json" 
--data @body.json 
"http://<domain name>/ActionModule/v1.0/actionType/{actionType}/{className}"

The above command returns the following output JSON response:

{
  "Message": "action type created sucessfully"
}

HTTP Request

POST http://<domainname>/ActionModule/v1.0/actionType/{actionType}/{className}

URL Parameters

Parameter Description
actionType The name of the action type the user wants to create
className Class name of the custom jar created which has method Set_Variable and Action method
JarFile Jar file to be added

Note:

If class is inside a package then we have to mention the path of the whole class including the package name for example if RDBMSAction class is inside a package action then we have to mention the class name as action. RDBMSAction

5.2. Update an Action Type

This will update a custom action type. It can be used to update the binary jar file. This API will be used by the admin.

curl -X POST -H "x-api-key: admin" -H "Content-Type: application/json" 
--data @body.json 
"http://<domain name>/ActionModule/v1.0/actionType/{actionType}/{className}"

The above command returns the following output JSON response:

{
  "Message": "action type updated sucessfully"
}

HTTP Request

PUT http://<domainname>/ActionModule/v1.0/actionType/{actionType}/{className}

URL Parameters

Parameter Description
actionType The name of the action type the user wants to update
className Class name of the custom jar to be updated which has method Set_Variable and Action method
JarFile Jar file to be updated

Note:

If class is inside a package then we have to mention the path of the whole class including the package name for example if RDBMSAction class is inside a package action then we have to mention the class name as action. RDBMSAction

5.3. Update an Action Type with Validation Schema

This will update a custom action type with a validation schema JSON. Validation schema specifies the mandatory and optional parameters of an Action type. This API will be used by the admin.

curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'x-api-key: Admin' -d '{ \ 
   "mandatory": [ \ 
     { \ 
       "name": " ", \ 
       "dataType": " " \ 
     } \ 
   ], \ 
   "optional": [ \ 
     { \ 
       "name": " ", \ 
       "value": " ", \ 
       "type": " ", \ 
       "dataType": " " \ 
     } \ 
   ] \ 
 }' 'https://<domain name>/ActionModule/v1.0/actionTypes/{type}'

The above command returns the following output JSON response:

{
  "Message": "action type updated successfully"
}

HTTP Request

PUT http://<domainname>/ActionModule/v1.0/actionType/{type}

URL Parameters

Parameter Description
type The name of the action type the user wants to update
Validation Json Validation JSON

Note:

This API is an optinal, In case it is not updated , it will be not be checked during rule creation.

5.4. Get List of Action Type

This will give the list of action types.

curl -X GET 
"http://<domain name>/ActionModule/v1.0/actionType"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

[
  {
    "actionId": 1,
    "actionType": "syslog",
    "jarName": "SYSLOG.jar",
    "className": "SYSLOG"
  },
  {
    "actionId": 61,
    "actionType": "ElasticSearchRegister",
    "jarName": "ESREGISTRATION.jar",
    "className": "ESREGISTRATION"
  },
  {
    "actionId": 81,
    "actionType": "ElasticSearchInsert",
    "jarName": "ESInsert.jar",
    "className": "ESInsert"
  }
 ]

HTTP Request

GET http://<domainname>/ActionModule/v1.0/actionType

5.5. Describe an Action Type

This will provide the details of the action type.

curl -X GET 
"http://<domain name>/ActionModule/v1.0/actionType/{actionType}"
  -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****"

The above command returns the following output JSON response:

[
  {
    "actionId": 1,
    "actionType": "syslog",
    "jarName": "SYSLOG.jar",
    "className": "SYSLOG"
  }
 ]

HTTP Request

GET http://<domainname>/ActionModule/v1.0/actionType/{actionType}

URL Parameters

Parameter Description
actionType Action type name

5.6. Deletes an Action Type

This will delete an action type based on the action type name.

curl -X DELETE 
"http://<domain name>/ActionModule/v1.0/actionType/{actionType}"
  -H "x-api-key: admin"

The above command returns the following output JSON response:

{
  "Message": "action type delete sucessfully"
}

HTTP Request

DELETE http://<domainname>/ActionModule/v1.0/actionType/{actionType}

URL Parameters

Parameter Description
actionType Action type name

6. Mobile Device User

These APIs will be used to register mobile devices, describe and delete details in Action Service.

6.1. Create a Mobile Device User

This will register a new mobile device user.

curl -X POST -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json 
"http://<domainname>/ActionModule/v1.0/mobileDeviceUser"

Example: body.json contains the input JSON request like below:

{
  "User_Id": "Nayan",
  "Secret_Key": "Google registration key",
  "Server_Name": "Google",
  "Server_Key": "Google project key"
}

The above command returns the following output JSON response:

{
  "Message": "Mobile device registration successful"
}

HTTP Request

POST http://<domainname>/ActionModule/v1.0/mobileDeviceUser

Note : Google registration key will be generated when a mobile device registers with the Google server.

6.2. Update a Mobile Device User

This will update a mobile device user.

curl -X PUT -H "Content-Type: application/json" 
-H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
--data @body.json 
"http://<domainname>/ActionModule/v1.0/mobileDeviceUser/{user_id}"

body.json contains the input JSON request like below:

 {

  "Secret_Key": "Google registration key",
  "Server_Name": "Google",
  "Server_Key": "Google project key"

}

The above command returns the following output JSON response:

{
  "Message": "Mobile device registration successfully updated"
}

HTTP Request

PUT http://<domainname>/ActionModule/v1.0/mobileDeviceUser/{user_id}

URL Parameters

Parameter Description
user_id mobile device user ID

6.3. Get User Details

This will give the list of mobile device users.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/mobileDeviceUser?user_id=subrata"

The above command returns the following output JSON response:

[
  {
    "user_id": "subrata",
    "server_key": "AIzaSyDy90au7ZSogroH6HcFvnKRDJG48E3A6ZU",
    "secret_key": "APA91bE8kDw2CGSrYq2DljBAuv4RIWt_9d3_ytLgW4k3OCinYKyVy0-bjYuw92MU1bjc3qRo3Geog0Ye9TtWqEcy-C_ieg4gO2CA_w1RJeCh-etRWGcM1txNbrrdofQ1RfhFFYajGKA4",
    "server_name": "GoogleGCM"
  }
]

HTTP Request

GET http://<domainname>/ActionModule/v1.0/mobileDeviceUser?user_id=subrata

Note: If the user_id is not mentioned as the query parameter, then it will give all the user details.

Query Parameters

Parameter Required Values Description
user_id false string mobile device user ID

6.4. Delete a Mobile Device User

This will delete mobile device users based on the user IDs.

curl -X DELETE -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/mobileDeviceUser/{user_id}"

The above command returns the following output JSON response:

{
  "Message": "user id is deleted successfully"
}

HTTP Request

DELETE http://<domainname>/ActionModule/v1.0/mobileDeviceUser/{user_id}

7. Statistics

7.1. Get All Rule Details

Users can get the details of the number of rules in running, stopped and created state.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/ruleDetails"

The above command returns the following output JSON response:

{
    "Created": 3,
    "Started": 10,
    "Stopped": 21
}

HTTP Request

GET http://<domainname>/ActionModule/v1.0/ruleDetails

7.2. Get All Rule Statistics

Users can get the detailed statistics of messages processed by rules.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/statistics?rule_id={rule_id}&start_time={start_time}&end_time={end_time}"

The above command returns the following output JSON response:

{
    "MessageCount": 22,
    "SuccessCount": 15,
    "FailureCount": 7
}

HTTP Request

GET http://<domainname>/ActionModule/v1.0/statistics?rule_id={rule_id}&start_time={start_time}&end_time={end_time}

Parameter Description
rule_id rule ID of the rule for which we want to get the details
start_time starting time of the interval for which the user requires the statistics
end_time end time of the interval for which the user requires the statistics

-
Note

7.3. Get a Rule Statistics

Users can get the detailed statistics of the message processed by a specific rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/statistics/{rule_id}"

The above command returns the following output JSON response:

{
    "MessageCount": 3,
    "SuccessCount": 2,
    "FailureCount": 1,
    "AvgHourlyMessageRate": 0.00035444234404536864
}

HTTP Request

GET http://<domainname>/ActionModule/v1.0/statistics/{rule_id}

Parameter Description
rule_id rule ID of the rule for which the user wants the details

8. Versions

8.1. Get All Matching Rules

Users can get all the matching rules’ version for the given conditions.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}"

The above command returns the following output JSON response:


[
  {
    "rule_id": 421,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "19-Aug-2019 18:26:02.911",
    "version": 2,
    "metadata": null,
    "routingRules": {
      "input": {
        "type": "topic",
        "topic": "testESTopic.*",
        "MQName": "",
        "exchange": "testTopicExchange"
      },
      "RuleId": 421,
      "Status": "Running",
      "actions": [
        {
          "type": "ESINSERT",
          "parameter": [
            {
              "name": "connectorURL",
              "value": "elasticsearch:9200"
            },
            {
              "name": "connectionTimeout",
              "value": "6000"
            },
            {
              "name": "clusterName",
              "value": "my_cluster_name"
            },
            {
              "name": "mappingName",
              "value": "observations:sensor"
            },
            {
              "name": "rootNode",
              "value": "observations"
            },
            {
              "name": "indexName",
              "value": "test"
            },
            {
              "name": "schema",
              "value": "[{\"operation\":\"shift\",\"spec\":{\"record\":{\"*\":{\"output\":{\"*\":{\"@value\":\"[&3].@name\"}},\"checktime1\":\"[&1].checktime1\",\"checktime\":\"[&1].checktime\",\"@(2,feature)\":\"[&1].feature\",\"endtime\":\"[&1].endtime\",\"starttime\":\"[&1].starttime\",\"@(2,sensor)\":\"[&1].sensor\",\"@(3,sensor)\":\"[&1].category\",\"@(2,offering)\":\"[&1].offering\"}}}}]"
            },
            {
              "name": "inputDateFormat",
              "value": "dd-MMM-yyyy hh:mm:ss.SSS ZZZ"
            },
            {
              "name": "outputDateFormat",
              "value": "yyyy-MM-dd'T'HH:mm:ss.SSS"
            }
          ]
        }
      ],
      "RuleName": "ESInsert 1",
      "noOfInstance": 3,
      "RuleDescription": "checking rule"
    }
  },
  {
    "rule_id": 421,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "19-Aug-2019 17:58:40.068",
    "version": 1,
    "metadata": null,
    "routingRules": {
      "input": {
        "type": "topic",
        "topic": "testESTopic.*",
        "MQName": "",
        "exchange": "testTopicExchange"
      },
      "RuleId": 421,
      "Status": "Stopped",
      "actions": [
        {
          "type": "ESINSERT",
          "parameter": [
            {
              "name": "connectorURL",
              "value": "elasticsearch:9200"
            },
            {
              "name": "connectionTimeout",
              "value": "6000"
            },
            {
              "name": "clusterName",
              "value": "my_cluster_name"
            },
            {
              "name": "mappingName",
              "value": "observations:sensor"
            },
            {
              "name": "indexName",
              "value": "test"
            },
            {
              "name": "schema",
              "value": "[{\"operation\":\"shift\",\"spec\":{\"record\":{\"*\":{\"output\":{\"*\":{\"@value\":\"[&3].@name\"}},\"checktime1\":\"[&1].checktime1\",\"checktime\":\"[&1].checktime\",\"@(2,feature)\":\"[&1].feature\",\"endtime\":\"[&1].endtime\",\"starttime\":\"[&1].starttime\",\"@(2,sensor)\":\"[&1].sensor\",\"@(3,sensor)\":\"[&1].category\",\"@(2,offering)\":\"[&1].offering\"}}}}]"
            },
            {
              "name": "inputDateFormat",
              "value": "dd-MMM-yyyy hh:mm:ss.SSS ZZZ"
            },
            {
              "name": "outputDateFormat",
              "value": "yyyy-MM-dd'T'HH:mm:ss.SSS"
            }
          ]
        }
      ],
      "RuleName": "ESInsert 1",
      "noOfInstance": 3,
      "RuleDescription": "checking rule"
    }
  },
  {
    "rule_id": 201,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "19-Aug-2019 13:11:10.474",
    "version": 1,
    "metadata": null,
    "routingRules": {
      "input": {
        "type": "topic",
        "topic": "testTopicParquet.*",
        "MQName": "",
        "exchange": "testTopicExchange"
      },
      "RuleId": 201,
      "Status": "Running",
      "actions": [
        {
          "type": "ParquetAction",
          "parameter": [
            {
              "name": "compressionCodec",
              "value": "GZIP"
            },
            {
              "name": "hdfsURL",
              "value": "s3a://actionfiles/"
            },
            {
              "name": "accessKeyID",
              "value": "AKIATHXANAAZVVENEYC3"
            },
            {
              "name": "secretAccessKey",
              "value": "CurrubUyNqnbuqxRhQ9egzTPZfNgZc0/N1JiOs+1"
            },
            {
              "name": "messageFormat",
              "value": "JSON"
            },
            {
              "name": "fileName",
              "value": "dlstest_{dd-MMM-yyyy hh:mm:ss}"
            },
            {
              "name": "method",
              "value": "POST"
            },
            {
              "name": "connectionTimeout",
              "value": "1000"
            },
            {
              "name": "connectorURL",
              "value": "http://datalake:8080/dls/file"
            },
            {
              "name": "metadata",
              "type": "formdata",
              "value": "name=Nayan3,service=Action9",
              "dataType": "string"
            },
            {
              "name": "dateFieldPath",
              "value": "$.observations[0].record[0].starttime"
            },
            {
              "name": "dateFormat",
              "value": "dd-MMM-yyyy HH:mm:ss.SSS z"
            },
            {
              "name": "filename",
              "type": "query",
              "value": "{filePath}",
              "dataType": "string"
            }
          ]
        }
      ],
      "RuleName": "TestRule5customNO",
      "schedule": {
        "window": "count",
        "trigger": "periodic",
        "countsize": "3"
      },
      "noOfInstance": 3,
      "RuleDescription": "checking"
    }
  }
]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID.
user_id string User ID.
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON

-
HTTP Request

http://<domainname>/ActionModule/v1.0/versions?search_text={search_text}&start_time={start_time}&end_time={end_time}

Parameter Required Values Description
search_text false string text search based on rule name and description.
start_time false string Applied start datetime (DD-MMM-YYYY HH:mm:ss zzz). Default value Epoch time.
end_time false string Applied end datetime (DD-MMM-YYYY HH:mm:ss zzz). Default is current date and time.

-
Note
It displays the versions in a descending manner based on the update time.

8.2. Get All Versions of a Rule

Users can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/versions/{rule_id}"

The above command returns the following output JSON response:


[
  {
    "rule_id": 421,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "19-Aug-2019 18:26:02.911",
    "version": 2,
    "metadata": null,
    "routingRules": {
      "input": {
        "type": "topic",
        "topic": "testESTopic.*",
        "MQName": "",
        "exchange": "testTopicExchange"
      },
      "RuleId": 421,
      "Status": "Running",
      "actions": [
        {
          "type": "ESINSERT",
          "parameter": [
            {
              "name": "connectorURL",
              "value": "elasticsearch:9200"
            },
            {
              "name": "connectionTimeout",
              "value": "6000"
            },
            {
              "name": "clusterName",
              "value": "my_cluster_name"
            },
            {
              "name": "mappingName",
              "value": "observations:sensor"
            },
            {
              "name": "rootNode",
              "value": "observations"
            },
            {
              "name": "indexName",
              "value": "test"
            },
            {
              "name": "schema",
              "value": "[{\"operation\":\"shift\",\"spec\":{\"record\":{\"*\":{\"output\":{\"*\":{\"@value\":\"[&3].@name\"}},\"checktime1\":\"[&1].checktime1\",\"checktime\":\"[&1].checktime\",\"@(2,feature)\":\"[&1].feature\",\"endtime\":\"[&1].endtime\",\"starttime\":\"[&1].starttime\",\"@(2,sensor)\":\"[&1].sensor\",\"@(3,sensor)\":\"[&1].category\",\"@(2,offering)\":\"[&1].offering\"}}}}]"
            },
            {
              "name": "inputDateFormat",
              "value": "dd-MMM-yyyy hh:mm:ss.SSS ZZZ"
            },
            {
              "name": "outputDateFormat",
              "value": "yyyy-MM-dd'T'HH:mm:ss.SSS"
            }
          ]
        }
      ],
      "RuleName": "ESInsert 1",
      "noOfInstance": 3,
      "RuleDescription": "checking rule"
    }
  },
  {
    "rule_id": 421,
    "user_id": null,
    "status": "UPDATED",
    "applied_at": "19-Aug-2019 17:58:40.068",
    "version": 1,
    "metadata": null,
    "routingRules": {
      "input": {
        "type": "topic",
        "topic": "testESTopic.*",
        "MQName": "",
        "exchange": "testTopicExchange"
      },
      "RuleId": 421,
      "Status": "Stopped",
      "actions": [
        {
          "type": "ESINSERT",
          "parameter": [
            {
              "name": "connectorURL",
              "value": "elasticsearch:9200"
            },
            {
              "name": "connectionTimeout",
              "value": "6000"
            },
            {
              "name": "clusterName",
              "value": "my_cluster_name"
            },
            {
              "name": "mappingName",
              "value": "observations:sensor"
            },
            {
              "name": "indexName",
              "value": "test"
            },
            {
              "name": "schema",
              "value": "[{\"operation\":\"shift\",\"spec\":{\"record\":{\"*\":{\"output\":{\"*\":{\"@value\":\"[&3].@name\"}},\"checktime1\":\"[&1].checktime1\",\"checktime\":\"[&1].checktime\",\"@(2,feature)\":\"[&1].feature\",\"endtime\":\"[&1].endtime\",\"starttime\":\"[&1].starttime\",\"@(2,sensor)\":\"[&1].sensor\",\"@(3,sensor)\":\"[&1].category\",\"@(2,offering)\":\"[&1].offering\"}}}}]"
            },
            {
              "name": "inputDateFormat",
              "value": "dd-MMM-yyyy hh:mm:ss.SSS ZZZ"
            },
            {
              "name": "outputDateFormat",
              "value": "yyyy-MM-dd'T'HH:mm:ss.SSS"
            }
          ]
        }
      ],
      "RuleName": "ESInsert 1",
      "noOfInstance": 3,
      "RuleDescription": "checking rule"
    }
  }
]

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID
user_id string User ID
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON

HTTP Request

http://<domainname>/ActionModule/v1.0/versions/{rule_id}

Parameter Required Values Description
rule_id true number routing rule ID.

Note - It displays the versions in a descending manner based on
the update time.

8.3. Get a Version of a Rule

Users can get all the versions of a rule.

curl -X GET -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK****" 
"http://<domainname>/ActionModule/v1.0/versions/{rule_id}/{version}"

The above command returns the following output JSON response:

{
  "rule_id": 421,
  "user_id": null,
  "status": "UPDATED",
  "applied_at": "19-Aug-2019 17:58:40.068",
  "version": 1,
  "metadata": null,
  "routingRules": {
    "input": {
      "type": "topic",
      "topic": "testESTopic.*",
      "MQName": "",
      "exchange": "testTopicExchange"
    },
    "RuleId": 421,
    "Status": "Stopped",
    "actions": [
      {
        "type": "ESINSERT",
        "parameter": [
          {
            "name": "connectorURL",
            "value": "elasticsearch:9200"
          },
          {
            "name": "connectionTimeout",
            "value": "6000"
          },
          {
            "name": "clusterName",
            "value": "my_cluster_name"
          },
          {
            "name": "mappingName",
            "value": "observations:sensor"
          },
          {
            "name": "indexName",
            "value": "test"
          },
          {
            "name": "schema",
            "value": "[{\"operation\":\"shift\",\"spec\":{\"record\":{\"*\":{\"output\":{\"*\":{\"@value\":\"[&3].@name\"}},\"checktime1\":\"[&1].checktime1\",\"checktime\":\"[&1].checktime\",\"@(2,feature)\":\"[&1].feature\",\"endtime\":\"[&1].endtime\",\"starttime\":\"[&1].starttime\",\"@(2,sensor)\":\"[&1].sensor\",\"@(3,sensor)\":\"[&1].category\",\"@(2,offering)\":\"[&1].offering\"}}}}]"
          },
          {
            "name": "inputDateFormat",
            "value": "dd-MMM-yyyy hh:mm:ss.SSS ZZZ"
          },
          {
            "name": "outputDateFormat",
            "value": "yyyy-MM-dd'T'HH:mm:ss.SSS"
          }
        ]
      }
    ],
    "RuleName": "ESInsert 1",
    "noOfInstance": 3,
    "RuleDescription": "checking rule"
  }
}

Below are the description of each parameters of the above JSON.

Parameter Values Description
rule_id number Rule ID
user_id string User ID
status string status possible values are CREATED/UPDATED/DELETED.
applied_at string Applied time-stamp
version number Rule version number
metadata string currently not used, kept for future use
routingRules JSON Routing rule JSON

HTTP Request

http://<domainname>/ActionModule/v1.0/versions/{rule_id}/{version}

Parameter Required Values Description
rule_id true number routing rule ID
version true number routing rule’s version number.

MQ Service

1. Introduction

TCUP’s Message Queue Service allows the user to create queues with multiple parameters in the underlying message broker, messages can be stored in the queue in a sequential order similar to an inbox of any mailing application and the users are allowed to perform various operations on the queue such as getting the status of the queue, message statistics (for example - the incoming/outgoing message rates, memory usage, idle time), binding a queue with an exchange and topic.

This service uses the underlying message broker for message handling and follows the Advanced Message Queuing Protocol (AMQP).

Message Queue Service also provides the credentials for TCUP services or applications deployed on TCUP to access the queues using the AMQP protocol.

2. Reference Documents

Message Queue Service Concept Guide

Message Queue Service User’s Guide

2.1. RESTful Resources in MQ Service

  1. Accounts
  2. Queues
  3. Bindings
  4. Statistics
  5. Users

3. Authentication

For MQ Service the API key has to be included in all the API requests to the server in a header like the following:

x-api-key: uKK6WjaZZnnYBj1G6rONQgNAIuc=

3.1. Request Headers

Header Description Sample Value
x-user-key Valid user key of the user under a valid tenant. It is also mandatory in every call. keydemo
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

4. Accounts

4.1. Add a Message Queue Account

It is used to add a new message-queue account. Only admin can perform this task.

HTTP Request:
POST /api/mq/v2.0/accounts

Request Body:

curl -i  -H "Content-Type: application/json" -H "x-api-key: <x-api-key>" -X POST -d 

'{
        "apikey":"test1",
        "username": "TestUser",
        "password": "TestUser",
        "vhost": "TestUser@tcup",
        "host": "x.x.x.x"
  }' 
"http://<domainname>/api/mq/v2.0/accounts"

The Request body command returns either success message or failure message if the account for the given API key already exists or no user present for the API key.

Response Body (Success) :

{
  "Message": "account saved successfully"
}

-----------------------------------------------------------------
Response Body (Failure when account for API key already exists) :

{
  "Message": "account for this api key already exists"
}

-----------------------------------------------------------------

Response Body (Failure when no user present for the API key) :

{
  "status": "error",
  "Message": "no user is present with this apikey"
}

-------------------------------------------------------------------

JSON Parameters

Field Required Values Description
apikey true test1 Key that uniquely identifies a user
username true TestUser Username required to create a queue
password true TestUser Password required to create a queue
vhost true TestUser@tcup Gives the vhost to create a queue
host true x.x.x.x Host where the broker is running
Status Codes Message
200 Success
400 Bad request
403 Forbidden:Invalid API Key

4.2. Get Account Details

This is used to get the details of the message-queue account. Each user can only view the account corresponding to the API key provided in the header. The admin can view all the account details.

HTTP Request
GET /api/mq/v2.0/accounts


Request Body:
 curl -i -H "x-api-key: <x-api-key>" "http://<domainname>/api/mq/v2.0/accounts"``

Response Body: 

{
  "username": "TestUser",
  "password": "TestUser",
  "vhost": "TestUser@tcup",
  "host": "x.x.x.x"
}
Status Codes Message
200 Ok
400 Bad request
403 Forbidden:Invalid API Key

4.3. Delete Account

This is used to delete the details of the message-queue account user. This operation can be performed by the admin only.

HTTP Request
DELETE /api/mq/v2.0/accounts/

Request Body:

curl -i -H "x-api-key : <x-api-key>" "http://<domainname>/api/mq/v2.0/accounts/<apikey>"
Response Body:

{"Message":"Account deleted successfully"}
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

5. Queues

5.1. Create a Queue

This is used to create a queue for the user. The registration details are present in the input JSON.

HTTP Request
POST /api/mq/v2.0/queues

Request Body:

curl -i  -H "Content-Type: application/json" -H "x-api-key: <x-api-key>" -X POST -d 
'{    
          "name": "TestQ",
      "durable":true,
      "auto_delete":false,
      "arguments": 
      {
        "x-message-ttl": 60000,
        "x-expires": 600000,
        "x-max-length": 66,
        "x-max-length-bytes": 6,
        "x-dead-letter-exchange": "",
        "x-dead-letter-routing-key": "",
                "x-max-priority": 4

      }
}' 
    "http://<domainname>/api/mq/v2.0/queues"
Response Body:

{"Message":"Queue created successfully "}

JSON Parameters

Field Required Values Description
name true String Gives the name of the queue
durable false boolean Whether the queue survives broker restart
auto_delete false boolean Whether the queue gets deleted if no subscriptions are left on that queue
x-message-ttl false Integer(0 <= n) Defines the expiration period of a message in miliseconds
x-expires false Integer (0 < n) Sets the expiry time for the queue in miliseconds
x-max-length false Integer Sets the maximum number of messages in the queue
x-max-length-bytes false Integer Sets the lenth of the queue in bytes
x-dead-letter-exchange flase String Defines the dead-letter-exchange name
x-dead-letter-routing-key false String Defines the dead-letter routing key
x-max-priority false Integer Defines priority queue. Larger numbers indicate higher priority
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

5.2. Get List of Queues

This is used to retrieve all the details of the message-queue queues associated with the provided mq user.

HTTP Request
GET /api/mq/v2.0/queues

Request Body:

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/queues"
Response Body (Success):

[
 {
  "queues": [
    {
      "name": "TcupQueue",
      "memory": "13768",
      "noOfMessage": "0"
    },
    {
      "name": "TestUserQ1",
      "memory": "13768",
      "noOfMessage": "0"
    }
  ]
 }
]
Response Body: (Failure)
if RabbitmQ management plug-in is not installed: 

{
  "Message": "Unable to connect message broker"
}
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

5.3. Describes a Queue

This is used to retrieve all the details of the message-queue queues associated with the provided queue name.

HTTP Request
GET /api/mq/v2.0/queues/

Request Body:

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/queues/<name>"
Response Body (Success): 

{
  "name": "TestQ",
  "vhost": "TestUser@tcup",
  "durable": false,
  "auto_delete": false,
  "exclusive": false,
  "arguments": {},
  "node": "test@tcs-ThinkCentre-M58p",
  "consumer_details": [],
  "deliveries": [],
  "incoming": [],
  "backing_queue_status": {
    "mode": "default",
    "q1": 0,
    "q2": 0,
    "delta": [
      "delta",
      "undefined",
      0,
      "undefined"
    ],
    "q3": 0,
    "q4": 0,
    "len": 0,
    "target_ram_count": "infinity",
    "next_seq_id": 0,
    "avg_ingress_rate": 0,
    "avg_egress_rate": 0,
    "avg_ack_ingress_rate": 0,
    "avg_ack_egress_rate": 0
  },
  "disk_writes": 0,
  "disk_reads": 0,
  "head_message_timestamp": null,
  "message_bytes_persistent": 0,
  "message_bytes_ram": 0,
  "message_bytes_unacknowledged": 0,
  "message_bytes_ready": 0,
  "message_bytes": 0,
  "messages_persistent": 0,
  "messages_unacknowledged_ram": 0,
  "messages_ready_ram": 0,
  "messages_ram": 0,
  "garbage_collection": {
    "min_bin_vheap_size": 46422,
    "min_heap_size": 233,
    "fullsweep_after": 65535,
    "minor_gcs": 1
  },
  "state": "running",
  "recoverable_slaves": null,
  "consumers": 0,
  "exclusive_consumer_tag": null,
  "policy": null,
  "consumer_utilisation": null,
  "idle_since": "2017-03-22 5:56:08",
  "messages_unacknowledged_details": {
    "rate": 0
  },
  "messages_unacknowledged": 0,
  "messages_ready_details": {
    "rate": 0
  },
  "messages_ready": 0,
  "messages_details": {
    "rate": 0
  },
  "messages": 0,
  "reductions_details": {
    "rate": 0
  },
  "reductions": 1953,
  "memory": 6968
}
Response Body: (Failure)
if RabbitmQ management plug-in is not installed: 

{
  "Message": "Unable to connect message broker"
}

URL Parameters

Parameter Description
name Gives the name of the queue
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

5.4. Delete a Queue

This is used to delete a queue.

HTTP Request
DELETE /api/mq/v2.0/queues//?ifUnused=true/false&ifEmpty=true/false

Request Body: 

curl -i -H "x-api-key : <x-api-key>" -X DELETE http://<domainname>/api/mq/v2.0/queues/<name>/?ifUnused=true/false&ifEmpty=true/false"
Response Body: 

{
  "Message": "Queue deleted successfully"
}

URL Parameters

Parameter Description
name Gives the name of the queue
ifUnused ‘ifUnused= true’, prevents the deletion if the queue has consumers
ifEmpty ‘ifEmpty= true’, prevents the deletion if the queue contains messages
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

6. Bindings

6.1. Create a Queue-Bind

This is used to bind a queue with a given exchange. The details are present in the input JSON.

HTTP Request
POST /api/mq/v2.0/bindings

Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <x-api-key>" -X POST -d 
'{
      "queue": "Q7",
      "exchange":"TestExchange",
      "routing_key":"TEST"

}' 
    "http://<domainname>/api/mq/v2.0/bindings"
Response Body (Success): 

{
  "Message": "Queue Q7 is bind to the exchange TestExchange"
}
Response Body (Failure):
If the exchange does not exist 

{
  "Message": "Exchange  doesnot exist"
}

The above command returns the follwoing JSON if the queue does not exist:

{
  "Message": "Queue  does not exist"
}

JSON Parameters

Field Required Values Description
queue true String Gives the name of the queue
exchange true String Gives the name of the exchange
routing_key true String Gives the name of the routing_key
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

6.2. Get Binding Details Corresponding to Given Queue

This is used to retrieve all the details of the message-queue bindings associated with the provided queue name.

HTTP Request
GET /api/mq/v2.0/bindings/q/

Request Body: 

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/bindings/q/<queue>"
Response Body (Success): 

[
  {
    "source": "",
    "vhost": "TestUser@tcup",
    "destination": "QName",
    "destination_type": "queue",
    "routing_key": "QName",
    "arguments": {},
    "properties_key": "QName"
  },
  {
    "source": "TestExchange",
    "vhost": "TestUser@tcup",
    "destination": "QName",
    "destination_type": "queue",
    "routing_key": "TEST",
    "arguments": {},
    "properties_key": "TEST"
  },
  {
    "source": "TestExchange1",
    "vhost": "TestUser@tcup",
    "destination": "QName",
    "destination_type": "queue",
    "routing_key": "TEST",
    "arguments": {},
    "properties_key": "TEST"
  }
]
Response Body (Failure):
If RabbitmQ management plug-in is not installed

{
  "Message": "Unable to connect message broker"
}

Note : Here “source” defines the name of the exchange and “destination” is the queue name associated with it.

URL Parameters

Parameter Description
queue Gives the name of the queue
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

6.3. Get Binding Details for a Given Exchange

This is used to retrieve all the details of the message-queue bindings associated with the provided exchange.

HTTP Request
GET /api/mq/v2.0/bindings/e/

Request Body: 

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/bindings/e/<exchange>"

The above command returns the following JSON :

Response Body (Success): 

[
  {
    "source": "TestExchange",
    "vhost": "TestUser@tcup",
    "destination": "QName",
    "destination_type": "queue",
    "routing_key": "TEST",
    "arguments": {},
    "properties_key": "TEST"
  },
  {
    "source": "TestExchange",
    "vhost": "TestUser@tcup",
    "destination": "QTest",
    "destination_type": "queue",
    "routing_key": "TEST",
    "arguments": {},
    "properties_key": "TEST"
  }
]
Response Body (Failure):
If RabbitmQ management plug-in is not installed

{
  "Message": "Unable to connect message broker"
}

Note : Here “source” defines the name of the exchange and “destination” is the queue name associated with it.

URL Parameters

Parameter Description
exchange Gives the name of the exchange
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

6.4. Get Binding Details Corresponding to Given Exchange and Queue

This is used to retrieve the details of the binding associated with the provided queue and the exchange.

HTTP Request
GET /api/mq/v2.0/bindings/q//e/

Request Body: 

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/bindings/q/<queue>/e/<exchange>"
Response Body (Success): 

[
  {
    "source": "TestExchange",
    "vhost": "TestUser@tcup",
    "destination": "QName",
    "destination_type": "queue",
    "routing_key": "TEST",
    "arguments": {},
    "properties_key": "TEST"
  }
]
Response Body (Failure):
If RabbitmQ management plug-in is not installed

{
  "Message": "Unable to connect message broker"
}

Note : Here “source” defines the name of the exchange and “destination” is the queue name associated with it.

URL Parameters

Parameter Description
queue Gives the name of the queue
exchange Gives the name of the exchange
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

6.5. Delete Binding Details Corresponding to Given Exchange and Queue

This is used to unbind a queue with a given exchange

HTTP Request
DELETE /api/mq/v2.0/bindings/q//e/?routing_key=

Request Body: 

curl -i -H "x-api-key : <x-api-key>" -X 
DELETE -d '{"routing_key":"TEST"}'http://<domainname>/api/mq/v2.0/bindings/q/<queue>/e/<exchange>"
Response Body: 

{
  "Message": "Queue Qtest is unbind to the exchange TestExchange"
}

The above command returns the following JSON if the exchange does not exist:

{
  "Message": "Exchange  does not exist"
}

The above command returns the following JSON if the queue does not exist:

{
  "Message": "Queue  does not exist"
}

URL Parameters

Parameter Description
queue Gives the name of the queue
exchange Gives the name of the exchange
routing_key Gives the value of the routing_key
Status Codes Message
200 Ok
400 Invalid request
403 Forbidden:Invalid API Key

7. Statistics

7.1. Get Queue Statistics

This is used to get the statistics of the message-queue service. Each user can only view the details corresponding to the apikey provided in the header.

HTTP Request
GET /api/mq/v2.0/stats

Request Body: 

 curl -i -H "x-api-key: <x-api-key>"
 "http://<domainname>/api/mq/v2.0/stats"
Response Body (Success): 

{
  "totalQueues": 1,
  "totalSystemQueues": 0,
  "totalUserdefinedQueues": 1,
  "totalMessages": 0,
  "totalMemoryInBytes": 4376
}

The above command returns the following JSON if RabbitmQ management plug-in is not installed:

Response Body (Failure):
If RabbitmQ management plug-in is not installed

{
  "Message": "Unable to connect message broker"
}
Status Codes Message
200 Success:Logged
400 Bad request
403 Forbidden:Invalid API Key

Device Management

1. Introduction

This section provides the list of RESTful APIs using which different DEVICE MANAGEMENT specific functions ie. device registration, de-registration, resource query, resource update, resource subscription etc. can be performed. DM is based on OMA LightweightM2M standard which works over CoAP protocol (RFC 7242).

Note:

User management was handled by the respective services till TCUP9 and hence each user would have his/her own user key and tenant key. Effective TCUP 10, the user management is supervised by Identity Access Management(IAM) module, hence user create, update, delete API is hidden from DM in TCUP 10.

Introduction of IAM also necessitated a change of the header name ‘user-key’ to ‘x-user-key’ to have uniformity with other service as per IAM nomenclature. The impact is that every client, including test script, needs to call DM API with x-user-key instead of user-key. The DM user may be a tenant or a user under a tenant as per IAM and is allocated one unique user key by IAM; so headers x-api-key and x-user-key will be same and equal to the user public key and API gateway will convert the public key to private key. Both x-api-key and x-user-key are retained for backward compatibility. For DM agent the user public key will be given in key argument.

2. Reference Documents

Device Management Service Concept Guide

Device Managment Service User’s Guide

3. Device API

3.1. Pre-Register a New Device in the System

This provides a method of commissioning a new device under the ownership of a user. The pre-registration step also ensures uniqueness of the device EPN(endpoint name). This is a mandatory manual process required for device ID and key file generation before actual registration by device agent. Pre-registration is recommended to be done from pre-registration service using its pre-registration API however, there is a deprecated API support for existing pre-registration API from DM service.

Method : POST
URL : https://{domain}/dms/v1/device

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

Content-Type: application/json

Request Body: 

{
    "epnid": "androiddtls"    
}

Note : EPN ID should be alphanumeric, no special characters are allowed.

Parameter XSD Type Description Optional
epnId string Device name unique. No
Status Codes Message
200 Registration successful
400 Device already registered
401 Missing Key

3.2. Get the List of Devices

This provides a method of getting a list of registered devices in DM. Either all the devices can be retrieved by a single call or the devices can be fetched part by part in a page-wise manner.

3.2.1. Read Device without Server Side Pagination REST API:

This API returns all the devices at a single shot. The pagination, if required, needs to be done by the client. The returned device list is in the Least Recently Updated (LRU) order. If the number of devices is massive the response latency will increase.

Method : GET
URL : https://{domain}/dms/v1/device

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

This will have long latency when the number of devices are huge.

Accept : application/json

Example JSON Payload:

GET /v1/device

Content-Type: application/json

Response Body: 

{
    "devices": [{
        "epnid": "android-Xperia-sp",
        "registrationType": "DeviceEnded",
        "registrationTime": "2014-04-10T05:12:47.026Z",
        "connectionDetails": {
            "connection": "NOT-REACHABLE",
            "lastSuccessfulConnectionTime": "2014-04-10T05:29:12.315Z",
            "lastUpdateTime": "2014-04-11T06:16:12.325Z"
        }
    }, {
        "epnid": "android-nexus",
        "registrationType": "DeviceEnded",
        "registrationTime": "2014-04-17T10:08:45.047Z",
        "connectionDetails": {
            "connection": "CONNECTED",
            "lastSuccessfulConnectionTime": "2014-04-28T12:15:32.316Z",
            "lastUpdateTime": "2014-04-28T12:15:32.316Z"
        }
    }, {
        "epnid": "android-sola",
        "registrationType": "DeviceEnded",
        "registrationTime": "2014-04-07T11:17:27.577Z",
        "connectionDetails": {
            "connection": "NOT-REACHABLE",
            "lastSuccessfulConnectionTime": "2014-04-25T13:16:19.039Z",
            "lastUpdateTime": "2014-04-28T10:15:11.466Z"
        }
    }, {
        "epnid": "elan-box",
        "registrationType": "DeviceEnded",
        "registrationTime": "2014-04-04T09:47:20.198Z",
        "connectionDetails": {
            "connection": "NOT-REACHABLE",
            "lastSuccessfulConnectionTime": "2014-04-04T10:32:04.184Z",
            "lastUpdateTime": "2014-04-11T06:16:04.309Z"
        }
    }, {
        "epnid": "linux-dm-device",
        "registrationType": "DeviceEnded",
        "registrationTime": "2014-04-25T13:16:19.007Z",
        "connectionDetails": {
            "connection": "NOT-CONNECTED",
            "lastSuccessfulConnectionTime": "2014-04-25T13:19:45.950Z",
            "lastUpdateTime": "2014-04-28T10:15:19.955Z"
        }
    }]
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
Status Codes Message
200 List of devices
401 Missing Key

3.2.2. Get List of Device with Server Side Pagination REST API :

This provides a method of getting a list of registered devices in DM in a particular order spanning over multiple pages. The order may be recently detected, recently updated, least recently registered, least recently updated or sorted by device name in ascending or descending order.

Method : GET
URL : https://{domain}/dms/v1/device?params

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET /v1/device?limit=10&pageno=1&sortby=DNA

Content-Type: application/json

Response Body: 

{
    "devices": [{
        "epnid": "Arduino4",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-04-08T11:39:13.569Z",
        "connectionDetails": {
            "connection": "NOT-CONNECTED",
            "lastSuccessfulConnectionTime": "2015-04-08T11:52:26.551Z",
            "lastUpdateTime": "2015-04-09T06:38:34.132Z"
        }
    }, {
        "epnid": "ArindamLaptop2",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-04-08T11:30:09.203Z",
        "connectionDetails": {
            "connection": "CONNECTED",
            "lastSuccessfulConnectionTime": "2015-04-09T09:06:17.313Z",
            "lastUpdateTime": "2015-04-10T08:05:54.784Z"
        }
    }, {
        "epnid": "AxisCamera",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-03-25T07:24:45.711Z",
        "connectionDetails": {
            "connection": "NOT-REACHABLE",
            "lastSuccessfulConnectionTime": "2015-04-02T07:12:32.516Z",
            "lastUpdateTime": "2015-04-08T09:03:14.857Z"
        }
    }, {
        "epnid": "Nozomi",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-04-08T11:52:12.605Z",
        "connectionDetails": {
            "connection": "NOT-CONNECTED",
            "lastSuccessfulConnectionTime": "2015-04-08T12:28:43.940Z",
            "lastUpdateTime": "2015-04-09T06:38:58.217Z"
        }
    }, {
        "epnid": "devdc8",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-04-10T06:28:43.112Z",
        "connectionDetails": {
            "connection": "CONNECTED",
            "lastSuccessfulConnectionTime": "2015-04-10T06:28:43.112Z",
            "lastUpdateTime": "2015-04-10T06:28:43.112Z"
        }
    }, {
        "epnid": "fnetester",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-03-27T07:14:12.113Z",
        "connectionDetails": {
            "connection": "NOT-CONNECTED",
            "lastSuccessfulConnectionTime": "2015-03-27T13:10:00.864Z",
            "lastUpdateTime": "2015-04-09T06:38:54.322Z"
        }
    }],
    "paging": {
        "totalCount": 6,
        "token": "o0oNVvuAYZIXKXj",
        "pageno": 1
    }
}
Parameter XSD Type Description Optional
limit Numeric Number of devices to be displayed in a page Yes
token Alphanumeric To hold the current session No
Pageno Numeric To jump to the page No
Sortby String Sorting of the data Yes

-
Additional notes:

Status Codes Message
200 List of devices
401 Missing Key

3.3. Get Device Details

This provides a method of getting details of a registered device in DM.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

-

Query XSD Type Description Optional
fromDevice string true if fresh data from device is seek Y

Accept : application/json

GET /v1/device/{epnid}

Content-Type: application/json

Response Body: 

{
    "epnid": "android-dev",
    "macId": "01:02:03:04:05:06",
    "imei": "",
    "os": "android4.04",
    "externalSosId": "",
    "foiSos": "ecospace1B",
    "address": "rajarhat",
    "deviceType": "android",
    "deviceGroup": "android",
    "definition": "elan",
    "deviceConnectionAddress": "14.234.08.256",
    "interfaceType": "WLAN",
    "serverURI": "ripsac2.web2labs.net",
    "firmwareDetails": {
        "firmwareName": "elanswapp",
        "firmwareVersion": "v1",
        "firmwareURI": "apprepos.ripsac2.web2labs.net"
    },
    "hardwareDetails": {
        "model": "elan",
        "ram": "2048MB",
        "storage": "8096MB",
        "freeMemory": "1024MB",
        "heap": "800MB",
        "batteryLevel": "80%",
        "cpuFamily": "arm-v7",
        "cpuLoad": "27%",
        "cpuFrequency": "1000000KHz",
        "slNo": "1234"
    },
    "locationDetails": {
        "lat": "22.3",
        "lng": "88.13",
        "alt": "2000m",
        "locationId": "CCU-IN"
    }
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
Status Codes Message
200 OK, JSON representing the Device
401 Missing Key
404 Device not found

3.4. Get Block Device State of a Device

This API provides a method of getting the information about the blocked state of a device. It gives the block device flag value which is ‘Y’ if the device is blocked else ‘N’.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/block

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4
Parameter XSD Type Description Optional
epnId string Device name unique. No

Accept : application/json

GET http://DMServiceURL:PORT/dms/v1/device/dmtest/block

Response :
Content-Type: application/json

Response Body: 

{
  "blockDevice": "Y",
  "secured": false
}
Key Description
blockDevice Block device flag
Status Codes Message
401 Authentication Error
403 Forbidden
404 Block Device flag not found
500 Server Error

3.5. Set Block Device

This API provides a method of setting the block device flag for a device . If the flag is set then the device is considered to be in blocked state. No PUT resource,subscribe resource will be allowed for a blocked device. Device agent, if running,should be stopped before blocking a device.

Method : SET
URL : https://{domain}/dms/v1/device/{epnid}/block

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4
Parameter Description Optional
epnId Device name unique. No
blockDevice BlockDevice flag Y/N No

Accept : application/json

GET http://DMServiceURL:PORT/dms/v1/device/dmtest/block?blockDevice=Y

Response :
Content-Type: application/json

Response Body: 

{
  "status": 200,
  "message": "Device is blocked."
}
Key Description
status Http return status
message State of block device flag
Status Codes Message
200 Block Device flag set
401 Block Device flag setting failed

3.6. Delete Device

This provides a method of deregistering/deleting a registered device in DM. Device agent, if running, should be stopped before deregistering a device.

Delete Device REST API

Method : DELETE
URL : https://{domain}/dms/v1/device/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

Parameter XSD Type Description Optional
epnId string Device name unique. No
Status Codes Message
200 OK, JSON representing the Device
401 Missing Key
404 Device not found
403 Delete failed
500 Internal server error

4. Device Statistics API

4.1.Get Statistics

This API provides a method of getting the statistics of a number of devices and their connection status in a summary level.

Method : GET
URL : https://{domain}/dms/v1/device/stats

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET http://DMServiceURL:PORT/dms/v1/device/stats

Response :
Content-Type: application/json

Response Body: 

{ "deviceCount": 20, "connectedDeviceCount": 2, "preregisteredDeviceCount": 10, "securedDeviceCount": 2 }
Key Description
deviceCount Total number of devices
connectedDeviceCount Number of devices online
preregisteredDeviceCount Number of devices pre-registered but actual registration is pending
securedDeviceCount Number of DTLS devices online or offline
Status Codes Message
200 Successful
401 Missing Key

4.2. Get DM Information

This API provides a method of getting information of DM URL and CoAP and DTLS ports, these information can be used by DM agents, bootstrap service and other applications to get the information on the URL and port to connect.

Method : GET
URL : https://{domain}/dms/v1/device/stats/dmsInfo

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET http://DMServiceURL:PORT/dms/v1/device/stats/dmsInfo

Response :
Content-Type: application/JSON

Response Body: 

{
  "dm_url": "https://dm.tcupiot.com",
  "dm_port": 5683,
  "dm_dtls_port": 5684
}
Key Description
dm_url DM service URL
dm_port DM CoAP port
dm_dtls_port DM DTLS port
Status Codes Message
200 Successful
401 Missing Key

5. Subscription API

5.1 Subscribe Resource

This provides a method of subscribing to a resource of a device registered in DM. By setting a subscription, the resource value will be notified automatically. Whether to automatically resume the subscription after device reconnect can be set using autoResume flag, default value is true.

Subscribe Resource REST API

Method : PUT
URL : https://{domain}/dms/v1/device/{epnid}/{resourceid}/subscribe

Header Description Sample Value
x-user-key DM User Key key#demo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4=

Accept : application/json

GET /v1/device/{devicename}/sysUpTime/subscribe

Content-Type: application/json

Response Body:

{
    "status": 200,
    "message": "subscription is successful ."
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No
Status Codes Message
200 List of devices
401 Missing Key
404 device / resource not found
500 internal server error

5.2 Get Subscription Status

This provides a method of getting subscription status of a resource of a device registered in DM.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/{resourceid}/subscribe

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET /v1/device/{devicename}/sysUpTime/subscribe

Content-Type: application/json

Response Body: 

{
    "status": 404,
    "message": "subscription is not active ."
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No
Status Codes Message
200 Subscription active
401 Missing Key
404 Resource subscription not active
500 internal server error

5.3. Remove Subscription

This provides a method of removing subscription status of a resource of a device registered in DM.

Method : DELETE
URL : https://{domain}/dms/v1/device/{epnid}/{resourceid}/subscribe

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

DELETE /v1/device/{devicename}/sysUpTime/subscribe

Content-Type: application/json

Response Body: 

{
    "status": 200,
    "message": "subscription removed ."
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No

-

Status Codes Message
200 Subscription remove successful
401 Missing Key
404 Resource subscription not active
500 internal server error

6. Resource API

6.1 Get Details of a Particular Device Resource

This provides a method of getting details of a resource of a device registered in DM.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/{resourceid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET /v1/device/{devicename}/sysUpTime

Content-Type: application/json

Response Body: 

{
    "epnid": "android",
    "resourceid": "sysUpTime",
    "value": "40 sec"
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No
Status Codes Message
200 OK , JSON of resource
401 Missing Key
404 Resource not found

6.2 Update Resource of a Device

This provides a method of updating a particular resource of a device registered in DM, provided the resource is editable.

Method : PUT
URL : https://{domain}/dms/v1/device/{epnid}/{resourceid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

PUT /v1/device/{devicename}/definition

Content-Type: application/json

Request Body: 

{
    "epnid": "android",
    "resourceid": "definition",
    "value": "TestChangedDefinition"
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No
value string nevaluew No

-

Status Codes Message
201 OK , device resource updated
401 Missing Key
404 Resource not found

7. Access Control List API

7.1. Get ACL of a Device

This provides a method of showing default ACL of resources for a particular device registered in DM. These resources are normative resources as per LightweightM2M specification. Additionally users can define their own sensor type and custom type resource and corresponding ACL. ACLs are defined during registration of a device.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/ACL

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET /v1/device/{devicename}/ACL

Content-Type: application/json

Response Body:

{
    "acl": [{
        "updatable": false,
        "observable": false,
        "path": "/imei",
        "name": "imei"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/os",
        "name": "os"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/externalSosId",
        "name": "externalSosId"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/foiSos",
        "name": "foiSos"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/address",
        "name": "address"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/deviceType",
        "name": "deviceType"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/deviceGroup",
        "name": "deviceGroup"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/deviceConnectionAddress",
        "name": "deviceConnectionAddress"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/definition",
        "name": "definition"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/interfaceType",
        "name": "interfaceType"
    }, {
        "updatable": true,
        "observable": false,
        "path": "/serverURI",
        "name": "serverURI"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/firmwareDetails/firmwareName",
        "name": "firmwareName"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/firmwareDetails/firmwareVersion",
        "name": "firmwareVersion"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/firmwareDetails/firmwareURI",
        "name": "firmwareURI"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/locationDetails/lat",
        "name": "lat"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/locationDetails/lng",
        "name": "lng"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/locationDetails/alt",
        "name": "alt"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/locationDetails/locationId",
        "name": "locationId"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/model",
        "name": "model"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/slNo",
        "name": "slNo"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/hardwareDetails/ram",
        "name": "ram"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/hardwareDetails/freeMemory",
        "name": "freeMemory"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/hardwareDetails/batteryLevel",
        "name": "batteryLevel"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/cpuFamily",
        "name": "cpuFamily"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/hardwareDetails/cpuLoad",
        "name": "cpuLoad"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/cpuFrequency",
        "name": "cpuFrequency"
    }, {
        "updatable": false,
        "observable": true,
        "path": "/hardwareDetails/heap",
        "name": "heap"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/storage",
        "name": "storage"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/processorType",
        "name": "processorType"
    }, {
        "updatable": false,
        "observable": false,
        "path": "/hardwareDetails/processorSpeed",
        "name": "processorSpeed"
    }]
}
Parameter XSD Type Description Optional
epnId string Device name unique. No
resourceId string Resource name No
value string nevaluew No
Status Codes Message
200 OK , json response
401 Missing Key
404 Resource not found

8. User API

8.1. Validate User

This provides a method of validating an existing user and returning corresponding DM user key with TCUP tenant key.

Validate a DM user REST API

Method : POST
URL : https://{domain}/dms/validate/user

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

POST <dmurl>/validate/user

Content-Type : application/json

Request Body: 

{
    "userName": "demo",
    "password": "demo"
}
Parameter XSD Type Description Optional
userName string user No
password string password No

-

* Example JSON Payload for HTTP Response:

Response Body: 

{
    "ripsacKey": "ucrFbFW2ppyjF2cfFtrxfAIH2L4",
    "userKey": "keydemo"
}

Note: User key and tenant key will be identical post IAM deployment.

Status Codes Message
200 OK, DM user key returned
401 Missing Key
404 User not registered as a valid DM user

9. Search API

9.1. Search for a Device

Used to search a particular device or a set of devices having a particular name pattern. This request is used to search for a particular device name. Also this can be used to search for a set of devices having the ‘required’ pattern either in the beginning /middle/ end . The two different search patterns are toggled by using the parameter metadata – true or false respectively.

Method : GET
URL : https://{domain}/dms/v1/device/search/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET /v1/device/search/{epnid-pattern}?metadata=true&choice=contains

Here epnid-pattern is ‘a’

Content-Type : application/json

Response Body:

{
    "devices": [{
        "epnid": "ArindamLaptop2",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-04-08T11:30:09.203Z",
        "connectionDetails": {
            "connection": "CONNECTED",
            "lastSuccessfulConnectionTime": "2015-04-09T09:06:17.313Z",
            "lastUpdateTime": "2015-04-10T08:05:54.784Z"
        }
    }, {
        "epnid": "AxisCamera",
        "registrationType": "deviceEnded",
        "registrationTime": "2015-03-25T07:24:45.711Z",
        "connectionDetails": {
            "connection": "NOT-REACHABLE",
            "lastSuccessfulConnectionTime": "2015-04-02T07:12:32.516Z",
            "lastUpdateTime": "2015-04-08T09:03:14.857Z"
        }
    }]
}

GET /v1/device/search/{epnid-pattern}?metadata=false

here epnid-pattern is ‘dev’

Content-Type : application/json

Response Body:

{
    "devices": [
        "devdc8",
        "devdc9",
        "devdc10"
    ]
}

The restful API can be invoked from any application to access the device data.

Parameter XSD Type Description Optional
epnid string device id/pattern No
choice string begins/ends/contains No
metadata string true/false No
Status Codes Message
200 Search Result
401 Missing Key
404 No result found

10. Filter API

10.1. Filter Devices

Used to filter particular device or a set of devices having a defined criteria like a particular device type or a device model or a device group. Also this can be used to search for a set of devices having the ‘required’ criteria pattern either in the beginning /middle/ end . The two different filter patterns are toggled by using the parameter metadata – true or false respectively.

Method : GET
URL : https://{domain}/dms/v1/device/Filter

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

GET https://{domain}/v1/device/filter?filterby={type}&value={test}&choice={beginswith}&metadata={true}

Here filtering is done on device type starting with “test”

Content-Type : application/json

Response Body for Filter Device:

{

    "devices": [
    {
      "epnid": "dev01",
      "registrationType": "deviceEnded",
      "registrationTime": "2017-02-27T10:18:25.254Z",
      "connectionDetails": {
        "connection": "NOT_CONNECTED",
        "lastSuccessfulConnectionTime": "2017-02-27T04:52:13.693Z",
        "lastUpdateTime": "2017-02-27T04:52:13.693Z"
      },
      "secured": false
    },
    {
      "epnid": "dmotatest",
      "registrationType": "userEnded",
      "registrationTime": "2017-02-27T11:47:47.114Z",
      "connectionDetails": {
        "connection": "NOT_REACHABLE",
        "lastSuccessfulConnectionTime": "2017-02-27T11:48:24.909Z",
        "lastUpdateTime": "2017-02-27T11:48:24.909Z"
      },
      "secured": false
    }
    ]
}

The restful API can be invoked from any application to access the device data.

Parameter XSD Type Description Optional
filterby string device type/model/group No
value string type/model/grp value No
choice string begins/ends/contains No
metadata string true/false No
Status Codes Message
200 Filter Result
401 Key Mismatch (Unauthorised)
403 Forbidden
404 No result found

11. Command API

11.1. Create Command

Create command can schedule command for either online or offline devices . This is basically a mechanism to trigger a PUT resource call for queued operation. If the device is online it will act on the queued command after the schedule interval elapses or at the specified time. If the device is offline it will act on the scheduled command as soon as it becomes online.
There is a threshold of the maximum number of commands which can be queued. The default value is 20 and it can be configured during service deplyment. The command is stored in queue in FIFO manner, command gets evicted from queue once executed.

Method : POST
URL https://{domain}/dms/v1/device/{epnid}/command

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body:

{
    "interval": "string",
    "mandatory": true,
    "resourceid": "string",
    "timestamp": "string",
    "value": "string"
}

where,
EPNID – Endpoint ID
Interval – duration after which the user wants the command to get executed. Accepted values include now, x sec/ s/ seconds, m/ min/ minutes, h/ hours/ hrs. x is any integer > 0
ex- for some command to get executed after 5seconds users can give interval
value either as 5s or 5sec or 5seconds. 5 minutes can be given as 5m or 5min or 5mins or 5minutes. “now” if users want to execute it right now
mandatory – if users want the resource to get executed even after it could not be executed due to failure or device is offline etc. accepted values true/false. Default is false.
ResourceID – ResourceID of the resource for which command will be executed.
Example- customToggle
The resource must be updatable.
timestamp – format dd-MM-uuuu HH:mm:ss z ( in UTC format)

Note: If both timestamp and interval are present in the request payload, interval will be ignored and timestamp time will be considered for execution.
Value – the value to which the resource will get updated.

POST http://localhost:8089/dms/v1/device/test-device-2/command

Sample  Payload:

{
    "interval": "10s",
    "mandatory": true,
    "resourceid": "externalSosId",
    "value": "changeIt"
}
Sample Response:

{
    "cid": "3ba11572-d212-4f76-8d59-5e28e317611b",
    "epnid": "test-device-2",
    "resourceId": "externalSosId",
    "resourcePath": "/4/0/22",
    "value": "changeIt",
    "scheduled_at": "06-12-2017 09:05:21 UTC",
    "status": "CREATED",
    "device_response_code": 0,
    "mandatory": true
}

where,
CID – Unique Command ID assigned to this command ( in UUID format)
Scheduled_at – Time at which this command will get executed. This is calculated by the server based on the interval or timestamp provided by the user in request payload.
status – status of the command.(Created / Processed)
device_response_code – response code obtained from device while executing the command. Response code can be 500, 404, 200 etc. here 0 stands for command not yet sent to the device.

11.2. GET All Commands:

API to get all the commands for a device.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/command

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4
Sample Response Body :

[{
        "cid": "3ba11572-d212-4f76-8d59-5e28e317611b",
        "epnid": "test-device-2",
        "resourceId": "externalSosId",
        "resourcePath": "/4/0/22",
        "value": "changeIt",
        "creation_at": "06-12-2017 09:05:11 UTC",
        "scheduled_at": "06-12-2017 09:05:21 UTC",
        "process_at": "06-12-2017 14:35:16 UTC",
        "status": "HOLD",
        "device_response_code": 0,
        "mandatory": true
    },
    {
        "cid": "679dbbfc-f44b-4e90-a4cc-109aa5a03fd4",
        "epnid": "test-device-2",
        "resourceId": "externalSosId",
        "resourcePath": "/4/0/22",
        "value": "changeIt",
        "creation_at": "06-12-2017 09:30:46 UTC",
        "scheduled_at": "06-12-2017 09:30:56 UTC",
        "status": "CREATED",
        "device_response_code": 0,
        "mandatory": true
    }
]

11.3. Get Command from Command ID:

Get the command by giving the command ID.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/command/{cid}

Where, epnid – Endpoint ID & cid – Command ID

Header Fields of Rest Call

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

http://localhost:8089/dms/v1/device/test-device-2/command/3ba11572-d212-4f76-8d59-5e28e317611b

Sample Response Bosy:

{
    "cid": "3ba11572-d212-4f76-8d59-5e28e317611b",
    "epnid": "test-device-2",
    "resourceId": "externalSosId",
    "resourcePath": "/4/0/22",
    "value": "changeIt",
    "creation_at": "06-12-2017 09:05:11 UTC",
    "scheduled_at": "06-12-2017 09:05:21 UTC",
    "process_at": "06-12-2017 14:35:16 UTC",
    "status": "HOLD",
    "device_response_code": 0,
    "mandatory": true
}

11.4. Cancel Commands

API for cancelling all commands or specific commands based on command ID.

Method : POST
URL : https://{domain}/dms/v1/device/{epnid}/command/cancel

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Payload:

Request Body :

{
    "cids": [
        "string"
    ]
}

where
cids – list of cids to cancel or if the user gives “all” then it will cancel all the commands which are yet to get processed.

Sample Payload:

Sample Request Body:

{
    "cids": [
        "3ba11572-d212-4f76-8d59-5e28e317611b"
    ]
}

Sample response:

Sample Response Body:

{
    "status": 200,
    "message": "1 cids got cancelled"
}

11.5. Delete Commands:

API for deleting all commands or specific commands based on command ID.

Method : DELETE
URL : https://{domain}/dms/v1/v1/device/test-device-2/command

-

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

-

Request Body:

{
    "cids": [
        "string"
    ]
}

where cids – list of cids to delete or if the users give “all” then it will delete all the commands which are processed, cancelled or failed.

Sample Request Body: 

{
    "cids": [
        "a5799cec-9d9b-4f14-b000-ca5ec612c8f3",
        "727f7bc2-b11b-4e90-8e40-4f4f28b8da6a"
    ]
}
Sample Response Body:

{
    "status": 200,
    "message": "2 cids got deleted"
}

12. DTLS security abd Security API

DM supports DTLS (RFC 6347) for transport layer security between device and DM server. Device can talk with DM server in either DTLS security mode or with No security mode. Users can still register without DTLS security and pre-registration.
DTLS is a transport layer security mechanism which implements HTTPS like TLS type security for Datagram i.e. UDP packets . Remember Device communicates with DM server over CoAP and CoAP packets are UDP.

For using DTLS security with Pre shared Key mode there are three steps:

  1. First pre register a device for a particular DM user under a TCUP tenant. This step will ensure that the system is aware of a new device with a particular name to be registered in future. Pre registration step will also tell if the device name is already taken by other DM users as duplicate device names are not allowed. In case the device name is already taken the user has to try preregistering with a different name.
  2. Generate the DTLS Key and identity for the device for the preregistered device name.
  3. This generated identity and DTLS key has to be fed to the device configuration file by user. These two arguments need to be supplied during registration request from device agent.

12.1. Get DTLS Key for a Device

This API is available under the security section of API sandbox. This is used to query device PSK and identity for DTLS security for a pre registered device. Preregistration is a mandatory step for DTLS security mode usage.

Method : GET
URL : https://{domain}/dms/v1/device/security/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Request URL :

http://{dmservice_URL:PORT}/dms/v1/device/security/devtest

Response Body:

{
    "epnid": "devtest",
    "identity": "VFbg2Sbjnd67Jwt7",
    "psk": "csFODqSxK2FdPRVv"
}
Status Codes Message
200 DTLS Key for the device
404 Not found
401 Missing Key

12.2. Create DTLS Key for a Device

This API is available under the security section of API sandbox. This is used to generate device PSK and identity for DTLS security for a pre-registered device. Preregistration is mandatory step for DTLS security mode usage.

Method : POST
URL : https://{domain}/dms/v1/device/security/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Success Response Code :

200
Response Body:

{
    "epnid": "devtest",
    "identity": "VFbg2Sbjnd67Jwt7",
    "psk": "csFODqSxK2FdPRVv"
}
Status Codes Message
200 Generated DTLS Key for the device
404 Not found
401 Missing Key

12.3. Delete DTLS Key for a Device

This API is available under the security section of API sandbox. This API is used to delete already generated PSK for a device if the PSK is compromised and the Key needs to be invalidated for a new KEY to be generated.

Method : DELETE
URL : https://{domain}/dms/v1/device/security/{epnid}

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Parameter :

Success Response Code :

200
Response Body (Failure):

{
    "status": 404,
    "message": "no PSK info is present for this device"
}
Status Codes Message
200 for successful deletion
404 PSK for device not found

12.4. Change DTLS Key for a Device

This API is available under the security section of API sandbox. This API is used to update an already generated DTLS PSK for a device if the DTLS Key is compromised and the key needs to be invalidated to generate a new key.

Method : PUT
URL : https://{domain}/dms/v1/device/security/{epnid}

-

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Not Applicable

Respose Body:

{
    "epnid": "devtest",
    "identity": "VFbg2Sbjnd67Jwt7",
    "psk": "AYqlXSZ6UV8CRYZB"
}
Status Codes Message
200 Successful update of DTLS Key
404 existing DTLS Key for device not found

12.5. Create DTLS Key for a Set of Devices

This API is available under the security section of API sandbox. This is used for bulk generation of device DTLS PSK and identity for a set of pre-registered devices. Preregistration is mandatory step for DTLS security mode usage.

Method : POST
URL : https://{domain}/dms/v1/device/security

-

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

-

Request Body:

{
  "epnids": [
    "testa1","testa2"
  ]
}
Response Body:

[
  {
    "epnid": "testa1",
    "identity": "L1Emwje1YtO87eQW",
    "psk": "bIqJHlTaRmKm4mJa"
  },
  {
    "epnid": "testa2",
    "identity": "EVFz3fDQAKEgMhOV",
    "psk": "sUENrEDAc8V5u8j9"
  }
]
Status Codes Message
200 Generated DTLS Key for the device
404 Not Found
401 Missing Key

Note for Bootstrapping a Device with DTLS Keys:

In order to inform the bootstrap service module about the generated or updated keys, client application (user) has to call a bootstrap service’s rebootstrap API passing the generated DTLS key details after DTLS key is created. Once the rebootstrapping is done at the server side, the device bootstrap agent will automatically get the DTLS keys after some interval( interval based on bootstrap agent configuration). The device has to register in DTLS mode i.e. reconnect using DTLS PSK and identity on DTLS port ( 5684).

Parameter Value
epnId AIHFASD123
hour 720
data {sample below}

{
    "identity": "L1Emwje1YtO87eQW",
    "psk": "bIqJHlTaRmKm4mJa"
}

13. EventLog API

13.1. Query Device Event

This API is available under Event section of API sandbox. Every operation on device level gets logged at the DM server. This API provides a method of getting a list of events performed by user on selected device in DM .The events will be shown either in ascending or descending order (selectable) spanning over multiple pages.

Method : GET
URL : https://{domain}/dms/v1/device/{epnid}/eventlog

Header Description Sample Value
x-user-key DM User Key keydemo
x-api-key TCUP tenant key ucrFbEXFppyjF2cfFtrxfAIH2L4

Accept : application/json

Description of Request Elements in JSON

Parameter XSD Type Description Optional
limit Numeric Number of events to be displayed in a page N
token Alphanumeric To hold the current session N*
Pageno Numeric To jump to the page N*
Order String Sorting of the data Y
Method String Sorting of the data Y
Operation String Sorting of the data Y

Additional Notes:

If sortby option is not given the device events are shown in reverse chronological order i.e. the latest one is shown first.

Deleted device events cannot be queried .

GET /v1/device/{epnid}/eventlog

Content-Type: application/json

Response Body:

{
  "events": [
    {
      "txnid": "b1bddce0-b2a3-48fa-bc07-d87779094fae",
      "epnid": "dmtest",
      "resourceid": "",
      "method": "GET",
      "operation_type": "READ_DEVICE",
      "requested_at": "31-07-2018 10:26:33:466 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "read request for device with epnid:dmtest",
      "response_at": "31-07-2018 10:26:33:673 UTC",
      "response_code": 200,
      "response_content": "Device Fetched"
    },
    {
      "txnid": "82c2c6f5-3a8b-4aca-8370-4ef74f228fbb",
      "epnid": "dmtest",
      "resourceid": "customtoggle",
      "method": "PUT",
      "operation_type": "UPDATE_RESOURCE",
      "requested_at": "31-07-2018 09:03:02:111 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "update resource request for device with epnid:dmtest and resource:customtoggle to value:OFF",
      "response_at": "31-07-2018 09:03:02:254 UTC",
      "response_code": 200,
      "response_content": "Resource updated."
    },
    {
      "txnid": "2e832f02-a75a-45a4-a8d0-900f4ef55dd3",
      "epnid": "dmtest",
      "resourceid": "",
      "method": "GET",
      "operation_type": "READ_DEVICE",
      "requested_at": "31-07-2018 09:02:46:291 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "fromDevice=true",
      "content": "read request for device with epnid:dmtest",
      "response_at": "31-07-2018 09:02:46:664 UTC",
      "response_code": 200,
      "response_content": "Device Fetched"
    },
    {
      "txnid": "4ceab565-d3e7-4612-95c6-e1096a80a252",
      "epnid": "dmtest",
      "resourceid": "customtoggle",
      "method": "PUT",
      "operation_type": "UPDATE_RESOURCE",
      "requested_at": "31-07-2018 09:02:28:384 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "update resource request for device with epnid:dmtest and resource:customtoggle to value:ON",
      "response_at": "31-07-2018 09:02:28:597 UTC",
      "response_code": 200,
      "response_content": "Resource updated."
    },
    {
      "txnid": "baa1d378-1d44-400a-b609-00b1183a6a2f",
      "epnid": "dmtest",
      "resourceid": "customtoggle",
      "method": "POST",
      "operation_type": "CREATE_COMMAND",
      "requested_at": "31-07-2018 08:57:08:202 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "command scheduled for dmtest resource:customtoggle value:OFF after 30s",
      "response_at": "31-07-2018 08:57:08:310 UTC",
      "response_code": 202,
      "response_content": "command created"
    },
    {
      "txnid": "88e79005-a3ce-4998-81cf-ee5ed8a5af94",
      "epnid": "dmtest",
      "resourceid": "customstring",
      "method": "GET",
      "operation_type": "READ_RESOURCE",
      "requested_at": "31-07-2018 08:55:05:128 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "read resource request for device with epnid:dmtest and resource:customstring",
      "response_at": "31-07-2018 08:55:05:381 UTC",
      "response_code": 200,
      "response_content": "resource fetched"
    },
    {
      "txnid": "d8c4ec3f-e573-46c3-bf81-9de3ece51e59",
      "epnid": "dmtest",
      "resourceid": "systemUpTime",
      "method": "PUT",
      "operation_type": "CREATE_SUBSCRIPTION",
      "requested_at": "31-07-2018 08:38:23:893 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "autoResume=true",
      "content": "subscribe for resource:systemUpTime on device with epnid:dmtest",
      "response_at": "31-07-2018 08:38:24:232 UTC",
      "response_code": 200,
      "response_content": "Resource subscribed."
    },
    {
      "txnid": "a870702e-042c-439a-bec2-e43d5f506d03",
      "epnid": "dmtest",
      "resourceid": "systemUpTime",
      "method": "DELETE",
      "operation_type": "DELETE_SUBSCRIPTION",
      "requested_at": "23-07-2018 07:09:41:030 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "remove subscription for device with epnid:dmtest and resource:systemUpTime",
      "response_at": "23-07-2018 07:09:41:165 UTC",
      "response_code": 200,
      "response_content": "Subscription removed."
    },
    {
      "txnid": "617571cf-3ae6-4b2d-9394-dfb42820f0cc",
      "epnid": "dmtest",
      "resourceid": "systemUpTime",
      "method": "PUT",
      "operation_type": "CREATE_SUBSCRIPTION",
      "requested_at": "23-07-2018 07:09:32:546 UTC",
      "tcup_key": "xxxxxxxxxxxxxx",
      "user_key": "xxxxxxxxxxxxxx",
      "additional_request": "",
      "content": "subscribe for resource:systemUpTime on device with epnid:dmtest",
      "response_at": "23-07-2018 07:09:32:715 UTC",
      "response_code": 200,
      "response_content": "Resource subscribed."
    },
  ],
  "paging": {
    "totalCount": 9,
    "token": "PSKrd2IsU2yg6dQ",
    "pageno": 1
  }
}
Status Codes Message
200 List of events for select device
401 Missing Key

14. Actual Registration of Device

The generated identity and PSK has to be fed to the device configuration so that the device agent can pass on these parameters during registration. A typical registration request in a Linux gateway would look like:

java -jar dmclient-leshan.jar -ep "devtest" -key "keydemo" -p "5684" -id "VFbg2Sbjnd67Jwt7" -psk "csFODqSxK2FdPZBA"
java -jar dmclient-leshan.jar -ep "devtest" -key "keydemo"

Important Note :

As EPN parameter we use the same name which was preregistered. ID parameter should be the same generated identity and PSK should be the same generated PSK in DTLS Key generation step. For DTLS P(port) parameter should always be set to 5684.

When bootstrap is used we can ignore passing on IP,key , PSK ,ID arguments as those will be available to the device agent through bootstrap process.

Task Service

1. Introduction

Task services is used for batch oriented data processing on historical sensor data stored and managed by external data services such as TCUP Sensor Observation System. IoT applications need the ability to process high volumes of data collected over a period of time and perform analysis on this data in batch mode. Typical processing involves machine learning algorithms for generating and executing analytical models.

Task Services enables a large number of batch programs running analytics workloads to be executed in parallel on large server clusters. Developers provide the path to the program and specify the path to the data. Using Task Service APIs, users can upload the program to be executed. Task Service APIs can be used to execute these programs written in C, Java, Python etc. Application developers have the option of managing the schedule and specifying the number of nodes that will execute the tasks.

2. Reference Documents

Task Service Concept Guide

Task Service User’s Guide

3. Status Code

Status Code Meaning
200 Success
400 Bad Request – Request argument is invalid
401 Unauthorized – Your API key is wrong
403 Forbidden – Missing API Key
404 Not Found – Resource not found
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintenance. Please try again later.

4. Project

4.1. Creates a Project

This API enables to create a project with a given name.

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json

HTTP Request
POST /api/analytics/v4.0/projects

Request Body: 

curl -i -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"projectName": <project-name>}'
"http://<domainname>/api/analytics/v4.0/projects"
Response Body (Success): 

{
    "success": {
        "projectDetail": {
            "projectName": "Project",
            "projectId": "P1002",
            "createdTime": 1484567159207
        }
    }
}

JSON Parameters

Field Required Values Description
projectName true Project Project name

4.2. Fetches All the Created Project Details

This API returns all the projects created by the user.

HTTP Request
GET /api/analytics/v4.0/projects

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X GET
"http://<domainname>/api/analytics/v4.0/projects"
Response Body (Success): 

{
    "success": {
        "projectDetails": [
            {
                "projectName": "test",
                "projectId": "P1001",
                "createdTime": 1484558730096,
                "fileSize": 59932,
                "noOfTask": 9                
            }, {
                "projectName": "Project",
                "projectId": "P1002",
                "createdTime": 1484567159207,
                "fileSize": 12520,
                "noOfTask": 3
            }
        ]
    }
}

4.3. Fetches Project Details by ProjectID

This API fetches the project details by project ID.

HTTP Request
GET /api/analytics/v4.0/projects/

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X GET
"http://<domainname>/api/analytics/v4.0/projects/<project-id>"
Response Body (Success): 

{
    "success": {
        "projectDetail": {
            "projectName": "test",
            "projectId": "P1001",
            "createdTime": 1484558730096
        }
    }
}

Query Parameters

Field Required Values Description
projectName true Project Project name/pattern

4.4. Searches Projects by ProjectName

This API enables searching projects by project name.

HTTP Request
GET /analytics/v4.0/projects/search

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X GET --header "Accept: application/json" --header "x-api-key: <api-key>" "http://<domainname>/api/analytics/v4.0/projects/search?projectName=<project-name>"
Response Body: 

{
  "success": {
    "projectDetails": [
      {
        "projectName": "Project2",
        "projectId": "P12",
        "createdTime": 1556519309705
      },
      {
        "projectName": "ProjectEmpty",
        "projectId": "P47",
        "createdTime": 1559824248378
      }
    ]
  }
}

URL Parameters

Parameter Description
project-name name/pattern of required project

4.5. Searches Tasks by JobName/Status

This API searches tasks by name and status within the project given by ID.

HTTP Request
GET /api/analytics/v4.0/projects//tasks/search

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X GET
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/search?taskName=<task-name>&status=<task-status>"
Response Body: 

{
    "success": {
        "jobDetails": [
            {
                "projectId": "P1001",
                "jobName": "testTask",
                "jobId": "T1",
                "createdTime": 1484558744283,
                "isDelayed": false,
                "isRecurr": false,
                "jobState": "FINISHED",
                "isReadyToRun": true,
                "startAt": 1484563518613,
                "endAt": 1484563519844,
                "executableNm": "helloPython.py",
                "channel": {
                    "message": "channel added",
                    "channelName": "channel:P1001:1"
                },
                "outputFiles": [
                    "helloPython_Mon_Jan_16_2017_10:45:18_GMT_0000_(UTC).Rerr",
                    "helloPython_Mon_Jan_16_2017_10:45:18_GMT_0000_(UTC).Rout"
                ]
            }
        ]
    }
}

URL Parameters

Parameter Description
project-id ID of required project

Query Parameters

Field Required Values Description
taskName false test Task name
status false FINISHED Task status

4.6. Searches Delayed Tasks by JobName/Status

This API searches delayed tasks by name and status within project given by ID.

HTTP Request
GET /api/analytics/v4.0/projects//delayedTasks/search

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X GET
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/delayedTasks/search?taskName=<task-name>&status=<task-status>"
Response Body: 

{
  "success": {
    "jobDetails": [
      {
        "projectId": "P1001",
        "jobName": "cTask",
        "jobId": "T4",
        "createdTime": 1484562914670,
        "isDelayed": true,
        "isRecurr": false,
        "jobState": "FINISHED",
        "isReadyToRun": true,
        "delayedAt": 1484563080000,
        "startAt": 1484563517884,
        "endAt": 1484563520260,
        "executableNm": "cprogram.c",
        "channel": {
          "message": "channel added",
          "channelName": "channel:P1001:4"
        },
        "outputFiles": [
          "cprogram",
          "cprogram_Mon_Jan_16_2017_10:45:17_GMT_0000_(UTC).Rerr",
          "cprogram_Mon_Jan_16_2017_10:45:17_GMT_0000_(UTC).Rout"
        ]
      }
    ]
  }
}

URL Parameters

Parameter Description
project-id ID of required project

Query Parameters

Field Required Values Description
taskName false task Task name
status false FINISHED Task status

4.7. Searches Recurrent Tasks by JobName/Status

This API searches recurrent tasks by name, status or scheduling status within project given by ID.

HTTP Request
GET /api/analytics/v4.0/projects//recurrentTasks/search

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X GET
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/recurrentTasks/search?taskName=<task-name>&status=<task-status>&scheduleStatus=<schedule-status>"
Response Body: 

{
  "success": {
    "jobDetails": [
      {
        "projectId": "P1001",
        "jobName": "testRecurr2",
        "jobId": "T3",
        "createdTime": 1484561461928,
        "isDelayed": false,
        "isRecurr": true,
        "jobState": "FINISHED",
        "isReadyToRun": true,
        "scheduleStatus": "FINISHED",
        "startAt": 1484562243457,
        "endAt": 1484562244003,
        "scheduleStartAt": 1484561520367,
        "scheduleEndAt": 1484562244141,
        "cronPattern": "* * * * *",
        "runCountsLeft": 0,
        "counts": 1,
        "inputFiles": "data.csv",
        "executableNm": "code.R",
        "channel": {
          "message": "channel exists",
          "channelName": "channel:P1001:3"
        },
        "outputFiles": [
          "Rplots.pdf",
          "code_Mon_Jan_16_2017_10:24:03_GMT_0000_(UTC).Rerr",
          "code_Mon_Jan_16_2017_10:24:03_GMT_0000_(UTC).Rout"
        ]
      },
      {
        "projectId": "P1001",
        "jobName": "testRecurr",
        "jobId": "T2",
        "createdTime": 1484559644766,
        "isDelayed": false,
        "isRecurr": true,
        "jobState": "FINISHED",
        "isReadyToRun": true,
        "scheduleStatus": "FINISHED",
        "startAt": 1484562664810,
        "endAt": 1484562665342,
        "scheduleStartAt": 1484562540743,
        "scheduleEndAt": 1484562665342,
        "cronPattern": "* * * * *",
        "runCountsLeft": 0,
        "counts": 3,
        "inputFiles": "data.csv",
        "executableNm": "code.py",
        "channel": {
          "message": "channel exists",
          "channelName": "channel:P1001:2"
        },
        "outputFiles": [
          "Rplots.pdf",
          "code_Mon_Jan_16_2017_10:29:03_GMT_0000_(UTC).err",
          "code_Mon_Jan_16_2017_10:29:03_GMT_0000_(UTC).out"
        ]
      }
    ]
  }
}

URL Parameters

Parameter Description
project-id Id of required project

Query Parameters

Field Required Values Description
taskName false task Task name
status false FINISHED Task status
scheduleStatus false FINISHED Scheduling status

4.8. Deletes Project Details by ProjectID

This API deletes project details by ID.

HTTP Request
DELETE /api/analytics/v4.0/projects/

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -X DELETE
"http://<domainname>/api/analytics/v4.0/projects/<project-id>"
Response Body: 

{
    "success": "P1002 deleted"
}

URL Parameters

Parameter Description
project-id ID of required project

5. Task

Task is a one-time job, executed when started. Users can create tasks to test their algorithms and dataset, and check for desired results.

5.1. Creates a Task

This API creates a new task under a project.

HTTP Request
POST /api/analytics/v4.0/projects//tasks

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>"}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "Task1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "CREATED",
            "isReadyToRun": false
        }
    }
}

URL Parameters

Parameter Description
project-id ID of required project

JSON Parameters

Field Required Values Description
jobName true Task1 Task name

5.2. Copies a Task

This API enables copying the instance of a task.

HTTP Request
POST /api/analytics/v4.0/projects//copyTask

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>", "parentJobId": "<task-id>"}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/copyTask"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Task",
      "jobId": "T699",
      "createdTime": 1577177259630,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "runTime": "py",
      "executableNm": "working.py",
      "startAt": 0,
      "endAt": 0,
      "containerId": "",
      "outputFiles": []
    }
  }
}

URL Parameters

Parameter Description
project-id ID of required project

JSON Parameters

Field Required Values Description
jobName true Task New unique Task name
parentJobId true T366 ID of task to copy

5.3. Copies a Task to Delayed Task

This API copies the instance of a delayed task.

HTTP Request
POST /api/analytics/v4.0/projects//copyToDelayedTask

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>", "parentJobId": "<task-id>", "delayedAt": <timestamp>}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/copyToDelayedTask"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Taskr",
      "jobId": "D700",
      "createdTime": 1577177672331,
      "delayedAt": 1981196600000,
      "isDelayed": true,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "runTime": "py",
      "executableNm": "working.py",
      "startAt": 0,
      "endAt": 0,
      "containerId": "",
      "outputFiles": []
    }
  }
}

URL Parameters

Parameter Description
project-id ID of required project

JSON Parameters

Field Required Values Description
jobName true Task1 new unique Task name
parentJobId true T366 id of task to copy
delayedAt true 1981196600000 timestamp

5.4. Copies a Task to Recurrent Task

This API copies the instance of a task.

HTTP Request
POST /api/analytics/v4.0/projects//copyToRecurrentTask

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>", "parentJobId": "<task-id>", "cronPattern": "<cron-pattern>", "counts": <count>}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/copyToRecurrentTask"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Taske",
      "jobId": "R701",
      "createdTime": 1577177927586,
      "isDelayed": false,
      "isRecurr": true,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "cronPattern": "* * * * *",
      "counts": 0,
      "runTime": "py",
      "executableNm": "working.py",
      "startAt": 0,
      "endAt": 0,
      "containerId": "",
      "outputFiles": [],
      "infiniteRunCounts": 0
    }
  }
}

URL Parameters

Parameter Description
project-id ID of required project

Json Parameters

Field Required Values Description
jobName true Task1 new unique Task name
parentJobId true T366 ID of task to copy
cronPattern true * cron pattern
counts true 0 number of repetitions to run task

5.5. Uploads/ Downloads Files To/ From External Location

This API allows downloading/ uploading of files from/ to external locations on runtime.

HTTP Request
POST /api//analytics/v4.0/projects/updates/external

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'x-api-key: <api-key>' -d '{ \ 
   "projectId": "<project-id>", \ 
   "jobId": "<job-id>", \ 
   "externalInputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ], \ 
   "externalOutputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ] \ 
 }' 'https://ftqa11.tcupiot.com/api/analytics/v4.0/projects/updates/external'
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P47",
      "jobName": "checktask",
      "jobId": "T193",
      "createdTime": 1574229910941,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "FINISHED",
      "isReadyToRun": true,
      "startAt": 1574230190046,
      "endAt": 1574230195291,
      "executableNm": "Hello.cpp",
      "channel": {
        "message": "channel added",
        "channelName": "channel:P47:T193"
      },
      "outputFiles": [
        "Hello",
        "Hello.err",
        "Hello.out"
      ],
      "externalInputs": [
        {
          "originType": "task",
          "projectId": "P28",
          "jobId": "T25",
          "fileName": "*"
        }
      ]
    }
  }

JSON Parameters

Field Required Values Description
projectId true P47 ProjectId
jobId true T193 jobId
externalInputs[0].originType true task origin type
externalInputs[0].projectId true if externalInputs[0].originType==”task” P28 projectId of external input task
externalInputs[0].jobId true if externalInputs[0].originType==”task” T25 jobId of input task
externalInputs[0].fileName true if externalInputs[0].originType==”task” * pattern/files to copy at runtime
externalOutputs true null external outputs of task

5.6. Fetches any Task Details by ID

This API gets the details of a task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//details

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/details"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "DEPLOYED",
            "isReadyToRun": true,
            "startAt": 0,
            "endAt": 0,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.7. Fetches Task Status with Respect to ID

This API gets the status of a task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//status

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/status"
Response Body: 

{
    "success": {
        "jobStatus": "DEPLOYED"
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.8. Deploys any Task by ID

This API is used to deploy the created task under a particular project. Only created/ undeployed tasks can be deployed.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//deploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “multipart/form-data” and it is mandatory. @
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT -F "exe: @<file-name>" -F "runTime: <run-time>"
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/deploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "DEPLOYED",
            "isReadyToRun": true,
            "startAt": 0,
            "endAt": 0,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
exe true Executable file for task
inp false Data files(.zip file)
dpn false Dependent files(.zip file) of executableNm
runtimeArgs false Commandline runtime arguments for task execution
runTime true Runtime environment for task execution

5.9. Starts the Execution of a Task by ID

This API is used to start the execution of a task by ID. Tasks with status finished/ error/ deployed can be started.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//start

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “multipart/form-data” and it is mandatory. @
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/start"
Response Body: 
{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "QUEUED",
            "isReadyToRun": true,
            "startAt": 0,
            "endAt": 0,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files required for execution
runTimeArgs false Command line arguments for job execution

5.10. Pause the Execution of Any Task by ID

This API is used to pause the execution of a task by ID. Tasks with status running can only be paused.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//pause

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/pause"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "PAUSED",
            "isReadyToRun": true,
            "startAt": 1484635520498,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.11. Resume the Execution of Any Paused Task by ID

It is used to resume the execution of a task by ID. Tasks with status ‘paused’ only can be resumed.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//resume

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/resume"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "RUNNING",
            "isReadyToRun": true,
            "startAt": 1484635520498,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.12. Stops the Execution of Any Task Specfic by ID

This API is used to stop the execution of a task by ID. Tasks with only status ‘running’ and ‘queued’ can be stopped.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//stop

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/stop"
Response Body: 

{
    "success": {

        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "ABORTED",
            "isReadyToRun": true,
            "startAt": 1484637890280,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": [
                "infinitePython_Tue_Jan_17_2017_07:24:50_GMT_0000_(UTC).Rerr",
                "infinitePython_Tue_Jan_17_2017_07:24:50_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.13. Edits Any Task by ID

This API is used to edit a task by ID. Tasks with status ‘deployed’ can be edited.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//edit

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/edit"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Task",
      "jobId": "T699",
      "createdTime": 1577177259630,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "startAt": 0,
      "endAt": 0,
      "dependentFiles": "undefined",
      "inputFiles": "",
      "executableNm": "working.py",
      "outputFiles": []
    }
  }
}

URL Parameters

Parameter Description
task-id Id of required task
project-id Id of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files required for execution
runTimeArgs false Command line arguments for job execution

5.14. Undeploys any Task by ID

It is used to undeploy a task by ID. Tasks that are deployed/ finished/ aborted/ error can be undeployed.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//undeploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/undeploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "UNDEPLOYED",
            "isReadyToRun": false,
            "runTime": "",
            "executableNm": "",
            "outputFiles": [],
            "startAt": 0,
            "endAt": 0,
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "arguments": "",
            "dependentFiles": "",
            "inputFiles": ""
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.15. Deletes any Task Details by ID

It is used to delete a task by ID . Tasks with status Queued/ Running cannot be deleted.

HTTP Request
DELETE /api/analytics/v4.0/projects//tasks/

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>"
Response Body: 

{
    "success": {
        "message": "deleted",
        "jobDetails": {
            "projectId": "P1001",
            "jobName": "TaskSwagger1",
            "jobId": "T9",
            "createdTime": 1484564013487,
            "isDelayed": false,
            "isRecurr": false,
            "jobState": "DELETED",
            "isReadyToRun": true,
            "startAt": 1484640580366,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:9"
            },
            "outputFiles": [
                "infinitePython_Tue_Jan_17_2017_08:09:40_GMT_0000_(UTC).Rerr",
                "infinitePython_Tue_Jan_17_2017_08:09:40_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

5.16. Add External Input and Output Config to Task

It is used to add inputs and outputs to pre-configured destination. External config can be added only when Task is not Queued/ Running/ Paused.

**HTTP Request
POST /api/analytics/v4.0/projects/update/external

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>"
"http://<domainname>/api/analytics/v4.0/projects/updates/external"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P1001",
      "jobName": "TaskC1",
      "jobId": "T187",
      "createdTime": 1489142374398,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "runTime": "R",
      "arguments": "",
      "dependentFiles": "",
      "inputFiles": "data.csv",
      "executableNm": "code.R",
      "startAt": 0,
      "endAt": 0,
      "containerId": "",
      "outputFiles": []
    }
  }
}

JSON Parameters

Parameter Description
projectId ID of required project
jobId ID of required task
externalInputs Array of JSON objects with originType, projectId, jobId, fileName

5.17. Downloads Any File of Any Task by ID and FileName

Downloads files by file name for a task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//download

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/download?fileName=<file-name>"

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

Query Parameters

Field Required Description
fileName true Name of the file which is to be downloaded

6. Delayed Tasks

Delayed tasks are one-time tasks with execution at a delayed time given by user.

6.1. Create Delayed Task

Creates a new delayed Task under a project. Time of delay should be in Milliseconds since Unix Epoch (January 1, 1970, 0:00 UTC).

HTTP Request
POST /api/analytics/v4.0/projects//delayedTasks

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>", "delayedAt": <execution-time>}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/delayedTasks"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "DelayedTask",
            "jobId": "T11",
            "createdTime": 1484641428341,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "CREATED",
            "isReadyToRun": false,
            "delayedAt": 1484641800000
        }
    }
}

URL Parameters

Parameter Description
project-id Id of required project

-
JSON Parameters

Field Required Values Description
jobName true DelayedTask Task name
delayedAt true 1484641800000 Execution timestamp in milliseconds

6.2. Uploads/ Downloads Files To/ From External Location

This API will make things ready for download/upload of files to/from external location on runtime

HTTP Request
POST /api//analytics/v4.0/projects/updates/external

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'x-api-key: <api-key>' -d '{ \ 
   "projectId": "<project-id>", \ 
   "jobId": "<job-id>", \ 
   "externalInputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ], \ 
   "externalOutputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ] \ 
 }' 'https://ftqa11.tcupiot.com/api/analytics/v4.0/projects/updates/external'
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P47",
      "jobName": "checktask",
      "jobId": "T193",
      "createdTime": 1574229910941,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "FINISHED",
      "isReadyToRun": true,
      "startAt": 1574230190046,
      "endAt": 1574230195291,
      "executableNm": "Hello.cpp",
      "channel": {
        "message": "channel added",
        "channelName": "channel:P47:T193"
      },
      "outputFiles": [
        "Hello",
        "Hello.err",
        "Hello.out"
      ],
      "externalInputs": [
        {
          "originType": "task",
          "projectId": "P28",
          "jobId": "T25",
          "fileName": "*"
        }
      ]
    }
  }

JSON Parameters

Field Required Values Description
projectId true P47 ProjectId
jobId true T193 jobId
externalInputs[0].originType true task origin type
externalInputs[0].projectId true if externalInputs[0].originType==”task” P28 projectId of external input task
externalInputs[0].jobId true if externalInputs[0].originType==”task” T25 jobId of input task
externalInputs[0].fileName true if externalInputs[0].originType==”task” * pattern/files to copy at runtime
externalOutputs true null external outputs of task

6.3. Fetches Any Task Details by ID

This API helps to get the details of a Delayed Task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//details

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/details"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "DelayedTask",
            "jobId": "T11",
            "createdTime": 1484641428341,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "FINISHED",
            "isReadyToRun": true,
            "delayedAt": 1484641800000,
            "startAt": 1484641801472,
            "endAt": 1484641803174,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:11"
            },
            "outputFiles": [
                "helloPython_Tue_Jan_17_2017_08:30:01_GMT_0000_(UTC).Rerr",
                "helloPython_Tue_Jan_17_2017_08:30:01_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.4. Fetches Task Status With Respect to ID

This API helps to get the status of a delayed Task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//status

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/status"
Response Body: 

{
    "success": {
        "jobState": "FINISHED"
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.5. Deploys Any Task by ID

This API helps to deploy a particular delayed task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//deploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “multipart/form-data” and it is mandatory. @
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT -F "exe: @<file-name>" -F "runTime: <run-time>"
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/deploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "DelayedTask",
            "jobId": "T11",
            "createdTime": 1484641428341,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "DEPLOYED",
            "isReadyToRun": true,
            "delayedAt": 1484641800000,
            "executableNm": "helloPython.py"
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
exe true Executable file for task
inp false Data files(.zip file)
dpn false Dependent files(.zip file) of executableNm
runtimeArgs false Commandline runtime arguments for task execution
runTime true Runtime environment for task execution

6.6. Starts the Execution of a Delayed Task by ID

This API helps to run a particular delayed task.

HTTP Request
PUT /api/analytics/v4.0/projects//delayedTasks//start

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/start"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "DelayedTask",
            "jobId": "T11",
            "createdTime": 1484641428341,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "QUEUED",
            "isReadyToRun": true,
            "delayedAt": 1484641800000,
            "startAt": 0,
            "endAt": 0,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:11"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files(.zip file)
runtimeArgs false Commandline runtime arguments for task execution

6.7. Pause the Execution of Any Task by ID

This API enables pausing a running delayed Task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//pause

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/pause"
Response Body: 

{
    "success": {
        "jobDetails": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "PAUSED",
            "isReadyToRun": true,
            "delayedAt": 1484642520000,
            "startAt": 1484642524489,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.8. Resume the Execution of Any Paused Task by ID

This API enables to resume a paused delayed task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//resume

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

 curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/resume"
Response Body: 

{
    "success": {
        "jobDetails": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "RUNNING",
            "isReadyToRun": true,
            "delayedAt": 1484642520000,
            "startAt": 1484642980384,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.9. Stops the Execution of Any Task Specfic by ID

This API stops a running delayed task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//stop

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/stop"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "ABORTED",
            "isReadyToRun": true,
            "delayedAt": 1484642520000,
            "startAt": 1484642980384,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": [
                "infinitePython_Tue_Jan_17_2017_08:42:04_GMT_0000_(UTC).Rerr",
                "infinitePython_Tue_Jan_17_2017_08:42:04_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.10. Undeploys any Task by ID

This API enables to undeploy a stopped task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//undeploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/undeploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "DelayedTask",
            "jobId": "T11",
            "createdTime": 1484641428341,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "UNDEPLOYED",
            "isReadyToRun": false,
            "delayedAt": 1484641800000,
            "runTime": "",
            "executableNm": "",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:11"
            },
            "startAt": 0,
            "endAt": 0,
            "outputFiles": [],
            "containerId": "",
            "arguments": "",
            "dependentFiles": "",
            "inputFiles": ""
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.11. Reschedules a Delayed Task by ID

This API reschedules a delayed task that has completed execution.

HTTP Request
PUT /api/analytics/v4.0/projects//delayedTasks//reschedule

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT -F "delayedAt: <delayed-time>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/delayedTasks/<task-id>/reschedule"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "QUEUED",
            "isReadyToRun": true,
            "delayedAt": 1484643900000,
            "startAt": 0,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files(.zip file)
runtimeArgs false Commandline runtime arguments for task execution
delayedAt true Execution timestamp in milliseconds

6.12. Edits Any Task by ID

This API is used to edit a task by ID. Tasks with status ‘deployed’ can be edited.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//edit

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/edit"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Task",
      "jobId": "T699",
      "createdTime": 1577177259630,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "startAt": 0,
      "endAt": 0,
      "dependentFiles": "undefined",
      "inputFiles": "",
      "executableNm": "working.py",
      "outputFiles": []
    }
  }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files required for execution
runTimeArgs false Command line arguments for job execution

6.13. Deletes any Task Details by ID

This API is used to delete a delayed task.

HTTP Request
DELETE /api/analytics/v4.0/projects//tasks/

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>"
Response Body: 

{
    "success": {
        "message": "deleted",
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "DELETED",
            "isReadyToRun": true,
            "delayedAt": 1484643900000,
            "startAt": 1484643903102,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": [
                "infinitePython_Tue_Jan_17_2017_09:05:02_GMT_0000_(UTC).Rerr",
                "infinitePython_Tue_Jan_17_2017_09:05:02_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

6.14. Downloads Any File of Any Task by ID and FileName

This API is used to download files by file name for a task

HTTP Request
GET /api/analytics/v4.0/projects//tasks//download

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/download?fileName=<file-name>"

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
fileName true Name of the file which is to be downloaded

7. Recurrent Tasks

Recurrent tasks are executed recurrently in cron-like recurrence interval.

7.1. Create Recurrent Task

This API is used to create a new recurrent task under a project.

HTTP Request
POST /api/analytics/v4.0/projects//recurrentTasks

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" -X POST -d '{"jobName": "<task-name>", "cronPattern": <cron-pattern>, "counts": 0}' 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/recurrentTasks"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "CREATED",
            "isReadyToRun": false,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0
        }
    }
}

URL Parameters

Parameter Description
project-id ID of required project

-
JSON Parameters

Field Required Values Description
jobName true DelayedTask Task name
cronPattern true * Cron-like recurrent interval for execution
counts true 0 Recurrence limit; If 0, no limit for recurrence

7.2. Uploads/ Downloads Files To/ From External Location

This API will be used to download/upload of files to/from external location on runtime.

HTTP Request
POST /api//analytics/v4.0/projects/updates/external

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'x-api-key: <api-key>' -d '{ \ 
   "projectId": "<project-id>", \ 
   "jobId": "<job-id>", \ 
   "externalInputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ], \ 
   "externalOutputs": [ \ 
     { \ 
       "originType": "<origin-type>", \ 
       "fileName": "<file-name>" \ 
     } \ 
   ] \ 
 }' 'https://ftqa11.tcupiot.com/api/analytics/v4.0/projects/updates/external'
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P47",
      "jobName": "checktask",
      "jobId": "T193",
      "createdTime": 1574229910941,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "FINISHED",
      "isReadyToRun": true,
      "startAt": 1574230190046,
      "endAt": 1574230195291,
      "executableNm": "Hello.cpp",
      "channel": {
        "message": "channel added",
        "channelName": "channel:P47:T193"
      },
      "outputFiles": [
        "Hello",
        "Hello.err",
        "Hello.out"
      ],
      "externalInputs": [
        {
          "originType": "task",
          "projectId": "P28",
          "jobId": "T25",
          "fileName": "*"
        }
      ]
    }
  }

JSON Parameters

Field Required Values Description
projectId true P47 ProjectId
jobId true T193 jobId
externalInputs[0].originType true task origin type
externalInputs[0].projectId true if externalInputs[0].originType==”task” P28 projectId of external input task
externalInputs[0].jobId true if externalInputs[0].originType==”task” T25 jobId of input task
externalInputs[0].fileName true if externalInputs[0].originType==”task” * pattern/files to copy at runtime
externalOutputs true null external outputs of task

7.3. Fetches Any Task Details by ID

This API is used to get details of a recurrent task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//details

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/details"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T14",
            "createdTime": 1484648642371,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "RUNNING",
            "isReadyToRun": true,
            "scheduleStatus": "RUNNING",
            "startAt": 1484648852704,
            "endAt": 0,
            "scheduleStartAt": 1484648700428,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:14"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.4. Fetches Task Status With Respect to ID

This API is used to get the status of a recurrent task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//status

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/status"
Response Body: 

{
    "success": {
        "jobStatus": "RUNNING",
        "scheduleStatus": "RUNNING",
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.5. Deploys Any Task by ID

This API is used to deploy a particular recurrent task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//deploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “multipart/form-data” and it is mandatory. @
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT -F "exe: @<file-name>" -F "runTime:<run-time>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/deploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "DEPLOYED",
            "isReadyToRun": true,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0,
            "executableNm": "helloPython.py"
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
exe true Executable file for task
inp false Data files(.zip file)
dpn false Dependent files(.zip file) of executableNm
runtimeArgs false Commandline runtime arguments for task execution
runTime true Runtime environment for task execution

7.6. Starts the Execution of a Recurrent Task by ID

This API is used to run a particular recurrent task.

HTTP Request
PUT /api/analytics/v4.0/projects//recurrentTasks//start

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT  
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/start"
Response Body: 

{
    "success": {
        "jobDetails": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "QUEUED",
            "isReadyToRun": true,
            "scheduleStatus": "RUNNING",
            "startAt": 0,
            "endAt": 0,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:13"
            }
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files(.zip file)
runtimeArgs false Commandline runtime arguments for task execution

7.7. Edits Any Task by ID

This API is used to edit a task by ID. Tasks with status ‘deployed’ can be edited.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//edit

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/edit"
Response Body: 

{
  "success": {
    "jobDetail": {
      "projectId": "P128",
      "jobName": "Task",
      "jobId": "T699",
      "createdTime": 1577177259630,
      "isDelayed": false,
      "isRecurr": false,
      "jobState": "DEPLOYED",
      "isReadyToRun": true,
      "startAt": 0,
      "endAt": 0,
      "dependentFiles": "undefined",
      "inputFiles": "",
      "executableNm": "working.py",
      "outputFiles": []
    }
  }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files required for execution
runTimeArgs false Command line arguments for job execution

7.8. Cancels Scheduling of a Recurrent Task by ID

This API is used to cancel a running recurrent task.

HTTP Request
PUT /api/analytics/v4.0/projects//recurrentTasks//cancel

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/recurrentTasks/<task-id>/cancel"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "FINISHED",
            "isReadyToRun": true,
            "scheduleStatus": "CANCELLED",
            "startAt": 1484648225757,
            "endAt": 1484648225996,
            "scheduleStartAt": 1484647800923,
            "scheduleEndAt": 1484648271310,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 8,
            "executableNm": "helloPython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:13"
            },
            "outputFiles": [
                "helloPython_Tue_Jan_17_2017_10:10:02_GMT_0000_(UTC).Rerr",
                "helloPython_Tue_Jan_17_2017_10:10:02_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.9. Pause the Execution of Any Task by ID

This API is used to pause a running recurrent task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//pause

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/pause"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T14",
            "createdTime": 1484648642371,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "PAUSED",
            "isReadyToRun": true,
            "scheduleStatus": "RUNNING",
            "startAt": 1484648701272,
            "endAt": 0,
            "scheduleStartAt": 1484648700428,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:14"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.10. Resume the execution of any paused Task by ID

This API is used to resume a paused recurrent task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//resume

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/resume"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T14",
            "createdTime": 1484648642371,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "RUNNING",
            "isReadyToRun": true,
            "scheduleStatus": "RUNNING",
            "startAt": 1484648852704,
            "endAt": 0,
            "scheduleStartAt": 1484648700428,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:14"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.11. Stops the Execution of Any Task Specfic by ID

This API is used to stop a running delayed task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//stop

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/stop"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "TestDelayed",
            "jobId": "T12",
            "createdTime": 1484642235121,
            "isDelayed": true,
            "isRecurr": false,
            "jobState": "ABORTED",
            "isReadyToRun": true,
            "delayedAt": 1484642520000,
            "startAt": 1484642980384,
            "endAt": 0,
            "executableNm": "infinitePython.py",
            "channel": {
                "message": "channel exists",
                "channelName": "channel:P1001:12"
            },
            "outputFiles": [
                "infinitePython_Tue_Jan_17_2017_08:42:04_GMT_0000_(UTC).Rerr",
                "infinitePython_Tue_Jan_17_2017_08:42:04_GMT_0000_(UTC).Rout"
            ]
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.12. Undeploys Any Task by ID

This API is used to undeploy a stopped task.

HTTP Request
PUT /api/analytics/v4.0/projects//tasks//undeploy

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i -XPUT -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/undeploy"
Response Body: 

{
    "success": {
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "UNDEPLOYED",
            "isReadyToRun": false,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 8,
            "runTime": "",
            "executableNm": "",
            "scheduleStatus": "CANCELLED",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:13"
            },
            "startAt": 0,
            "endAt": 0,
            "scheduleStartAt": 1484647800923,
            "containerId": "",
            "outputFiles": [],
            "scheduleEndAt": 1484648271310,
            "arguments": "",
            "dependentFiles": "",
            "inputFiles": ""
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.13. Reschedules a Recurrent Task by ID

This API is used to reschedule a recurrent task changing the recurrence interval.

HTTP Request
PUT /api/analytics/v4.0/projects//recurrentTasks//reschedule

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Request Body: 

curl -i -H "x-api-key: <api-key>" -XPUT -F "counts: <counts>" -F "cronPattern:<cron-pattern>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/reschedule"
Response Body: 

{   
    "success": {
        "jobDetail": {
            "projectId": "P1017",
            "jobName": "test_Recurr",
            "jobId": "T60",
            "createdTime": 1485249811926,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "QUEUED",
            "isReadyToRun": true,
            "scheduleStatus": "RUNNING",
            "startAt": 0,
            "endAt": 0,
            "scheduleStartAt": 1485249840683,
            "scheduleEndAt": 1485250806275,
            "cronPattern": "* * * * *",
            "runCountsLeft": 1,
            "counts": 1,
            "inputFiles": "data.csv",
            "executableNm": "code.R",
            "channel": {
              "message": "channel exists",
              "channelName": "channel:P1017:60"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

-
Query Parameters

Field Required Description
apiKey true Task name

-
JSON Parameters

Field Required Description
inpFile false Data files(.zip file)
runtimeArgs false Commandline runtime arguments for task execution
cronPattern true Cron-like recurrence interval for execution
counts true Recurrence limit; If 0, no limit for recurrence

7.14. Deletes Any Task Details by ID

This API is used to delete a recurrent task.

HTTP Request
DELETE /api/analytics/v4.0/projects/<project-id>/tasks/<task-id>

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>"
Response Body: 

{
    "success": {
        "message": "deleted",
        "jobDetail": {
            "projectId": "P1001",
            "jobName": "RecurrentTask",
            "jobId": "T13",
            "createdTime": 1484647271941,
            "isDelayed": false,
            "isRecurr": true,
            "jobState": "DELETED",
            "isReadyToRun": false,
            "scheduleStatus": "CANCELLED",
            "startAt": 0,
            "endAt": 0,
            "scheduleStartAt": 1484647800923,
            "scheduleEndAt": 1484648271310,
            "cronPattern": "* * * * *",
            "counts": 0,
            "infiniteRunCounts": 8,
            "dependentFiles": "",
            "inputFiles": "",
            "executableNm": "",
            "channel": {
                "message": "channel added",
                "channelName": "channel:P1001:13"
            },
            "outputFiles": []
        }
    }
}

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

7.15. Downloads Any File of Any Task by ID and File Name

This API is used to download files by file name for a task.

HTTP Request
GET /api/analytics/v4.0/projects//tasks//download

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -i  -H "Content-Type: application/json" -H "x-api-key: <api-key>" 
"http://<domainname>/api/analytics/v4.0/projects/<project-id>/tasks/<task-id>/download?fileName=<file-name>"

URL Parameters

Parameter Description
task-id ID of required task
project-id ID of required project

Query Parameters

Field Required Description
fileName true Name of the file which is to be downloaded

8. Migrate

8.1. Exports the Project With All Its Tasks and Compresses It

This API is used to export the project with all its tasks and compress it.

HTTP Request
GET /api/analytics/v4.0/projects/export

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/zip' --header 'x-api-key: <api-key>' -d '{ \ 
   "projectId": "<project-id>" \ 
 }' 'http://<domain-name>/api/analytics/v4.0/projects/export'

JSON Parameters

Field Required Values Description
projectId true P128 projectID of project to export

8.2. Imports the Project With All Its Tasks Into This User

This API is used to import a project with all its tasks.

HTTP Request
GET /api/analytics/v4.0/projects/import

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “multipart/form-data” and it is mandatory. @
Request Body: 

curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'x-api-key: <api-key>' -F projectName=<project-name>  'http://<domain-name>/api/analytics/v4.0/projects/import'

JSON Parameters

Parameter Required Description
projectName false unique project name
inp true supported zip file

9. Stats

9.1. Display Tasks Statistics Under a Particular API Key

This API is used to get the tasks statistics under a particular apiKey.

HTTP Request
GET /api/analytics/v4.0/tasks/stats

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and it is mandatory. application/json
Request Body: 

curl -X GET --header 'Accept: application/json' --header 'x-api-key: <x-api-key>' 'https://ftqa11.tcupiot.com/api/analytics/v4.0/tasks/stats'
Response Body: 

{
  "success": {
    "statDetails": [
      {
        "totalTasks": 6,
        "totalQueuedTasks": 0,
        "totalRunningTasks": 0,
        "totalScheduleRunning": 0,
        "totalScheduleFinished": 0,
        "totalFinishedTasks": 2,
        "totalNormalTasks": 6,
        "totalDelayedTasks": 0,
        "totalRecurrentTasks": 0
      }
    ]
  }
}

Application Service

1. Introduction

Application Service helps to deploy web applications on cloud environment with simple APIs. Once deployed, users can access applications through unique URLs.

2. Reference Documents

Application Service User’s Guide

Application Service Concept Guide

3. API Details

3.1 Request Headers

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

3.2. Status Code

Status Code Message
200 Ok
400 Bad Request
401 Unauthorized – Invalid API key
404 Invalid Payload
500 Internal Server Error

3.3 Create Application

This API endpoint creates a new application. The formats currently supported are war, play-1.2.5 and play-2.2.1.

HTTP Request
POST /api/v1/tcup/applications

Request Body:

 curl -i  -H "Content-Type: application/json" -H "x-api-key: <x-api-key>" -X POST -d '{"name": "SampleApplication","type":"war","description":"testing","logo":"xyz","callbackUrl":"/demo/url"}' 
"http://<domainname>/api/v1/tcup/applications"
Response Body:

{
    "name": "TestApplication",
    "type": "play",
    "desc": "testing",
    "status": "Registered",
    "appKey": "cbn2GjZAzsHYhX1Balyey4UPE6E=",
    "appID": "dierte5464vdg64",
    "url": "/demo/url"
}

JSON Parameters

Field Required Values Description
name true SampleApplication Name of the application
type true war Type of application
description true A demo app Brief description about the application
logo true xyz Application’s logo
callbackUrl true /demo/url Application’s callback URL

3.4. Get All Applications

This API endpoint is used to get the list of all the applications for a given x-api-key.

HTTP Request
GET /api/v1/tcup/applications

Request Body:

 curl -i -H "x-api-key: <x-api-key>"  "http://<domainname>/api/v1/tcup/applications"
Response Body (Success): 

{
 "applications" : [ {
    "name" : "TestApplication1",
    "type" : "war",
    "desc" : "PredictorV2",
    "status" : "Stopped",
    "appKey" : "cbn2GjZAzsHYhX1Balyey4UPE6E=",
    "appID": "cbn2GjZAzsHYhX1Balyey4UPE6E=1450157731320",
    "callbackUrl": "/demo/url1",
    "logo":"xyz"
  }, {
    "name" : "TestApplication2",
    "type" : "play-2.2.1",
    "desc" : "ScadaV1",
    "status" : "Started",
    "appKey" : "RqrsJ0KH83aUuvVh2cOnMMAZeA4=",
    "appID": "RqrsJ0KH83aUuvVh2cOnMMAZeA4=1450157731320",
    "callbackUrl": "/demo/url2",
    "logo":"xyz"
  } ]
}

3.5. Get Application by Application ID

This API endpoint is used to get an application for a given x-api-key by the unique application ID.

HTTP Request
GET /api/v1/tcup/applications/<app-id>

Request Body:

curl -i -H "x-api-key: <x-api-key>"  "http://<domainname>/api/v1/tcup/applications/<app-id>"
Response Body (Success): 

{
 "applications" : [ {
    "name" : "TestApplication1",
    "type" : "play",
    "desc" : "PredictorV2",
    "status" : "Stopped",
    "appKey" : "cbn2GjZAzsHYhX1Balyey4UPE6E=",
    "appID": "cbn2GjZAzsHYhX1Balyey4UPE6E=1450157731320",
    "callbackUrl": "/demo/url1",
    "logo":"xyz"
  } ]
}

URL Parameters

Parameter Description
app-id The unique application ID.

3.6. Deploy Application

This API endpoint is used to deploy the application matching the provided application ID.

HTTP Request
POST /api/v1/tcup/applications/<app-id>/deploy

Request Body:

curl -i -H "x-api-key : <x-api-key>" --data-binary <file-location> -X POST http://<domainname>/api/v1/tcup/applications/<app-id>/deploy
Response Body (Success): 

{ 
    "name" : "TestApplication1",
    "status" : "Deployed",
    "url" : http://<donain>/app/sample/TestApplication1",
    "callbackUrl": "/demo/url",
    "logo":"xyz"    
}

URL Parameters

Parameter Description
app-id The unique application-ID.

Note: Zip file has to be uploaded for play applications.

3.7. Start Application

This API endpoint is used to start the application matching the provided app_id.

HTTP Request
POST /api/v1/tcup/applications/<app-id>/start

Request Body:

curl -i -H "x-api-key : <x-api-key>" -X POST http://<domainname>/api/v1/tcup/applications/<app-id>/start
Response Body (Success): 

{
    "name" : "TestApplication1",
    "status" : "Started",
    "url" : http://<donain>/app/sample/TestApplication1",
    "callbackUrl": "/demo/url",
    "logo":"xyz"
}

URL Parameters

Parameter Description
app-id The unique application-id.

3.8. Stop Application

This API endpoint is used to stop the application matching the provided app_id.

HTTP Request
POST /api/v1/tcup/applications/<app-id>/stop

Request Body:

curl -i -H "x-api-key : <x-api-key>" -X POST http://<domainname>/api/v1/tcup/applications/<app-id>/stop
Response Body (Success): 

{
    "name" : "TestApplication1",
    "status" : "Stopped",
    "callbackUrl": "/demo/url",
    "logo":"xyz"
}

URL Parameters

Parameter Description
app-id The unique application-id.

3.9. Reload Application

This API endpoint is used to start the application matching the provided app_id.

HTTP Request
POST /api/v1/tcup/applications/<app-id>/reload

Request Body:

curl -i -H "x-api-key : <x-api-key>" -X POST http://<domainname>/api/v1/tcup/applications/<app-id>/reload
Response Body (Success): 

{
    "name" : "TestApplication1",
    "status" : "Reloaded",
    "url" : http://<donain>/app/sample/TestApplication1",
    "callbackUrl": "/demo/url",
    "logo":"xyz"
}

URL Parameters

Parameter Description
app-id The unique application-id.

3.10. Undeploy Application

This API endpoint is used to undeploy the application matching the provided app_id.

HTTP Request
POST /api/v1/tcup/applications/<app-id>/undeploy

Request Body:

curl -i -H "x-api-key : <x-api-key>" -X POST http://<domainname>/api/v1/tcup/applications/<app-id>/undeploy
Response Body (Success): 

{
    "name" : "TestApplication1",
    "status" : "Undeployed",
    "url" : http://<donain>/app/sample/TestApplication1",
    "logo":"xyz"
}

URL Parameters

Parameter Description
app-id The unique application-id.

3.11. Delete Application

This API endpoint is used to delete the application matching the provided app_id.

HTTP Request
DELETE /api/v1/tcup/applications/<app-id>

Request Body:

curl -i -H "x-api-key : <x-api-key>" -X DELETE http://<domainname>/api/v1/tcup/applications/<app-id>
Response Body (Success): 

{
    "name" : "TestApplication1",
    "status" : "Successfully deleted"
}

URL Parameters

Parameter Description
app-id The unique application-id.

Database Service

1. Introduction

TCUP facilitates to deploy and run applications on its Application Deployment service. Such applications may need a relational database for its use. TCUP Database Service provides a database infrastructure for such applications.

TCUP Database Service is a relational database service. It allows the user to create and use a PostGres database. This allows the application developer to use RDBMS to store data without taking the pain of provisioning a server and installing a separate database.
Developers can create their own database through a web interface or API. They can also upload SQL file and create or update schema.

2. Reference Documents

Database Service Concept Guide

Database Service User’s Guide

2.1. Request Headers

Header Description Sample Value
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

2.2. Status Code

Status Code Message
200 Ok
400 Bad Request
401 Unauthorized – Invalid API key
404 Invalid Payload
500 Internal Server Error

3. API Details

3.1 Create Database Schema

This API endpoint creates a new database (relational database). Currently postgresql type database creation is supported.

HTTP Request
POST /api/db/v2.0/databases

Request Body:

 curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/plain' --header 'x-api-key: 8eb86b5e40467b3439d24bcd93654094589d135903aa3ec986b95e21002d23fe' -d 
 '{ \ 
   "dbName": "tdb1", \ 
   "databaseType": "Postgresql", \ 
   "username": "tenant1", \ 
   "dbUsername": "tuser2", \ 
   "dbPassword": "Tuser2%40123" \ 
 }' 'http://<domainname>/api/db/v2.0/databases'
Response Body (Success):

{
  "status" : "OK",
  "id" : 38,
  "dbName" : "tdb1_tenant1",
  "host" : "postgres",
  "connectionurl" : "jdbc:postgresql://postgres:5432/tdb1_tenant1",
  "dbUsername" : "tuser2_tenant1",
  "registeredDate" : "10-01-2020 08:13:16 UTC"
}

JSON Parameters

Field Required Values Description
username true dummyUser2 TCUP tenant username is
dbName true Sampledb TCUP database name
databaseType true Postgresql TCUP Postgresql structure
dbUsername true xyz Database username is uesd
dbPassword true xyz Database password is used

3.2. Get All Database Details

This API endpoint gives the details (connection URL, db password, db username, hostname where the database is created, registered date) of all databases.

HTTP Request
GET /api/db/v2.0/databases

Request Body:

curl -i -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK9M="  
"http://<domainname>/api/db/v2.0/databases"
Response Body:

{
  "status" : "OK",
  "dbs" : [ {
    "id" : 2,
    "dbName" : "dbname4_testtenant",
    "host" : "postgres",
    "connectionurl" : "jdbc:postgresql://postgres:5432/dbname4_testtenant",
    "dbUsername" : "dbuser4_testtenant",
    "registeredDate" : "25-11-2019 06:22:22 UTC"
  }, {
    "id" : 36,
    "dbName" : "testdb_tenant1",
    "host" : "postgres",
    "connectionurl" : "jdbc:postgresql://postgres:5432/testdb_tenant1",
    "dbUsername" : "testuser_tenant1",
    "registeredDate" : "13-12-2019 09:13:32 UTC"
  }, {
    "id" : 37,
    "dbName" : "tdb_tenant1",
    "host" : "postgres",
    "connectionurl" : "jdbc:postgresql://postgres:5432/tdb_tenant1",
    "dbUsername" : "tuser_tenant1",
    "registeredDate" : "10-01-2020 08:10:27 UTC"
  }, {
    "id" : 38,
    "dbName" : "tdb1_tenant1",
    "host" : "postgres",
    "connectionurl" : "jdbc:postgresql://postgres:5432/tdb1_tenant1",
    "dbUsername" : "tuser2_tenant1",
    "registeredDate" : "10-01-2020 08:13:16 UTC"
  } ]
}

3.3. Get Database Detail

This API endpoint gives the details (connection URL, db password, db username, hostname where the database is created, registered date) of the requested database.

HTTP Request
GET /api/db/v2.0/databases/

Request Body:

curl -i -H "x-api-key: NZOlaIbIQikF9FoNbdbLsOwK9M="  
"http://<domainname>/api/db/v2.0/databases/38"
Response Body:

{
  "status" : "OK",
  "id" : 38,
  "dbName" : "tdb1_tenant1",
  "host" : "postgres",
  "connectionurl" : "jdbc:postgresql://postgres:5432/tdb1_tenant1",
  "dbUsername" : "tuser2_tenant1",
  "registeredDate" : "10-01-2020 08:13:16 UTC"
}

URL Parameters

Parameter Description
db_id The ID of the database

3.4. Get Database Count

This API endpoint gives the count of databases registered by a tenant.

HTTP Request
GET /api/db/v2.0/databases/stats

Request Body:

curl -X GET --header 'Accept: application/json' --header 'x-api-key: 8eb86b5e40467b3439d24bcd93654094589d135903aa3ec986b95e21002d23fe' 'http://<domainname>/api/db/v2.0/databases/stats'
Response Body:

{
  "database_count": 4
}

3.5. Update Database

This API endpoint updates a schema against the db ID provided. Currently supports the updation of postgresql database.

HTTP Request
PUT /api/db/v2.0/databases/

Request Body:

curl -X PUT --header 'Content-Type: multipart/form-data' --header 'Accept: text/plain' --header 'dbPassword: Tuser2@123' --header 'x-api-key: 8eb86b5e40467b3439d24bcd93654094589d135903aa3ec986b95e21002d23fe' {"type":"formData"} 'http://<domainname>/api/db/v2.0/databases/38'
Response:

Script executed successfully.

URL Parameters

Parameter Description
db_id The ID of the database

Additional Header

Parameter Description
dbPassword database password

3.6. Delete Database Schema

This API endpoint deletes a schema against the db ID provided. Currently supports the deletion of postgresql database.

HTTP Request
Delete /api/db/v2.0/databases/

Request Body:

curl -i -H "x-api-key : 4d62a44e-f7af-441a-80ba-e2376ce0fae1" -X DELETE http://10.100.10.220:6400/api/db/v2.0/databases/41
Response Body:

[
 Database dropped successfully! 
]



Asset Service

1. Introduction

This document provides a comprehensive architectural overview of the system using a number of different architectural views to depict different aspects of the system. It is intended to capture and convey the significant architectural decisions which have been made on the system.

1.1. How does Asset Service work?

Asset Service is deployed in TCUP cloud. This is a RESTful web-service which accepts JSON payload.

1.2. What are the RESTful resources in Asset Service

1.3. Request Headers

Header Description Sample Value
x-user-key Valid user key of the user under a valid tenant. It is also mandatory in every call. keydemo
x-api-key Valid API key of the tenant is needed in every call and is mandatory. ucrFbEXFppyjF2cfFtrxfAIH2L4
Content-Type Its value is “application/json” and is needed in every API call but it is not mandatory. application/json

1.4. Status Code

Status Codes Message
201 CREATED
205 UPDATED
200 SUCCESS
204 DELETE
401 UNAUTHORISED
500 Internal Server Error
404 Not Found
400 Bad Request

1.5. Supported Time Format

The following timestamp formats are supported. SOS can store time-stamp up to millisecond level. All incoming time-zone is converted into Coordinated Universal Time(UTC) and stored.

Example: 04-OCT-2016 16:30:20.220 IST

2. Reference Documents

Asset Service Concept Guide

Asset Service User’s Guide

API Components

3. Asset Domain

3.1. Create Asset Domain

This API is used to create asset domain. A valid asset domain name must be present in the JSON payload as the only mandatory field.

Method: POST
URL: https://{domain}/AssetService/assetdomain/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
 "assetDomainName": "MyDomain1", 
 "description": "something"
}

Response

[
  {
    "id": "2",
    "httpStatus": "201",
    "status": "Asset Domain created for domain [MyDomain1] with domainid [2]"
  }
]

3.2. Update Asset Domain

This API helps to update an existing domain except its asset domain ID.

Method: PUT
URL: https://{domain}/AssetService/assetdomain/update

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "assetDomainId": "1",
  "assetDomainName": "Energy",
  "icon": "icon.jpg",
  "description": "Energy domain"
}

Response

[
  {
    "id": "1",
    "httpStatus": "205",
    "status": "asset domain updated"
   }
]

3.3. Get Asset Domain by ID

Retrieve the exisitng asset domain JSON for the mentioned assetdomain ID from the request parametes.

Method: GET
URL: https://{domain}/AssetService/assetdomain/getbyid

Key value
Header x-api-key, x-user-key (optional)

Response

{
  "assetDomainId": "1",
  "assetDomainName": "MyNewDOmainname",
  "description": "some description,
  "icon": "icon.jpg",
  "createdTime": "11-JUL-2016 10:45:07.640 IST",
  "domain": "1"
}

3.4. Get All Asset Domain

This API lists all the active asset domains irrespective of the tenant or the users.

Method: GET
URL: https://{domain}/AssetService/assetdomain/getall

Key Value
Header x-api-key, x-user-key (optional)

Response

[
  {
    "assetDomainId": "1",
    "assetDomainName": "Utility",
    "domainGuid":  "5bcc515a3d2f44aab86d7a2fcd131632138589823763957",
    "description": "something",
    "icon": null,
    "createdTime": "08-JUL-2016 12:35:42.005 IST",
    "domain": "1"
  },
  {
    "assetDomainId": "2",
    "assetDomainName": "MyDomain1",
    "domainGuid":  "4tcc515a3d2f44aud73d7a2fcd131128538589823767541",
    "description": "something",
    "icon": null,
    "createdTime": "11-JUL-2016 10:42:32.954 IST",
    "domain": "2"
  }
]

3.5. Upload Image for Asset Domain

This API is used to upload an image file for an exisitng asset domain.

Method: POST
URL: https://{domain}/AssetService/assetdomain/uploadImage

Key Value
Header x-api-key,x-user-key (optional)
Request Parameter assetdomain ID

Body

Image File

Response

{
  "id": "2",
  "httpStatus": "205",
  "status": "image uploaded successfully as at this location : /uploadedimageDomain/2.jpeg",
  "path": "/uploadedimageDomain/2.jpeg"
}

3.6. Delete Asset Domain

Asset domain deletion is possible only when there is no project under it.

Method: DELETE
URL: https://{domain}/AssetService/assetdomain/delete?assetDomainId=2

Key Value
Header x-api-key, x-user-key (optional)
Request Parameter assetdomain ID

Response

[
  {
    "httpStatus": "204",
    "id": "2",
    "status": "AssetDomain deleted."
  }
]

4. Projects

Projects exist under each asset domain. Different users can create their projects under the same asset domain name.

4.1. Create Project

This API is used to create projects under a valid asset domain. Mandatory part of the input JSON payload is “assetDomainId” and “projectName”. Users can also provide assetdomain name as value of the key “assetDomainId” if they don’t remember the exact asset domain id.

Method: POST
URL: https://{domain}/AssetService/projects/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
 "projectName": "project_1",
 "assetDomainId": "1",
 "description": "some useful description",
 "icon":"pic1.jpeg",
  "createdBy": "some user"
}

Response

[
  {
    "httpStatus": "201",
    "id":"9",
    "status": "New project created. "
  }
]

4.2. Get Project By ID

If a project is fetched in shared mode then the “sharedProject” field contains value “yes”, otherwise “null”.

Method: GET
URL: https://{domain}/AssetService/projects/getById

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Response

{
  "sharedProject":  null,
  "projectId": "32",
  "projectName": "Ecospace 1B",
  "assetDomainId": "4",
  "createdBy": "user",
  "updatedBy": "user",
  "userId": "17",
  "status": "active",
  "description": "Energy Monitoring of Ecospace 1B",
  "createdTime": "28-NOV-2016 13:16:34.900 UTC",
  "updatedTime": "28-NOV-2016 13:16:34.900 UTC",
  "icon": null,
  "projectGuid":  "776c556d-70f6-45f2-b40f-60003ee239cd",
  "projectType":  null
}

4.3. Get AssetType Count

To get the number of the active assettypes that exist under the given projectid for that user.

Method: GET
URL: https://{domain}/AssetService/projects/getAssetTypeCount

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Response

{
  "count": "3"
}

4.4. Get All Projects

This API lists the project details by the mentioned asset domain ID.

Method: GET
URL: https://{domain}/AssetService/projects/getAll?domainId=1

Key value
Header x-api-key, x-user-key (optional)
RequestParameter domainId

Response

[
  {
    "sharedProject":  null,
    "projectId": "1",
    "projectName": "project_1",
    "assetDomainId": "1",
    "createdBy": "user1",
    "updatedBy": "user1",
    "userId": "2",
    "status": "active",
    "description": "some useful description",
    "createdTime": "06-FEB-2017 12:50:36.971 IST",
    "updatedTime": "22-FEB-2017 17:10:25.448 IST",
    "icon": "projectimage/1.jpeg",
    "projectGuid":  "776c556d-70f6-45f2-b40f-60003ee239cd",
    "projectType":  null
  }
]

4.5. Upload Image for Project

This API is used to upload an image file for an existing projectid.

Method: POST
URL: https://{domain}/AssetService/projects/uploadImage?projectId=1

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Body

Image File

Response

{
  "path": "projectimage/1.jpeg",
  "httpStatus": "205",
  "id": "1",
  "status": "image uploaded successfully as at this location : projectimage/1.jpeg"
}

4.6. Update Project

Except projectid and domainid, all the other fields’ values can be updated.

Method: PUT
URL: https://{domain}/AssetService/projects/update

Key value
Header x-api-key, x-user-key (optional)

Body

{
  "projectId": "1",
  "projectName": "project_1_renamed",
  "updatedBy": "ram",
  "description": "new description"

}

Response

[
  {
    "httpStatus": "205",
    "status": "Project updated. "
  }
]

4.7. Delete Project

A project can only be deleted if there there are no active assettypes under it else the users will get suitable message.

Method: DELETE
URL: https://{domain}/AssetService/projects/delete?projectId=3

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Response

[
  {
    "httpStatus": "204",
    "id": "3",
    "status": "Project deleted."
  }
]

4.8. Adding Geofence to a Project

Users can attach two types of geofences (circular or polygon types) for a valid projectid. Geofence names should be unique for a projectid. If the geofence is of circular type, then the centre point coordinate and radius must be given. If the geofence is of polygon type, then a list of more than three points coordinates must be specified as input JSON. Point coordinates are (x,y) values.

Method: PUT
URL: https://{domain}/AssetService/projects/addGeofence

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId(mandatory),assetTypeId(optional)

Body

{
    "geofence": [{
        "name": "area1",
        "type": "circle",
        "points": [{
            "x": "-40.5",
            "y": "-57.65"
        }],
        "radius": "10"
    }, {
        "name": "area2",
        "type": "polygon",
        "points": [{
            "x": "-40.5",
            "y": "-57.65"
        }, {
            "x": "40.5",
            "y": "-57.65"
        }, {
            "x": "-40.5",
            "y": "57.65"
        }, {
            "x": "40.5",
            "y": "57.65"
        }],
        "radius": ""
    }]
}

Response

[{
    "httpStatus": "205",
    "message": "New project-geofence mapping added.",
    "status": "Project updated."
}, {
    "httpStatus": "205",
    "message": "New project-geofence mapping added.",
    "status": "Project updated."
}]

4.9. Get Assets under Geofence

This API displays the assets of different geofences for that projectid.

Method: GET
URL: https://{domain}/AssetService/projects/getAssetUnderGeofence?projectId=3

Key value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Response

[{
    "geoname": "area2",
    "geotype": "polygon",
    "assets": [{
        "assetid": 2646,
        "assetname": "AT1"
    }]
}]

5. Asset Type

5.1. Create Asset Type

Asset Type can be created under a valid projectId. The payload JSON must contain “projectId” field, the users can optionally provide “assetDomainId” in the payload. Users must mention a unique “assetTypeName” for a given projectId and set “isTemplate” flag as “false”. Users can optionally specify a valid assettypeid at “parentTypeId” field if they want to create the new assettype under that parent. It helps to create the assettype hierarchy.Users can also use project name as value of the key “projectId” and assettype will be created in that case also.

Method: POST
URL: https://{domain}/AssetService/assettype/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
    "assetTypeName": "MyBuilding",
    "projectId": "1",
    "privacy":"public",
    "isTemplate":false,
    "assetTypeProperty": [{
        "assetPropertyName": "Height",
        "assetPropertyType": "USER_DEFINED", 
        "assetPropertyValue":"",
        "assetPropertyUnit":"meter",
        "filter": "",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"double",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "Width",
        "assetPropertyType": "USER_DEFINED", 
        "assetPropertyValue":"",
        "assetPropertyUnit":"meter",
        "filter": "",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"double",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "Area",
        "assetPropertyType": "SCRIPT", 
        "assetPropertyExpression":"",
        "assetPropertyValue":"",
        "filter": "",
        "assetPropertyUnit":"sqmeter",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"double",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "Occupancy",
        "assetPropertyType": "OBSERVATION", 
        "assetPropertyValue":"",
        "assetPropertyUnit":"",
        "filter": "",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"double",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "AggregateOccupancy",
        "assetPropertyType": "AGGREGATE", 
        "assetPropertyExpression":"Sum(Occupancy)",
        "assetPropertyValue":"",
        "filter": "energy>40",
        "assetPropertyUnit":"",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"double",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "link",
        "assetPropertyType": "EXTERNAL", 
        "assetPropertyExpression":"",
        "assetPropertyValue":"",
        "filter": "",
        "assetPropertyUnit":"",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"text",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },   {
        "assetPropertyName": "Zone",
        "assetPropertyType": "LOOKUP", 
        "assetPropertyValue":"North,East,West,South",
        "filter": "",
        "assetPropertyUnit":"",
        "assetPropertyRange":"",
        "propertyDescription":"",
        "dataType":"text",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isMovable": false,
        "isViewable": true,
        "isNotification": true,
        "isDirty": true,
        "isPersist": true,
        "isVirtual": false,
        "isRuleset": false,
        "isUnique":false,
        "uri":""
    },{
            "assetPropertyName": "Meter",
            "assetPropertyType": "COMPOSITE",
            "assetPropertyValue": "2",
            "dataType": "double",
            "assetPropertyUnit": null,
            "assetPropertyExpression": null,
            "assetPropertyRange": null,
            "uri": null,
            "isEditable": true,
            "isDeletable": true,
            "isViewable": true,
            "isMovable": false,
            "isVirtual": false,
            "isPersist": true,
            "isNotification": true,
            "isDirty": true,
            "isRuleset": false,
            "propertyDescription": null,
            "status": "active",
            "filter": null,
            "isUnique":false,
            "mandatory": false
        }],
    "assetTypeRule": [{
        "ruleId": "Rule-1",
        "ruleDescription": "some brief rule descriptions",
        "metaDataList": [{
            "name": "Height",
            "value": "50", 
            "operator": "<", 
            "type": "quantity" 
        }]
    }],
    "typeRelation": [] ,
    "description":"short description of asset type",
   "icon":"assettypeicon.jpg",
    "color":"blue"
}

Response

[
  {
    "id": "2",
    "message": "AssetType [MyBuilding] created under project id 1",
    "httpCode": "201",
    "assetTypeGuid":  "d1860e3b-363f-4e17-b0d8-220af81526fe",
    "status": "Success."
  }
]

5.2. AssetType Template Creation

AssetType Template is created under a valid asset domain. Unlike assetType create JSON,this payload JSON must contain “assetDomainId” field. If it is not mentioned then the users will be asked for the domain ID. If the user provides any valid “projectId”, projectId will be ignored because AssetType Template is always created under domain and AssetType is created under project. Users must mention “assetTypeName” and “isTemplate” as “true” in order to create assetType template. Users can provide domain name as the value of the key “assetDomainId” and assettype template will be created in that case also.

Body

{
    "assetTypeName": "PumpTemplate",
    "assetDomainId": "1",
    "isTemplate": true,
    "assetTypeProperty": [{
        "assetPropertyName": "PowerConsumption",
        "assetPropertyType": "USER_DEFINED",
        "dataType": "double",
        "assetPropertyUnit": "watt",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "",
        "source": null,
        "classification": null,
        "aspect": null,
        "isDeleted": false
    }]
}

Response

[{
    "httpStatus": "201",
    "id": "277",
    "message": "AssetType Template [PumpTemplate] created under assetdomain id 1",
    "assetTypeGuid": "afd803bb-d33c-424c-9a7e-7a84a5e6764e",
    "status": "Success."
}]

5.3. Create Asset Type from Asset Type Template

Using this API, the users can create an assettype from an existing assettype template or assettype to a new projectid. As a result a hierarchy of assettype will be created.

Method: POST
URL: https://{domain}/AssetService/assettype/createAssetTypeFromTypeTemplate?assetTypeid=2&assetTypeName=building_1&projectId=5

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeid, assetTypeName, projectId (all are mandatory)

Response

{
  "id": "4",
  "message": "AssetType [building_1] created under project id 1",
  "httpStatus": "201",
  "assetTypeGuid":  "d1850e3b-723f-5f17-a1d8-560af81536y53",
  "status": "Success."
}

5.4. Upload Image for Asset Type

This API helps to upload an image for a valid assettype or assettype template.

Method: POST
URL: https://{domain}/AssetService/assettype/uploadImage?assetTypeid=242&file=picture.jpg

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeid

Body

Image File

Response

{
  "assetTypeId": "242",
  "httpStatus": "205",
  "location": "typeimage/242.jpeg",
  "status": "image uploaded successfully as at this location : typeimage/242.jpeg"
}

5.5. Upload Asset Type from Excel File

This API will create an assettype by uploading an excel file. The excel file must contain a single entry of assettype information.

Method: POST
URL: https://{domain}/AssetService/assettype/uploadAssetType

Key Value
Header x-api-key, x-user-key (optional)
Request Body Multipart File (only excel file is allowed to upload)

Response

[{
    "httpStatus": "201",
    "id": "280",
    "message": "AssetType [RealPump2] created under project id 1",
    "assetTypeGuid": "afd803bb-d33c-424c-9a7e-7a84a5e6764e",
    "status": "Success."
}]

5.6. Import AssetType and Assets from Excel File

This API will create assettype and its assets by uploading an excel file. The excel file must contain a single entry of assettype and its assets in another tab.

Method: POST
URL: https://{domain}/AssetService/assettype/importTypeAndAssets

Key Value
Header x-api-key, x-user-key (optional)
Request Body Multipart File (only excel file is allowed to upload)

Response

[{
        "httpStatus": "201",
        "id": "69",
        "message": "AssetType created under project id 1",
        "assetTypeGuid": "bb4e49a7-4302-49c8-bdca-a01e5c331d4f",
        "status": "Success."
    },
    {
        "assetGuid": "fb63e781-aaf9-483f-adbf-1f543eeea629",
        "httpStatus": "201",
        "assetName": "Asset2a_rename",
        "id": "75",
        "status": "Asset created."
    },
    {
        "assetGuid": "dc80b73c-fb70-47f4-8d5b-9211cab8c115",
        "httpStatus": "201",
        "assetName": "Asset4a",
        "id": "76",
        "status": "Asset created."
    },
    {
        "assetGuid": "84b4c834-94d9-4aab-a457-5f7d3671ba18",
        "httpStatus": "201",
        "assetName": "Asset1b",
        "id": "77",
        "status": "Asset created."
    },
    {
        "assetGuid": "9379aa09-7cac-4fd0-90f2-edc0409575c2",
        "httpStatus": "201",
        "assetName": "Asset5a",
        "id": "78",
        "status": "Asset created."
    },
    {
        "assetGuid": "10dc27b8-9163-469a-8fdc-95313ccadcd6",
        "httpStatus": "201",
        "assetName": "MM_1a",
        "id": "79",
        "status": "Asset created."
    }
]

5.7. Delete Asset Type

An assettype can only be deleted if there are no existing assets. An assettype can’t be deleted even if there is a single asset in the system.

Method: DELETE
URL: https://{domain}/AssetService/assettype/delete?assetTypeId=8

Key value
Header x-api-key,x-user-key (optional)
RequestParameter assetTypeId

Response

[
  {
    "httpStatus": "204",
    "id": "8",
    "message": "assettype deleted",
    "status": "Success"
  }
]

5.8. Get AssetType Path

This API is used to fetch the hierarchy of assettypes in upwards or downwards fashion.

Method: GET
URL: https://{domain}/AssetService/assettype/getPath?assetTypeId=2631&direction=downward

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeId, direction (=upward or downward)

Response

[
  {
    "assetTypeNames": "atype1,btype",
    "assetTypeIds": "2631,2726"
  }
]

5.9. Add New Assettype Properties

Add new property to an existing assettype or assettype template.

Method: PUT
URL: https://{domain}/AssetService/assettype/addAssetProperty?assetTypeId=2

Key Value
Header x-api-key, x-user-key (optional)

Body

{
    "assetTypeProperty": [{
            "assetPropertyName": "Color",
            "assetPropertyType": "USER_DEFINED",
            "assetPropertyValue": null,
            "dataType": "text",
            "assetPropertyUnit": "",
            "isMandatory": false,
            "isEditable": true,
            "isDeletable": true,
            "isViewable": true,
            "isMovable": false,
            "isVirtual": false,
            "isPersist": false,
            "isNotification": false,
            "isDirty": false,
            "isRuleset": false,
            "filter": null,
            "isUnique": false,
            "isDeleted": false,
            "propertyMetaTypes": [{
                "id": "",
                "propertyMetaTypeId": "5",
                "metaData": "",
                "metaDataName": "",
                "propertyMetaValue": ""
            }, {
                "id": "",
                "propertyMetaTypeId": "6",
                "metaData": "",
                "metaDataName": "",
                "propertyMetaValue": ""
            }]
        }]
}

Response

{ 
   "message": "asset property(s) updated", 
   "status": "success" 
}

5.10. Update AssetType

Assettype meta fields except assetTypeId, projectId & domainId can be updated using this API. AssetProperty names once created can’t be updated. If an attempt is made to update an existing assetproperty name under an assettype, a new assetproperty will be created by that name.

Method: PUT
URL: https://{domain}/AssetService/assettype/update

Key Value
Header x-api-key, x-user-key (optional)

Body

{
    "assetTypeId": "242",
    "assetTypeName": "Tower_1",
    "projectId": "37",
    "assetDomainId": "1",
    "privacy": "private",
    "isTemplate": false,
    "assetTypeProperty": [
      {
        "propertyId": "2491",
        "assetPropertyName": "Height",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": 89.52,
        "dataType": "Double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "30-NOV-2016 09:38:31.754 UTC",
        "propertyLastupdatedTime": "11-JAN-2017 12:37:36.363 UTC",
        "isEditable": false,
        "isDeletable": false,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": false,
        "isNotification": false,
        "isDirty": false,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique":false,
        "mandatory": false
      }
    ],
    "assetTypeRule": [],
    "typeRelation": [],
    "description": null,
    "icon": "typeimage/242.jpeg",
    "color": "green",

    "createdBy": "Administrator",
    "updatedBy": "Ram",
    "status": "active"
  }

Response

[
  {
    "id": "242",
    "message": "Updated AssetType : Tower_1",
    "httpCode": "205",
    "status": "success"
  }
]

5.11. Get AssetType By ID

This API returns the assettype JSON by the assettype ID. The assettypeid is fetched in shared mode, then the “sharedType” field will contain the value “yes”, otherwise it is set to null. If the assettype doesn’t exist under the user, then a proper message is returned to the caller.

Method: GET
URL: https://{domain}/AssetService/assettype/get?assetTypeId=242

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeId

Response

{
  "sharedType":null,
  "assetTypeId": "242",
  "assetTypeName": "Tower_1",
  "projectId": "37",
  "assetDomainId": "1",
  "privacy": "private",
  "isTemplate": false,
  "assetTypeProperty": [
    {
      "propertyId": "2491",
      "assetPropertyName": "Height",
      "assetPropertyType": "USER_DEFINED",
      "assetPropertyValue": "89.52",
      "dataType": "Double",
      "assetPropertyUnit": null,
      "assetPropertyExpression": null,
      "assetPropertyRange": null,
      "uri": null,
      "recordTime": "30-NOV-2016 09:38:31.754 UTC",
      "propertyLastupdatedTime": "13-JAN-2017 07:28:24.982 UTC",
      "isEditable": false,
      "isDeletable": false,
      "isViewable": true,
      "isMovable": false,
      "isVirtual": false,
      "isPersist": false,
      "isNotification": false,
      "isDirty": false,
      "isRuleset": false,
      "propertyDescription": null,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "updatedBy": null,
      "status": "active",
      "filter": null,
      "isUnique":false,
      "mandatory": false
    }
  ],
  "assetTypeRule": [],
  "typeRelation": [],
  "description": null,
  "icon": "typeimage/242.jpeg",
  "color": "green",
  "createdTime": "30-NOV-2016 09:38:31.626 UTC",
  "updatedTime": "13-JAN-2017 07:28:23.968 UTC",
  "createdBy": "Ram",
  "updatedBy": "Ram",
  "status": "active"
}

5.12. Get All Asset Types

This API searches for the assettypes under a user against multiple input parameter combinations. If “minimal” is set to “yes”, then the assettypes without assettype properties, assettype relations are returned. “sharedType” field determines whether the assettype is accessed in shared mode or not. If “count” is present, then only the assettype counts are displayed.

Method: GET
URL: https://{domain}/AssetService/assettype/getall

Key Value
Header x-api-key,x-user-key (optional)
RequestParameter template (optional), projectId(optional), assetDomainId(optional),parentName (optional), parentId (optional), minimal (optional), majorversionnumber (optional),count(optional),assetTypeName (optional), assetTypeId (optional)

Response

[
{
    "sharedType": null,
    "assetTypeId": "67",
    "assetTypeName": "MyBuilding",
    "projectId": "9",
    "assetDomainId": "1",
    "privacy": "public",
    "isTemplate": false,
    "typeRelation": [],
    "description": "short description of asset type",
    "icon": "assettypeicon.jpg",
    "color": "blue",
    "createdTime": "12-JUL-2019 11:56:55.737 IST",
    "updatedTime": "12-JUL-2019 11:56:55.737 IST",
    "createdBy": null,
    "updatedBy": null,
    "status": "active",
    "parentGuid": null,
    "parentType": null,
    "classification": null,
    "aspect": null,
    "assetTypeGuid": "d1860e3b-363f-4e17-b0d8-220af81526fe",
    "parentVersion": "0",
    "majorVersionNumber": "0",
    "parentIdList": null,
    "parentNameList": "",
    "references": null,
    "assetTypeProperty": [
      {
        "propertyId": "104",
        "propertyValueGuid": null,
        "assetPropertyName": "Height",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.331 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.331 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "e34672a9-9a84-44a8-8453-115f8dc9bea2",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "105",
        "propertyValueGuid": null,
        "assetPropertyName": "Width",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.436 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.436 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "0246ea0c-2c4f-48ef-a3a2-926173dd44b3",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "106",
        "propertyValueGuid": null,
        "assetPropertyName": "Area",
        "assetPropertyType": "SCRIPT",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": "sqmeter",
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.440 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.440 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "dda09ebf-728d-4dec-af08-83659501ad49",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "107",
        "propertyValueGuid": null,
        "assetPropertyName": "Occupancy",
        "assetPropertyType": "OBSERVATION",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.444 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.444 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "e1537a9b-9fca-4ce8-8bd8-2afb608ca111",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "108",
        "propertyValueGuid": null,
        "assetPropertyName": "AggregateOccupancy",
        "assetPropertyType": "AGGREGATE",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "Sum(Occupancy)",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.449 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.449 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": "energy>40",
        "isUnique": false,
        "assetPropertyGuid": "6bcfcc1e-890b-4d5f-a006-53fe1c8f97ff",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "109",
        "propertyValueGuid": null,
        "assetPropertyName": "link",
        "assetPropertyType": "EXTERNAL",
        "assetPropertyValue": null,
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.454 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.454 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "337ad069-9cfb-4fcb-866d-5c417957795e",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      },
      {
        "propertyId": "110",
        "propertyValueGuid": null,
        "assetPropertyName": "Zone",
        "assetPropertyType": "LOOKUP",
        "assetPropertyValue": "North,East,West,South",
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": null,
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "12-JUL-2019 11:56:56.458 IST",
        "propertyLastupdatedTime": "12-JUL-2019 11:56:56.458 IST",
        "isMandatory": false,
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": null,
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique": false,
        "assetPropertyGuid": "462dd6f2-131b-4fdb-8923-7e5625c0ab98",
        "source": null,
        "classification": null,
        "aspect": null,
        "majorVersion": "0",
        "isDeleted": false
      }
    ],
    "assetTypeRule": [
      {
        "ruleId": "Rule-1",
        "metaDataList": [
          {
            "rulemappingid": "2",
            "name": "Height",
            "value": "50",
            "operator": "<",
            "type": "quantity"
          }
        ]
      }
    ],
    "minorVersionNumber": "0",
    "parentTypeId": "0",
    "parentTypeName": null
  }
]

5.13. Get All Asset Count by Asset Type ID

This API shows the asset counts by the asset type IDs given a valid projectID.

Method: GET
URL: https://{domain}/AssetService/assettype/getAllAssetCounts?projectId=37

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter projectId

Response

[
  {
    "assettypeId": "242",
    "propertyCount": "3",
    "assetCount": "42",
    "projectId": "37",
    "assettype": "Tower"
  }
]

5.14. Export Asset Types to Excel File

If “withAssets” parameter is set to “yes”, then it will export the assettypes along with assets into an excel file. Otherwise only assettype will be exported into an excel file.

Method: GET
URL: https://{domain}/AssetService/assettype/exportAssetType?assetTypeId=242

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeId

Response

{
  "file": "AssetTemplate( 242 )78138.xls"
}

5.15. Download File - To Get the File

This API helps to download the files that are generated using the export APIs.

Method: GET
URL: https://{domain}/AssetService/assettype/downloadfile?fileName=AssetTemplate78138.xls

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter fileName

Response

File

5.16. Add New Asset Type Relation

This API creates the relation between two existing assettypes. “assetTypeRelationshipType” field is mandatory. Other mandatory fields are “relation”, “destination”, “relationshipstatus”.

Method: PUT
URL: https://{domain}/AssetService/assettype/addNewAssetTypeRelation?assetTypeId=242

Key Value
Header x-api-key, x-user-key (optional)

Body

{
    "typeRelation": [{
        "relation": "is-a2",
        "destination": "410",
        "relationshipstatus": "status_of_relation",
        "uri": "",
        "lcardinality": "0",
        "rcardinality": "0",
        "assetTypeRelationshipType": {
            "relationshipTypeName": "",
            "relationshipTypeDescription": "",
            "relationshipTypeUri": ""
        }
    }]
}

Response

[
  {
    "httpStatus": "205",
    "message": "new type relation added",
    "status": "asset type updated"
  }
]

5.17. Get Aggregate Value of All Numeric Property Types

This API will return the aggregated values of all assettypes given a valid projectid. The aggregate function is to provided - permissible values are “MIN”,”MAX”,”SUM”,”AVG”,”COUNT”.

Method: GET
URL: https://{domain}/AssetService/assettype/getAggregate?projectId=26&function=MIN

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter

Response

[
  {
    "assetProperty": "VMU_Sensor_ID",
    "aggregateFunction": "MIN",
    "propertyId": "2568",
    "aggregatedValue": "35"
  },
  {
    "assetProperty": "Temperature",
    "aggregateFunction": "MIN",
    "propertyId": "2724",
    "aggregatedValue": "48.5"
  }
]

5.18. Create AssetType Property Meta

This API is used to create meta of some property. If some existing propertyMetaId is mentioned as “parentMetaId”, then the meta hierarchy is constructed. This propertyMetaId can be mapped to any assettype’s proeprty.

Method: POST
URL: https://{domain}/AssetService/assettype/propertyMeta

Key Value
Header x-api-key, x-user-key (optional)
RequestBody JSON

Body

{

    "propertyMetaData": "[{\"name\":\"accuracy\",\"type\":\"dataType\",\"unit\":\"unit\"},{\"name\":\"quality\",\"type\":\"dataType\",\"unit\":\"unit\"}]",
    "propertyMetaName": "PressureMeta1",
    "parentMetaId":""
}

Response

[
  {
    "httpStatus": "201",
    "message": "Proeperty meta [PressureMeta1] added successfully with id 33",
    "status": "Created"
  }
]

5.19. Get Property Meta

This API returns the assettype property meta created by giving the property meta name or property meta ID.

Method: GET
URL: https://{domain}/AssetService/assettype/propertyMeta?propertyMeta=PressureMeta1
OR:
URL: https://{domain}/AssetService/assettype//propertyMeta?propertyMeta=33

Key value
Header x-api-key, x-user-key (optional)
RequestParameter property meta ID or property meta name

Response

{
    "propertyMetaId": 33,
    "propertyMetaName": "PressureMeta1",
    "propertyMetaData": "[{\"name\": \"accuracy\", \"type\": \"dataType\", \"unit\": \"unit\"}, {\"name\": \"quality\", \"type\": \"dataType\", \"unit\": \"unit\"}]",
    "parentMetaId": "0",
    "parentMeatIdList": "",
    "parentMeatNameList": "",
    "recordTime": "16-SEP-2019 17:39:56.846 IST",
    "validfrom": "16-SEP-2019 17:39:56.846 IST",
    "validto": "null",
    "metadata": "[{\"unit\": \"\", \"accuracy\": \"\", \"dataType\": \"\"}, {\"unit\": \"\", \"quality\": \"\", \"dataType\": \"\"}]"
}

5.20. Get Property Meta Hierarchy

This API produces the property meta hierarchy for that user.

Method: GET
URL: https://{domain}/AssetService/assettype/propertyMetaHierarchy?propertyMeta=33

Key value
Header x-api-key, x-user-key (optional)
RequestParameter proeprtyMeta id

Response

[{
    "level": "1",
    "metaElements": [{
        "parentmetatype": "33",
        "parentpropertymetatypename": "PressureMeta1",
        "childrenMetaIds": [
            "35"
        ],
        "childrenMetaNames": [
            "InletPressureMeta2"
        ]
    }]
}]

5.21. Create AssetType Template from AssetType Template

Using this API, the users can create an assettype template from an existing assettype template under an assetdomainid. As a result a hierarchy of assettype templates will be created.

Method: POST
URL: https://{domain}/AssetService/assettype/createAssetTypeTemplateFromTemplate?assetTypeid=2&assetTypeName=building_2&assetDomainId=5

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeid, assetTypeName, assetDomainId (all are mandatory)

Response

{
  "id": "4",
  "message": "AssetType Template [building_2] created under assetdomain id 5",
  "httpStatus": "201",
  "assetTypeGuid":  "d1850e3b-723f-5f17-a1d8-560af81536y53",
  "status": "Success."
}

6. Asset

6.1. Create Asset

This API helps to create assets under a valid user. Mandatory fields are “assetTypeId”, “assetName” and assetproperty values.Users can use asset type name as the value of key “assetTypeId” and in that case also asset will be created.

Method: POST
URL: https://{domain}/AssetService/asset/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "assetTypeId": "12",
  "assetName": "my_asset_1",
  "location": "Mumbai",

  "assetProperty": [
    {
      "assetPropertyName": "Height",
      "assetPropertyValue": "50",
       "assetPropertyUnit": null,
      "assetPropertyExpression": "null",
      "assetPropertyRange": null,
      "uri": null,
      "isMandatory": true,
      "isEditable": true,
      "isDeletable": true,
      "isViewable": true,
      "isMovable": false,
      "isVirtual": false,
      "isPersist": true,
      "isNotification": true,
      "isDirty": false,
      "isRuleset": false,
      "propertyDescription": null,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": null,
      "updatedBy": null,
      "status": "active",
      "filter": null,
      "isUnique": false,
      "source": null,
      "classification": null,
      "aspect": null,
      "majorVersion": null,
      "isDeleted": false
    },
    {
      "assetPropertyName": "Width",
      "assetPropertyValue": "40",
       "assetPropertyUnit": null,
      "assetPropertyExpression": "null",
      "assetPropertyRange": null,
      "uri": null,
      "isMandatory": true,
      "isEditable": true,
      "isDeletable": true,
      "isViewable": true,
      "isMovable": false,
      "isVirtual": false,
      "isPersist": true,
      "isNotification": true,
      "isDirty": false,
      "isRuleset": false,
      "propertyDescription": null,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": null,
      "updatedBy": null,
      "status": "active",
      "filter": null,
      "isUnique": false,
      "source": null,
      "classification": null,
      "aspect": null,
      "majorVersion": null,
      "isDeleted": false
    },
    {
      "assetPropertyName": "Area",
      "assetPropertyExpression": "Height * Width",
       "assetPropertyUnit": null,
      "assetPropertyExpression": "null",
      "assetPropertyRange": null,
      "uri": null,
      "isMandatory": true,
      "isEditable": true,
      "isDeletable": true,
      "isViewable": true,
      "isMovable": false,
      "isVirtual": false,
      "isPersist": true,
      "isNotification": true,
      "isDirty": false,
      "isRuleset": false,
      "propertyDescription": null,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": null,
      "updatedBy": null,
      "status": "active",
      "filter": null,
      "isUnique": false,
      "source": null,
      "classification": null,
      "aspect": null,
      "majorVersion": null,
      "isDeleted": false
    },
    {
      "assetPropertyName": "Zone",
      "assetPropertyValue": "East",
       "assetPropertyUnit": null,
      "assetPropertyExpression": "null",
      "assetPropertyRange": null,
      "uri": null,
      "isMandatory": true,
      "isEditable": true,
      "isDeletable": true,
      "isViewable": true,
      "isMovable": false,
      "isVirtual": false,
      "isPersist": true,
      "isNotification": true,
      "isDirty": false,
      "isRuleset": false,
      "propertyDescription": null,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": null,
      "updatedBy": null,
      "status": "active",
      "filter": null,
      "isUnique": false,
      "source": null,
      "classification": null,
      "aspect": null,
      "majorVersion": null,
      "isDeleted": false
    }
  ],

  "sensorIdList": [
    {
      "sensorId": "occupancy-sensor",
      "mapping": [
        {
          "assetProperty": "Occupancy",
          "observedProperty": "occupancy"
        }
      ]
    }
  ],
  "parent": "0",
  "assetDescription": "sample asset json",
  "relation": [
    {
      "relation": "is-a",
      "destination": "7",
      "direction": "7",
      "relationshipEndDate": "31-DEC-2020 23:59:59.000 IST",
      "relationshipStatus": "status_of_relation",
      "isassettype": false,
      "relationshipType": {
        "relationshipTypeName": "name",
        "relationshipTypeDescription": "abcd",
        "relationshipTypeUri": "uri"
      }
    }
  ],
  "assetIcon": "icon.jpeg",
  "assetColor": "default",
  "latitude":"4",
  "longitude":"5",
  "altitude":"3m",
  "assetUpdatedBy": "",
  "assetCreatedBy": "Ram"
}

Response

[{
    "assetGuid": "d3748afa-9410-4c1e-b6f4-a4a5ddd1fc00",
    "httpStatus": "201",
    "id": "80",
    "status": "Asset created of name [my_asset_a1]."
}]

6.2. Update Asset

This API helps to update an existing asset. “assetId”, “assetTypeId”, “projectId”, “assetGuid”, “assetDomainId” fields cannot be updated. This API can’t update the asset property values. To update asset propert values please use “/asset/updateProperty” API. To update asset sensor mappings, asset relations please use the “/asset/addNewAssetSensorMap”, “/asset/addNewAssetRelation” APIs respectively.

Method: PUT
URL: https://{domain}/AssetService/asset/update

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "assetTypeId": "5",
  "assetName": "my_asset_1",
  "assetId": "7",
  "assetProperty": [
    {
      "assetPropertyName": "Height",
      "assetPropertyValue": "50"
    }
  ]
}

Response

[
  {
    "httpStatus": "205",
    "status": "Asset updated successfully."
  }
]

6.3. Update Asset Property

Only the asset property values can be updated using this API.

Method: PUT
URL: https://{domain}/AssetService/asset/updateProperty

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "assetId": "7",
  "assetProperty": [
    {
      "assetPropertyName": "Height",
      "assetPropertyValue": "60"
    }
  ]
}

Response

[
  {
    "httpStatus": "205",
    "status": "Asset updated successfully."
  }
]

6.4. Get Asset by its ID

This API displays the asset JSON by giving a valid asset ID. If the asset is fetched in shared mode, the “sharedAsset” field will be set as “yes”, otherwise “null”.

Method: GET
URL: https://{domain}/AssetService/asset/get?assetId=1

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId

Response

{
  "sharedAsset":  null,
  "assetName":"a1",
  "assetTypeId": "1",
  "assetTypeName": "Building",
  "privacy": "public",
  "isTemplate": false,
  "icon": "default",
  "location":"Kolkata",
  "latitude":"22",
  "longitude":"88",
  "altitude":"1",
  "color": "default",
  "value":  {},
  "references":  null,
  "createdTime": "08-JUL-2016 14:10:31.195 IST",
  "createdBy": "sayan",
  "status": "active",
  "validFrom": "2016-07-08 14:10:31.195",
  "validTo": "null",
  "assetId": "4",
  "assetName": "xray1",
  "assetGuid": "f42c1ff1a65643cc9c45caeec9db8baa875633312349309",
  "location": "mumbai",

  "sensorIdList": [
    {
      "sensorId": "Occ-s2",
      "mapping": [
        {
          "assetProperty": "Occupancy",
          "observedProperty": "occupancy"
        }
      ]
    }
  ],
  "parent": "0",
  "parentId": "0",
  "childAssets": [
    "xray2"
  ],
  "assetProperty": [
    {
      "propertyId":  "118",
      "assetPropertyType": "USER_DEFINED",
      "assetPropertyName": "Height",
      "assetPropertyUnit": "sqmeter",
      "assetPropertyValue": "10.0",
      "assetPropertyExpression": "null",
      "dataType": "double",
      "recordTime": "2016-07-08 14:10:31.195",
      "propertyLastupdatedTime": "08-JUL-2016 14:10:31.195 IST",
      "isRuleset": false,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "status": "active",
      "validFrom": "2016-07-08 14:10:31.195",
      "propertyId": 1,
      "notification": true,
      "mandatory": false,
      "virtual": false,
      "deletable": true,
      "viewable": true,
      "movable": false,
      "persist": true,
      "dirty": true,
      "ruleset": false,
      "isUnique":false,
      "editable": true,
      "assetPropertyGuid": "8d6aa5b6-6151-4c82-a330-0a55b455ad7d",
    "source": null,
    "classification": null,
    "aspect": null,
    "majorVersion": null,
    "isDeleted": false
    },
    {
      "propertyId":  "119",
      "assetPropertyType": "USER_DEFINED",
      "assetPropertyName": "Width",
      "assetPropertyUnit": "sqmeter",
      "assetPropertyValue": "25.0",
      "assetPropertyExpression": "null",
      "dataType": "double",
      "recordTime": "2016-07-08 14:10:31.195",
      "propertyLastupdatedTime": "08-JUL-2016 14:10:31.195 IST",
      "isRuleset": false,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "status": "active",
      "validFrom": "2016-07-08 14:10:31.195",
      "propertyId": 2,
      "notification": true,
      "mandatory": false,
      "virtual": false,
      "deletable": true,
      "viewable": true,
      "movable": false,
      "persist": true,
      "dirty": true,
      "ruleset": false,
      "isUnique":false,
      "editable": true,
      "assetPropertyGuid": "8e6aa5b6-6151-4c82-a330-0a55b455ad5y",
    "source": null,
    "classification": null,
    "aspect": null,
    "majorVersion": null,
    "isDeleted": false
    },
    {
      "propertyId":  "120",
      "assetPropertyType": "SCRIPT",
      "assetPropertyName": "Area",
      "assetPropertyValue": "250.0",
      "assetPropertyExpression": "Height*Width",
      "dataType": "double",
      "recordTime": "2016-07-08 14:10:31.195",
      "propertyLastupdatedTime": "08-JUL-2016 14:10:31.195 IST",
      "isRuleset": false,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "status": "active",
      "validFrom": "2016-07-08 14:10:31.195",
      "propertyId": 3,
      "notification": true,
      "mandatory": false,
      "virtual": false,
      "deletable": true,
      "viewable": true,
      "movable": false,
      "persist": true,
      "dirty": true,
      "ruleset": false,
      "isUnique":false,
      "editable": true,
      "assetPropertyGuid": "4ryaa5b6-6151-4c82-a330-0a55b455art8",
    "source": null,
    "classification": null,
    "aspect": null,
    "majorVersion": null,
    "isDeleted": false
    },
    {
      "propertyId":  "121",
      "assetPropertyType": "OBSERVATION",
      "assetPropertyName": "Occupancy",
      "assetPropertyExpression": "null",
      "dataType": "double",
      "recordTime": "2016-07-08 14:10:31.195",
      "propertyLastupdatedTime": "08-JUL-2016 14:10:31.195 IST",
      "isRuleset": false,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "status": "active",
      "validFrom": "2016-07-08 14:10:31.195",
      "propertyId": 4,
      "notification": true,
      "mandatory": false,
      "virtual": false,
      "deletable": true,
      "viewable": true,
      "movable": false,
      "persist": true,
      "dirty": true,
      "ruleset": false,
      "isUnique":false,
      "editable": true,
      "assetPropertyGuid": "5t9aa5b6-6151-4c82-a330-0a55b455a4tg",
    "source": null,
    "classification": null,
    "aspect": null,
    "majorVersion": null,
    "isDeleted": false
    },
    {
      "propertyId":  "122",
      "assetPropertyType": "LOOKUP",
      "assetPropertyName": "Zone",
      "assetPropertyValue": "East",
      "assetPropertyExpression": "null",
      "dataType": "text",
      "recordTime": "2016-07-08 14:10:31.195",
      "propertyLastupdatedTime": "08-JUL-2016 14:10:31.195 IST",
      "isRuleset": false,
      "propertyIcon": "default",
      "propertyColor": "default",
      "createdBy": "Administrator",
      "status": "active",
      "validFrom": "2016-07-08 14:10:31.195",
      "propertyId": 5,
      "notification": true,
      "mandatory": false,
      "virtual": false,
      "deletable": true,
      "viewable": true,
      "movable": false,
      "persist": true,
      "dirty": true,
      "ruleset": false,
      "isUnique":false,
      "editable": true,
      "assetPropertyGuid": "4rtaa5b6-6151-4c82-a330-0a55b455a5yu",
    "source": null,
    "classification": null,
    "aspect": null,
    "majorVersion": null,
    "isDeleted": false
    }
  ],
  "relation": [
    {
      "relationid": "2",
      "assetid": "4",
      "relation": "Is-a",
      "destination": "5",
      "direction": "4",
      "relationshipType": {
        "relationshiptypeid": "2",
        "relationshipTypeName": "is a relation",
        "relationshipTypeDescription": "sadfsdf",
        "relationshipTypeUri": "eeee"
      },
      "validfrom": "2016-07-08 14:10:32.111",
      "validto": "null",
      "validDays": "31-DEC-2010 23:59:59 IST",
      "relationshipEndDate": null,
      "relationshipStatus": "act",
      "lastUpdatedTime": "08-JUL-2016 14:10:32.111 IST",
      "isassettype": false
    }
  ],
  "assetDescription": "xray machine 1",
  "assetIcon": "default",
  "assetColor": "default",
  "latitude":"3",
  "longitude":"4".
  "altitude":"3m",
  "geohash":"2eryhud",
  "template": false,
  "versionNumber":"0"
}

6.5. Download Asset Templates in Excel File Format

This API generates a blank excel template for the given assettype ID. Users need to fill up the excel file in order to upload bulk assets in one go.

Method: GET
URL: https://{domain}/AssetService/asset/downloadAssetTemplate?assetTypeId=264

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeId

Response

{
  "file": "AssetTemplate_264_1511860176472.xls"
}

6.6. Download File - To Get the File

This API downloads the actual file generated by the other export APIs, download asset templates API.

Method: GET
URL: https://{domain}/AssetService/asset/downloadfile?fileName=AssetTemplate_264_1511860176472.xls

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter fileName

Response

File

6.7. Export All Assets based on an Assettype ID into an Excel File

This API exports all the assets by giving a valid assettype ID into an excel file ( if “fileType” parameter is set blank or “excel”). If “fileType” parameter is set to “csv”, then assets are exported to csv file but semcolon as column seoarator.

Method: GET
URL: https://{domain}/AssetService/asset/exportAssets?assetTypeId=264

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetTypeId, fileType(optional with values “excel”, “csv”)

Response

{
  "file": "Asset_264_1511860178594.xls",
  "httpStatus": "302"
}

This API executes the external URL specified at EXTERNAL type asset property and the asset is updated with the result of the URL.
If the external URL contains ‘https’, then the corresponding certificate has to be installed at the server’s keystore file at jvm.

Method: GET
URL: https://{domain}/AssetService/asset/getByIdWithExternal?assetId=940

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId, type (optional with values - empty, EXTERNAL, LINK)

Response

[
  {
    "assetId": "940",
    "assetName": "A1",
    "assetGuid": "9cde8c0e93bc42a1b3cb0175612ae65a7770246387481352",
    "assetTypeId": "301",
    "assetTypeName": "Q",
    "privacy": "public",
    "typeRelation": [],
    "status": "active",
    "location": "Mumbai",

    "sensorIdList": [],
    "parent": "939",
    "parentName": "A1",
    "childAssets": [],
    "childAssetWithId": [],
    "assetProperty": [
      {
        "propertyId": "2736",
        "assetPropertyName": "Zone",
        "assetPropertyType": "LOOKUP",
        "assetPropertyValue": "West",
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "isUnique":false,
        "mandatory": false
      },
      {
        "propertyId": "2733",
        "assetPropertyName": "Occupancy",
        "assetPropertyType": "OBSERVATION",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isUnique":false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2732",
        "assetPropertyName": "Area",
        "assetPropertyType": "SCRIPT",
        "assetPropertyValue": "1500.0",
        "dataType": "double",
        "assetPropertyUnit": "sqmeter",
        "assetPropertyExpression": "Height * Width * 0.5",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isUnique":false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2735",
        "assetPropertyName": "link",
        "assetPropertyType": "EXTERNAL",
        "assetPropertyValue": "Something went wrong during execution of the url,please check url & http-headers given in correct format",
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService1.0/asset/getAllDetails",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isUnique":false,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": "Content-Type:Application/Json,x-api-key:sayan",
        "mandatory": false
      },
      {
        "propertyId": "2734",
        "assetPropertyName": "AggregateOccupancy",
        "assetPropertyType": "AGGREGATE",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "Sum(Height)",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isUnique":false,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": "energy>40",
        "mandatory": false
      },
      {
        "propertyId": "2730",
        "assetPropertyName": "Height",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": "60",
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isUnique":false,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2731",
        "assetPropertyName": "Width",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": "50",
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:33:16.075 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:33:16.075 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isUnique":false,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      }
    ],
    "relation": [],
    "assetDescription": "sample asset json",
    "assetIcon": "asseticon.jpeg",
    "assetColor": "red",
    "assetCreatedTime": "16-JAN-2017 10:33:16.075 UTC",
    "assetUpdatedTime": "16-JAN-2017 10:33:16.075 UTC",
    "assetCreatedBy": null,
    "assetUpdatedBy": null,
    "filtertag": null,
    "versionNumber":"0"
  }
]

6.9. Get Asset with Aggregate Data

This API executes the expression provided as AGGREGATE property type. SUM,MIN,MAX,AVG,COUNT as aggregate function are supported. The expression is executed and the corresponding asset property is updated with the result.

Method: GET
URL: https://{domain}/AssetService/asset/getByIdWithAggregate?assetId=939&includeCurrentNode=YES&assetTypeCheck=NO&includeRelation=NO

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId, includeCurrentNode, assetTypeCheck, includeRelation

Response

[
  {
    "assetId": "939",
    "assetName": "A1",
    "assetGuid": "871eeb00d9164489a5c2d7f25a3f6c207770201438333649",
    "assetTypeId": "301",
    "assetTypeName": "Q",
    "privacy": "public",
    "typeRelation": [],
    "status": "active",
    "location": "Mumbai",
    "sensorIdList": [],
    "parent": "0",
    "parentName": "ROOT",
    "childAssets": [
      "A1"
    ],
    "childAssetWithId": [
      {
        "assetId": "940",
        "assetName": "A1"
      }
    ],
    "assetProperty": [
      {
        "propertyId": "2736",
        "assetPropertyName": "Zone",
        "assetPropertyType": "LOOKUP",
        "assetPropertyValue": "East",
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isUnique":false,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2733",
        "assetPropertyName": "Occupancy",
        "assetPropertyType": "OBSERVATION",
        "assetPropertyValue": null,
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isUnique":false,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2732",
        "assetPropertyName": "Area",
        "assetPropertyType": "SCRIPT",
        "assetPropertyValue": "2000.0",
        "dataType": "double",
        "assetPropertyUnit": "sqmeter",
        "assetPropertyExpression": "Height * Width",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isUnique":false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2735",
        "assetPropertyName": "link",
        "assetPropertyType": "EXTERNAL",
        "assetPropertyValue": null,
        "dataType": "text",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService1.0/asset/getAllDetails",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isUnique":false,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": "Content-Type:Application/Json,x-api-key:sayan",
        "mandatory": false
      },
      {
        "propertyId": "2734",
        "assetPropertyName": "AggregateOccupancy",
        "assetPropertyType": "AGGREGATE",
        "assetPropertyValue": "110.0",
        "dataType": "double",
        "assetPropertyUnit": null,
        "assetPropertyExpression": "Sum(Height)",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isVirtual": false,
        "isUnique":false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": "energy>40",
        "mandatory": false
      },
      {
        "propertyId": "2730",
        "assetPropertyName": "Height",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": "50",
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isUnique":false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      },
      {
        "propertyId": "2731",
        "assetPropertyName": "Width",
        "assetPropertyType": "USER_DEFINED",
        "assetPropertyValue": "40",
        "dataType": "double",
        "assetPropertyUnit": "meter",
        "assetPropertyExpression": "null",
        "assetPropertyRange": null,
        "uri": null,
        "recordTime": "16-JAN-2017 10:32:34.559 UTC",
        "propertyLastupdatedTime": "16-JAN-2017 10:32:34.559 UTC",
        "isEditable": true,
        "isDeletable": true,
        "isViewable": true,
        "isMovable": false,
        "isUnique":false,
        "isVirtual": false,
        "isPersist": true,
        "isNotification": true,
        "isDirty": true,
        "isRuleset": false,
        "propertyDescription": null,
        "propertyIcon": "default",
        "propertyColor": "default",
        "createdBy": "Administrator",
        "updatedBy": null,
        "status": "active",
        "filter": null,
        "mandatory": false
      }
    ],
    "relation": [],
    "assetDescription": "sample asset json",
    "assetIcon": "asseticon.jpeg",
    "assetColor": "red",
    "assetCreatedTime": "16-JAN-2017 10:32:34.559 UTC",
    "assetUpdatedTime": "16-JAN-2017 10:32:34.559 UTC",
    "assetCreatedBy": null,
    "assetUpdatedBy": null,
    "filtertag": null,
    "versionNumber":"0"
  }
]

6.10. Get Asset Property History

This API helps the user to get the history of a particular asset property of an asset. Assetid, propertyname, starttime are mandatory fields. The user has to provide single assetid, single propertyname and single starttime. Starttime, endtime basically covers a time range. If the user only provides a starttime then it will fetch records from that time to the current time. If the user provides the starttime and end time, then the records from that time span are returned appended by the current record at the beginning of the result. The following time format is supported DD-MMM-YYYY HH:MM:SS.SSS Z or DD-MMM-YYYY HH:MM:SS Z

There is a filed called ‘function’ and it is optional. If the user chooses MAX, then it will show the record which is maximum from the result set. This will only work if the datatype of the propertyname is of numeric type.

If the user chooses “function” values, then the user will get the result based on the function name but it must work on numeric type of data set.

Method: GET
URL: https://{domain}/AssetService/asset/getPropertyHistory?assetId=939&propertyId=Height&starttime=15-JAN-2017 IST

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId,p ropertyName, starttime, endtime(optional),function(optional with values “MIN”, “MAX”, “SUM”, “AVG”, “COUNT”, “VARIANCE”)

Response

[
  {
    "updatedBy": null,
    "recordTime": "03-MAY-2017 14:29:59.547 IST",
    "createdBy": null,
    "httpStatus": "302",
    "propertyValue": "7",
    "validFrom": "03-MAY-2017 14:32:27.931 IST",
    "propertyId": "323",
    "validTo": "null"
  },
  {
    "updatedBy": null,
    "recordTime": "03-MAY-2017 14:29:59.547 IST",
    "createdBy": null,
    "httpStatus": "302",
    "propertyValue": "66",
    "validFrom": "03-MAY-2017 14:32:02.179 IST",
    "propertyId": "323",
    "validTo": "03-MAY-2017 14:32:27.933 IST"
  },
  {
    "updatedBy": null,
    "recordTime": "03-MAY-2017 14:29:59.547 IST",
    "createdBy": null,
    "httpStatus": "302",
    "propertyValue": "66",
    "validFrom": "03-MAY-2017 14:31:30.532 IST",
    "propertyId": "323",
    "validTo": "03-MAY-2017 14:32:02.179 IST"
  },
  {
    "updatedBy": null,
    "recordTime": "03-MAY-2017 14:29:59.547 IST",
    "createdBy": null,
    "httpStatus": "302",
    "propertyValue": "66",
    "validFrom": "03-MAY-2017 14:29:59.547 IST",
    "propertyId": "323",
    "validTo": "03-MAY-2017 14:31:30.532 IST"
  }
]

6.11. Bulk Upload Asset using Excel or CSV File Format

This API helps to create assets in bulk by uploading a excel or csv file. By default, it supports excel file support. To fill up the excel file, the users can get the format from downloadTemplate API.Semicolon is used as column separator in case of csv file. To upload csv file, ‘type’ parameter needs to be explicitly filled up.

Method: POST
URL: https://{domain}/AssetService/asset/bulkupload

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter type (optional with values “excel”, “csv” - default is “excel”)

Response

[{
        "assetGuid": "118dc5d9-99b8-468a-b723-7e596b45dde2",
        "httpStatus": "201",
        "assetName": "sa1",
        "id": "506",
        "status": "Asset created of name [sa1]."
    },
    {
        "assetGuid": "39d3d495-8127-4552-abe6-a2522e14830c",
        "httpStatus": "201",
        "assetName": "sa2",
        "id": "507",
        "status": "Asset created of name [sa2]."
    },
    {
        "assetGuid": "90b19c32-1a2c-4ea4-a6b8-2df596d5358e",
        "httpStatus": "201",
        "assetName": "sa3",
        "id": "508",
        "status": "Asset created of name [sa3]."
    }
]

6.12. Delete Asset

This API helps to delete an existing asset. If the ‘recursive’ flag is set to ‘true’, then all the child assets from the given assetid will also get deleted.

Method: DELETE
URL: https://{domain}/AssetService/asset/delete?assetId=931

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId, recursive (optional with value “true” - default is not recursive delete)

Response for Asset Delete

[
  {
    "assetId": "931",
    "httpStatus": "204",
    "message": "asset deleted successfully",
    "status": "Success"
  }
]

Response for Recursive Delete Operation

[
  {
    "httpStatus": "204",
    "message": "[35, 36, 37, 39, 38]",
    "status": "Resursively childs deleted for this asset id 35"
  }
]

6.13. Get List of an Asset’s Children

This API returns the hierarchy of assets starting from the given assetid for that user. The output is level wise.

Method: GET
URL: https://{domain}/AssetService/asset/ getPathToEnd?assetId=349

Key Value
Header x-api-key,x-user-key (optional)
RequestParameter assetId

Response

[{
    "level": "1",
    "elements": [{
        "parentId": "1",
        "parentName": "my_asset_1",
        "childrenIds": [
            "2",
            "5"
        ],
        "childrenNames": [
            "my_asset_2",
            "my_asset_3"
        ]
    }]
}]

6.14. Get Asset Path To Root

This API produces the path from the given assetid to ROOT. i.e. in upward direction.

Method: GET
URL: https://{domain}/AssetService/asset/getPathToRoot?assetId=349

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId

Response

[
  {
    "path": "[USA, ROOT]",
    "httpStatus": "302",
    "id": "[349, 0]",
    "assetTypeIds": "[236, Nill]"
  }
]

6.15. Get All Assets Metadata for this User

This API helps to return the assets based on the parameters. The asset JSON is minimal i.e. the asset property, relation, sensor mapping, type relation information are not present at the asset JSON. pageNo concept is obsolete here, it will be removed at next release.

Method: GET
URL: https://{domain}/AssetService/asset/getall?projectId=26

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter projectId (mandatory), pageNo,parent

Response

[
  {
    "assetTypeName": "Building",
    "assetTypeId": "236",
    "assetId": "349",
    "assetName": "USA",
    "parent": "0",
    "parentName": "ROOT",
    "hasChild": "false",
    "childCount": null,
    "relation": [],
    "typeRelation": []
  },
  {
    "assetTypeName": "Building",
    "assetTypeId": "236",
    "assetId": "350",
    "assetName": "California",
    "parent": "349",
    "parentName": "USA",
    "hasChild": "false",
    "childCount": null,
    "relation": [],
    "typeRelation": []
  }
]

6.16. Add New Asset Relation

Custom relations between two existing assetids can be created using this API. “Relation”, “destination”, “direction relationshipType” are mandatory.

Method: PUT
URL: https://{domain}/AssetService/asset/addNewAssetRelation?assetId=930

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId

Body


{
    "relation": [{
        "relation": "is-a",
        "destination": "928",
        "direction": "928",
        "relationshipEndDate": "31-DEC-2020 23:59:59.000 IST",
        "relationshipStatus": "status_of_relation",
        "isassettype": false,
        "relationshipType": {
            "relationshipTypeName": "name",
            "relationshipTypeDescription": "abcd",
            "relationshipTypeUri": "uri"
        }
    }]
}

Note: If the user wants to add multiple relation for a given asset, then the new relation JSON under “relation” array has to be added using comma.

Response

[
  {
    "httpStatus": "205",
    "message": "new relation added",
    "status": "asset updated"
  }
]

6.17. Add New Asset Sensor Mappings

External sensors can be mapped with asset OBSERVED properties using this API.

Method: PUT
URL: https://{domain}/AssetService/asset/addNewAssetSensorMap?assetId=930

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId

Body

{
    "sensorIdList": [{
        "sensorId": "occupancy-sensor",
        "mapping": [{
            "assetProperty": "Occupancy",
            "observedProperty": "occupancy"
        }]
    }]
}

Response

[ { "httpStatus": "205", "message": "New asset-sensor mapping added.", "status": "Asset updated." } ]

6.18. Upload Image for an Asset

Upload image for an existing asset ID.

Method: POST
URL: https://{domain}/AssetService/asset/uploadImage?assetId=939

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId, image file(request body)

Body

Image File

Response

{
    "assetId": "939",
    "httpStatus": "205",
    "location": "assetimage/939.jpg",
    "status": "Image uploaded successfully as at this location : assetimage/939.jpg"
}

6.19. Search for Assets based on Parameters

This API helps the users to search for assets based on multiple parameters. The parameters are not mandatory and if searched without any parameters, all the assets created by the user will be returned to the user. To query using the starttime and endtime, the users can only give the starttime or starttime and endtime combination but the starttime should be less than endtime value.If the future date is input as starttime, then only the current record will be returned.

Method: GET
URL: https://{domain}/AssetService/asset/query?property=Height=52,Zone=West

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter All parameters are optional, they are assetTypeId, assetType, asset, assetId, assetDomainId, projectId, location, startTime, endTime, property, sensorId, parent, createdBy, updatedBy, relation, relationshiptype, relationStartTime, relationEndTime, count(with value ‘COUNT’), pageNo, pageSize

Response

[{
        "sharedAsset": null,
        "assetId": "2",
        "assetName": "my_asset_2",
        "isAsset": "false",
        "isMachine": "false",
        "versionNumber": "0",
        "assetGuid": "e7b0c1a3-6aec-4d06-968f-99ad566c596a",
        "businessKey": null,
        "assetTypeId": "3",
        "assetTypeMajorVersion": "0",
        "assetTypeMinorVersion": "0",
        "projectId": "1",
        "location": "Mumbai",
        "latitude": "19.076",
        "longitude": "72.8777",
        "altitude": "14",
        "value": {},
        "assetTypeName": "Building",
        "typeRelation": [],
        "status": "active",
        "parentName": "my_asset_1",
        "majorVersionNumber": null,
        "references": null,
        "geohash": "te7ud2evv2pu",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "assetRuleList": [],
        "sensorIdList": [],
        "parent": "1",
        "childAssets": [],
        "childAssetWithId": [],
        "assetProperty": [{
                "propertyId": "15",
                "propertyValueGuid": "b45bc1d4-744d-4cb1-b03f-0c4889b0eb97",
                "assetPropertyName": "Height",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "52",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "16",
                "propertyValueGuid": "bc1fb6dc-f882-4674-a3c6-21a14ee4de30",
                "assetPropertyName": "Width",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "1",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "17",
                "propertyValueGuid": "6c7628b0-e55f-41f3-8244-72d9ff5c6425",
                "assetPropertyName": "Area",
                "assetPropertyType": "SCRIPT",
                "assetPropertyValue": "52.0",
                "dataType": "double",
                "assetPropertyUnit": "sqmeter",
                "assetPropertyExpression": "Height * Width",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "18",
                "propertyValueGuid": "56c0647b-d73d-48f3-8d10-05ad2b4ae066",
                "assetPropertyName": "Occupancy",
                "assetPropertyType": "OBSERVATION",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": true,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "19",
                "propertyValueGuid": "a794d996-54d4-48ca-9244-496d0de3c279",
                "assetPropertyName": "AggregateOccupancy",
                "assetPropertyType": "AGGREGATE",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "SUM(Occupancy)",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "20",
                "propertyValueGuid": "190af75e-c121-4802-a953-c64084f41fdf",
                "assetPropertyName": "link",
                "assetPropertyType": "EXTERNAL",
                "assetPropertyValue": null,
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService/asset/get?assetId=5",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "21",
                "propertyValueGuid": "9dcc1192-42bb-4522-b9b1-df865cd15d16",
                "assetPropertyName": "Zone",
                "assetPropertyType": "LOOKUP",
                "assetPropertyValue": "West",
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 13:34:46.472 IST",
                "propertyLastupdatedTime": "18-JUL-2019 13:34:46.472 IST",
                "isMandatory": false,
                "isEditable": false,
                "isDeletable": false,
                "isViewable": false,
                "isMovable": false,
                "isVirtual": false,
                "isPersist": false,
                "isNotification": false,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            }
        ],
        "relation": [],
        "assetDescription": "sample asset json",
        "assetIcon": "asseticon.jpeg",
        "assetColor": "default",
        "assetCreatedTime": "18-JUL-2019 13:34:46.472 IST",
        "assetUpdatedTime": "18-JUL-2019 13:34:46.472 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": "",
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false"
    },
    {
        "sharedAsset": null,
        "assetId": "5",
        "assetName": "my_asset_3",
        "isAsset": "false",
        "isMachine": "false",
        "versionNumber": "0",
        "assetGuid": "6e81efa6f83c448eb0bdd6d0aae22cb79848293357751",
        "businessKey": null,
        "assetTypeId": "3",
        "assetTypeMajorVersion": "0",
        "assetTypeMinorVersion": "0",
        "projectId": "1",
        "location": "Mumbai",
        "latitude": "19.076",
        "longitude": "72.8777",
        "altitude": "14",
        "value": {},
        "assetTypeName": "Building",
        "typeRelation": [],
        "status": "active",
        "parentName": "my_asset_1",
        "majorVersionNumber": null,
        "references": null,
        "geohash": "te7ud2evv2pu",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "assetRuleList": [],
        "sensorIdList": [],
        "parent": "1",
        "childAssets": [],
        "childAssetWithId": [],
        "assetProperty": [{
                "propertyId": "15",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "Height",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "52",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "16",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "Width",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "1",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "17",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "Area",
                "assetPropertyType": "SCRIPT",
                "assetPropertyValue": "52.0",
                "dataType": "double",
                "assetPropertyUnit": "sqmeter",
                "assetPropertyExpression": "Height * Width",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "18",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "Occupancy",
                "assetPropertyType": "OBSERVATION",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "19",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "AggregateOccupancy",
                "assetPropertyType": "AGGREGATE",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "SUM(Occupancy)",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "20",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "link",
                "assetPropertyType": "EXTERNAL",
                "assetPropertyValue": null,
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService/asset/get?assetId=5",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "21",
                "propertyValueGuid": "f0b52505-af08-42dd-9e68-7defa87b114d",
                "assetPropertyName": "Zone",
                "assetPropertyType": "LOOKUP",
                "assetPropertyValue": "West",
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 14:40:06.170 IST",
                "propertyLastupdatedTime": "18-JUL-2019 14:40:06.170 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            }
        ],
        "relation": [],
        "assetDescription": "sample asset json",
        "assetIcon": "asseticon.jpeg",
        "assetColor": "default",
        "assetCreatedTime": "18-JUL-2019 14:40:06.170 IST",
        "assetUpdatedTime": "18-JUL-2019 14:40:06.170 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": "",
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false"
    },
    {
        "sharedAsset": null,
        "assetId": "9",
        "assetName": "s3",
        "isAsset": "false",
        "isMachine": "false",
        "versionNumber": "0",
        "assetGuid": "6f2e9f7ec1734ee1bf0ed6d0c27e36ce20332617590573",
        "businessKey": null,
        "assetTypeId": "3",
        "assetTypeMajorVersion": "0",
        "assetTypeMinorVersion": "0",
        "projectId": "1",
        "location": "Mumbai",
        "latitude": "19.076",
        "longitude": "72.8777",
        "altitude": "14",
        "value": {},
        "assetTypeName": "Building",
        "typeRelation": [],
        "status": "active",
        "parentName": "s1",
        "majorVersionNumber": null,
        "references": null,
        "geohash": "te7ud2evv2pu",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "assetRuleList": [],
        "sensorIdList": [],
        "parent": "8",
        "childAssets": [],
        "childAssetWithId": [],
        "assetProperty": [{
                "propertyId": "15",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Height",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "52",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "16",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Width",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "1",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "17",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Area",
                "assetPropertyType": "SCRIPT",
                "assetPropertyValue": "52.0",
                "dataType": "double",
                "assetPropertyUnit": "sqmeter",
                "assetPropertyExpression": "Height * Width",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "18",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Occupancy",
                "assetPropertyType": "OBSERVATION",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "19",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "AggregateOccupancy",
                "assetPropertyType": "AGGREGATE",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "SUM(Occupancy)",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "20",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "link",
                "assetPropertyType": "EXTERNAL",
                "assetPropertyValue": null,
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService/asset/get?assetId=5",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "21",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Zone",
                "assetPropertyType": "LOOKUP",
                "assetPropertyValue": "West",
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.623 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.623 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            }
        ],
        "relation": [],
        "assetDescription": "sample asset json",
        "assetIcon": "asseticon.jpeg",
        "assetColor": "default",
        "assetCreatedTime": "18-JUL-2019 17:34:50.623 IST",
        "assetUpdatedTime": "18-JUL-2019 17:34:50.623 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": "",
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false"
    },
    {
        "sharedAsset": null,
        "assetId": "12",
        "assetName": "s2",
        "isAsset": "false",
        "isMachine": "false",
        "versionNumber": "0",
        "assetGuid": "60b161c1ccf14fc79709a08f32076f6d20332686292784",
        "businessKey": null,
        "assetTypeId": "3",
        "assetTypeMajorVersion": "0",
        "assetTypeMinorVersion": "0",
        "projectId": "1",
        "location": "Mumbai",
        "latitude": "19.076",
        "longitude": "72.8777",
        "altitude": "14",
        "value": {},
        "assetTypeName": "Building",
        "typeRelation": [],
        "status": "active",
        "parentName": "s1",
        "majorVersionNumber": null,
        "references": null,
        "geohash": "te7ud2evv2pu",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "assetRuleList": [],
        "sensorIdList": [],
        "parent": "8",
        "childAssets": [],
        "childAssetWithId": [],
        "assetProperty": [{
                "propertyId": "15",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Height",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "52",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "16",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Width",
                "assetPropertyType": "USER_DEFINED",
                "assetPropertyValue": "1",
                "dataType": "double",
                "assetPropertyUnit": "meter",
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "17",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Area",
                "assetPropertyType": "SCRIPT",
                "assetPropertyValue": "52.0",
                "dataType": "double",
                "assetPropertyUnit": "sqmeter",
                "assetPropertyExpression": "Height * Width",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "18",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Occupancy",
                "assetPropertyType": "OBSERVATION",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "19",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "AggregateOccupancy",
                "assetPropertyType": "AGGREGATE",
                "assetPropertyValue": null,
                "dataType": "double",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "SUM(Occupancy)",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "20",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "link",
                "assetPropertyType": "EXTERNAL",
                "assetPropertyValue": null,
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "http://assetservice.tcupiot.com/AssetService/asset/get?assetId=5",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            },
            {
                "propertyId": "21",
                "propertyValueGuid": "6931ae7e-1e4d-40be-a020-a3eba4209bf1",
                "assetPropertyName": "Zone",
                "assetPropertyType": "LOOKUP",
                "assetPropertyValue": "West",
                "dataType": "text",
                "assetPropertyUnit": null,
                "assetPropertyExpression": "null",
                "assetPropertyRange": null,
                "uri": null,
                "recordTime": "18-JUL-2019 17:34:50.690 IST",
                "propertyLastupdatedTime": "18-JUL-2019 17:34:50.690 IST",
                "isMandatory": false,
                "isEditable": true,
                "isDeletable": true,
                "isViewable": true,
                "isMovable": true,
                "isVirtual": false,
                "isPersist": true,
                "isNotification": true,
                "isDirty": false,
                "isRuleset": false,
                "propertyDescription": null,
                "propertyIcon": "default",
                "propertyColor": "default",
                "createdBy": null,
                "updatedBy": null,
                "status": "active",
                "filter": null,
                "isUnique": false,
                "assetPropertyGuid": "5ca0fcb4-28fc-49bd-bf72-0574db37445b",
                "source": null,
                "classification": null,
                "aspect": null,
                "majorVersion": null,
                "isDeleted": false
            }
        ],
        "relation": [],
        "assetDescription": "sample asset json",
        "assetIcon": "asseticon.jpeg",
        "assetColor": "default",
        "assetCreatedTime": "18-JUL-2019 17:34:50.690 IST",
        "assetUpdatedTime": "18-JUL-2019 17:34:50.690 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": "",
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false"
    }
]

6.20. Process Observations in Asset

This API updates the asset observed properties from sensor observation JSON. Sensor mapping with assets have to be present as a pre-requisite. This API is called by Action Service to automatically update asset whenever a SOS observation is generated.

Method: POST
URL: https://{domain}/AssetService/asset/deleteRule?assetId=930&rule=R2&id=57

Key Value
Header x-api-key, x-user-key(optional)
RequestBody SOS observation JSON

Body

{
  "observations": [{
      "record": [{
          "output": [{
              "name": "occupancy",
              "type": "DOUBLE",
              "unit": "m",
              "value": "12.5"
            }],
          "starttime": "1-NOV-2018 08:30:56 IST"
        }],
      "sensor": "occupancy-sensor"
      }],
  "version": "1.0.1"
}

Response

[
  {
    "httpStatus": "200",
    "status": "Existing asset updated."
  }
]

6.21. Compare Asset

This API provides a comparasion between the assets.

Method: GET
URL: https://{domain}/AssetService/asset/compareAssets?sourceSet=30&destinationSet=31&propertyNameSet=B1

Key Value
Header x-api-key, x-user-key(optional)
RequestParameter sourceSet(comma separated assetIds or single assetId), destinationset (comma separated assetIds or single assetId), sourceAssetTypeId, destinationAssetTypeId, propertyNameSet(comma separated asset proeprty names or single name)

Response

[
  {
    "destination": [
      {
        "assetId": "31",
        "assetName": "A_tenant_7",
        "assetGuid": "867531bde10046778a805963bd705d73173456294211940",
        "projectId": "8",
        "location": null,
        "latitude": "0.0",
        "longitude": "0.0",
        "altitude": null,
        "assetTypeId": "9",
        "assetTypeName": "B_Tenant_24Sep_updated",
        "privacy": "public",
        "typeRelation": [],
        "status": "active",
        "geohash": "s00000000000",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "sensorIdList": [],
        "parent": "30",
        "parentName": "A_tenant_6",
        "childAssets": [
          "A_tenant_8",
          "A_tenant_10"
        ],
        "childAssetWithId": [
          {
            "assetId": "32",
            "assetName": "A_tenant_8"
          },
          {
            "assetId": "34",
            "assetName": "A_tenant_10"
          }
        ],
        "assetProperty": [
          {
            "propertyId": "64",
            "assetPropertyName": "B1",
            "assetPropertyType": "USER_DEFINED",
            "assetPropertyValue": "14.5",
            "dataType": "double",
            "assetPropertyUnit": "meter",
            "assetPropertyExpression": "null",
            "assetPropertyRange": null,
            "uri": null,
            "recordTime": "27-SEP-2018 12:20:41.400 IST",
            "propertyLastupdatedTime": "27-SEP-2018 12:20:41.400 IST",
            "isEditable": true,
            "isDeletable": true,
            "isViewable": true,
            "isMovable": false,
            "isVirtual": false,
            "isUnique":false,
            "isPersist": true,
            "isNotification": true,
            "isDirty": true,
            "isRuleset": false,
            "propertyDescription": null,
            "propertyIcon": "default",
            "propertyColor": "default",
            "createdBy": null,
            "updatedBy": null,
            "status": "active",
            "filter": null,
            "mandatory": false
          }
        ],
        "relation": [],
        "assetDescription": null,
        "assetIcon": "default",
        "assetColor": "default",
        "assetCreatedTime": "27-SEP-2018 12:20:41.400 IST",
        "assetUpdatedTime": "27-SEP-2018 12:20:41.400 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": null,
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false",
        "updateCount": "0"
      }
    ],
    "source": [
      {
        "assetId": "30",
        "assetName": "A_tenant_6",
        "assetGuid": "0d2465e1b9444e3aacc70337db27b254173431120883330",
        "projectId": "8",
        "location": null,
        "latitude": "0.0",
        "longitude": "0.0",
        "altitude": null,
        "assetTypeId": "9",
        "assetTypeName": "B_Tenant_24Sep_updated",
        "privacy": "public",
        "typeRelation": [],
        "status": "active",
        "geohash": "s00000000000",
        "composedOf": [],
        "composedOfAssetProperty": [],
        "sensorIdList": [],
        "parent": "24",
        "parentName": "A_tenant_renamed",
        "childAssets": [
          "A_tenant_7"
        ],
        "childAssetWithId": [
          {
            "assetId": "31",
            "assetName": "A_tenant_7"
          }
        ],
        "assetProperty": [
          {
            "propertyId": "64",
            "assetPropertyName": "B1",
            "assetPropertyType": "USER_DEFINED",
            "assetPropertyValue": "11",
            "dataType": "double",
            "assetPropertyUnit": "meter",
            "assetPropertyExpression": "null",
            "assetPropertyRange": null,
            "uri": null,
            "recordTime": "27-SEP-2018 12:20:16.333 IST",
            "propertyLastupdatedTime": "27-SEP-2018 12:20:16.333 IST",
            "isEditable": true,
            "isUnique":false,
            "isDeletable": true,
            "isViewable": true,
            "isMovable": false,
            "isVirtual": false,
            "isPersist": true,
            "isNotification": true,
            "isDirty": true,
            "isRuleset": false,
            "propertyDescription": null,
            "propertyIcon": "default",
            "propertyColor": "default",
            "createdBy": null,
            "updatedBy": null,
            "status": "active",
            "filter": null,
            "mandatory": false
          }
        ],
        "relation": [],
        "assetDescription": null,
        "assetIcon": "default",
        "assetColor": "default",
        "assetCreatedTime": "27-SEP-2018 12:20:16.333 IST",
        "assetUpdatedTime": "27-SEP-2018 12:20:16.333 IST",
        "assetCreatedBy": null,
        "assetUpdatedBy": null,
        "filtertag": null,
        "ismovable": "false",
        "isvirtual": "false",
        "updateCount": "0"
      }
    ]
  }
]

7. EventType

7.1. Create Event Type

The ruleUrl, createdBy fields do not have to be validated as these fields are for taking user inputs.

Method: POST
URL: https://{domain}/AssetService/eventtype/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "eventTypeName":"Car Start",
   "description":"The car engine is started",
   "projectId":"2",
   "ruleId":"45",
   "ruleUrl":"www.ruleurl.com?id=45",
   "createdBy":"Dibs"
}

Response

[
{
    "httpStatus": "201",
    "id": "7",
    "status": "New event type created."
}
]

7.2. Delete Event Type

This API is used to delete an existing event type.

Method: DELETE
URL: https://{domain}/AssetService/eventtype/delete

Key Value
Header x-api-key,x-user-key (optional)
RequestParameter eventTypeId

Response

[
  {
    "httpStatus": "200",
    "status": "Event type deleted successfully."
  }
]

7.3. Get All Event Type

This API is used to produce all the event types for the user.

Method: GET
URL: https://{domain}/AssetService/eventtype/getAll

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter projectId (mandatory), eventTypeId, status

Response

[{
        "eventTypeId": "27",
        "eventTypeName": "Clock Invalid",
        "description": "Clock Invalid",
        "createdBy": "Dibs",
        "createTime": "16-JAN-2018 10:02:50.763 UTC",
        "updatedBy": "Dibs",
        "updatedTime": "16-JAN-2018 10:02:50.763 UTC",
        "userId": "37",
        "projectId": "2",
        "status": "active",
        "ruleId": "45",
        "ruleUrl": "www.ruleurl.com?id=45"
    },
    {
        "eventTypeId": "4",
        "eventTypeName": "Car Start",
        "description": "The car engine is started",
        "createdBy": "Dibs",
        "createTime": "30-OCT-2017 11:14:25.043 UTC",
        "updatedBy": "Dibs",
        "updatedTime": "30-OCT-2017 11:14:25.043 UTC",
        "userId": "37",
        "projectId": "2",
        "status": "active",
        "ruleId": "45",
        "ruleUrl": "www.ruleurl.com?id=45"
    }
]

7.4. Update Event Type

This API is used to update an existing eventtype. “eventTypeId”,”projectId” cannot be updated.

Method: PUT
URL: https://{domain}/AssetService/eventtype/update

Key Value
Header x-api-key, x-user-key (optional)

Body

{
  "eventTypeId":"1",
  "eventTypeName":"Car Start",
   "description":"The car engine is started",
   "projectId":"2",
   "ruleId":"45",
   "ruleUrl":"www.ruleurl.com?id=45",
   "createdBy":"Dibs",
   "status": "active"
}

Response

[
  {
    "httpStatus": "205",
    "status": "Event type updated."
  }
]

7.5. Get Event Type By AssetID

This API displays event type registered for an exisitng asset ID.

Method: GET
URL: https://{domain}/AssetService/eventtype/data/getEventTypesByAssetId

Key Value
Header x-api-key, x-user-key (optional)
RequestParameter assetId

Response

[
  "Car Start",
  "Car Stop"
]

7.6. Create Rule for Event Type

This API creates event type rule for a given asset ID and event type ID.

Method: POST
URL: https://{domain}/AssetService/eventtype/rule/create

Key Value
Header x-api-key, x-user-key (optional)

Body

{
   "eventTypeId":"1",
   "assetId":"1",
   "rule":"(Height + Width) > 200 && (Height + Width) < 400",
   "createdBy":"Dibs"
}

Response

[{
    "httpStatus": "201",
    "id": "5",
    "status": "New Rule created."
}]

7.7. Delete Rule for Event Type

This API deletes an existing asset event type rule ID.

Method: DELETE
URL: https://{domain}/AssetService/eventtype/rule/delete

Key value
Header x-api-key,x-user-key (optional)
RequestParameter ruleId

Response

[
  {
    "httpStatus": "200",
    "status": "Asset Event type rule deleted successfully."
  }
]

7.8. Get All Rule for Event Type

This API displays all the asset event type rules created for that user.

Method: GET
URL: https://{domain}/AssetService/eventtype/rule/getAll

Key value
Header x-api-key,x-user-key (optional)
RequestParameter assetId

Response

[
    {
        "ruleId": "1",
        "eventTypeId": "1",
        "eventTypeName": "Ht+wd gt 100",
        "assetId": "1",
        "createdBy": "Dibs",
        "createTime": "12-DEC-2017 12:22:21.135 IST",
        "rule": "(Height + Width) > 100 && (Height + Width) < 200"
    },
    {
        "ruleId": "2",
        "eventTypeId": "2",
        "eventTypeName": "Ht+wd gt 200",
        "assetId": "1",
        "createdBy": "Dibs",
        "createTime": "12-DEC-2017 12:22:35.318 IST",
        "rule": "(Height + Width) > 200"
    }
]

7.9. Update Rule for Event Type

This API helps to update an existing asset event type rule. “ruleId”,

Method: PUT
URL: https://{domain}/AssetService/eventtype/rule/update

Key Value
Header x-api-key, x-user-key (optional)

Body

{
    "ruleId": "1",
    "eventTypeId": "1",
    "assetId": "1",
    "rule": "(Height + Width) > 100 && (Height + Width) < 400"
  }

Response

[
  {
    "httpStatus": "205",
    "status": "Event type rule updated."
  }
]

7.10. Add New Asset Type Rule

This API creates assettype event type rule.

Method: PUT
URL: https://{domain}/AssetService/eventtype/addNewAssetTypeRule

Key value
Header x-api-key, x-user-key (optional)

Body

{
    "assetTypeRule": [{
        "eventTypeId": "1",
        "ruleId": "1",
        "ruleDescription": "some brief rule descriptions",
        "metaDataList": [{
            "name": "Height",
            "value": "50",
            "operator": "<",
            "type": "quantity"
        }]
    }]
}

Response

[{
    "httpStatus": "205",
    "message": "New asset type-rule mapping added.",
    "status": "Assettype updated."
}]

7.11. Delete Asset Type Rule

This API deletes the assettype event type rule.

Method: DELETE
URL: https://{domain}/AssetService/eventtype/deleteAssetTypeRule

Key Value
Header x-api-key,x-user-key (optional)
RequestParameter assetTypeId (Mandatory), ruleId (Mandatory), rulemappingid (Mandatory)

Response

[{
    "httpStatus": "204",
    "status": "Rule deleted successfully."
}]

8. Event

Systems like MR, CEP or any other external systems can use this feature to record various events that take place on any asset.

8.1. Create Event

This API creates an event for an event type ID.

Method: POST
URL: https://{domain}/AssetService/event/create

Key value
Header x-api-key, x-user-key (optional)

Body
This API supports payload in 2 formats:
First format :

{
  "version": "1.0.1",
  "observations": [
    {
      "id": 378605,
      "sensor": "",
      "record": [
        {
          "starttime": "26-MAY-2017 07:23:19 UTC",
          "output": [
            {
              "name": "eventKeywords",
              "value": "Car Operation,Car,Start"
            },
            {
              "name": "projectId",
              "value": "2"
            },
            {
              "name": "obsvPayload",
              "value": "{ \"version\": \"1.0.1\", \"observations\": [{  \"sensor\": \"Sensor-4\",  \"record\": [{   \"starttime\": \"1-JAN-2017 15:30:00 IST\",   \"output\": [{    \"name\": \"sensor\",    \"value\": \"333\"   },{    \"name\": \"eventtype\",    \"value\": \"Car Start\"   },{    \"name\": \"ruleid\",    \"value\": \"21\"   }]  }] }, {  \"sensor\": \"Sensor-Dibs\",  \"record\": [{   \"starttime\": \"1-JAN-2017 15:30:00 IST\",   \"output\": [{    \"name\": \"speed\",    \"value\": \"11\"   },{    \"name\": \"eventtype\",    \"value\": \"Car Stop\"   },{    \"name\": \"ruleid\",    \"value\": \"34\"   }]  }] }]}"
            },
            {
              "name": "eventSource",
              "value": "System 1"
            },
            {
              "name": "createdby",
              "value": "Dibs"
            },
            {
              "name": "eventType",
              "value": "Car Start"
            },
            {
              "name": "prevEventId",
              "value": "378604"
            },
            {
              "name&