diff --git a/_data/trendz/docs-home.yml b/_data/trendz/docs-home.yml index a826b5ad75..af2d3ff96c 100644 --- a/_data/trendz/docs-home.yml +++ b/_data/trendz/docs-home.yml @@ -59,8 +59,6 @@ toc: path: /docs/trendz/calculated-fields/ - title: Batch calculations path: /docs/trendz/batch-calculated-fields/ - - title: Test functions - path: /docs/trendz/test-calculated-fields/ - title: Save metric to ThingsBoard path: /docs/trendz/save-calculated-to-thingsboard/ - title: Prediction @@ -87,8 +85,6 @@ toc: path: /docs/trendz/widget-settings/ - title: External datasources path: /docs/trendz/mix-sql-datasource/ -- title: Sync to ThingsBoard - path: /docs/trendz/save-telemetry-to-thingsboard/ - title: States path: /docs/trendz/states/ - title: Caching @@ -97,6 +93,8 @@ toc: path: /docs/trendz/background-jobs/ - title: White labeling path: /docs/trendz/white-labeling/ +- title: Tasks + path: /docs/trendz/tasks-service/ - title: Trendz REST API path: /docs/trendz/rest-api/ - title: Trendz release notes diff --git a/docs/trendz/calculated-fields.md b/docs/trendz/calculated-fields.md index 4d7120b248..70b3d439c7 100755 --- a/docs/trendz/calculated-fields.md +++ b/docs/trendz/calculated-fields.md @@ -9,28 +9,112 @@ description: Trendz Calculated Fields * TOC {:toc} -Calculated fields are one of the most powerful features for KPI monitoring and prediction. -Based on the input data, calculated fields allow you to run statistical functions and create new data items by applying calculations. -As Trendz Analytics processes the calculations on the fly, no data from ThingsBoard database will be damage. - And no additional load will be applied. +Calculated fields are a powerful feature in Trendz for KPI monitoring and prediction. They allow you to apply statistical functions and create new data items based on your input data, all while processing calculations on the fly. +This ensures that no data in the ThingsBoard database is damaged or subjected to additional load. Trendz offers a robust tool for creating and managing these calculated fields, enabling complex calculations and custom formulas for data analysis and visualization. +Additionally, you can store your calculations as telemetry in ThingsBoard, enhancing the utility and integration of your data. +To access the calculated fields tool, click on the icon **√x** labeled "Calculation Fields" located on the left side of the workspace. -## Simple calculation +Within this section, a table lists all created calculated fields, along with key details. You can open, modify, or perform other actions on any of these fields. +To create a new calculated field, click the "Create Calculation Field" button. + +![image](https://img.thingsboard.io/trendz/calculated-field-create.png) + + +## Function Tab + +The Function tab is where you configure parameters that affect data calculations. Below is a breakdown of each option: + +***KEY:*** The identifier under which the calculated telemetry data is saved in ThingsBoard with prefix \_ECD_. *(Required)* + +***ENTITY:*** The business entity to which this calculated field is linked. Affects entity settings, visualization, and filters. *(Required)* + +***LANGUAGE:*** The scripting language for the calculation function. Choose between JavaScript (default) and Python. +* *JavaScript:* Uses ECMAScript 5.1 for writing transformation functions. +* *Python:* Supports Python 3.8 and libraries such as Flask, NumPy, Pandas, etc. + +***GROUPING INTERVAL:*** Time interval for data grouping (e.g., hour, day, week, month). + +***FIELD TYPE:*** + +* *Simple:* Processes one value at a time. +* *Batch:* Works with the entire raw telemetry array. + +***AGGREGATION:*** Method for data aggregation, including options like AVG, SUM, LATEST, MIN, MAX, COUNT, UNIQ, etc. + +Aggregation function applied to a grouped dataset. Find more details about [Grouping and Aggregation in this article](/docs/trendz/data-grouping-aggregation/) + +***Fill Gap:*** Handles missing telemetry data with different methods, which are selected in the TIME UNIT and STRATEGY settings. + +***TIMERANGE STRATEGY:*** Determines data loading strategy during refresh tasks: + +* *Dynamic Strategy:* Loads new data since the last calculation. +* *Fixed Strategy:* Uses a predefined time range for each execution. + +For details on writing functions for [Calculated Fields](/docs/trendz/calculated-fields/), refer to the corresponding documentation section. +Choose to work with aggregated or raw data by enabling [batch mode](/docs/trendz/batch-calculated-fields/) as needed. + +![image](https://img.thingsboard.io/trendz/calculated-function-tab.png) + + + +## Input Tab + +The Input section allows you to define and understand the data that will be used in your calculations. Here’s a breakdown of each field: + +***Data Field:*** +* *Real Data:* Displays read-only input data based on specified parameters. +* *Manual:* Allows custom data input for testing. Manual data entries can be deleted, copied, or modified. Editable fields are highlighted with a gray background. + +***Main Fields:*** +* *startTs (Start Timestamp):* Defines the calculation's start period. +* *endTs (End Timestamp):* Defines the calculation's end period. +* *groupBy:* Sets the time interval for data grouping. +* *tzName (Time Zone Name):* Selects the desired time zone. +* *zOffsetMs (Time Zone Offset in Milliseconds):* Adjusts data according to the local time zone. + +This setup makes sure the data is defined correctly, allowing for accurate calculations and useful insights. + +![image](https://img.thingsboard.io/trendz/calculated-input-tab.png) + + + +## Output Tab + +When you click "Run test," you will access the Output tab, featuring the following modes: + +***Function:*** Modify previously defined calculations for testing. + +***Output Data:*** View calculation results (simple values or arrays). Results can be displayed as a table or line chart. + +***Logs:*** Shows logs similar to those in the browser console. + +![image](https://img.thingsboard.io/trendz/calculated-output-tab.png) -Let's assume that sensor submit boiler temperature in Celsius and we want convert it to Fahrenheit: -* Drop **Calculated** field from left navigation to the **Y axis** section -* Open field configration and write transformation function + +## Tasks Tab + +The Tasks tab provides an overview of all tasks initiated for a specific calculation, including their status (completed, in progress, or pending). +For more detailed task management information, refer to the corresponding section in the documentation. + + + +## Examples + +**Simple calculation** + +Let's assume that sensor submit boiler temperature in Celsius and we want convert it to Fahrenheit: {% highlight javascript %} - var celsius = avg(Machine.boilerTemp); - var fahrenheit = celsius*1.8 + 32; - return fahrenheit; +var celsius = avg(Machine.boilerTemp); +var fahrenheit = celsius*1.8 + 32; +return fahrenheit; {% endhighlight %} ![image](https://img.thingsboard.io/trendz/calculated-simple.png) -## Multiple fields for calculation +**Multiple fields for calculation** In this example we have Apartment asset that has 2 sensors installed - HeatMeter and EnergyMeter. Both sensors submit how much energy was consumed. Also Apartment has area attribute that contains apartment size. We want calculate total energy consumed by HeatMeter and EnergyMeter @@ -41,24 +125,18 @@ in Apartment per square meter. Let's break it to subtasks: * Get Appartment size - **area** attribute * Sum **heatConsumption** and **energyConsumption** * Devide it by **area** - -For implementing this we need to: -* Drop **Calculated** field from left navigation to the **Y axis** section -* Open field configration and write transformation function - + {% highlight javascript %} - var energy = sum(energyMeter.energyConsumption); - var heat = sum(heatMeter.heatConsumption); - var size = uniq(apartment.area); +var energy = sum(energyMeter.energyConsumption); +var heat = sum(heatMeter.heatConsumption); +var size = uniq(apartment.area); return (energy + heat) / size; {% endhighlight %} ![image](https://img.thingsboard.io/trendz/calculated-complex-config.png) -![image](https://img.thingsboard.io/trendz/calculated-complex-result.png) - -## Get original field value +**Get original field value** Before applying transformation you need to get a reference to the original field value. Here is an example how to do this: @@ -74,43 +152,83 @@ var temp = avg(Machine.temperature); If original field value is an attribute, entity name or owner name - you should use **uniq()** aggregation function. -## Supported Aggregation Functions -JSEditor for calculated fields supports following aggregation functions: -* avg() -* sum() -* min() -* max() -* count() -* latest() -* uniq() +## Saving and Editing Calculations -Each function allows only 1 argument - reference to the filed on format EntityName.fieldName. For example: +After creating a calculated field, you can save it for future use by clicking the "Save Field" button located in the upper right corner. +The saved field will appear in the list of business entities within the view fields, using the specified name from the calculation. +If a field with the same name or key already exists, the system will notify you of the duplicate. -``` -sum(Machine.temperature) -``` +**Enabling Calculated Fields** -Aggregation function applied to a grouped dataset. Find more details about [Grouping and Aggregation in this article](/docs/trendz/data-grouping-aggregation/) +During the saving process, you have the option to "Enable" the calculated field. When enabled, the calculated field will be recorded as telemetry in ThingsBoard with the specified parameters. + +![image](https://img.thingsboard.io/trendz/calculated-enable.png) + +For more details, refer to the [Save Metric to ThingsBoard](/docs/trendz/save-calculated-to-thingsboard/) section. + +**Modifying and Re-Saving Calculations** + +Once saved, you can modify your calculations as needed. Here's how the process works: + +**Modifying the Calculation:** +* *Access the Calculation:* Navigate to the specific calculation you want to adjust. You can make changes to the formula, update parameters, or modify data sources. + +**Re-Saving the Calculation:** +* *Save Changes:* After making modifications, save the calculation again. + +**Applying Changes to View Fields:** +* *Prompt for Update:* Upon re-saving, Trendz will prompt you to apply these changes across all view fields based on this calculation, ensuring consistency in data representation. +* *Automatic Update:* If you choose to apply the changes, all relevant view fields will automatically update with the new logic or parameters. + +**Handling Enabled Calculations:** +* *Reprocess Task:* If the calculation was enabled and you modify and re-save it, you will need to run the Reprocess Task to apply the updated logic to historical data. +* *Future Data:* Without running the Reprocess Task, the updated calculation only applies to new data recorded after re-saving, leaving historical data unchanged. +* *How to Run the Reprocess Task:* Go to the Tasks tab and click the “Run Reprocess Task” button to apply the updated calculation to all relevant historical data. + +![image](https://img.thingsboard.io/trendz/calculated-reprocess-task.png) + +This functionality ensures seamless management of calculations, consistently reflecting updates across all areas where the calculation is applied. + + +## Using Calculations in View Fields + +Once you have created and saved a calculation in Trendz, it can be used in view fields to enhance data representation and analysis. Here’s how to effectively use these calculations: + +**Accessing the Calculations in View Fields** +* *Business Entities List:* Calculations created by a tenant will appear in the list of business entities under the name provided during creation. This allows for easy selection and integration into view fields. +* *Telemetry Display for Customers:* Once enabled, the calculated data becomes visible to end users as telemetry. It will be displayed under the key name defined in the calculation, making it accessible in dashboards and widgets. + +![image](https://img.thingsboard.io/trendz/calculated-view-fields.png) + +**Using the Calculation in Views** + +Simply select the desired calculation to include it in the view field. The data generated by this calculation will now be part of the visual representation in the selected view. + +**Using Real-Time (RT) and ThingsBoard (TB) Data** +* *ThingsBoard Data (TB):* Calculations saved as telemetry in ThingsBoard can be displayed in view fields for historical or periodically updated data. These calculations update according to the schedule set in the task settings. +* *Real-Time Data (RT):* For immediate data needs, real-time calculations can be utilized. Note that RT calculations might take longer to process than batch-calculated data. + +![image](https://img.thingsboard.io/trendz/calculated-real-time.png) + +**Editing and Managing Calculations:** + +To adjust or manage a calculation after adding it to a view field, access the calculation settings directly from the view field configuration by pressing the "Go to calculation field" button. + +![image](https://img.thingsboard.io/trendz/calculated-go-to-calculation.png) -## Save and reuse calculated fields -Once the calculated field is created you can save it for future reuse by pressing **Save Field** button under function editor. -Current field label would be used as a field name. If a field with such name already exists - the system will overwrite it. +## Disabled Calculation -Saved calculated field is only a template. Once it is dropped from the left navigation tree into some axis, a new -calculated field created and this field would not be connected with the original template. -It means that if you will update field configuration in the future, it will only update a template, -but real calculated fields that are added to View configuration are not affected. +If a calculated field is disabled isn't saved in ThingsBoard as telemetry, it will appear normally in the list of business entity fields. +However, when you drag this field into the chart-building area, a red bell icon will appear next to it. By clicking on the red bell icon, you can go directly to the created calculated field, where you can enable it as telemetry. -## Language and script engine +![image](https://img.thingsboard.io/trendz/calculated-disabled-bell.png) -You can write calculated fields using Javascript or Python. By default, Javascript engine is selected. +By following these steps, you can effectively use created calculations within view fields, making sure your data analysis is both complete and exact. -* **Javascript** - Calculated Fields use Javascript as a language for writing transformation function. Inner Engine provide 100% support of ECMAScript 5.1 -* **Python** - Python script engine support python 3.8 and provide full access to python standard libraries. Additionally, you can use following libraries: flask, numpy, statsmodels, pandas, scikit-learn, prophet, seaborn, pmdarima. ## Next Steps -{% assign currentGuide = "CalculatedFields" %}{% include templates/trndz-guides-banner.md %} \ No newline at end of file +{% assign currentGuide = "CalculatedFields" %}{% include templates/trndz-guides-banner.md %} diff --git a/docs/trendz/save-calculated-to-thingsboard.md b/docs/trendz/save-calculated-to-thingsboard.md index 6e7aaa6ca6..938c6b3cf1 100755 --- a/docs/trendz/save-calculated-to-thingsboard.md +++ b/docs/trendz/save-calculated-to-thingsboard.md @@ -6,26 +6,54 @@ title: Save calculated values as a telemetry into ThingsBoard description: Save calculated values as a telemetry into ThingsBoard --- -Calculated fields in Trendz offer the ability to compute various metrics based on existing telemetry and attributes. -These metrics can serve different purposes, from visualization in reports to triggering actions or reuse in other computations. -What's more, Trendz allows you to save these calculated metrics as device or asset telemetry back to ThingsBoard, enhancing the functionality of your IoT application. +Calculated fields in Trendz offer the ability to compute various metrics based on existing telemetry and attributes. +These metrics can serve different purposes, from visualization in reports to triggering actions or reuse in other computations. +What's more, Trendz allows you to save these calculated metrics as device or asset telemetry back to ThingsBoard, enhancing the functionality of your IoT application. Let's explore a few examples of how this feature can be utilized: -* By using the calculated metrics as input parameters for further calculations or predictions, you can enhance the accuracy and effectiveness of subsequent analyses. This empowers you to make more informed decisions based on reliable data. -* Creating alarms based on the calculated telemetry enables proactive monitoring and timely response. By setting thresholds or conditions, you can trigger alerts when the calculated values reach critical levels. This ensures that appropriate actions are taken promptly. -* Utilizing the calculated telemetry, you can set up notifications that provide real-time updates or alerts to relevant stakeholders. -* Performance Optimization - Once the metrics are computed and saved as telemetry, you can optimize the performance of the Trendz server. Instead of loading raw telemetry and recomputing metrics each time when they are required, the pre-computed metrics can be loaded directly from ThingsBoard. This reduces the load on the server, resulting in faster and more efficient operations. +* By using the calculated metrics as input parameters for further calculations or predictions, you can enhance the accuracy and effectiveness of subsequent analyses. + This empowers you to make more informed decisions based on reliable data. +* Creating alarms based on the calculated telemetry enables proactive monitoring and timely response. + By setting thresholds or conditions, you can trigger alerts when the calculated values reach critical levels. This ensures that appropriate actions are taken promptly. +* Utilizing the calculated telemetry, you can set up notifications that provide real-time updates or alerts to relevant stakeholders. +* Performance Optimization - Once the metrics are computed and saved as telemetry, you can optimize the performance of the Trendz server. + Instead of loading raw telemetry and recomputing metrics each time when they are required, the pre-computed metrics can be loaded directly from ThingsBoard. + This reduces the load on the server, resulting in faster and more efficient operations. +## Calculation Enable/Disable -Simplified workflow for saving calculated metrics to ThingsBoard is the following: +When you save a calculated field, it can be activated to initiate two main tasks and store the data in ThingsBoard as telemetry: +1. *Reprocess Historical Data:* +* This task runs once to analyze the data within the chosen time frame. +* It starts immediately after activation. +2. *Real-Time Refresh:* +* This task allows you to specify the data update frequency and select items to be refreshed. +* The task is scheduled to run at regular intervals, ensuring the data remains current in real-time. + +#### Item Selection for Calculation + +In addition to setting up the tasks, you can choose specific items for which you want the calculation to run: +* Select All: Apply the calculation to all available items. +* Choose Items for Calculate: Manually select the items to include in the calculation. + +![image](https://img.thingsboard.io/trendz/enable-button.png) + + +#### Storing Calculations as Telemetry + +When these settings are saved, your calculations are recorded in ThingsBoard as telemetry with a key name prefixed by \_ECD_, and the status of the calculation is set to “enabled” + +The data generated appears in the construction of view fields in the list of business entities under the name assigned to the calculation at the time of creation and, +if activated, will be updated according to the specified frequency when creating the task. The created calculation will appear in the view fields under the name given to the calculation during its creation. + +![image](https://img.thingsboard.io/trendz/name-calculation-field.png) + +If the calculation is not activated, it can still be used when constructing view fields, but users will receive a reminder indicating that no task has been created for this calculation. + +You can activate the calculated field at any time after saving by using the ENABLE button. -* Create Trendz calculated field to compute required metric -* Visualize metric in Table view -* Configure background job that will run calculations for new incoming telemetry -* Save computed metrics as a new telemetry to ThingsBoard -**Detailed step-by-step tutorial how to do this you can find in this article - [Sync to ThingsBoard](/docs/trendz/save-telemetry-to-thingsboard/).** ## Next Steps -{% assign currentGuide = "CalculatedFields" %}{% include templates/trndz-guides-banner.md %} \ No newline at end of file +{% assign currentGuide = "CalculatedFields" %}{% include templates/trndz-guides-banner.md %} diff --git a/docs/trendz/save-telemetry-to-thingsboard.md b/docs/trendz/save-telemetry-to-thingsboard.md deleted file mode 100755 index b4871776d8..0000000000 --- a/docs/trendz/save-telemetry-to-thingsboard.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: docwithnav-trendz -assignees: -- vparomskiy -title: Save telemetry to ThingsBoard -description: Save telemetry to ThingsBoard ---- - -* TOC -{:toc} - -Sometimes you can face to situation, where you need to do some complicated action on the data using different features -of Trendz and ThingsBoard at the same time. You understand you need to provide Trendz result data to ThingsBoard -for different purposes - make alert rules to data derived from particular calculations or provide the data to the rule chain. -After that, you notice that you can share data from Thingsboard, but not vice versa. -To solve this problem we have made a **Save Telemetry To TB** feature for each view configuration that you can create (table, line chart, etc). - -The **Save Telemetry To TB** feature provides the ability to make and save (to the same item) a new telemetry that is made -by a calculation field that is derived from any telemetry field that you want. It is a scheduled action that will be launched every chosen time unit to keep actual values during the present time. - -## Configuration steps: -* Create a view configuration (usually a table). -* Add a Date field to the Columns with the next types of date aggregation: **FULL_HOUR** or **FULL_DATE**. -* Add item name field of needed business entity - for example, if you have lamps that provide telemetry “light” you need to add the “lamps” business entity field (drop list on the left side of the screen). -* In the view config settings (right side of the screen) choose the **View Mode Field** menu, select `Row Click Entity` and choose the needed business entity - for example, lamp. -* Add Batched Calculated Field to the Columns and write a script that defines the necessary data for your business entity - for example, lamp. You can add a lot of these fields. Notice that you must use only one same Business Entity (for example, lamp). Usual calculation fields (not batched) are forbidden. -* Also, you must name fields by custom names and select the needed aggregation. Each name of each calculation field must be unique - otherwise, there will be collisions and data will rewrite each other. -* In the view config settings (right side of the screen) choose `TB calculated telemetry save`, choose how often the task must be launched by **Every** and **Time Unit** fields and switch on the checkbox. -* Press the **Save changes** Button to save the view configuration. - -## Review historical jobs -In view settings page where scheduling was configured you can press `Show History` button will appear in the **TB calculated telemetry save** menu and you can check when the task was performed, what was the duration of the task and their status. - -## Important notes - -* You can add any telemetry/attribute field just to see the data - they will be ignored for saving to TB. -* Only Batched Calculation Fields will be used. -* Usual calculation fields (not batched) are forbidden. -* Use only one same Business Entity. -* The new telemetry key would have name: `Trendz_[field aggreagtion]_[field name]` -* Used Date field aggregation will define how often the data will be represented on the timeline (each hour/each day). diff --git a/docs/trendz/tasks-service.md b/docs/trendz/tasks-service.md new file mode 100644 index 0000000000..91724fd886 --- /dev/null +++ b/docs/trendz/tasks-service.md @@ -0,0 +1,59 @@ +--- +layout: docwithnav-trendz +assignees: +- vparomskiy +title: Tasks +description: Task Service in Trendz +--- + +* TOC +{:toc} + +## Tasks Tab + +The Task Service in Trendz is a key feature for managing and running tasks related to data processing and calculations. It takes care of scheduling, running, and monitoring these tasks, +ensuring that data updates and calculations happen efficiently and on time. This service is essential for automating and optimizing the handling of both real-time data and reprocessing historical data, helping you manage large datasets effectively. +To see your tasks, go to the Tasks section in the main menu. Here, you will find a list of all tasks with a brief overview. Use the Job Type Filter to choose between different types of tasks: +* All +* Build Alarm Report +* Build View Report +* Load View Filter +* Refresh Cache +* Save Telemetry to TB +* Build Anomaly Model +* Find Anomalies +* Anomaly Autodiscovery +* Test Calculation +* Save Calculation Results to TB +* Train prediction model +* Save prediction model result to TB + +![image](https://img.thingsboard.io/trendz/tasks-types.png) + +### Selecting a Task + +Click on a task to view more details about its execution. You’ll see important information such as: +* *Time Started:* When the task started. +* *Duration:* How long the task has been running. +* *Time Finished:* When the task finished or is expected to finish. +* *Status:* The current state of the task (Created, Running, Finished, Failed, Canceled, Lost, None). + +### Managing Tasks + +Within the task details, you can also manage tasks by: +* *Start:* Manually start a task if it’s stopped. +* *Stop:* Stop a running task if needed. + +The Tasks section helps you easily monitor and control the execution of tasks, keeping your system running smoothly. From the task details, you can quickly go to the related entity for further management. + +![image](https://img.thingsboard.io/trendz/tasks-go-to-entity.png) + +## Executions Tab + +The Execution tab within the Tasks section provides a detailed view of all task executions. Here, you can track the progress and outcomes of each task in real-time. +The tab lists all executions, allowing you to filter them by their status: **All, Created, Running, Failed**. +For each execution, you can see details such as: **Time Started, Duration, Time Finished, Status.** +This tab is crucial for monitoring the performance and health of your tasks, enabling you to quickly identify and address any issues that arise during execution. + +![image](https://img.thingsboard.io/trendz/tasks-executions.png) + diff --git a/docs/trendz/test-calculated-fields.md b/docs/trendz/test-calculated-fields.md deleted file mode 100755 index e4f9d3630f..0000000000 --- a/docs/trendz/test-calculated-fields.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -layout: docwithnav-trendz -assignees: -- vparomskiy -title: Test calculated fields -description: Test calculated fields ---- - -* TOC -{:toc} - -The Calculate Tester is a tool that allows you to debug the code of the Calculate Fields. To open the Calculate Tester window, you need to click on the **Test** button in the Calculate field settings. - -![image](https://img.thingsboard.io/trendz/test-calculated-open.png) - -The layout is divided into four sections: - -* **Preview**: This section displays a visualization, just like in the non-tester mode. -* **Function**: This field serves as the input area for the Calculation Field code, just like in the non-tester mode. -* **Input**: Here you can view and modify the input data values. -* **Output**: The resulting output data after the calculation will be shown here, along with any logs if the "Function" field contains any console.log() statements. - -![image](https://img.thingsboard.io/trendz/test-calculated-details.png) - -#### Preview -This part is just a smaller copy of the main visualization. It is not dependent on test data; it is based solely on real data. -This means that changes to the telemetry value in the Input field will not affect it. Changes can only be seen if you change the Formula itself. -The Preview will be updated if you click on the "Build" or "Get real data" button. However, in the second case, if you have changed the input data, it will also be overwritten. - -#### Input -The input data helps you understand what data is involved in the calculation and gives you the opportunity to change it for tests. -The initial input data can be obtained or updated by clicking either the 'Test' or 'Get real data' button. -But we recommend that you first request real data, and then test it. So the list of input data will be more complete. Also, "Get real data" in some cases can give a more full list of logs when it comes to the "Row" object. - -Main fields - -* startTs - Start of time period - * type - number/unix format - * example - 1677621600000 -* endTs - End of time period - * type - number/unix format - * example - 1685566799999 -* groupBy - Grouping by time. The value is "null" when the visualization does not contain a RAW date field or calculate field is butch type. - * type - `"week" | "day", "hour" | "minute" | "null"` - * example - "week" -* row - An object where keys represent the names of the visualization fields for a single iteration. This can be visualized as one row in a table, but this object is also accessible for other chart types. However, it is not available for batch calculated fields. To refer to a specific row, use square brackets with the key name (row['key name']). - * type - `{[key]: string | number}` - * example - `{"CalculatedSUM": 100, "GR greenhouseUNIQ": "London", "consumptionWaterSUM": 2684}` -* telemetry - These are aggregated or raw values (depending on the type of Calculated Field), used in the formula. - * for simple fields - * type - `string | number` - * example - `"sum(GR water meter.consumptionWater)": 100` - * for batch fields - * type - `Array<{ts: number, value: number | string}>` - * example - `"none(GR water meter.consumptionWater)": [{"ts": 1677621600000, "value": 100 }, … ]` - -In the Input, you can change the values for the tests, but you cannot change the keys. - -Pressing **Get real data** again will overwrite the current changes. - - -#### Example for simple Calculated Field - -![image](https://img.thingsboard.io/trendz/test-calculated-simple-field.png) - -#### Example for batch Calculated Field - -![image](https://img.thingsboard.io/trendz/test-calculated-batch-field.png) - -#### Function -More details on how to write a function for the Calculated Field can be found in the corresponding section of the documentation. -This field is the same. It is only worth recalling that you can work with aggregated data or with raw data. In the second option, you need to enable the **batch** mode by activating the corresponding checkbox. - -#### Output -This is a non-editable field that has two modes: - -* **Output data**: you can see the calculation results. This is the value that the function returns at the end. For non-batch Calculate Fields, this will be a simple value (number or string), and for batch ones, it will be an array of objects similar to Input Data. - -![image](https://img.thingsboard.io/trendz/test-calculated-output.png) - -* **Logs**: logs are displayed, similar to those displayed in the browser console, if any console.log() is present in the "Formula" field. - -![image](https://img.thingsboard.io/trendz/test-calculated-logs.png) - - -Output data and logs updated after clicking the **Test** button. The logs are also updated when you click on **Get real data**, which sometimes makes it possible to make them more complete than the **Test** button. - -When you are satisfied with the calculation results, don't forget to click the **Save** button. Afterward, the new function will be available in the Calculate Field. - -## Next Steps - -{% assign currentGuide = "CalculatedFields" %}{% include templates/trndz-guides-banner.md %} \ No newline at end of file diff --git a/docs/trendz/widget-actions.md b/docs/trendz/widget-actions.md index 46f3b53383..040008a75c 100755 --- a/docs/trendz/widget-actions.md +++ b/docs/trendz/widget-actions.md @@ -8,9 +8,9 @@ description: Trendz widget actions --- * TOC - {:toc} +{:toc} -#### Configure OnRowClick action +## Configure OnRowClick action Trendz Table view support onRowClick action. You can configure what should happen when user click on a Row in a table. For example, you can save entity to the Dashboard state alias or open new dashboard state. @@ -28,12 +28,12 @@ If you want to use 'onRowClick' action - you need to define what item is selecte * Select required Device/Asset type in **Row click entity** dropdown. * Save changes. -#### Configure OnRowClick action for Anomaly +## Configure OnRowClick action for Anomaly If you use the Anomaly Table on your dashboard and want to create an action that not only sets the selected entity but also updates the time window, follow these straightforward steps: 1. **Configure Row Click Entity.** Head to the chart settings in Trendz and set the "Row click entity." -![image](https://img.thingsboard.io/trendz/row-click-anomaly.png) + ![image](https://img.thingsboard.io/trendz/row-click-anomaly.png) 2. **Create Row Click Action.** Go to the Actions tab in your Anomaly view settings on the dashboard and create a new action. Choose "On Row click" as the Action source and set the type to "Custom action." Then you have to add some custom code to define the chosen entity as the selected entity on your dashboard. Begin by obtaining the state ID and parameters for the new state entity. In our example, we used "selectedDevice," @@ -50,7 +50,7 @@ stateParams.selectedDevice = { widgetContext.dashboard.onUpdateTimewindow(additionalParams.startTs, additionalParams.endTs); widgetContext.stateController.updateState(stateId, stateParams); ``` -#### Configure Date selected action +## Configure Date selected action Trendz Calendar and Anomaly table support date-selected action, allowing you to dynamically update the timewindow of your ThingsBoard dashboard based on the selected date in either the calendar or the anomaly timerange. To enable the date-select event: @@ -66,6 +66,52 @@ widgetContext.dashboard.onUpdateTimewindow(additionalParams.startTs, additionalP [//]: # (#### Configure Switch Field action) +## Configure Row Click to Select Multiple Entities + +To implement the selection of multiple entities via row click in a Trendz view, follow these steps. For this example, we have a table displaying a list of buildings, each with a count of energy meters and aggregated energy consumption. +Our goal is to send a list of energy meters to an alias on the dashboard upon clicking a specific table row. + +![image](https://img.thingsboard.io/trendz/row-click-select-entities.png) + +**Step 1. Set Up the Trendz View** +1. Set the entity type of the entities that you want to send as the alias. In our case it is EM energy meter. + ![image](https://img.thingsboard.io/trendz/set-up-trendz-view.png) +2. Send this view to the ThingsBoard Dashboard. + +**Step 2. Create New Alias on the Dashboard** +1. Name the Alias (Remember the alias name for later reference). +2. Toggle on "Resolve as multiple entities". +3. Choose "Entity list" as Filter Type. +4. In the Entity Type field choose the type of entities selectable via row click. +5. Select default entities to be displayed initially. + +![image](https://img.thingsboard.io/trendz/create-new-alias.png) + +**Step 3. Configure the Action in Trendz View** +1. Select “On Row Click” as action source. +2. Provide a name for the action. +3. Select "Custom action" as Action Type. + + ![image](https://img.thingsboard.io/trendz/configure-action.png) +4. Write custom code to set ids to previously created alias: + +* Find the alias: +```javascript +let entityAlias = +Object.values(widgetContext.aliasController.entityAliases).find(el => el.alias +=== "Selected entities"); +``` + +* Trendz view will send additionalParams containing an array of entities. Transform this array to extract only entity IDs and assign this array of entity IDs to the entityList in your alias. +```javascript +if(entityAlias && additionalParams["entityIds"] && additionalParams["entityIds"].length) { + let devices = additionalParams["entityIds"].map(entity => entity.entityId.id); + entityAlias.filter.entityList = devices; + + widgetContext.updateAliases(); +} +``` + ## Next Steps -{% assign currentGuide = "EmbedVisualizations" %}{% include templates/trndz-guides-banner.md %} \ No newline at end of file +{% assign currentGuide = "EmbedVisualizations" %}{% include templates/trndz-guides-banner.md %} diff --git a/images/trendz/calculated-complex-config.png b/images/trendz/calculated-complex-config.png index 86ff903c28..bf6ecf1c2e 100644 Binary files a/images/trendz/calculated-complex-config.png and b/images/trendz/calculated-complex-config.png differ diff --git a/images/trendz/calculated-disabled-bell.png b/images/trendz/calculated-disabled-bell.png new file mode 100644 index 0000000000..1b43ef914c Binary files /dev/null and b/images/trendz/calculated-disabled-bell.png differ diff --git a/images/trendz/calculated-enable.png b/images/trendz/calculated-enable.png new file mode 100644 index 0000000000..00893d6123 Binary files /dev/null and b/images/trendz/calculated-enable.png differ diff --git a/images/trendz/calculated-field-create.png b/images/trendz/calculated-field-create.png new file mode 100644 index 0000000000..2fe0354303 Binary files /dev/null and b/images/trendz/calculated-field-create.png differ diff --git a/images/trendz/calculated-function-tab.png b/images/trendz/calculated-function-tab.png new file mode 100644 index 0000000000..2aa3b929d0 Binary files /dev/null and b/images/trendz/calculated-function-tab.png differ diff --git a/images/trendz/calculated-go-to-calculation.png b/images/trendz/calculated-go-to-calculation.png new file mode 100644 index 0000000000..360e9cab29 Binary files /dev/null and b/images/trendz/calculated-go-to-calculation.png differ diff --git a/images/trendz/calculated-input-tab.png b/images/trendz/calculated-input-tab.png new file mode 100644 index 0000000000..09adae1d38 Binary files /dev/null and b/images/trendz/calculated-input-tab.png differ diff --git a/images/trendz/calculated-output-tab.png b/images/trendz/calculated-output-tab.png new file mode 100644 index 0000000000..1962e1333e Binary files /dev/null and b/images/trendz/calculated-output-tab.png differ diff --git a/images/trendz/calculated-real-time.png b/images/trendz/calculated-real-time.png new file mode 100644 index 0000000000..8aca62027b Binary files /dev/null and b/images/trendz/calculated-real-time.png differ diff --git a/images/trendz/calculated-reprocess-task.png b/images/trendz/calculated-reprocess-task.png new file mode 100644 index 0000000000..1fcc2c8312 Binary files /dev/null and b/images/trendz/calculated-reprocess-task.png differ diff --git a/images/trendz/calculated-simple.png b/images/trendz/calculated-simple.png index 60b75d71ac..5ddb6aaee3 100644 Binary files a/images/trendz/calculated-simple.png and b/images/trendz/calculated-simple.png differ diff --git a/images/trendz/calculated-view-fields.png b/images/trendz/calculated-view-fields.png new file mode 100644 index 0000000000..74fb3dde2a Binary files /dev/null and b/images/trendz/calculated-view-fields.png differ diff --git a/images/trendz/configure-action-preview.png b/images/trendz/configure-action-preview.png new file mode 100644 index 0000000000..2007b044c2 Binary files /dev/null and b/images/trendz/configure-action-preview.png differ diff --git a/images/trendz/configure-action.png b/images/trendz/configure-action.png new file mode 100644 index 0000000000..2007b044c2 Binary files /dev/null and b/images/trendz/configure-action.png differ diff --git a/images/trendz/create-new-alias-preview.png b/images/trendz/create-new-alias-preview.png new file mode 100644 index 0000000000..cde8fe139b Binary files /dev/null and b/images/trendz/create-new-alias-preview.png differ diff --git a/images/trendz/create-new-alias.png b/images/trendz/create-new-alias.png new file mode 100644 index 0000000000..cde8fe139b Binary files /dev/null and b/images/trendz/create-new-alias.png differ diff --git a/images/trendz/enable-button.png b/images/trendz/enable-button.png new file mode 100644 index 0000000000..c38b8ce2c6 Binary files /dev/null and b/images/trendz/enable-button.png differ diff --git a/images/trendz/name-calculation-field.png b/images/trendz/name-calculation-field.png new file mode 100644 index 0000000000..0be8dac57e Binary files /dev/null and b/images/trendz/name-calculation-field.png differ diff --git a/images/trendz/row-click-select-entities-preview.png b/images/trendz/row-click-select-entities-preview.png new file mode 100644 index 0000000000..f8ea942c1a Binary files /dev/null and b/images/trendz/row-click-select-entities-preview.png differ diff --git a/images/trendz/row-click-select-entities.png b/images/trendz/row-click-select-entities.png new file mode 100644 index 0000000000..f8ea942c1a Binary files /dev/null and b/images/trendz/row-click-select-entities.png differ diff --git a/images/trendz/set-up-trendz-view-preview.png b/images/trendz/set-up-trendz-view-preview.png new file mode 100644 index 0000000000..e9fee822a3 Binary files /dev/null and b/images/trendz/set-up-trendz-view-preview.png differ diff --git a/images/trendz/set-up-trendz-view.png b/images/trendz/set-up-trendz-view.png new file mode 100644 index 0000000000..e9fee822a3 Binary files /dev/null and b/images/trendz/set-up-trendz-view.png differ diff --git a/images/trendz/tasks-executions.png b/images/trendz/tasks-executions.png new file mode 100644 index 0000000000..4685f7aed1 Binary files /dev/null and b/images/trendz/tasks-executions.png differ diff --git a/images/trendz/tasks-go-to-entity.png b/images/trendz/tasks-go-to-entity.png new file mode 100644 index 0000000000..bb80e12322 Binary files /dev/null and b/images/trendz/tasks-go-to-entity.png differ diff --git a/images/trendz/tasks-types.png b/images/trendz/tasks-types.png new file mode 100644 index 0000000000..49d106a580 Binary files /dev/null and b/images/trendz/tasks-types.png differ