This method is used to add a configuration to the configuration management of the vision system. It concerns itself only with the metadata of the configuration, the actual content is transferred by an object of ConfigurationTransferType which is defined in Section 7.4.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

AddConfiguration ([in]ConfigurationIdDataTypeexternalId[out]ConfigurationIdDataTypeinternalId[out]NodeIdconfiguration[out]BooleantransferRequired[out]Int32error);

Table 12 – AddConfiguration Method Arguments

Argument	Description
externalId	Identification of the configuration used by the environment. This argument must not be empty.
internalId	System-wide unique ID for identifying a configuration. This ID is assigned by the vision system.
configuration	If the server chooses to represent the configuration in the Address Space, it shall return the NodeId of the newly created entry in the Configurations variable here. If the server uses only method-based configuration management, this shall be a null NodeId as defined in OPC 10000-3.
transferRequired	In this argument, the server returns whether the vision system assumes that a transfer of the file content of the configuration is required. Note that this is only a hint for the client. If the server returns TRUE, the client will have to assume that the vision system needs the configuration content and shall transfer it. If the server returns FALSE, the client may transfer the configuration content anyway.
error	0 – OK Values > 0 are reserved for errors defined by this and future standards. Values < 0 shall be used for application-specific errors.

Table 13 – AddConfiguration Method AddressSpace Definition

Attribute	Value
BrowseName	AddConfiguration
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If AddConfiguration is called with an ExternalId not yet existing in the configuration management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is unique on the system. The server then returns this InternalId.

If the server chooses to represent all or selected configurations in the Address Space and if the new configuration matches the current selection criteria, the server shall create a new entry in the Configurations folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the configuration management of the vision system, it is expected the configuration does not yet exist either in the local configuration storage of the vision system, and therefore needs to be transferred.

If AddConfiguration is called with an ExternalId already existing in the configuration management of the vision system, it is expected that the vision system checks whether an identical version of the configuration already exists, provided that the content of the ExternalId allows for such a check. (A way to perform this comparison without having to download the binary content first is offered by the optional hash value in the ExternalId. The idea is that the client computes a hash for the contents of the recipe and passes that hash in the ExternalId. The server can then check this hash against a hash transmitted earlier, or it can compute a hash by itself over the contents of the recipe currently stored on the vision system side. For this procedure, the server needs to know the hash algorithm used by the client which can be transmitted in the hashAlgorithm member of the ExternalId).

Note that the method has no way of checking this with the actual configuration content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the method comes to the conclusion that the configuration already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the configuration content anyway.

If the server represents configurations in the Address Space, no new entry shall be created in the configurations folder.

If AddConfiguration comes to the conclusion that the content of the configuration to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the configuration metadata and configuration content is entirely application-defined. The vision system may decide to create a new management structure and add the configuration content to the local configuration store, or it may decide to re-use the existing ExternalId and overwrite the configuration content. In any case, the vision system shall create a new, system-wide unique InternalId for this configuration.

If the server chooses to represent configurations in the Address Space, the behavior with respect to these objects should mirror the behavior of the vision system in its internal configuration management.

This is not, strictly speaking, a use case of the method AddConfiguration, but results are comparable, and therefore the use case is described here.

If a configuration is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the configuration is added without using method AddConfiguration, then this configuration shall have a system-wide unique InternalId, just like a configuration added through the method.

If an existing configuration which was uploaded to the vision system through the method AddConfiguration, is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two configurations cannot be confused. The vision system may record the history from which configuration it was derived.

If the server exposes configurations in the Address Space and if the locally created or edited configurations match the current filter criteria, then they shall be represented as nodes in the Configurations folder, with their system-wide unique InternalIds, but without ExternalIds.