< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 69 of 145 Table 82 – StandardUIAction definition Name Type Description StandardUIAction UInteger Identifier for the standard UI action item with one of the following values: APPLY_0 Apply Standard UI Action • With this action the Client requests that parameter changes in the user interface will be applied to the source. CLOSE_1 Close Standard UI Action • With this action the Client requests that the UIP be closed. If changes to the parameters have not been applied, the UIP shall open a dialog asking the user to confirm. HELP_2 Help Standard UI Action • Requests to display online help describing the UIP functionality (a help document). It is no substitute for context-sensitive help which will typically be provided via tooltips. 6.1.2.3 StandardUIActionItem The components of this parameter are defined in Table 83. Table 83 – StandardUIActionItem definition Name Type Description StandardUIActionItem Structure actionId StandardUIAction Identifier for the standard UI action item. enabled Boolean Indicates the state of the action item. “true” indicates the item is enabled. “false” indicates the item is disabled. 6.1.2.4 SpecificUIActionItem The components of this parameter are defined in Table 84. Table 84 – SpecificUIActionItem definition Name Type Description SpecificUIActionItem structure actionId UInteger Identifier for the action item that is specific to the UIP. descriptor String A human readable string which provides information about the action. enabled Boolean Indicates the state of the Action Item. “true” indicates the item is enabled. “false” indicates the item is disabled. label String Label of the action item. 6.2 UIP instantiation rules For each device instance there may be a maximum of two instances of the same UIP type, one for the offline version and one for the online version. 6.3 UIP state machine States NOTE Create and Dispose are technology dependent services described in FCG TS62769-6 and its subparts. Create uses the StartElementName Property (see FCG TS62769-5) of the UIP to create the appropriate UIP. Figure 7 shows the UIP state machine. If the UIP Services (see 6.1) trigger state changes, they are mentioned on the state machine edges. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 70 of 145 Created Operational Activate Create Loaded Deactivated Deactivate Dispose Disposed NOTE Create and Dispose are technology dependent services described in FCG TS62769-6. Create uses the StartElementName Property (see FCG TS62769-5) of the UIP to create the appropriate UIP. Figure 7 – UIP state machine The UIP states are specified in Table 85. Table 85 – UIP states State Description Created The initial state after the UIP instance is created by the FDI Client. Operational The normal execution state. Deactivated The final state before a UIP is disposed. State transitions The UIP state transitions are defined in Table 86. Table 86 – UIP state transitions Source state Event Destination state Loaded The FDI Client created the UIP instance. Created Created Activate service has been called on UIP instance. Operational Operational Deactivate service has been successfully called on UIP instance. Deactivated Deactivated The FDI Client disposed the UIP instance. Disposed Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 71 of 145 6.4 UIP permissions and restrictions Introduction The permissions, a FDI Client shall grant to a UIP are specified in this section. Mandatory permissions shall be granted by the FDI Client to the UIP as they are granted by the operating system. This does not mean that a UIP has unrestricted access to the complete file system. The permissions for accessing the file system and printers are defined by the system configuration. NOTE The setting of permissions for operation system resources in a system configuration is outside the scope of this standard. Optional permissions can be restricted compared to the permissions given by the system configuration. The means by which an FDI Client can restrict permissions, are specified in FCG TS62769-6. UIPs shall never block the Client, for instance by issuing synchronous calls to potentially block operating system resources. Worker threads are a common means for avoiding blocking situations. A UIP shall not implement role based access permission constraints. Access to local file system A UIP shall have read and write access to a specific directory on the client machine. This UIP directory is shared by all UIPs. The UIP uses the hosting service GetHostingProperties to query the information (path) of the directory from the FDI Client. The UIP directory shall be persistent, i.e. the host nor the hosting environment shall not delete any files within the UIP directory. The UIP can create / delete subdirectories within the UIP directory and shall organize the data in the directory according to its own responsibility. Data stored in the UIP directory is accessible to other UIPs and potentially other users. Thus if there is data of sensitive nature UIPs shall implement additional protection mechanisms (see IEC 62443-3-3, SR 4.1 Information Confidentiality). Data read from the UIP directory should be subject to input validation and possibly be authenticated. Furthermore, data stored in the UIP directory should be purged on closing the UIP (see IEC 62443-3-3 SR 4.2). File system permissions may be used to restrict access to the files to the UIP user. Export / Import of files Using the hosting services ImportFile / ExportFile the UIP can save data to a user selectable location within the file system of the FDI Client respectively it can import files from a a user selectable location within the file system of the FDI Client. UIPs shall perform a validation of the imported file to assure the file is as expected. Note: The security of the local file system and possibly mapped network drives is beyond scope of this specification. It is assumed that the administrator of the machine the FDI Client is executed on, manages this. Inter-Process Communication (IPC) A UIP process may use IPC to communicate with other processes executed on the same machine. The UIP process is not allowed to communicate with processes on other machines, i.e. the UIP shall not have any network access. The UIP is not allowed to start new processes. Instead the UIP can interact with a running process that provides services. How the process is managed is not in scope of this specification. The UIP should not assume any authentication of the other process to be done by the FDI Client. Thus the UIP IPC usage must authenticate peer processes where appropriate. A UIP should perform sanity checks for actions requested by other processes to be performed by the UIP. A UIP shall not expose services to other services. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 72 of 145 Note: The trustworthiness of external applications is beyond the scope of this specification. Mechanisms such as application whitelisting, code signing, access control should be applied to reduce the risk of malicious external applications (see IEC 62443-3-3 SR 3.4). Open files based on MIME Type Using the hosting service InitOpenDefaultApplication, a UIP may open a file in the registered application for this MIME type. The application is started by the FDI Client and the file is opened. The FDI Client may limit the MIME types which UIPs can work with. Note: The trustworthiness of external applications is beyond the scope of this specification. It is the user’s responsibility to register the appropriate external application to handle the MIME file types (see IEC 62443-3-3 SR 3.4). Access to ressources The UIP shall have access to the printers, which are available in the hosting environment.A UIP executable shall not perform internet access. A UIP executable shall not perform local area network (LAN) access. 6.5 UIP deployment UIP downloads from FDI Server The following scenarios require an FDI Client to retrieve a UIP. • The UID specifies a UIP in its XML element Plugin (see Annex A). • The UIP opens another UIP with the OpenUserInterface service (see 5.2.2.3). In all scenarios the FDI Client gets a UipId as identification for the UIP. A UipId is a UUID (universally unique identifier). A UIP may have several UIP Variants that differ in their platform and runtime support (see FCG TS62769-4). NOTE A UipId does not contain version information. Resolving a UipId to the appropriate version of the UIP is done by the FDI Server based on FDI Package information. The same UipId may be resolved to different UIP versions for different Devices. At different points in time even for the same Device the same UipId may be resolved differently if a UIP update happened in the FDI Server in between. With the UipId the FDI Client can retrieve the following information about all corresponding UIP Variants (see FCG TS62769-5) from the FDI Server. • RuntimeId and PlatformId • UIPVariantVersion • FDITechnologyVersion For this the FDI Client calls the OPC UA service TranslateBrowsePathToNodeIds with the following list of relative names: "UIPSet/<UipId>" "UIPSet/<UipId >/RuntimeId" "UIPSet/<UipId >/PlatformId" "UIPSet/<UipId >/FDITechnologyVersion" "UIPSet/<UipId >/Style" "UIPSet/<UipId >/StartElementName" "UIPSet/<UipId >/UIPVariantVersion" Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 73 of 145 The FDI Server returns arrays of NodeIds for each relative name. The number of entries in each array matches the number of UIP Variants for the UipId. Next the FDI Client can read the property values. If multiple UIP Variants are available, the FDI Client chooses the most appropriate UIP Variant based on FDITechnologyVersion, RuntimeId, and PlatformId. The FDI Client may maintain a cache of UIP Variants already downloaded from the FDI Server. If UipId, RuntimeId, PlatformId, FDITechnologyVersion and UIPVariantVersion of the chosen UIP Variant match with a UIP Variant in its UIP Variant cache, this UIP Variant can be used and no download from the FDI Server is required. If no cache is maintained or no matching UIP Variant is found in the cache, the FDI Client shall read the FDITechnologyVersion (see FCG TS62769-5) of the chosen UIP Variant. The parameter FDITechnologyVersion helps the FDI Client to determine whether it can support the execution of the UIP. The FDI Client shall execute a UIP of the same major version independently from the minor version or revision. Finally the FDI Client can download the selected UIP from the FDI Server by reading the value of the UIP Variant. An FDI Client may implement another sequence than the one described here. For example, it may check the FDITechnologyVersion first to determine whether it can run the UIP at all. The FDITechnologyVersion is the same for all UIP Variants of a specific version of a UIP. The FDI Client may implement optimization strategies. For example, it may cache UIP versions (in addition to UIP Variant versions). If the version of the UIP is identical to the cached UIP version, there is no need to read the UIP Variant versions because they are required to be the same for an identical UIP version (see FCG TS62769-4). UIP management on FDI Client The UIP installation is done per file copy only. The UIP is installed within a folder structure, which is called the UIP folder structure. The FDI Client shall manage the UIP folder structure. The UIP folder structure shall separate the UIP Variants from each other in order to avoid file name conflicts. UIP executables shall be installed to a path that allows browse and read access.Since the FDI Client manages the folder structure the UIP shall not perform any access to an absolute path. Any file access shall be done relative to the installation root of the UIP. Reference data bases and help files (UIP Supplementary data) shall be provided with UIP and stored within in the UIP installation folder on the FDI Client. The access permission to this folder is read-only. According the version management described in FCG TS62769-4, the coexistence of major version changes of UIP of the same type shall be supported. This shall be done by installing a newer UIP into a separate folder. 7 Actions 7.1 General The EDD contained in the FDI Package as defined in FCG TS62769-4 may have EDD methods. Some EDD methods may be exposed to the FDI Client as Actions and can be triggered by FDI Clients. NOTE These Actions have no relationship to the EDD ACTION construct. Actions are executed in the FDI Server. The Action state machine is defined in FCG TS62769-3. An FDI Client can invoke an Action by calling the OPC UA InvokeAction method (see FCG TS62769-5). State changes of the corresponding Action state machine are sent to the FDI Client via the subscription mechanism (see IEC 62541-4). Additional data that may come with a state change are transferred as an XML document. An Action may involve user interaction. The result of a user interaction is sent to the FDI Server with the RespondAction service (see FCG TS62769-5). Data that are sent with this service are transferred as an XML document. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 74 of 145 An Action can be aborted either by the Client of by the Server. If the Server aborts an Action, it first sends an AbortingNotification. The Client shall reply with an AbortNotificationConfirmation but still continue processing ActionRequests. Once the AbortNotification was received, the Client shall disable the CancelButton. When the abort process is finished, the Server will send an AbortRequest to the Client. The Client replies with an AbortResponse and closes the ActionWindow. An FDI Client may abort an Action as follows: 1. Call the AbortAction service (see FCG TS62769-5) 2. Reply to an existing ActionRequest by sending a valid ActionResponse. 3. Continue processing of ActionRequests. 4. The Server sends an AbortingNotification once it has started the abort process. The Client shall reply with an AbortNotificationConfirmation but still continue processing ActionRequests. Once the AbortNotification was received, the Client shall disable the CancelButton. 5. The Action is aborted after an AbortingRequest is received from the Server. The Client shall reply with an AbortResponse and closes the ActionWindow. Annex B contains an example of an EDD method being executed by an FDI Server and the resulting interaction with an FDI Client. It includes state diagrams and exchanged messages (XML snippets). 7.2 Sequence diagram The sequence diagram shown in Figure 8 shows the client/server interaction of an Action call. This diagram assumes as a pre-condition that the Action can be started from a user interface shown by the FDI Client. NOTE 1 The diagram shows UIDInterpreter, ActionWindow and AcknowledgeWindow as subsystems of the FDI Client. It also shows EDDMethodExecution as a subsystem of the FDI Server. This is for explanatory reasons only. The Action is initiated from the user interface. If not already locked, InitLock has to be called first. The FDI Client then calls the OPC UA InvokeAction method (see FCG TS62769-5). The name of the Action to be invoked, as well as any Action arguments needed, is given as OPC UA method arguments. The FDI Server responds to the InvokeAction call by creating an Action execution state machine and responds to the FDI Client by returning an ActionNodeId that represents the state machine in the Information Model. The FDI Server is responsible for running the state machine (as defined in FCG TS62769-3) and updating its state in the Information Model using the provided ActionNodeId. The ActionNodeId is also used by the FDI Client to establish subscriptions with the FDI Server in order to monitor the Action execution. As the Action execution proceeds, the FDI Server updates the state machine and the corresponding Node in the Information Model. If there are any existing subscriptions for the ActionNodeId the FDI Server will process these changes and advise the FDI Client of the changes. During the Action execution, operations such as notifications, read and write (also to other Nodes than the Node with the ActionNodeId) are not blocked. The FDI Server begins an Action by first setting the state to Running and then starts to execute the EDD method. The FDI Client uses the OPC UA AddMonitoredItem service (see IEC 62541-4) to establish a subscription using the provided ActionNodeId. The FDI Server responds to the newly created subscription by advising the FDI Client of the current state of the Action state machine. In this sequence diagram the subscription was established before the Action execution reaches any notable state such as the TimeDelay state. Therefore, the first notice to the FDI Client would indicate “Running”. If the Action had reached the TimeDelay state before the subscription was established the first notice to the FDI Client would indicate “TimeDelay” since this would be the current state. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 75 of 145 UIDInterpreterFDIServer InvokeAction(“ActionName”, list of Arguments) EDD Method Execution New(“ActionName”) Response(ActionNodeId) Init(ActionNodeId) Action Window New() AddMonitoredItem(ActionNodeId.value) Response(MonitoredItemId) UIRequest(“Running”) UIRequest(“TimeDelay”, 10sec) UIRequest(“TimeDelay”, 5sec) Update(MonitoredItemId, value) Update(MonitoredItemId, value) UIRequest(“Acknowledge”, “Ok to Continue?”) Update(MonitoredItemId, value) Acknowledge Window New() Init(ActionNodeId) Alternate Response cases No Response (Timeout Condition) Abort Response Acknowledge Response UIRequest(“Aborted”, Timeout) Update(MonitoredItemId, value) Close() AbortAction(ActionNodeId) AbortExecution UIRequest(“Aborted”, ByUser) Update(MonitoredItemId, value) Close() Response() RespondAction(ActionNodeId, Response) Feedback UIRequest(“Running”) Update(MonitoredItemId, value) Close() UIRequest(“Completed”) Update(MonitoredItemId, value) Update(MonitoredItemId, value) RemoveMonitoredItem(MonitoredItemId) RemoveMonitoredItem(MonitoredItemId) RemoveMonitoredItem(MonitoredItemId) Button Associated with Action is pressed Abort Button Pressed OK Button Pressed Open(ActionNodeId) InitLock(DeviceNodeId) ExitLock(DeviceNodeId) Close self Close self Close self Figure 8 – FDI Action sequence diagram Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 76 of 145 The FDI Client shall not maintain an Action state machine. NOTE 2 The information sent to the FDI Client combines state information and the last UI request. Therefore, there is no race condition with respect to when the FDI Client adds the state Node as a monitored item. Even if the Action state machine has gone through several state transitions, the FDI Client need not know this. The standard OPC UA behaviour is that the current information is sent when a Node is added as monitored item. When the FDI Server enters the TimeDelay state the ActionNodeId is updated at the beginning of the delay and at the end of the delay. There may also be intermediate updates regarding the length of the delay. The actual frequency of the intermediate updates is determined by the design of the FDI Server, typically every few seconds. All updates of the ActionNodeId will be submitted to the FDI Client via the subscription mechanism. In example 1 in Figure 8, the FDI Server has entered a time delay of 10 seconds and sends updates every 5 seconds. When the FDI Server enters the WaitingForFeedback state the Information Model is updated including the user prompt. The state machine pauses the execution of the Action until a response from the user is provided or a timeout expires. The state machine change results in the FDI Client being provided a notification. The FDI Client detecting that the new state is WaitingForFeedback opens a message dialog presenting the prompt provided in the state information as well as a means to provide feedback. In example 2 in Figure 8, the FDI Client shows the buttons to “OK” the method or “Abort” the method. Response case “Timeout”: If the user fails to respond to the prompt before the server timeout expires the FDI Server will abort the Action execution. The state in the Information Model is set to Aborted with an indication that the cause was a timeout condition. The Action execution terminates at this point but the FDI Server maintains the state Node and the final state until the subscriptions are terminated either by the FDI Client removing the monitored item or a general timeout of the FDI Client session with the FDI Server. Response case “Abort”: If the user responds to the FDI Server with an abort response the method execution is aborted. The state in the Information Model is set to Aborted with an indication that the cause was a user action. The FDI Server maintains the state Node and the final state until the subscriptions are terminated either by the FDI Client removing the monitored item or a general timeout of the FDI Client session with the FDI Server. The state Node is also preserved if the Completed or Aborted state of the Action state machine is reached before the FDI Client established a subscription and added the state Node as a monitored item. Response case “Positive feedback”: If the user responds to the FDI Server with positive feedback the Action execution sets the state in the Information Model back to Running and continues the normal execution of the Action. In example 3 in Figure 8, no further state changes occur before the end of the Action and therefore the next state change is to the final Completed state. The state machine terminates after the final state is set. The FDI Server maintains the state Node and the final state until the subscriptions are terminated either by the FDI Client removing the monitored item or a general timeout of the FDI Client session with the FDI Server. NOTE 3 No separate KeepAlive method is needed. The supervision of the session tells the FDI Server that the FDI Client is alive. After the Action execution ended and the monitored item has been removed the lock can be removed. 7.3 FDI Action schema definition The XML schema for the XML sent between the FDI Client and FDI Server is defined in Annex A. NOTE The XML schema in Annex A also includes the definitions for UIDs. ActionRequest is the root element of the XML documents that are exchanged from the FDI Server to the FDI Client during Action execution. These XML documents are sent to the FDI Client with the Update service (see IEC 62541-4). The mandatory part of these documents is the ActionState that specifies the current state of the corresponding Action state machine (see FCG TS62769-3). Additional data is specified if the FDI Client has to Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 77 of 145 show a user interface on behalf of the Action. The user interface style as well as content is specified in this additional data. ActionResponse is the root element of the XML documents that are exchanged from FDI Client to FDI Server. These documents are used when the user provides feedback for a UI request. The Action state machine (as defined in FCG TS62769-3) shall be in state WaitingForFeedback or WaitingForFeedbackA. The FDI Server sets the state back to Running or Aborting after receiving the user feedback. These XML documents are sent with the RespondAction service (as defined in FCG TS62769-5). Arguments for Actions are also specified by XML documents. The arguments are specified with the ListOfActionArguments type as name-value pairs. 8 User Interface Description (UID) 8.1 Overview As defined in FCG TS62769-5, top-level FunctionalGroup in the Information Model may contain a UIDescription (UID) Node or a set of UIPlugin (UIP) Nodes. The Value Attribute of a UID Node is a string, and the UID XML Schema defines the contents of that string. The XML schema is defined in Annex A. NOTE 1 The XML schema in Annex A also includes the definitions for FDI Actions. In addition to the UID Nodes exposed in the Information Model via FunctionalGroups, there may be non- browseable UID Nodes. As shown in Figure 9, non-browseable UID Nodes are linked to a parent UID Node via the NodePath attribute. The parent UID Node may be either a browseable or non-browseable Node. The root element of the Value Attribute of a FunctionalGroup's UID Node shall be a Window, Dialog, Menu, or Table element. The root element of the Value Attribute of a non-browseable UID Node shall be a Window, Dialog, Page, Menu, or Table element. The Value Attribute of a FunctionalGroup's UID Node shall contain enough information to allow the FDI Client to render the visible parts of the view. The FDI Server may omit those parts of the view that are not visible. In place of the omitted information the FDI Server shall provide a reference (via the NodePath attribute) to a non- browseable UID Node that contains the missing information. The FDI Client may use the specified NodePath to obtain the missing information from the FDI Server as it deems necessary. NOTE 2 An example of a non-visible part of a window would be the second page of a tabbed dialog. The label of the second page is visible, but the content of the second page is not. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 78 of 145 FunctionalGroupType: <Identifier> UIDescriptionType: <Identifier> Value Attribute <Window> … </Window> UIDescriptionType: <Identifier> Value Attribute <Page> … </Page> UIDescriptionType: <Identifier> Value Attribute <Page> … </Page> UIDescriptionType: <Identifier> Value Attribute <Dialog> … </Dialog> FunctionalGroupType: <Identifier> Nested functional groups have neither a UID nor a UIP Organizes Value Attribute references non-browseable UID nodes FunctionalGroupType: <Identifier> Organizes Figure 9 – User Interface Descriptions The XML returned to the FDI Client from an FDI Server contains layout elements and content elements. Layout elements define the visual organization, positioning, and structure of the user interface. Content elements are the basic building blocks of the user interface. NOTE 3 The XML only includes “valid” elements. New XML documents will be returned if validity changes. The layout elements are • ColumnBreak • Dialog • EditDisplay • Group Next >