7.8.5 ConfigurationFiles

7.8.5.1 ConfigurationFileType

This type defines a FileType that can be used to access the configuration associated with an Object.

The file is a stream containing an instance of UABinaryFileDataType serialized using one of the DataEncodings defined in OPC 10000-6. The DataEncoding used depends on the DataEncoding used for the messages sent to the Server. The body of the UABinaryFileDataType shall be an instance of the DataType specified by the SupportedDataType Property.

An instance of a ConfigurationFileType shall restrict access to appropriate users or applications. This should be ConfigureAdmin, SecurityAdmin or an equivalent administrative Role.

The Open Method shall not support modes other than Read (0x01) and Read + Write (0x03).

When a Client opens the file for reading and writing, the Client shall follow the following steps.

Read the existing configuration with the FileType Read Method.

Set the position to the beginning of the file with the FileType SetPosition Method.

Write the changes with the FileType Write Method.

Apply the changes with the CloseAndUpdate Method.

Servers shall automatically Close ConfigurationFiles if there are no calls to Methods on the ConfigurationFile Object within the time specified by the ActivityTimeout Property.

The Size Property inherited from FileType has no meaning for ConfigurationFile and returns the error code defined in OPC 10000-20.

When the CloseAndUpdate Method is called the Server will validate the configuration and then schedules the update. The Server returns initial results in the CloseAndUpdate response and may return additional errors after applying the changes in the response to ConfirmUpdate.

If CloseAndUpdate succeeds it returns a UpdateId that is used to confirm that the Client can connect after the update by calling the ConfirmUpdate Method. If it is not necessary to call ConfirmUpdate, the Server returns a empty value for the UpdateId.

The LastUpdateTime Property indicates when the configuration was last updated. The LastUpdateTime shall reflect changes made using the ConfigurationFile Object Methods. A ConfigurationFile Object should also reflect changes made in other ways.

The CurrentVersion Property is the value of the Version for the currently active configuration.

The ActivityTimeout Property specifies the maximum elapsed time between the calls to Methods on the ConfigurationFile Object after Open is called. If this time elapses the ConfigurationFile is automatically closed by the Server and any changes are discarded. The default value is 60 000 milliseconds (1 minute).

The SupportedDataType Property specifies the NodeId of the DataType that is put into the body of the UABinaryFileDataType during reading and writing. Any DataType shall be a subtype of BaseConfigurationDataType which is defined in 7.8.5.4.

The CloseAndUpdate Method validates the configuration and returns any validation errors.

The ConfirmUpdate Method is used to confirm that the Client can reconnect after the changes were applied.

7.8.5.2 CloseAndUpdate

The CloseAndUpdate Method closes the ConfigurationFile and applies the changes to the configuration. It can only be called if the ConfigurationFile was opened for writing. If the Close Method is called any cached data is discarded and the configuration is not changed.

The Client may partially update the configuration by specifying one or more targets. Each target refers to a component of the configuration that will be inserted, updated or deleted. The Server shall attempt to apply all changes. If any errors occur then all changes are rolled back.

Updating the configuration will often require the endpoints to be closed and all active Sessions be interrupted. When the new configuration is applied it is possible that a configuration error made the Server unreachable. The RestartDelayTime argument is used to delay the restart process to give the Client a chance to receive results from the CloseAndUpdate call. The RevertAfterTime argument is used to automatically restore the previous configuration if the Client is not able to reconnect and call the ConfirmUpdate Method.

If auditing is supported, the Server shall generate the ConfigurationUpdatedAuditEventType (see 7.8.5.8) when the configuration is updated. This may occur before CloseAndUpdate completes or when the update is scheduled to occur based on the RestartDelayTime.

Signature

CloseAndUpdate(
	[in]  0:UInt32 FileHandle
	[in]  0:VersionTime VersionToUpdate
	[in]  0:ConfigurationUpdateTargetType[] Targets
	[in]  0:Duration RevertAfterTime
	[in]  0:Duration RestartDelayTime
	[out] 0:StatusCode[] UpdateResults
	[out] 0:VersionTime NewVersion
	[out] 0:Guid UpdateId
);

Method Result Codes (defined in Call Service)

Operation Result Codes (Returned in UpdateResults)

Table 29 specifies the AddressSpace representation for the CloseAndUpdate Method.

7.8.5.3 ConfirmUpdate

The ConfirmUpdate Method allows a Client to confirm that it can connect after the configuration has been applied. The Client shall disconnect from the Server and reconnect before calling ConfirmUpdate. The RevertAfterTime parameter passed to the CloseAndUpdate Method specifies how long the Server shall wait for confirmation.

If the Server could not apply all changes then the return code is Bad_TransactionFailed and no changes were applied.

If the Method is called too soon the Server returns Bad_InvalidState.

The permissions needed to call this method shall be specified by the subtype and should require one of the administrator Roles.

Signature

ConfirmUpdate(
	[in]  0:Guid UpdateId
);

Method Result Codes (defined in Call Service)

Table 28 specifies the AddressSpace representation for the ConfirmUpdate Method.

7.8.5.4 BaseConfigurationDataType

This DataType is the base DataType used to serialize configurations. It is defined in Table 65.

7.8.5.5 BaseConfigurationRecordDataType

This DataType is the base DataType for a named record contained within a configuration. It is defined in Table 67.

Its representation in the AddressSpace is defined in Table 66.

7.8.5.6 ConfigurationUpdateTargetType

This is a DataType that defines a target for an update operation It allows the Client to specify the type of update operation (insert, replace or delete).

The Path field defines the path to the target record of the update operation within the configuration. Only fields which are subtypes of BaseConfigurationRecordDataType are valid targets of the path.

The UpdateType specifies that operation to be performed.

Examples of paths:

CertificateGroups.[1]

ApplicationIdentity

UserTokenSettings.[2]

The ConfigurationUpdateTargetType is defined in Table 69.

Its representation in the AddressSpace is defined in Table 70.

7.8.5.7 ConfigurationUpdateType

This is a DataType that defines the values used for the UpdateType field in the ConfigurationUpdateTargetType. Its values are defined in Table 71.

The update operation is applied to a target within the configuration identified by a path (see 7.8.5.6). The Replace and Delete operations use the Name field in the Structure to match a target with an existing record. For Insert operations no existing record with the same Name may exist. For Delete operations the contents of the record are ignored.

Its representation in the AddressSpace is defined in Table 72.

7.8.5.8 ConfigurationUpdatedAuditEventType

This event is raised when a configuration been updated.

The SourceNode Property for Events of this type shall be assigned to the NodeId for the Node that owns the configuration (usually the parent of the ConfigurationFile Object). The SourceName for Events of this type shall be the BrowseName of the configuration owner.

Its representation in the AddressSpace is formally defined in Table 73.

This EventType inherits all Properties of the AuditEventType. Their semantic is defined in OPC 10000-5.

The DataType Property specifies the DataType of the configuration that was updated.