Smart Bots expression reference

An expression in a bot is specified using a C# lambda expression – a function taking the current bot agent context as an input and returning the value to store in memory. Note that a custom C# script can be used in the Value expression property. This allows a user to easily and flexibly define a value to save in memory depending on the current bot context.

This section describes the methods and properties available to a user in the expression, except the existing base .Net framework types. Please refer Microsoft help for more information about the .Net framework base types.

The operation Save to Memory puts a result of the given expression in the bot agent’s memory. The operation Write to Worksheet also accepts the expressions.

Bot context

The current Bot Agent context.

Access expression sample		x => x
Properties
Name		Type	Description
BotName		String	Name of the current Smart Bot
Chat		Chat	Current chat object
LastMessage		InstantMessage	Last message object in the current chat
Methods
Name	Arguments	Type	Description
Variable	-	bool, double, string	Returns the real-time value of the given variable. Object of type bool is returned for bit variables. Object of type double is returned for register variables. Object of type string is returned for text variables
	variableName	String	Full name of the variable e.g., Branch.Bit01 The variable name is prefixed with the current bot’s branch unless the @ symbol is used.
HistoricalAt	-	HisDataPoint	Returns the information about the variable at the given date and time from the specified archive unit.
	variableName	String	Full name of the variable, e.g., Branch.Bit01. The variable name is prefixed with the current bot’s branch unless the @ symbol is used.
	unitName	String	Name of the archive unit where the variable information will be searched. Smart bots can receive data from any supported archive unit type.
	Date	DateTime	Date and time at which the variable information will be searched.
Historical	-	HisDataCollection	Returns a collection of the variable data points at the specified time range from the given archive unit.
	variableName	String	Full name of the variable, e.g. Branch.Bit01. The variable name is prefixed with the current bot’s branch unless the @ symbol is used.
	unitName	String	Name of the archive unit where the variable information will be searched. Smart bots can receive data from any supported archive unit type.
	range	DateRange	DateTime range defined either by start and end dates or by a number of specified intervals before the real-time variable value. e.g. use number = 5 and interval = Intervals.Seconds to get information about the variable during last 5 seconds.

Chat

Information about the current chat.

Access expression sample	x => x.Chat
Properties
Name	Type	Description
ChatId	String	Surrogate Identifier of the chat room.
ChatName	String	Displayed Identifier of the chat room. Can be used in SCADA Basic scripting.
Description	String	Displayed Title of the chat room.
ColorString	String	HEX code of the color assigned to a chat.
ChatAccess	List<ChatAccess>	Accessibility of the chat room. All usual properties and methods of generic lists can be applied.
StorageTimeOfMessage	Int	Maximum time an old message can remain in the chat, in minutes, null for infinite.

ChatAccess

Accessibility of the given participant in the chat room.

Access expression sample	x => x.Chat.ChatAccess[0]
Properties
Name	Type	Description
UserId	String	Unique identifier of the first participant in the chat room.
ChatId	String	Surrogate Identifier of the chat room.
CreationDate	DateTime	Entry date of the second participant in the chat room.
Access	Int	Access level of the second participant in the chat room.

InstantMessage

Information about a chat message.

Access expression sample	x => x.LastMessage
Properties
Name	Type	Description
MessageId	System.Guid	Unique identifier of the message.
DeviceId	String	Unique identifier of the device/station used to send the message.
DeviceDisplayName	String	Displayed name of the device/station used to send the message.
ZoneId	String	Sender’s location when the message was sent.
Sender	String	User name of the message sender.
DateOffset	DateTimeOffset	Local timestamp of the message.
Date	DateTime	UTC timestamp of the message.
Type	String	Type of the message.
Text	String	Content of the text messages or file name for attachments.
TotalBytes	Long	Size of the message attachments in bytes.
Extra	XElement	Extensions of the message, such as auto-response options. XML.
FilePath	String	The full path of the attachment file. The specific path for attachments stored in the database as binary blocks. You can configure the location and format under which the IM server stores message attachments by modifying the following setting in the file svInstantMessagingHost.exe.config located in the Bin folder: StoreFilesInDatabase - Indicates where to store the message attachments. This setting allows you to configure the IM server so as to store all message attachments as binary blocks in the database, instead of storing them as files.

HisDataPoint

Information about the specified variable at a given date and time

Access expression sample	x => x.HistoricalAt(“Branch.Register01”, “Unit01”, System.DateTime.Now.AddSeconds(-5))
Properties
Name	Type	Description
Value	Double	Value of the variable at the given time.
Quality	Uint	Quality of the variable value at the given time.
IsGood	Bool	Returns true if the Quality is good, otherwise returns false.
Timestamp	DateTime	Time-stamp of the variable data point.

DateRange

Range defined either by start and end dates or by a number of specified intervals before the real-time variable value.

Access expression sample	new DateRange (DateTime start, DateTime end) or new DateRange (double number, Intervals interval)
Properties
Name	Type	Description
Start	DateTime	Beginning of the date time range.
End	DateTime	Ending of the date time range.

HisDataCollection

A collection of the variable data points at the specified time range from the given archive Unit

Access expression sample		x => x.Historical(“Branch .Register01”, “Unit01”, new DateRange(10, Intervals.Seconds))
Properties
Name		Type	Description
Range		DateRange	Requested date and time range
Variable		String	Full name of the variable e.g. Branch.Bit01. The variable name is prefixed with the current bot’s branch unless the “@” symbol is used.
Unit		String	Name of the archive unit where the variable information will be searched. Smart bots can receive data from any supported archiving unit type.
Methods
Name	Arguments	Type	Description
Padding	-	PaddedHisDataCollection	Returns a collection of the variable data points at the specified time range from the given archive Unit using the given padding: i.e. data is spread over the specified time range with one data point every padding interval.
	Double	Number	Number of specified intervals. e.g. use number = 5 and interval = Intervals.Seconds in order to get information about the variable for every 5 seconds.
	Intervals	Interval	Scale of the time intervals used for padding. e.g. use number = 5 and interval = Intervals.Minutes in order to get the information about the variable for every 5 minutes. Allowed enumeration values. Seconds, Minutes, Hours, Days, Weeks, Months, Years
ExcludeNS	-	IEnumerable of HisDataPoint	Returns a collection of the variable data points only with good quality.

PaddedHisDataCollection

A collection of the variable data points at the specified time range from the given archive unit spread over the range with the given padding (e.g. 1 data point every second).

Access expression sample		x => x.Historical(“Branch .Register01”, “Unit01”, new DateRange(10, Intervals.Seconds)).Padding(1, Intervals.Seconds) x => x.Historical(“Branch .Register01”, “Unit01”, new DateRange(10, Intervals.Seconds)).Padding(1, Intervals.Seconds).Filter(“Bit01”)
Properties
Name		Type	Description
Variable		String	Full name of the variable e.g. Branch.Bit01 The variable name is prefixed with the current bot’s branch unless the @ symbol is used.
Unit		String	Name of the archive unit where the variable information will be searched. Smart bots can receive data from any supported archiving unit type.
Number		Double	Number of specified intervals used for padding. e.g. use number = 5 and interval = Intervals.Seconds in order to get information about the variable for every 5 seconds.
Interval		Intervals	Scale of the time intervals used for padding. e.g. use number = 5 and interval = Intervals.Minutes in order to get the information about the variable for every 5 minutes. Allowed enumeration values. Seconds, Minutes, Hours, Days, Weeks, Months, Years
Methods
Name	Arguments	Type	Description
Filter	-	PaddedHisDataCollection	Returns a collection of the variable data points at the specified time range from the given archive unit using the given padding, where the specified filter variable was true (like a machine status signal).
	String	bitVariable	Full name of the bit variable used to filter the received data set by using an additional filter variable check. Returns only those data points when the specified filter variable was true (like a machine status signal).
ExcludeNS	-	PaddedHisDataCollection	Returns a collection of the variable data points only with good quality at the specified time range from the given archive unit using the given padding.

EventItemOccurence

Information about the occurrence of the event.

Access expression sample	x => x.Context (in case where the smart bot is started by the event as its Entry or Exit action)
Properties
Name	Type	Description
PeriodStart	DateTimeOffset	Beginning of the event occurrence.
PeriodEnd	DateTimeOffset	Ending of the event occurrence.
CalendarName	String	Name of the schedule with corresponding event.
Duration	TimeSpan	Duration of the event occurrence.
Event	EventItem	Corresponding event object.

EventItem

Information about the event.

Access expression sample	x => x.Context.Event (in case where the smart bot is started by the event as its Entry or Exit action)
Properties
Name	Type	Description
Id	String	Unique id of the event.
Name	String	Summary of the event.
Description	String	Event body.
s	String	Branch name assigned to the executed smart bot as entry or exit action. Branch name applied to all SCADA variables in bot’s operation and conditions.
BotUri	String	Path to the smart bot blueprint file. The specified path is relative to the following directory: <projectFolder>\MsgData\Bots.
BotName	String	Name of the bot, which can be referenced in the InviteUserToChat and RemoveUserFromChat operations. This name is unique within a set of all deployed bots and all users in the project.
ChatId	String	Unique identifier of the chat in which the smart bot will be added.
ChatColor	String	HEX code of the chat color. This property is set only if the chat is created or modified.
ZoneId	String	Name of the zone associated to the given chat. This property is set only if the chat is created or modified.
Location	String	Location of the event (e.g. Teams meeting). This parameter is not related to the Geolocation Zones.
ActionExecuteBot	Boolean	Specifies whether to deploy a smart bot procedure when the Event starts.
ActionExitExecuteBot	Boolean	Specifies whether to deploy a smart bot procedure when the event ends or is removed.
ActionCreateChat	Boolean	Specifies whether the chat with the given name should be created / modified or not. When the event starts, the bot searches for the chat with the given name. If True and the chat was not found, a new chat will be created. If true and the chat was found, it will be modified. If false and entry or exit actions are specified, the corresponding SmartBot procedures will still be invited to the chat.
IsReccurent	Boolean	Specifies whether the event has recurrence settings.
CanEntry	Boolean	True if the event is enabled and it has some entry actions, that is calling a procedure or modifying the chat. False otherwise.
CanExit	Boolean	True if the event is enabled and it has some exit actions, i.e. calling a procedure. False otherwise.
StartedAtDate	DateTime	Date when the event is planned to start.
StartingAtDate	DateTime	Date when the event has started.
EndingAtDate	DateTime	Date when the event is planned to end.
LastDate	DateTime	Last date for recurrent events or the planned end date for ordinary events.
IsRunning	Boolean	True if the event has been started. False otherwise.
Frequency	Integer	Event recurrence frequency according to the following enumeration. 0 = None 1 = Secondly 2 = Minutely 3 = Hourly 4 = Daily 5 = Weekly 6 = Monthly 7 = Yearly
Interval	Integer	Specifies how often the recurrent event should occur. E.g. if the Frequency is set to “Secondly” and Interval is 5, then the event will occur every 5 seconds. This property is set only for recurrent events.
Duration	Long	Duration of the event in milliseconds.
HumanReadableDuration	String	Human readable representation of the event duration.
IsAllDay	Boolean	Specifies whether the event is a full day event.
RecurOnMondays	Boolean	Specifies whether the recurrent event should occur on Mondays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnTuesdays	Boolean	Specifies whether the recurrent event should occur on Tuesdays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnWednesdays	Boolean	Specifies whether the recurrent event should occur on Wednesdays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnThursdays	Boolean	Specifies whether the recurrent event should occur on Thursdays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnFridays	Boolean	Specifies whether the recurrent event should occur on Fridays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnSaturdays	Boolean	Specifies whether the recurrent event should occur on Saturdays. This property is set only for recurrent events with the “Weekly” frequency.
RecurOnSundays	Boolean	Specifies whether the recurrent event should occur on Sundays. This property is set only for recurrent events with the “Weekly” frequency.
Attendees	ICollection<ChatAttendee>	List of event attendees.
BotParameters	ICollection<BotParameter>	List of internal variables and corresponding values that will be predefined in the executed smart bot.
ExitBotParameters	ICollection<BotParameter>	List of internal variables and corresponding values that will be predefined in the executed smart bot.
Parent	CalendarConfiguration	Schedule object with the current event.

ChatAttendee

Information about the attendee of an event.

Access expression sample	x => x.Context.Event.Attendees[0] (in case where the smart bot is started by the event as its Entry or Exit action)
Properties
Name	Type	Description
UserId	String	Unique identifier of the user.
AccessLevel	Integer	Access level of the user in the chat room.
CommonName	String	Display name of the user.
Email	String	Email of the user.
DisplayText	String	First non-empty string of the following values in the specified order. CommonName, UserId or Email.

BotParameter

Internal variable and the corresponding value that will be predefined in the executed smart bot.

Access expression sample	x => x.Context.Event.BotParameters[0] (in case where the smart bot is started by the event as its entry action) x => x.Context.Event.ExitBotParameters[0] (in case where the smart bot is started by the event as its exit action)
Properties
Name	Type	Description
Key	String	Unique reference to the value in memory.
Value	String	Value of the corresponding internal variable in memory specified by the “Key” reference.

CalendarConfiguration

Information about the schedule with the current event.

Access expression sample	x => x.Context.Event.Parent (in case where the smart bot is started by the event as its Entry or Exit action)
Properties
Name	Type	Description
Name	String	Unique name of the schedule.
Source	String	Path to the deployed schedule file.
OriginalSource	String	Path to the original schedule file used when deploying.
Events	ICollection<>	List of schedule events.
Synchonization	String	Synchronization mode. This property is set when the schedule is synchronized with a third-party calendar.
IsSynchronized	Boolean	Specifies whether the schedule is synchronized with a third-party calendar or not.

Working with data sets

Some methods and properties available to a user in the expression return a collection of items. This section describes some methods that can be used to extract a value from the collection as well as calculate some statistical values on the collection.

The current Bot Agent context has a method called Historical in order to receive a collection of the variable data points at the specified time range.

Returned type of this method is HisDataCollection. After applying Padding method, the collection becomes PaddedHisDataCollection. Both of these types are inherited from IList<HisDataPoint>. This means we can iterate through all data points and compute some function on each data point.

In order to pass through all items in the collection and to compute the required value, a LINQ expression can be used. Please refer the Microsoft Help to receive the information about .Net Language Integrated Queries (LINQ).

The following list demonstrates some examples of getting the Historical data set.

• Historical data points during the last 1 day.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days))

• Historical data points during the last 4 hours.

  x => x.Historical("Register01", "Unit01", new DateRange(4, Intervals.Hours))

• Historical data points between 01/01/2019 and 31/01/2019.

  x => x.Historical(“Branch .Register01”, “Unit01”, new DateRange(new DateTime(2019, 1, 1), new DateTime(2019, 1, 31)))

The following list demonstrates some examples of getting the padded historical data set.

• Historical data points with padding of 1 second (1 data point every second).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Seconds)

• Historical data points with padding of 1 minute (1 data point every minute).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes)

• Historical data points with 1 minute padding, when Bit01 was activated.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes).Filter(“Bit01”)

• Historical data points with 1 minute padding, when both Bit01 and Bit02 were activated.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes).Filter(“Bit01”) .Filter(“Bit02”)

• Historical data points with Good quality and with 1 minute padding, when both Bit01 and Bit02 were activated.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes).Filter(“Bit01”) .Filter(“Bit02”).ExcludeNS()

The following list demonstrates some examples of LINQ functions applied.

• Minimum value in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Min(q => q.Value)

• Minimum value with Good quality in the last 1 day when Bit01 was activated, with 1 minute padding:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes).Filter(“Bit01”) .ExcludeNS().Min(q => q.Value)

• Maximum value in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Padding(1, Intervals.Minutes).ExcludeNS().Max(q => q.Value)

• Average value in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Average(q => q.Value)

• Sum of all values in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Sum(q => q.Value)

• The first value in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).First().Value

• The first value with a Good quality in the last 1 day:

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).First(q => q.IsGood).Value

• The last value in the last 1 day.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Last().Value

• Excel VAR.P function (returns the variance in an entire population).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).VarP(q => q.Value)

• Excel VAR.S function (returns the variance of a sample).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).VarS(q => q.Value)

• Excel VAR function (the same as VAR.S function).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Var(q => q.Value)

• Excel STDEV.P function (calculates the standard deviation for an entire population).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).StDevP(q => q.Value)

• Excel STDEV.S function (calculates the standard deviation for a sample set of data).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).StDevS(q => q.Value)

• Excel STDEV function (the same as STDEV.S function).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).StDev(q => q.Value)

• Excel PERCENTILE.EXC function, calculates the 95-th percentile for a set of data.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).PercentileExc(q => q.Value, 0.95)

• Excel PERCENTILE.INC function, calculates the 80-th percentile for a set of data, inclusive.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).PercentileInc(q => q.Value, 0.8)

• Excel PERCENTILE function (the same as PERCENTILE.INC function).

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Percentile(q => q.Value, 0.7)

• Quality of the first value in the last 1 day.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).First(q => q.Quality)

All other features of LINQ are also available. Some examples are following.

• Average value of data points whose value was greater than 10 in the last 1 day.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).Where(q => q.Value > 10).Average(q => q.Value)

• Data points in the last 1 day are ordered by Value, then the first data point with a Good quality is retrieved, then its Value is returned.

  x => x.Historical("Register01", "Unit01", new DateRange(1, Intervals.Days)).OrderBy(q => q.Value).First(q => q.IsGood).Value