Converting templates

Process Designer Express provides the following conversion functionality:

Importing files

Process Designer Express can import BPEL and UML (in XMI 1.1) files for use in a collaboration template. Use the information in these files to create a new template definition.

Perform the following tasks to create a new collaboration template based on existing BPEL or UML (in XMI 1.1) files:

  1. Ensure Process Designer Express is open.
  2. Click File --> Import. The Process Designer Express Importer opens.
  3. Select the file type you want to import, and then click Next.
  4. Select the location of the BPEL or UML source file or files.
  5. Select the file or files you want to import.
    Note:
    If you are planning to use BPEL files, you must import all three of the.bpel,.wsdl, and.bpelGUI.xml files. Use the Ctrl key to select all three files for import.
  6. Click Next to begin the import process. After the import is complete, the New Template dialog box opens.
  7. Select the name of the user project the template belongs to in the Project field.
  8. Type the name of the template you are creating in the Template Name field. A template name can include alphabetic characters, numbers, and underscores.
  9. Click OK. Process Designer Express creates the new collaboration template and populates it with all of the information contained in the source BPEL or UML files.

Exporting a collaboration template

You can export your collaboration template into BPEL or UML (in XMI 1.1) format for use in other applications. When a InterChange Server Express collaboration template is exported to BPEL format, the following files are created:

When a collaboration template is exported to UML (in XMI 1.1), a *.xmi file is created.

Perform the following steps to export an InterChange Server Express collaboration template:

  1. Ensure that Process Designer Express is open and that your collaboration template has been saved and has compiled without error.
  2. Click File --> Export. The Process Designer Express Exporter opens.
  3. Select the format to which you want to export your template, and then click Next.
  4. Select the location in which you want to save the exported template file or files.
  5. In the File Name field, specify the name for the exported template file. If you are exporting to BPEL, do not specify a file extension in the File Name field.
  6. Click Next to begin the export process. The Process Designer Express Exporter dialog shows the progress of the conversion.
  7. Click Close when the export process has finished.

Updating templates from previous releases

If you have a collaboration template from a previous release, you can use it with the latest version of InterChange Server Express. The process for importing and updating these templates varies depending on whether the old template is stored in InterChange Server Express or on a local file system.

If your existing template is stored in InterChange Server Express, use System Manager to import it into a project as follows:

  1. Ensure System Manager is open and is connected to InterChange Server Express, where the old template is stored.
  2. Locate the appropriate project folder in the Integration Component Library and right-click it.
  3. From the project folder's context menu, click Import components from server --> Collaboration templates. The Import Components dialog box is displayed.
  4. Select the collaboration template you want to import, and then click Finish.

The template is automatically updated for use with the latest version of Integration Server Express. After the template has been imported and updated, you can use Process Designer Express to edit it as needed.

If you want to use an existing collaboration template that is not stored in InterChange Server Express, you must open it in Process Designer Express with the File --> Open --> From file command. If the template is not compatible with the latest version of InterChange Server Express, Process Designer Express prompts you to update it. Confirm the update; Process Designer Express converts the existing template into a usable format.

After the conversion completes, it is good practice to visually inspect the new activity diagram for correctness. When you are satisfied with the template, save it to keep the changes.

Considerations when modifying templates.

Collaborations may require changes over time as businesses grow and change. Some of the changes will be to the Java(TM) code and others will be to the template definition itself.

You can change the Java code that supports a collaboration without adversely affecting existing collaborations; they will use the changed code on the next instantiation of the collaboration.

If you change the definition of a template, you must recreate any collaboration objects based on the template. The changes that require the collaboration object include (but are not limited to):

When you recreate the collaboration object, compile and test it as described in Testing a collaboration.

Special considerations for collaborations that use the SEND_EMAIL and INFORMATIONAL_EXCEPTIONS properties

Many collaboration templates based on the CollaborationFoundation template or BaseCollaboration template contain the SEND_EMAIL and INFORMATIONAL_EXCEPTIONS configuration properties (typically in the action nodes under the Main scenario). These properties determine how a collaboration handles exceptions; values can include specific exception message numbers.

In previous releases, the following code was used to obtain exception messages and parse them for the message number:

//Get exception message
sMessage=currentException.getMessage();

//Get exception type
sExceptionType=currentException.getType();

//Determine whether to send email. If SEND_EMAIL is set to none,
//then never send email. If SEND_EMAIL is set to all, then always
//send email. Else, make sure the message number is included in 
//the comma-delimited list of SEND_EMAIL values.

StringTokenizer emailtoken=new StringTokenizer(sSendEmail, ",");
bBranch=false;

if (sSendEmail.trim().toLowerCase().equals("all"))
   {
     bBranch=true;
   }
else while (emailtoken.hasMoreTokens())
   {
     sToken=emailtoken.nextToken();
     sToken=sToken.trim().toLowerCase();
     sToken="Error"+sToken;
     if (sMessage.lastIndexOf(sToken)>-1)
       {
         bBranch=true;
         break;
       }
   }   

The getMsgNumber() method has been added to the CollaborationExceptions class; it returns exception message numbers that are in turn used by the SEND_EMAIL and INFORMATIONAL_EXCEPTIONS properties in determining how an exception is handled. As a result, it can be necessary to manually update code in an existing collaboration template to take advantage of the getMsgNumber() method.

Determine whether the template you are converting contains the SEND_EMAIL or INFORMATIONAL_EXCEPTIONS configuration properties. If the template contains one or both of these properties, do the following:

  1. Evaluate each scenario that contains SEND_EMAIL or INFORMATIONAL_EXCEPTIONS to identify any customized code (code other than that provided in the collaboration templates shipped with the product) in the action nodes. If the scenario does not contain any customized code, continue with Step 2.

    If the scenario contains customized code to evaluate an exception message string for a message number, remove that code and then continue with Step 2.

  2. Add the following code to any action node that returns exception messages and parses for exception message numbers:
    //Get Exception Number
    iMessageNum=currentException.getMsgNumber();
    sMessageNum=String.valueOf(iMessageNum);
  3. In the same action node, replace the existing while loop that returns the message number by parsing for the string Error with new code, as follows:
    Existing code to replace

    else while (emailtoken.hasMoreTokens())
       {
         sToken=emailtoken.nextToken();
         sToken=sToken.trim().toLowerCase();
         sToken="Error"+sToken;
         if (sMessage.lastIndexOf(sToken)>-1)
           {
             bBranch=true;
             break;
           }
       }
    New code

    else while (emailtoken.hasMoreTokens())
       {
         sToken=emailtoken.nextToken();
         sToken=sToken.trim().toLowerCase();
         
         if (sToken.equals(sMessageNum))
           {
             bBranch=true;
             break;
           }
       }
  4. If the action node uses SEND_EMAIL to determine collaboration exception handling, add the following code to support the ability to specify a range of exception message numbers. This code is nested inside the while loop you modified in Step 3; the example below shows the whole while loop so you can locate the insertion point for the new code.
    else while (emailtoken.hasMoreTokens())
       {
         sToken = emailtoken.nextToken();
         sToken = sToken.trim().toLowerCase();
    
         trace (3,"***** Current sToken value is: "+sToken);
    
         String sSeparator="-";
    
         if (sToken.lastIndexOf(sSeparator)>-1)
           {
             int pos = sToken.indexOf(sSeparator);
             
             sLowerRange = sToken.subtring(0,pos);
             sLowerRange = sLowerRange.trim();
             iTemp = new Integer(sLowerRange);
             iLowerRange = (((Integer)iTemp).intValue());
    
             sUpperRange = sToken.substring(pos+1,sToken.length());
             sUpperRange = sUpperRange.trim();
             iTemp = new Integer(sUpperRange);
             iUpperRange = (((Integer)iTemp).intValue());
    
             trace(3," ***** iLowerRange value is -" +iLowerRange 
                   +" *****iUpperRange value is -" 
                   +iUpperRange +" *****");
    
             if ((iMessageNum>=iLowerRange) && (iMessageNum<=iUpperRange))
               {
                 bBranch = true;
                 trace(3," ***** The current exception falls within 
                       this range *****");
                 break;
               }
         }
         else
           {
            if (sToken.equals(sMessageNum))
              {
                bBranch=true;
                break;
              }
           }
       }
  5. For each scenario that contains the SEND_EMAIL or INFORMATION_EXCEPTIONS properties, add the following scenario variables in the Scenario Definitions dialog box. For more information on adding scenario variables, see Defining scenario variables.
    Table 33. Scenario variables to add during template conversion
    Variable type Variable name Initial value
    String sMessageNum null
    String sLowerRange null
    String sUpperRange null
    int iMessageNum 0
    int iLowerRange 0
    int iUpperRange 0
  6. Recompile your template and test it to ensure the changes are correct. See Compiling a collaboration template and Testing a collaboration for more information on these tasks.

Copyright IBM Corp. 2004, 2005