More on using submaps

This section provides the following tips on the use of submaps:

For an introductions to submaps, see "Transforming with a submap".

Providing conditions when calling the submap

Often the map requires some programming logic to determine when to call a submap. Sometimes you might have certain conditions that must be true for the submap to be called. This logic goes into the main map, in the attribute that contains the submap's destination business object, and before the call to the runMap() method. If you enter these conditions in the Conditions area of the Submap dialog (see Figure 21), Map Designer adds these conditions to the if statement with which it surrounds the runMap() call.

Guidelines: Keep the following points in mind when entering these conditions:

Example: In the business objects shown in Figure 20 the OrderLine business object has an attribute called DelSched, which is a child business object. In a submap condition, you can refer to that attribute as follows:

srcBusObj

Enter the following submap condition in the Conditions area of the Submap dialog to execute a submap on the DelSched business object only if the value of the TransportType attribute of the same business object is equal to the string AIR.

srcBusObj.getString("TransportType").equals("AIR")

The following condition executes the submap for OrderLine DelSched attributes only if the OrderLine LinePrice attribute value is greater than $10,000.00.

ObjOrderLine.getFloat["LinePrice") > 10000.00

Example: Conditions are needed for the following map because the mapping should occur only if SAP_CustPartnerFunctions.PartnerId is not equal to SAP_CustomerMaster.CustomerId:

SAP_CustomerMaster.SAP_CustSalesAreaData.SAP_
CustPartnerFunctions[n]

to

Customer.RelatedCustomerRef

The following sections take you through the steps in creating the map call:

Steps for creating the submap

To create the Sub_SaCwCustCreditAreaData submap, perform the following steps from within Map Designer:

  1. Close the main map and start a new submap.

    Specify a source business object of SAP_CustPartnerFunctions and a destination business object of RelatedCustomerRef. Name the map as Sub_SaCwCustPartners.

  2. Set the verb as described in "Setting the destination business object verb".
  3. Map individual attributes as described in "Specifying standard attribute transformations" and "More attribute transformation methods".
  4. Compile the submap by selecting Compile from the File menu. If everything is correct, the following message displays:
    Map validation OK.
    Native Map: Code generation succeeded.
    

Steps for calling the submap

To call the Sub_SaCwCustCreditAreaData submap, perform the following steps from within Map Designer:

  1. Go back to the main map and, in the Diagram tab, hold the Ctrl key and drag SAP_CustPartnerFunctions onto RelatedCustomerRef. Double-click Submap from the list in the Rule column of the destination business object. Select the SaCwCustPartners map in the Submap dialog and click OK.

    In the case of a simple condition, you can type it into the Condition area for Submap dialog window:

    srcBusObj.getString("PartnerId").equals("some_id")
    

    Map Designer generates the code for the submap call with the condition added to the if statement that precedes the submap call.

    If you leave the Condition field blank and click OK, Map Designer generates the code for the submap call without the condition. Continue to step 2 for information on how to explicitly add the code.

  2. Modify the generated code to add the submap condition.

    To access Activity Editor, double-click the Rule column again and click the View Code push-button of the Submap dialog.

    For the RelatedCustomerRef attribute, the code that includes the condition follows:

    {
          BusObjArray srcBusObjs = null;
          srcBusObjs =
    ObjSAP_CustomerMaster.getBusObjArray
    ("SAP_CustSalesAreaData.SAP_CustPartnerFunctions");
      String parent_custid = ObjSAP_CustomerMaster.getString("CustomerId");
      //
      // LOOP ONLY ON NON-EMPTY ARRAYS
          // -----------------------------
          //
          // Perform the loop only if the source array is non-empty.
          //
          if ((srcBusObjs != null) && (srcBusObjs.size() > 0))
      {
        int srcIndex;
                int lastSrcIndex = srcBusObjs.getLastIndex();
                for (srcIndex = 0; srcIndex <= lastSrcIndex; srcIndex++)
        {
          BusObj srcBusObjInstance = (BusObj)
    (srcBusObjs.elementAt(srcIndex));
          //
          // INVOKE MAP ON VALID OBJECTS
                      // ---------------------------
          //
                      // Invoke the map only on those children objects 
                      // that meet certain criteria.
                      //
          if ((srcBusObjInstance != null))
          {
          // check the submap running condition
          if 
      (!(srcBusObjInstance.getString("PartnerId")).equals(parent_custid))
          {
             // set the verb of the source business object of submap
    srcBusObjInstance.setVerb(ObjSAP_CustomerMaster.getVerb());
             try
             {
               BusObj[] _cw_inObjs = { srcBusObjInstance };
                                       BusObj[] _cw_outObjs =
    DtpMapService.runMap("Sub_SaCwCustPartners", 
    "CwMap", _cw_inObjs,cwExecCtx);
    

    ObjCustomer.setWithCreate("RelatedCustomerRef", _cw_outObjs[0]);
             }
             catch(MapNotFoundException me) 
                                 {
                                     logError(5502, "Sub_SaCwCustPartners");
             throw new MapFailureException("Submap not found");
             }
           }
         }
               } 
     }
    }
    
  3. Once you have added the call to the submap, recompile the main map.

Using Expression Builder to call a submap

You can use Map Designer to automatically generate a submap call through the Submap dialog. However, you can also use Expression Builder to generate the submap call. Coding the map call allows you to write more varied operations than Map Designer supports graphically. For example, you can use a submap to provide a value for an attribute that does not contain a child business object or use a submap that has multiple inputs and outputs.

Steps for using Expression Builder to call a submap

Perform the following steps to use Expression Builder to generate a submap call:

  1. Double-click the transformation rule in either the Table or Diagram tab to display Activity Editor in Java view.
  2. Right-click anywhere in Activity Editor, then select Expression Builder from the Context menu.
  3. In Expression Builder:



    Figure 95. Coding a submap call

    Result: Map Designer generates the Java code necessary to call the map you specify as a submap. It displays in the code area at the top of the Expression Builder window.

  4. In the generated code, replace the input and output object place holders with the actual current source and destination business object names for the submap, and write code to handle the value that the submap returns.

    Replace the placeholders InObj, , OutObj, and OutAttrName with the correct names for the following:

  5. Click OK to close Expression Builder.

    Result: The code is inserted into Activity Editor at the insertion point.

Passing business objects of different types to submaps

To map source business objects of different types to a destination business object, you need to create a many-to-one submap.

Example: This kind of mapping would be needed for the following map:

SAP_CustCreditControlAreaData[n] 
 
to
Customer.CustomerInformation.CustomerCreditData[0].
CreditAreaCreditData[n]

Some of the attributes must be mapped from SAP_CustomerMaster and SAP_CustCreditCentralData.

Transforming multiple source business objects of different types involves the following major steps:

  1. Steps for creating the many-to-one submap--create a many-to-one submap, which transforms the needed attributes in the multiple source business objects to those in the single destination business object.
  2. Steps for calling the many-to-one submap--Call this submap from the main map, in the attribute that holds the submap's destination business object.

Steps for creating the many-to-one submap

To create a submap that maps source child business objects of different types to one destination child object, you create a map with the many source business objects and the single destination business object. This map contains the transformations for attributes in the different source object to the corresponding attributes in the destination object.

To create a many-to-one submap, perform the following steps from within Map Designer:

  1. Close the main map and start a new map. The new map will have at least two source objects and one destination object.

    Drag SAP_CustCreditControlAreaData, SAP_CustCreditCentralData, and SAP_CustomerMaster business objects into the left half of the mapping screen, and CreditAreaCreditData into the right half. The new map will have three source objects and one destination object.

  2. Save the submap.

    Recommendation: Submap names should begin with the prefix "Sub_". For example: Sub_SaCwCustCreditAreaData.

  3. Set the verb of the destination object as described in "Setting the destination business object verb".

    Unless the relationship management is performed in this submap, it does not matter which source object is used to set the verb. Ensure that when you call this submap, you set the verb for the same particular object before passing it into the submap. If one of the source objects is the source parent object and you choose to use its verb, you do not need to set the verb before passing this object into the submap; it already has a verb associated with it.

  4. Map individual attributes as described in "Specifying standard attribute transformations" and "More attribute transformation methods".
  5. Compile the submap by selecting Compile from the File menu.

    Result: If everything is correct, the following message displays:

    Map validation OK.
    Native Map: Code generation
     succeeded.
    

Steps for calling the many-to-one submap

To invoke the many-to-one submap, call it with the runMap() method from the main map, in the attribute that holds the submap's destination business object. To invoke the Sub_SaCwCustCreditAreaData submap, perform the following steps from within Map Designer:

  1. Open the main map.

    For the Sub_SaCwCustCreditAreaData submap, the main map is the map that contains the CreditAreaCreditData business object as an attribute.

  2. Double-click in the Transformation Rule column for the submap's destination object to open Activity Editor.

    Double-click the Transformation Rule column associated with the CreditAreaCreditData attribute to open its Activity Editor and enter the following code:

    {
    BusObj srcobj1 = ObjSAP_CustomerMaster;
    BusObj srcobj2 = (BusObj)
       (ObjSAP_CustomerMaster.getBusObj("SAP_CustCreditCentralData"));
    BusObjArray srcobj3 =
       (BusObjArray)(ObjSAP_CustomerMaster.get(
          "SAP_CustCreditControlAreaData"));
     
    //
    // INVOKE MAP ON VALID OBJECTS
    // ---------------------------
    //
    // Invoke the map only on those child objects that meet certain
    // criteria.
    //
    int i = 0;
     
    // When checking all 3 source objects, != null might be not required
    if (srcobj1 != null && srcobj2 != null & srcobj3 != null)
       {
       for (i = 0; i < srcobj3.size(); i++) 
          {
          BusObj[] _cw_inObjs = new BusObj[3];
     
          // set verb for the one of the following objects
          _cw_inObjs[0] = srcobj1;
          _cw_inObjs[1]= srcobj2;
          _cw_inObjs[2] = srcobj3.elementAt(i);
     
          try 
             {
             BusObj[] _cw_outObjs = DtpMapService.runMap(
                "Sub_SaCwCustCreditAreaData",
                "CwMap", 
                _cw_inObjs, 
                cwExecCtx);
             ObjCustomer.setWithCreate(
    "CustomerInformation.CustomerCreditData[0].CreditAreaCreditData[" 
                + i + "]", _cw_outObjs[0]);
             }
     
          catch (MapNotFoundException me) 
             {
             logError(5502, "Sub_SaCwCustCreditAreaData");
             throw new MapFailureException ("Submap not found");
             }
          }
       }
    }
    
  3. To track the map execution, use the logInfo() method inside the for loop. The code follows.
    logInfo("in for loop");
    

    or

    trace("in for loop");
    
  4. Once you have added the call to the submap, recompile the main map.

If everything is working properly and none of your source objects is null, the message in for loop displays in the InterChange Server log file as many times as there are instances of the source child object.

Copyright IBM Corp. 1997, 2004