Return Data External Object

Beginning with the May 2013 update of m-Power, developers will have access to a Return Data Java external object for use within maintenance applications. This object takes in 1 parameter to find a row within a retrieval, and then returns that value(s) to your maintainer. A common example of using this is within the Email Upload template, where you might use the sender's email address to look up what customer information they are associated with and store that value(s) in the email table for future reference. This object is also very easy to configure and can be used with any existing maintenance application.

1. First, create a lookup retrieval for use with this object. In this case, we are going to submit an email address, and return a customer number and a customer name. Therefore, our retrieval has at least these three fields. For the purposes of this document, the lookup retrieval will be MRCWORKLIB.I00010s.
2. Next, we need to register the actual object before we can use it in our application. To do so, navigate to "Admin Menu" -> "Custom Code" -> "External Objects" -> "Create New Object." Give your object a name and description, and make sure that Java Method is selected for Object Type. Within class name, type:
   
   com.mrc.ext.MrcReturnData("MRCWORKLIB.I00010s", *REQ)
   
   Note: Be sure to substitute your lookup retrieval above.
   
   Also, set the method name to:
   
   get(pValue, pName, pName1)
   
   Once done, your screen should look similar to the screenshot below:
   
   
   
    
3. After clicking Accept, you will be brought to the Manage External Objects screen. Now, you can add the needed parameters by clicking the Parms button.
4. The first parameter must be the field you are using to lookup the proper record. You may make the description whatever value you would like, however the name must be the name of the field within your lookup retrieval. In our example, the field name is EMAIL so that is what we will use here. Set the length and decimal appropriately, and set Required Field to Yes.
   
   
   
    
5. The rest of the parameters are the fields you will be returning. Again, the description is not important, while the name must be the name of the field from the lookup retrieval. In our example, we will be returning fields CUSNO and CNAME.
   
   
   
    
6. Now that our object has been registered, we will add it to our maintenance application. To do so, navigate to Maintenance and click the Edit button next to your maintainer you wish to use. Once the application menu is open, click the External Object button.
7. Select your object from the dropdown, and select a proper location such as *BEFOREACT, which will run this object before any action has taken place so that the fields are updated properly. Finally, map the fields properly here (EMAIL to EMAIL, CUSNO to CUSNO, CNAME to CNAME). Note: If you do not see your field in the parameter dropdown, you have set the length and/or decimal incorrectly. You must fix this before proceeding.
8. Once done, click Accept, and compile/recompile. Note: It is not necessary to overwrite anything when only adding/modifying an external object.

This object will now use the value of the email field to lookup the associated customer number and name at runtime, with no additional intervention needed by the developers. This object can be reused as many times as needed.