├── .gitignore
├── LICENSE
├── README.md
├── images
    └── session-concept.png
└── pages
    ├── accessing-project-nodes.md
    ├── advanced-svg.md
    ├── alarming.md
    ├── async-tasks.md
    ├── audit-signature.md
    ├── colors.md
    ├── companion-specs.md
    ├── creating-objects.md
    ├── database-interaction.md
    ├── datagrids.md
    ├── dialog-boxes.md
    ├── dispatch-events.md
    ├── dynamic-links.md
    ├── events.md
    ├── execute-command.md
    ├── good-practices.md
    ├── information-model.md
    ├── log-output.md
    ├── managing-aliases.md
    ├── netlogic-overview.md
    ├── opcua.md
    ├── plc-tags.md
    ├── random-generation.md
    ├── regex.md
    ├── register-observers.md
    ├── reports.md
    ├── resource-uri.md
    ├── runtime-tags-import.md
    ├── sessions.md
    ├── system-node.md
    ├── template-library.md
    ├── translations.md
    ├── trends.md
    ├── ui-animations.md
    ├── users-groups.md
    ├── variables-formatting.md
    ├── variables-interaction.md
    └── variables-properties.md


/.gitignore:
--------------------------------------------------------------------------------
1 | **.pdf
2 | **.doc*


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2023 ASEM S.r.l
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # FT Optix cheat sheet
 2 | 
 3 | Collection of C# snippets ready for copy-paste
 4 | 
 5 | ## Disclaimer
 6 | 
 7 | Rockwell Automation maintains these repositories as a convenience to you and other users. Although Rockwell Automation reserves the right at any time and for any reason to refuse access to edit or remove content from this Repository, you acknowledge and agree to accept sole responsibility and liability for any Repository content posted, transmitted, downloaded, or used by you. Rockwell Automation has no obligation to monitor or update Repository content
 8 | 
 9 | The examples provided are to be used as a reference for building your application and should not be used in production as-is. It is recommended to adapt the example for the purpose, of observing the highest safety standards.
10 | 
11 | > [!IMPORTANT]
12 | > This guide does not replace the official FT Optix documentation, it is just a place some code snippets with a brief explanation.
13 | 
14 | > [!WARNING]
15 | > These snippets *may* use some non-public APIs that may be subject to changes, please refer to official documentation to access the publicly available APIs which are guaranteed to be maintained.
16 | 
17 | > [!WARNING]
18 | > Some of the snippets from this repository may irremediably break your project, use them at your own risk. Make sure to implement proper error handling and testing before deploying them to a production environment.
19 | 
20 | > [!WARNING]
21 | > Usage of the version control features of the FactoryTalk Optix IDE is hightly recommended to avoid any data loss. Make sure to commit your changes regularly to recover from any potential issue.
22 | 
23 | ## Sections
24 | 
25 | ### Introduction
26 | 
27 | - [The InformationModel](./pages/information-model.md)
28 | - [NetLogic overview](./pages/netlogic-overview.md)
29 | - [Accessing project nodes](./pages/accessing-project-nodes.md)
30 | - [General FT Optix good practices](./pages/good-practices.md)
31 | 
32 | ### General NetLogic tips and tricks
33 | 
34 | - [Objects, types and instances](./pages/creating-objects.md)
35 | - [Sessions](./pages/sessions.md)
36 | - [Asynchronous tasks](./pages/async-tasks.md)
37 | 
38 | ### Variables
39 | 
40 | - [Managing aliases](./pages/managing-aliases.md)
41 | - [Resource URI](./pages/resource-uri.md)
42 | - [Variables formatting](./pages/variables-formatting.md)
43 | - [Variables properties](./pages/variables-properties.md)
44 | - [RegEx](./pages/regex.md)
45 | - [Variables Interaction](./pages/variables-interaction.md)
46 | - [Runtime tags import](./pages/runtime-tags-import.md)
47 | - [Dynamic Links](./pages/dynamic-links.md)
48 | - [PLC Tags](./pages/plc-tags.md)
49 | - [Audit signature](./pages/audit-signature.md)
50 | 
51 | ### OPC/UA
52 | 
53 | - [OPC/UA](./pages/opcua.md)
54 | - [Companion Specifications](./pages/companion-specs.md)
55 | 
56 | ### UI
57 | 
58 | - [DialogBox](./pages/dialog-boxes.md)
59 | - [Events handling](./pages/events.md)
60 | - [Colors](./pages/colors.md)
61 | - [Advanced SVG](./pages/advanced-svg.md)
62 | - [DataGrid](./pages/datagrids.md)
63 | - [Animations](./pages/ui-animations.md)
64 | - [Trends](./pages/trends.md)
65 | 
66 | ### Others
67 | 
68 | - [Log output](./pages/log-output.md)
69 | - [Database interaction (queries)](./pages/database-interaction.md)
70 | - [Random generation](./pages/random-generation.md)
71 | - [Execute commands](./pages/execute-command.md)
72 | - [Locales and Translations](./pages/translations.md)
73 | - [Users and groups](./pages/users-groups.md)
74 | - [Alarms](./pages/alarming.md)
75 | - [System Node](./pages/system-node.md)
76 | - [Template Library](./pages/template-library.md) (starting from FactoryTalk Optix 1.6.X)
77 | - [Reports](./pages/reports.md)
78 | 
79 | ### Advanced
80 | 
81 | > [!WARNING]
82 | > The following topics are very advanced and potentially dangerous, think twice before implementing them as they could lead to unexpected results
83 | 
84 | - [Register OPC/UA observers](./pages/register-observers.md)
85 | - [Dispatch OPC/UA events](./pages/dispatch-events.md)
86 | 


--------------------------------------------------------------------------------
/images/session-concept.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/FactoryTalk-Optix/NetLogic_CheatSheet/d5b670ac7a85728feffddd3412b6afc1d3950aa5/images/session-concept.png


--------------------------------------------------------------------------------
/pages/accessing-project-nodes.md:
--------------------------------------------------------------------------------
 1 | # Accessing project nodes
 2 | 
 3 | Before reading this page, please make sure to have the concept of [InformationModel and Session](./information-model.md).
 4 | 
 5 | ## Navigating to a node
 6 | 
 7 | ### The `Node.Get` syntax
 8 | 
 9 | The `Get` method is used to fetch nodes from the current project, it can retrieve both session and global objects (nodes), this method also accepts a type that will be passed to the variable type
10 | - Example:
11 |     - `var myButton = … .Get<Button>("path/to/button");` -> Will create a _myButton_ variable of Type `FTOptix.UI.Button` pointing to the desired element
12 | - After the object has been casted to the proper path, you can access its properties using IntelliSense
13 |     - Example:
14 |         - `myButton.Text = Hello;`
15 | 
16 | ### Accessing global objects
17 | 
18 | In order to manipulate any project element, you first need to access it, this can be either done by getting its NodeId or its node object
19 | 
20 | - Examples:
21 |     - `var myNodeId = Project.Current.Get( [path/to/node] ).NodeId;`
22 |     - `var myObject = Project.Current.Get( [path/to/node] );`
23 | 
24 |     - Where `path/to/node` can be obtained by right clicking any element of the IDE and then clicking `Copy path to node`, here you need to remember to remove the project name from the pasted element
25 |         - Example:
26 |             - `NewHMIProject25/Model/MyCustomMotor` --> `Model/MyCustomMotor`
27 | 
28 | ### Accessing session-based objects
29 | 
30 | Now that we know how session works, it's easy to understand the benefits of placing a NetLogic in a session-based object (such as the page you want to access or manipulate) and then use the relative addressing to retrieve the right element
31 |     - Example:
32 |         - `var ButtonText = Owner.Get("MotorButton/Text");`
33 | 
34 | ### The `Node.Find` syntax
35 | 
36 | You can also search for a specific object by knowing its `BrowseName` by using the `Find` method, this can be useful but it is not recommended as it is very slow to perform (it will recursively browse the whole project until it gets to the first element with such node)
37 | - Example:
38 |     - `var myObj = Project.Current.Find("ObjectName");`
39 | 
40 | ## Casting vs Type passing
41 | 
42 | ### Passing the object type
43 | 
44 | Type parameter can be used with "generic methods" that allows using different types. A generic method can be called either without an argument (anything that applies to any node such as `BrowseName` or `NodeId`) or by specifying the type of argument within angle brackets
45 | - Example:
46 |     - `var myfolder = Project.Current.Get<Folder>("Model\MyFolder");`
47 | 
48 | Using this type passing option, the returned node is `null` if:
49 | - Node does not exist
50 | - The node does not match the specified type (e.g: `MyFolder` is an `Object` and not a `Folder`)
51 | 
52 | ### Casting from IUANode
53 | 
54 | A cast is an explicit conversion, to perform a cast, specify the type that you are casting to in parentheses in front of the value or variable to be converted.
55 |     - Example:
56 |         - `var myfolder = (Folder)Project.Current.Get("Model\MyFolder");`
57 | 
58 | Using this casting option, the node is returned as null only if completely missing, if the object type cannot be casted, an exception is thrown.
59 | 
60 | ### Summary
61 | 
62 | Result is very similar, as best practice we suggest to use the type passing approach unless casting is a specific requirement to achieve the result
63 | 


--------------------------------------------------------------------------------
/pages/advanced-svg.md:
--------------------------------------------------------------------------------
  1 | # Advanced SVG image
  2 | 
  3 | The AdvancedSVGImage container, supports direct manipulation of the image buffer, allowing for fast and direct access to the content, this allows runtime editing that can efficiently manipulate the path or properties of an SVG image without impacting the InformationModel
  4 | 
  5 | This feature was introduced in FT Optix 1.4.x
  6 | 
  7 | ## Sample image
  8 | 
  9 | This is the sample image (containing a "star" shape) that we used in the examples below to be animated
 10 | 
 11 | ```svg
 12 | <?xml version="1.0" encoding="iso-8859-1"?>
 13 | <svg version="1.1" id="Overall" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" viewBox="0 0 300 300">
 14 |   <g id="MyPaths" opacity="1.0">
 15 | 	  <path style="fill:#3C4660;" d="M 0 67.2262 L 72.1921 67.2262 L 94.5 0 L 116.8079 67.2262 L 189 67.2262 L 130.5954 108.7738 L 152.9045 176 L 94.5 134.4513 L 36.0954 176 L 58.4045 108.7738 L 0 67.2262 Z" transform="rotate(0, 150, 219)"/>
 16 |   </g>
 17 |   <g id="Box1">
 18 |     <polygon style="fill:#CB8252;" points="25,270 75,270 75,220 25,220" transform="rotate(0, 20, 20)"/>
 19 |   </g>
 20 | </svg>
 21 | ```
 22 | 
 23 | ## Making the image disappear
 24 | 
 25 | ```csharp
 26 | [ExportMethod]
 27 | public void replaceSVG()
 28 | {
 29 |     // LogicObject.Owner is the button, so LogicObject.Owner is the MainWindow
 30 |     AdvancedSVGImage svgImage = LogicObject.Owner.Get<AdvancedSVGImage>("AdvancedSVGImage1");
 31 | 
 32 |     string myXML = "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>\r\n<svg version=\"1.1\" id=\"Overall\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xml:space=\"preserve\" viewBox=\"0 0 300 300\">\r\n  <g id=\"Box1\">\r\n    <polygon style=\"fill:#CB8252;\" points=\"25,270 75,270 75,220 25,220\" transform=\"rotate(0, 20, 20)\"/>\r\n  </g>\r\n</svg>\r\n";
 33 | 
 34 |     //Update the SVG
 35 |     svgImage.SetImageContent(myXML);
 36 | }
 37 | ```
 38 | 
 39 | ## Rotate the image
 40 | 
 41 | ```csharp
 42 | #region Using directives
 43 | using FTOptix.NetLogic;
 44 | using FTOptix.UI;
 45 | using System.Xml.Linq;
 46 | using System.Linq;
 47 | using UAManagedCore;
 48 | using System.Threading;
 49 | #endregion
 50 | 
 51 | public class RuntimeNetLogic1 : BaseNetLogic
 52 | {
 53 |     public override void Start()
 54 |     {
 55 |         // LogicObject.Owner is the button, so LogicObject.Owner is the MainWindow
 56 |         svgImage = LogicObject.Owner.Get<AdvancedSVGImage>("AdvancedSVGImage1");
 57 |         // Retrieve the Path to the SVG
 58 |         var imageAbsolutePath = svgImage.Path.Uri;
 59 |         // Load the SVG into an XDocument
 60 |         xDocument = XDocument.Load(imageAbsolutePath);
 61 |         // Find the first path element
 62 |         var pathNode = xDocument.Descendants().Where(x => x.Name.LocalName == "path").FirstOrDefault();
 63 |         // Find the first polygon element
 64 |         var polyNode = xDocument.Descendants().Where(x => x.Name.LocalName == "polygon").FirstOrDefault();
 65 |         // Get the polygon transform attribute
 66 |         polyTransformAttribute = polyNode.Attribute("transform");
 67 |         // Get the polygon transform attribute
 68 |         pathTransformAttribute = pathNode.Attribute("transform");
 69 |     }
 70 | 
 71 |     public override void Stop()
 72 |     {
 73 |         keepGoing = false;
 74 |         if (myLRT != null)
 75 |             myLRT.Dispose();
 76 |     }
 77 | 
 78 |     private void doRotate()
 79 |     {
 80 |         int degrees = 3;
 81 |         while (keepGoing)
 82 |         {
 83 |             Thread.Sleep(50);
 84 |             degrees += 3;
 85 |             if (degrees > 360)
 86 |                 degrees = 0;
 87 |             string newTransformPoly = new string("rotate(" + degrees + ", 50, 250)");
 88 |             polyTransformAttribute.SetValue(newTransformPoly);
 89 |             string newTransformPath = new string("rotate(" + degrees + ", 96, 97)");
 90 |             pathTransformAttribute.SetValue(newTransformPath);
 91 |             //Update the SVG
 92 |             svgImage.SetImageContent(xDocument.ToString());
 93 |         }
 94 |     }
 95 | 
 96 |     [ExportMethod]
 97 |     public void rotateSVG()
 98 |     {
 99 |         keepGoing = false;
100 |         if (myLRT != null)
101 |             myLRT.Dispose();
102 |         keepGoing = true;
103 |         myLRT = new LongRunningTask(doRotate, LogicObject);
104 |         myLRT.Start();
105 |     }
106 | 
107 |     private XDocument xDocument;
108 |     private AdvancedSVGImage svgImage;
109 |     private XAttribute polyTransformAttribute;
110 |     private XAttribute pathTransformAttribute;
111 |     private LongRunningTask myLRT;
112 |     private bool keepGoing = true;
113 | }
114 | ```
115 | 
116 | 


--------------------------------------------------------------------------------
/pages/alarming.md:
--------------------------------------------------------------------------------
  1 | # Alarms
  2 | 
  3 | ## Create alarms at Runtime
  4 | 
  5 | ```csharp
  6 | #region Using directives
  7 | using FTOptix.Alarm;
  8 | using FTOptix.Core;
  9 | using FTOptix.HMIProject;
 10 | using FTOptix.NetLogic;
 11 | using FTOptix.UI;
 12 | using UAManagedCore;
 13 | using OpcUa = UAManagedCore.OpcUa;
 14 | #endregion
 15 | 
 16 | public class RuntimeAlarmsLogic : BaseNetLogic
 17 | {
 18 |     public override void Start() 
 19 |     {
 20 |         // Insert code to be executed when the user-defined logic is started
 21 |         DetectAlarmType();
 22 |     }
 23 | 
 24 |     public override void Stop()
 25 |     {
 26 |         // Insert code to be executed when the user-defined logic is stopped
 27 |     }
 28 | 
 29 |     [ExportMethod]
 30 |     public void DetectAlarmType()
 31 |     {
 32 |         // Check which alarm type we need to create and display the related info on a Label
 33 |         var targetLabel = Owner.Get<Label>("AlarmType");
 34 |         var alarmTag = InformationModel.GetVariable(Owner.Get<ComboBox>("SourceVar").SelectedItem);
 35 |         if (alarmTag.DataType == OpcUa.DataTypes.Boolean)
 36 |         {
 37 |             targetLabel.LocalizedText = new LocalizedText(targetLabel.NodeId.NamespaceIndex, "DigitalAlarm");
 38 |         }
 39 |         else
 40 |         {
 41 |             targetLabel.LocalizedText = new LocalizedText(targetLabel.NodeId.NamespaceIndex, "AnalogAlarm");
 42 |         }
 43 |     }
 44 | 
 45 |     [ExportMethod]
 46 |     public void CreateAlarm()
 47 |     {
 48 |         // Get the alarms container
 49 |         var alarmsFolder = Project.Current.Get<Folder>("Alarms/RuntimeAlarms");
 50 |         var alarmTag = InformationModel.GetVariable(Owner.Get<ComboBox>("SourceVar").SelectedItem);
 51 |         var existingAlarm = alarmsFolder.Get(alarmTag.BrowseName) ?? null;
 52 |         // Check if alarm already exist (skip) or create new based on DataType
 53 |         if (existingAlarm == null)
 54 |         {
 55 |             if (alarmTag.DataType == OpcUa.DataTypes.Boolean)
 56 |             {
 57 |                 var newAlarm = InformationModel.MakeObject<DigitalAlarm>(alarmTag.BrowseName);
 58 |                 newAlarm.InputValueVariable.SetDynamicLink(alarmTag);
 59 |                 newAlarm.Message = Owner.Get<TextBox>("AlarmMessage").Text;
 60 |                 newAlarm.AutoAcknowledge = true;
 61 |                 newAlarm.AutoConfirm = true;
 62 |                 alarmsFolder.Add(newAlarm);
 63 |             }
 64 |             else
 65 |             {
 66 |                 var newAlarm = InformationModel.MakeObject<ExclusiveLevelAlarmController>(alarmTag.BrowseName);
 67 |                 newAlarm.InputValueVariable.SetDynamicLink(alarmTag);
 68 |                 newAlarm.Message = Owner.Get<TextBox>("AlarmMessage").Text;
 69 |                 newAlarm.HighLimit = 50;
 70 |                 newAlarm.AutoAcknowledge = true;
 71 |                 newAlarm.AutoConfirm = true;
 72 |                 alarmsFolder.Add(newAlarm);
 73 |             }
 74 |         }
 75 |     }
 76 |     
 77 |     [ExportMethod]
 78 |     public void DeleteAlarm()
 79 |     {
 80 |         // Delete alarm if exist
 81 |         var alarmsFolder = Project.Current.Get<Folder>("Alarms/RuntimeAlarms");
 82 |         var alarmTag = InformationModel.GetVariable(Owner.Get<ComboBox>("SourceVar").SelectedItem);
 83 |         var existingAlarm = alarmsFolder.Get(alarmTag.BrowseName) ?? null;
 84 |         existingAlarm?.Delete();
 85 |     }
 86 | }
 87 | 
 88 | ```
 89 | 
 90 | ## Subscribe to new alarms and get notified at every Acknowledge or Confirm event
 91 | 
 92 | ```csharp
 93 | #region Using directives
 94 | using System;
 95 | using UAManagedCore;
 96 | using OpcUa = UAManagedCore.OpcUa;
 97 | using FTOptix.UI;
 98 | using FTOptix.NativeUI;
 99 | using FTOptix.HMIProject;
100 | using FTOptix.Retentivity;
101 | using FTOptix.CoreBase;
102 | using FTOptix.Core;
103 | using FTOptix.NetLogic;
104 | using FTOptix.Alarm;
105 | using System.Collections.Generic;
106 | using LogsHandler;
107 | using System.Transactions;
108 | #endregion
109 | 
110 | public class AlarmsObserverLogic : BaseNetLogic
111 | {
112 |     public override void Start()
113 |     {
114 |         // Get the affinity ID of the current NetLogic to avoid cross thread issues
115 |         affinityId = LogicObject.Context.AssignAffinityId();
116 |         // Create the observer to check when alarms are created and/or deleted
117 |         StartObserver();
118 |     }
119 | 
120 |     public override void Stop()
121 |     {
122 |         // Destroy the observer when closing the NetLogic
123 |         alarmsCreationObserver?.Dispose();
124 |     }
125 | 
126 |     public void StartObserver()
127 |     {
128 |         // Get the alarms server object
129 |         var retainedAlarmsObject = LogicObject.Context.GetNode(FTOptix.Alarm.Objects.RetainedAlarms);
130 |         // Get the object containing the actual list of alarms
131 |         var localizedAlarmsObject = retainedAlarmsObject.GetVariable("LocalizedAlarms");
132 |         var localizedAlarmsNodeId = (NodeId) localizedAlarmsObject.Value;
133 |         IUANode localizedAlarmsContainer = null;
134 |         if (localizedAlarmsNodeId?.IsEmpty == false)
135 |             localizedAlarmsContainer = LogicObject.Context.GetNode(localizedAlarmsNodeId);
136 |         if (localizedAlarmsContainer == null)
137 |         {
138 |             Log.Error("AlarmsObserverLogic", "LocalizedAlarms node not found");
139 |             return;
140 |         }
141 |         // Create a new custom alarms observer
142 |         var logsObserver = new AlarmsCreationObserver();
143 |         // Register the observer to the server node
144 |         alarmsCreationObserver = localizedAlarmsContainer.RegisterEventObserver(
145 |             logsObserver, // Which observer to use
146 |             EventType.ForwardReferenceAdded | // Register when alarms are created
147 |             EventType.ForwardReferenceRemoved, // Register when alarms are disposed
148 |             affinityId); // Pass the affinity ID
149 |     }
150 | 
151 |     private IEventRegistration alarmsCreationObserver;
152 |     private uint affinityId; // This can also be moved to a local variable
153 | }
154 | 
155 | namespace LogsHandler
156 | {
157 |     class AlarmsCreationObserver : IReferenceObserver
158 |     {
159 |         public AlarmsCreationObserver()
160 |         {
161 |             // Just create the class instance, nothing really to do
162 |             Log.Info("LogsEventObserver", "Starting alarms observer");
163 |         }
164 | 
165 |         public void OnReferenceAdded(IUANode sourceNode, IUANode targetNode, NodeId referenceTypeId, ulong senderId)
166 |         {
167 |             // When an alarm gets activated it will be added as reference to the RetainedAlarms object
168 |             // Here a custom logic can be added to trigger some actions
169 |             Log.Info("LogsEventObserver", $"{targetNode.BrowseName} alarm got enabled");
170 | 
171 |             // Subscribe to some variables (can be customized as needed)
172 |             try
173 |             {
174 |                 if (targetNode is not UAObject alarmNode)
175 |                 {
176 |                     Log.Error("LogsEventObserver", "Alarm node is invalid");
177 |                     return;
178 |                 }
179 | 
180 |                 // Trigger the VariableChange to some variables, can be customized to call different methods if needed
181 |                 alarmNode.GetVariable("ActiveState/Id").VariableChange += AlarmsCreationObserver_VariableChange;
182 |                 alarmNode.GetVariable("AckedState/Id").VariableChange += AlarmsCreationObserver_VariableChange;
183 |                 alarmNode.GetVariable("ConfirmedState/Id").VariableChange += AlarmsCreationObserver_VariableChange;
184 |             }
185 |             catch
186 |             {
187 |                 Log.Error("LogsEventObserver", "Error while trying to subscribe to alarm variables");
188 |             }
189 |         }
190 | 
191 |         // Method to be called whenever a variable changes in value
192 |         private void AlarmsCreationObserver_VariableChange(object sender, VariableChangeEventArgs e)
193 |         {
194 |             // Do something when variables are changing
195 |             var variable = sender as IUAVariable;
196 |             Log.Info("LogsEventObserver", $"{variable.Owner.BrowseName} alarm status changed to {e.NewValue}");
197 |         }
198 | 
199 |         public void OnReferenceRemoved(IUANode sourceNode, IUANode targetNode, NodeId referenceTypeId, ulong senderId)
200 |         {
201 |             // Do something when the alarms deactivates
202 |             Log.Info("LogsEventObserver", $"{targetNode.BrowseName} alarm got removed");
203 |         }
204 |     }
205 | }
206 | ```
207 | 
208 | ## Get the originating alarm from the RetainedAlarms object
209 | 
210 | ```csharp
211 | /// <summary>
212 | /// Retrieves the <see cref="AlarmController"/> associated with the given retained alarm ID.
213 | /// </summary>
214 | /// <param name="retainedAlarmId">The <see cref="NodeId"/> of the alarm in the RetainedAlarm object.</param>
215 | /// <returns>The <see cref="AlarmController"/> associated with the retained alarm.</returns>
216 | /// <exception cref="System.ArgumentException">Thrown when the alarm is not found.</exception>
217 | private static AlarmController GetAlarmFromRetainedAlarm(NodeId retainedAlarmId)
218 | {
219 |     // Get the alarm controller from the retained alarm
220 |     var retainedAlarm = InformationModel.Get(retainedAlarmId);
221 |     // Get the alarm controller from the retained alarm
222 |     return InformationModel.Get<AlarmController>(retainedAlarm.GetVariable("ConditionId").Value) ?? throw new System.ArgumentException("Alarm not found");
223 | }
224 | ```
225 | 
226 | ## Acknowledge and Confirm multiple alarms from a DataGrid
227 | 
228 | > [!WARNING]
229 | > The multi selection feature can only be used in the AlarmGrid component. The standard DataGrid object does not support multi selection and forcing it may cause unexpected results.
230 | 
231 | ```csharp
232 | public class AlarmGridLogic : BaseNetLogic
233 | {
234 |     public override void Start()
235 |     {
236 |         alarmsDataGridModel = Owner.Get<DataGrid>("AlarmsDataGrid").GetVariable("Model");
237 |     }
238 | 
239 |     /// <summary>
240 |     /// Acknowledges the selected alarms with a specified message.
241 |     /// </summary>
242 |     /// <param name="ackMessage">The acknowledgment message.</param>
243 |     [ExportMethod]
244 |     public void AckAlarmsWithMessage(LocalizedText ackMessage)
245 |     {
246 |         ProcessAlarms(ackMessage, (alarm, message) => alarm.Acknowledge(message));
247 |     }
248 | 
249 |     /// <summary>
250 |     /// Confirms the selected alarms with a specified message.
251 |     /// </summary>
252 |     /// <param name="confirmMessage">The confirmation message.</param>
253 |     [ExportMethod]
254 |     public void ConfirmAlarmsWithMessage(LocalizedText confirmMessage)
255 |     {
256 |         ProcessAlarms(confirmMessage, (alarm, message) => alarm.Confirm(message));
257 |     }
258 | 
259 |     #region Private methods
260 | 
261 |     /// <summary>
262 |     /// Processes the selected alarms with a specified action.
263 |     /// </summary>
264 |     /// <param name="message">The message to be used for the action.</param>
265 |     /// <param name="alarmAction">The action to be performed on the alarms.</param>
266 |     private void ProcessAlarms(LocalizedText message, Action<AlarmController, LocalizedText> alarmAction)
267 |     {
268 |         var dataGrid = Owner.Get<DataGrid>("AlarmsDataGrid");
269 | 
270 |         if (dataGrid.GetVariable("AllowMultiSelection").Value)
271 |         {
272 |             // Multi selection
273 |             var selectedItemsNodes = dataGrid.GetOptionalVariableValue("UISelectedItems") ?? throw new System.ArgumentException("UISelectedItems variable not found in AlarmsDataGrid");
274 | 
275 |             var selectedItemsArray = (NodeId[]) selectedItemsNodes.Value;
276 |             if (selectedItemsArray == null || selectedItemsArray.Length == 0)
277 |             {
278 |                 throw new System.ArgumentException("No alarms selected");
279 |             }
280 | 
281 |             // Process each selected alarm
282 |             foreach (var nodeId in selectedItemsArray)
283 |             {
284 |                 var alarm = GetAlarmFromRetainedAlarm(nodeId) ?? throw new System.ArgumentException("Alarm not found");
285 |                 alarmAction(alarm, message);
286 |             }
287 |         }
288 |         else
289 |         {
290 |             // Single selection
291 |             var alarm = GetAlarmFromRetainedAlarm(dataGrid.UISelectedItem) ?? throw new System.ArgumentException("Alarm not found");
292 |             alarmAction(alarm, message);
293 |         }
294 |     }
295 | 
296 |     /// <summary>
297 |     /// Retrieves the <see cref="AlarmController"/> associated with the given retained alarm ID.
298 |     /// </summary>
299 |     /// <param name="retainedAlarmId">The <see cref="NodeId"/> of the retained alarm.</param>
300 |     /// <returns>The <see cref="AlarmController"/> associated with the retained alarm.</returns>
301 |     /// <exception cref="System.ArgumentException">Thrown when the alarm is not found.</exception>
302 |     private static AlarmController GetAlarmFromRetainedAlarm(NodeId retainedAlarmId)
303 |     {
304 |         // Get the alarm controller from the retained alarm
305 |         var retainedAlarm = InformationModel.Get(retainedAlarmId);
306 |         // Get the alarm controller from the retained alarm
307 |         return InformationModel.Get<AlarmController>(retainedAlarm.GetVariable("ConditionId").Value) ?? throw new System.ArgumentException("Alarm not found");
308 |     }
309 | 
310 |     #endregion
311 | 
312 |     #endregion
313 | 
314 |     private IUAVariable alarmsDataGridModel;
315 | }
316 | ```


--------------------------------------------------------------------------------
/pages/async-tasks.md:
--------------------------------------------------------------------------------
  1 | # Asynchronous tasks
  2 | 
  3 | Asynchronous tasks are very common when executing special or long tasks that may negatively impact the overall execution
  4 | 
  5 | ## General concepts about Asynchronous tasks
  6 | 
  7 | Standard C# language provides multiple ways to execute asynchronous operations (such as the `async` modifier for some methods), these can be used in FT Optix as long as those methods does not access any of the project structure (pages, tags, etc).
  8 | 
  9 | - Example:
 10 |     - async method to read/write a CSV -> GOOD
 11 |     - async method to read a CSV and import it into the TranslationDictionary -> BAD
 12 | 
 13 | ## Using FT Optix Asynchronous tasks
 14 | 
 15 | These asynchronous tasks are InformationModel-safe and can be used to access project nodes without concerns
 16 | 
 17 | ### PeriodicTask
 18 | 
 19 | This kind of task allows a specific method to be executed every `x` milliseconds, for example to blink a LED or to handle a watchdog.
 20 | 
 21 | Please note: the specified interval, is actually the delay between two consecutive execution of the method, and the execution is impacted by the length of the instruction to process. The next execution is delayed until the task is completed, for example:
 22 | 
 23 | Having a task:
 24 | - PeriodicTask declared every 50mS
 25 | - Method executed by the PeriodicTask takes 100mS to process
 26 | 
 27 | With this timings, the task is actually executed every 150mS, as the interval is actually the delay after which the task is executed again.
 28 | 
 29 | ```csharp
 30 | public override void Start()
 31 | {
 32 |     // Creates a task that runs every second without impacting the UI
 33 |     myPeriodicTask = new PeriodicTask(IncrementVariable, 1000, LogicObject);
 34 |     myPeriodicTask.Start();
 35 | }
 36 | 
 37 | public override void Stop()
 38 | {
 39 |     // When the NetLogic is disposed, kill the task too
 40 |     myPeriodicTask?.Dispose();
 41 | }
 42 | 
 43 | private void IncrementVariable()
 44 | {
 45 |     // Action to be executed every tick of the periodic task
 46 |     …
 47 | }
 48 | 
 49 | private PeriodicTask myPeriodicTask;
 50 | ```
 51 | 
 52 | ### DelayedTask
 53 | 
 54 | This kind of task will trigger a method after `x` milliseconds it is called, this can be useful for example to hide a toast notification after some time
 55 | 
 56 | ```csharp
 57 | public override void Start()
 58 | {
 59 |     // Create an action that is executed after 10s the page is loaded
 60 |     // this could also be a method called by a button or any trigger
 61 |     myDelayedTask = new DelayedTask(ResetLabelText, 10000, LogicObject);
 62 |     myDelayedTask.Start();
 63 | }
 64 | 
 65 | public override void Stop()
 66 | {
 67 |     // Make sure to dispose the task when the NetLogic is stopped
 68 |     myDelayedTask?.Dispose();
 69 | }
 70 | 
 71 | private void ResetLabelText()
 72 | {
 73 |     // Action to be executed after the delay
 74 |     …
 75 | }
 76 | 
 77 | private DelayedTask myDelayedTask;
 78 | ```
 79 | 
 80 | ### LongRunningTask
 81 | 
 82 | This is the most similar approach to the `async` modifier of the standard C# scripting, it allows to create a dedicated thread and execute it without affecting the main code execution.
 83 | An `async` modifier can also be used, but an async method **cannot** access any project node (it may cause concurrency issues), in such cases, use a LongRunningTask instead.
 84 | 
 85 | ```csharp
 86 | class public override void Start()
 87 | {
 88 |     // Create a dedicated thread to run a long or demanding process
 89 |     // Without stopping the FT Optix Runtime or Studio
 90 |     myLongRunningTask = new LongRunningTask(ProcessCSVFile, LogicObject);
 91 |     myLongRunningTask.Start();
 92 | }
 93 | 
 94 | public override void Stop()
 95 | {
 96 |     // Make sure to dispose the thread once the NetLogic is stopped
 97 |     myLongRunningTask?.Dispose();
 98 | }
 99 | 
100 | private void ProcessCsvFile(LongRunningTask task)
101 | {
102 |     // Process that takes long time to be executed
103 |     …
104 | }
105 | 
106 | private LongRunningTask myLongRunningTask;
107 | ```
108 | 
109 | #### Passing arguments to a LongRunningTask
110 | 
111 | An overload of the LongRunningTask constructor accepts a task and an object, the task can be used to check if a cancellation was requested, while the object can be used to pass arguments to the thread that is being generated
112 | 
113 | ```csharp
114 | [ExportMethod]
115 | public void StartExam(bool free, string clientID = "", string examCode = "")
116 | {
117 |     Log.Debug(examCode == "" ? "ExamLogic.StartExam" : "ExamLogic.StartExamCertification", "Starting exam");
118 |     startExamTask?.Dispose();
119 |     var argumentsObject = new StartExamParameters { isFree = free, clientID = clientID, examCode = examCode };
120 |     startExamTask = new LongRunningTask(StartExamMethod, argumentsObject, LogicObject);
121 |     startExamTask.Start();
122 |     Log.Debug(examCode == "" ? "ExamLogic.StartExam" : "ExamLogic.StartExamCertification", "Leaving method");
123 | }
124 | 
125 | private void StartExamMethod(LongRunningTask task, object examParameters)
126 | {
127 |     // Get the parameters
128 |     var argumentsObject = (StartExamParameters)examParameters;
129 |     string clientID = argumentsObject.clientID;
130 |     string examCode = argumentsObject.examCode;
131 |     bool free = argumentsObject.isFree;
132 |     // Do other stuff
133 |     // ...
134 | }
135 | 
136 | private sealed class StartExamParameters
137 | {
138 |     public bool isFree;
139 |     public string clientID;
140 |     public string examCode;
141 | }
142 | 
143 | private LongRunningTask startExamTask = null;
144 | ```
145 | 
146 | ## Some general notes on asynchronous tasks
147 | 
148 | ### Cancellation token
149 | 
150 | When a task is called asynchronously (especially in LongRunningTask), then the method itself should check if a cancellation request is pending (see [documentation here](https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/task-cancellation)) and act accordingly, for example:
151 | 
152 | ```csharp
153 | public class LongRunningLogic : BaseNetLogic
154 | {
155 |     public override void Start()
156 |     {
157 |         // Create the new LongRunningTask and execute it
158 |         myTask = new LongRunningTask(MyMethod, LogicObject);
159 |         myTask.Start();
160 |     }
161 | 
162 |     public override void Stop()
163 |     {
164 |         // Request a cancellation event to the async task
165 |         myTask?.Dispose();
166 |     }
167 | 
168 |     public void MyMethod()
169 |     {
170 |         for (int i = 0; i < 1000; i++)
171 |         {
172 |             // Check if the somebody requested to dispose this task
173 |             if (myTask.IsCancellationRequested)
174 |                 return;
175 |             // Do some work here
176 |             Thread.Sleep(1000);
177 |             Owner.Get<Led>("LED1").Active = !Owner.Get<Led>("LED1").Active;
178 |         }
179 |     }
180 | 
181 |     private LongRunningTask myTask;
182 | }
183 | ```
184 | 
185 | ### Check if a task is running
186 | 
187 | > [!WARNING]
188 | > This is a non-public API (accessed using C# reflections) and may be subject to changes, please refer to the official documentation to access the publicly available APIs which are guaranteed to be maintained.
189 | 
190 | ```csharp
191 | [ExportMethod]
192 | public void DoStuff()
193 | {
194 |     // Initialize the LongRunningTask
195 |     var myTask = new LongRunningTask(MyMethod, LogicObject);
196 | 
197 |     // Do some stuff
198 | 
199 |     // Check if the task is still running
200 |     while (IsTaskRunning(task))
201 |     {
202 |         Log.Info("The task is still running...");
203 |         Thread.Sleep(100);
204 |     }
205 | }
206 | 
207 | private void MyMethod(LongRunningTask task)
208 | {
209 |     // Do some work
210 |     throw new NotImplementedException();
211 | }
212 | 
213 | private static bool IsTaskRunning(LongRunningTask task)
214 | {
215 |     // Get the type of the LongRunningTask
216 |     Type taskType = task.GetType();
217 | 
218 |     // Get the FieldInfo object for the isRunning field
219 |     FieldInfo isRunningField = taskType.GetField("isRunning", BindingFlags.NonPublic | BindingFlags.Instance);
220 | 
221 |     // Check if the field was found
222 |     if (isRunningField != null)
223 |     {
224 |         // Get the value of the isRunning field
225 |         bool isRunning = (bool) isRunningField.GetValue(task);
226 |         return isRunning;
227 |     }
228 |     else
229 |     {
230 |         throw new InvalidOperationException("The isRunning field was not found on the LongRunningTask type.");
231 |     }
232 | }
233 | ```
234 | 


--------------------------------------------------------------------------------
/pages/audit-signature.md:
--------------------------------------------------------------------------------
 1 | # Audit Signature (CFR21 workflow)
 2 | 
 3 | ## Add signature to a variable
 4 | 
 5 | ```csharp
 6 | [ExportMethod]
 7 | public void AddSignatureToVariable()
 8 | {
 9 |     var sourceVarPointer = LogicObject.GetVariable("SourceVariable") ?? throw new ArgumentException("Cannot find source variable");
10 |     var sourceVar = InformationModel.GetVariable(sourceVarPointer.Value) ?? throw new ArgumentException("Cannot find source variable");
11 |     // Create the audit variable
12 |     var sourceVar = InformationModel.Make<AuditInfo>("AuditSigning Signature");
13 |     sourceVar.Add(auditVar);
14 | }
15 | ```
16 | 
17 | ## Add signature on all bits of a word
18 | 
19 | ```csharp
20 | [ExportMethod]
21 | public void CreateAuditOnVariableSingleBits()
22 | {
23 |     // Check if InputVariable is populated
24 |     var sourceVarPointer = LogicObject.GetVariable("SourceVariable") ?? throw new ArgumentException("Cannot find source variable");
25 |     var sourceVar = InformationModel.GetVariable(sourceVarPointer.Value) ?? throw new ArgumentException("Cannot find source variable");
26 | 
27 |     // Check if TargetFolder is populated
28 |     var targetFolderPointer = LogicObject.GetVariable("TargetFolder") ?? throw new ArgumentException("Cannot find target folder");
29 |     var targetFolder = InformationModel.Get<Folder>(targetFolderPointer.Value) ?? throw new ArgumentException("Cannot find target folder");
30 | 
31 |     // Prepare object for the method
32 |     var methodArguments = new object[] { sourceVar, targetFolder };
33 | 
34 |     // Execute the method in a separate thread
35 |     var myTask = new LongRunningTask(CreateSingleBits, methodArguments, LogicObject);
36 |     myTask.Start();
37 | }
38 | 
39 | private void CreateSingleBits(LongRunningTask task, object methodArgumentsObj)
40 | {
41 |     // Extract the method arguments
42 |     var methodArguments = (object[]) methodArgumentsObj;
43 |     var sourceVar = (IUAVariable) methodArguments[0];
44 |     var targetFolder = (Folder) methodArguments[1];
45 | 
46 |     // Variable to store the number of bits
47 |     var numberOfBits = 0;
48 | 
49 |     // Get the type of the source variable. Add new datatypes if needed
50 |     if (sourceVar.DataType == OpcUa.DataTypes.Int32 || sourceVar.DataType == OpcUa.DataTypes.UInt32)
51 |         numberOfBits = 32;
52 |     else if (sourceVar.DataType == OpcUa.DataTypes.Int16 || sourceVar.DataType == OpcUa.DataTypes.UInt16)
53 |         numberOfBits = 16;
54 |     else if (sourceVar.DataType == OpcUa.DataTypes.Float)
55 |         numberOfBits = 32;
56 |     else if (sourceVar.DataType == OpcUa.DataTypes.Double)
57 |         numberOfBits = 64;
58 |     else
59 |         throw new ArgumentException("Unsupported data type");
60 | 
61 |     // Create the variable for each bit and add the auditing
62 |     for (int i = 0; i < numberOfBits; i++)
63 |     {
64 |         // Create the new variable
65 |         var newVariable = InformationModel.MakeVariable($"{sourceVar.BrowseName}_Bit{i}", OpcUa.DataTypes.Boolean);
66 |         newVariable.SetDynamicLink(sourceVar, DynamicLinkMode.ReadWrite);
67 | 
68 |         // Modify the dynamic link to read only the bit
69 |         var dynamicLinkVariable = newVariable.GetVariable("DynamicLink");
70 |         dynamicLinkVariable.Value = dynamicLinkVariable.Value.Value + $".{i}";
71 | 
72 |         // Create the audit variable
73 |         var auditVar = InformationModel.Make<AuditInfo>("AuditSigning Signature");
74 |         newVariable.Add(auditVar);
75 | 
76 |         // Check if the variable already exists and delete it
77 |         if (targetFolder.Children.OfType<IUAVariable>().Any(v => v.BrowseName == newVariable.BrowseName))
78 |             targetFolder.Get(newVariable.BrowseName).Delete();
79 | 
80 |         // Add the variable to the target folder
81 |         targetFolder.Add(newVariable);
82 |     }
83 | }
84 | ```


--------------------------------------------------------------------------------
/pages/colors.md:
--------------------------------------------------------------------------------
 1 | # Colors
 2 | 
 3 | FT Optix can interact with the color of the objects and also create custom colors
 4 | 
 5 | ```csharp
 6 | // Create a Led
 7 | var myObject = InformationModel.Make<Led>("myLabel");
 8 | // Set Color to any valid RGB color
 9 | var myCustomColor = new Color(0xff, 0xaa, 0xbb, 0xcc);
10 | // Set the Led color to the new color
11 | myObject.Color = myCustomColor;
12 | // Add the Led to the page
13 | ...
14 | ```
15 | 
16 | ```csharp
17 | // Create a Led
18 | var myObject = InformationModel.Make<Led>("myLabel");
19 | // Set the Led color to Red
20 | myObject.Color = Colors.Red;
21 | // Add the Led to the page
22 | ...
23 | ```
24 | 
25 | ```csharp
26 | // Create a Led
27 | var myObject = InformationModel.Make<Led>("myLabel");
28 | // Set the Led color with System color Goldenrod by call method ToArgb to get the argb value
29 | myObject.Color = new Color(System.Drawing.Color.Goldenrod.ToArgb());;
30 | // Add the Led to the page
31 | ...
32 | ```
33 | 


--------------------------------------------------------------------------------
/pages/companion-specs.md:
--------------------------------------------------------------------------------
 1 | # Companion Specifications
 2 | 
 3 | ## Load Companion Specifications
 4 | 
 5 | - Companion Specifications files can be downloaded from [https://github.com/OPCFoundation/UA-Nodeset](https://github.com/OPCFoundation/UA-Nodeset)
 6 | - Add them to FT Optix in one of these paths (make sure to replace your username or the proper FT Optix setup folder):
 7 |     - `C:\Users\<username>\Documents\Rockwell Automation\FactoryTalk Optix\CompanionSpecifications`
 8 |     - `C:\Program Files\Rockwell Automation\FactoryTalk Optix\Studio <version number>\CompanionSpecifications`
 9 | - Restart the IDE after adding files to one of those paths to load new files
10 |     - Check the FT Optix output if any error was reported after loading the files
11 | 
12 | ## Create an instance of a Companion Specs type
13 | 
14 | Please make sure the proper XML file was added to FT Optix before executing the script
15 | 
16 | We will load an instance of the BlockType object from the DI specifications, the XML relevant part is:
17 | 
18 | ```xml
19 | <?xml version="1.0" encoding="utf-8"?>
20 |     <UANodeSet LastModified="2023-04-13T14:49:52.318Z" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://opcfoundation.org/UA/2011/03/UANodeSet.xsd" xmlns:uax="http://opcfoundation.org/UA/2008/02/Types.xsd" xmlns:si="http://www.siemens.com/OPCUA/2017/SimaticNodeSetExtensions" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s1="http://opcfoundation.org/UA/Machinery/ProcessValues/Types.xsd" xmlns:s2="http://opcfoundation.org/UA/PADIM/Types.xsd" xmlns:ua="http://unifiedautomation.com/Configuration/NodeSet.xsd">
21 |     <NamespaceUris>
22 |         <Uri>http://opcfoundation.org/UA/DI/</Uri>
23 |     </NamespaceUris>
24 | 
25 | ...
26 | 
27 |     <UAObjectType IsAbstract="true" NodeId="ns=1;i=1003" BrowseName="1:BlockType">
28 |         <DisplayName>BlockType</DisplayName>
29 |         <Description>Adds the concept of Blocks needed for block-oriented FieldDevices</Description>
30 |         <Documentation>https://reference.opcfoundation.org/v105/DI/v103/docs/4.11</Documentation>
31 |         <References>
32 |             <Reference ReferenceType="HasSubtype" IsForward="false">ns=1;i=1001</Reference>
33 |             <Reference ReferenceType="HasProperty">ns=1;i=6009</Reference>
34 |             <Reference ReferenceType="HasProperty">ns=1;i=6010</Reference>
35 |             <Reference ReferenceType="HasProperty">ns=1;i=6011</Reference>
36 |             <Reference ReferenceType="HasProperty">ns=1;i=6012</Reference>
37 |             <Reference ReferenceType="HasProperty">ns=1;i=6013</Reference>
38 |         </References>
39 |     </UAObjectType>
40 |     
41 | ...
42 | ```
43 | 
44 | From the XML we can see that the numeric identifier for the BlockType is `1003`, now in FT Optix we need to read the NameSpaceIndex. We will also need the NamespaceUri for that CompanionSpecs, in this case is `http://opcfoundation.org/UA/DI/`
45 | 
46 | ```csharp
47 | [ExportMethod]
48 | public void CreateCompanionSpecsInstance()
49 | {
50 |     Log.Info("Create Companion Specs NetLogic", "Searching NameSpaceIndex for companion spec");
51 |     // Get the NameSpaceIndex URI from the XML file
52 |     var nameSpaceIndex = LogicObject.Context.GetNamespaceIndex("http://opcfoundation.org/UA/DI/");
53 |     if (nameSpaceIndex == -1 || nameSpaceIndex == null)
54 |     {
55 |         Log.Error("Create Companion Specs NetLogic", "NameSpaceIndex not found, make sure the CompanionSpecification was properly loaded");
56 |         return;
57 |     }
58 |     else
59 |     {
60 |         Log.Info("Create Companion Specs NetLogic", "NameSpaceIndex found: " + nameSpaceIndex);
61 |     }
62 |     // The ID of the Type we want to add is 1003 - we can get this value from the specs XML file
63 |     var companionSpecsTypeNodeId = new NodeId(nameSpaceIndex, 1003);
64 |     // Create an instance of the element
65 |     Log.Info("Create Companion Specs NetLogic", "Type definition NodeId: " + companionSpecsTypeNodeId);
66 |     var instanceName = InformationModel.Get(companionSpecsTypeNodeId).BrowseName + "Instance";
67 |     var companionSpecsInstance = InformationModel.MakeObject(instanceName, companionSpecsTypeNodeId);
68 |     Project.Current.Get($"Model/{instanceName}")?.Delete();
69 |     // Optional, set a value to a children variable set as "optional" in the CompanionSpecs
70 |     // companionSpecsInstance.GetOrCreateVariable("RevisionCounter").Value = 100;
71 |     Project.Current.Get("Model").Add(companionSpecsInstance);
72 |     Log.Info("Create Companion Specs NetLogic", $"Companion Specs instance \"{instanceName}\" created and added to the model");
73 | }
74 | ```
75 | 


--------------------------------------------------------------------------------
/pages/creating-objects.md:
--------------------------------------------------------------------------------
  1 | # Creating elements
  2 | 
  3 | ## UI Elements
  4 | 
  5 | ### Add an element to the project
  6 | 
  7 | Native types are the one predefined in FTOptix, these are the most simple to create and add anywhere in the project. These types exists both at RunTime and DesignTime, so the syntax does not change depending on the execution
  8 | 
  9 | ```csharp
 10 | // Create a new Panel called "MyNewPanelName"
 11 | var newPanel = InformationModel.Make<Panel>("MyNewPanelName");
 12 | // Set some properties (if needed)
 13 | newPanel.Width = 300.0;
 14 | newPanel.HorizontalAlignment = HorizontalAlignment.Stretch;
 15 | // Add it to "UI/Screens/Screen1"
 16 | Project.Current.Get("UI/Screens/Screen1").Add(newPanel);
 17 | ```
 18 | 
 19 | #### Make it faster
 20 | 
 21 | When you need to create a lot of element in a short time (such in a `for` loop), adding each element to the page every time is not recommended as multiple async request are made to FTOptix APIs and some concurrency issues may appear, in this case we suggest to create the whole model in RAM and then add it to the page only when the whole structure is defined
 22 | 
 23 | ```csharp
 24 | // Create a container for the new elements
 25 | var tempPanel = InformationModel.Make<Panel>("MotorsGroup");
 26 | // Set the container to fill the parent item
 27 | tempPanel.HorizontalAlignment = HorizontalAlignment.Stretch;
 28 | tempPanel.VerticalAlignment = VerticalAlignment.Stretch;
 29 | // Create the 100 motors
 30 | for (i = 0; i < 100; i++) {
 31 |     // Create the new Panel widget
 32 |     var newPanel = InformationModel.Make<Panel>("MyMotor" + i.ToString());
 33 |     // Set some properties
 34 |     newPanel.Width = 300.0;
 35 |     newPanel.HorizontalAlignment = HorizontalAlignment.Stretch;
 36 |     // Add the Panel to the new container
 37 |     tempPanel.Add(newPanel);
 38 | }
 39 | // Finally, add the new container to the Screen (with all the elements)
 40 | Project.Current.Get("UI/Screens/Screen1").Add(tempPanel);
 41 | ```
 42 | 
 43 | ### `Panel` Assigning the value of Move Target property
 44 | 
 45 | The Move target property is an optional extra, so it must be materialized before any value can be set. When creating a Panel from NetLogic, this step is mandatory.
 46 | This property may be *None* or *Self*. As this property is a **NodePointer**, you must create a dynamicLink with value **..@NodeId** if you want to set **Self**, otherwise you must simply remove the DynamicLink to set **None**.
 47 | 
 48 | ```csharp
 49 | private void StuffMakePanelUIObject(IUANode panelOwner, string panelName, int width, int height, bool moveTargetSelf)
 50 | {
 51 |     // Get the owner of the Panel (in case we want to use the Panel to move the parent element)
 52 |     Panel panel = panelOwner.Get(panelName) as Panel;
 53 |     // Make sure the Panel exists
 54 |     if (panel == null)
 55 |     {
 56 |         panel = InformationModel.MakeObject<Panel>(panelName);
 57 |         panelOwner.Add(panel);
 58 |     }
 59 |     // Set some properties
 60 |     panel.Height = height;
 61 |     panel.Width = width;
 62 |     // Access the optional variable value
 63 |     IUAVariable moveTarget = panel.GetOrCreateVariable("MoveTarget"); 
 64 |     // Prepare the DynamicLink
 65 |     DynamicLink moveTargetLink = moveTarget?.GetVariable("DynamicLink") as DynamicLink;
 66 |     if (moveTarget != null && moveTargetSelf)
 67 |     {
 68 |         if (moveTargetLink == null)
 69 |         {
 70 |             // Add the destination for the NodeTarget (Owner)
 71 |             moveTargetLink = InformationModel.MakeVariable<DynamicLink>("DynamicLink", FTOptix.Core.DataTypes.NodePath);
 72 |             moveTargetLink.Value = "..@NodeId";
 73 |             moveTargetLink.Mode = DynamicLinkMode.Read;
 74 |             moveTarget.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, moveTargetLink);
 75 |         }
 76 |     }
 77 |     else
 78 |     {
 79 |         // Remove any existing dynamic link from the MoveTarget
 80 |         if (moveTargetLink != null)
 81 |         {
 82 |             moveTarget?.Refs.RemoveReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, moveTargetLink.NodeId);
 83 |         }
 84 |     }
 85 | }
 86 | ```
 87 | 
 88 | ### Custom UI types instances (widget instances)
 89 | 
 90 | When creating custom types or templates, the equivalent C# class is automatically created by FTOptix, then you can instantiate such classes with the same syntax
 91 | 
 92 | **Please note**: The user-defined types does not exists when executing scripts at DesignTime, so they should be treated as normal objects (see the DesignTime snippet below)
 93 | 
 94 | #### RunTime creation of UI instances
 95 | 
 96 | ```csharp
 97 | // This syntax is only valid at Runtime, while designing the app,
 98 | // the CustomMotorWidget class does not exist
 99 | var myCustomPanel = InformationModel.Make<CustomMotorWidget>("MotorWidget");
100 | // Add it to the page
101 | Owner.Add(myCustomPanel);
102 | ```
103 | 
104 | #### DesignTime creation of UI instances
105 | 
106 | ```csharp
107 | // This method works both at Runtime and Design-time
108 | // Get the original type to be instantiated
109 | var myCustomPanelType = Project.Current.Get("path/to/type")
110 | // Create an object by specifying the custom type
111 | var myCustomPanel = InformationModel.MakeObject("MotorWidget", myCustomPanelType.NodeId);
112 | // Add the new instance to the screen
113 | Project.Current.Get("UI/Screens/Screen1").Add(myCustomPanel);
114 | ```
115 | 
116 | ## IUAObjects
117 | 
118 | Objects are generic containers that can hold variables or other OPC/UA objects and instances
119 | 
120 | ### Create a custom Object type
121 | 
122 | ```csharp
123 | // Create a new Object Type
124 | var newObject = InformationModel.MakeObjectType("NewMotorType");
125 | // Add some properties to the Object type
126 | newObject.Add(InformationModel.MakeVariable("Speed", OpcUa.DataTypes.Int32));
127 | newObject.Add(InformationModel.MakeVariable("Power", OpcUa.DataTypes.Bool));
128 | // Add the Object Type to the Model folder
129 | Project.Current.Get("Model/Templates").Add(newObject);
130 | ```
131 | 
132 | ### DesignTime creation of custom Object instances
133 | 
134 | After the custom type has been created, new instances can be created with a slightly different syntax
135 | 
136 | ```csharp
137 | // Get the custom type definition
138 | var customType = Project.Current.Get("Model/Templates/CustomMotor");
139 | // Create the new object as instance of the custom type
140 | var customTypeInstance = InformationModel.MakeObject("MotorInstance1", customType.NodeId);
141 | // Add the new instance to the Model folder
142 | Project.Current.Get("Model/instances").Add(customTypeInstance);
143 | ```
144 | 
145 | ### RunTime creation of custom Object instances
146 | 
147 | ```csharp
148 | // This syntax only works at Runtime, 
149 | // get the MotorType class and create a new object
150 | var myObj = InformationModel.MakeObject<MotorType>("NewMotorInstance");
151 | // Add the object to the parent element
152 | Owner.Add(myObj);
153 | ```
154 | 
155 | ## Custom behavior
156 | 
157 | OPC/UA objects can expose custom OPC/UA methods that can be called from any connected client.
158 | 
159 | How to add a custom behavior:
160 | 
161 | 1. Create an Object
162 | 1. Add some children variables
163 | 1. Convert the Object into Type
164 | 1. Right click on the Object Type and click `Add Custom Behavior`
165 | 1. Double click the Object Type and Visual Studio will appear
166 | 
167 | Now that the new class is created you can add as many C# methods as you need. Children variables can be accessed by calling `Node.[VariableName]`
168 | 
169 | ```csharp
170 | [ExportMethod]
171 | public void StartMotor() {
172 |     // Node refers to the current object ("this")
173 |     Node.Running = true;
174 |     Node.CurSpeed = Node.SetSpeed;
175 | }
176 | 
177 | [ExportMethod]
178 | public void StopMotor() {
179 |     Node.Running = false;
180 |     Node.CurSpeed = (Int32)0;
181 | }
182 | 
183 | [ExportMethod]
184 | Public void Banana(int a, int b, out int c) {
185 |     c = a + b;
186 | }
187 | 
188 | #region Auto-generated code, do not edit!
189 | protected new MotorWithBehaviorType Node => (MotorWithBehaviorType)base.Node;
190 | #endregion
191 | ```
192 | 
193 | ## Detect the Object Type of an element
194 | 
195 | ### Extract the BrowseName of the Type of any element
196 | 
197 | ```csharp
198 | // Cast myVar to IUAVariable to read the DataType,
199 | // then get it from the InformationModel and read the BrowseName
200 | String dataType = InformationModel.Get(((IUAVariable)myVar).DataType).BrowseName;
201 | ```
202 | 
203 | ```csharp
204 | // Get the Variable to read the type
205 | var dataSource = InformationModel.Get(Owner.GetVariable("Model").Value);
206 | // Get it as a string
207 | String baseType = dataSource.GetType().FullName.ToString()
208 | ```
209 | 
210 | ### More advanced scenarios
211 | 
212 | This method expects the `BrowseName` of a `Screen` and makes a recursive search starting from a root node
213 | 
214 | ```csharp
215 | private NodeId RecursiveSearch(IUANode inputObject, String screenType) {
216 |     // Browse all children of the starting node
217 |     foreach (IUANode childrenObject in inputObject.Children) {
218 |         try {
219 |             if (childrenObject is FTOptix.Core.Folder) {
220 |                 // Start looking into the folder
221 |                 Log.Verbose1("FindPages.Folder", "Found folder with name [" + childrenObject.BrowseName + "] and Type: [" + childrenObject.GetType().ToString() + "]");
222 |                 // Recursive call to keep browsing
223 |                 RecursiveSearch(childrenObject, screenType);
224 |             } else if (((UAManagedCore.UAObjectType)childrenObject).SuperType.BrowseName == screenType) {
225 |                 // If the screen type was found, return it
226 |                 return childrenObject.NodeId
227 |             } else {
228 |                 // Other type that does not need to be used
229 |                 Log.Verbose1("FindPages.Else", "Found unknown with name [" + childrenObject.BrowseName + "] and Type: [" + childrenObject.GetType().ToString() + "]");
230 |             }
231 |         } catch (Exception ex) {
232 |             // Handle exceptions
233 |             Log.Error("FindPages.Catch", "Exception thrown: " + ex.Message);
234 |         }
235 |     }
236 | }
237 | 
238 | ```
239 | 
240 | ## Find types derived from a specific type
241 | 
242 | In the OPC/UA model, types can be derived from other types. This means that a type can inherit properties and methods from another type. To find all types derived from a specific type, you need to navigate through the references of the starting type type.
243 | 
244 | > [!NOTE]
245 | > The routine might be called recursively, as derived types can have their own derived types, and so on. This is useful for exploring the hierarchy of types in the OPC/UA model.
246 | 
247 | ### Find all types derived from BaseEventType
248 | 
249 | ```csharp
250 | public class FindBaseEventTypesRecursively : BaseNetLogic
251 | {
252 |     [ExportMethod]
253 |     public void FindBaseEventTypeSubtypes()
254 |     {
255 |         recursiveTypesSearchTask = new LongRunningTask(RecursiveSearchMethod, LogicObject);
256 |         recursiveTypesSearchTask.Start();
257 |     }
258 | 
259 |     private void RecursiveSearchMethod()
260 |     {
261 |         RecursiveSearch(null);
262 |         Log.Info($"Found {foundSubtypes.Count} subtypes of BaseEventType.");
263 |         recursiveTypesSearchTask.Dispose();
264 |     }
265 | 
266 |     private void RecursiveSearch(IUANode baseEventType = null)
267 |     {
268 |         if (baseEventType == null)
269 |         {
270 |             baseEventType = InformationModel.Get(OpcUa.ObjectTypes.BaseEventType);
271 |             if (baseEventType == null)
272 |             {
273 |                 Log.Error("BaseEventType not found in the information model.");
274 |                 return;
275 |             }
276 |         }
277 | 
278 |         var subtypes = baseEventType.Refs.GetNodes(OpcUa.ReferenceTypes.HasSubtype);
279 | 
280 |         foreach (var subtype in subtypes)
281 |         {
282 |             Log.Info($"Found subtype: {subtype.BrowseName}");
283 |             foundSubtypes.Add(subtype);
284 |             RecursiveSearch(subtype);
285 |         }
286 |     }
287 | 
288 |     private LongRunningTask recursiveTypesSearchTask;
289 |     private List<IUANode> foundSubtypes = new List<IUANode>();
290 | }
291 | ```
292 | 


--------------------------------------------------------------------------------
/pages/database-interaction.md:
--------------------------------------------------------------------------------
  1 | # Database Interaction
  2 | 
  3 | Database interaction is only possible via the FT Optix API
  4 | 
  5 | ## Insert
  6 | 
  7 | First you need to access the Database node, then get the Table by its BrowseName and then prepare the object which will contain the rows to add
  8 | 
  9 | ```csharp
 10 | private void InsertData()
 11 | {
 12 |     // Get the Database object from the current project
 13 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase");
 14 |     // Get a specific table by name
 15 |     var myTable = myStore.Tables.Get<Table>("TableName");
 16 |     // Prepare the header for the insert query (list of columns)
 17 |     string[] columns = { "Username", "Apples", "Bananas", "Timestamp" };
 18 |     // Create the new object, a bidimensional array where the first element
 19 |     // is the number of rows to be added, the second one is the number
 20 |     // of columns to be added (same size of the columns array)
 21 |     var values = new object[1, 4];
 22 |     // Set some values for each column
 23 |     values[0, 0] = (string)Owner.Owner.Get<Label>("LbUser").Text;
 24 |     values[0, 1] = (int)Owner.Owner.Get<SpinBox>("Apples").Value;
 25 |     values[0, 2] = (int)Owner.Owner.Get<SpinBox>("Bananas").Value;
 26 |     values[0, 3] = DateTime.Now;
 27 |     // Perform the insert query
 28 |     myTable.Insert(columns, values);
 29 |     // Some log for users
 30 |     Log.Info("InsertData", "Inserting data for user " + values[0, 0]);
 31 | }
 32 | ```
 33 | 
 34 | ## Update
 35 | 
 36 | ```csharp
 37 | private void UpdateData()
 38 | {
 39 |     // Get the Database from the current project
 40 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase");
 41 |     // Create the output to get the result (mandatory)
 42 |     Object[,] ResultSet;
 43 |     String[] Header;
 44 |     // Perform the query
 45 |     myStore.Query("UPDATE MyTable SET ColumnName=NewValue", out Header, out ResultSet);
 46 | }
 47 | ```
 48 | 
 49 | ## Delete
 50 | 
 51 | ```csharp
 52 | private void DeleteData()
 53 | {
 54 |     // Get the Database from the current project
 55 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase");
 56 |     // Create the output to get the result (mandatory)
 57 |     Object[,] ResultSet;
 58 |     String[] Header;
 59 |     // Perform the query
 60 |     myStore.Query("DELETE FROM MyTable WHERE ColumnName=NewValue", out Header, out ResultSet);
 61 | }
 62 | ```
 63 | 
 64 | ## Select
 65 | 
 66 | ```csharp
 67 | private void SelectData()
 68 | {
 69 |     // Get the Database from the current project
 70 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase");
 71 |     // Create the output to get the result (mandatory)
 72 |     Object[,] ResultSet;
 73 |     String[] Header;
 74 |     // Perform the query
 75 |     myStore.Query("SELECT * FROM TableName", out Header, out ResultSet);
 76 |     // Get the result
 77 |     Log.Info("SelectData", "Result: " + ResultSet[0, 0]);
 78 | }
 79 | ```
 80 | 
 81 | ```csharp
 82 | [ExportMethod]
 83 | public void SelectData(NodeId minDateTimePickerNodeId, NodeId maxDateTimePickerNodeId, out double averageValue)
 84 | {
 85 |     // Get the Database from the current project
 86 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase1");
 87 |     var minDateTimePicker = InformationModel.Get<DateTimePicker>(minDateTimePickerNodeId);
 88 |     var minDate = minDateTimePicker.Value.ToString("yyyy-MM-ddTHH:mm:ss.fffffff");
 89 |     var maxDateTimePicker = InformationModel.Get<DateTimePicker>(maxDateTimePickerNodeId);
 90 |     var maxDate = maxDateTimePicker.Value.ToString("yyyy-MM-ddTHH:mm:ss.fffffff");
 91 |     // Create the output to get the result (mandatory)
 92 |     Object[,] ResultSet;
 93 |     String[] Header;
 94 |     var query = $"SELECT AVG(Speed) AS AverageSpeed FROM prod1_table WHERE Machine_state = \"RUN\" AND (Timestamp BETWEEN \"{minDate}\" AND \"{maxDate}\") ORDER BY AverageSpeed DESC";
 95 |     // Perform the query
 96 |     myStore.Query(query, out Header, out ResultSet);
 97 |     // Get the result
 98 |     averageValue = (double)ResultSet[0, 0];
 99 | }
100 | ```
101 | 
102 | ### Get the list of columns name from a DataBase
103 | 
104 | #### From ODBC
105 | 
106 | ```csharp
107 | private void ExtractColumnNames()
108 | {
109 |     // Get the Database from the current project
110 |     var myStore = Project.Current.Get<Store>("DataStores/EmbeddedDatabase");
111 |     // Create the output to get the result (mandatory)
112 |     Object[,] ResultSet;
113 |     String[] Header;
114 |     // Perform the query
115 |     myStore.Query("SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = 'AlarmsEventLogger1'", out Header, out ResultSet);
116 | }
117 | ```
118 | 
119 | #### From EmbeddedDatabase
120 | 
121 | The EmbeddedDatabase uses a SQLite technology which only supports a subset of features from a normal store, we will need some additional steps
122 | 
123 | ```csharp
124 | private void ExtractColumnNames()
125 | {
126 |     Regex regexTable = new Regex("(?<=\\bFROM\\s)(\\w+)");
127 |     String tableName = regexTable.Match(Owner.GetVariable("Query").Value.Value.ToString(), 0, Owner.GetVariable("Query").Value.Value.ToString().Length).Value;
128 | 
129 |     // Check if we are using EmbeddedDatabase or SQL
130 |     if (dataSource.GetType().FullName.ToString().Contains("SQLite")) 
131 |     {
132 |         // Extract list of tables
133 |         var tablesList = myStore.Children.ToList()[0].Children.ToList();
134 |         foreach (var table in tablesList) 
135 |         {
136 |         // Check if current table matches input query table
137 |         if (((QPlatform.SQLiteStore.SQLiteStoreTable)table).BrowseName == tableName) 
138 |         {
139 |             var columnList = ((QPlatform.SQLiteStore.SQLiteStoreTable)table).Columns.ToList();
140 |             // Extract columns name
141 |             for (int i = 1; i < (columnList.Count - 2); i++) 
142 |             {
143 |                 if (i == 1) 
144 |                 {
145 |                     dataNames = columnList[i].BrowseName.ToString();
146 |                 } else 
147 |                 {
148 |                     dataNames += ", " + columnList[i].BrowseName.ToString();
149 |                 }
150 |             }
151 |         }
152 |     }
153 | }
154 | ```
155 | 
156 | ## Creating random Database data
157 | 
158 | ```csharp
159 | private void PopulateTableWithRandomData(string tableName)
160 | {
161 |     // Read the column names from the current  project
162 |     var tableColumnsNames = GetTableColumnsNames(tableName);
163 |     var tableColumnsTypes = GetTableColumnsTypes(tableName);
164 |     // Add some data (using a for loop to specify entries)
165 |     for (int i = 0; i < 100; i++)
166 |     {
167 |         object[,] values = GenerateTableRowData(tableColumnsTypes, tableColumnsNames);
168 |         // Perform the insert
169 |         _store.Insert(tableName, tableColumnsNames.ToArray(), values);
170 |     }
171 | }
172 | 
173 | private object[,] GenerateTableRowData(List<Type> tableColumnsTypes, List<string> tableColumnsNames)
174 | {
175 |     Random random = new Random();
176 |     object[,] values = new object[1, tableColumnsTypes.Count];
177 |     // Generate a random value for each column
178 |     var rowData = tableColumnsTypes.Select(rowType => GetRandomValue(rowType, random)).ToList();
179 |     // Add the new data to the returned object
180 |     for (int i = 0; i < tableColumnsTypes.Count; i++)
181 |     {
182 |         values[0, i] = rowData[i];
183 |     }
184 |     return values;
185 | }
186 | 
187 | private static object GetRandomValue(Type dataType, Random random)
188 | {
189 |     if (dataType == typeof(int)) return random.Next(1, 100);
190 |     if (dataType == typeof(float)) return random.NextDouble() * 100.0;
191 |     if (dataType == typeof(string)) return Guid.NewGuid().ToString();
192 |     if (dataType == typeof(bool)) return random.Next(2);
193 |     return null;
194 | }
195 | 
196 | ```
197 | 
198 | ## Dynamic creation of a DataGrid
199 | 
200 | ```csharp
201 | [ExportMethod]
202 | public void QueryOnStore(string tableName)
203 | {
204 |     queryTask?.Dispose();
205 |     var arguments = new object[] { tableName };
206 |     queryTask = new LongRunningTask(QueryAndUpdate, arguments, LogicObject);
207 |     queryTask.Start();
208 | }
209 | 
210 | private void QueryAndUpdate(LongRunningTask myTask, object args)
211 | {
212 |     // Get the table name from the arguments
213 |     var argumentsArray = (object[])args;
214 |     var tableName = (string)argumentsArray[0];
215 | 
216 |     if (string.IsNullOrEmpty(tableName))
217 |         return;
218 | 
219 |     // Get the DataGrid and Store
220 |     var store = Project.Current.Get<Store>("DataStores/EmbeddedDatabase1");
221 |     var dataGrid = Owner.Get<DataGrid>("DataGrid");
222 | 
223 |     if (store == null || dataGrid == null)
224 |         return;
225 | 
226 |     // Reset the grid
227 |     dataGrid.Query = "";
228 | 
229 |     // Prepare the query
230 |     var query = $"SELECT * FROM {tableName}";
231 | 
232 |     // Execute the query
233 |     store.Query(query, out String[] header, out Object[,] resultSet);
234 | 
235 |     if (header == null || resultSet == null)
236 |         return;
237 | 
238 |     // Clear existing rows
239 |     dataGrid.Columns.Clear();
240 | 
241 |     DynamicLink lastDynamicLink = null;
242 | 
243 |     // Create columns based on the header
244 |     foreach (var columnName in header)
245 |     {
246 |         var newDataGridColumn = InformationModel.MakeObject<DataGridColumn>(columnName);
247 |         newDataGridColumn.Title = columnName;
248 |         newDataGridColumn.DataItemTemplate = InformationModel.MakeObject<DataGridLabelItemTemplate>("DataItemTemplate");
249 |         var dynamicLink = InformationModel.MakeVariable<DynamicLink>("DynamicLink", FTOptix.Core.DataTypes.NodePath);
250 |         dynamicLink.Value = "{Item}/" + NodePath.EscapeNodePathBrowseName(columnName);
251 |         newDataGridColumn.DataItemTemplate.GetVariable("Text").Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, dynamicLink);
252 |         newDataGridColumn.OrderBy = dynamicLink.Value;
253 |         dataGrid.Columns.Add(newDataGridColumn);
254 |         lastDynamicLink = dynamicLink;
255 |     }
256 | 
257 |     // Set last column as sort item - not really needed
258 |     dataGrid.SortColumnVariable.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, lastDynamicLink);
259 | 
260 |     // Add the new query to the grid
261 |     dataGrid.Query = query + " ORDER BY Timestamp DESC";
262 | }
263 | ```
264 | 
265 | ## Sample queries
266 | 
267 | ### Populate a PieChard with the count of unique values in a column
268 | 
269 | This query returns the count of unique values in the column `Code` of the table `SQLiteStoreTable1` to populate a pie chard. Each slice of the pie chart will represent a unique value in the column `Code` and the size of the slice will be the count of the occurrences of that value.
270 | 
271 | The PieChard object should be populated with:
272 | 
273 | - Model: `EmbeddedDatabase1`
274 | - Query: `SELECT Code, COUNT(*) AS Count FROM SQLiteStoreTable1 GROUP BY Code ORDER BY Count DESC`
275 | - Label: `{Item}/Code`
276 | - Value: `{Item}/Count`
277 | 
278 | ### Populate a Histogram chart with the count of unique values in a column
279 | 
280 | This query returns the count of unique values in the column `StatusMachine` of the table `SQLiteStoreTable1` to populate a histogram chart. Each bar of the histogram will represent a unique value in the column `StatusMachine` and the height of the bar will be the count of the occurrences of that value.
281 | 
282 | - Model: `EmbeddedDatabase1`
283 | - Query: `SELECT StatusMachine, COUNT(*) AS Occurrences FROM Machine_state WHERE StatusMachine >= 0 GROUP BY StatusMachine ORDER BY Occurrences DESC`
284 | - Label: `{Item}/StatusMachine`
285 | - Value: `{Item}/Occurrences`
286 | 


--------------------------------------------------------------------------------
/pages/datagrids.md:
--------------------------------------------------------------------------------
 1 | # Data grids
 2 | 
 3 | ## Getting column values from the UI Selected Item
 4 | 
 5 | Add a Runtime NetLogic as children of the DataGrid, add the following NetLogic and invoke the `DataGridSelectionChanged` method in the `User selection changed` event of the DataGrid itself, remember to pass the NodeId of the DataGrid as argument of the function (to make it session-independent).
 6 | The UI Selected Item is actually an object which has a children variable per each column of the DataGrid.
 7 | 
 8 | ```csharp
 9 | [ExportMethod]
10 | public void DataGridSelectionChanged(NodeId dataGrid)
11 | {
12 |     // Session variables where to store the output of the SelectedItem
13 |     var sessionClientId = Session.GetVariable("selectedClientId");
14 |     var sessionUsedCnt = Session.GetVariable("selectedUsedCnt");
15 |     var sessionLastUsedTime = Session.GetVariable("selectedLastUsedTime");
16 | 
17 |     // Retrieve the DataGrid object
18 |     var dataGridItem = InformationModel.Get<DataGrid>(dataGrid);
19 |     if (dataGridItem == null)
20 |     {
21 |         Log.Error("DataGrid is null");
22 |         return;
23 |     }
24 | 
25 |     // Get the UI Selected Item variable (an object)
26 |     var selectedRow = InformationModel.Get(dataGridItem.UISelectedItem);
27 |     if (selectedRow == null)
28 |     {
29 |         Log.Error("Selected row is null");
30 |         return;
31 |     }
32 | 
33 |     // Get the value at the column called "ClientID" (string)
34 |     var selectedRowClientId = selectedRow.Children.OfType<IUAVariable>().FirstOrDefault(x => x.BrowseName == "ClientID");
35 |     if (selectedRowClientId == null)
36 |     {
37 |         Log.Error("ClientID is null");
38 |         return;
39 |     }
40 | 
41 |     // Get the value at the column called "Used" (Bool)
42 |     var selectedRowUsedCnt = selectedRow.Children.OfType<IUAVariable>().FirstOrDefault(x => x.BrowseName == "Used");
43 |     if (selectedRowUsedCnt == null)
44 |     {
45 |         Log.Error("Used is null");
46 |         return;
47 |     }
48 | 
49 |     // Get the value at the column called "LastUsedTime" (DateTime)
50 |     var selectedRowLastUsedTime = selectedRow.Children.OfType<IUAVariable>().FirstOrDefault(x => x.BrowseName == "LastUsedTime");
51 |     if (selectedRowLastUsedTime == null)
52 |     {
53 |         Log.Error("LastUsedTime is null");
54 |         return;
55 |     }
56 | 
57 |     // Set the variables in the editor object
58 |     sessionClientId.Value = selectedRowClientId.Value.Value.ToString();
59 |     sessionUsedCnt.Value = Convert.ToInt32(selectedRowUsedCnt.Value.Value.ToString());
60 |     sessionLastUsedTime.Value = Convert.ToDateTime(selectedRowLastUsedTime.Value.Value.ToString());
61 | }
62 | ```
63 | 


--------------------------------------------------------------------------------
/pages/dialog-boxes.md:
--------------------------------------------------------------------------------
 1 | # DialogBox
 2 | 
 3 | ## Opening a DialogBox
 4 | 
 5 | ```csharp
 6 | [ExportMethod]
 7 | public void OpenMyDialogBox()
 8 | {
 9 |     // Source type definition of the DialogBox
10 |     var myDialogType = (DialogType)Project.Current.Get("UI/Templates/DialogBox1");
11 |     // DialogBoxes needs a graphical container as parent in order to
12 |     // understand to which session they have to spawn
13 |     parentPanel = (FTOptix.UI.Panel)Owner;
14 |     UICommands.OpenDialog(parentPanel, myDialogType);
15 | }
16 | ```
17 | 
18 | ### Open a DialogBox on all sessions (native and web)
19 | 
20 | ```csharp
21 | [ExportMethod]
22 | public void OpenDialogBox(string DialogBoxName, NodeId[] AliasArray = null)
23 | {
24 |     DialogType dialogBox = (DialogType)Project.Current.Get($"UI/Screens/{DialogBoxName}");  // depends on path to Screens folder
25 |  
26 |     var npe = Project.Current.Get("UI/NativePresentationEngine");   // depends on UI and NativePresentationEngine paths
27 |     var npeSessions = npe.Get("Sessions");      // npe has a single session
28 |     var npeSession = npeSessions.Children[0];   // the single npe session is at [0]
29 |     var npeWindow = npeSession.Get("UIRoot");   // "UIRoot" is the browsename of the main window
30 |     UICommands.OpenDialog(npeWindow, dialogBox, AliasArray);
31 |  
32 |     var wpe = Project.Current.Get("UI/WebPresentationEngine");   // depends on UI and WebPresentationEngine paths
33 |     var wpeSessions = wpe.Get("Sessions");      // wpe could have multiple sessions
34 |     foreach (var wpeSession in wpeSessions.Children)
35 |     {
36 |         var wpeWindow = wpeSession.Get("UIRoot");   // "UIRoot" is the browsename of the main window
37 |         if (wpeWindow != null)
38 |         {
39 |             UICommands.OpenDialog(wpeWindow, dialogBox, AliasArray);
40 |         }
41 |     }
42 | }
43 | ```
44 | 
45 | ## Close all DialogBoxes
46 | 
47 | > [!TIP]
48 | > The following snippet must be placed in a session-based object (e.g. the `MainWindow` of a project).
49 | 
50 | ```csharp
51 | [ExportMethod]
52 | public void CloseAllDialogs()
53 | {
54 |     // DialogBoxes are children of the current Session, so we can iterate in
55 |     // children to get all of them
56 |     foreach (Dialog item in Session.Get("UIRoot").Children.OfType<Dialog>().ToList()) {
57 |         item.Close();
58 |     }
59 | }
60 | ```
61 | 


--------------------------------------------------------------------------------
/pages/dispatch-events.md:
--------------------------------------------------------------------------------
  1 | # Triggering events to the FactoryTalk Optix core
  2 | 
  3 | ## Introduction to OPC/UA Events
  4 | 
  5 | OPC Unified Architecture (OPC UA) is a machine-to-machine communication protocol for industrial automation developed by the OPC Foundation. One of the key features of OPC UA is its ability to handle events. Events in OPC UA are notifications about changes or occurrences within the system that are of interest to clients.
  6 | 
  7 | ### What are OPC/UA Events?
  8 | 
  9 | OPC UA events provide a mechanism for servers to notify clients about significant changes or occurrences. These events can be anything from simple state changes to complex alarms and conditions. Events are used to inform clients about changes in the system without the need for constant polling, making the communication more efficient.
 10 | 
 11 | ### Types of Events
 12 | 
 13 | OPC UA defines several types of events, including:
 14 | 
 15 | - **Simple Events**: Basic notifications about changes or occurrences.
 16 | - **Condition Events**: Notifications about conditions that have a state and can change over time.
 17 | - **Alarm Events**: Special types of condition events that indicate abnormal or critical conditions.
 18 | 
 19 | ### Event Model
 20 | 
 21 | The OPC UA event model is based on the concept of event types and event instances. Event types define the structure and semantics of events, while event instances are actual occurrences of these events. The event model allows for the creation of custom event types to suit specific application needs.
 22 | 
 23 | ### References to Specifications
 24 | 
 25 | For more detailed information about OPC UA events, refer to the following OPC Foundation specifications:
 26 | 
 27 | - [OPC Unified Architecture, Part 3: Address Space Model](https://opcfoundation.org/developer-tools/specifications-unified-architecture/part-3-address-space-model/)
 28 | - [OPC Unified Architecture, Part 5: Information Model](https://opcfoundation.org/developer-tools/specifications-unified-architecture/part-5-information-model/)
 29 | - [OPC Unified Architecture, Part 9: Alarms and Conditions](https://opcfoundation.org/developer-tools/specifications-unified-architecture/part-9-alarms-conditions/)
 30 | 
 31 | These documents provide comprehensive details on the structure, types, and handling of events in OPC UA.
 32 | 
 33 | ## Dispatching an OPC/UA event
 34 | 
 35 | > [!WARNING]
 36 | > Events are not directly supported in the FactoryTalk Optix IDE, and the code provided here is an example of how to manually trigger them using custom logic. This code is for reference only and should be adapted to your specific use case.
 37 | 
 38 | ### 1. Creating the dispatch method
 39 | 
 40 | ```csharp
 41 | [ExportMethod]
 42 | public void TriggerUserSessionEvent(object[] inputArgs)
 43 | {
 44 |     // Convert input arguments to the expected types
 45 |     var sourceName = (string) inputArgs[0];
 46 |     var sourceNode = (NodeId) inputArgs[1];
 47 |     var clientUserId = (string) inputArgs[2];
 48 |     var status = (bool) inputArgs[3];
 49 |     var message = new LocalizedText((string) inputArgs[4], "en-US");
 50 | 
 51 |     // Get the UserSessionEvent object type
 52 |     var userSessionEvent = (IUAObjectType) InformationModel.Get(FTOptix.Core.ObjectTypes.UserSessionEvent);
 53 | 
 54 |     // Create a list to store the event arguments
 55 |     List<object> argumentList = [];
 56 |     if (userSessionEvent.EventArguments != null)
 57 |     {
 58 |         argumentList.AddRange(new object[userSessionEvent.EventArguments.GetFields().Count]);
 59 |         foreach (var field in userSessionEvent.EventArguments.GetFields())
 60 |         {
 61 |             // Set the field value based on the field name
 62 |             object fieldValue = field switch
 63 |             {
 64 |                 "EventId" => GenerateEventIdFromNodeId((Guid) Session.NodeId.Id),
 65 |                 "EventType" => FTOptix.Core.ObjectTypes.UserSessionEvent,
 66 |                 "SourceName" => sourceName,
 67 |                 "SourceNode" => sourceNode,
 68 |                 "ClientUserId" => clientUserId,
 69 |                 "Status" => status,
 70 |                 "Message" => message,
 71 |                 "Time" => DateTime.Now,
 72 |                 "Severity" => new Random().Next(1, 500),
 73 |                 _ => null
 74 |             };
 75 |             if (fieldValue != null)
 76 |             {
 77 |                 userSessionEvent.EventArguments.SetFieldValue(argumentList, field, fieldValue);
 78 |             }
 79 |         }
 80 |         // Dispatch the event to the Server object
 81 |         LogicObject.Context.GetObject(OpcUa.Objects.Server).DispatchUAEvent(FTOptix.Core.ObjectTypes.UserSessionEvent, argumentList.AsReadOnly());
 82 |     }
 83 | }
 84 | 
 85 | public static ByteString GenerateEventIdFromNodeId(Guid nodeId)
 86 | {
 87 |     string baseString = nodeId.ToString() + DateTime.UtcNow.Ticks.ToString();
 88 |     using SHA256 sha256 = SHA256.Create();
 89 |     byte[] hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(baseString));
 90 |     return new ByteString(hashBytes);
 91 | }
 92 | ```
 93 | 
 94 | ### 2. Triggering the event
 95 | 
 96 | ```csharp
 97 | 
 98 | [ExportMethod]
 99 | public void TriggerEvent()
100 | {
101 |     DispatchEventToCore(Session.User.BrowseName, false, "Custom message triggered from a button");
102 | }
103 | 
104 | private void DispatchEventToCore(string username, bool successful, string message)
105 | {
106 |     // Get the EventDispatcher NetLogic
107 |     // This is the NetLogic object that dispatches events to the FactoryTalk Optix core
108 |     // as created in the previous section
109 |     var eventsDispatcherLogic = Project.Current.GetObject("NetLogic/EventsDispatcher");
110 |     if (eventsDispatcherLogic == null)
111 |     {
112 |         Log.Error("LoginButtonLogic", "EventsDispatcher NetLogic not found");
113 |         return;
114 |     }
115 |  
116 |     // Create the input arguments for the event
117 |     // The arguments are passed as an object array, to find the list of arguments
118 |     // and the expected values, you can use an EventLogger object and generate
119 |     // an event to see the expected arguments
120 |     var inputArgs = new object[]
121 |     {
122 |         "LoginForm", // SourceName -> The friendly name of the source of the event
123 |         Owner.NodeId, // SourceNode -> The NodeId of the source of the event
124 |         username, // ClientUserId -> The user associated with the event
125 |         successful, // Status -> The status of the event (boolean)
126 |         message // Message -> The message associated with the event
127 |     };
128 | 
129 |     // Trigger the event
130 |     eventsDispatcherLogic.ExecuteMethod("TriggerUserSessionEvent", [inputArgs]);
131 | }
132 | ```
133 | 


--------------------------------------------------------------------------------
/pages/dynamic-links.md:
--------------------------------------------------------------------------------
  1 | # Dynamic Links
  2 | 
  3 | ## Simple Dynamic Link
  4 | 
  5 | By default a `DynamicLink` is made as _Read only_ unless you specify different mode
  6 | 
  7 | ```csharp
  8 |     ...
  9 |     // Get the element where the dynamic link has to be added
 10 |     var myObj = Owner.Get<Motor>("Motor1");
 11 |     // Reach the specific variable
 12 |     var speedValue = Owner.GetObject("SpeedLabel").GetVariable("Text");
 13 |     // Create the dynamic link and specify the mode (optional - read only if empty)
 14 |     myObj.SpeedVariable.SetDynamicLink(speedValue, DynamicLinkMode.Read);
 15 |     ...
 16 | ```
 17 | 
 18 | ### Dynamic link manipulation
 19 | 
 20 | > [!WARNING]
 21 | > Manipulating a dynamic link is a very advanced topic and should be used with caution. It is recommended to use the default dynamic link APIs unless you have a specific use case.
 22 | 
 23 | #### Resolve a DynamicLink
 24 | 
 25 | ```csharp
 26 |     ...
 27 |     // Get the element containing a DynamicLink
 28 |     TrendPen originalPen = InformationModel.Get<TrendPen>(Owner.GetAlias("AliasPen").NodeId);
 29 |     // Read the variable value
 30 |     var myVariable = (String)originalPen.FindVariable("DynamicLink").Value;
 31 |     // Resolve the dynamic link target
 32 |     var result = LogicObject.Context.ResolvePath(myVariable);
 33 |     var resolvedNode = result.ResolvedNode;
 34 |     // Set the target variable somewhere in the project
 35 |     Owner.Find<ComboBox>("ComboBox1").SelectedItem = resolvedNode.Owner.NodeId;
 36 |     ...
 37 | ```
 38 | 
 39 | ```csharp
 40 |     ...
 41 |     // Get the element containing a DynamicLink
 42 |     var textVariable = Owner.Children.Get<IUAVariable>("Text");
 43 |     // Get the DynamicLink node
 44 |     var dynamicLinkNode = textVariable.Children.Get("DynamicLink");
 45 |     // Get the pointed node
 46 |     var pointedNode = dynamicLinkNode.Refs.GetNodes(FTOptix.Core.ReferenceTypes.Resolves).First();
 47 |     ...
 48 | ```
 49 | 
 50 | #### Check for a DynamicLink
 51 | 
 52 | ```csharp
 53 | // Check if the current node has a dynamic link
 54 | var dynamicLink = inputVariable.Refs.GetVariable(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink);
 55 | // Retrieve the path of the dynamic link
 56 | var dynamicLinkPath = (string)dynamicLink.Value;
 57 | // Resolve the dynamic link and get to the target node
 58 | var targetVariable = LogicObject.Context.ResolvePath(inputVariable, dynamicLinkPath).ResolvedNode;
 59 | ```
 60 | 
 61 | #### Check for broken DynamicLink
 62 | 
 63 | ```csharp
 64 | [ExportMethod]
 65 | public void GetBrokenDynamicLinks()
 66 | {
 67 |     var nodesWithBrokenDynamicLink = new List<string>();
 68 |     var projectNodes = Project.Current.Parent.FindNodesByType<IUANode>();
 69 |  
 70 |     foreach (var n in projectNodes)
 71 |     {
 72 |         // Check if the current node has a dynamic link
 73 |         var dynamicLink = n.Refs.GetVariable(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink);
 74 |         if (dynamicLink == null) continue;
 75 |         // Retrieve the path of the dynamic link
 76 |         var dynamicLinkPath = (string)dynamicLink.Value;
 77 |         // Resolve the dynamic link and get to the target node
 78 |         var targetVariable = LogicObject.Context.ResolvePath(n, dynamicLinkPath).ResolvedNode;
 79 |             if (targetVariable == null)
 80 |         {
 81 |             nodesWithBrokenDynamicLink.Add("Node BrowsePath: " + Log.Node(n));
 82 |         }
 83 |     }
 84 |  
 85 |     foreach (var info in nodesWithBrokenDynamicLink)
 86 |     {
 87 |         Log.Info(info);
 88 |     }
 89 | }
 90 | ```
 91 | 
 92 | #### Change the EU Mode of a DynamicLink
 93 | 
 94 | ```csharp
 95 | [ExportMethod]
 96 | public void SetEuModeOfText()
 97 | {
 98 |     // Get to the label that will display the value of the variable
 99 |     var myLabelText = Owner.GetVariable("Label1/Text");
100 |     // Get the dynamic link at the text property
101 |     var dynamicLink = myLabelText.Refs.GetVariable(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink);
102 |     // Set the EU mode of the dynamic link to "Localize"
103 |     ((DynamicLink)dynamicLink).EUMode = DynamicLinkEUMode.SetParentLocalizedEngineeringUnit;
104 |     // Set the EU mode of the dynamic link to "Set Parent as Source" (no conversion)
105 |     //((DynamicLink)dynamicLink).EUMode = DynamicLinkEUMode.SetParentEngineeringUnitAsSource;
106 | }
107 | ```
108 | 
109 | #### Dynamic Link to a bit indexed word
110 | 
111 | ```csharp
112 | [ExportMethod]
113 | public void AddDynamicLinkToBitOfIntegerVariable()
114 | {
115 |     // Get the variable
116 |     var myBitAlarm = Project.Current.GetVariable("Model/BitVariable");
117 |     // Create a fake variable
118 |     IUAVariable tempVariable = null;
119 |     // Add a dynamic link to the fake variable (to trigger the link mechanism)
120 |     myBitAlarm.SetDynamicLink(tempVariable, DynamicLinkMode.ReadWrite);
121 |     // Replace the dynamic link content to the real target value
122 |     myBitAlarm.GetVariable("DynamicLink").Value = "../Int32Variable.1";
123 | }
124 | ```
125 | 
126 | #### Dynamic Link to a single element of array variable
127 | 
128 | ```csharp
129 | private void StuffDynamicLinkToArrayElement(IUAVariable sourceVariable, IUAVariable targetDynamicLink, uint sourceVariableArrayIndex, int targetDynamicLinkArrayIndex, DynamicLinkMode dynamicLinkMode)
130 | {
131 |     // Prepare the BrowseName for the dynamic link variable
132 |     string dynamicLinkVariableBrowseName = $"DynamicLink_{sourceVariableArrayIndex}";
133 |     // Create the dynamic link object
134 |     DynamicLink newDynamicLink = InformationModel.MakeVariable<DynamicLink>(dynamicLinkVariableBrowseName, FTOptix.Core.DataTypes.NodePath);
135 |     // Set the dynamic link values
136 |     newDynamicLink.Value = DynamicLinkPath.MakePath(sourceVariable, targetDynamicLink);
137 |     newDynamicLink.Mode = dynamicLinkMode;
138 |     // Get the parent element access variable as Struct for getting the values
139 |     Struct parentElementAccess = newDynamicLink.ParentElementAccessVariable.Value;
140 |     // Generate the new values for the parent element access variable (the first element is the index in case of an array, the second is the field index in case of struct)
141 |     var newValues = parentElementAccess.Values.ToList();
142 |     // Set the target index as array of uint (OPCUA specs)
143 |     newValues[0] = new uint[]{sourceVariableArrayIndex};
144 |     // Overwrite the struct with the new values
145 |     newDynamicLink.ParentElementAccessVariable.Value = new Struct(parentElementAccess.DataTypeId,newValues);
146 |     // Check if the target of dynamic link is an array
147 |     if (targetDynamicLinkArrayIndex >= 0)
148 |     {
149 |         //If it is set the index by adding square brackets with inside the index value at the end of the path
150 |         newDynamicLink.Value = $"{newDynamicLink.Value.Value}[{targetDynamicLinkArrayIndex}]";
151 |     }
152 |     // Add the dynamic link reference to the dynamic link (OPCUA specs)
153 |     sourceVariable.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, newDynamicLink);
154 |     // Set the proper modelling rule (OPCUA specs)
155 |     newDynamicLink.SetModellingRuleRecursive();
156 | }
157 | ```
158 | 
159 | #### Formatted dynamic link
160 | 
161 | A formatted dynamic link is very similar to a string formatter and it is used to dynamically reference different objects in the project, such as using the same widget to control different motors using a SpinBox
162 | 
163 | ```csharp
164 | public void StuffCreateNewDynamicLinkFormatter()
165 | {
166 |     // Get to the text box where the dynamic link has to be created
167 |     IUAVariable targetVariable = Owner.Get("TextBox1").GetVariable("Text");
168 |     // Remove dynamic link (if any)
169 |     targetVariable.ResetDynamicLink();
170 |     // Create a new empty dynamic link object
171 |     DynamicLink newDynamicLink = InformationModel.MakeVariable<DynamicLink>("DynamicLink", FTOptix.Core.DataTypes.NodePath);
172 |     newDynamicLink.Value = "";
173 |     // Create a string formatter to be added to the dynamic link
174 |     StringFormatter newStringFormatter = InformationModel.MakeObject<StringFormatter>("DynamicLinkFormatter", FTOptix.CoreBase.ObjectTypes.StringFormatter);
175 |     // Set the proper format for the string formatter, where curly brackets are used as placeholders
176 |     newStringFormatter.Format = "/Objects/StuffTest/Model/Folder1/Variable5[{0},{1}]";
177 |     // Set the sources for the placeholders
178 |     IUAVariable source0 = InformationModel.MakeVariable("Source0", OpcUa.DataTypes.BaseDataType);
179 |     IUAVariable source1 = InformationModel.MakeVariable("Source1", OpcUa.DataTypes.BaseDataType);
180 |     source0.SetDynamicLink(Project.Current.GetVariable("Model/Folder1/Variable1"));
181 |     source1.SetDynamicLink(Project.Current.GetVariable("Model/Folder1/Variable2"));
182 |     // Add the references about the children variables to the string formatter
183 |     newStringFormatter.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source0);
184 |     newStringFormatter.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source1);
185 |     // Set the dynamic link mode (if needed)
186 |     newDynamicLink.Mode = DynamicLinkMode.ReadWrite;
187 |     // Set the proper references and modelling rules (OPCUA specs)
188 |     newDynamicLink.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasConverter, newStringFormatter);
189 |     newStringFormatter.SetModellingRuleRecursive();
190 |     targetVariable.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasDynamicLink, newDynamicLink);
191 |     newDynamicLink.SetModellingRuleRecursive();       
192 | }
193 | ```
194 | 
195 | ### Advanced dynamic links
196 | 
197 | > [!WARNING]
198 | > Advanced dynamic links are a very advanced topic and should be used with caution. It is recommended to use the default dynamic link APIs unless you have a specific use case.
199 | 
200 | #### Creating a String Formatter
201 | 
202 | ```csharp
203 | // Create a new variable
204 | var variable4 = InformationModel.MakeVariable("Variable4", OpcUa.DataTypes.String); 
205 | // Add the variable to the Model folder
206 | Project.Current.Get("Model").Add(variable4); 
207 | // Create a string formatter
208 | var stringFormatter = InformationModel.Make<StringFormatter>("StringFormatter1"); 
209 | // Set the base text (with placeholders)
210 | stringFormatter.Format = "{0} and {1}"; 
211 | // Configure placeholders
212 | var source0 = InformationModel.MakeVariable("Source0", OpcUa.DataTypes.BaseDataType); 
213 | stringFormatter.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source0); 
214 | var source1 = InformationModel.MakeVariable("Source1", OpcUa.DataTypes.BaseDataType); 
215 | stringFormatter.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source1); 
216 | // Add the new converter to the variable
217 | variable4.SetConverter(stringFormatter);
218 | // Set the targets for the dynamic links 
219 | var variable1 = Project.Current.GetVariable("Model/Variable1"); 
220 | var variable2 = Project.Current.GetVariable("Model/Variable2"); 
221 | source0.SetDynamicLink(variable1); 
222 | source1.SetDynamicLink(variable2);
223 | ```
224 | 
225 | #### Creating an Expression Evaluator
226 | 
227 | ```csharp
228 | [ExportMethod]
229 | public void Method1()
230 | {
231 |     // Get the source variables
232 |     var var1 = Project.Current.GetVariable("Model/Variable1");
233 |     var var2 = Project.Current.GetVariable("Model/Variable2");
234 |     var var3 = Project.Current.GetVariable("Model/Variable3");
235 |     // Create the expression evaluator object
236 |     var expressionEvaluator = InformationModel.MakeObject<ExpressionEvaluator>("ExpressionEvaluator");
237 |     // Set the format
238 |     expressionEvaluator.Expression = "{0} + {1}";
239 |     // Set the dynamic links to the source variables
240 |     var source0 = InformationModel.MakeVariable("Source0", OpcUa.DataTypes.BaseDataType);
241 |     source0.SetDynamicLink(var2);
242 |     var source1 = InformationModel.MakeVariable("Source1", OpcUa.DataTypes.BaseDataType);
243 |     source1.SetDynamicLink(var3);
244 |     // Add the references (OPCUA specs)
245 |     expressionEvaluator.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source0);
246 |     expressionEvaluator.Refs.AddReference(FTOptix.CoreBase.ReferenceTypes.HasSource, source1);
247 |     // Add the converter to the variable
248 |     var1.SetConverter(expressionEvaluator);
249 | }
250 | ```
251 | 
252 | #### Creating a Key-Value Converter
253 | 
254 | ```csharp
255 | private void StuffCreateKeyPair(IUAVariable targetNode, IUAVariable sourceVariable)
256 | {
257 |     // Create the new key value converter
258 |     ValueMapConverter newValueMapConverter = InformationModel.MakeObject<ValueMapConverter>("KeyValueConverter1", FTOptix.CoreBase.ObjectTypes.ValueMapConverter);
259 |     // Create the pairs object
260 |     IUAObject newPairs = InformationModel.MakeObject(new QualifiedName(FTOptix.CoreBase.ObjectTypes.ValueMapConverter.NamespaceIndex, "Pairs"));
261 |     // For each pair, set properties
262 |     for (int i = 0; i < 3; i++)
263 |     {
264 |         // First element is the default one
265 |         string pairBrowseName = "Pair";
266 |         if (i > 0)
267 |             pairBrowseName += i.ToString();
268 |         // Create the new pair
269 |         IUAObject newPair = InformationModel.MakeObject(pairBrowseName, FTOptix.CoreBase.ObjectTypes.ValueMapPair);
270 |         IUAVariable newKey = newPair.GetVariable("Key");
271 |         IUAVariable newValue = newPair.GetVariable("Value");
272 |         // Set the proper datatype
273 |         newKey.DataType = OpcUa.DataTypes.UInt32;
274 |         newValue.DataType = FTOptix.Core.DataTypes.Color;
275 |         // Set the proper value
276 |         newKey.Value = i;
277 |         newValue.Value = System.Drawing.Color.Violet.ToArgb();
278 |         // Add the pair to the map
279 |         newPairs.Add(newPair);
280 |     }
281 |     // Add the map to the key value converter
282 |     newValueMapConverter.Add(newPairs);
283 |     newValueMapConverter.SourceVariable.SetDynamicLink(sourceVariable);
284 |     // Add the key value converter to the variable
285 |     targetNode.SetConverter(newValueMapConverter);
286 | }
287 | ```
288 | 
289 | #### Creating a Conditional Converter
290 | 
291 | ```csharp
292 | private void StuffCreateConditionalConverter(IUAVariable targetNode, IUAVariable sourceVariable)
293 | {
294 |     // Create the conditional converter
295 |     ConditionalConverter newConditionalConverter = InformationModel.MakeObject<ConditionalConverter>("ConditionalConverter1", FTOptix.CoreBase.ObjectTypes.ConditionalConverter);
296 |     // Set the "false" condition
297 |     newConditionalConverter.FalseValueVariable.DataType = FTOptix.Core.DataTypes.Color;
298 |     newConditionalConverter.FalseValueVariable.Value = System.Drawing.Color.Red.ToArgb();
299 |     // Set the "true" condition
300 |     newConditionalConverter.TrueValueVariable.DataType = FTOptix.Core.DataTypes.Color;
301 |     newConditionalConverter.TrueValueVariable.Value = System.Drawing.Color.Green.ToArgb();
302 |     // Add the source variable
303 |     newConditionalConverter.ConditionVariable.SetDynamicLink(sourceVariable);
304 |     // Set the dynamic link to the object
305 |     newConditionalConverter.Mode = DynamicLinkMode.Read;
306 |     targetNode.SetConverter(newConditionalConverter);
307 | }
308 | ```
309 | 


--------------------------------------------------------------------------------
/pages/events.md:
--------------------------------------------------------------------------------
  1 | # Events handling
  2 | 
  3 | > [!WARNING]
  4 | > This section is a work in progress and uses some low-level APIs.
  5 | > The documentation will be completed as soon as possible.
  6 | 
  7 | ## Add MouseClick event to a Button
  8 | 
  9 | This code adds a GeneratePDF method to a button, and a SetVariableValue to a different button
 10 | 
 11 | ```csharp
 12 | #region Using directives
 13 | using System;
 14 | using System.Collections.Generic;
 15 | using System.Linq;
 16 | using UAManagedCore;
 17 | using OpcUa = UAManagedCore.OpcUa;
 18 | using FTOptix.HMIProject;
 19 | using FTOptix.UI;
 20 | using FTOptix.Core;
 21 | using FTOptix.CoreBase;
 22 | using FTOptix.NetLogic;
 23 | #endregion
 24 | 
 25 | public class DesignTimeNetLogic1 : BaseNetLogic
 26 | {
 27 |     [ExportMethod]
 28 |     public void CreateEventHandlers()
 29 |     {
 30 |         var mainWindow = Project.Current.Get<WindowType>("UI/MainWindow");
 31 |         var generateReportButton = mainWindow.Get<Button>("GenerateReportButton");
 32 |         var changeColorButton = mainWindow.Get<Button>("ChangeColorButton");
 33 |         var button1 = mainWindow.Get<Button>("Button1");
 34 |         var button1BackgroundColor = button1.BackgroundColorVariable;
 35 | 
 36 |         // Make sure to remove old handlers (if any)
 37 |         var oldEventHandlers = generateReportButton.Children.OfType<FTOptix.CoreBase.EventHandler>().ToList();
 38 |         oldEventHandlers.AddRange(changeColorButton.Children.OfType<FTOptix.CoreBase.EventHandler>());
 39 |         foreach (var oldEventHandler in oldEventHandlers)
 40 |             oldEventHandler.Delete();
 41 | 
 42 |         // Report object that we want to create with a button
 43 |         var report1 = Project.Current.GetObject("Reports/Report1");
 44 | 
 45 |         MakeEventHandler( // Add the GeneratePdf method to the button
 46 |             generateReportButton, // Object where to create the method
 47 |             FTOptix.UI.ObjectTypes.MouseClickEvent, // Method to be created
 48 |             report1, // Object pointer where to call the method
 49 |             "GeneratePdf", // Method name
 50 |             new List<Tuple<string, NodeId, object>> // Method arguments
 51 |             {
 52 |                 // Each row is a tuple, each tuple contains a string (name of the argument), a NodeId (DataType) and an Object (value)
 53 |                 new("OutputPath", FTOptix.Core.DataTypes.ResourceUri, (string)ResourceUri.FromApplicationRelativePath("MyReport.pdf")),
 54 |                 new("LocaleId", OpcUa.DataTypes.String, "en-US")
 55 |             }
 56 |         );
 57 |         
 58 |         MakeEventHandler( // Add the SetVariableValue method to the button
 59 |             changeColorButton, // Object where to create the method
 60 |             FTOptix.UI.ObjectTypes.MouseClickEvent, // Event to be added
 61 |             InformationModel.GetObject(FTOptix.CoreBase.Objects.VariableCommands), // Object that exposes the method
 62 |             "Set", // Name of the method
 63 |             new List<Tuple<string, NodeId, object>> // Method arguments
 64 |             {
 65 |                 // Each row is a tuple, each tuple contains a string (name of the argument), a NodeId (DataType) and an Object (value)
 66 |                 new("VariableToModify", FTOptix.Core.DataTypes.VariablePointer, NodeId.Empty),
 67 |                 new("Value", FTOptix.Core.DataTypes.Color, new Color(0xff3480ebu).ARGB),
 68 |                 new("ArrayIndex", OpcUa.DataTypes.UInt32, 0u)
 69 |             }
 70 |         );
 71 | 
 72 |         // Set which variable to be modified by the Set method
 73 |         var changeColorButtonEventHandler = changeColorButton.Get("EventHandler");
 74 |         // This path can be different depending on the MethodContainer name assigned by the MakeEventHandler method
 75 |         var variableToModifyArgumentVariable = changeColorButtonEventHandler.GetVariable("MethodsToCall/MethodContainer1/InputArguments/VariableToModify");
 76 |         // Assign a DynamicLink to the VariableToModify
 77 |         variableToModifyArgumentVariable.SetDynamicLink(button1BackgroundColor);
 78 |         // Change the DynamicLink to make sure the NodeId attribute is used (IDE has a fallback to the @Value otherwise)
 79 |         var dynamicLink = variableToModifyArgumentVariable.Children.OfType<DynamicLink>().First();
 80 |         dynamicLink.Value = dynamicLink.Value + "@NodeId";
 81 |     }
 82 | 
 83 |     private FTOptix.CoreBase.EventHandler MakeEventHandler(
 84 |         IUANode parentNode, // The parent node to which the event handler is to be added
 85 |         NodeId listenEventTypeId, // The NodeID of the event to be listened
 86 |         IUAObject callingObject, // The object on which the method is to be executed
 87 |         string methodName, // The name of the method to be called
 88 |         List<Tuple<string, NodeId, object>> arguments = null // List of input arguments (name, data type NodeID, value)
 89 |     )
 90 |     {
 91 |         // Create event handler object
 92 |         var eventHandler = InformationModel.MakeObject<FTOptix.CoreBase.EventHandler>("EventHandler");
 93 |         parentNode.Add(eventHandler);
 94 | 
 95 |         // Set the ListenEventType variable value to the Node ID of the event to be listened
 96 |         eventHandler.ListenEventType = listenEventTypeId;
 97 | 
 98 |         // Create method container
 99 |         // This must be an unique name if the multiple methods are added to the same button. A random name can also be used
100 |         var methodIndex = eventHandler.MethodsToCall.Any() ? eventHandler.MethodsToCall.Count + 1 : 1;
101 |         var methodContainer = InformationModel.MakeObject($"MethodContainer{methodIndex}");
102 |         eventHandler.MethodsToCall.Add(methodContainer);
103 | 
104 |         // Create the ObjectPointer variable and set its value to the object on which the method is to be executed
105 |         var objectPointerVariable = InformationModel.MakeVariable<NodePointer>("ObjectPointer", OpcUa.DataTypes.NodeId);
106 |         objectPointerVariable.Value = callingObject.NodeId;
107 |         methodContainer.Add(objectPointerVariable);
108 | 
109 |         // Create the Method variable and set its value to the name of the method to be called
110 |         var methodNameVariable = InformationModel.MakeVariable("Method", OpcUa.DataTypes.String);
111 |         methodNameVariable.Value = methodName;
112 |         methodContainer.Add(methodNameVariable);
113 | 
114 |         if (arguments != null)
115 |             CreateInputArguments(methodContainer, arguments);
116 | 
117 |         return eventHandler;
118 |     }
119 | 
120 |     private void CreateInputArguments(
121 |         IUANode methodContainer,
122 |         List<Tuple<string, NodeId, object>> arguments)
123 |     {
124 |         IUAObject inputArguments = InformationModel.MakeObject("InputArguments");
125 |         methodContainer.Add(inputArguments);
126 | 
127 |         foreach (var arg in arguments)
128 |         {
129 |             var argumentVariable = inputArguments.Context.NodeFactory.MakeVariable(
130 |                 NodeId.Random(inputArguments.NodeId.NamespaceIndex),
131 |                 arg.Item1,
132 |                 arg.Item2,
133 |                 OpcUa.VariableTypes.BaseDataVariableType,
134 |                 false,
135 |                 arg.Item3);
136 | 
137 |             inputArguments.Add(argumentVariable);
138 |         }
139 |     }
140 | }
141 | 
142 | ```
143 | 
144 | ## Add a method handler to an object
145 | 
146 | ```csharp
147 | #region Using directives
148 | 
149 | using System;
150 | using System.Collections.Generic;
151 | using System.Linq;
152 | using FTOptix.Core;
153 | using FTOptix.CoreBase;
154 | using FTOptix.HMIProject;
155 | using FTOptix.NetLogic;
156 | using UAManagedCore;
157 | using OpcUa = UAManagedCore.OpcUa;
158 | 
159 | #endregion
160 | 
161 | public class CreateEventHandler : BaseNetLogic
162 | {
163 |     private FTOptix.CoreBase.EventHandler MakeEventHandler(
164 |        IUANode parentNode, // The parent node to which the event handler is to be added
165 |        NodeId listenEventTypeId, // The NodeID of the event to be listened
166 |        IUAObject callingObject, // The object on which the method is to be executed
167 |        string methodName, // The name of the method to be called
168 |        List<Tuple<string, NodeId, object>> arguments = null // List of input arguments (name, data type NodeID, value)
169 |     )
170 | 
171 |     {
172 |         // Create event handler object
173 |         var eventHandler = InformationModel.MakeObject<FTOptix.CoreBase.EventHandler>("EventHandler");
174 |         parentNode.Add(eventHandler);
175 | 
176 |         // Set the ListenEventType variable value to the Node ID of the event to be listened
177 |         eventHandler.ListenEventType = listenEventTypeId;
178 | 
179 |         // Create method container
180 |         var methodContainer = InformationModel.MakeObject("MethodContainer1");
181 |         eventHandler.MethodsToCall.Add(methodContainer);
182 | 
183 |         // Create the ObjectPointer variable and set its value to the object on which the method is to be executed
184 |         var objectPointerVariable = InformationModel.MakeVariable<NodePointer>("ObjectPointer", OpcUa.DataTypes.NodeId);
185 |         objectPointerVariable.Value = callingObject.NodeId;
186 |         string resultPath = CreateRelativePath(parentNode, callingObject);
187 |         var isCore = resultPath.Contains("Root");
188 |         if (!isCore)
189 |         {
190 |             IUAVariable temp = null;
191 |             objectPointerVariable.SetDynamicLink(temp, DynamicLinkMode.ReadWrite);
192 |             objectPointerVariable.GetVariable("DynamicLink").Value = "../../../../" + resultPath;
193 |         }
194 | 
195 |         methodContainer.Add(objectPointerVariable);
196 | 
197 |         // Create the Method variable and set its value to the name of the method to be called
198 |         var methodNameVariable = InformationModel.MakeVariable("Method", OpcUa.DataTypes.String);
199 |         methodNameVariable.Value = methodName;
200 |         methodContainer.Add(methodNameVariable);
201 | 
202 |         if (arguments != null)
203 |             CreateInputArguments(methodContainer, arguments);
204 | 
205 |         return eventHandler;
206 |     }
207 | 
208 |     private void CreateInputArguments(
209 |         IUANode methodContainer,
210 |         List<Tuple<string, NodeId, object>> arguments)
211 |     {
212 |         IUAObject inputArguments = InformationModel.MakeObject("InputArguments");
213 |         methodContainer.Add(inputArguments);
214 | 
215 |         foreach (var arg in arguments)
216 |         {
217 |             var argumentVariable = inputArguments.Context.NodeFactory.MakeVariable(
218 |                 NodeId.Random(inputArguments.NodeId.NamespaceIndex),
219 |                 arg.Item1,
220 |                 arg.Item2,
221 |                 OpcUa.VariableTypes.BaseDataVariableType,
222 |                 false,
223 |                 arg.Item3);
224 | 
225 |             inputArguments.Add(argumentVariable);
226 |         }
227 |     }
228 | 
229 |     private static string CreateRelativePath(IUANode source, IUANode target)
230 |     {
231 |         string result = "";
232 |         var srcPath = GetCurrentProjectBrowsePath(source);
233 |         var tarPath = GetCurrentProjectBrowsePath(target);
234 |         var srcArr = srcPath.Split("/");
235 |         var tarArr = tarPath.Split("/");
236 |         var max = Math.Max(srcPath.Count(), tarPath.Count());
237 |         int i = 0;
238 |         for (; i < max; i++)
239 |         {
240 |             result = "..";
241 |             if (srcArr[i] != tarArr[i])
242 |             {
243 |                 break;
244 |             }
245 |         }
246 |         for (int j = srcArr.Count() - 1; j > i; j--)
247 |         {
248 |             result = result + "/..";
249 |         }
250 |         for (int k = i; k < tarArr.Count(); k++)
251 |         {
252 |             result = result + "/" + tarArr[k];
253 |         }
254 |         return result;
255 |     }
256 | 
257 |     private static string GetCurrentProjectBrowsePath(IUANode node)
258 |     {
259 |         if (node.Owner == Project.Current || node.BrowseName == "Root")
260 |             return node.BrowseName;
261 |         return GetCurrentProjectBrowsePath(node.Owner) + "/" + node.BrowseName;
262 |     }
263 | }
264 | ```
265 | 
266 | ## Subscribe to methods execution
267 | 
268 | This script can be put anywhere on the project and will listen to every OPCUA method being called (script or UI)
269 | 
270 | ```csharp
271 | public class MethodExecutionAuditLogic : BaseNetLogic, IUAEventObserver
272 | {
273 |     public override void Start()
274 |     {
275 |         var serverObject = LogicObject.Context.GetObject(OpcUa.Objects.Server);
276 |         //eventRegistration = serverObject.RegisterUAEventObserver(this, UAManagedCore.OpcUa.ObjectTypes.AuditUpdateMethodEventType);
277 |     }
278 | 
279 |     public override void Stop()
280 |     {
281 |         // Insert code to be executed when the user-defined logic is stopped
282 |     }
283 | 
284 |     public void OnEvent(IUAObject eventNotifier, IUAObjectType eventType, IReadOnlyList<object> eventData, ulong senderId)
285 |     {
286 |         StringBuilder builder = new StringBuilder();
287 |         builder.Append($"Event of type {eventType.BrowseName} triggered");
288 | 
289 |         var eventArguments = eventType.EventArguments;
290 |         foreach (var eventField in eventArguments.GetFields())
291 |         {
292 |             var fieldValue = eventArguments.GetFieldValue(eventData, eventField);
293 |             builder.Append($"\t{eventField} = {fieldValue?.ToString() ?? "null"}");
294 |         }
295 | 
296 |         builder.Append("\n");
297 |         Log.Info(builder.ToString());
298 |     }
299 | 
300 |   //  private IEventRegistration eventRegistration;
301 | }
302 | ```
303 | 
304 | ## Add a VariableChanged event to a variable
305 | 
306 | > [!WARNING]
307 | > This method can only work at DesignTime
308 | 
309 | ```csharp
310 | [ExportMethod]
311 | public void AddVariableChangeEvent()
312 | {
313 |     IUAVariable targetVariable = null;
314 |     try
315 |     {
316 |         targetVariable = InformationModel.GetVariable(LogicObject.GetVariable("VariableToAddChangeMethod").Value);
317 |     }
318 |     catch
319 |     {
320 |         Log.Error("Variable not found");
321 |         return;
322 |     }
323 | 
324 |     var variableOwner = targetVariable.Owner;
325 |     var variableChangedEventDispatcher = InformationModel.Make<VariableChangedEventDispatcher>($"{targetVariable.BrowseName}Changed");
326 |     variableChangedEventDispatcher.GetVariable("VariableNodePath").Value = $"../{targetVariable.BrowseName}";
327 | 
328 |     variableOwner.Add(variableChangedEventDispatcher);
329 | }
330 | ```
331 | 


--------------------------------------------------------------------------------
/pages/execute-command.md:
--------------------------------------------------------------------------------
  1 | # Execute commands
  2 | 
  3 | ## OPC/UA Methods
  4 | 
  5 | See [here](./creating-objects.md)
  6 | 
  7 | ## Execute external commands (CMD or external softwares)
  8 | 
  9 | ```csharp
 10 | using System.Diagnostics;
 11 | 
 12 | static void ExecuteCommand(string command)
 13 | {
 14 |     int exitCode;
 15 |     ProcessStartInfo processInfo;
 16 |     Process process;
 17 |     // Create the new command and launch it using the command prompt
 18 |     processInfo = new ProcessStartInfo("cmd.exe", "/c " + command);
 19 |     processInfo.CreateNoWindow = true;
 20 |     processInfo.UseShellExecute = false;
 21 |     //Redirect the output
 22 |     processInfo.RedirectStandardError = true;
 23 |     processInfo.RedirectStandardOutput = true;
 24 |     // Start the process
 25 |     process = Process.Start(processInfo);
 26 |     process.WaitForExit();
 27 |     // Read the streams
 28 |     // Warning: This approach can lead to deadlocks
 29 |     string output = process.StandardOutput.ReadToEnd();
 30 |     string error = process.StandardError.ReadToEnd();
 31 |     // Read the exit code
 32 |     exitCode = process.ExitCode;
 33 |     // Print some output
 34 |     Log.Info("output>>" + (String.IsNullOrEmpty(output) ? "(none)" : output));
 35 |     Log.Info("error>>" + (String.IsNullOrEmpty(error) ? "(none)" : error));
 36 |     Log.Info("ExitCode: " + exitCode.ToString(), "ExecuteCommand");
 37 |     // Close the process handler
 38 |     process.Close();
 39 | }
 40 | ```
 41 | 
 42 | ## Open a WebBrowser to a specific page
 43 | 
 44 | ```csharp
 45 | [ExportMethod]
 46 | public void OpenBrowser(string urlPath) {
 47 |     //string destinationPath = new ResourceUri(urlPath).Uri;
 48 |     string destinationPath = urlPath;
 49 |     Process myProcess = new Process();
 50 | 
 51 |     try {
 52 |         // true is the default, but it is important not to set it to false
 53 |         myProcess.StartInfo.UseShellExecute = true;
 54 |         myProcess.StartInfo.FileName = destinationPath;
 55 |         // Start the process
 56 |         myProcess.Start();
 57 |     } catch (Exception e) {
 58 |         // Print any exception (if needed)
 59 |         Log.Error("OpenInBrowser", e.Message);
 60 |     }
 61 | }
 62 | ```
 63 | 
 64 | ## Execute FT Optix Core commands
 65 | 
 66 | ```csharp
 67 | // Get the core commands object (exposed by FT Optix APIs)
 68 | var coreCommandsObject = InformationModel.GetObject(FTOptix.CoreBase.Objects.CoreCommands);
 69 | // Call a specific command
 70 | coreCommandsObject.ExecuteMethod("Close");
 71 | ```
 72 | 
 73 | ## Execute FT Optix Alarm commands
 74 | 
 75 | ```csharp
 76 | // Get the alarms object
 77 | var alarmCommands = InformationModel.GetObject(FTOptix.Alarm.Objects.AlarmCommands);
 78 | // Acknowledge all alarms
 79 | alarmCommands.ExecuteMethod("AcknowledgeAll");
 80 | // Confirm all alarms
 81 | alarmCommands.ExecuteMethod("ConfirmAll");
 82 | ```
 83 | 
 84 | ## Execute a method from a different NetLogic
 85 | 
 86 | Calling a NetLogic instance with `var myNetLogic = new MyNetLogic();` will create a new instance of the NetLogic, but it will not be the same as the one that is running in the project so it should be avoided. To call a method from a different NetLogic, you need to get the NetLogic object from the project and then call the method on that object.
 87 | 
 88 | ```csharp
 89 | [ExportMethod]
 90 | public void CallMethod1()
 91 | {
 92 |     // Get the NetLogic containing the method to execute
 93 |     var myScript = Project.Current.GetObject("NetLogic/RuntimeNetLogic1");
 94 |     // Launch the method
 95 |     myScript.ExecuteMethod("Method1");
 96 | }
 97 | ```
 98 | 
 99 | ### Execute a method from a different NetLogic with parameters
100 | 
101 | #### NetLogic to be called
102 | 
103 | ```csharp
104 | public class AlarmGridLogic : BaseNetLogic
105 | {
106 |     [ExportMethod]
107 |     public void AckAllAlarmsWithMessage(object[] arguments)
108 |     {
109 |         var ackMessage = (LocalizedText) arguments[0];
110 |         var alarmsList = GetAllAlarms();
111 |         if (alarmsList.Count == 0)
112 |         {
113 |             Log.Warning("No alarms to acknowledge");
114 |             return;
115 |         }
116 |         ProcessAlarms(ackMessage, alarmsList, (alarm, message) => alarm.Acknowledge(message));
117 |     }
118 | }
119 | ```
120 | 
121 | #### Caller
122 | 
123 | ```csharp
124 | public class AckConfirmMessageLogic : BaseNetLogic
125 | {
126 |     [ExportMethod]
127 |     public void PerformAction()
128 |     {
129 |         // Get the target NetLogic object
130 |         var alarmsNetLogic = GetNetLogicObject();
131 |         // Get the action name to be executed
132 |         string action = Owner.GetVariable("MethodName").Value;
133 |         // Get the comment to be added to the alarm
134 |         var comment = Owner.Get<TextBox>("Comment").LocalizedText;
135 |         // Create the object arguments to be passed to the method
136 |         object[] arguments = new object[] { comment };
137 |         alarmsNetLogic.ExecuteMethod(action, [arguments]);
138 |         (Owner as Dialog)?.Close();
139 |     }
140 | 
141 |     private IUAObject GetNetLogicObject()
142 |     {
143 |         // Here the NetLogic is passed as a variable to the owner object,
144 |         // but it could be retrieved in a different way (like Project.Current.GetObject)
145 |         return InformationModel.GetObject(Owner.GetVariable("AlarmGridLogic").Value);
146 |     }
147 | }
148 | ```
149 | 


--------------------------------------------------------------------------------
/pages/good-practices.md:
--------------------------------------------------------------------------------
 1 | # Good practices
 2 | 
 3 | Here is a list of convention our FT Optix technicians uses when creating new projects, feel free to choose if this can apply to your project
 4 | 
 5 | - Use significative names for every project element (no default names)
 6 |     - Exception is made when creating object types, still remember to give meaningful name if possible
 7 |     - Avoid using number at the end of item name
 8 |     - Avoid abbreviations in object names to improve readability
 9 |     - Examples:
10 |         - `Templates/SpinBox (Type)` -> BAD
11 |         - `Templates/SpinBoxWithGreenBorder (Type)` -> GOOD
12 |         - `MainWindow/SpinBox1` -> BAD
13 |         - `MainWindow/MotorSpeed_SpinBox` -> GOOD
14 |         - `MainWindow/MotorSP_SB` -> BAD
15 | - Nice to use same EmbeddedDatabase for every item to be stored
16 |     - Multiple tables can be used in same EmbeddedDatabase with different settings (RecordLimit, Names, etc)
17 | - Use `PascalCase` for object names
18 | - Use `camelCase` for variable names (Model, Session and Local variables)
19 | - All graphical elements should be in `UI` folder
20 | 	- Here you can create standard folders to organize your work, such as:
21 | 		- `UI/Templates`-> Contains all custom types used to create objects
22 | 		- `UI/Screens` -> Contains the different pages that are used in the project
23 | 	- Both subfolder can have children subfolder to organize elements if needed
24 | 		- Example:
25 | 			- `UI/Templates/MotorWidgets`
26 | 			- `UI/Templates/PumpsWidgets`
27 | 			- `UI/Screens/Filler`
28 | 			- `UI/Screens/Settings`
29 | 	- Nice to use Templates folder in any first level project folder (e.g. UI, Model, Converters, etc...) when creating custom types
30 | 
31 | - Global variables should be created in the `Model` folder (and subfolder)
32 | - Nice to use HTML color palette if no special need for custom coloring
33 | 	- Example:
34 | 		- `red` -> GOOD
35 | 		- `#FFA1C8` -> BAD
36 | - Object names and LocalizationDictionary keys should be in English
37 | - Nice to sort items by their type in project tree
38 | 	- Exception is made when defining layers is necessary to build final interface (bottom most element is highest layer)
39 | - When creating a new page/container, avoid using a `Panel` with a `Rectangle` as coloured background to avoid doubling project nodes
40 | 	- Use instead:
41 | 		- `Screen` if the object is a whole screen that is going to be displayed in the HMI
42 | 		- `Rectangle` if coloured background is needed
43 | 		- `Panel` if background should be transparent (usually to group elements)
44 | - Nice to group items using Panel
45 | 	- This is useful to reduce project complexity when assigning groups-based permissions and/or to trigger specific visual logics (enabling, visibility, etc)
46 | - Nice to use same `Label` name and `LocalizationDictionary` item key
47 | - Nice to use keyword in controls names to identify which variable/object is referring to 
48 | 	- Example:
49 | 		- `VoltageText` -> Label that shows the translation key for the _Voltage_ element
50 | 		- `VoltageValue` -> Name for a LinearGauge controlling _Voltage_ value
51 | 


--------------------------------------------------------------------------------
/pages/information-model.md:
--------------------------------------------------------------------------------
 1 | # The Information Model
 2 | 
 3 | ## Overview
 4 | 
 5 | In FactoryTalk Optix, each and every object is a `node`, the definition of a node comes from the OPC/UA specifications which states that an OPC/UA node is like an entity representing information. Some Nodes are Variables, DataType, References, Object, Methods... depending of what they are used for.
 6 | 
 7 | The OPC/UA specifications can be found at the following link [opcfoundation resources](https://opcfoundation.org/developer-tools/documents/?type=Specification) and search for [OPC 10000-1 UA Part 1: Overview and Concepts](https://opcfoundation.org/developer-tools/documents/view/158) and [OPC 10000-3 UA Part 3: Address Space Model](https://opcfoundation.org/developer-tools/documents/view/160)
 8 | 
 9 | Understanding the concept of nodes is crucial when working with FactoryTalk Optix because it forms the backbone of the OPC/UA information model, which FactoryTalk Optix leverages for data representation and interaction. Nodes represent various types of information and their relationships, enabling a standardized way to access and manipulate data within the system. This allows integration and interoperability between different components and devices, ensuring that data can be efficiently managed and utilized across the entire project.
10 | 
11 | ### The Information Model of OPC/UA
12 | 
13 | The OPC Unified Architecture (OPC/UA) defines a rich information model that allows for complex data representation and interaction. At the core of this model is the concept of a "node". A node is an entity that represents information and can be of various types, each serving a different purpose within the information model. The major properties of a node include:
14 | 
15 | - **NodeId**: A unique identifier for the node within the address space.
16 | - **BrowseName**: A human-readable name used for browsing the node.
17 | - **DisplayName**: A localized name intended for display purposes.
18 | - **Description**: A localized text description of the node.
19 | 
20 | Nodes can be of different types, including:
21 | 
22 | - **Object**: Represents physical or abstract entities.
23 | - **Variable**: Holds a value and can have a data type.
24 | - **Method**: Represents callable functions or procedures.
25 | - **ObjectType**: Defines the type of an object.
26 | - **VariableType**: Defines the type of a variable.
27 | - **ReferenceType**: Defines the type of a reference between nodes.
28 | - **DataType**: Defines the data type of a variable.
29 | - **View**: Represents a subset of the address space for browsing.
30 | 
31 | These nodes and their properties form the foundation of the OPC/UA information model, enabling a standardized way to represent and interact with data across different systems and devices.
32 | 
33 | ### The Information Model of FactoryTalk Optix
34 | 
35 | As everything in FactoryTalk Optix is actually an OPC/UA node, we can implement some complex scenarios like:
36 | 
37 | - Allowing other applications (both FactoryTalk Optix or third-parties) to read and write project nodes
38 |     - This includes exposing project elements like Databases, PLC Tags, Model variables, UI objects, etc
39 | - Allowing other applications to produce and consume alarms and events using the OPC/UA A&E protocol
40 | - Manipulating parts of the project using NetLogic or an external OPC/UA client
41 | 
42 | ## Project context
43 | 
44 | Accessing the path of the node will return the project-level node, this is good for global elements (Model Variables, PLC Tags, etc) but it cannot be used to access session-based elements, as each user session will have a unique instance of windows and pages with uniques NodeIds
45 | 
46 | ### Overview
47 | 
48 | ![Project vs session](../images/session-concept.png)
49 | 
50 | FactoryTalk Optix graphical interface is based on the object's oriented paradigm, this means that when defining UI elements at design-time, these are actually created as object types. When the runtime starts, and a session is created (NativePresentationEngine creates automatically one UI instance, each client of the WebPresentationEngine creates one UI instance), this session is derived from the UI type that was designed, thus becoming an instance.
51 | 
52 | Each session lives as an independent object, each session can interact with global objects (such as Model variables or PLC tags) but cannot access other sessions, when calling methods that targets a session object (such as the refresh of a DataGrid), it can only affect the session where the method was called, other instances and sessions are unaffected.
53 | 
54 | NetLogic are also affected by this functionality:
55 | - When using the `Project.Current.Get` syntax, only the project definition can be accessed, if a UI element is manipulated using such syntax, the session instance must be destroyed and recreated in order to inherit the new changes (for example navigating to a different page and then coming back)
56 | - When placing the NetLogic inside a page (which can be something like a Screen, a Panel, a Rectangle, or any UI object) and using the `Owner.Get` syntax, the specific instance where the NetLogic is executed gets accessed and the UI is immediately refreshed. Only the instance where the NetLogic exists can be accessed, a session-based NetLogic cannot interact with other sessions, only with elements in the current session or global objects (such as PLC tags or Model variables).
57 | 
58 | ### Summary
59 | 
60 | - Each session of a PresentationEngine creates an instance of the UI types
61 | - Each session is completely independent from other session
62 | - A session can only interact with:
63 |     - Elements in the same session
64 |     - Global objects (Model variables, PLC tags, alarms, etc)
65 | - A session cannot interact with other sessions
66 | - Session changes are discarded when the instance is destroyed (page is changed or reloaded)
67 |     - Retentivity cannot be applied to session objects
68 |     - Retentivity should never be applied to any UI object
69 | - A session can access global objects, but global objects cannot access session objects, for example:
70 |     - A global NetLogic cannot refresh the DataGrid of a session, a global NetLogic can only access nodes at the project level (such as alarms, PLC tags, Model variables, etc)
71 |     - A session NetLogic can access all global objects, all elements of the current UI session but cannot access other sessions.
72 | 
73 | ### Examples
74 | 
75 | #### Refreshing a DataGrid
76 | 
77 | As the DataGrid is a session object, the NetLogic to refresh a DataGrid must be placed at a session level
78 | 
79 | #### Creating a new alarm
80 | 
81 | As the Alarm is a global object, the NetLogic can be either at the session level or at a global level
82 | 
83 | #### Performing an SQL query
84 | 
85 | Here it depends on the final goal:
86 | 
87 | - If just inserting data to a database, the NetLogic can be either at the session level or at a global level, the data can be passed as global variable or as argument of the called method
88 | - If performing a query (such as a SELECT) depending on some parameters from the user, the NetLogic must be placed at the session level (where TextBox or other controls can be accessed)
89 | - If performing a query (such as a SELECT or an INSERT) depending on some values from the controller (PLC), the NetLogic can be placed either at a global or session level


--------------------------------------------------------------------------------
/pages/log-output.md:
--------------------------------------------------------------------------------
 1 | # Log messages
 2 | 
 3 | Log messages can be displayed both at RunTime and DesignTime, at DesignTime logs will appear in `Optix Studio Output` while at RunTime they will appear in the `Emulator output` or the RunTime log
 4 | 
 5 | ## General syntax
 6 | 
 7 | `Log . [level] ( [optional category] , [ message content] );`
 8 | 
 9 | ## Examples
10 | 
11 | Different log levels can be triggered and then filtered in `Optix Studio Output` and `Emulator output`. Specifying an optional custom `Category` helps you understanding where this line was generated (for example the NetLogic name and/or the method name)
12 | 
13 | - `Log.Error(category, message);`
14 | - `Log.Warning(category, message);`
15 | - `Log.Info(category, message);`
16 | - `Log.Debug(category, message);`
17 | - `Log.Verbose1(category, message);`
18 | - `Log.Verbose2(category, message);`
19 | 
20 | ## Get the node path for any project node
21 | 
22 | - `Log.Node(IUANode);` -> Returns a string containing the node path for a specific element
23 | 
24 | ## Getting total count of project nodes
25 | 
26 | - `LogicObject.Context.NodeCount` -> returns the total number of nodes (whole project)
27 | 
28 | ## Reading debug logs
29 | 
30 | When debug logs are enabled, the output of some rendering methods is logged to the output, here is an example:
31 | 
32 | ```txt
33 | 2024-10-22 10:55:05     NativeUI    StartNetLogics,10,6,600.000
34 | ```
35 | 
36 | The syntax is:
37 | 
38 | ```txt
39 | [Timestamp]    [Module Name]    [Method Name];[Total time in ms],[Number of processed items],[Items per second]
40 | ```
41 | 
42 | So, in the example above we get the NativeUI:
43 | 
44 | - Executing the `Start` method of all NetLogics in the page
45 | - Starting a total of 6 NetLogics
46 | - Running at a theoretical 600 NetLogics per second can be loaded (this is something like benchmarking)
47 | 


--------------------------------------------------------------------------------
/pages/managing-aliases.md:
--------------------------------------------------------------------------------
 1 | # Managing Aliases
 2 | 
 3 | ## Delete the value from an Alias
 4 | 
 5 | ```csharp
 6 | Project.Current.Get("UI/Pages/MainPage").SetAlias("MainBoilerAlias", NodeId.Empty);
 7 | ```
 8 | 
 9 | ## Delete the Kind property of an Alias
10 | 
11 | ```csharp
12 | Project.Current.Get<Alias>("UI/Pages/MainPage/MainBoilerAlias").Kind = NodeId.Empty;
13 | ```
14 | 
15 | ## Connect an Alias to a node
16 | 
17 | ```csharp
18 | // Get the target variable
19 | var targetVariable = Project.Current.Get<Tag>("CommDriver/RAEthernetIP/Station1/InletPump");
20 | // Set the alias to the target value
21 | Project.Current.Get("UI/Pages/MainPage").SetAlias("MainBoilerAlias", targetVariable.NodeId);
22 | ```
23 | 


--------------------------------------------------------------------------------
/pages/netlogic-overview.md:
--------------------------------------------------------------------------------
 1 | # NetLogic overview
 2 | 
 3 | - NetLogic are C# scripts that help you implementing custom and/or advanced logic in FT OPtix with custom code.
 4 | - There are no limits on the amount of C# snippet you can add to a project
 5 | - There are some limitations on the packages you can add to a NetLogic
 6 |     - Example:
 7 |         - `WPF` (WindowsForms) -> These are not supported as they are not cross platform in the way FT Optix works
 8 |         - `ActiveX` -> These are not supported as they are old and unsecure
 9 |         - `MSSQL` (Microsoft SQL) -> This is not supported as FT Optix APIs offers a common syntax to access both EmbeddedDatabase and ODBC with same syntax by translating the output query for you. This is needed to make SQL independents from the type of database you are accessing
10 |             - This limitation was removed starting from FT Optix 1.6.0.44, assuming at least one ODBC Connector is added to the project (even if unused)
11 | - NetLogic can be RunTime or DesignTime
12 |     - `RunTime NetLogic` -> This is the most common type of NetLogic, you can use it to trigger custom logic when the RunTime is running
13 |     - `DesignTime NetLogic` -> These king of NetLogic are typically used to make the designer's life easier by automating some repetitive operations (such as creating hundreds of alarms, variables, assigning DynamicLink and more)   
14 | - Distinction between the two kind of NetLogic only exists in the YAML definition, the same APIs can be used both at DesignTime and/or at RunTime
15 |     - DesignTime NetLogic can only access elements that exists at DesignTime, you cannot access a `CommDriver` or a `Database` if the application is not running
16 | 
17 | ## Things to remember
18 | 
19 | - NetLogic class name is the same of the NetLogic object name
20 |     - Don't change the NetLogic name from any external editor, rename it from Studio instead!
21 | - NetLogic objects can be browsed from the NetSolution
22 |     - Don't delete a NetLogic from the solution, remove it from Studio instead!
23 |     - Don't move a NetLogic from any external editor, move it from Studio (better to copy paste the NetLogic in the new position and then delete it from the unused place)
24 | 


--------------------------------------------------------------------------------
/pages/opcua.md:
--------------------------------------------------------------------------------
  1 | # OPC/UA
  2 | 
  3 | ## Node's references
  4 | 
  5 | In OPC/UA, some nodes may have additional references are explicit relationship (a named pointer) from one Node to another
  6 | 
  7 | ```csharp
  8 | [ExportMethod]
  9 | public void ReadReference(NodeId element)
 10 | {
 11 |     // Get to the element where we want to investigate the OPC/UA references
 12 |     IUANode targetNode = InformationModel.Get(element);
 13 |     // Assuming the node exists
 14 |     if (targetNode != null)
 15 |     {
 16 |         // Loop per each reference and list it in the console output
 17 |         foreach (var item in targetNode.Refs.GetReferences())
 18 |         {
 19 |             Log.Info("References", $"ReferenceTypeId: {item.ReferenceTypeId}, TargetNodeId: {item.TargetNodeId}, TargetNode: {item.TargetNode.BrowseName}");
 20 |         }
 21 |     }
 22 |     else
 23 |     {
 24 |         Log.Info("References", "Cannot find such node in the current project");
 25 |     }
 26 | }
 27 | ```
 28 | 
 29 | ## Read arbitrary tag from an OPC/UA Server
 30 | 
 31 | > [!WARNING]
 32 | > This method involves some low-level OPC/UA operations and may not be recommended for production usage. It is recommended to use the OPC/UA Client TagImporter instead.
 33 | 
 34 | This method allows to read any OPC/UA variables from a remote server knowing its `NameSpaceIndex` and `ID`. The following examples reads the `Server > ServerStatus > State` (0/2259) variable from the UaAnsiCServer from the OPC Foundation 
 35 | 
 36 | ```csharp
 37 | // This list comes from the OPC/UA specification
 38 | enum OpcAttributes
 39 | {
 40 |     NodeId = 1,
 41 |     NodeClass = 2,
 42 |     BrowseName = 3,
 43 |     DisplayName = 4,
 44 |     Description = 5,
 45 |     WriteMask = 6,
 46 |     UserWriteMask = 7,
 47 |     IsAbstract = 8,
 48 |     Symmetric = 9,
 49 |     InverseName = 10,
 50 |     ContainsNoLoops = 11,
 51 |     EventNotifier = 12,
 52 |     Value = 13,
 53 |     DataType = 14,
 54 |     ValueRank = 15,
 55 |     ArrayDimensions = 16,
 56 |     AccessLevel = 17,
 57 |     UserAccessLevel = 18,
 58 |     MinimumSamplingInterval = 19,
 59 |     Historizing = 20,
 60 |     Executable = 21,
 61 |     UserExecutable = 22,
 62 |     DataTypeDefinition = 23,
 63 |     RolePermissions = 24,
 64 |     UserRolePermissions = 25,
 65 |     AccessRestrictions = 26,
 66 |     AccessLevelEx = 27,
 67 |     BrowsePath = 64,
 68 |     Quality = 65,
 69 |     StatusCode = 66,
 70 |     SourceTimestamp = 67,
 71 |     ServerTimestamp = 68,
 72 |     ActualDataType = 69,
 73 |     ActualArrayDimensions = 70
 74 | };
 75 | 
 76 | [ExportMethod]
 77 | public void ReadArbitraryValueFromRemoteOpcUaServer(int nameSpaceIndex, uint identifier)
 78 | {
 79 |     // Get the OPC/UA Client from the project
 80 |     var opc = Project.Current.Get<OPCUAClient>("OPC-UA/OPCUAClient1");
 81 | 
 82 |     // OPC/UA Variable to read from the remote server
 83 |     object[] opcVariable = new object[3]
 84 |     {
 85 |         new NodeId(nameSpaceIndex, identifier), // NodeId of the variable to read (UaExpert can be used to get these values)
 86 |         OpcAttributes.Value, // Attribute ID to read (13 = Value), see enumeration above
 87 |         new uint[0] // Indexes, for simple scalar tags this is an empty array
 88 |     };
 89 | 
 90 |     // Create a Struct object that holds the information of the remote variable to be passed to the OPC/UA Client
 91 |     // Syntax: new Struct(NodeId dataTypeId, object[] values)
 92 |     // Where:
 93 |     // - DataTypeId is the NodeId of the DataType expected as input argument of the method (50 is the ReadValues DataType)
 94 |     // - Values is an array containing the information of the variable to read
 95 |     UAManagedCore.Struct asd = new Struct(new NodeId(FTOptix.OPCUAClient.ObjectTypes.OPCUAClient.NamespaceIndex, 50), opcVariable);
 96 | 
 97 |     // The ExecuteMethod method of the OPC/UA Client is used to call the ReadValues method of the OPC/UA Server
 98 |     // This expects an object[] as input parameters, so we will create a mono-dimensional array with the Struct object
 99 |     object[] inputArgs = new object[1];
100 |     // The first element of the array is the Struct object that we created
101 |     inputArgs[0] = new UAManagedCore.Struct[1];
102 |     // The first element of the Struct array is the variable information to read
103 |     ((UAManagedCore.Struct[])inputArgs[0])[0] = asd;
104 | 
105 |     // The ExecuteMethod method returns an object[] with the output parameters of the method
106 |     object[] outputArgs = new object[1];
107 | 
108 |     // Call the ReadValues method of the OPC/UA Server
109 |     opc.ExecuteMethod("ReadValues", inputArgs, out outputArgs); // OPCUA\OPCUAClient\OPCUAClient\Module.xml.in
110 | 
111 |     // The outputArgs array contains the output parameters of the ReadValues method
112 |     var output = (UAManagedCore.Struct[])outputArgs[0];
113 |     Log.Info(output[0].Values[0].ToString());
114 | }
115 | ```
116 | 
117 | ## Change the Status property of a Tag (changing the DataValue structure)
118 | 
119 | This may be needed in some OPC/UA companion specifications where the Status of a tag is used to detect other status that are not only good or bad
120 | 
121 | ```csharp
122 | [ExportMethod]
123 | public void UpdateStatusCode()
124 | {
125 |     var myVariable = Project.Current.GetVariable("Model/MyFolder/Test");
126 |     // The StatusCode shortcut is read-only
127 |     Log.Info($"Original status code: {myVariable.StatusCode}");
128 |     // new DataValue(UAValue value, uint statusCode, DateTime sourceTimestamp)
129 |     // new DataValue(UAValue value, uint statusCode, DateTime sourceTimestamp, DateTime serverTimestamp)
130 |     myVariable.DataValue = new DataValue(myVariable.Value, 100, DateTime.UtcNow);
131 |     // The StatusCode shortcut is read-only
132 | Log.Info($"New status code: {myVariable.StatusCode}");
133 | }
134 | ```
135 | 
136 | ## Manually create an OPC/UA Client Tag
137 | 
138 | This script presumes that the OPC/UA Client is already configured in the project and at least a tag was imported (needed to get the NameSpaceIndex). It creates a new tag in the project that will be used to read a variable from the OPC/UA Server.
139 | 
140 | ```csharp
141 | [ExportMethod]
142 | public void CreateArbitraryTag()
143 | {
144 |     // Get the NameSpaceIndex of the OPC/UA Client, the best solution would be to read it from an imported tag.
145 |     // This must be in the `.optix` file of the project, so it must be a known index.
146 |     var nxIndex = LogicObject.Context.GetNamespaceIndex("0ccdea9893ed5102b4fae754ef1732f7#http://www.unifiedautomation.com/DemoServer/");
147 |     // Create a new variable in the project with the NodeId of the OPC/UA variable to read in the remote server
148 |     var variable = LogicObject.Context.NodeFactory.MakeVariable(new NodeId(nxIndex, "Demo.Static.Scalar.Double"+), "Double", OpcUa.DataTypes.Double, OpcUa.VariableTypes.BaseDataVariableType);
149 |     // Add the variable to the Objects folder of the OPC/UA client project
150 |     LogicObject.Owner.GetObject("Objects").Add(variable);
151 | }
152 | 


--------------------------------------------------------------------------------
/pages/plc-tags.md:
--------------------------------------------------------------------------------
  1 | # Field tags
  2 | 
  3 | Field tags are functionally identical to Model variables (global variables), but with some additions.
  4 | 
  5 | Field tags can be forced to read or write a value to the field device (a.k.a. PLC) or to force the value to be synched to the controller with a specific refresh time.
  6 | 
  7 | ## Variable synchronizer
  8 | 
  9 | The `VariableSynchronizer` allows users to keep some variables synched even if not in use by any current page, it will keep all the children elements updated with the field. This method handles an automatic optimization of the Tags in order to minimize the number of read/write from the controller (while the `RemoteRead` performs a request per each tag and it is much slower)
 10 | 
 11 | ### Providing a TimeSpan argument
 12 | 
 13 | The `TimeSpan` argument of the `RemoteVariableSynchronizer` should be used to avoid overloading the field device. If the `RemoteVariableSynchronizer` is created without any arguments, it defaults to full-speed synchronization, which can be too fast for the field device to handle. This can lead to performance issues because the iPC (industrial PC) is typically faster than the controller. By specifying a `TimeSpan` argument, you define a refresh interval between subsequent reads, which helps in managing the load on the field device and ensures smoother operation.
 14 | 
 15 | Avoid this constructor: `variableSynchronizer = new RemoteVariableSynchronizer();`
 16 | Use this instead: `variableSynchronizer = new RemoteVariableSynchronizer(new TimeSpan.FromSeconds(5));`
 17 | 
 18 | The argument can be configure as needed, depending on the speed of the synchronization which is required.
 19 | 
 20 | ### Please note
 21 | 
 22 | - The `ChildrenRemoteRead` is just as "slow" as the `RemoteRead`, it is just a recursive approach to a normal `RemoteRead`
 23 | - The `VariableSynchronizer` is made to sync a small number of tags and may have significant impact on the communication driver, make sure to use it wisely
 24 | 
 25 | ```csharp
 26 | public override void Start() 
 27 | {
 28 |     // Get the field variable
 29 |     motorSpeed = LogicObject.Owner.GetVariable("Speed");
 30 |     // Create the VariableSynchronizer object
 31 |     var updateRate = TimeSpan.FromSeconds(5);
 32 |     variableSynchronizer = new RemoteVariableSynchronizer(updateRate);
 33 |     // Add the variables to the synchronizer
 34 |     variableSynchronizer.Add(motorSpeed);
 35 |     // Add the event to listen to value changes
 36 |     motorSpeed.VariableChange += MotorSpeed_VariableChange;
 37 | }
 38 | public override void Stop() 
 39 | {
 40 |     // Destroy the synchronized on stop
 41 |     variableSynchronizer?.Dispose();
 42 | }
 43 | private void MotorSpeed_VariableChange(object sender, VariableChangeEventArgs e) 
 44 | {
 45 |     // Event listener when value change is detected
 46 |     if (motorSpeed.Value > 200) {
 47 |         Log.Warning("Speed limit reached!");
 48 |     }
 49 | }
 50 | private IUAVariable motorSpeed;
 51 | private RemoteVariableSynchronizer variableSynchronizer;
 52 | ```
 53 | 
 54 | ## RemoteRead
 55 | 
 56 | Remote read is a inline read of the field value, code is stopped to read the value, once the variable is updated, the code keeps running
 57 | 
 58 | ### Read simple tags
 59 | 
 60 | ```csharp
 61 | [ExportMethod]
 62 | public void ReadBitFromPlcInteger(out int value)
 63 | {
 64 |     // Get the plc tag to read
 65 |     var tag1 = Project.Current.GetVariable("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Program:CustomUdtProgram/program_dint_1D");
 66 |     // Read the new values
 67 |     var variableValue = tag1.RemoteRead();
 68 |     // Do something with the values
 69 |     Log.Info($"Value of the plc tag is: {variableValue}");
 70 | }
 71 | ```
 72 | 
 73 | ### Read arrays
 74 | 
 75 | ```csharp
 76 | [ExportMethod]
 77 | public void ReadBitFromPlcInteger(out int value)
 78 | {
 79 |     // Get the plc tag to read
 80 |     var tag1 = Project.Current.Get<FTOptix.RAEtherNetIP.Tag>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Program:CustomUdtProgram/program_dint_1D");
 81 |     // Create the remote read object
 82 |     var remoteVariables = new List<RemoteVariable>()
 83 |     {
 84 |         // Add the variables to read to the list
 85 |         new RemoteVariable(tag1),
 86 |     };
 87 |     // Read the new values
 88 |     var values = InformationModel.RemoteRead(remoteVariables).ToList();
 89 |     // Get the field values to a C# variable
 90 |     var plcArray = (int[])values[0].Value.Value;
 91 |     // Do something with the values
 92 |     Log.Info($"Value of first element of the array is {plcArray[0]}");
 93 |     Log.Info($"Bit 5 of first element of the array is {GetBitValue(plcArray[0], 5)}");
 94 | }
 95 | 
 96 | private bool GetBitValue(int inputValue, int bitPosition)
 97 | {
 98 |     // Read a specific bit from a word
 99 |     var array = new BitArray(new int[] { inputValue });
100 |     return array[bitPosition];
101 | }
102 | ```
103 | 
104 | ### Adding a timeout
105 | 
106 | ```csharp
107 | // Get the variable to update
108 | var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
109 | // Try to get the most updated value with a timeout of 100ms
110 | var newValue = currentSpeed.RemoteRead(100.0);
111 | ```
112 | 
113 | ## RemoteWrite
114 | 
115 | Similar to the `RemoteRead`, when a value should be sent immediately to the field, a `RemoteWrite` method can be used
116 | 
117 | ### Write a simple value
118 | 
119 | ```csharp
120 | // Which tag to update
121 | var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
122 | // Write the new value (no write timeout)
123 | currentSpeed.RemoteWrite(42);
124 | ```
125 | 
126 | ### Write multiple values
127 | 
128 | ```csharp
129 | // Which tags to update
130 | var tag1 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR1");
131 | var tag3 = Project.Current.Get<Tag>("CommDrivers/CodesysDriver1/CodesysStation1/Tags/Application/PLC_PRG/VAR3");
132 | // Create the RemoteWrite object
133 | var remoteVariableValues = new List<RemoteVariableValue>()
134 | {
135 |     new RemoteVariableValue(tag3, 0),
136 |     new RemoteVariableValue(tag1, 123)
137 | };
138 | // Perform the write operation (no write timeout)
139 | InformationModel.RemoteWrite(remoteVariableValues);
140 | ```
141 | 
142 | ### Adding a timeout
143 | 
144 | ```csharp
145 | // Get the variable to update
146 | var currentSpeed = Project.Current.GetVariable("Model/Motor/Speed");
147 | // Try to write the value 150 with a timeout of 100ms
148 | currentSpeed.RemoteWrite(150, 100.0);
149 | ```
150 | 


--------------------------------------------------------------------------------
/pages/random-generation.md:
--------------------------------------------------------------------------------
 1 | # Random generation
 2 | 
 3 | When using the random generation, if the loop is particularly fast the system tick may not be different and the same number is generated twice, a small delay may help
 4 | 
 5 | ## Random number generator
 6 | 
 7 | ```csharp
 8 | Random r = new Random();
 9 | 
10 | public void Start() 
11 | {
12 |     // Create a random integer value
13 | 	Int variableRandom = r.Next(min, max);
14 |     // Create a random double value
15 | 	Double variableRandom = r.NextDouble()
16 | }
17 | ```
18 | 
19 | ## Random strings generator
20 | 
21 | ### Using custom character list
22 | 
23 | ```csharp
24 | private static Random random = new Random();
25 | 
26 | public static string RandomString(int stringLength) 
27 | {
28 |     // Set the subset of characters to be used
29 |     const string usableCharacters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
30 |     // Return the random string
31 |     return new string(Enumerable.Repeat(usableCharacters, stringLength)
32 |         .Select(s => s[random.Next(s.Length)]).ToArray());
33 | }
34 | 
35 | public void Start() 
36 | {
37 |     // Call the method to generate the string
38 | 	String randomString = RandomString(10);
39 | }
40 | ```
41 | 
42 | ### Using random GUID
43 | 
44 | Please note, this should **never** be used to generate passwords or tokens as it's not random enough. If high security is required, use the [RandomNumberGenerator](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.randomnumbergenerator?view=net-8.0) instead.
45 | 
46 | ```csharp
47 | private string RandomString()
48 | {
49 |     // Create a new guid
50 |     Guid newGuid = Guid.NewGuid();
51 |     // Remove dashes to keep only alphanumeric characters
52 |     return newGuid.ToString().Replace("-", "");
53 | }
54 | ```
55 | 
56 | ```csharp
57 | private static string GenerateRandomString(int length = 8)
58 | {
59 |     const string alphanumericChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
60 | 
61 |     using var rng = System.Security.Cryptography.RandomNumberGenerator.Create();
62 |     var bytes = new byte[length];
63 |     rng.GetBytes(bytes);
64 | 
65 |     var chars = new char[length];
66 |     for (int i = 0; i < length; i++)
67 |     {
68 |         chars[i] = alphanumericChars[bytes[i] % alphanumericChars.Length];
69 |     }
70 | 
71 |     return new string(chars);
72 | }
73 | ```
74 | 
75 | This one should be better
76 | 
77 | ```csharp
78 | [ExportMethod]
79 | public static void GenerateRandomString(out string randomString)
80 | {
81 |     // Create a random string generator using the RandomNumberGenerator class
82 |     using var rng = RandomNumberGenerator.Create();
83 |     // Create a byte array to store the random values
84 |     var randomBytes = new byte[32];
85 |     // Fill the byte array with random values
86 |     rng.GetBytes(randomBytes);
87 |     // Convert the byte array to a string
88 |     randomString = Convert.ToBase64String(randomBytes).Substring(0, 32);
89 | }
90 | ```
91 | 


--------------------------------------------------------------------------------
/pages/regex.md:
--------------------------------------------------------------------------------
 1 | # Regex
 2 | 
 3 | ## Extract alphanumeric characters from a string
 4 | 
 5 | ```csharp
 6 | Regex regexFileName = new Regex("[^a-zA-Z0-9 -]");
 7 | fileName = regexFileName.Replace(fileName, "");
 8 | ```
 9 | 
10 | ## Extract the table name from a query
11 | 
12 | ```csharp
13 | Regex regexTable = new Regex("(?<=\\bFROM\\s)(\\w+)");
14 | Var tableName = regexTable.Match(Query, 0, Query.Length)
15 | ```


--------------------------------------------------------------------------------
/pages/register-observers.md:
--------------------------------------------------------------------------------
  1 | # OPC/UA Observers
  2 | 
  3 | > [!WARNING]
  4 | > Observers are low-level features and should be used with caution. 
  5 | > This feature is not officially supported and may be subject to changes in future releases.
  6 | 
  7 | The OPC/UA protocol implements some ways to monitor changes in the nodes tree, this allows the creation of observers that can monitor some project nodes and triggers some logics based on a set of events (which can be specified using a mask).
  8 | 
  9 | This technique allows multiple scenarios like:
 10 | 
 11 | - Detecting the nodes status (started, stopped, attached, detached, dispose)
 12 | - Detecting changes in values
 13 | - Detecting changes in attributes
 14 | - Detecting changes in references
 15 | - Detecting OPC/UA events
 16 | 
 17 | Subscribers must be added to all the elements that needs to be monitored, attaching an observer to the `Model` folder, won't enable the listener on all children nodes
 18 | 
 19 | ## References to OPC/UA Specifications
 20 | 
 21 | - **OPC UA Part 4 - Services**: Describes the services provided by the OPC UA server, including event subscriptions.
 22 | - **OPC UA Part 9 - Alarms & Conditions**: Provides details on how events and conditions are managed in OPC UA.
 23 | 
 24 | For more detailed information, refer to the [OPC UA Specifications](https://opcfoundation.org/developer-tools/specifications-unified-architecture).
 25 | 
 26 | ## Intercepting FactoryTalk Optix Runtime messages
 27 | 
 28 | The messages that are printed to the "Runtime Output" (or "Emulator Output") are generated as per OPC/UA specs by the Server object, which can be subscribed to trigger custom logics
 29 | 
 30 | ```csharp
 31 | #region Using directives
 32 | using System;
 33 | using UAManagedCore;
 34 | using OpcUa = UAManagedCore.OpcUa;
 35 | using FTOptix.NetLogic;
 36 | using System.Collections.Generic;
 37 | using LogsHandler;
 38 | #endregion
 39 | 
 40 | public class RuntimeLoggerMonitor : BaseNetLogic
 41 | {
 42 |     public override void Start()
 43 |     {
 44 |         // Build the observer for the output messages
 45 |         StartObserver();
 46 |     }
 47 | 
 48 |     public override void Stop()
 49 |     {
 50 |         // Destroy the observer when closing the NetLogic
 51 |         logsRegistration?.Dispose();
 52 |     }
 53 | 
 54 |     public void StartObserver()
 55 |     {
 56 |         // Get the server object
 57 |         var serverObject = LogicObject.Context.GetObject(OpcUa.Objects.Server);
 58 |         // Create a new observer
 59 |         var logsObserver = new LogsHandler.LogsEventObserver();
 60 |         // Register the observer to the server node
 61 |         logsRegistration = serverObject.RegisterUAEventObserver(logsObserver, FTOptix.Core.ObjectTypes.LogEvent);
 62 |     }
 63 | 
 64 |     // This node must stay "alive" as long as the subscriber is needed
 65 |     // Do not move it to a local variable or the observer won't work
 66 |     private IEventRegistration logsRegistration;
 67 | }
 68 | 
 69 | namespace LogsHandler
 70 | {
 71 |     class LogsEventObserver : IUAEventObserver
 72 |     {
 73 |         public LogsEventObserver()
 74 |         {
 75 |             Log.Info("LogsEventObserver", "Starting observer");
 76 |         }
 77 | 
 78 |         public void OnEvent(IUAObject eventNotifier, IUAObjectType eventType, IReadOnlyList<object> args, ulong senderId)
 79 |         {
 80 |             Console.WriteLine(((LocalizedText) args[7]).Text); // Content of the message
 81 |             Console.WriteLine(args[15]); // Module name
 82 |             Console.WriteLine(args[13]); // Message level
 83 |             // Do not use `Log.` events here or it will loop!
 84 |         }
 85 |     }
 86 | }
 87 | 
 88 | ```
 89 | 
 90 | ## Subscribe to methods execution
 91 | 
 92 | This script can be put anywhere on the project and will listen to every OPCUA method being called (script or UI)
 93 | 
 94 | ```csharp
 95 | public class RuntimeNetLogic1 : BaseNetLogic
 96 | {
 97 |     public override void Start()
 98 |     {
 99 |         var serverObject = LogicObject.Context.GetObject(OpcUa.Objects.Server);
100 |         var eventHandler = new EventsHandler.EventsHandler();
101 |         eventRegistration = serverObject.RegisterUAEventObserver(eventHandler, UAManagedCore.OpcUa.ObjectTypes.AuditUpdateMethodEventType);
102 |     }
103 | 
104 |     public override void Stop()
105 |     {
106 |         // Insert code to be executed when the user-defined logic is stopped
107 |         eventRegistration?.Dispose();
108 |     }
109 | 
110 |     private IEventRegistration eventRegistration;
111 | }
112 | 
113 | namespace EventsHandler
114 | {
115 |     public class EventsHandler : IUAEventObserver
116 |     {
117 |         public EventsHandler()
118 |         {
119 |             Log.Info("EventsHandler", "EventsHandler instance created");
120 |         }
121 | 
122 |         public void OnEvent(IUAObject eventNotifier, IUAObjectType eventType, IReadOnlyList<object> eventData, ulong senderId)
123 |         {
124 |             StringBuilder builder = new StringBuilder();
125 |             builder.Append($"Event of type {eventType.BrowseName} triggered");
126 |             var eventArguments = eventType.EventArguments;
127 |             foreach (var eventField in eventArguments.GetFields())
128 |             {
129 |                 var fieldValue = eventArguments.GetFieldValue(eventData, eventField);
130 |                 builder.Append($"\t{eventField} = {fieldValue?.ToString() ?? "null"}");
131 |             }
132 |             builder.Append("\n");
133 |             Log.Info(builder.ToString());
134 |         }
135 |     }
136 | }
137 | ```
138 | 
139 | ## Track the login and logout of users and get the list of groups for the current user
140 | 
141 | This example leverages the observers to track the login and logout of users, as well as to get the list of groups for the current user.
142 | 
143 | ```csharp
144 | public class RuntimeNetLogic1 : BaseNetLogic
145 | {
146 |     public override void Start()
147 |     {
148 |         var serverObject = LogicObject.Context.GetObject(OpcUa.Objects.Server);
149 |         var eventHandler = new EventsHandler.EventsHandler();
150 |         eventRegistration = serverObject.RegisterUAEventObserver(eventHandler, FTOptix.Core.ObjectTypes.UserSessionEvent);
151 |     }
152 | 
153 |     public override void Stop()
154 |     {
155 |         // Insert code to be executed when the user-defined logic is stopped
156 |         eventRegistration?.Dispose();
157 |     }
158 | 
159 |     private IEventRegistration eventRegistration;
160 | }
161 | 
162 | namespace EventsHandler
163 | {
164 |     public class EventsHandler : IUAEventObserver
165 |     {
166 |         public EventsHandler()
167 |         {
168 |             Log.Info("EventsHandler", "EventsHandler instance created");
169 |         }
170 | 
171 |         public void OnEvent(IUAObject eventNotifier, IUAObjectType eventType, IReadOnlyList<object> eventData, ulong senderId)
172 |         {
173 |             // Log the event to the console
174 |             StringBuilder builder = new StringBuilder();
175 |             builder.Append($"Event of type {eventType.BrowseName} triggered");
176 |             var eventArguments = eventType.EventArguments;
177 |             foreach (var eventField in eventArguments.GetFields())
178 |             {
179 |                 var fieldValue = eventArguments.GetFieldValue(eventData, eventField);
180 |                 builder.Append($"\t{eventField} = {fieldValue?.ToString() ?? "null"}");
181 |             }
182 |             Log.Debug(builder.ToString());
183 | 
184 |             // Optional: only operate on Login event
185 |             if ((string)eventArguments.GetFieldValue(eventData, "SourceName") == "Login")
186 |             {
187 |                 // Get the groups linked to the current user
188 |                 var userNodeId = (NodeId)eventArguments.GetFieldValue(eventData, "UserId");
189 |                 // Get the user object from the node ID
190 |                 var newUser = InformationModel.Get<User>(userNodeId);
191 |                 // Get all groups the user is part of
192 |                 var userGroups = newUser.Refs.GetObjects(FTOptix.Core.ReferenceTypes.HasGroup, false);
193 |                 // Create a string with the groups and log it
194 |                 builder = new StringBuilder();
195 |                 builder.Append($"User {newUser.BrowseName} is part of the following groups: ");
196 |                 foreach (var group in userGroups)
197 |                 {
198 |                     builder.Append($"{group.BrowseName}, ");
199 |                 }
200 |                 // Remove the last comma and space
201 |                 if (userGroups.Count > 0)
202 |                 {
203 |                     builder.Length -= 2; // Remove the last comma and space
204 |                 }
205 |                 else
206 |                 {
207 |                     builder.Append("No groups found");
208 |                 }
209 |                 Log.Info(builder.ToString());
210 |             }
211 |         }
212 |     }
213 | }
214 | ```


--------------------------------------------------------------------------------
/pages/reports.md:
--------------------------------------------------------------------------------
  1 | # Reports
  2 | 
  3 | ## Generate a report and trigger some action based on the result code
  4 | 
  5 | ```csharp
  6 | #region Using directives
  7 | using System;
  8 | using System.IO;
  9 | using System.Linq;
 10 | using System.Reflection.Emit;
 11 | using FTOptix.Core;
 12 | using FTOptix.HMIProject;
 13 | using FTOptix.NetLogic;
 14 | using FTOptix.Report;
 15 | using FTOptix.UI;
 16 | using UAManagedCore;
 17 | #endregion
 18 | 
 19 | public partial class PdfReportLogic : BaseNetLogic
 20 | {
 21 |     public override void Start()
 22 |     {
 23 |         // Try to assign a value to the button
 24 |         try
 25 |         {
 26 |             generatePdfButton = Owner.Get<Button>("TrackedValues/Generate");
 27 |             viewPdfButton = Owner.Get<Button>("TrackedValues/View");
 28 |             viewPdfButton.Enabled = false;
 29 |         }
 30 |         catch
 31 |         {
 32 |             // Button does not exist
 33 |             Log.Warning("PdfReportLogic", "Can't find PDF buttons, maybe they were renamed?");
 34 |         }
 35 |     }
 36 | 
 37 |     public override void Stop()
 38 |     {
 39 |         myReport.OnGeneratePdfCompleted -= MyReport_OnGeneratePdfCompleted;
 40 |     }
 41 | 
 42 |     [ExportMethod]
 43 |     public void GenerateReport(string fileName, string pdfLocale)
 44 |     {
 45 |         // Hide button
 46 |         generatePdfButton.Enabled = false;
 47 | 
 48 |         // Check if the path is empty
 49 |         if (string.IsNullOrEmpty(fileName))
 50 |         {
 51 |             Log.Error("PdfReportLogic", "Empty PDF name");
 52 |             SetOutputMessage("ReportEmptyPath");
 53 |             throw new ArgumentNullException();
 54 |         }
 55 | 
 56 |         // Check if the pdf has the extension
 57 |         if (!fileName.EndsWith(".pdf", StringComparison.InvariantCultureIgnoreCase))
 58 |         {
 59 |             Log.Warning("PdfReportLogic", "PDF extension not found, adding it");
 60 |             fileName += ".pdf";
 61 |         }
 62 | 
 63 |         // Make sure to use only the file name
 64 |         fileName = fileName.Split('\\', '/').Last();
 65 | 
 66 |         // Check if the path is an Optix path variable
 67 |         var pdfResourceUri = ResourceUri.FromProjectRelativePath(fileName);
 68 | 
 69 |         // Check if the locale is valid
 70 |         if (string.IsNullOrEmpty(pdfLocale))
 71 |         {
 72 |             Log.Error("PdfReportLogic", "Empty locale");
 73 |             SetOutputMessage("ReportEmptyLocale");
 74 |             throw new ArgumentNullException();
 75 |         }
 76 | 
 77 |         // Check if the locale is valid using regex
 78 |         if (!LocaleIdRegex().IsMatch(pdfLocale))
 79 |         {
 80 |             Log.Error("PdfReportLogic", "Invalid locale");
 81 |             SetOutputMessage("ReportInvalidLocale");
 82 |             throw new ArgumentException();
 83 |         }
 84 | 
 85 |         // Generate the report
 86 |         myReport = Project.Current.Get<Report>("Reports/LoggerReport");
 87 |         Log.Debug("PdfReportLogic", $"Generating PDF report with locale: {pdfLocale}");
 88 |         Log.Debug("PdfReportLogic", $"Saving PDF report to: {pdfResourceUri.Uri}");
 89 |         myReport.GeneratePdf(pdfResourceUri, pdfLocale, out Guid operationId);
 90 | 
 91 |         // Subscribe to the report generation event
 92 |         myReport.OnGeneratePdfCompleted += MyReport_OnGeneratePdfCompleted;
 93 | 
 94 |         Log.Debug("PdfReportLogic", $"Report generation started with operation ID: {operationId}");
 95 |     }
 96 | 
 97 |     private void MyReport_OnGeneratePdfCompleted(object sender, GeneratePdfCompletedEvent e)
 98 |     {
 99 |         Log.Info("PdfReportLogic", $"Report generation completed with result: {e.Result}");
100 |         if (e.Result == GeneratePdfCompletedResult.PdfSuccessfullyGenerated)
101 |         {
102 |             SetOutputMessage("ReportSuccess");
103 |             viewPdfButton.Enabled = true;
104 |         }
105 |         else
106 |         {
107 |             SetOutputMessage("ReportFailed");
108 |             viewPdfButton.Enabled = false;
109 |             Log.Error("PdfReportLogic", $"PDF generation failed, error: {e.Result}");
110 |         }
111 | 
112 |         generatePdfButton.Enabled = true;
113 |     }
114 | 
115 |     // Set output message
116 |     private void SetOutputMessage(string translationKey)
117 |     {
118 |         var outputLabel = Owner.Get<FTOptix.UI.Label>("TrackedValues/OutputMessage");
119 |         try
120 |         {
121 |             outputLabel.LocalizedText = new LocalizedText(outputLabel.NodeId.NamespaceIndex, translationKey);
122 |         }
123 |         catch
124 |         {
125 |             Log.Warning("PdfReportLogic", $"Translation key not found: {translationKey}");
126 |             outputLabel.Text = translationKey;
127 |         }
128 |     }
129 | 
130 |     // Regex for locale ID
131 |     [System.Text.RegularExpressions.GeneratedRegex("^[a-z]{2}-[A-Z]{2}$")]
132 |     private static partial System.Text.RegularExpressions.Regex LocaleIdRegex();
133 |     // PDF generator button
134 |     private FTOptix.UI.Button generatePdfButton;
135 |     private FTOptix.UI.Button viewPdfButton;
136 |     private FTOptix.Report.Report myReport;
137 | }
138 | ```
139 | 


--------------------------------------------------------------------------------
/pages/resource-uri.md:
--------------------------------------------------------------------------------
 1 | # Resource URIs
 2 | 
 3 | ## Important note
 4 | 
 5 | Although multiple solutions are shown here to set the target path for a ResourceUri variable, please remember that the WebPresentationEngine only supports accessing elements that are in the `%PROJECTDIR%` and a relative path is used (example: `%PROJECTDIR%/imgs/logo.svg`), using an absolute path for an element (example: `C:/OptixProjects/NewHMIProject1/Project Files/imgs/logo.svg`), will never work in the WebPresentationEngine for safety reasons.
 6 | 
 7 | ## Create a ResourceUri from scratch
 8 | 
 9 | ```csharp
10 | // Get the working folder from the current context
11 | var baseUri = new Uri(System.IO.Directory.GetCurrentDirectory());
12 | // Get the ProjectDir folder
13 | var chartUri = new Uri(baseUri, Project.Current.ProjectDirectory);
14 | // Browse to the NetSolution folder
15 | var nextStep = new Uri(chartUri, "NetSolution");
16 | // Browse to NetSolution/Charts.xlst
17 | var finalPath = new Uri(nextStep, "Charts.xslt");
18 | // Get the full path
19 | string filePath = finalPath.AbsolutePath;
20 | Log.Info("Final path: " + filePath);
21 | Log.Info(MethodBase.GetCurrentMethod().Name, $"File name is: {fileName}");
22 | ```
23 | 
24 | ## Reading a ResourceUri
25 | 
26 | This assumes the variable is set to ResourceUri
27 | 
28 | ```csharp
29 | // Get a variable with datatype set to ResourceUri
30 | var csvPathVariable = LogicObject.Get<IUAVariable>("CSVPath");
31 | // Get the full path
32 | string myString = new ResourceUri(csvPathVariable.Value).Uri;
33 | ```
34 | 
35 | ```csharp
36 | pdfPathStr = new ResourceUri(((IUAVariable)myPathNode).Value).Uri;
37 | ```
38 | 
39 | ## Set the path of an Image to the ProjectFiles
40 | 
41 | ```csharp
42 | // Note: the Path.DirectorySeparatorChar is used to make the application cross-platform capable
43 | singlePiece.Get<Image>("PuzzleImage").Path = ResourceUri.FromProjectRelativePath("").Uri + Path.DirectorySeparatorChar + "imgs" + Path.DirectorySeparatorChar + "Puzzle" + Path.DirectorySeparatorChar + "Piece" + (i + 1).ToString() + ".png";
44 | ```
45 | 
46 | ## Get a file from ProjectFiles
47 | 
48 | ```csharp
49 | string localPath = Path.DirectorySeparatorChar + "imgs" + Path.DirectorySeparatorChar + "Puzzle" + Path.DirectorySeparatorChar + "Piece" + (i + 1).ToString() + ".png";
50 | singlePiece.Get<Image>("PuzzleImage").Path = "ns=" + singlePiece.NodeId.NamespaceIndex.ToString() + ";%PROJECTDIR%" + localPath;
51 | ```
52 | 
53 | ```csharp
54 | string localPath = "imgs" + Path.DirectorySeparatorChar + "Puzzle" + Path.DirectorySeparatorChar + "Piece" + (i + 1).ToString() + ".png";
55 | singlePiece.Get<Image>("PuzzleImage").Path = Path.Combine(ResourceUri.FromProjectRelativePath(""), localPath);
56 | ```
57 | 
58 | ```csharp
59 | // Start from the ProjectDir and get the Template-line-smooth.html file
60 | var templatePath = ResourceUri.FromProjectRelativePath("Template-line-smooth.html");
61 | // Remove the Template- prefix
62 | templatePath = ResourceUri.FromProjectRelativePath(templatePath.Uri.Replace("Template-", ""));
63 | // Write the new content to the file
64 | File.WriteAllText(templatePath.Uri, text);
65 | ```
66 | 


--------------------------------------------------------------------------------
/pages/runtime-tags-import.md:
--------------------------------------------------------------------------------
  1 | # Runtime import of PLC tags
  2 | 
  3 | Importing of PLC tags while the application is running is currently only supported for:
  4 | 
  5 | > [!NOTE]
  6 | > Runtime import of extended tag attributes from the RA Ethernet/IP driver is not supported yet.
  7 | 
  8 | - TwinCAT
  9 | - RA Ethernet/IP
 10 | - Siemens S7 Profinet
 11 | 
 12 | ### Warning
 13 | 
 14 | when importing tags at runtime, especially if filtering is used, a flat list is returned, this means that of you have a structure like:
 15 | 
 16 | - PLC
 17 |     - Motor1 (UDT)
 18 |         - Speed (Int32)
 19 |         - Torque (Int32)
 20 |     - Motor2 (UDT)
 21 |         - Speed (Int32)
 22 |         - Torque (Int32)
 23 | 
 24 | And you use the filtering mechanism to extract the `Speed` property of both structures, you will get:
 25 | 
 26 | - PLC
 27 |     - Speed (Int32)
 28 |     - Speed (Int32)
 29 | 
 30 | So, the whole structure should be imported or unique names shall be used
 31 | 
 32 | ### Code example
 33 | 
 34 | Browse and import PLC tags
 35 | 
 36 | ```csharp
 37 | [ExportMethod]
 38 | public void Import()
 39 | {
 40 |     var station = Project.Current.Get<Station>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1");
 41 | 
 42 |     Struct[] instances;
 43 |     Struct[] types;
 44 |     station.Browse(out instances, out types);
 45 |     station.Import(instances, types);
 46 | 
 47 |     var tag = Project.Current.Get<Tag>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1/Tags/Program:CustomUdtProgram/Increment_INT");
 48 |     Log.Info($"Read value of {tag.BrowseName}");
 49 |     Log.Info($"{tag.RemoteRead()}");
 50 | }
 51 | ```
 52 | 
 53 | The following code contains a method for each of the driver where runtime import is supported
 54 | 
 55 | ```csharp
 56 | #region StandardUsing
 57 | using System;
 58 | using System.Collections.Generic;
 59 | using System.Linq;
 60 | using System.Reflection;
 61 | using FTOptix.CommunicationDriver;
 62 | using FTOptix.HMIProject;
 63 | using UAManagedCore;
 64 | #endregion
 65 | 
 66 | public class RuntimeTagsImport : FTOptix.NetLogic.BaseNetLogic
 67 | {
 68 |     /// <summary>
 69 |     /// Import tags from TwinCAT driver
 70 |     /// </summary>
 71 |     [FTOptix.NetLogic.ExportMethod]
 72 |     public static void ImportFromTwincat()
 73 |     {
 74 |         Log.Info(MethodBase.GetCurrentMethod().Name, "Starting runtime tags import");
 75 | 
 76 |         var station = Project.Current.Get<FTOptix.TwinCAT.Station>("CommDrivers/TwinCATDriver1/TwinCATStation1");
 77 | 
 78 |         // Call Browse method to retrieve data from PLC
 79 |         // prototypes parameter for TwinCat is always empty
 80 |         station.Browse(out var plcItems, out var prototypes);
 81 | 
 82 |         Log.Info("RuntimeTagsImport.ImportFromTwincat", "Fetched " + plcItems.Length + " tags");
 83 | 
 84 |         // Filter tag to import by tag name
 85 |         var tagInstances = FilterTagsToImport(new List<string>() { "SampleTag.A", "SomeOtherTag.B" }, plcItems); //TODO
 86 | 
 87 |         // Delete existing tags
 88 |         Log.Info("RuntimeTagsImport.ImportFromTwincat", "Clearing existing tags");
 89 |         station.Tags.Clear();
 90 | 
 91 |         Log.Info("RuntimeTagsImport.ImportFromTwincat", "Importing " + tagInstances.Length + " tags");
 92 | 
 93 |         // Filter tag to import by prototypeId
 94 |         // var tagInstances = GetTagsOfType("MachineParameter", plcItems);
 95 | 
 96 |         station.Import(tagInstances, prototypes);
 97 | 
 98 |         // Remote read on imported tag
 99 |         ReadTag("SampleTag.A", station);
100 | 
101 |         // Remote write on imported structure
102 |         // WriteStructure("SomeOtherTag.B", station);
103 | 
104 |         // Remote read on imported structure
105 |         // ReadStructure("SomeOtherTag.B", station);
106 |     }
107 | 
108 |     /// <summary>
109 |     /// Import tags from Profinet driver
110 |     /// </summary>
111 |     [FTOptix.NetLogic.ExportMethod]
112 |     public static void ImportFromProfinet()
113 |     {
114 |         Log.Info(MethodBase.GetCurrentMethod().Name, "Starting runtime tags import");
115 | 
116 |         var station = Project.Current.Get<FTOptix.S7TiaProfinet.Station>("CommDrivers/S7TIAPROFINETDriver1/S7TIAPROFINETStation1");
117 | 
118 |         // Call Browse method to retrieve data from PLC
119 |         // prototypes parameter for S7TiaProfinet is always empty
120 |         station.Browse(out var plcItems, out var prototypes);
121 | 
122 |         Log.Info("RuntimeTagsImport.ImportFromProfinet", "Fetched " + plcItems.Length + " PLC structures");
123 | 
124 |         // Profinet tag are grouped by project, so we need to retrieve tags from root
125 |         var root = plcItems.OfType<BasePlcItem>().ToList();
126 |         // Root node is always the first element in the list
127 |         // This is called "PLC" when browsing from the TagImporter
128 |         var tags = root[0].Items;
129 |         Log.Info("RuntimeTagsImport.ImportFromProfinet", "Fetched " + tags.Length + " tags");
130 |         // Filter tag to import by tag name
131 |         var tagInstances = FilterTagsToImport(new List<string>() { "PLC/TestFix", "PLC/TestDT" }, tags);
132 | 
133 |         // Delete existing tags
134 |         Log.Info("RuntimeTagsImport.ImportFromProfinet", "Clearing existing tags");
135 |         station.Tags.Clear();
136 | 
137 |         Log.Info("RuntimeTagsImport.ImportFromProfinet", "Importing " + tagInstances.Length + " tags");
138 | 
139 |         //Filter tag to import by prototypeId
140 |         //var tagInstances = GetTagsOfType("MachineParameter", tags);
141 | 
142 |         station.Import(tagInstances, prototypes);
143 |         Log.Info("Imported " + tagInstances.Length + " tags");
144 | 
145 |         // Remote read on imported tag
146 |         ReadTag("SampleTag.A", station);
147 | 
148 |         // Remote write on imported structure
149 |         // WriteStructure("SomeOtherTag.B", station);
150 | 
151 |         // Remote read on imported structure
152 |         // ReadStructure("SomeOtherTag.B", station);
153 |     }
154 | 
155 |     /// <summary>
156 |     /// Import tags from RA Ethernet/IP driver
157 |     /// </summary>
158 |     [FTOptix.NetLogic.ExportMethod]
159 |     public static void ImportFromRAEthernetIP()
160 |     {
161 |         Log.Info("RuntimeTagsImport.ImportFromRAEthernetIP", "Starting runtime tags import");
162 | 
163 |         var station = Project.Current.Get<FTOptix.RAEtherNetIP.Station>("CommDrivers/RAEtherNet_IPDriver1/RAEtherNet_IPStation1");
164 | 
165 |         // Call Browse method to retrieve data from PLC
166 |         station.Browse(out var plcItems, out var prototypes);
167 | 
168 |         Log.Info("RuntimeTagsImport.ImportFromRAEthernetIP", "Fetched " + plcItems.Length + " tags structures from the PLC");
169 | 
170 |         // Filter tag to import by tag name
171 |         var tagInstances = FilterTagsToImport(new List<string>() { "Controller Tags/Tank1/Level", "Controller Tags/Tank2/Level" }, plcItems);
172 | 
173 |         // Delete existing tags
174 |         Log.Info("RuntimeTagsImport.ImportFromRAEthernetIP", "Clearing existing tags");
175 |         station.Tags.Clear();
176 | 
177 |         Log.Info("RuntimeTagsImport.ImportFromRAEthernetIP", "Importing " + tagInstances.Length + " tags");
178 | 
179 |         if (tagInstances.Length == 0)
180 |         {
181 |             Log.Warning("RuntimeTagsImport.ImportFromRAEthernetIP", "No tags to import. Returning.");
182 |             return;
183 |         }
184 | 
185 |         //Filter tag to import by prototypeId
186 |         // var tagInstances = GetTagsOfType("MachineParameter", plcItems);
187 | 
188 |         station.Import(tagInstances, prototypes);
189 | 
190 |         // Remote read on imported tag
191 |         ReadTag("Controller Tags/Tank1/Level", station);
192 | 
193 |         // Remote write on imported structure
194 |         // WriteStructure("Controller Tags/Tank1/Level", station);
195 | 
196 |         // Remote read on imported structure
197 |         // ReadStructure("Controller Tags/Tank1", station);
198 |     }
199 | 
200 |     /// <summary>
201 |     /// Filter tags to import by tag name.
202 |     /// Expects a list of tag paths to import (like "Controller Tags/Motor1/Speed" and
203 |     /// the list of all tags that were fetch from the PLC.
204 |     /// If the list of tags to import is empty, all fetched tags will be returned.
205 |     /// Warning: a flat list is returned, so the tag paths must be unique.
206 |     /// </summary>
207 |     /// <param name="tagPathsToImport">List of tag paths to import (path with forward slashes "/")</param>
208 |     /// <param name="plcItems">List of all tags fetched from the PLC</param>
209 |     /// <returns>List of tags (Struct[]) that matches the input list</returns>
210 |     private static Struct[] FilterTagsToImport(List<string> tagPathsToImport, Struct[] plcItems)
211 |     {
212 |         var listOfFoundTags = new List<Struct>();
213 | 
214 |         // If no list of tags to import was provided, return all tags
215 |         if (tagPathsToImport.Count == 0)
216 |         {
217 |             Log.Warning("RuntimeTagsImport.FilterTagsToImport", "No list of tags to import was provided. Returning all tags.");
218 |             return plcItems;
219 |         }
220 | 
221 |         if (plcItems.Length == 0)
222 |         {
223 |             Log.Warning("RuntimeTagsImport.FilterTagsToImport", "No tags were fetched from the PLC. Returning empty list.");
224 |             return plcItems;
225 |         }
226 | 
227 |         // Filter tags to import by tag name
228 |         foreach (string tagPath in tagPathsToImport)
229 |         {
230 |             string[] splitPath = tagPath.Split('/');
231 |             var node = plcItems;
232 |             for (int i = 0; i < splitPath.Length; i++)
233 |             {
234 |                 for (int k = 0; k < node.Length; k++)
235 |                 {
236 |                     if (((BasePlcItem)node[k]).Name == splitPath[i])
237 |                     {
238 |                         if (i == splitPath.Length - 1)
239 |                         {
240 |                             listOfFoundTags.Add(node[k]);
241 |                             break;
242 |                         }
243 |                         else
244 |                         {
245 |                             node = ((BasePlcItem)node[k]).Items;
246 |                             break;
247 |                         }
248 |                     }
249 |                 }
250 |             }
251 |         }
252 | 
253 |         return listOfFoundTags.ToArray();
254 |     }
255 | 
256 |     /// <summary>
257 |     /// Performs a remote read on a tag.
258 |     /// </summary>
259 |     /// <param name="tagName"></param>
260 |     /// <param name="station"></param>
261 |     private static void ReadTag(string tagName, FTOptix.CommunicationDriver.CommunicationStation station)
262 |     {
263 |         try
264 |         {
265 |             var tag = station.Get<FTOptix.CommunicationDriver.Tag>("Tags/" + tagName);
266 |             var result = tag.RemoteRead();
267 |             Log.Info($"RemoteRead succeed -> {tagName}: {result.Value}");
268 |         }
269 |         catch (Exception e)
270 |         {
271 |             Log.Error("RemoteRead failed: " + e.Message);
272 |         }
273 |     }
274 | }
275 | 
276 | 
277 | ```


--------------------------------------------------------------------------------
/pages/sessions.md:
--------------------------------------------------------------------------------
 1 | # Sessions
 2 | 
 3 | ## Getting the number of the WebPresentationEngine sessions
 4 | 
 5 | ```csharp
 6 |  /// <summary>
 7 |  /// Retrieves the number of active Web sessions
 8 |  /// </summary>
 9 |  /// <param name="webPresentationEngineNodeId">NodeId of the WebPresentationEngine node</param>
10 |  /// <param name="activeWebSessionNumber">Counting active web sessions</param>
11 |  [ExportMethod]
12 |  public void GetActiveWebSessionsNumber(NodeId webPresentationEngineNodeId, out int activeWebSessionNumber)
13 |  {
14 |      try
15 |      {
16 |          // Get the current WebPresentationEngine from the project
17 |          PresentationEngine webPresentationEngine = InformationModel.Get<PresentationEngine>(webPresentationEngineNodeId);
18 |          // Call the method to read the active sessions
19 |          activeWebSessionNumber = GetWebPresentationEngineSessions(webPresentationEngine).Count();
20 |      }
21 |      catch (Exception ex)
22 |      {
23 |          Log.Error(ex.Message);
24 |          activeWebSessionNumber = -1;
25 |      }
26 |  }
27 | 
28 |  // Use reflections to get the sessions (check where user is present (like Anonymous))
29 |  private static IEnumerable<UISession> GetWebPresentationEngineSessions(PresentationEngine webPresentationEngine) => webPresentationEngine.Sessions.Where(s => s.User != null);
30 | ```
31 | 


--------------------------------------------------------------------------------
/pages/system-node.md:
--------------------------------------------------------------------------------
 1 | # The system object
 2 | 
 3 | The "System" object is a special node which provides some methods and events to interact with Optix devices (like OptixPanel, OptixEdge, etc)
 4 | 
 5 | ## Load a new application
 6 | 
 7 | Please note:
 8 | - Application must be exported by FactoryTalk Optix Studio with the same version that was previously used to deploy the original application
 9 | - Exported application must be protected by a password
10 | - The import procedure might take some time, please wait for the confirmation message
11 | 
12 | ```csharp
13 | #region Using directives
14 | using System;
15 | using UAManagedCore;
16 | using OpcUa = UAManagedCore.OpcUa;
17 | using FTOptix.UI;
18 | using FTOptix.NativeUI;
19 | using FTOptix.HMIProject;
20 | using FTOptix.Retentivity;
21 | using FTOptix.CoreBase;
22 | using FTOptix.Core;
23 | using FTOptix.NetLogic;
24 | using FTOptix.System;
25 | using System.IO;
26 | using System.Runtime.Versioning;
27 | #endregion
28 | 
29 | public class RuntimeNetLogic1 : BaseNetLogic
30 | {
31 |     public override void Start()
32 |     {
33 |         // Insert code to be executed when the user-defined logic is started
34 |     }
35 | 
36 |     public override void Stop()
37 |     {
38 |         // Insert code to be executed when the user-defined logic is stopped
39 |         systemNode.OnLoadApplicationStatusEvent -= SystemNode_OnLoadApplicationStatusEvent;
40 |     }
41 | 
42 |     [ExportMethod]
43 |     public void LoadNewApplication(string password, bool deleteApplicationFiles)
44 |     {
45 |         // Get to the system node
46 |         systemNode = Project.Current.Get<FTOptix.System.System>("System/System");
47 |         // Get the new application path
48 |         var newApplicationPath = ResourceUri.FromProjectRelativePath("NewApplication.z");
49 | 
50 |         // Subscribe to the application load event
51 |         systemNode.OnLoadApplicationStatusEvent += SystemNode_OnLoadApplicationStatusEvent;
52 | 
53 |         // Load the new application
54 |         if (systemNode.LoadApplication(newApplicationPath.Uri, password, deleteApplicationFiles))
55 |         {
56 |             // Call to the SystemManager API to load the new application was successful
57 |             Log.Info("LoadApplication", "Load application call was successful, please wait for the process to complete");
58 |         }
59 |         else
60 |         {
61 |             // Call to the SystemManager API to load the new application failed
62 |             Log.Error("LoadApplication", "Failed to load application, call to the SystemManager APIs failed");
63 |         }
64 |     }
65 | 
66 |     private void SystemNode_OnLoadApplicationStatusEvent(object sender, LoadApplicationStatusEvent e)
67 |     {
68 |         if (e.Status == LoadApplicationStatus.Success)
69 |         {
70 |             // Application loaded successfully
71 |             Log.Info("LoadApplicationStatus", "Application loaded successfully");
72 |         }
73 |         else
74 |         {
75 |             // Application failed to load
76 |             Log.Error("LoadApplicationStatus", "Failed to load application: " + e.Status);
77 |         }
78 |     }
79 | 
80 |     FTOptix.System.System systemNode;
81 | }
82 | ```


--------------------------------------------------------------------------------
/pages/template-library.md:
--------------------------------------------------------------------------------
  1 | # Template Library
  2 | 
  3 | ## Import an object from the template library
  4 | 
  5 | This feature allows you to import objects from the template library into your project. The imported object will be placed in the specified folder. The object can be an instance or a type.
  6 | 
  7 | > [!TIP]
  8 | > This feature got introduced in FactoryTalk Optix 1.6.X
  9 | 
 10 | ### Import item syntax
 11 | 
 12 | ```csharp
 13 | public static class TemplateLibrary
 14 | {
 15 |     public static IUANode ImportLibraryItem(IUANode destinationNode, NodeClass nodeClass, string libraryName,
 16 |         string itemPath, List<TypeConflictResolutionChoice> conflictResolutionChoices = null,
 17 |         bool preserveTypeDependencyPaths = false);
 18 | }
 19 | ```
 20 | 
 21 | ### Import the LoginForm from the Widgets library example
 22 | 
 23 | ```csharp
 24 | [ExportMethod]
 25 | public void ImportLoginFormFromLibrary()
 26 | {
 27 |     // The place where the object will be imported
 28 |     var targetFolder = Project.Current.Get("UI");
 29 |     // Import the object
 30 |     // Syntax: ImportLibraryItem(<item destination>, <node class (type or instance)>, <name of the library>, <name of the library item>)
 31 |     var myWidget = TemplateLibrary.ImportLibraryItem(targetFolder, NodeClass.ObjectType, "Widgets", "LoginForm");
 32 |     // Log the result
 33 |     Log.Info($"Imported LoginForm from library to: {Log.Node(myWidget)}");
 34 | }
 35 | ```
 36 | 
 37 | ## Specifying a conflict resolution
 38 | 
 39 | If the imported element already exists in the target folder, you can specify a conflict resolution strategy.
 40 | 
 41 | ### Conflict resolution syntax
 42 | 
 43 | A list of `TypeConflictResolutionChoice` structures is used to specify the conflict resolution strategy. The structure contains the following fields:
 44 | 
 45 | ```csharp
 46 | public struct TypeConflictResolutionChoice
 47 | {
 48 |     public TypeConflictResolutionChoice(string browseName, NodeClass nodeClass, ConflictResolution resolution)
 49 |     {
 50 |         BrowseName = browseName;
 51 |         NodeClass = nodeClass;
 52 |         Resolution = resolution;
 53 |     }
 54 | 
 55 |     public readonly string BrowseName;
 56 |     public readonly NodeClass NodeClass;
 57 |     public readonly ConflictResolution Resolution;
 58 | }
 59 | ```
 60 | 
 61 | ### Conflict resolution example
 62 | 
 63 |  The following example will import the LoginForm from the TeamplateLibrary by overwriting the existing element (if any):
 64 | 
 65 | ```csharp
 66 | using UAManagedCore;
 67 | using FTOptix.HMIProject;
 68 | using FTOptix.NetLogic;
 69 | using System.Collections.Generic;
 70 | using static UAManagedCore.TemplateLibrary;
 71 | 
 72 | public class DesignTimeNetLogic1 : BaseNetLogic
 73 | {
 74 |     [ExportMethod]
 75 |     public void ImportLoginFormFromLibrary()
 76 |     {
 77 |         // Conflict resolution strategy
 78 |         var conflictResolutionChoices = new List<TypeConflictResolutionChoice>
 79 |         {
 80 |             // This is the list of elements which are inside the LoginForm object, we can specify how to handle each of them
 81 |             new TypeConflictResolutionChoice("LoginForm", NodeClass.ObjectType, ConflictResolution.Replace),
 82 |             new TypeConflictResolutionChoice("Login", NodeClass.ObjectType, ConflictResolution.Replace),
 83 |             new TypeConflictResolutionChoice("LoginPasswordExpiredDialog", NodeClass.ObjectType, ConflictResolution.Replace),
 84 |             new TypeConflictResolutionChoice("LoginChangePasswordForm", NodeClass.ObjectType, ConflictResolution.Replace),
 85 |             new TypeConflictResolutionChoice("Logout", NodeClass.ObjectType, ConflictResolution.Replace),
 86 |             new TypeConflictResolutionChoice("OAuth2Login", NodeClass.ObjectType, ConflictResolution.Replace)
 87 |         };
 88 |         // The place where the object will be imported
 89 |         var targetFolder = Project.Current.Get("UI");
 90 |         // Import the object
 91 |         // Syntax: ImportLibraryItem(<item destination>, <node class (type or instance)>, <name of the library>, <name of the library item>)
 92 |         var myWidget = TemplateLibrary.ImportLibraryItem(targetFolder, NodeClass.ObjectType, "Widgets", "LoginForm", conflictResolutionChoices);
 93 |         // Log the result
 94 |         Log.Info($"Imported LoginForm from library to: {Log.Node(myWidget)}");
 95 |     }
 96 | }
 97 | ```
 98 | 
 99 | ## Getting better performance
100 | 
101 | If you are importing a large object with many dependencies, you can improve the performance by calling the import routine using a LongRunningTask.
102 | 
103 | ### Importing a large object using a LongRunningTask
104 | 
105 | ```csharp
106 | [ExportMethod]
107 | public void ImportLargeObjectFromLibrary()
108 | {
109 |     // Import the object
110 |     var importWidgetTask = new LongRunningTask(ImportLoginForm, LogicObject);
111 |     importWidgetTask.Start();
112 | }
113 | 
114 | private void ImportLoginForm()
115 | {
116 |     // The place where the object will be imported
117 |     var targetFolder = Project.Current.Get("UI");
118 |     // Import the object
119 |     // Syntax: ImportLibraryItem(<item destination>, <node class (type or instance)>, <name of the library>, <name of the library item>)
120 |     var myWidget = TemplateLibrary.ImportLibraryItem(targetFolder, NodeClass.ObjectType, "Widgets", "LoginForm");
121 |     // Log the result
122 |     Log.Info($"Imported LoginForm from library to: {Log.Node(myWidget)}");
123 | }
124 | ```
125 | 


--------------------------------------------------------------------------------
/pages/translations.md:
--------------------------------------------------------------------------------
  1 | # Translations
  2 | 
  3 | ## Assign a translation key to a Text property
  4 | 
  5 | Please note: `myKey` should already exist in the TranslationDictionary
  6 | 
  7 | ```csharp
  8 | // Create a new label
  9 | Label myLabel = InformationModel.Make<Label>("MyLabelName");
 10 | // Create a new LocalizedText with a specific Key (that should exist in the LocalizationDictionary)
 11 | myLabel.LocalizedText = new LocalizedText(myLabel.NodeId.NamespaceIndex, "myKey1");
 12 | // Add the label to the project
 13 | Owner.Add(myLabel);
 14 | ```
 15 | 
 16 | ## Read the translation key of a Text property
 17 | 
 18 | ```csharp
 19 | // Get the LocalizedText variable from the Label
 20 | string myKey = myLabel.LocalizedText.TextId
 21 | ```
 22 | 
 23 | ```csharp
 24 | // Alternative way (same result)
 25 | string myKey = ((LocalizedText)myVariable.Value).TextId
 26 | ```
 27 | 
 28 | ## Read the translation content for a specific key
 29 | 
 30 | ```csharp
 31 | // Create a new temporary localized text to read the key value from the dictionary
 32 | LocalizedText alarmKey = new LocalizedText(LogicObject.NodeId.NamespaceIndex, "Alarm_TL_Key");
 33 | // Get the text value from the current language
 34 | string alarmMessage = InformationModel.LookupTranslation(alarmKey).Text;
 35 | ```
 36 | 
 37 | ## Adding a description to a variable
 38 | 
 39 | ```csharp
 40 | // Set the description of an object to a localized text
 41 | variable.Description = new LocalizedText(Project.Current.NodeId.NamespaceIndex, "descriptionTextId");
 42 | ```
 43 | 
 44 | ## Create a dictionary
 45 | 
 46 | Dictionary is a variable with dataType OpcUa.String and variableType FTOptix.Core.LocalizationDictionary, values are stored in a bidimensional array of string
 47 | 
 48 | ```csharp
 49 | private void StuffMakeNewDictionary(string browseName, string[]languages, IUANode dictionaryOwner) 
 50 | {
 51 |     if (dictionaryOwner == null || languages.Length <= 0 || string.IsNullOrEmpty(browseName))
 52 |         return;
 53 |     if (languages[0] != "")
 54 |     {
 55 |         // The first column needs to be empty as it's the keys list
 56 |         string[] firstColumnEmpty = new string[1] {""};
 57 |         // Add the languages to the other columns
 58 |         languages = firstColumnEmpty.Concat(languages).ToArray();
 59 |     }
 60 |     List<string> languageVerifiedToAdd = new List<string>();
 61 |     foreach (string language in languages) 
 62 |     {
 63 |         try
 64 |         {
 65 |             if (CultureInfo.GetCultureInfo(language, false) != null)
 66 |                 languageVerifiedToAdd.Add(language);
 67 |         }
 68 |         catch 
 69 |         {  
 70 |             // In case of culture identifier is not valid, skip to add to dictionary          
 71 |         }
 72 |     }
 73 |     string[,] newDictionaryValues = new string[1, languageVerifiedToAdd.Count];
 74 |     for (int i = 0; i < languageVerifiedToAdd.Count; i++) 
 75 |     {
 76 |         newDictionaryValues[0,i] = languageVerifiedToAdd[i];
 77 |     }
 78 |     // Create the new dictionary
 79 |     IUAVariable newDictionary = InformationModel.MakeVariable(
 80 |         browseName, 
 81 |         OpcUa.DataTypes.String, 
 82 |         FTOptix.Core.VariableTypes.LocalizationDictionary, 
 83 |         new uint[2] { 
 84 |             (uint)newDictionaryValues.GetLength(0), 
 85 |             (uint)newDictionaryValues.GetLength(1) 
 86 |         });
 87 |     // Set the dictionary content
 88 |     newDictionary.Value = new UAValue(newDictionaryValues);
 89 |     // Check if the dictionary does not exist already, then add it
 90 |     if (dictionaryOwner.Get(browseName) == null) 
 91 |         dictionaryOwner.Add(newDictionary);
 92 | }
 93 | ```
 94 | 
 95 | ## Add/Modify/Remove translation from a dictionary
 96 | 
 97 | Dictionary values are stored in a bidimensional array of string, you need to handle this rectangular array and regenerate the UAValue to store into the dictionary.
 98 | 
 99 | ### Add elements to the dictionary
100 | 
101 | This example provide a collection of array to add multiple records into the dictionary
102 | 
103 | ```csharp
104 | private void StuffAddDictionaryTranslations(IUAVariable dictionary, List<string[]> valuesToAdd)
105 | {
106 |     // A big dictionary may take a long processing time, so using a LongRunningTask is recommended to avoid blocking the main thread.
107 |     
108 |     // Validate input: if any of the inputs are null or empty, exit early.
109 |     if (dictionary == null || dictionary.Value.Value == null || valuesToAdd == null || valuesToAdd.Count <= 0)
110 |         return;
111 | 
112 |     string[,] actualDictionaryValues;
113 |     try
114 |     {
115 |         // Attempt to cast the dictionary's value to a 2D string array (dictionary format).
116 |         actualDictionaryValues = dictionary.Value.Value as string[,];
117 |     }
118 |     catch
119 |     {
120 |         // If the dictionary value is not a valid 2D array, stop further execution.
121 |         return;
122 |     }
123 | 
124 |     // List to store only verified values that can be safely added to the dictionary.
125 |     List<string[]> valuesVerifiedToAdd = new List<string[]>();
126 | 
127 |     // Iterate through each value set to be added to the dictionary.
128 |     foreach (string[] valueToAdd in valuesToAdd)
129 |     {
130 |         if (valueToAdd == null)
131 |             continue; // Skip null entries.
132 | 
133 |         // Check if the number of elements in the value matches the number of columns in the dictionary.
134 |         if (valueToAdd.Length != actualDictionaryValues.GetLength(1))
135 |         {
136 |             Log.Warning(LogicObject.BrowseName, "The count of elements to be added is different from the number of columns in the dictionary, skipped");
137 |             continue;
138 |         }
139 | 
140 |         // Validate that the first column (key) is not null or empty.
141 |         if (string.IsNullOrEmpty(valueToAdd[0]))
142 |         {
143 |             Log.Warning(LogicObject.BrowseName, "Missing key, skipped");
144 |             continue;
145 |         }
146 | 
147 |         // Check if the key already exists in the current dictionary.
148 |         string checkIfKeyExist = Enumerable
149 |             .Range(0, actualDictionaryValues.GetLength(0)) // Generate row indices.
150 |             .Where(x => actualDictionaryValues[x, 0] == valueToAdd[0]) // Check if the key matches the first column.
151 |             .Select(y => actualDictionaryValues[y, 0]) // Get the matching key.
152 |             .FirstOrDefault(); // Return the first match or null.
153 | 
154 |         if (!string.IsNullOrEmpty(checkIfKeyExist))
155 |         {
156 |             Log.Warning(LogicObject.BrowseName, $"Key {valueToAdd[0]} already exists, cannot add to dictionary, use Edit method");
157 |             continue;
158 |         }
159 | 
160 |         // Add the value to the list of verified values for addition.
161 |         valuesVerifiedToAdd.Add(valueToAdd);
162 |     }
163 | 
164 |     // Create a new dictionary with additional rows for the new entries.
165 |     string[,] newDictionaryValues = new string[actualDictionaryValues.GetLength(0) + valuesVerifiedToAdd.Count, actualDictionaryValues.GetLength(1)];
166 | 
167 |     // Copy the existing dictionary values to the new dictionary.
168 |     for (int i = 0; i < actualDictionaryValues.GetLength(0); i++)
169 |     {
170 |         for (int j = 0; j < actualDictionaryValues.GetLength(1); j++)
171 |         {
172 |             newDictionaryValues[i, j] = actualDictionaryValues[i, j];
173 |         }
174 |     }
175 | 
176 |     // Add the verified new values to the new dictionary starting from the next available row.
177 |     int rowOffset = 0;
178 |     foreach (string[] valueToAdd in valuesVerifiedToAdd)
179 |     {
180 |         for (int i = 0; i < valueToAdd.Length; i++)
181 |         {
182 |             int rowIndex = actualDictionaryValues.GetLength(0) + rowOffset; // Calculate the row index for the new entry.
183 |             newDictionaryValues[rowIndex, i] = valueToAdd[i]; // Add the value to the corresponding position.
184 |         }
185 |         rowOffset++; // Move to the next row for subsequent entries.
186 |     }
187 | 
188 |     // Update the dictionary's value with the new dictionary containing the added values.
189 |     dictionary.Value = new UAValue(newDictionaryValues);
190 | }
191 | 
192 | ```
193 | 
194 | ### Modify content of a dictionary
195 | 
196 | This example provide a collection of array to edit multiple records into the dictionary. Into a single array you can only write the language value to modify (take in consideration to place in correct order) and leave other field empty.
197 | 
198 | ```csharp
199 | private void StuffModifyDictionaryTranslations(IUAVariable dictionary, List<string[]> valuesToEdit)
200 | {
201 |     // A big dictionary may take a long time to process, so using a LongRunningTask is recommended to avoid blocking execution.
202 |     
203 |     // Validate inputs: check if dictionary or its value is null, or if there are no values to edit.
204 |     if (dictionary == null || dictionary.Value.Value == null || valuesToEdit == null || valuesToEdit.Count <= 0)
205 |         return;
206 | 
207 |     string[,] actualDictionaryValues;
208 |     try
209 |     {
210 |         // Attempt to cast the dictionary's value to a two-dimensional string array.
211 |         actualDictionaryValues = dictionary.Value.Value as string[,];
212 |     }
213 |     catch
214 |     {
215 |         // If the value cannot be cast, it may not be a dictionary, so stop further execution.
216 |         return;
217 |     }
218 | 
219 |     // Iterate over each entry in the valuesToEdit list.
220 |     foreach (string[] valueToEdit in valuesToEdit)
221 |     {
222 |         // Skip null entries.
223 |         if (valueToEdit == null)
224 |             continue;
225 | 
226 |         // Check if the entry length matches the number of dictionary columns.
227 |         if (valueToEdit.Length != actualDictionaryValues.GetLength(1))
228 |         {
229 |             Log.Warning(LogicObject.BrowseName, "The count of elements to be edited is different from the number of columns in the dictionary, skipped");
230 |             continue;
231 |         }
232 | 
233 |         // Ensure the key (first element) is not null or empty.
234 |         if (string.IsNullOrEmpty(valueToEdit[0]))
235 |         {
236 |             Log.Warning(LogicObject.BrowseName, "Missing key, skipped");
237 |             continue;
238 |         }
239 | 
240 |         // Find the row in the dictionary corresponding to the key.
241 |         int rowNumberToEdit = Enumerable
242 |             .Range(0, actualDictionaryValues.GetLength(0)) // Iterate over all rows.
243 |             .Where(x => actualDictionaryValues[x, 0] == valueToEdit[0]) // Check if the first column matches the key.
244 |             .FirstOrDefault(-1); // Default to -1 if no match is found.
245 | 
246 |         // If the key does not exist in the dictionary, log a warning and skip the entry.
247 |         if (rowNumberToEdit == -1)
248 |         {
249 |             Log.Warning(LogicObject.BrowseName, $"Key {valueToEdit[0]} does not exist, cannot edit the dictionary, use Add method");
250 |             continue;
251 |         }
252 | 
253 |         // Update the corresponding row with the new values.
254 |         for (int i = 0; i < valueToEdit.Length; i++)
255 |         {
256 |             // Only update non-empty values to avoid overwriting existing data with empty values.
257 |             if (!string.IsNullOrEmpty(valueToEdit[i]))
258 |                 actualDictionaryValues[rowNumberToEdit, i] = valueToEdit[i];
259 |         }
260 |     }
261 | 
262 |     // Update the dictionary with the modified values.
263 |     dictionary.Value = new UAValue(actualDictionaryValues);
264 | }
265 | 
266 | ```
267 | 
268 | ### Remove
269 | 
270 | This example provide a list of keys to delete multiple records into the dictionary.
271 | 
272 | ```csharp
273 | private void StuffRemoveDictionaryTranslations(IUAVariable dictionary, List<string> keysToRemove)
274 | {
275 |     // A big dictionary may take a long processing time, usage of a LongRunningTask is recommended
276 |     if (dictionary == null || dictionary.Value.Value == null || keysToRemove == null || keysToRemove.Count <= 0)
277 |         return;
278 |     string[,] actualDictionaryValues;
279 |     try
280 |     {
281 |         actualDictionaryValues = dictionary.Value.Value as string[,];
282 |     }
283 |     catch
284 |     {
285 |         //Maybe is not a dictionary, so is better to stop execution here
286 |         return;
287 |     }
288 |     List<int> rowsToRemove = new List<int>();
289 |     const int defaultValue = 0;
290 |     foreach(string keyToRemove in keysToRemove) 
291 |     {
292 |         if (string.IsNullOrEmpty(keyToRemove))
293 |         {
294 |             Log.Warning(LogicObject.BrowseName, "Missing key, skipped");
295 |             continue;
296 |         }
297 |         int rowToDelete = Enumerable
298 |        .Range(0, actualDictionaryValues.GetLength(0))
299 |        .Where(x => actualDictionaryValues[x, 0] == keyToRemove)
300 |        .FirstOrDefault(defaultValue);
301 |         if (rowToDelete == defaultValue)
302 |         {
303 |             Log.Warning(LogicObject.BrowseName, $"Key {keyToRemove} not exist, cannot edit the dictionary, use Add method");
304 |             continue;
305 |         }
306 |         rowsToRemove.Add(rowToDelete);
307 |     }
308 |     if (rowsToRemove.Count >= actualDictionaryValues.GetLength(0))
309 |     {
310 |         Log.Error(LogicObject.BrowseName, "The rows to be removed are equal to or more than the dictionary entries with header, impossible to continue");
311 |         return;
312 |     }
313 |     string[,] newDictionaryValues = new string[actualDictionaryValues.GetLength(0) - rowsToRemove.Count, actualDictionaryValues.GetLength(1)];
314 |     int rowToWrite = 0;
315 |     for (int i = 0; i < actualDictionaryValues.GetLength(0); i++) 
316 |     {
317 |         if (!rowsToRemove.Contains(i))
318 |         {
319 |             for (int j = 0; j < actualDictionaryValues.GetLength(1); j++)
320 |             {
321 |                 newDictionaryValues[rowToWrite, j] = actualDictionaryValues[i, j];
322 |             }
323 |             rowToWrite++;
324 |         }
325 |     }
326 |     dictionary.Value = new UAValue(newDictionaryValues);
327 | }
328 | ```
329 | 
330 | ### Example of previous code snippets
331 | 
332 | You can build a Design NetLogic with all previous methods to create and populate a Dictionary
333 | 
334 | ```csharp
335 | [ExportMethod]
336 | public void Method1()
337 | {
338 |     // Get to the translations folder
339 |     Folder translation = Project.Current.Get<Folder>("Translations");
340 |     // Create the new dictionary object
341 |     StuffMakeNewDictionary("MyNewDictionary", new string[6] { "", "it-IT", "en-US", "fr-FR", "es-ES","de-DE" }, translation);
342 |     // Set some content to the dictionary
343 |     List<string[]> fillThisDict = new List<string[]>
344 |     {
345 |         new string[6] { "keyHello1", "Ciao", "Hello", "Bonjour", "Hola", "Hallo" },
346 |         new string[6] { "keyHello", "Ciao", "Hello", "Bonjour", "Hola", "Hallo" },
347 |         new string[6] { "keyStart2", "Avviare!", "Start!", "Démarrer!", "Inicio!","Start!" },
348 |         new string[6] { "keyStop2", "Fermare", "Stop", "Arrêter", "Para", "Stopp" },
349 |         new string[6] { "keyStart", "Avviare", "Start", "Démarrer", "Inicio", "Start" },
350 |         new string[6] { "keyStop", "Fermare", "Stop", "Arrêter", "Para", "Stopp" },
351 |         new string[6] { "keyStop3", "Fermare", "Stop", "Arrêter", "Para", "Stopp" }
352 |     };
353 |     StuffAddDictionaryTranslations(translation.GetVariable("MyNewDictionary"), fillThisDict);
354 |     // Add even more lines to the dictionary
355 |     List<string[]> editThisDict = new List<string[]>
356 |     {
357 |         new string[6] { "keyHello", "Ciao!", "Hello!", "Bonjour!", "Hola!", "Hallo!" },
358 |         new string[6] { "keyStop", "Fermati!", "Stop", "Arrêter", "Para", "Stopp" },
359 |         new string[6] { "keyStart2", "Avviare", "Start", "Démarrer", "Inicio", "Start" }
360 |     };
361 |     StuffModifyDictionaryTranslations(translation.GetVariable("MyNewDictionary"), editThisDict);
362 |     // Remove some unused keys
363 |     List<string> removeToThisDict = new List<string>
364 |     {
365 |         "keyHello1",
366 |         "keyStart2",
367 |         "keyStop2",
368 |         "keyStop3"
369 |     };
370 |     StuffRemoveDictionaryTranslations(translation.GetVariable("MyNewDictionary"), removeToThisDict);
371 | }
372 | ```
373 | 
374 | ## Send the current locale to the PLC
375 | 
376 | > [!NOTE] 
377 | > This code might limit the flexibility of locales switching in FactoryTalk Optix. 
378 | 
379 | By default, each session has its own independent locale. This means that the script will be triggered every time any connected session changes its locale. The last session to change the locale will update the value in the controller.
380 | 
381 | This setup works fine if you are using only one session. However, if you are using multiple sessions, you should use a different approach. For example, you could log the locale change for each session separately into different variables.
382 | 
383 | ```csharp
384 | public class RuntimeNetLogic1 : BaseNetLogic
385 | {
386 |     // Place this code in the RuntimeNetLogic1.cs file
387 |     // in the MainWindow object of the project
388 | 
389 |     public override void Start()
390 |     {
391 |         // Subscribe to the LocaleId variable change event
392 |         Session.ActualLocaleIdVariable.VariableChange += Session_LocaleIdVariable_VariableChange;
393 |         // You can also log the initial LocaleId value if needed
394 |         Log.Info("Initial LocaleId: " + Session.ActualLocaleId);
395 |     }
396 | 
397 |     private void Session_LocaleIdVariable_VariableChange(object sender, VariableChangeEventArgs e)
398 |     {
399 |         // This code will be executed when the LocaleId variable changes
400 |         // You can add your custom logic here
401 |         var newLocaleId = e.NewValue;
402 |         // For example, you can log the new LocaleId
403 |         Log.Info("New LocaleId: " + newLocaleId);
404 |         // Or send the new LocaleId to the PLC
405 |         Project.Current.Get<Variable>("CommDrivers/PLC1/Tags/LocaleId").Value = newLocaleId;
406 |     }
407 | 
408 |     public override void Stop()
409 |     {
410 |         // Unsubscribe from the variable change event
411 |         if (Session.LocaleIdVariable != null)
412 |         {
413 |             Session.ActualLocaleIdVariable.VariableChange -= Session_LocaleIdVariable_VariableChange;
414 |         }
415 |     }
416 | }
417 | ```
418 | 


--------------------------------------------------------------------------------
/pages/trends.md:
--------------------------------------------------------------------------------
 1 | # Trends
 2 | 
 3 | ## Add a pen to a trend
 4 | 
 5 | ```csharp
 6 | [ExportMethod]
 7 | public void AddPen(NodeId penId)
 8 | {
 9 |     // Get the variable that will be used as a pen
10 |     var tag = InformationModel.GetVariable(penId);
11 |     // Create the pen object
12 |     var pen = InformationModel.Make<TrendPen>(tag.BrowseName + "_pen");
13 |     // Link the pen to the variable
14 |     pen.SetDynamicLink(tag, DynamicLinkMode.ReadWrite);
15 |     // Set the pen properties
16 |     pen.Color = Colors.Coral;
17 |     pen.Thickness = 3;
18 |     // Add the pen to the trend
19 |     trend.Pens.Add(pen);
20 |     // Refresh the trend to show the new pen
21 |     trend.Refresh();
22 | }
23 | ```
24 | 
25 | ## Add a Y-axis to a pen
26 | 
27 | ```csharp
28 | [ExportMethod]
29 | public void AddYAxisToPen(NodeId penId)
30 | {
31 |     // Get the pen and the Y-axis
32 |     var pen = InformationModel.Get<TrendPen>(penId);
33 |     // Create a new Y-axis
34 |     var yAxis = InformationModel.Make<ValueAxis>("YAxis");
35 |     // Set the Y-axis properties
36 |     yAxis.MinValueVariable.Value = -10;
37 |     yAxis.MaxValueVariable.Value = 42;
38 |     yAxis.PositionVariable.Value = 0; // 0 = left, 1 = right
39 |     // Add the Y-axis to the pen
40 |     pen.YAxes.Add(yAxis);
41 | }
42 | ```
43 | 


--------------------------------------------------------------------------------
/pages/ui-animations.md:
--------------------------------------------------------------------------------
  1 | # UI Animations
  2 | 
  3 | Animations allow variable values to be changed with a defined (or infinite) number of iterations; these animations can also be contained in parallel (run concurrently) or sequential animations.
  4 | 
  5 | ## Number animation
  6 | 
  7 | Numerical animations allow the offset to be added to the value of the variable by defining an initial value to a final value by also defining the relevant type of interpolation (the value is an enumeration called EasingCurve)
  8 | 
  9 | ```csharp
 10 | private NumberAnimation CreateNumberAnimation(IUANode ownerAnimationNode, NodeId targetAnimationNode, int from, int to, int loops, bool running, int duration, EasingCurve interpolation)
 11 | {
 12 |     // Look at the count of current animations in the node
 13 |     int animationCounter = ownerAnimationNode.GetNodesByType<NumberAnimation>().Count();
 14 |     // Create a new Number Animation with a browseName with index +1 over the current present animations
 15 |     var numberAnimation = InformationModel.Make<NumberAnimation>($"NumberAnimation{animationCounter + 1}");
 16 |     // Set animation parameters, target animation node must be a NodeId
 17 |     numberAnimation.Target = targetAnimationNode;
 18 |     numberAnimation.From = from;
 19 |     numberAnimation.To = to;
 20 |     numberAnimation.Loops = loops;
 21 |     numberAnimation.Running = running;
 22 |     numberAnimation.Duration = duration;
 23 |     numberAnimation.EasingCurve = interpolation;
 24 |     // Add the animation node to the target node
 25 |     ownerAnimationNode.Add(numberAnimation);
 26 |     // Return the new animation for further future use
 27 |     return numberAnimation;
 28 | }
 29 | ```
 30 | 
 31 | ## Sequential animation
 32 | 
 33 | Sequential animation allows all animations of this object to be performed sequentially
 34 | 
 35 | ```csharp
 36 | private SequentialAnimation CreateSequentialAnimation(IUANode ownerAnimationNode, int loops, bool running)
 37 | {
 38 |     // Look at the count of current animations in the node
 39 |     int animationCounter = ownerAnimationNode.GetNodesByType<SequentialAnimation>().Count();
 40 |     // Create a new Sequential Animation with a browseName with index +1 over the current present animations
 41 |     var sequentialAnimation = InformationModel.Make<SequentialAnimation>($"SequentialAnimation{animationCounter + 1}");
 42 |     // Set animation parameters
 43 |     sequentialAnimation.Loops = loops;
 44 |     sequentialAnimation.Running = running;
 45 |     // Add the animation node to the target node
 46 |     ownerAnimationNode.Add(sequentialAnimation);
 47 |     // Return the new animation for further future use
 48 |     return sequentialAnimation;
 49 | }
 50 | ```
 51 | 
 52 | ## Parallel animation
 53 | 
 54 | Parallel animations allow all animations of this object to run simultaneously
 55 | 
 56 | ```csharp
 57 | private ParallelAnimation CreateParallelAnimation(IUANode ownerAnimationNode, int loops, bool running)
 58 | {
 59 |     // Look at the count of current animations in the node
 60 |     int animationCounter = ownerAnimationNode.GetNodesByType<ParallelAnimation>().Count();
 61 |     // Create a new Parallel Animation with a browseName with index +1 over the current present animations
 62 |     var parallelAnimation = InformationModel.Make<ParallelAnimation>($"ParallelAnimation{animationCounter + 1}");
 63 |     // Set animation parameters
 64 |     parallelAnimation.Loops = loops;
 65 |     parallelAnimation.Running = running;
 66 |     // Add the animation node to the target node
 67 |     ownerAnimationNode.Add(parallelAnimation);
 68 |     // Return the new animation for further future use
 69 |     return parallelAnimation;
 70 | }
 71 | ```
 72 | 
 73 | ### Example of creating animations on a TextBox
 74 | 
 75 | ```csharp
 76 | [ExportMethod]
 77 | public void GenerateStuffAnimation()
 78 | {
 79 |     var targetUiObject = Project.Current.Get<Item>("UI/Screens/Screen1/TextBox1");
 80 |     var parallelAnimation = CreateParallelAnimation(targetUiObject, 10, true);
 81 |     _ = CreateNumberAnimation(parallelAnimation, targetUiObject.OpacityVariable.NodeId, 0, 100, -1, true, 2000, EasingCurve.Linear);
 82 |     var sequentialAnimation = CreateSequentialAnimation(targetUiObject, 5, true);
 83 |     _ = CreateNumberAnimation(sequentialAnimation, targetUiObject.RotationVariable.NodeId, 0, 360, -1, true, 2000, EasingCurve.Linear);
 84 | 
 85 | }
 86 | ```
 87 | 
 88 | ## Value change animation
 89 | 
 90 | Animation on value change allows you to define the animation and duration to make the new value reach the value that is set in the variable
 91 | 
 92 | ```csharp
 93 | [ExportMethod]
 94 | public void GenerateStuffBehaviorAnimation()
 95 | {
 96 |     var targetUiObject = Project.Current.Get<Item>("UI/Screens/Screen1/TextBox1");
 97 |     CreateBehaviorAnimation(targetUiObject.WidthVariable, 5000, EasingCurve.InOutQuad);
 98 | }
 99 | 
100 | private void CreateBehaviorAnimation(IUANode targetAnimationNode, int duration, EasingCurve interpolation)
101 | {
102 |     // Check that targetNode is a variable and does not already have Behavior Animation
103 |     if (targetAnimationNode is not IUAVariable || targetAnimationNode.GetNodesByType<BehaviourAnimation>().Any())
104 |     {
105 |         return;
106 |     }
107 |     // Create new Behavior Animation
108 |     var behaviorAnimation = InformationModel.Make<BehaviourAnimation>($"Value change animation");
109 |     // Set animation parameters
110 |     behaviorAnimation.Duration = duration;
111 |     behaviorAnimation.EasingCurve = interpolation;
112 |     // Add the animation node to the target node
113 |     targetAnimationNode.Add(behaviorAnimation);
114 | }
115 | ```
116 | 


--------------------------------------------------------------------------------
/pages/users-groups.md:
--------------------------------------------------------------------------------
  1 | # Users, groups and roles
  2 | 
  3 | Groups and roles are used to manage user permissions in FactoryTalk Optix. Users can be assigned to groups and roles, which can then be used to control access to various parts of the system.
  4 | 
  5 | Both Roles and Groups are reference types, meaning that they can be assigned to users by adding a reference between the user and the group or role. This allows for flexible management of user permissions.
  6 | 
  7 | For example:
  8 | 
  9 | ```csharp
 10 | // Get all groups the user is part of
 11 | var userGroups = newUser.Refs.GetObjects(FTOptix.Core.ReferenceTypes.HasGroup, false);
 12 | // Get all roles the user is part of
 13 | var userGroups = newUser.Refs.GetObjects(FTOptix.Core.ReferenceTypes.HasRole, false);
 14 | ```
 15 | 
 16 | Roles can be assigned to groups and users, groups can be assigned to roles and users, you can make any combination of these to create a flexible permission system.
 17 | 
 18 | ## Groups
 19 | 
 20 | ### Creating a new Group
 21 | 
 22 | ```csharp
 23 | [ExportMethod]
 24 | public void CreateNewGroup(string groupName) {
 25 |     // Get to the base folder to create groups
 26 |     Folder userFolder = Project.Current.Get<Folder>("Security/Groups");
 27 |     if (userFolder == null) {
 28 |         Log.Error("CreateNewGroup", "Cannot find Groups folder");
 29 |         return;
 30 |     } else if (string.IsNullOrEmpty(groupName)) {
 31 |         Log.Error("CreateNewGroup", "Cannot create group with empty name");
 32 |         return;
 33 |     } else if (userFolder.Get<Group>(groupName) != null) {
 34 |         Log.Error("CreateNewGroup", "Group already exists!");
 35 |         return;
 36 |     }
 37 |     // Create a new group
 38 |     var newGroup = InformationModel.Make<Group>(groupName);
 39 |     // Add the group to the folder
 40 |     userFolder.Add(newGroup);
 41 | }
 42 | ```
 43 | 
 44 | ### Check if user is part of a group
 45 | 
 46 | ```csharp
 47 | // Method to check if a user is part of a specific group
 48 | private static bool UserHasGroup(FTOptix.Core.User user, FTOptix.Core.Group group)
 49 | {
 50 |     // Return false if user is null
 51 |     if (user == null)
 52 |         return false;
 53 |     
 54 |     // Return false if group is null
 55 |     if (group == null)
 56 |         return false;
 57 | 
 58 |     // Get all groups the user is part of
 59 |     var userGroups = user.Refs.GetObjects(FTOptix.Core.ReferenceTypes.HasGroup, false);
 60 | 
 61 |     // Iterate through the groups to check if the user is part of the specified group
 62 |     foreach (var userGroup in userGroups)
 63 |     {
 64 |         if (userGroup.NodeId == group.NodeId)
 65 |             return true;
 66 |     }
 67 |     // Return false if the user is not part of the specified group
 68 |     return false;
 69 | }
 70 | ```
 71 | 
 72 | ### Assign group to a user
 73 | 
 74 | ```csharp
 75 | /// <summary>
 76 | /// Assigns a user to a specified group by adding a reference between the user and the group.
 77 | /// </summary>
 78 | /// <param name="user">The user to be assigned to the group.</param>
 79 | /// <param name="group">The group to which the user will be assigned.</param>
 80 | private void AssignUserToGroup(FTOptix.Core.User user, FTOptix.Core.Group group)
 81 | {
 82 |     user.Refs.AddReference(FTOptix.Core.ReferenceTypes.HasGroup, group.NodeId);
 83 | }
 84 | ```
 85 | 
 86 | ### Remove group from a user
 87 | 
 88 | ```csharp
 89 | /// <summary>
 90 | /// Removes a user from the specified group by removing a reference between the user and the group.
 91 | /// </summary>
 92 | /// <param name="user">The user to be removed from the group.</param>
 93 | /// <param name="group">The group to which the user will be removed from.</param>
 94 | private void RemoveUserFromGroup(FTOptix.Core.User user, FTOptix.Core.Group group)
 95 | {
 96 |     user.Refs.RemoveReference(FTOptix.Core.ReferenceTypes.HasGroup, group.NodeId);
 97 | }
 98 | ```
 99 | 
100 | ## Roles
101 | 
102 | ### Creating a new Role
103 | 
104 | ```csharp
105 | [ExportMethod]
106 | public void CreateNewRole(string roleName) {
107 |     // Get to the base folder to create roles
108 |     Folder userFolder = Project.Current.Get<Folder>("Security/Roles");
109 |     if (userFolder == null) {
110 |         Log.Error("CreateNewRole", "Cannot find Roles folder");
111 |         return;
112 |     } else if (string.IsNullOrEmpty(roleName)) {
113 |         Log.Error("CreateNewRole", "Cannot create role with empty name");
114 |         return;
115 |     } else if (userFolder.Get<FTOptix.Core.Role>(roleName) != null) {
116 |         Log.Error("CreateNewRole", "Role already exists!");
117 |         return;
118 |     }
119 |     // Create a new role
120 |     var newRole = InformationModel.Make<FTOptix.Core.Role>(roleName);
121 |     // Add the role to the folder
122 |     userFolder.Add(newRole);
123 | }
124 | ```
125 | 
126 | ### Check if user is part of a role
127 | 
128 | ```csharp
129 | /// <summary>
130 | /// Checks if a user is part of a specified role.
131 | /// </summary>
132 | /// <param name="user">The user to check.</param>
133 | /// <param name="role">The role to check against.</param>
134 | /// <returns>True if the user is part of the role, otherwise false.</returns>
135 | private static bool UserHasRole(FTOptix.Core.User user, FTOptix.Core.Role role)
136 | {
137 |     // Return false if user is null
138 |     if (user == null)
139 |         return false;
140 |     
141 |     // Return false if role is null
142 |     if (role == null)
143 |         return false;
144 | 
145 |     // Get all roles the user is part of
146 |     var userRoles = user.Refs.GetObjects(FTOptix.Core.ReferenceTypes.HasRole, false);
147 | 
148 |     // Iterate through the roles to check if the user is part of the specified role
149 |     foreach (var userRole in userRoles)
150 |     {
151 |         if (userRole.NodeId == role.NodeId)
152 |             return true;
153 |     }
154 |     // Return false if the user is not part of the specified role
155 |     return false;
156 | }
157 | ```
158 | 
159 | ### Assign role to a user
160 | 
161 | ```csharp
162 | /// <summary>
163 | /// Assigns a user to a specified role by adding a reference between the user and the role.
164 | /// </summary>
165 | /// <param name="user">The user to be assigned to the role.</param>
166 | /// <param name="role">The role to which the user will be assigned.</param>
167 | private void AssignUserToRole(FTOptix.Core.User user, FTOptix.Core.Role role)
168 | {
169 |     user.Refs.AddReference(FTOptix.Core.ReferenceTypes.HasRole, role.NodeId);
170 | }
171 | ```
172 | 
173 | ### Remove role from a user
174 | 
175 | ```csharp
176 | /// <summary>
177 | /// Removes a user from the specified role by removing a reference between the user and the role.
178 | /// </summary>
179 | /// <param name="user">The user to be removed from the role.</param>
180 | /// <param name="role">The role to which the user will be removed from.</param>
181 | private void RemoveUserFromRole(FTOptix.Core.User user, FTOptix.Core.Role role)
182 | {
183 |     user.Refs.RemoveReference(FTOptix.Core.ReferenceTypes.HasRole, role.NodeId);
184 | }
185 | ```
186 | 
187 | ## Get the list of groups associated to the user which is logging in
188 | 
189 | Please see: [Register OPC/UA observers](./register-observers.md).
190 | 


--------------------------------------------------------------------------------
/pages/variables-formatting.md:
--------------------------------------------------------------------------------
 1 | # Variables formatting
 2 | 
 3 | ## Zero padding
 4 | 
 5 | Reads value of `i`, converts into a string and add a zero to the left if value is less than 10
 6 | 
 7 | ```csharp
 8 | text = i.ToString("D2");
 9 | ```
10 | 
11 | ## Print the hex equivalent of any character
12 | 
13 | ```csharp
14 | keyPressed = "a";
15 | Log.Info(BitConverter.ToString(Encoding.Default.GetBytes(keyPressed)));
16 | ```
17 | 


--------------------------------------------------------------------------------
/pages/variables-properties.md:
--------------------------------------------------------------------------------
 1 | # Variables properties
 2 | 
 3 | ## Adding engineering units to a variable
 4 | 
 5 | The engineering unit follows the OPC-UA standard and is identified by a unique ID that has been issued by the foundation, you can check [Here](https://reference.opcfoundation.org/Core/Part8/v104/docs/5.6.3).
 6 | 
 7 | > [!WARNING]
 8 | > It is mandatory to use IDs to generate an EUInformation
 9 | 
10 | ```csharp
11 | private void GenerateEUInfo(NodeId targetVariable, uint eUID)
12 | {
13 |     // Check if the target variable is a valid IUAVariable
14 |     if (InformationModel.GetVariable(targetVariable) is IUAVariable variableToAnalyze)
15 |     {
16 |         // Check if the variable already has an EngineeringUnits property
17 |         // If it does, update the UnitId value
18 |         if (variableToAnalyze.GetVariable("EngineeringUnits") is IUAVariable euInfo)
19 |         {
20 |             euInfo.GetVariable("UnitId").Value = eUID;
21 |         }
22 |         // If it doesn't, create a new EngineeringUnits property and set the UnitId value
23 |         else
24 |         {
25 |             euInfo = InformationModel.MakeVariable<EUInformation>("EngineeringUnits", OpcUa.DataTypes.EUInformation);
26 |             euInfo.QualifiedBrowseName = new QualifiedName(0,"EngineeringUnits");
27 |             euInfo.GetVariable("UnitId").Value = eUID;
28 |             variableToAnalyze.Refs.AddReference(OpcUa.ReferenceTypes.HasProperty, euInfo);
29 |         }          
30 |     }
31 | }
32 | ```
33 | 


--------------------------------------------------------------------------------