This method is used to add a recipe to the recipe management of the vision system. It concerns itself only with the metadata of the recipe, the actual content is transferred by a RecipeTransferType object.

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

Signature

AddRecipe ([in]RecipeIdExternalDataTypeexternalId[in]ProductIdDataTypeproductId[out]RecipeIdInternalDataTypeinternalId[out]NodeIdrecipe[out]NodeIdproduct[out]BooleantransferRequired[out]Int32error);

Table 31 – AddRecipe Method Arguments

Argument	Description
externalId	Identification of the recipe used by the environment. This argument must not be empty.
productId	Identification of a product the recipe is to be used for. This argument may be empty.
internalId	Internal identification of the recipe. This identification shall be system-wide unique and must be returned.
recipe	If the server chooses to represent the recipe in the Address Space, it shall return the NodeId of the newly created entry in the Recipes folder here. If the server uses only method-based recipe management, this shall be null. Note that, even if the server uses the Recipes folder to expose recipe data in the Address Space, this may be empty, if the newly created recipe does not fit the selection criteria of the server for the entries in this folder.
product	If the server chooses to represent product information in the Address Space, it shall return the NodeId of a newly created entry in the Products folder here. If the server uses only method-based recipe management, this shall be null. Note that, even if the server uses the Products folder to expose product data in the Address Space, this may be null if the newly created product does not fit the selection criteria of the server for the entries in the Products folder.
transferRequired	In this argument, the server returns whether the vision system assumes that a transfer of the file content of the recipe 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 recipe content and shall transfer it. If the server returns FALSE, the client may transfer the recipe 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 32 – AddRecipe Method AddressSpace Definition

Attribute	Value
BrowseName	AddRecipe
References	Node Class	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

If AddRecipe is called with an ExternalId not yet existing in the recipe management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is system-wide unique. The server may then return this InternalId, however the client cannot rely on this.

If the server chooses to represent all or selected recipes in the Address Space and if the new recipe matches the current selection critieria, the server shall create a new entry in the Recipes folder in the Address Space.

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

If the ProductId argument is non-empty, it is expected that the vision system creates an appropriate management structure linking the newly created recipe for use with this ProductId. If the ProductId does not yet exist on the vision system, it is expected that it is created.

If the ProductId argument is empty, no such linking takes place. Note that it will not be possible to start a job based on a ProductId not linked to a recipe.

If the server chooses to represent all or selected products in the Address Space and if the ProductId matches the selection criteria, the server shall create a new entry in the Products folder in the Address Space.

If the server chooses to represent all or selected recipes in the Address Space and if the given recipe matches the selection criteria, the ProductId shall be added to the list of products within the appropriate Recipe node.

If AddRecipe is called with an ExternalId already existing in the recipe management of the vision system, it is expected that the vision system checks whether an identical version of the recipe already exists, provided that the content of the ExternalId allows for such a check (most likely using the hash value).

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

The method will return FALSE in the TransferRequired argument if the system comes to the conclusion that the recipe 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 recipe content anyway.

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

The behavior with regard to the ProductId argument is as described above for a new ExternalId. This way of calling AddRecipe can be used to link an existing recipe with another product.

If AddRecipe comes to the conclusion that the content of the recipe 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 recipe metadata and recipe content is entirely application-defined. The vision system may decide to create a new management structure with a new InternalId and add the recipe content to the local recipe store, or it may decide to re-use the existing ExternalId and overwrite the recipe content.

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

The behavior with regard to the ProductId argument is as described above for a new ExternalId. If the vision system stores both recipe versions, it is implementation-defined whether both are linked to the ProductId or not.

Note that overwriting a recipe shall result in a change to the internalId of the recipe. The change may effect only the hash value, the identifier may remain the same. Historical storage is not required.

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

If a recipe 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 recipe is added without using the AddRecipe method, then this recipe shall have a system-wide unique InternalId, just like a recipe added through the method.

If an existing recipe which was uploaded to the vision system through AddRecipe 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 recipes cannot be confused. Of course the vision system may record the history from which recipe it was derived.

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

An important special case is the local editing of an already prepared recipe, described in Section B.1.2.3. Since after local editing, the already prepared recipe is different from before, effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).