Lifecycle Applications

What You Will Learn With This Use Case

This use case is intended to help you make your first steps in programming user-exits. More particularly, it shows how to implement a user-exit that is called by the Workflow (WFL) modeler.

[Top]

The CAAVpiWFLUserExit Use Case

CAAVpiWFLUserExit is a use case of the CAAVPMInterfaces.edu framework that illustrates VPMInterfaces framework functionalities.

[Top]

What Does CAAVpiWFLUserExit Do

The goal of CAAVpiWFLUserExit use case is to show how to implement a particular user-exit that is called by the Workflow modeler whenever a WFL entity is created (eg. a Process, an Activity, a Relevant-Data, a Participant, etc...). Particularly, this user-exit sample gives the application designer an insight on how to set a customized id for the Workflow entities being created.

To do so, the use case goes through the following steps:

• Create a Process as the WFL entity which will be used to trigger the user-exit. This step is implemented in the file CAAVpiWFLUserExit.cpp which also includes the main program. 
• Implement the user-exit called "GetId" by performing the following steps:
• get the type of WFL entity being created. In our case it is WFProcess.
• construct an id. by concatenating the type "WFProcess" and the current date.
• Assign the constructed id. to the new Process.

The actual implementation of the user-exit is contained in the file CAAVpiWFLUserExit_GetId.cpp.

[Top]

How to Launch CAAVpiWFLUserExit

To launch CAAVpiWFLUserExit, you will need to set up the build-time environment, next compile CAAVpiWFLUserExit along with its prerequisites, then set up the run-time environment, and finally execute the use case [1].

Launch the use case as follows:

• With Windows

e:>CAAVpiWFLUserExit

• With UNIX

$ CAAVpiWFLUserExit

[Top]

Where to Find the CAAVpiWFLUserExit Code

The CAAVpiWFLUserExit use case is made of two source files named CAAVpiWFLUserExit.cpp and CAAVpiWFLUserExit_GetId.cpp, both located in the module CAAVpiWFLUserExit.m of the framework CAAVPMInterfaces.edu.

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

[Top]

Step-by-Step

There are six main steps in CAAVpiWFLUserExit code:

1. Prolog
2. Getting the WFL creation factory interface
3. Creating a Process
4. Implementing the User Exit
5. Getting the type of WFL entity being created
6. Constructing an Id and Passing it Back to the Modeler

We will now comment each of these sections in detail.

[Top]

Prolog

[Top]

Getting a WFL Factory Manager

...
  // Get a session
  VPMSession* session = VPMSession::OpenSession();
...
  // Get a factory manager from the session
  CATIVpmFactoryManager_var factoryMgr;
  session->GetVPMObjectFactory(factoryMgr);
...
  // Query an interface on VPMIWflCreation
  VPMIWflCreation_var creationItf(factoryMgr);
...

The Workflow creation interfaces provides functions for creating all exposed Workflow objects. Examples are Process, Activity, Participant, and Relevant-Data.

A session is needed to retrieve a smart pointer to the standard FactoryManager. An interface query on VPMIWflCreation is then performed to retrieve the specific WFL creation manager.

VPMIWflCreation

The Workflow creation interface

[Top]

Creating a Process

...
  // Create a Process
  VPMIWflProcess_var process;
  CATUnicodeString procName = CATUnicodeString("MyProcess"); 
  CATUnicodeString procDefName = procName;
  procDefName.Append("_Def");
  rc = creationItf -> CreateProcess( procDefName, procName, process);
...

A Process is created by specifying  its name, and the name of the Workflow definition which it stems from (Workflow template). However, like for any other Workflow object,  a Process has a unique id. which may be constructed automatically via the user-exit GetId . It is the creation function CreateProcess() which will attempt to create the user-exit object with late-type "EWFUE_GetId". In general, for a Workflow user-exit named XXX, the corresponding late-type must be called "EWFUE_XXX". Furthermore, this late-type must adhere to interface VPMIWflUserExit. An implementation of the user-exit for this late-type must then implement the method Run(CATListOfCATUnicodeString).

[Top]

Implementing the User Exit

As hinted above, to implement the user-exit, an implementation class must be defined for the latetype EWFUE_GetId.
This class must then adhere to the interface VPMIWflUserExit to implement the method Run().

...
//-----------------------------------------------------------------------------
// Implementation of CAAVpiWFLUserExit_GetId
//-----------------------------------------------------------------------------
CATImplementClass (CAAVpiWFLUserExit_GetId, DataExtension, CATBaseUnknown, EWFUE_GetId);
...
#include "TIE_VPMIWflUserExit.h"
TIEchain_VPMIWflUserExit (CAAVpiWFLUserExit_GetId);
// Implementation of method VPMIWflUserExit::Runt()
HRESULT  CAAVpiWFLUserExit_GetId::Run(CATListOfCATUnicodeString& ioList)
{ ...
  if (ioList[1]=="NEW")
  {
    ...

The method Run() takes one in-out parameter of a list of String. At the method call, the first element of the list specifies the reason why the user exit is called. In our case case, it must be "NEW" to make sure the user-exit code is being executed for creating a WFL object. 

...
  if (ioList[1]=="NEW")
  {
    // Get a session
    VPMSession* session = VPMSession::OpenSession();
    ...
    // Get a factory manager from the session
    CATIVpmFactoryManager_var factoryMgr;
    session->GetVPMObjectFactory(factoryMgr);

    // Query an interface on VPMIWflCreation
    VPMIWflCreation_var creationItf(factoryMgr);
    

...

[Top]

Constructing an Id and Passing it Back to the Modeler

Since the convention for ids is the concatenation of the object  type and the current date, the type of the WFL object being created is first retrieved from the parameter list. Indeed, the type name is the second element of the parameter list. In our scenario it should be "WFProcess". This name is used to initialize the id. to be constructed. A date is then computed and appended to the object type. Once the object name is constructed, it must be pushed in to the in-out list parameter as first element (after resetting the list). It is the method CreateProcess() which after the user-exit returns will set the returned id to the Process being created.

...
    // Initialize the id. with the object type being created 
    CATUnicodeString processId = ioList[2];

    // Get the current date and time and make it "readable"
    CATTime date = CATTime::GetCurrentLocalTime();
    CATUnicodeString strDate = date.ConvertToString("%c");
    CATUnicodeString strDay = strDate.SubString(8,2);
    if (strDay.SubString(0,1)==" ") strDay = "0"+strDay.SubString(1,1);

    // Concatenate the stringefied date to the action type
    processId = processId + "_" + strDate.SubString(4,3)+ strDay+ "-" +strDate.SubString(11,8)+ "-"+strDate.SubString(20,4);

    // Reset the ioList. The returned list must contain the constructed id that 
    // the WFL modeler will assign to the object being created
    ioList.RemoveAll();

    // Push the name into the list to be returned
    ioList.Append(processId);

[Top]

In Short

This use case demonstrates how the user-exit technique can be used in the Workflow modeler to implement customized behavior.
As an example, a user-exit for identifying Workflow objects at their creation is described.

[Top]

References

History

Copyright © 2003, Dassault Systèmes. All rights reserved.