Introduction to Tags Objects
<< Short review of the concept pf Tag, and explanation that the TAGS can created directly in the Unified Namespace hierchtiavl, in the table format in Tag→Object sections. That can be also creating using the Tag Wizard Importer tools.
This section provides comprehensive guidance on managing tags in FactoryStudio by covering essential topics such as creating and editing tags, configuring tag properties, formatting tag values, and importing tag definitions. The instructions and information provided are tailored to help users effectively utilize the software and ensure a smooth user experience.
On this page:
Understanding How to Creating and Editing Tags
This section elucidates the concepts and functionality of the creating and editing tags, organized into the following topics:
In FactoryStudio, tags can be created and edited using various methods, such as:
Using the Create Tag Icon on the main toolbar or the Unified Namespace. See Toolbar commands to Create and Edit Tags.
Using the Tag Objects DataGrid to create and edit tags using a table format. See Tags Object Data Grid.
Importing Tag Definitions
To import tag definitions into a project, you can use several methods, such as:
a. Copy-pasting from other projects or Excel. See Import from Excel.
b. Importing from CSV files (individual or extended). See Import from CSV Files.
c. Using the Import Tag Wizards. See Import Tag Wizards.
d. Utilizing external programming APIs. See Eng Wrapper API Introduction.
After importing the tags, you can organize them using the Asset Modeling feature, which enables you to create a hierarchical structure for your project's tags.
Tag Configuration Properties
Main configuration properties are essential for defining a tag's characteristics. The key properties include:
- TagName: A unique identifier for the tag.
- Type: The data type of the tag (e.g., Integer, Digital).
Optional configuration properties offer additional customization for tags. These properties can be edited after importing the tags into the project. Examples of optional properties include:
- Alarm configurations: Settings related to alarms triggered by tag values.
- Historian settings: Configurations for data logging and archiving.
- Device Address: The address or location of the tag in the PLC or data source
Tag value formatting allows you to display the tag values in a more readable and meaningful format. This includes setting:
b. Units: Appropriate units for the tag values, such as temperature or pressure.
c. Precision: The number of decimal places to display for the tag value.
c. Other project-specific attributes: Custom properties specific to the project requirements
The explanation for the various in on the section Tag Configuration Properties (CRIAR ESSA SEcao nesta pagina) A Parte do OBJECTS, deve dar a explicação geral de PATH e as coisas mais importantes de algumas colunas, mas nao precisa ter cada coluna descrita, ele deve apontar tamebm para a seção the Tag Configuration Properties, para o significados das colunas adicionais. Assim como ter link para a dewscricao genérica de usando grid no Project Designer.
Toolbar commands to Create and Edit Tags
Click on New Tag Icon to create new Tags, or the Tag Properties to edit the Tag.
The following dialog will be presented. <<IMAGE>>
The only 2 essential fields to field in are the NAME and the TYPE of the Tag,
Editing Tags at the Unified Namespace
When using the toolbar from the Unified Namespace page you select in which folder the Tag will be created.
To create or edit tags on the Unified Namespace view, navigate to the Project Designer tools and select the "Tags - Unified Namespace" section. From there, you can create new tags or edit existing ones, assigning them to specific data types or templates. When creating a tag, ensure you define the relevant attributes, such as data source, initial values, and any required metadata. Existing tags can be edited to update their attributes or modify their relationships with other tags or assets as needed.
Main Configuration Properties
To import tags, ensure that these properties are correctly defined in the source file (Excel or CSV).
Tag Types
All tags have a specific type for its value, such an integer, text or DateTime. The many pre-defined Tag Types are the Built-in tag types. In addition, the tag type can be an UDT (User Defined Type) or Tag Template .
Tags have also pre-defined properties, such as Description and Array size. Different tag types may have specific properties, but most properties are available to all Tags.
When creating the Tag, some of those properties are defined in the configuration — such as the Description —, some of the properties are only accessible when the application is running — like Value, Quality and Timestamp. The complete set of Tag properties when running the project is referred as the Runtime Tag Properties.
Built-in Tag Types
The built-in tag types are based directly as extensions of the .NET datatypes. The tag types are summarized in the following table:
Built-in Tag Types | ||
|---|---|---|
Tag Type | .Net Type | Description and Value Range |
Digital | System.Int32 | Binary value, 0 or 1. |
Integer | System.Int32 | Integer values, range -2,147,483,648 through 2,147,483,647 |
Long | System.Int64 | Long integer values, range -2,147,483,648 through 2,147,483,647 |
Double | System.Double | Floating point value. ranging -1.79769313486231570E+308 through -4.94065645841246544E-324 for negative values; 4.94065645841246544E-324 through 1.79769313486231570E+308 for positive values |
Decimal | System.Decimal | Extended precision floating point., ranging 0 through +/-79,228,162,514,264,337,593,543,950,335 with no decimal point; 0 through +/-7.9228162514264337593543950335 with 28 places to the right of the decimal; smallest nonzero number is +/-0.000 The Decimal type allows calculation with higher precision than the Double type. However, math operations using Decimal can be 40 times slower than using Double. So the Decimal type should only be used when Double precision is not enough. |
Text | System.String | Text strings composed of Unicode character. Maximum length of the sting is the integer range. |
Timer | System.Int32 | Timer is a built-in integer type that can be used to generate precise timing signals and wave pattenrs. Timers have the following models:
For SquareWave, Pulse, and Comparer, the tag toggles between 0 and the StartValue (instead of 0 and 1) if you set the tag StartValue. |
DateTime | System.DateTimeOffset | From 12:00:00 midnight, January 1, 0001 to 11:59:59 P.M., December 31, 9999 |
TimeSpan | TimeSpan | Data Interval in Days, Hours, Minutes, Seconds and Milliseconds, where each of those properties can hold a Double value |
Guid | Guid | Standard Microsoft Globally Unique Identifier (GUID) |
DataTable | System.Data.DataTable | Holds an in-memory DataTable |
Image | System.Byte[] | Can hold an Image file or any binary content. The Long value is the maximum size of the content. |
Reference Type
Reference tags allow dynamic addressing of variables.
The way you use Reference tags in the project is similar to how you use references in .NET programming, as they both have a defined type. The target type for the Reference is defined in the Parameters columns.
Typed references bring advantages in both the engineering stage and in runtime. In the engineering stage, it allows IntelliSense to directly browse the template members if a reference is pointing to a template. In runtime, it allows string data validation.
All Reference tags have an additional runtime attribute: the Link property, which specifies which tag that the reference will be linked to during execution.
Essentially, the Link property is a string property that needs to receive the target tag name before using the reference tag. You can assign a string directly or by using a string expression. The best way to set the link property is to use the method GetName(), which will create the string based on the current tag name. This way, you can rename the tag without having to search the strings. This also shows the tag names linked on the cross-reference utility.
Examples:
@Tag.Reference1.Link = @Tag.TagName.GetName();
@Tag.Reference1.Link = @Tag.TagName.GetName();
@Tag.Reference1.Link = "Tag.TagName";
@Tag.Reference1.Link = "Tag.TagNa" + "me";
The reason for using the GetName() method instead of using strings directly is that with GetName() you retain the benefits of Cross-Reference and Refactoring.
Tags Object DataGrid
To create new local tags using the Object DataGrid:
- Go to Edit → Tags → Objects and insert a new row with the tag properties defined in the columns.
- or, in any configuration windows, just click the <<< IMAGE >>>. New Tag button on the Top Toolbar
- or, when at the Edit → Tags → Assets, use the NewTag toolbar button <<IMAGE >> to create a tag at the selected asset level
- or, by copy-paste the data form Excel or another project;
- or, using the other Importing tags tools.
To edit the properties of existing local tags:
- Go to Edit → Tags → Objects and edit the row with the tag definition you want to modify. Multiple rows selection is allowed. << Link editing data grids >>.
- Select a Tag Name at the top toolbar << IMAGE >> and click the Tag Properties button at the toolbar << IMAGE >>
Either creating a new tag, or editing tags, in the datagrid view or the properties dialogs, the tag has the following configuration fields:
Tag main configuration properties | |
|---|---|
Field | Description |
Parent | Specify the Parent Level where the Tag is located in Asset tree. |
Name | Enter a name for the tag. The system lets you know if the name is not valid.
|
Type | Select the tag type, which may be a built-in type or a user-defined Tag Template. |
Parameters | Configure any parameters. The parameters vary based on the tag type. Once the type is entered, you can double-click the parameters field to see a dropdown menu with any applicable parameters.
Example 1: If the DeadBand is Set to 5 and initial value of the tag is 0, the next input possible to be saved, need to be >=5 or <=-5. Example 2: If the current value of the tag is 100 and the deadband is set to 10%, the next input possible to be saved, need to be >=110 or <=90.
For example, a device may have a value of 0 The definition for the Enumeration Set dictionary is on Tags → Enumeration Sets When configuring a display component to use these tags, set the TextOutput to one of the following:
|
Array | When this field is blank, the tag is not an array. When the field contains an integer value of N, an Array is created from position 0 to N. For example, if the field contains the value 5, the Array is created from Tag[0] to Tag[5]. This means that 6 elements are created. Two programming styles are accommodated by this method; one that counts elements from 0 to less than 5, and one that counts from 1 to 5. |
Description | String message with additional information about the Tag, maximum string length is 1024 |
The fields above are visible by default on the datagrid view. To add or remove columns, right-click the column heading area and check or uncheck the columns that should be visible.
| Tag optional configuration properties | |
|---|---|
| Field / Column | Description |
| Min | Enter the minimum value that is valid for the object. |
| Max | Enter the maximum value that is valid for the object. |
| ScaleMin | Stores a minimum value to assist scaling charts or communication devices. |
| ScaleMax | Stores a maximum value to assist scaling charts or communication devices. |
| Units | String with the Engineering units of measure, simplifying the visualization of the value on Displays, and allowing the dynamic change of metric systems. More information at Dictionaries Units. |
| Format | Default format for displaying tag value. E.g.: N2 for 2 decimals; See the next table, Formatting Tag Values. |
| StartValue | Initial value set to the Tag when the project first runs. This value is overridden if a Retentive option is used. |
| Retentive | Select this option to save the value of the tag and its internal properties to the database every time the value changes. This retains the value when the application shuts down and makes the value available when the next next application starts.
The values for Retentive Tags are stores at the database defined at Datasets → DBs → Retentive, and it can be customize to use any database. Retentive can be applied to Tags of Domain Server, in this case, you can easily allow the cold-start from the Project, without losing Operator-Inputed values or other Tags that shall keep the last value in between a shutdown and a startup. Retentive can be applied to Tags of Domain Client, in this case, you can falsity create concepts as User Configuration settings, that are stored and located according the client or user connection. |
| Domain | Defines if the tag value has Server (global) or Client (instance) scope. Server (Default): the value of tag is unique, synchronize across all operator stations accessing the project. All tags used by Devices Communications and Historian must be or Type Server. Client: The value of tag is local at each Client Displays Instance accessing the project. Common use for client tags are to manage the user interface. |
| Visibility | Select the value visibility of your tag to external connection and the built-in OPC server. Private: Tag is visible only to the local project and redundant pair. If not defined, the visibility is Public by default. |
| Comment | Enter a short comment about this tag. The comment field is typically used to show a friendly name to the operator on the displays. For instance, a tag name "LV102KP" can have the Comment as "Level Tank 102". The Description field is typically the longer engineering definition of the tag usage. |
| Category | Allows to define metadata labels to the tag. Categories are useful for project organization during the engineering phase. Categories are also useful when copy pasting tags directly the draw area, automatically creating symbols. For more information on Categories, go to Dictionaries Categories. |
| DevicePoint | Read-only property. Show which communication point address is related to the tag (if any). |
| Disable | When checked disable the use of the Tag in the project execution. Default is enabled. |
| Other Columns | For definitions of other columns that are available in this table, see Common Column Definitions. |
Tag Value formatting
The format property defines the display format of tag values. For example, N1 defines a number with one decimal place, like 2.1
Proper formatting ensures that the tag values are displayed accurately and are easily understood by users.
These formats follow the specifications provided in Microsoft .NET.
Numerical values formatting | |
|---|---|
Specifier | Description |
N0 | Number with no decimal places |
Nn | Number with n decimal places (replace n by any integer number) |
X | Hexadecimal (supported only for integral types) |
C | Currency |
R | A string that can round-trip to an identical number |
P | Number multiplied by 100 and displayed with a percent symbol |
G | The more compact of either fixed-point or scientific notation |
F | Integral and decimal digits with optional negative sign |
E | Exponential notation |
D | Integer digits with optional negative sign |
Date/time formats | |
|---|---|
Specifier | Description |
T (only) | Long time pattern (equivalent to HH:mm:ss). |
d (only) | Short date pattern (equivalent to M/d/yyyy (month/day/year) for en-us). |
dd | Show the day of the month as a number from 01 through 31. |
ddd | Show the abbreviated name of the day of the week. |
dddd | Show the full name of the day of the week. |
MM | Show the month as a number from 01 through 12. |
MMM | Show the abbreviated name of the month. |
yy | Show the year as a two-digit number. |
yyyy | Show the year as a four-digit number. |
hh | Show the hour as a number from 01 through 12. |
HH | Show the hour as a number from 00 through 23. |
mm | Show the minute as a number from 00 through 59. |
ss | Show the second as a number from 00 through 59. |
fff | Show the millisecond as a number from 000 through 999. |
tt | Show the A.M./P.M. designator. |
Import Tag Definitions
There are many ways to import Tag definition to the project:
- Just Copy from other Projects and in this Project.
- Using the Import from Excel.
- Using the import from CSV Files.
- Using the Import Tag Wizards.
- Using the EngWrapper API.
Import from Excel
Importing Tag and PLC Addresses
You can copy and paste the contents of an Excel table. As long you include the title of the columns when you copy and paste the contents of the table, the tables in your project can have different columns or can be ordered differently. The system will put the data in the expected columns, even if the order is different in the source.
To create and import Tags:
- In Excel, make a table with the columns that are shown below.
To successfully import the tags, you need the TagName, Type, and Address columns.
- After you chose the device protocol and create a new node, click the Import button. Then, choose the .CSV file that contains the tag's information and click the Ok button.
- The Tags and Points will be created automatically in Tags.
- Device → Points
After you use the Import tool for the first time, the system will save whatever settings you used. The import button turns into the "Sync" button. This make the button execute a synchronization that verifies the previously imported addresses and the new ones.
Import from CSV Files
Individual CSV File
In this scenario, we are importing items for each individual table that is available throughout the Engineering Environment.
In your Engineering Environment, you should find a toolbar located on the top of the display with green arrow in it.
In Tabs that do not contain a table, the import icon is unfocused and is unable to be selected.
For Tabs that do contain grids, the import button is available when the grid is on focus (selected). When the import button is clicked, a dialog window will open.
Browse for the csv file and click Open.
Examples
To better understand how to use this feature, we are going to add Alarm Items into our sample project.
Assuming we have two Tags, Tag1 and Tag2, in our project. Each tag must have an alarm configured to it.
1. Tag1 - Belongs to ’Critical’ Alarm Group and triggers an alarm when its value is lower than 20.
2. Tag2 - Belongs to ’Warning’ Alarm Group and triggers an alarm when its value is higher than 80.
The import steps are:
- Go to Alarms → Items, create a dummy row, and copy it (Ctrl + C).
- On your external Table Editor (e.g. Excel, Google Docs, Notepad, etc), paste the copied content.
3. Fill your table with the required information.
4. Save the file as a ‘.csv’.
5. Go back to the Alarms → Items page and click the Import CSV File Button.
If you used a text editor (Notepad, Notepad++, etc), you need to add the comma separator (‘ , ’) between each column.
Extended CSV Files
In this scenario, we are using a single .csv table to import information on Tags, Devices, Alarms and historian items.
In your Engineering Environment, navigate to Run → Extensions → Import. You should see many supported files that can be imported into a project.
Select the CSV file and browse for your Table File.
The table must obey a certain format. The required columns can be obtained by following the same method as in the previous section; copy from project and paste on Sheet Editor.
The difference in this method is that the final table is a concatenation of the various grids from the project.
Examples
To illustrate the usage of this feature, we will add a couple of items to our sample project. The following items will be added:
Tags:
- MyTag1: Integer DataType and StartValue = 0.
- MyTag2: Digital DataType.
Alarm Items:
- MyTag1:
- HiHi alarm limit (configured for ‘Critical’ alarm group) set to 95
- Lo alarm limit (configured for ‘Warning’ alarm group) set to 10
- MyTag2:
- Hi alarm limit (configured for ‘Critical’ alarm group) set to 1 and Message ’Tag Alarm is Hi’.
- LoLo alarm limit (configured for ‘Warning’ alarm group) set to 0, Priority set to 1 and Message ’Tag Alarm is LoLo’.
Historian:
- MyTag1: Added to default Historian Table ‘Table1’.
- MyTag2: Added to default Historian Table ‘Table1’.
The table that contains all the columns and rows required to import the items described above can be found in the pictures below (with additional columns):
Following the importation procedure in Run → Extensions → Import, select the CSV option, browse for the filled csv file, and click Import.
Troubleshooting and Best Practices
Troubleshooting and Common #Issues
Some common issues that may arise while working with importing Tag definitions include:
#Inconsistency or missing data after importing:
Ensure that the import files (Excel, CSV, or any other supported format) are properly formatted and follow the guidelines mentioned in the documentation. Check if the required columns are present, and verify that the data types and values are compatible with the destination tables.
#Performance issues during import:
If you experience slow import times or performance issues during the import process, consider optimizing the organization of tags, assets, and templates to reduce unnecessary data overhead and improve system performance. Refer to the respective sections in the documentation for more information on optimization and best practices.
Best Practices and #Recommendations To get the most out of importing Tag definitions, follow these best practices:
Best Practices and #Recommendations
#Proper formatting of import files:
Ensure that the import files adhere to the required formats and structures, as mentioned in the documentation. Use the appropriate column names, data types, and values to avoid inconsistencies or missing data.
#Regular maintenance and organization of tags and assets:
Organize tags and assets in a clear and hierarchical manner, making it easier for users to navigate and understand the data. Use templates to create reusable data structures, reducing redundancy and streamlining data management. Regularly review and update tags and assets to ensure their accuracy and relevance.
#Efficient use of import tools and methods:
Choose the most suitable import method based on your project requirements and available resources. Utilize available import tools and wizards, such as the Import from Excel or Import from CSV Files tools, to simplify and automate the import process.
#Monitoring and validation:
After importing Tag definitions, verify the accuracy and completeness of the imported data by checking the Tag values and their associations with other elements, such as alarms or historian configurations. Implement monitoring systems and scripts to regularly report system performance and connection status with external data sources, and set up alarm conditions for critical situations.
In this section...