Tool-defined Resource Operations

Unlike static resource operations such as UPDATE or DELETE, tool-defined resource operations can be dynamically returned by a tool. There are only two reasons for using a tool-defined resource operation instead of a static one:

The correct resource operation for an element can be determined only at run time, such as for an update or insert.
Based on one input element, the tool creates or updates several elements, for example, a compile tool which creates output files.

Examples

A tool Check OutFile either updates an element if it already exists in the application's development stage (UPDATE) or copies a file into the application's development stage (INSERT).
The tool Compile Program creates several build output files (multiple INSERT resource operations).

Configuring a tool-defined resource operation in the model requires the following:

The Resource Processing attribute of the tool descriptor must be set to TOOL-DEFINED.
Properties returned by the resource operation must be modeled as output parameters of the type ToolDefinedResourceOperation for tools defined according to the old tool interface (before Enterprise Developer 5.0) or as "Resource Operation Value" for tools defined according to the new tool interface.

The resource operations to be processed by AWM are returned by the tool at run time by using specific syntax:

      operation(refid,REFRESH,SELECT): properties

See the table below for more information.

Example

UPDATE-ELEMENT(DDLOCK): SCLM,DEV1,SOURCE,TESTRP1, 2014/03/21 09:16:28

This resource operation updates the changed date and time of an SCLM element with the ID SCLM_DEV1_SOURCE_TESTRP1 and saves the properties in a separate context. This element can be accessed by follow-up tools by the logical name DDLOCK in the 'Affected Resource Name' attribute of the Action_Has_Tool relationship.

Keyword	Description
operation *	The resource operation to be executed. Valid values: INSERT-ELEMENT INSERT-CHILD REMOVE-ELEMENT UPDATE-ELEMENT The values are equivalent to the static resource operations INSERT, INSERT-CHILD, REMOVE and UPDATE.
refid [O]	A reference ID, which is a logical name that creates a separate context that can be accessed by other tools within the action. Properties returned by this resource operation are stored in the separate context instead of the main context. Any following tools of the action that have the reference ID modeled as Affected Resource Name (relationship Action has Tool) use that separate context. See Relationship: Action Has Tool for more information.
REFRESH [O]	Determines whether to execute the "Get All Properties" action of the element. This action is executed directly after the tool that returned this resource operation.
SELECT [O]	Selects the element in the view where the action was executed. Only relevant if the properties of the resource operation contain a valid element ID (combination of ID definition properties). See ID Definition for more information.
properties	Depending on the resource operation, the following rules apply to tool output parameters: INSERT-ELEMENT and INSERT-CHILD Requires all key properties of the element that should be created and the match name property. If the returned ID exists, an UPDATE is performed instead. Additional regular properties are added to the inserted or updated element. REMOVE-ELEMENT Depending on whether key properties and the match name property are returned by the resource operation, either the identified element or the selected one is removed. UPDATE-ELEMENT Only updates properties returned by the resource operation. Key properties and match name update a specific element. Without key properties, the selected element is updated. Returned resource operation properties must be modeled as output parameters of the type ToolDefinedResourceOperation.

Affected Resource Contexts

Tool-defined resource operations can provide a logical name to create a separate, independent execution context to be used by subsequent tools. This context is called an Affected Resource Context and is only used by tools which refer to its logical name in the relationship Action has Tool . Exceptions to this are related save/close actions, see note below.

Scenarios can occur where the element of interest changes during an action. It is possible to create multiple affected resource contexts during an action.

Example

An action “Create Test Case…” is executed on a program. Its first tool creates a test case element and returns an INSERT tool-defined resource operation with affected resource name TESTCASE and properties for the new test case element. The second tool opens the test case in an editor, using TESTCASE as the affected resource name (relationship Action has Tool). This is necessary, because both the program and the test case element have common properties, for example, path, name, and suffix. The edit tool requires the path, name, and suffix from the test case element, not from the program.

Note:

If a tool that supports related save/close actions is used with an Affected Resource Context, related actions are executed on the same referenced context. See Related Save-/Close Action for more information.
Before AWM V3.0, affected resource contexts were not independent from the main context. Properties and output parameters in the main context were still resolved in affected resource contexts, which was causing inconsistencies and a lack of transparency. In order to maintain backward compatibility, this behavior can still be enabled by setting the application option Independent Affected Resource Contexts to false. See Application Options for more information.