COM method signatures - Metasys - LIT-12013522 - Software Application - Basic Services client library for .NET (and COM) - Metasys API - 4.2

Metasys REST Client for .NET and COM Developer Guide

Brand
Metasys
Product name
Basic Services client library for .NET (and COM)
Metasys API
Document type
API Reference Guide
Document number
LIT-12013522
Version
4.2
Revision date
2021-04-07
Language
English (United States)

The intended audience for this section is VBA developers.

Table 1. Login and access token, using the Credential Manager COM signature
Library method name TryLogin
Description Login to the client.
Method signature IComAccessToken TryLoginWithCredMan(string target, bool refresh = true);
Method input parameters string target, bool refresh = true
Return value An IComAccessToken.
The following VBA code is an example of how to obtain the login and access token using the Credential Manager:
Global client As LegacyMetasysClient

Public Sub CreateClientandLogin()
  If client Is Nothing Then
    'Init legacy client using the IP address (or server name)
    Set client = clientFactory.GetLegacyClient("xxx.xxx.xxx.xxx", True, "v3", "en-US")
    Dim token As IComAccessToken
    'Login using the windows credential manager
    Set token = client.TryLoginWithCredMan("<credman_name>")
  End If
End Sub
Table 2. Login and access token, using the user name and password COM signature
Library method name TryLogin
Description Login to the client.
Method signature IComAccessToken TryLogin(string username, string password, bool refresh = true);
Method input parameters string username, string password, bool refresh = true
Return value An IComAccessToken object.
The following VBA code is an example of how to obtain the login and access token using the user name and password:
Global client As LegacyMetasysClient

Public Sub CreateClientandLogin()
  If client Is Nothing Then
    'Init legacy client using the IP address (or server name)
    Set client = clientFactory.GetLegacyClient("xxx.xxx.xxx.xxx", True, "v3", "en-US")
    Dim token As IComAccessToken
    'Login using the credentials (user and password) and get the token
    Set token = client.TryLogin("<username>", "<password>")
  End If
End Sub
Table 3. Get an object ID COM signature
Library method name GetObjectIdentifier
Description Retrieve an object ID.
Method signature string GetObjectIdentifier(string itemReference);
Method input parameters string itemReference
Return value The Guid string.
The following VBA code is an example of how to get an object ID:
Public Function GetObjectGUID(byval fqr as string) As String
'Example of parameter value:
' fqr = "WIN-21DJ9JV9QH6:EECMI-NCE25-2/AV1"
  Get the object GUID associated to the object FQR
  Dim result As String: result =""
  objectGUID = client.GetObjectIdentifier(fqr)

GetObjectGUID = result 
End Function
Table 4. Get a property COM signature
Library method name ReadProperty
Description Get a property of an object.
Method signature IComVariant ReadProperty(string id, string attributeName);
Method input parameters string id, string attributeName
Return value IComVariant object.
The following VBA code is an example of how to get a property of an object:
Public Function ReadProperty(ByVal fqr As String, ByVal prop As String) As String
'Example of parameter values:
' fqr = "WIN-21DJ9JV9QH6:EECMI-NCE25-2/AV1"
' prop ="presentValue"
  'Get first the GUID of the Object specified by the 'fqr'
  Dim objId As String
  objId = client.GetObjectIdentifier(fqr)
  'Get the value of the property specified by 'prop'
  Dim res As ComVariant
  Set res = client.ReadProperty(objId, prop)
'Return the read value
ReadProperty = res.stringValue
End Function
Table 5. Get multiple properties from multiple objects COM signature
Library method name ReadPropertyMultiple
Description Get multiple properties from multiple objects.
Method signature object ReadPropertyMultiple([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)]string[] ids, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)]string[] attributeNames);
Method input parameters string[] ids, string[] attributeNames
Return value A collection of ComVariantMultiple objects.
The following VBA code is an example of how to get multiple properties:
Public Function ReadProperties(ByVal objects As String, ByVal props As String) As String
' Example of parameter values:
' objects = "WIN-21DJ9JV9QH6:EECMI-NCE25-2/FCB.10FEC11 - V6 Unit.V5 Network Outdoor Temperature, WIN-21DJ9JV9QH6:EECMI-NCE25-2/FCB.10FEC11 - V6 Unit.V9 Network Outdoor Temperature, WIN-21DJ9JV9QH6:EECMI-NCE25-2/AV1"
' props = "name,description,presentValue"

  'Parse array objects
  Dim rawArray() As String
  Dim varArray() As String
  rawArray = Split(objects, ",")
  ReDim varArray(LBound(rawArray) To UBound(rawArray))
  Dim index As Long
  For index = LBound(rawArray) To UBound(rawArray)
    varArray(index) = client.GetObjectIdentifier(rawArray(index))
  Next index
  'Parse array props
  Dim rawArray2() As String
  Dim varArray2() As String
  rawArray2 = Split(props, ",")
  ReDim varArray2(LBound(rawArray2) To UBound(rawArray2))
  Dim index2 As Long
  For index2 = LBound(rawArray2) To UBound(rawArray2)
    varArray2(index2) = rawArray2(index2)
  Next index2
  Dim res() As Object
  res = client.ReadPropertyMultiple(varArray, varArray2)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item reference and put it in a var array
    Dim varArray5() As Variant
    ReDim varArray5(rows)
    Dim i As Integer
    Dim m As IComVariantMultiple
    Dim variants() As Object
    Dim o As IComVariant
    For i = 0 To UBound(res)
      Set m = res(i)
      ReDim variants(UBound(m.values))
      variants = m.values
      Set o = variants(i)
      varArray5(i) = o.stringValue
    Next
    'Write the results in a string (where the values are separated by a ',')
    ReadProperties = ArrayToDelimited(varArray5, ",")
  End If
End Function
Table 6. Write a property COM signature
Library method name WriteProperty
Description Get a property of an object.
Method signature void WriteProperty(string id, string attributeName, string newValue, string priority = null);
Method input parameters string id, string attributeName, string newValue, string priority = null
Return value None
The following VBA code is an example of how to write a property:
Public Function WriteProp(Byval fqr As String, prop As String, newValue As String) As String
On Error GoTo Alert
  Dim objId As String
  'Get the Object GUID according to the 'fqr'
  objId = client.GetObjectIdentifier(fqr)
  'Write the 'newValue' into the property 'prop'
  client.WriteProperty objId, prop, newValue
  'Return the result
  WriteMsProp = "Successfully done."
Done:
  Exit Function
Alert:
  'Return the error message
  WriteMsProp = "Error: " & Err.Description
End Function
Table 7. Write multiple properties from an object COM signature
Library method name WritePropertyMultiple
Description Get multiple properties from multiple objects.
Method signature void WritePropertyMultiple([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)]string[] ids, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)]string[] attributes, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)]string[] attributeValues, string priority = null);
Method input parameters string[] ids,string[] attributes, string[] attributeValues
Return value None
The following VBA code is an example of how to get multiple properties from multiple objects:
Public Function WriteMsProps(objects As String, props As String, values As String) As String
' Example of parameter values:
' objects = "WIN-21DJ9JV9QH6:EECMI-NCE25-2/FCB.10FEC11 - V6 Unit.E4 Network Outdoor Temperature,WIN-21DJ9JV9QH6:EECMI-NCE25-2/FCB.10FEC11 - V6 Unit.V9 Network Outdoor Temperature, WIN-21DJ9JV9QH6:EECMI-NCE25-2/FCB.10FEC11 - V6 Unit.E4 Network Outdoor Temperature"
' props = "name,description"
' values = "MyTest,MyTest Description"
On Error GoTo Alert
  Parse array objects
  im rawArray() As String
  im varArray() As String
  awArray = Split(objects, ",")
  eDim varArray(LBound(rawArray) To UBound(rawArray))
  im index As Long
  or index = LBound(rawArray) To UBound(rawArray)
    varArray(index) = client.GetObjectIdentifier(rawArray(index))
  Next index
  'Parse array props
  Dim rawArray2() As String
  Dim varArray2() As String
  rawArray2 = Split(props, ",")
  ReDim varArray2(LBound(rawArray2) To UBound(rawArray2))
  Dim index2 As Long
  For index2 = LBound(rawArray2) To UBound(rawArray2)
    varArray2(index2) = rawArray2(index2)
  Next index2
  'Parse array values
  Dim rawArray3() As String
  Dim varArray3() As String
  rawArray3 = Split(values, ",")
  ReDim varArray3(LBound(rawArray3) To UBound(rawArray3))
  Dim index3 As Long
  For index3 = LBound(rawArray3) To UBound(rawArray3)
    varArray3(index3) = rawArray3(index3)
  Next index3
  client.WritePropertyMultiple varArray, varArray2, varArray3
  WriteMsProps = "Successfully done."
Done:
  Exit Function
Alert:
  WriteMsProps = "Error: " & Err.Description
End Function
Table 8. Get commands COM signature
Library method name GetCommands
Description Get all commands on an object.
Method signature object GetCommands(string id);
Method input parameters string id
Return value A collection of ComCommand objects.
The following VBA code is an example of how to get all commands on an object:
Public Function GetObjectCmds(ByVal fqr As String) As ComCommand()
  'Get first the GUID of the Object specified by the 'fqr'
  Dim objId As String
  objId = client.GetObjectIdentifier(fqr)
  'Get the value of the specified by property 'prop'
  Dim res() As ComCommand
  res = client.GetCommands(objId)
'Return the values
GetObjectCmds = res()
End Function
Table 9. Send commands COM signature
Library method name SendCommand
Description Send all commands on an object.
Method signature void SendCommand(string id, string command, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] string[] values = null);
Method input parameters string id, string command, string[] values = null
Return value None
The following VBA code is an example of how to send all commands on an object:
Public Function SendMsCommand(fqr As String, command As String, Optional values As String) As String
'Example of parameter values:
' fqr = "WIN-21DJ9JV9QH6:EECMI-NCE25-2/AV1"
' command = "adjust"
' values = "25"
On Error GoTo Alert
  Dim objId As String
  objId = client.GetObjectIdentifier(fqr)
  If IsMissing(values) = False And Trim(values & vbNullString) <> vbNullString Then
    Dim varArray() As String
    'Parse array objects
    Dim rawArray() As String
    rawArray = Split(values, ",")
    ReDim varArray(LBound(rawArray) To UBound(rawArray))
    Dim index As Long
    For index = LBound(rawArray) To UBound(rawArray)
      varArray(index) = rawArray(index)
    Next index
    client.SendCommand objId, command, varArray
  Else
    client.SendCommand objId, command
  End If
  SendMsCommand = "Successfully done."
Done:
  Exit Function
Alert:
  SendMsCommand = "Error: " & Err.Description
End Function
Table 10. Get network devices COM signatures
Library method name GetNetworkDevices
Description Get all devices on the network.
Method signature object GetNetworkDevices(string type = null);
Method input parameters Optional: The type of network devices used as a filter.
Return value A collection of ComMetasyObjects that represent the devices.
The following VBA code is an example of how to get all devices on the network:
Public Function GetNetworkDevices() As String
'This function returns the FQR of all the network devices separated by ','
On Error GoTo Alert
  Dim result As String: result = ""
  'Get the network device objects
  Dim res() As Object
  res = client.GetNetworkDevices()
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item reference and put it in a var array
    Dim varArray() As Variant
    ReDim varArray(rows)
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res)
      Set o = res(i)
      result = result & o.ItemReference & ","
    Next
  End If
  'Return the result
  GetNetworkDevices = result
Done:
  Exit Function
Alert:
  'Return the error message
  GetNetworkDevices = "The following error occurred: " & Err.Description
End Function
Table 11. Get object children COM signatures
Library method name GetObjects
Description Get child devices of an object.
Method signature object GetObjects(string id, int levels = 1);
Method input parameters string id, int levels = 1
Return value A collection of ComMetasysObject.
The following VBA code is an example of how to get child devices of an object:
Public Function GetObjects(fqr As String, levels As String) As String
On Error GoTo Alert
  Dim result As String: result = ""
  Dim objId As String
  objId = client.GetObjectIdentifier(fqr)
  Dim res() As Object
  ' Note: this is possible because the return type is an object
  res = client.GetObjects(objId, levels)
  ' Check response
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res)
      Set o = res(i)
      ' Extract children when available
      If o.ChildrenCount > 0 Then
        Dim children() As Object
        children = o.children
        Dim c As IComMetasysObject
        Dim j As Integer
        For j = 0 To (o.ChildrenCount - 1)
          Set c = children(j)
          result = result & c.ItemReference & ","
        Next
      End If          
      result = result & o.ItemReference & ","
    Next
  End If
  'Return the result
  GetObjects = result
Done:
  Exit Function
Alert:
  'Return the error message
  GetObjects = "The following error occurred: " & Err.Description
End Function
Table 12. Get spaces COM signature
Library method name GetSpaces
Description Get available spaces on your server.
Method signature object GetSpaces(string type = null)
Method input parameters string type = null
Return value A collection of MetasysObject that represents spaces.
The following VBA code is an example of how to get available spaces on your server:
Public Function GetSpaces() As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the read value
  Dim res() As Object
  res = client.GetSpaces()
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item name and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res)
      Set o = res(i)
      result = result & o.Name & ","
    Next
  End If
  'Return the result
  GetSpaces = result
Done:
  Exit Function
Alert:
  'Return the error message
  GetSpaces = "The following error occurred: " & Err.Description
End Function
Table 13. Get spaces types COM signature
Library method name GetSpaceTypes
Description Get available space types on your server.
Method signature object GetSpaceTypes()
Method input parameters None
Return value A collection of MetasysObjectType.
The following VBA code is an example of how to get available space types on your server:
Public Function GetSpaceTypes() As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the read value
  Dim res() As Object
  res = client.GetSpaceTypes()
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item description and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysObjectType
    For i = 0 To UBound(res)
      Set o = res(i)
      Result = result & o.Description & ","
    Next
  End If
  'Return the result
  GetSpaceTypes = result
Done:
  Exit Function
Alert:
'Return the error message
  GetSpaceTypes = "The following error occurred: " & Err.Description
End Function
Table 14. Get equipment COM signature
Library method name GetEquipment
Description Get all equipment on your server.
Method signature object GetEquipment()
Method input parameters None
Return value A collection of MetasysObject that represent equipment.
The following VBA code is an example of how to get all equipment on your server:
Public Function GetEquipments() As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the read value
  Dim res() As Object
  res = client.GetEquipment()
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item name and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res)
      Set o = res(i)
      GetEquipments = GetEquipments & o.Name & ","
  Next
    End If
    GetEquipments = result
Done:
  Exit Function
Alert:
  GetEquipments = "The following error occurred: " & Err.Description
End Function
Table 15. Get equipment serving a space COM signature
Library method name GetSpaceEquipment
Description Get equipment for a specific space.
Method signature object GetSpaceEquipmnet(string spaceId);
Method input parameters string spaceId
Return value A collection of ComMetasysObject that represent equipment in a space.
The following VBA code is an example of how to get equipment for a specific space:
Public Function GetSpaceEquipments(ByVal spaceID As String) As String
'Example of parameter value:
' spaceID = "2a26bb37-4f30-5d0d-899a-752c535a3be2" (GUID of a space object)
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the equipments associated to a space
  Dim res2() As Object
  res2 = client.GetSpaceEquipment(spaceID)
  Dim rows As Long
  rows = UBound(res2) + 1
  If (rows > 0) Then
    'Extract Item name and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res2)
      Set o = res2(i)
      result = result & o.Name & ","
    Next
  End If
  'Return the result
  GetSpaceEquipments = result
Done:
  Exit Function
Alert:
'Return the error message
  GetSpaceEquipments = "The following error occurred: " & Err.Description
End Function
Table 16. Get children spaces of the given space COM signature
Library method name GetSpaceChildren
Description Get children spaces of a given space.
Method signature object GetSpaceChildren(string spaceId);
Method input parameters string spaceId
Return value A collection of ComMetasysObject that represent equipment in a space.
The following VBA code is an example of how to get children spaces of a given space:
Public Function GetSpaceChildren(ByVal spaceID As String) As String
'Example of parameter value:
' spaceID = "2a26bb37-4f30-5d0d-899a-752c535a3be2" (GUID of a space object)
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the spaces (children) associated to a space
  Dim res2() As Object
  res2 = client.GetSpaceChildren(spaceID)
  Dim rows As Long
  rows = UBound(res2) + 1
  If (rows > 0) Then
    'Extract Item name and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysObject
    For i = 0 To UBound(res2)
      Set o = res2(i)
      result = result & o.Name & ","
    Next
  End If
  'Return the result
  GetSpaceChildren = result
Done:
  Exit Function
Alert:
'Return the error message
  GetSpaceChildren = "The following error occurred: " & Err.Description
End Function
Table 17. Get equipment points COM signature
Library method name GetEquipmentPoints
Description GET points for a specific equipment
Method signature object GetEquipmentPoints(string equipmentId);
Method input parameters string equipmentId
Return value A collection of Point objects.
The following VBA code is an example of how to get points for a specific item of equipment:
Public Function GetEquipmentPoints(ByVal equipmentID As String) As String
'Example of parameter value:
' equipmentID = "cb2b651e-9a4a-5b51-8165-d7c4b18419ad"
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the read value
  Dim res() As Object
  res = client.GetEquipmentPoints(equipmentID)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item shortname and concatenate it in a string
    Dim i As Integer
    Dim o As IComMetasysPoint
    Dim val As IComVariant
    For i = 0 To UBound(res)
      Set o = res(i)
      Set val = o.PresentValue
      result = result & o.ShortName + ","
    Next
  End If
  GetEquipmentPoints = result
Done:
  Exit Function
Alert:
  GetEquipmentPoints = "The following error occurred: " & Err.Description
End Function
Table 18. Get alarms COM signature
Library method name GetAlarms
Description Get available alarms.
Method signature IComPagedResult GetAlarms(IComFilterAlarm alarmFilter);
Method input parameters IComFilterAlarm alarmFilter
Return value A ComPagedResult of ComAlarm.
The following VBA code is an example of how to get available alarms:
Public Function ReadAlarms() As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Return the read value
  Dim filter As New ComAlarmFilter
  filter.StartTime = "2020-01-10T08:10:20.243Z"
  filter.EndTime = "2020-06-02T09:10:20.243Z"
  filter.PageSize = 100
  filter.PriorityRange = "0,100"
  Dim alarmsPager As ComPagedResult
  Set alarmsPager = client.GetAlarms(filter)
  Dim total As Long
  total = alarmsPager.total
  If (total > 0) Then
    'Extract Item reference and put it in a var array
    Dim i As Integer
    Dim a As ComAlarm
    Dim alarms() As Object
    alarms = alarmsPager.Items
    For i = 0 To UBound(alarms)
      Set a = alarms(i)
      result = result & CStr(a.ID) & ","
    Next
  End If
  'Return the result
  ReadAlarms = result
Done:
  Exit Function
Alert:
'Return the error message
  ReadAlarms = "The following error occurred: " & Err.Description
End Function
Table 19. Get single alarm COM signature
Library method name GetSingleAlarm
Description Get a single alarm
Method signature object GetSingleAlarm(string alarmId);
Method input parameters string alarmId
Return value A ComAlarm object.
The following VBA code is an example of how to get a single alarm:
Public Function ReadSingleAlarm(ByVal alarmId As String) As String
On Error GoTo Alert
  Dim result As String: result = ""
  Dim alarm As ComAlarm
  'Get the alarm using its GUID
  Set alarm = client.GetSingleAlarm(alarmId)
  If Not (alarm Is Nothing) Then
    'Extract Item FQR use it as the result of this function
    result = CStr(alarm.ItemReference)
  End If
  'Return the result
  ReadSingleAlarm = result
Done:
  Exit Function
Alert:
  ReadSingleAlarm = "The following error occurred: " & Err.Description
End Function
Table 20. Get alarms for object COM signature
Library method name GetAlarmsForObject
Description Get the alarms for a specific object
Method signature IComPagedResult GetAlarmsForObject(string objectId, IComFilterAlarm alarmFilter
Method input parameters string objectId, IComFilterAlarm alarmFilter
Return value A ComPageResult of ComAlarm
The following VBA code is an example of how to get alarms for a specific object:
Public Function ReadAlarmsForAnObject(objectId As String) As String
On Error GoTo Alert
Dim result As String: result = ""
'Set the filter
  Dim filter As New ComAlarmFilter
  filter.StartTime = "2020-08-15T08:10:20.243Z"
  filter.EndTime = "2020-08-20T08:10:20.243Z"
  filter.ExcludeAcknowledged = True
  Dim alarmsPager As ComPagedResult
  'Get the alarms associated to the object ID (GUID)
  Set alarmsPager = client.GetAlarmsForObject(objectId, filter)
  Dim total As Long
  total = alarmsPager.total
  If (total > 0) Then
    'Extract Item reference and concatenate it in a string
    Dim i As Integer
    Dim a As ComAlarm
    Dim alarms() As Object
    ReDim alarms(total)
    alarms = alarmsPager.Items
    For i = 0 To UBound(alarms)
      Set a = alarms(i)
      result = result & CStr(a.ID) & ","
    Next
  End If
  'Return the result
  ReadAlarmsForAnObject = result
Done:
  Exit Function
Alert:
  ReadAlarmsForAnObject = "The following error occurred: " & Err.Description
End Function
Table 21. Get alarms for network device COM signature
Library method name GetAlarmsForNetworkDevice
Description Get the alarms for a specific network device
Method signature IComPagedResult GetAlarmsForNetworkDevice(string networkDeviceId, IComFilterAlarm alarmFilter)
Method input parameters string networkDeviceId, IComFilterAlarm alarmFilter
Return value A ComPageResult of ComAlarm
The following VBA code is an example of how to get alarms for a specific network device:
Public Function ReadAlarmsForNetworkDevice(ByVal networkDeviceId As String) As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Set the filter object
  Dim filter As New ComAlarmFilter
  filter.StartTime = "2020-05-18T08:10:20.243Z"
  filter.EndTime = "2020-06-18T09:10:20.243Z"
  Dim alarmsPager As ComPagedResult
  'Get the alarms assaciated to the network device Id (GUID)
  Set alarmsPager = client.GetAlarmsForNetworkDevice(networkDeviceId, filter)
  Dim total As Long
  total = alarmsPager.total
  If (total > 0) Then
    'Extract alarm GUID and concatenate it in a string
    Dim i As Integer
    Dim a As ComAlarm
    Dim alarms() As Object
    ReDim alarms(total)
    alarms = alarmsPager.Items
    For i = 0 To UBound(alarms)
      Set a = alarms(i)
      result = result & CStr(a.ID) & ","
    Next
  End If
  'Return the result
  ReadAlarmsForNetworkDevice = result
Done:
  Exit Function
Alert:
  'Return the error message
  ReadAlarmsForNetworkDevice = "The following error occurred: " & Err.Description
End Function
Table 22. Get alarm annotations COM signature
Library method name GetAlarmAnnotations
Description Get the annotations for a specific alarm
Method signature object GetAlarmAnnotations(string alarmId)
Method input parameters string alarmId
Return value An array of IComAlarmAnnotation
The following VBA code is an example of how to get the annotations for a specific alarm:
Public Function ReadAlarmAnnotations(ByVal alarmId As String) As String
On Error GoTo Alert
  Dim result As String: result = ""
  Dim res() As IComAlarmAnnotation
  'Get the alarm annotations associated to the alarm ID (GUID)
  res = client.GetAlarmAnnotations(alarmId)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract the alarm annotation text and concatenate it in a string
    Dim i As Integer
    For i = 0 To UBound(res)
      result = result & CStr(res(i).Text) & ","
    Next
  End If
  'Return the result
  ReadAlarmAnnotations = result
Done:
  Exit Function
Alert:
  'Return the error message
  ReadAlarmAnnotations = "The following error occurred: " & Err.Description
End Function
Table 23. Get trend samples COM signature
Library method name GetSamples
Description To get available trends samples
Method signature IComPagedResult GetSamples(string objectId, int attributeId, IComTimeFilter filter);
Method input parameters (string objectId, int attributeId, IComTimeFilter filter
Return value A ComPagedResult of Sample.
The following VBA code is an example of how to get available trends samples:
Public Function ReadSamples(ByVal objId As String, ByVal attributeId As Integer) As String
'Example of parameter values:
' objId = "3dfb7f09-2465-5520-b2d8-046e3b5ce80a"
' attributeId = 85
On Error GoTo Alert
  Dim result As String: result = ""
  'Set the filter to get the samples
  Dim filter As New ComTimeFilter
  filter.StartTime = "2020-06-04T08:10:20.243Z"
  filter.EndTime = "2020-06-06T09:10:20.243Z"
  Dim samplesPager As ComPagedResult
  Set samplesPager = client.GetSamples(objId, attributeId, filter)
  'Extract Items  and put it in a var array
  Dim rows As Long
  rows = UBound(samplesPager.Items) + 1
  If (rows > 0) Then
    Dim i As Integer
    Dim s As ComSample
    Dim samples() As Object
    ReDim samples(rows)
    samples = samplesPager.Items
    For i = 0 To UBound(samples)
      'Extract the sample value and concatenate it in a string
      Set s = samples(i)
      result = result & CStr(s.Value) & ","
    Next
  End If
  'Return the result
  ReadSamples = result
Done:
  Exit Function
Alert:
  ReadSamples = "The following error occurred: " & Err.Description
End Function
Table 24. Get trended attributes COM signature
Library method name GetTrendedAttributes
Description Get a list of trended attributes for a specific object.
Method signature object GetTrendedAttributes(string id);
Method input parameters string id
Return value A list of ComAttribute objects.
The following VBA code is an example of how to get a list of trended attributes for a specific object:
Public Function ReadTrendedAttributes(ByVal objId As String) As String
'Example of parameter value:
' objId = "3dfb7f09-2465-5520-b2d8-046e3b5ce80a"
On Error GoTo Alert
  Dim result As String: result = ""
  'Get Trended attributes
  Dim res() As ComMetasysAttribute
  res = client.GetTrendedAttributes(objId)
  Dim attr As ComMetasysAttribute
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract the tred attribute ID and concatenate it in a string
    Dim i As Long
    For i = 0 To UBound(res)
      result = result & CStr(res(i).ID) & ","
    Next
  End If
  'Return the result
  ReadTrendedAttributes = result
Done:
  Exit Function
Alert:
  ReadTrendedAttributes = "The following error occurred: " & Err.Description
End Function
Table 25. Get audits COM signature
Library method name GetAudits
Description Get all available audits.
Method signature IComPagedResult GetAudits(IComAuditFilter auditFilter);
Method input parameters IComAuditFilter auditFilter
Return value A ComPagedResult of ComAudit.
The following code is an example of how to get all available audits:
Public Function ReadAudits() As String
On Error GoTo Alert
  Dim result As String: result = ""
  'Set the object to filter the audits
  Dim filter As New ComAuditFilter
  filter.StartTime = "2020-05-05T08:10:20.243Z"
  filter.EndTime = "2020-06-02T09:10:20.243Z"
  filter.PageSize = 100
  filter.OriginApplications = "0,1,2"
  'Get the audits according to the filter
  Dim auditsPager As ComPagedResult
  Set auditsPager = client.GetAudits(filter)
  Dim total As Long
  total = auditsPager.total
  If (total > 0) Then
    'Extract audit ID and concatenate it in a string
    Dim i As Integer
    Dim a As ComAudit
    Dim audits() As Object
    audits = auditsPager.Items
    For i = 0 To UBound(audits)
      Set a = audits(i)
      result = result & CStr(a.ID) & ","
    Next
  End If
  'Return the result
  ReadAudits = result
Done:
  Exit Function
Alert:
  'Return the error message
  ReadAudits = "The following error occurred: " & Err.Description
End Function
Table 26. Get single audit COM signature
Library method name GetSingleAudit
Description Get single audit
Method signature object GetSingleAudit(string auditId);
REST API action string auditId
Return value A ComAudit object.
The following VBA code is an example of how to get a single audit:
Public Function ReadSingleAudit(ByVal auditId As String) As String
'Example of parameter value:
' auditId = "f225f75a-3bae-4b41-9126-8430a6d62178"
On Error GoTo Alert
  Dim result As String: result = ""
  Dim audit As ComAudit
  'Get the alarm using its GUID
  Set audit = client.GetSingleAudit(auditId)
  If Not (audit Is Nothing) Then
    'Extract audit ID and use it as the result of this function
    result = CStr(audit.ID)
  End If
  'Return the result
  ReadSingleAudit = result
Done:
  Exit Function
Alert:
  ReadSingleAudit = "The following error occurred: " & Err.Description
End Function
Table 27. Get audit for an object COM signature
Library method name GetAuditsForAnObject
Description Get an audit for a single object
Method signature IComPagedResult GetAuditsForAnObject(string objectId, IComAuditFilter auditFilter);
Method input parameters string objectId, IComAuditFilter auditFilter
Return value A ComPagedResult of ComAudit.
The following VBA code is an example of how to get an audit for a single object:
Public Function ReadAuditsForAnObject(ByVal objectId As String) As String
'Example of parameter value:
' objectId = "21c605fb-4755-5d65-8e9f-4fc8283b0366"
On Error GoTo Alert
  Dim result As String: result = ""
  'Set the filter
  Dim filter As New ComAuditFilter
  filter.StartTime = "2020-08-15T08:10:20.243Z"
  filter.EndTime = "2020-08-20T08:10:20.243Z"
  filter.PageSize = 100
  Dim auditsPager As ComPagedResult
  'Get the audits associated to the object Id
  Set auditsPager = client.GetAuditsForObject(objectId, filter)
  Dim total As Long
  total = auditsPager.total
  If (total > 0) Then
    'Extract audit ID (GUID) and concatenate it in a string
    Dim i As Integer
    Dim a As ComAudit
    Dim audits() As Object
    ReDim audits(total)
    audits = auditsPager.Items
    For i = 0 To UBound(audits)
      Set a = audits(i)
      result = result & CStr(a.ID) & ","
Next
  End If
  'Return the result
  ReadAuditsForAnObject = result
Done:
  Exit Function
Alert:
  ReadAuditsForAnObject = "The following error occurred: " & Err.Description
End Function
Table 28. Get audit annotations COM signature
Library method name GetAuditAnnotations
Description Get the annotations for a specific audit.
Method signature object GetAuditAnnotations(string auditId)
Method input parameters string auditId
Return value An array of IComAuditAnnotation.
The following VBA code is an example of how to get the annotations for a specific audit:
Public Function ReadAuditAnnotations(ByVal auditId As String) As String
'Example of parameter value:
' auditId = "f225f75a-3bae-4b41-9126-8430a6d62178"
On Error GoTo Alert
  Dim result As String: result = ""
  'Get the annotations associated to the audit Id
  Dim res() As Object
  res = client.GetAuditAnnotations(auditId)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract the audit annotation text and concatenate it in a string
    Dim i As Integer
    Dim m As IComAuditAnnotation
    For i = 0 To UBound(res)
      Set m = res(i)
      result = result & m.Text & ","
    Next
  End If
  'Return the result
  ReadAuditAnnotations = result
Done:
  Exit Function
Alert:
  'Return the error message
  ReadAuditAnnotations = "The following error occurred: " & Err.Description
End Function
Table 29. Add audit annotation COM signature
Library method name AddAuditAnnotation
Description Add an annotation to a specific audit.
Method signature void AddAuditAnnotation(string id, string text)
Method input parameters string id, string text
Return value None
The following VBA code is an example of how to add an annotation to a specific audit:
Public Function AddSingleAuditAnnotation(ByVal auditId As String, ByVal text As String) As String
'Example of parameter values:
' auditId = "f225f75a-3bae-4b41-9126-8430a6d62178"
' text = "ANNOTATION TO ADD"
On Error GoTo Alert
  'Add the audit annotation to the audit specified by the audit Id
  client.AddAuditAnnotation auditId, text
  'Return the result (if no errors occur)
  AddSingleAuditAnnotation = "Successfully done."
Done:
  Exit Function
Alert:
  'Return the error message
  AddSingleAuditAnnotation = "Error: " & Err.Description
End Function
Table 30. Add audit annotations COM signature
Library method name AddAuditAnnotationMultiple
Description Add one or many annotations to one or many audits.
Method signature string[] AddAuditAnnotationMultiple(string[] requestParams)
Method input parameters string[] requestParams
Return value An array of string.
The following VBA code is an example of how to add one or many annotations to one or many audits:
Public Function AddAuditAnnotationMultiple(requestParams() As String)
'Example of parameter value:
'    Dim requestParams(1) As String
'    requestParams(0) = "f225f75a-3bae-4b41-9126-8430a6d62178|ANNOTATION TO ADD #1"
'    requestParams(1) = "f225f75a-3bae-4b41-9126-8430a6d62178|ANNOTATION TO ADD #2"
On Error GoTo Alert
  Dim result As String: result = ""
  'Add multiple audit annotations
  Dim res() As String
  res = client.AddAuditAnnotationMultiple(requestParams)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item reference and put it in a var array
    Dim i As Integer
    For i = 0 To UBound(res)
      result = result & res(i) & ","
    Next
  End If
  'Return the result
  AddAuditAnnotationMultiple = result
Done:
  Exit Function
Alert:
  'Return the error message
  AddAuditAnnotationMultiple = "The following error occurred: " & Err.Description
End Function
Table 31. Discard audit COM signature
Library method name DiscardAudit
Description Discard a specific audit
Method signature void DiscardAudit(string auditId)
Method input parameters string auditId
Return value None
The following VBA code is an example of how to discard a specific audit:
Public Function DiscardSingleAudit(ByVal auditId As String, ByVal text As String) As String
'Example of parameter values:
' auditId = "1b3b3127-a703-42b7-bb9a-7527331e329d"
' text = "DISCARD AUDIT ANNOTATION"
On Error GoTo Alert
  'Discard the audit specified by the audit Id (and add an annotation to it)
  client.DiscardAudit auditId, text
  'Return the result (if no errors occur)
  DiscardSingleAudit = "Successfully done."
Done:
  Exit Function
Alert:
  'Return the error message
  DiscardSingleAudit = "Error: " & Err.Description
End Function
Table 32. Discard multiple audits COM signature
Library method name DiscardAuditMultiple
Description Discard one or many audits. Method also adds an annotation to each discarded audit.
Method signature string[] DiscardAuditMultiple(string[] requestParams)
Method input parameters string[] requestParams
Return value An array of string.
The following VBA code is an example of how to discard one or many audits:
Public Function DiscardAuditMultiple(requestParams() As String) As String
'Example of parameter value:
'    Dim requestParams(1) As String
'    requestParams(0) = "1b3b3127-a703-42b7-bb9a-7527331e329d|DISCARD ANNOTATION AUDIT#1"
'    requestParams(1) = "e3b6cbcf-cf05-43ed-b845-7321c8b86c38|DISCARD ANNOTATION AUDIT#2"
On Error GoTo Alert
  Dim result As String:   result = ""
  'Discard multiple audit (and add an annotation to them)
  Dim res() As String
  res = client.DiscardAuditMultiple(requestParams)
  Dim rows As Long
  rows = UBound(res) + 1
  If (rows > 0) Then
    'Extract Item reference and put it in a var array
    For i = 0 To UBound(res)
      result = result & CStr(res(i)) & ","
    Next
  End If
  'Return the result
  DiscardAuditMultiple = result
Done:
  Exit Function
Alert:
  'Return the error message
  MsgBox "The following error occurred: " & Err.Description
End Function