EnergySys Measurement Connector
The Measurement Connector runs as a standalone service on a Windows machine and the UI is accessed via a web browser. Once logged in the Connector's various screens are navigated to via the menu on the left.
At the top of the screen the current time and time zone that the Measurement Connector is set to operate in is displayed. Please note that this is not necessarily the same as the current date or time zone your computer is running in.
Event Log Screen
The Event Log screen shows a record of any job executions and other system events, such as errors that have occurred while the system was running (events older than 30 days will be automatically deleted).
Entries are colour coded Red/Green/Amber to help visualise the system status. Each entry has the following information:
| Screen column | Description |
| Description | the name of the Job or Event |
| Result | the result of the event (Success/Failure/Warning/Exception) |
| Summary | a brief description of the event |
| Run Timestamp | when the event occurred |
| Duration | how long the event took |
Selecting a row will show a popup with more information of the event (job execution results, error message, etc). The pagination controls at the top and bottom of the table can be used to view previous Events or show more Events per page.
Base Queries
The Base Queries screen shows all defined Base Queries available and allows for editing, creating or deleting.
Base Query Fields:
| Screen column | Description |
| Name | the Display Name of the Base Query when shown in the Scheduled Job screens |
| Query Text | the SQL of the query to use when running the Query. The Query Text can contain parameters (see below), the values of which can be set when creating the Query or automatically set when running a Job. Carriage returns are acceptable in the Query Text |
Query Text Parameters:
| Type | Syntax | Notes |
| Integer | $I{param_name} | Parameter of type Integer will be available to be set in the Query screen under the entered “param_name” |
| Float | $F{param_name} | Parameter of type Float will be available to be set in the Query screen under the entered “param_name” |
| String | $S{param_name} | Parameter of type String will be available to be set in the Query screen under the entered “param_name” |
| Date | $D{param_name} | Parameter of type Date/Time will be available to be set in the Query screen under the entered “param_name”. UNLESS the param_name is set to “today”, “yesterday”, “now” or “last_executed_date_time” in which case the value will be automatically injected when the Query is run in a Job or previewed |
Editing, creating or deleting:
| Controls | Description |
| Edit a Base Query (pencil icon) | click on the pencil icon in the right-hand column of the one you wish to edit, this will make the row editable |
| Add a Base Query (link) | click the link underneath the main Base Queriers table, this will add a new editable row with all fields blank |
| Delete a Base Query (trash can icon) | click the Trash Can icon in the right-hand column of the one you wish to delete. You will then be prompted to confirm your action. If a Base Query is being used by a Query then it will not be possible to delete it and all the queries using the Base Query will have to be deleted first |
Selecting a Base Query from the Base Queries table will show all the Parameters in the Base Query in the Parameters table.
Queries
The Queries screen shows all defined Queries currently defined and their Parameter values. It allows for the editing, creating, deleting and previewing of Queries and also editing of the Parameter values.
The Query fields:
| Screen column | Description |
| Name | the Display Name of the Query when shown in the Scheduled job screens |
| Base Query | the Base Query to use for the Query. The list is auto populated from the Base Queries available |
Selecting a Query from the Queries table will show all the Parameters in the Base Query and the set values for that Query in the Parameters table.
| Controls | Description |
| Edit a Query (pencil icon) | click on the pencil icon in the right-hand column of the row you wish to edit, this will make the row editable |
| Add a Query (link) | click the link underneath the main Queries table, this will add a new editable row with all fields blank or set to default values in the case of drop down lists |
| Delete a Query (trash can icon) | Trash Can icon in the right-hand column of the one you wish to delete. You will then be prompted to confirm your action |
Parameters
The parameters are variables that would like the query to be run with.
To edit a Parameter:
- select the Query in the Queries table, this will show all current parameters and their values in the Parameters table
- click the Pencil icon in the right-hand column, the Value of the parameter will become editable with a free text field for entering the value.
- Use the Calendar picker or manually enter the date (dd/MM/yyyy HH:MM:SS format).
Query Validation Status
The first column to the right of the Base Query column shows the Validation Status of the Queries Parameters.
- If the column contains a "tick" then all the parameters are present and have valid values set.
- If the column contains an "exclamation mark" then there are validation errors in the Parameter values (missing or out of date Parameters). Clicking the "exclamation mark" will show pop-ups detailing which parameters have failed validation and why.
- If a Query is edited and the Base Query is changed or edited and the Parameters change, then it is possible that the Parameter values may become out of date. If this is the case, the Query Validation Status will show as an "exclamation mark" and contain the validation errors.
- If the Parameters become out of date, select the Query and click the "Refresh Parameters" link at the bottom of the Parameters table. This will remove any invalid parameters and add any missing parameters. Parameters that are still valid will retain their values.
Previewing a Query
Any users can preview the execution of a Query. This will retrieve data from the database and create a spreadsheet of the results for downloading to the local file system.
To preview a Query, select the Download icon in the right-hand column. This will show a file selection pop-up to choose the location you wish to download the spreadsheet to.
Scheduled Jobs
The Scheduled Jobs screen shows the current list of Queries that are scheduled to run automatically.
A Scheduled Job will retrieve readings from the Database system using its Query, generate a spreadsheet of the results and submit the file to the EnergySys System for processing.
The Scheduled Jobs screen allows the editing, creating, suspending and manual execution of these scheduled Queries.
Scheduled Job Fields:
| Screen column | Description |
| Name | the name of the Job or Event |
| Query | the Query to execute will be auto populated with the Names from the Query screen |
| Start Date | the date and time from which this job will start running. Can be a calendar picker or free text (dd/MM/yyyy HH:MM). Jobs will not execute until the start date is reached. The first runtime will be calculated based on the value on the "Start Date" and the "Repeat Every" fields. If left blank then the "Start Date" is assumed to be the current time |
| End Date (Optional) | the date and time from when this job will stop running. Can be a calendar picker or free text (dd/MM/yyyy HH:MM). If left blank then the job will run indefinitely |
| >Repeat Every | the repeat schedule of the job. Can be free text number field and a drop down of Minutes/Hours/Days/Weeks/Months. With the "Start Date" this will determine when the job runs. Note that Daylight Savings will not affect the run time of a job |
| Is Active | a tick box determining if the job is active. If active then the job will be scheduled to run automatically at the next calculated time. If the job is not active the job will not run automatically |
Editing, creating, suspending and manual execution of these scheduled Queries
| Screen column | Description |
| Edit a Scheduled Job (pencil icon) | the name of the job when it is executed and appears in the Event Log screen |
| Add a Scheduled Job (link) | select the link underneath the main Scheduled Jobs table, this will add a new row with blank fields or default values set in the case of drop down lists |
| Delete a Scheduled Job (trash can icon) | select the Trash Can icon in the right-hand column. Only users with Admin or Configurator roles can delete Scheduled Jobs |
| Manually run a Scheduled Job | select the Play icon in the right-hand column. A small popup showing if the job was executed successfully will be shown and an entry added to the Event Log screen. Manually running a Scheduled Job does not affect the scheduled and job will continue to run at their scheduled tim |
If a Scheduled Job was not run for any reason it can be manually re-ran. To manually rerun a job, select the Fast Forward icon in the right-hand column. A popup dialog will be shown asking for a From and To date/time for which you wish to re-run the job for. Selecting the OK button will rerun the job for any time it was scheduled to run between the two entered date/times. Only From and To date/times that fall between the Start and End date of the Selected Job will be accepted.
Rerun Jobs will run as if they were running at the time they were originally scheduled to run. Any From and To dates in the Tag Query that were set to "Today", "Yesterday", etc. will be set to the correct dates for when it was scheduled. A popup showing if the rerun was successfully requested will be shown and an entry will be added to the Event Log screen for the request. The rerun jobs will run in the background and an entry will be added to the Event Log screen for each job.
When a job runs an entry will be added to the Event Log screen detailing the result of the job.
System Restarts
If the Connector is restarted, then the next run time of all Scheduled Jobs are recalculated. Any jobs that were scheduled to run while the Connector was stopped will be missed and not run until the following scheduled time. Any critical jobs should be ran manually after the Connector starts back up.