Sigma Extension for Zoho IoT

Sigma Extension for Zoho IoT

 
Zoho offers the Sigma extension development platform, enabling developers to build and host custom functionalities for various Zoho products. Zoho IoT leverages Sigma to facilitate the creation of tabs within the application, enhancing customization and efficiency in IoT solutions.
Zoho Extension Toolkit (ZET) is used to create extensions with the customization offline in your machine. Once the extensions are created, you'll need to upload them as a zip file in Sigma.
 
This document provides steps for installing ZET on your machine to package and upload the project ZIP file.
 

Prerequisite 

To install ZET and build your extension online, you need the following in your machine:
  1. Node.js (version 7.1.0 or higher)
  2. npm (version 3 or higher )

Creating Public Sigma 

The following steps must be performed for installing the public sigma and to run the server.


1. Installing ZET
 

For Mac/Unix system

sudo: npm install -g zoho-extension-toolkit

For Microsoft Windows

system: npm install -g zoho-extension-toolkit
 
-g denotes global installation. When ZET is installed globally, you will be able to execute commands from anywhere on the terminal. Otherwise, you will have to navigate to the path where ZET is installed, then execute commands.
 

 2. Creating the ZET Project   

(i) Execute the below command in the terminal to list the Zoho services.

$ZET init



(ii) Select Zoho IOT in the Zoho services list and hit enter.
(iii) Enter the name of the project when prompted.


The ZET Sigma project will be created.

Notes
Note: A default plugin-manifest.json file is generated as a part of the project template directory. This is a core configuration file placed at the root directory that has the location where the application has to be loaded.

 3. Starting the ZET Server   

Run the following command to start the Sigma server.

$ZET run

Initializing Sigma SDK 

In the next steps, the widget.html file located in the project application directory -> app folder needs be verified and modified (if required) to load the unified SDK and to call the relevant API.

A sample widget.html file content is provided below:
 
 
//widget.html file content
 
<!DOCTYPE html>
<!DOCTYPE html>
<html>
 
<head>
        <meta charset="UTF-8">
        <title>Zoho IOT - Apps</title>
</head>
 
<body>
 
        <h2>This is a sample App built using ZET CLI.</h2>
        <div id="response" style="white-space: pre;"></div>
<script src="https://static.zohocdn.com/sigma/client/sdk/v3/sigma-sdk.min.js"></script>
<script>
window.ZIOT = {};
window.ZIOT.getIoTSDK = ()=>{
        let promise = new Promise((resolve)=>{
                window.ZIOT.iotSDK = SigmaSDK.IOT.init(()=>{
                        resolve();
                });
        });
return promise;
};
 
ZIOT.getIoTSDK().then(()=>{
        ZIOT.iotSDK.get(['records', 'devices', '', {per_page: 1, lookup_type: 'quick'}]).then((response) => {
                        if(response){
                                document.querySelector('div#response').innerText = JSON.stringify(response.records, null, '\t');
                        }
        });
});
 
</script>
</body>
 
</html>
 

The sections of the widget.html file content given above that needs to be modified (if required) to load and initialize the Sigma SDK is provided below.

 
1. Loading the Sigma SDK  

 
<script src="https://static.zohocdn.com/sigma/client/sdk/v3/sigma-sdk.min.js"></script>
 
 
Notes
Note: The initializing of the SDK should happen only after downloading the sigma-sdk.min.js file.
 

2. Initializing the Sigma SDK 

To initialize the SigmaSDK and to use its functionalities. Call SigmaSDK.IOT.init() method in the wrapper as follows which returns a promise.

 
window.ZIOT = {};
window.ZIOT.getIoTSDK = ()=>{
        let promise = new Promise((resolve)=>{
                window.ZIOT.iotSDK = SigmaSDK.IOT.init(()=>{
                        resolve();
                });
        });
return promise;
};
 

 3. Communicating with UI client to get Data 

To communicate with UI client and fetch data, use the below code snippet as sample.

 
ZIOT.getIoTSDK().then(()=>{
        ZIOT.iotSDK.get(['records', 'devices', '', {per_page: 1, lookup_type: 'quick'}]).then((response) => {
                        if(response){
                                document.querySelector('div#response').innerText = JSON.stringify(response.records, null, '\t'); //your logic here
                        }
        });
});
 
Refer to the Sigma SDK Utils section for more details on the APIs.

 
Validating, Packing, and Uploading the Application 

Before uploading the final zip of the application, the following two commands must be executed to validate & package the application.


 1. Validating the Application 

To validate the application, execute the below command from the root directory.


$ ZET validate

 
After running the validation command, any errors identified must be addressed. If these validation issues are not resolved, the application cannot be uploaded, as the same code checks will occur during the upload to the Sigma service.

 2. Packaging the  Application 

To package the application, execute the below command.


$ ZET pack

  
When working on your project folder, it contains both the application source files and node modules necessary for local testing. Before uploading the application, ensure that the ZIP file includes only the relevant application files and folders. To simplify this packaging process, we provide a command called 'pack,' which creates a ZIP file containing only the essential application files, excluding node module-related files. This ZIP file is now ready to be uploaded.

 3. Uploading the  Application

After running the packaging command, a ZIP file named after your project will be generated in the 'dist' folder. You can upload this file to your application's settings by navigating to Integrations > Sigma Extensions. The following details are required for the update:
  1. category
    1. tab - customized page in the main menu tab
    2. form - customized form or user-created custom module addition
  2. module - this is mandatory for "form category"
  3. Extension zip (the packaged ZIP file generated in the previous step)
Notes
 Notes: To show the Sigma extension as a tab (menu), it has to be added as a menu through the Navigation Menu in the Zoho IoT Developer Portal. You can see Sigma Extensions as one of the modules there. 
   

Sigma Extension - SDK Utils 

This section of the document lists the Utils that can be used in Sigma SDK.

  1. Get Current User
Use this to get current logged in user details

Sample: GET  ZIOT.iotSDK.get('current-user')
 

ZIOT.iotSDK.get('current-user').then((response)=>{
        //your logic
});


Response can be used to include own logic.
 
  1. Get Org/Application info
Use this to get org/application details

Sample: GET  ZIOT.iotSDK.get('app_info')


ZIOT.iotSDK.get('app_info').then((response)=>{
        //your logic
});

 
  1. Get Client portal info
Use this to get client portal details

Sample: GET  ZIOT.iotSDK.get('client_portal_meta')


ZIOT.iotSDK.get('client_portal_meta').then((response)=>{
        //your logic
});


  1. Get All records by module
Use this to get records array by module (Get Records API) with pagination

Sample: GET  ZIOT.iotSDK.get(['records', '<module_apiname>', '', queryparams])


ZIOT.iotSDK.get(['records', '<module_apiname>', '', queryparams]).then((response) => {
// your logic
});


Refer to API documentation for query params.

  1. Get specific record by module
Use this to get record by module

Sample: GET  ZIOT.iotSDK.get(['record', '<module_apiname>', <record_id>, queryparams])


ZIOT.iotSDK.get(['record', '<module_apiname>', <record_id>, queryparams]).then((response) => {
// your logic
});


Refer to API documentation for query params.
 
  1. Get module
Sample: GET  ZIOT.iotSDK.get(['modules', '<module_apiname>', queryparams]);


ZIOT.iotSDK.get(['modules', '<module_apiname>', queryparams]).then((response) => {
// your logic
});


Refer to API documentation for query params.
 
  1. Get total records count of module
Use this to get records count by module

Sample: GET  ZIOT.iotSDK.get(['records_total_count', <module_api>, queryparam]);


ZIOT.iotSDK.get(['records_total_count', <module_api>, queryparam]).then((response) => {
// your logic
});
 

Refer to API documentation for query params.

  1. Get related records of a specific record
Use this to get related record count by module

Sample: GET  ZIOT.iotSDK.get(['records_total_count', <module_api>, <record_id>, <related_list_api_name>, queryParam]);


ZIOT.iotSDK.get(['related-records', <module_apiname>, <record_id>, <related_list_api_name>, queryParam]).then((response) => {
// your logic
});

 
Refer to API documentation for query params.

  1. Get total related records count of a specific record
Sample: GET  ZIOT.iotSDK.get(['records_total_count', <module_api>, <record_id>, <related_list_api_name>]);


ZIOT.iotSDK.get(['related-records', <module_api>, <record_id>, <related_list_api_name>]).then((response) => {
// your logic
});


  1. Get BD data by datapoint name
Use this to get BD data by giving datapoint name and source name

Sample: GET     ZIOT.iotSDK.get(['datapoints_data', queryparam]);


let queryparam = {
        source: <record name>,
      datapoint_name: <datapoint_name>,
      days: 1,
hrs: 4,
aggregation: 'avg',
time_grouping: 'hour'
    };
ZIOT.iotSDK.get(['datapoints_data',queryparam])
.then((response)=>{
//Your logic
    });

 
  1. Create record by module
Use this to create a record for a module

Sample: GET     ZIOT.iotSDK.dispatch('createRecord', {module: <module_apiname>, data: {}});


ZIOT.iotSDK.dispatch('createRecord', {//No I18N
        module: <module_apiname>,//No I18N
        data: {<module_apiname>: {}}
    }).then((response)=>{
//Yur logic
    });


  1. Update record by module
Use this to update a record for a module

Sample: PUT     ZIOT.iotSDK.dispatch('updateRecord', {module: <module_apiname>, data: {}});


ZIOT.iotSDK.dispatch('updateRecord', {//No I18N
     module: <module_apiname>,//No I18N
     data: {<module_apiname>: {}}
    }).then((response)=>{
//Yur logic
    });


  1. Delete record by module
Use this to delete a record for a module

Sample: DELETE     ZIOT.iotSDK.dispatch('deleteRecord', {module: <module_apiname>, id: <record_id>});


ZIOT.iotSDK.dispatch('deleteRecord', {//No I18N
     module: <module_apiname>,//No I18N
     id: <record_id>
    }).then((response)=>{
//your logic
    });