Overview

The TwinThread Add-In provides a very easy way to use Excel to interact with the data in the TwinThread application. The TwinThread Add-In for Excel is available as an Add-In from the Microsoft Office Add-Ins Store. There are a few key things to understand about how the Add-In works.

  1. You need to have an subscription and use your login credentials to connect the Excel Add-In to the TwinThread application. It is important to understand that when you connect to the TwinThread application, the Excel Add-In will have access to the Organization to which you were last connected (or have a current session connected). Since most users only are part of a single Organization this is not an issue for most.

  2. You can use the Add-In either through the side panel that provides an easy to follow way to set up the functions or directly by inserting a function into a cell. The benefit of using the side panel is that the configuration of each inserted function is validated prior to being added to the cell.

3. When using the functions within the Add-In it is important to understand that you almost always have to use a series of functions in order to interact with the system. The following example describing how to get historical data from a Twin's properties should help. The sequence of using one function to get an "id" and then using the "id" to get a value is a very common sequence used throughout the Add-In.

  • Login in via the side panel or the TwinThread.LOGIN function

  • Use the TwinThread.TWINS function to get the "assetId" of the Twin you are interested in. NOTE: Twin is the user facing term while asset is the underlying system term.

  • Use the TwinThread.PROPERTIES function with the "assetId" of the Twin you are interested in to get the "id" of the Property you are interested in.

  • Use the TwinThread.PROPERTYDETAILS function with the "id" of the Property you are interested in to get the Property value.

Functions

Each of the TwinThread Add-In for Excel functions are described in detail below. A couple of calling conventions to be aware of:

  1. Optional Input parameters are shown in [ ]. Required parameters do not have brackets.

  2. The "column" field in many of the functions lets you define which fields you want returned. You configure this by entering in for that field a list of the fields you want, with each column separated by a comma. Here is an example: "assetId, name, description"

TwinThread.VERSION

This function returns the current version of Add-In

Inputs: None are used

Returns: Version number as a String

TwinThread.LOGIN

This function lets you login in programmatically. You can also login using the Add-In side panel user interface.

Inputs:

  • email

  • password – be careful to expose this to others

Returns: a String - "Successfully logged in" or "Error in login (authentication verification failed)"

TwinThread.TWINS

This function returns a list of Twins and the associated information requested in the “columns” field that match the defined criteria

Inputs:

  • searchText - text string to match Twin name

  • [parent] – Id of parent Twin

  • [class] – Class ID, returns all Twins that use that Class

  • [status] – 1 for High, 2 for Medium, 3 for Low

  • [exactMatch] – defines whether the searchText field should be an exact match (1) or not (0) the default is 0

  • [direction] – 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [colums] – list of column names that should be returned. Can be assetId, name, description, parentId, status, classList

Returns: an array of Twin data with data for each Twin defined by the column parameter

TwinThread.TWINDETAIL

This function returns a list details as specified in the “column” parameter for the of Twin(s) listed in the assetId field

Inputs:

  • assetIds – one or more Twin Ids

  • [direction] 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [columns] – list of column names that should be returned. Can be assetId, name, description, parentId, status, classList

Returns: an array of Twin data with data for each Twin defined by the column parameter

TwinThread.PROPERTIES

This function returns a list Properties with associated data as specified in the “column” parameter for the of Twin(s) listed in the assetId field and Properties that match the search criteria fields. NOTE: the return field “id” is the ID of the Property. This should be used as input in the other Property related functions where the input is called “properyIds”

Inputs:

  • searchText – text string to be used to match Property names

  • assetIds – one or more Twin Ids

  • [status] – 1 for High, 2 for Medium, 3 for Low

  • [exactMatch] – defines whether the searchText field should be an exact match (1) or not (0) the default is 0

  • [direction] – 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [colums] – list of column names that should be returned. Can be id, name, description, assetId, assetName

Returns: an array of Property data with data for each Property defined by the column parameter

TwinThread.PROPERTYDETAILS

This function returns a list Property as specified in the “column” parameter for the Property(s) listed in the propertyList field

Inputs:

  • propertyList - one or more propertyIds

  • [direction] – 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [colums] – list of column names that should be returned. Can be propertyId, name, description, friendlyId, value, valueRaw, units, tagList, assetId, assetPath

Returns: an array of Property data with data for each Property listed in the propertyList field and defined by the “column” field parameters

TwinThread.PROPERTYTIMERANGEDATA

This function returns Property value data for the time range specified for the Property(s) listed in the propertyList field

Inputs:

  • propertyList - one or more propertyIds

  • startTime – the starting time of the time range

  • endTime – the ending time of the time range

  • [summaryType] – defines the variety of data summary types that can be used to “bucketize” the returned data. The complete list is provided in the function support pane. And a detailed explanation of each can be found in the TwinThread application help system. As a default “Snaphot” should be used

  • [sampleCounts] – the number of samples (or “buckets”) that should be returned

  • [direction] – 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [colums] – list of column names that should be returned. Can be propertyId, timestamp, value

Returns: an array of Property values constructed from the defined time rage, Summary Type and Sample Counts with data for each Property listed in the propertyList field and defined by the “column” field parameters

TwinThread.CLASSES

This function returns a list of Twin Classes that match the Search Criteria. A Twin Class is a Twin “Object Class” that can be used to create Twins with a shared set of features. This function is useful to find a Class assetId and then use that to find Twins that have the assetId as a Class Id (“class”)

Inputs:

  • searchText – text string to be used to match Property names

  • [exactMatch] – defines whether the searchText field should be an exact match (1) or not (0) the default is 0

  • [direction] – 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [columns] – list of column names that should be returned. Can be assetId, name, description

Returns: an array of Twin Class data for Twin Classes matching the searchText criteria with data for each Twin Class defined by the column parameter

TwinThread.CLASSDETAILS

This function returns a list of data as specified in the “column” parameter for the Twin(s) that are associated with the Class(es) listed in the classId field

Inputs:

  • classId – assetId of one or more Twin Classes

  • [direction] 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [columns] – list of column names that should be returned. Can be assetId, name, description

Returns: an array of Twin Class data with data for each Twin Class defined by the column parameter

TwinThread.UPDATEPROPERTYVALUE

This function allows you to write a new value to a Property in the TwinThread application. The new value will be timestamped with the current time and date.

Inputs:

  • propertyId – the id of the Property you want to update

  • value – the new value that you want to write to the Property

Returns: a String indicating "Success" or "Failed"

TwinThread.ALERT

This function returns data for Alerts as defined in the “column” filed for Alerts that match the defined criteria

Inputs:

  • [searchText] - text string to be used to match Alert names

  • [parent] – assetId of a Parent Twin – will return all Alerts for all Twins that are “children” id list Parent Twin.

  • [alertTypeIds] – a list of Alert Types to be used to filter the selection. Alert types are configurable so to get a list of Alert Types, you can look for Alert Types in the Context section of the TwinThread application or use the ALERTTYPES function to find a list of valid Alert Types

  • [startTime] - the starting time of the time range in which the Alert was raised

  • [endTime] - the starting time of the time range. in which the Alert was raised

  • [priority] – priority of the Alert - 1 for High, 2 for Medium, 3 for Low

  • [exactMatch] - defines whether the searchText field should be an exact match (1) or not (0) the default is 0

  • [direction] 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [columns] – list of column names that should be returned. Can be alertId, name, description, type, typeId, priority, priorityName, message, messageText, startTime, endTime, duration, pathIds

Returns: an array of Alert data for Alerts matching the selection criteria with data for each Alert defined by the column parameter

TwinThread.ALERTTYPES

This function returns Alert Types data based on the search criteria

Inputs:

  • [searchText] - text string to be used to match Alert Type names

  • [exactMatch] - defines whether the searchText field should be an exact match (1) or not (0) the default is 0

  • [direction] 1 to have the data returned in a Row, 2 to have it returned in a Column

  • [columns] – list of column names that should be returned. Can be value, name, count

Returns: an array of Alert Type data for Alerts matching the selection criteria with data for each Alert Type defined by the column parameter

Did this answer your question?