Retrieving VPM Identification

3D PLM Enterprise Architecture	VPM Navigator	Retrieving VPM Identification Retrieving information about existing object
Use Case

Abstract

This article shows the way to retrieve VPM Identification information about Part Version or Document Revision object using an Identification Acquisition Agent and explains how to use it in a command.

What You Will Learn With This Use Case
The Acquisition Agent and test Command Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to explain how to obtain VPM identification information about a selected object in either 'Query-Result' or 'Explorer' windows of the VPM Navigator. Use of such an Agent is demonstrated by means of an Agent test command from an Explorer window.

[Top]

The Acquisition Agent and test Command Use Case

The Agent test Command is a use case of the CAACATImmENOVIAProvider.edu framework that illustrates Identifier Acquisition Agent capabilities.

[Top]

What Does the Agent test Command Do

CAAImmIdAcqAgentTestCmd is a state dialog command which returns the VPM Identification information using the Identifier Acquisition Agent and is described by the following UML statechart diagram.

The dialog is as follows:

Select a Part Version or Document Revision Object from VPMNavigator tree.

The command returns with the VPM Identification information on the object selected. The command is then complete.

[Top]

How to Launch the Agent test Command

To launch CAAImmIdAcqAgentTestCmd , you will need to set up the build time environment, then compile CAAImmIdAcqAgentTestCmd along with its prerequisites, set up the run time environment, and then execute the use case [1] in the following way:

Run CNEXT on the command line.
Connect to Enovia using the command on Enovia V5 Toolbar.
Enter Login, Password and Enovia Server information and click OK to login.
Run Search command for a product on Enovia V5 Toolbar.
Right-Click on a Product and run Send To VPM Navigator.
Click on a Document Revision or Part Version and run the CAAImmIdAcqAgentTestCmd available from VPM Navigator workbench.

[Top]

Where to Find the Agent test Command Code

The Agent test command is made up of a single class named CAAImmIdAcqAgentTestCmd located in the CAAImmIdAcqAgentTestCmd.m module of the CAACATImmENOVIAProvider.edu framework :

Windows	`InstallRootDirectory\CAACATImmENOVIAProvider.edu\CAAImmIdAcqAgentTestCmd.m\`
Unix	`InstallRootDirectory/CAACATImmENOVIAProvider.edu/CAAImmIdAcqAgentTestCmd.m/`

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

To retrieve VPM Identification information using the Acquisition Agent, following steps should be followed:

#	Step	Where
1	Declare the Identification Acquisition agent	Header file
2	Instantiate the Acquisition agent	`BuildGraph` method
3	Assign the Acquisition agent to the Initial state	`BuildGraph` method
4	Create a transition from the Initial state triggered by the Acquisition agent valuation	`BuildGraph` method
5	Retrieve the VPM Identification	Transition action method `ActionCommand`
6	Release the Acquisition agent	Destructor

[Top]

Declaring the Acquisition Agent

The agent test command derives from CATSTateCommand.

class CAAImmIdAcqAgentTestCmd: public CATStateCommand
{
...
private:
	CATImmIdentifierAcquisitionAgent* _ImmIdentifierAcquisition;
    ...

A pointer to the Acquisition agent is declared as a private data member. This Acquisition agent is an instance of the CATPathElement class.

[Top]

Instantiating the Acquisition Agent

The Acquisition agent is intantiated in the command BuildGraph method.

void CAAImmIdAcqAgentTestCmd::BuildGraph()
{
...
_ImmIdentifierAcquisition = new CATImmIdentifierAcquisitionAgent();
  ...

[Top]

Assigning the Acquisition agent to a dialog state

Still in the BuildGraph method, the SelectImmersiveObject state is created, and the Acquisition agent is added to this state. This makes it possible to value the Acquisition agent when this state becomes the active one.

  ...
  pFirstState = GetInitialState("SelectImmersiveObject");
  pFirstState->AddDialogAgent(_ImmIdentifierAcquisition);
  ...

This Agent test command is a single stage command. The GetInitialState method retrieves a dialog state and adds it to the states managed by the dialog command. The AddDialogAgent method adds the Acquisition agent to the state. This acquisition agent supports selection of a single object only.

[Top]

Creating transition from start state to the end of command

The transition between the initial state and the end of command is created in the BuildGraph method. This transition is triggered when the Acquisition agent is valued, that is when the end user clicks a Part Version or a Document Revision.

  ...
  AddTransition(pFirstState, NULL,
    IsOutputSetCondition(_ImmIdentifierAcquisition), 
    Action ((ActionMethod)&CAAImmIdAcqAgentTestCmd::ActionCommand, NULL, NULL, (void*)NULL));
  ...

The AddTransition method creates a transition and adds it to the transitions managed by the dialog command. Pointers to the transition's source and target states are the first and second arguments respectively. In this case, the second parameter is nulled to indicate that the end of command. The transition trigger is defined in the guard condition as the first condition to be checked using the IsOutputSetCondition method applied to the Acquisition agent. This condition returns True when the Acquisition agent is valued. When the condition method returns True the transition is fired. In this case, the ActionCommand(void *) action method is executed.

[Top]

Retrieving the VPM Identification

When the guard condition returns true, the ActionCommand(void*) method is executed. In this method, the Acquisition agent object is used to retrieve Identification information as follows:

...
CATBoolean CAAImmIdAcqAgentTestCmd::ActionCommand(void* data)
{
	CATUnicodeString domainType = _ImmIdentifierAcquisition->GetType();
	
	CATListOfCATUnicodeString oNM;
	CATListOfCATUnicodeString oVA;
	
	hr=_ImmIdentifierAcquisition->GetIdentifiers(oNM, oVA);
	
	if(SUCCEEDED(hr)){
	  CATUnicodeString id_value=oVA[1];
	  CATUnicodeString version_value=oVA[2];
	  CATUnicodeString att_name=oNM[1];
	  CATUnicodeString att_vname=oNM[2];
	  ...
	}
  ...

First, using the GetType function, the type of the acquired object is returned in the form of 'Domain/Type'. For example, If a PartVersion object is acquired in the PRODUCT domain, the returned string will be PRODUCT/ENOVIA_VPMPartVersion.

Secondly, using the GetIdentifiers method, the identifiers of Enovia VPM object are acquired. For example, If a PartVersion object is selected by the end user, the identifiers V_ID and V_version for that object will be returned.

[Top]

Releasing the Acquisition agent

It is recommended to deallocate the agent at the end of the command, or when its use is finished in the following way,

if(_ImmIdentifierAcquisition){
		    _ImmIdentifierAcquisition->RequestDelayedDestruction();
	     }
             _ImmIdentifierAcquisition=NULL;
  ...

[Top]

In Short

This use case shows usage of the VPM Identifier Acquisition agent and the way to retrieve the VPM Identification information for a selected Part Version or Document Revision.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [Jan 2006]	Document created
[Top]

3D PLM Enterprise Architecture

VPM Navigator