Available Functions | Proficy Historian 2024 Documentation

Function Type	Function	Description	Example
Add Data	`Historian.AddData(tags, values,times)`	Write data to a tag in the Historian archive.	`Result=Historian.AddData ('Python_Sample_Calculation',0,'2023-12-13T15:13:44.536Z',100)`
Check Data Quality	`Historian.CurrentQuality('tag name')`	The current quality of the tag (0 for bad quality and 100 for good quality).	`Result=Historian.CurrentQuality('Tag')`
Check Data Quality	`Historian.InterpolatedQuality('tag name','time')`	The current quality of the interpolated tag.	`Result=Historian.InterpolatedQuality('Tag1','2023-12-13T16:32:03.626Z')`
Check Data Quality	`Historian.NextGoodQuality('tag name', 'time')`	The good quality of the raw sample after the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextGoodQuality('Tag1','2023-12-13T16:34:19.154Z')`
Check Data Quality	`Historian.NextQuality('tag name','time')`	The quality of the tag (0 for bad quality and 100 for good quality) after the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextQuality('Tag2','2023-12-13T16:35:41.709Z')`
Check Data Quality	`Historian.PreviousGoodQuality('tag name','time')`	The good quality of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.PreviousGoodQuality('Tag3','2023-12-13T16:36:47.736Z')`
Check Data Quality	`Historian.PreviousQuality('tag name','time')`	The quality of the tag (0 for bad quality and 100 for good quality) prior to the time specified. Time is provided as string in standard ISO 8601 format.	`datetime_str = Historian.CurrentTime() datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f') Result=Historian.PreviousQuality('Test_Sim.Simulation00001',datetime_object.isoformat())`
Insert A Calculation- Non-filtered Calculation	`Historian.Calculation('tag name', 'CalculationMode', 'StartTime', 'EndTime')`	Unfiltered calculated data query that returns a single value, similar to the Excel Add-In feature. For a list of the calculation mode, refer to calculation modes. All times are provided as string in standard ISO 8601 format.	`from datetime import datetime, timedelta datetime_str = Historian.CurrentTime() endTime = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f') startTime = endTime - timedelta(hours=0,minutes=0,seconds=10) Result=Historian.Calculation('Test_Sim.Simulation00002','Average', startTime.isoformat(), endTime.isoformat())`
Insert A Calculation- Filtered	`Historian. CalculationFilter('tag name', 'CalculationMode', 'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison', 'FilterValue')`	Filtered calculated data query that returns a single value, similar to the Excel Add-In feature. All times are provided as string in standard ISO 8601 format.	`from datetime import datetime, timedelta datetime_str = Historian.CurrentTime() endTime = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f') startTime = endTime - timedelta(hours=0, minutes=0,seconds=1) Result=Historian.CalculationFilter('Test_Sim.Simulation00004','Average', startTime.isoformat(), endTime.isoformat(),'Test_Sim.Simulation00006','AfterTime','GreaterThan','100')`
Insert A Calculation Quality- Non-filtered Calculation	`Historian.CalculationQuality('tag name', 'CalculationMode', 'StartTime', 'EndTime')`	Unfiltered calculated data query that returns the quality of resulting value. For a list of the calculation mode, refer to calculation modes. All times are provided as string in standard ISO 8601 format.	`Result=Historian.CalculationQuality('Python_2','Average','2023-12-13T16:54:27.296Z','2023-12-13T16:54:28.296Z')`
Insert A Calculation Quality- Filtered Calculation	`Historian.CalculationFilterQuality('tag name', 'CalculationMode', 'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison', 'FilterValue')`	Filtered calculated data query that returns the quality of value. All times are provided as string in standard ISO 8601 format.	`Result=Historian.CalculationFilterQuality('Tag','Average','2023-12-13T16:56:08.123Z','2023-12-13T16:56:09.123Z','Tag','AfterTime','Equal','')`
Insert A Tagname	`'Tag'`	The selected tag name.	`Result='Python_3_tag'`
Insert A Timestamp	`Historian.CurrentTime()`	The calculation execution time, which becomes the timestamp of the stored value. The result is returned as a string. For real-time processing of polled tags, the calculation execution time is the time when the calculation is triggered. For unsolicited tags, the calculation execution time is the timestamp delivered with the subscription. Note: When a calculation is performed, the timestamp of the result is the time that the calculation has begun, not the time that it completed. For recovery of polled or unsolicited tags, the calculation execution time is the time when the calculation would have been performed if the collector were running.	`The result is returned as a string. Format of timestamp is: "%m/%d/%y %H:%M:%S.%f" Example: “04/11/23 22:09:40.000” #Example to convert string timestamp to Python datetime object: from datetime import datetime datetime_str = Historian.CurrentTime() datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')`
Insert A Timestamp	`Historian.NextGoodTime(‘tag name’, ‘time’)`	The timestamp of the good raw sample after the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextGoodTime('Tag',2023-12-13T17:54:44.223Z)`
Insert A Timestamp	`Historian.NextTime(‘tag name’, ‘time’)`	The timestamp of the raw sample after the timestamp. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextTime('Tag','2023-12-13T17:56:21.726Z')`
Insert A Timestamp	`Historian.PreviousGoodTime(‘tag name’, ‘time’)`	The timestamp of the latest good quality of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.PreviousGoodTime('Tag','2023-12-13T17:57:45.308Z')`
Insert A Timestamp	`Historian.PreviousTime(‘tag name’, ‘time’)`	The timestamp of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.PreviousTime('Test_Sim.Simulation00001','2023-03-27T16:02:08.070557')`
Insert A Timestamp	`'time shortcut'`	The timestamp.value as a string format, in ISO 8601 format.	`Result='2023-12-13T18:00:38.186Z'`
Insert A Value	`Historian.CurrentValue(‘tag name’)`	The value of the tag, interpolated to the calculation execution time. The `CurrentValue` function returns 0 if the quality is 0 (bad quality). This occurs if you initialized it to 0, or if a previous call failed.	`Result=Historian.CurrentValue('Test_Sim.Simulation00001')`
Insert A Value	`Historian.InterpolatedValue(‘tag name’, ‘time’)`	The tag value, interpolated to the time that you enter. Time is provided as string in standard ISO 8601 format.	`Result=Historian.InterpolatedValue('Tag', '2023-12-13T18:05:29.367Z')'`
Insert A Value	`Historian.NextGoodValue(‘tag name’, ‘time’)`	The value of the good raw sample after the time. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextGoodValue('Tag', '2023-12-13T18:06:41.622Z')`
Insert A Value	`Historian.NextValue(‘tag name’, ‘time’)`	The value of the raw sample after the timestamp. Time is provided as string in standard ISO 8601 format.	`Result=Historian.NextValue('Tag', '2023-12-13T18:07:44.369Z')`
Insert A Value	`Historian.PreviousGoodValue(‘tag name’, ‘time’)`	The latest good value of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.	`from datetime import datetime, timedelta from time import time # Getting today's date and time todays_Date = datetime.now() # subtract 1 minute from current time timeToQuery = todays_Date - timedelta(hours=0,minutes=1,seconds=0) Result=Historian.PreviousGoodValue('Test_Sim.Simulation00001',timeToQuery.isoformat())`
Insert A Value	`Historian.PreviousValue(‘tag name’, ‘time’)`	The tag value of the raw sample prior to the time specified. Time is provided as string in standard ISO 8601 format.	`datetime_str = Historian.CurrentTime() datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f') Result=Historian.PreviousValue('Test_Sim.Simulation00001',datetime_object.isoformat())`
Insert An Advanced Calculation- Non-filtered Calculation	`Historian.AdvancedCalculation('Tagname', 'CalculationMode', ‘CriteriaString’ 'StartTime', 'EndTime')`	Unfiltered calculated data query with criteria string that returns a single value. All times are provided as string in standard ISO 8601 format.	`Result=Historian.AdvancedCalculation('Tag','Average','','2023-12-13T18:15:22.189Z','2023-12-13T17:15:23.189Z')`
Insert An Advanced Calculation- Filtered Calculation	`Historian.AdvancedCalculationFilter ('Tagname', 'CalculationMode', ‘CriteriaString’, 'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison', 'FilterValue')`	Filtered calculated data query with criteria string that returns a single value. All times are provided as string in standard ISO 8601 format.	`Result=Historian.AdvancedCalculationFilter('Tag','Average','','2023-12-13T18:16:29.333Z','2023-12-13T18:16:30.333Z','Tag','AfterTime','Equal','')`
Insert An Advanced Calculation Quality- Non-filtered Calculation	`Historian.AdvancedCalculationQuality('Tagname', 'CalculationMode', ‘CriteriaString’ 'StartTime', 'EndTime')`	Unfiltered calculated data query with criteria string that returns the quality of value. All times are provided as string in standard ISO 8601 format.	`Result=Historian.AdvancedCalculationQuality('Tag','Average','','2023-12-13T18:18:32.238Z','2023-12-13T18:18:33.238Z')`
Insert An Advanced Calculation Quality- Filtered Calculation	`Historian.AdvancedCalculationFilterQuality ('Tagname', 'CalculationMode', ‘CriteriaString’, 'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison', 'FilterValue')`	Filtered calculated data query with criteria string that returns the quality of value. All times are provided as string in standard ISO 8601 format.	`Result=Historian.AdvancedCalculationFilterQuality('Tag','Average','','2023-12-13T18:20:19.954Z','2023-12-13T18:20:20.954Z','Tag','AfterTime','Equal','')`
NA	`Historian.LogMessage(string_message)`	Allows you to write messages to the collector log file for debugging purposes. The collector log files are located in the `Proficy Historian Data\LogFiles\LogFiles` folder.	`Result=Historian.LogMessage(test_message)`

Add Data

Historian.AddData(tags, values,times)

Write data to a tag in the Historian archive.

Result=Historian.AddData
                        ('Python_Sample_Calculation',0,'2023-12-13T15:13:44.536Z',100)

Check Data Quality

Historian.CurrentQuality('tag name')

The current quality of the tag (0 for bad quality and 100 for good quality).

Result=Historian.CurrentQuality('Tag')

Check Data Quality

Historian.InterpolatedQuality('tag
                     name','time')

The current quality of the interpolated tag.

Result=Historian.InterpolatedQuality('Tag1','2023-12-13T16:32:03.626Z')

Check Data Quality

Historian.NextGoodQuality('tag name', 'time')

The good quality of the raw sample after the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextGoodQuality('Tag1','2023-12-13T16:34:19.154Z')

Check Data Quality

Historian.NextQuality('tag name','time')

The quality of the tag (0 for bad quality and 100 for good quality) after the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextQuality('Tag2','2023-12-13T16:35:41.709Z')

Check Data Quality

Historian.PreviousGoodQuality('tag
                     name','time')

The good quality of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.PreviousGoodQuality('Tag3','2023-12-13T16:36:47.736Z')

Check Data Quality

Historian.PreviousQuality('tag name','time')

The quality of the tag (0 for bad quality and 100 for good quality) prior to the time specified. Time is provided as string in standard ISO 8601 format.

datetime_str = Historian.CurrentTime()
datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')
Result=Historian.PreviousQuality('Test_Sim.Simulation00001',datetime_object.isoformat())

Insert A Calculation- Non-filtered Calculation

Historian.Calculation('tag name', 'CalculationMode', 'StartTime',
                        'EndTime')

Unfiltered calculated data query that returns a single value, similar to the Excel Add-In feature. For a list of the calculation mode, refer to calculation modes. All times are provided as string in standard ISO 8601 format.

from datetime import datetime, timedelta
datetime_str = Historian.CurrentTime()
endTime = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')
startTime = endTime - timedelta(hours=0,minutes=0,seconds=10)
Result=Historian.Calculation('Test_Sim.Simulation00002','Average', startTime.isoformat(), endTime.isoformat())

Insert A Calculation- Filtered

Historian. CalculationFilter('tag name', 'CalculationMode',
                        'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison',
                        'FilterValue')

Filtered calculated data query that returns a single value, similar to the Excel Add-In feature. All times are provided as string in standard ISO 8601 format.

from datetime import datetime, timedelta
datetime_str = Historian.CurrentTime()
endTime = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')
startTime = endTime - timedelta(hours=0, minutes=0,seconds=1)
Result=Historian.CalculationFilter('Test_Sim.Simulation00004','Average', startTime.isoformat(), endTime.isoformat(),'Test_Sim.Simulation00006','AfterTime','GreaterThan','100')

Insert A Calculation Quality- Non-filtered Calculation

Historian.CalculationQuality('tag name', 'CalculationMode',
                        'StartTime', 'EndTime')

Unfiltered calculated data query that returns the quality of resulting value. For a list of the calculation mode, refer to calculation modes. All times are provided as string in standard ISO 8601 format.

Result=Historian.CalculationQuality('Python_2','Average','2023-12-13T16:54:27.296Z','2023-12-13T16:54:28.296Z')

Insert A Calculation Quality- Filtered Calculation

Historian.CalculationFilterQuality('tag name', 'CalculationMode',
                        'StartTime', 'EndTime', 'FilterTagname', 'FilterMode', 'FilterComparison',
                        'FilterValue')

Filtered calculated data query that returns the quality of value. All times are provided as string in standard ISO 8601 format.

Result=Historian.CalculationFilterQuality('Tag','Average','2023-12-13T16:56:08.123Z','2023-12-13T16:56:09.123Z','Tag','AfterTime','Equal','')

Insert A Tagname

'Tag'

The selected tag name.

Result='Python_3_tag'

Insert A Timestamp

Historian.CurrentTime()

The calculation execution time, which becomes the timestamp of the stored value. The result is returned as a string.

For real-time processing of polled tags, the calculation execution time is the time when the calculation is triggered. For unsolicited tags, the calculation execution time is the timestamp delivered with the subscription.

Note: When a calculation is performed, the timestamp of the result is the time that the calculation has begun, not the time that it completed.

For recovery of polled or unsolicited tags, the calculation execution time is the time when the calculation would have been performed if the collector were running.

The result is returned as a string. 
Format of timestamp is: "%m/%d/%y %H:%M:%S.%f"
Example: “04/11/23 22:09:40.000”

#Example to convert string timestamp to Python datetime object:

from datetime import datetime
datetime_str = Historian.CurrentTime()
datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')

Insert A Timestamp

Historian.NextGoodTime(‘tag name’,
                        ‘time’)

The timestamp of the good raw sample after the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextGoodTime('Tag',2023-12-13T17:54:44.223Z)

Insert A Timestamp

Historian.NextTime(‘tag name’, ‘time’)

The timestamp of the raw sample after the timestamp. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextTime('Tag','2023-12-13T17:56:21.726Z')

Insert A Timestamp

Historian.PreviousGoodTime(‘tag name’, ‘time’)

The timestamp of the latest good quality of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.PreviousGoodTime('Tag','2023-12-13T17:57:45.308Z')

Insert A Timestamp

Historian.PreviousTime(‘tag name’, ‘time’)

The timestamp of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.PreviousTime('Test_Sim.Simulation00001','2023-03-27T16:02:08.070557')

Insert A Timestamp

'time shortcut'

The timestamp.value as a string format, in ISO 8601 format.

Result='2023-12-13T18:00:38.186Z'

Insert A Value

Historian.CurrentValue(‘tag name’)

The value of the tag, interpolated to the calculation execution time. The CurrentValue function returns 0 if the quality is 0 (bad quality). This occurs if you initialized it to 0, or if a previous call failed.

Result=Historian.CurrentValue('Test_Sim.Simulation00001')

Insert A Value

Historian.InterpolatedValue(‘tag name’,
                     ‘time’)

The tag value, interpolated to the time that you enter. Time is provided as string in standard ISO 8601 format.

Result=Historian.InterpolatedValue('Tag',
                        '2023-12-13T18:05:29.367Z')'

Insert A Value

Historian.NextGoodValue(‘tag name’, ‘time’)

The value of the good raw sample after the time. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextGoodValue('Tag',
                        '2023-12-13T18:06:41.622Z')

Insert A Value

Historian.NextValue(‘tag name’, ‘time’)

The value of the raw sample after the timestamp. Time is provided as string in standard ISO 8601 format.

Result=Historian.NextValue('Tag',
                        '2023-12-13T18:07:44.369Z')

Insert A Value

Historian.PreviousGoodValue(‘tag name’,
                     ‘time’)

The latest good value of the raw sample prior to the time. Time is provided as string in standard ISO 8601 format.

from datetime import datetime, timedelta
from time import time

 # Getting today's date and time
todays_Date = datetime.now()

# subtract 1 minute from current time
timeToQuery = todays_Date - timedelta(hours=0,minutes=1,seconds=0)
 Result=Historian.PreviousGoodValue('Test_Sim.Simulation00001',timeToQuery.isoformat())

Insert A Value

Historian.PreviousValue(‘tag name’, ‘time’)

The tag value of the raw sample prior to the time specified.

Time is provided as string in standard ISO 8601 format.

datetime_str = Historian.CurrentTime()
datetime_object = datetime.strptime(datetime_str, '%m/%d/%y %H:%M:%S.%f')
Result=Historian.PreviousValue('Test_Sim.Simulation00001',datetime_object.isoformat())

Insert An Advanced Calculation- Non-filtered Calculation

Historian.AdvancedCalculation('Tagname', 'CalculationMode',
                        ‘CriteriaString’ 'StartTime', 'EndTime')

Unfiltered calculated data query with criteria string that returns a single value. All times are provided as string in standard ISO 8601 format.

Result=Historian.AdvancedCalculation('Tag','Average','','2023-12-13T18:15:22.189Z','2023-12-13T17:15:23.189Z')

Insert An Advanced Calculation- Filtered Calculation

Historian.AdvancedCalculationFilter ('Tagname',
                        'CalculationMode', ‘CriteriaString’, 'StartTime', 'EndTime',
                        'FilterTagname', 'FilterMode', 'FilterComparison',
                     'FilterValue')

Filtered calculated data query with criteria string that returns a single value. All times are provided as string in standard ISO 8601 format.

Result=Historian.AdvancedCalculationFilter('Tag','Average','','2023-12-13T18:16:29.333Z','2023-12-13T18:16:30.333Z','Tag','AfterTime','Equal','')

Insert An Advanced Calculation Quality- Non-filtered Calculation

Historian.AdvancedCalculationQuality('Tagname',
                        'CalculationMode', ‘CriteriaString’ 'StartTime',
                     'EndTime')

Unfiltered calculated data query with criteria string that returns the quality of value. All times are provided as string in standard ISO 8601 format.

Result=Historian.AdvancedCalculationQuality('Tag','Average','','2023-12-13T18:18:32.238Z','2023-12-13T18:18:33.238Z')

Insert An Advanced Calculation Quality- Filtered Calculation

Historian.AdvancedCalculationFilterQuality ('Tagname',
                        'CalculationMode', ‘CriteriaString’, 'StartTime', 'EndTime',
                        'FilterTagname', 'FilterMode', 'FilterComparison',
                     'FilterValue')

Filtered calculated data query with criteria string that returns the quality of value. All times are provided as string in standard ISO 8601 format.

Result=Historian.AdvancedCalculationFilterQuality('Tag','Average','','2023-12-13T18:20:19.954Z','2023-12-13T18:20:20.954Z','Tag','AfterTime','Equal','')

NA

Historian.LogMessage(string_message)

Allows you to write messages to the collector log file for debugging purposes. The collector log files are located in the

Proficy Historian
        Data\LogFiles\LogFiles

folder.

Result=Historian.LogMessage(test_message)