Running a Business Interlink Object

This chapter discusses how to:

• Write a PeopleCode program to execute a Business Interlink object.

• View an example of a transaction PeopleCode template.

• View an example of a fully-coded transaction PeopleCode template.

• Name inputs and outputs with limitations.

Writing the PeopleCode Program to Execute a Business Interlink Object

This section shows how to run a Business Interlink object using PeopleCode.

See Enterprise PeopleTools 8.46 PeopleBook: PeopleCode Developer's Guide.

To run the Business Interlink object, you write a PeopleCode program that executes the Business Interlink object. The PeopleCode template contains the code that you can start with after you drag a Business Interlink definition into a PeopleCode page. The template generates the main structure of PeopleCode to instantiate your Business Interlink definition, creating a Business Interlink object, and then adding input values to, executing, and fetching output values from that Business Interlink object.

When you write a PeopleCode program, you fill in the PeopleCode template. (You could write the PeopleCode program from scratch, but it is easier to start with a template.) Filling in the PeopleCode template means writing a PeopleCode program that instantiates your Business Interlink definition into a Business Interlink object, and then executes the Business Interlink object. Once this has been done, the Business Interlink object is run whenever the PeopleCode program is executed. The PeopleCode program can be executed from an event or from an Application Engine Program, depending upon which you chose when you generated the PeopleCode template.

See Understanding How to Generate a PeopleCode Template.

To fill in the PeopleCode template, you can replace all references to <*> with references to PeopleCode variables or to Record Fields, and by inserting values for the input parameters:

• For Business Interlink object inputs, within the AddInputRow call, replace any references to <*> with a constant value, or a Record Field name, or a PeopleCode variable name.

• For Business Interlink object outputs, within the FetchNextRow call, replace any references to <*> with a Record Field name or a PeopleCode variable name.

• There may be default values for the input parameters in the PeopleCode template. Optionally, you can replace default values for the input parameters by typing in new constants, Record Fields, or PeopleCode variables.

The PeopleCode template consists of the following main sections:

• Configuration Parameter settings. If they have default values, you can type new values for them if you desire. Replace any <*> with a constant value, Record Field, or PeopleCode variable.

• GetInterlink method. This method instantiates your Business Interlink definition, creating a Business Interlink object that you can execute within PeopleCode.

• AddDoc, AddValue method. This section passes one set of input parameter values to the Business Interlink object. You can use several methods to pass inputs:

  • The supplied GetInputDocs, AddDoc, and AddValue methods pass a row of input to the object. Replace each <*> with a constant value, Record Field, or PeopleCode variable; these are the input values that you pass to the transaction. If the inputs have default values, you can type new values for them if you desire. The input is stored in an input buffer containing one or more sets of input parameter values for this transaction. If you pass only one set of input parameter values, the transaction is executed in real time. If you place the AddDoc and AddValue methods in a loop (including the AddNextDoc method to add the next set of input parameters) and call them many times to add many sets of input parameter values to the input buffer, the transaction is executed in batch mode. Queries have one input row, and are executed in real time.

  • If your data is mapped to a rowset, you can replace the GetInputDocs, AddDoc, and AddValue methods with the InputRowset method. The InputRowset method will take a standard rowset object to populate the input buffers.

  • If you’re sending a large amount of data to the input buffers, you might delete the supplied the GetInputDocs, AddDoc, and AddValue methods and write the data to a PeopleSoft record, then use the BulkExecute method. The BulkExecute method uses the data in the record to populate the input buffer, copying like-named fields. This method assumes that the names of the fields in the record match the names of the inputs defined in the Business Interlink definition.

• Execute method. This section executes the Business Interlink object. You can use several methods to execute:

  • The supplied Execute method executes the transaction. You call this method once, and it will execute once for each row of input you have in the input buffer. (Since queries do not have multiple rows of input, they are executed once.)

  • If you’re sending a large amount of data to the input buffers and you wrote the input data to a staging table, replace the Execute method with the BulkExecute method.

• GetOutputDocs, GetDoc, and GetValue methods. This section gets the outputs from the Business Interlink object. You can use several methods to get the outputs:

  • The supplied GetOutputDocs, GetDoc, and GetValue methods get one set of output parameter values. For a transaction that was executed in batch mode (more than one set of input parameter values entered), you will usually get one set of output for each set of input. Place the GetDoc and GetValue methods into a loop to do so, and include the GetNextDoc method to get the next set of output parameters. Replace each <*> with a Record Field or PeopleCode variable; these will be where the output values from the transaction is stored.

  • If you used the BulkExecute method, it can automatically fill the output record specified with the method with the output values if you’ve specified an output record.

  • If your data is hierarchical and you used the InputRowset method to take a standard rowset object to populate the input buffers, then replace the GetOutputDocs, GetDoc, and GetValue methods with the FetchIntoRowset method. The FetchIntoRowset method populates the rowset with data.

See Business Interlink Class Methods and Properties.

Viewing an Example of a Transaction PeopleCode Template

When you drag over the Business Interlink definition QE_COST, which is for the transaction Calculate Cost, you get the following PeopleCode. This Business Interlink definition is supplied with the Business Interlink software.

In addition to the template code and comments, this example includes some additional comments, marked with the text ADDITIONAL COMMENT.

/* ===>
This is a dynamically generated PeopleCode template to be used only as a helper?
 to the application developer. You need to replace all references to '<*>' OR default?
 values with references to PeopleCode variables and/or a Rec.Fields.*/
 
 
 
/* ===> Declare and instantiate: */
Local Interlink &QE_COST_1;
Local BIDocs &inDoc;
Local BIDocs &outDoc;
Local boolean &RSLT;
Local number  &EXECRSLT;
&QE_COST_1 =  GetInterlink(INTERLINK.QE_COST);
 
/* ===> You can use the following assignments to set the configuration parameters.
*/
 
/* ADDITIONAL COMMENT: The URL parameter points to the Business Interlink?
 runtime plug-in.*/
&QE_COST_1.URL = file://PScustomer.dll;
 
 
/* ===> You might want to call the following statement in a loop if you have?
 more than one row of data to be added. */
 
/* ADDITIONAL COMMENT: The AddValue calls use for its inputs the input names?
 in the Input Path column of the Input Tab for this Business Interlink Definition.
 
The AddValue calls also contain all of the default values that have been set?
 for the QE_COST Business Interlink Definition. You will likely replace?
 them with variables or record fields when you complete the coding for this?
 template. */
 
/* ===> Add inputs: */
&inDoc = &QE_COST_1.GetInputDocs("");
&FromDoc = &inDoc.AddDoc("From");
&ret = &FromDoc.AddValue("Country", <*>);
&ret = &FromDoc.AddValue("Postal_Code", <*>);
&ToDoc = &inDoc.AddDoc("To");
&ret = &ToDoc.AddValue("Country", <*>);
&ret = &ToDoc.AddValue("Address_Type", <*>);
&ret = &ToDoc.AddValue("Postal_Code", <*>);
&Package_InfoDoc = &inDoc.AddDoc("Package_Info");
&ret = &Package_InfoDoc.AddValue("Drop_off_Pickup", <*>);
&ret = &Package_InfoDoc.AddValue("Packaging", <*>);
&ret = &Package_InfoDoc.AddValue("Weight", <*>);
&ret = &Package_InfoDoc.AddValue("Length", <*>);
&ret = &Package_InfoDoc.AddValue("Width", <*>);
&ret = &Package_InfoDoc.AddValue("Height", <*>);
 
 
/* ===> The following statement executes this instance: */
&EXECRSLT = &QE_COST_1.Execute();
If ( &EXECRSLT <> 1 ) Then
   /* The instance failed to execute */
Else
/* ADDITIONAL COMMENT: The GetValue calls use for the outputs the output names?
 in the Output Path column of the Output Tab for this Business Interlink?
 Definition. */
&outDoc = &QE_COST_1.GetOutputDocs("");
&Service_RateDoc = &outDoc.GetDoc("Service_Rate");
&ret = &Service_RateDoc.GetValue("Service_Type", <*>);
&ret = &Service_RateDoc.GetValue("Guaranteed_By", <*>);
&ret = &Service_RateDoc.GetValue("Rate", <*>);
&ret = &outDoc.GetValue("return_status", <*>);
&ret = &outDoc.GetValue("return_status_msg", <*>);
 
End-If; /* If NOT &RSLT ... */

Viewing an Example of a Fully-Coded Transaction PeopleCode Template

The following code is an example of how the template for the Business Interlink definition QE_COST could be coded. This PeopleCode is an edited version of the PeopleCode contained within the QE_COST record, QE_COST_BUTTON field, FieldChange PeopleCode event.

This code executes the transaction named Calculate Cost(Domestic), which calculates the cost of shipping a package. It also execute the Tracking transaction, which tracks a package.

Following this code is an example of the inputs and outputs for these transactions, and then a short discussion of the records where this PeopleCode is used.

In addition to the code and comments in this PeopleCode event, this example includes comments pointing out the changes made to the template. These comments are marked with the text CHANGE.

/* ===> Declare and instantiate: */
Local Interlink &QE_COST_1;
Local boolean &RSLT;
Local number &EXECRSLT;
Local Record &REC;
Local number &count;
Local BIDocs &biDocs, &InputDocs;
Local BIDocs &ServiceRateDoc, &FromDoc, &ToDoc, &PackageDoc;
Local number &ret;
 
&QE_COST_1 = GetInterlink(Interlink.QE_COST);
 
/* ===> You can use the following assignments to set the configuration parameters.
*/
 
&QE_COST_1.URL = "file://PScustomer.dll";
 
GetLevel0()(1).GetRowset(Scroll.QE_COST_RES).Flush();
 
/* ===> You might want to call the following statement in a loop if you
have more than one row of data to be added. */
 
/* ===> Add inputs: */
/* CHANGE: The input values are set to fields within the QE_COST record,?
 rather than to default values. */
 
&REC = GetLevel0().GetRow(1).GetRecord(Record.QE_COST);
&COUNTRY_FROM = &REC.QE_ORIGIN_CNTRY.Value;
&FROM_POST_CODE = &REC.QE_FROM_POST_CODE.Value;
&COUNTRY_DEST = &REC.COUNTRY_DEST.Value;
&TO_POSTAL_CODE = &REC.QE_TO_POST_CODE.Value;
&DROP_OFF_PICKUP = &REC.QE_DROP_PICKUP.Value;
&PACKAGING = &REC.QE_PACKAGING.Value;
&WEIGHT = &REC.QE_WEIGHT.Value;
&LENGTH = &REC.QE_LENGTH.Value;
&WIDTH = &REC.QE_WIDTH.Value;
&HEIGHT = &REC.QE_HEIGHT.Value;
/* &DESTINATION = &REC.QE_TO_ZIP.Value; */
 
/* CHANGE: Evaluate several of the parameters */
/* Fix up the County From data */
Evaluate &COUNTRY_FROM
When = "USA" 
   &COUNTRY_FROM = "United States"
End-Evaluate;
 
/* Fix up the County dest data */
Evaluate &COUNTRY_DEST
When = "USA" 
   &COUNTRY_DEST = "United States"
When = "UK" 
   &COUNTRY_DEST = "United Kingdom"
When = "CAN" 
   &COUNTRY_DEST = "Canada"
End-Evaluate;
 
/* Evaluate the translates */
Evaluate &DROP_OFF_PICKUP
When = "A" 
   &DROP_OFF_PICKUP = "On Call Air";
When = "L" 
   &DROP_OFF_PICKUP = "Letter Center";
When = "O" 
   &DROP_OFF_PICKUP = "One Time Pickup";
When = "R" 
   &DROP_OFF_PICKUP = "Regular Daily Pickup";
End-Evaluate;
 
Evaluate &PACKAGING
When = "E" 
   &PACKAGING = "Express Box";
When = "L" 
   &PACKAGING = "Letter Envelope";
When = "T" 
   &PACKAGING = "Tube";
When = "Y" 
   &PACKAGING = "Your Packaging";
End-Evaluate;
 
 
/* New Hierarchical data buffer stuff */
 
/* CHANGE: The <*> in the AddValue methods are replaced with proper values. */
&InputDocs = &QE_COST_1.GetInputDocs("");
&FromDoc = &InputDocs.AddDoc("From");
&ret = &FromDoc.AddValue("Country", "United States");
&ret = &FromDoc.AddValue("Postal_Code", &FROM_POST_CODE);
 
&ToDoc = &InputDocs.AddDoc("To");
&ret = &ToDoc.AddValue("Country", &COUNTRY_DEST);
&ret = &ToDoc.AddValue("Postal_Code", &TO_POSTAL_CODE);
&ret = &ToDoc.AddValue("Address_Type", "Commercial");
 
&PackageDoc = &InputDocs.AddDoc("Package_Info");
&ret = &PackageDoc.AddValue("Drop_off_Pickup", &DROP_OFF_PICKUP);
&ret = &PackageDoc.AddValue("Packaging", &PACKAGING);
&ret = &PackageDoc.AddValue("Weight", &WEIGHT);
&ret = &PackageDoc.AddValue("Length", &LENGTH);
&ret = &PackageDoc.AddValue("Width", &WIDTH);
&ret = &PackageDoc.AddValue("Height", &HEIGHT);
 
/* ===> The following statement executes this instance: */
&EXECRSLT = &QE_COST_1.Execute();
If (&EXECRSLT <> 1) Then
   /* The instance failed to execute */
Else
   
   /* ===> Fetch Outputs: */
/* CHANGE: The <*> in the AddValue methods are replaced with proper values. */
   &RSLT = True;
   &ROWSET = GetRowset(Record.QE_COST_RES);
   &I = 1;
   &biDocs = &QE_COST_1.GetOutputDocs("");
/* CHANGE: Because Service_Rate is a list, you must get its values using a loop.?
 GetCount gets the number of Service_Rate output parameters. */
/* Possible fix: the following line may need to be added here:
   &ServiceRateDoc = &biDocs.GetDoc("Service_Rate"); */
 
/* Possible fix: the following line may need to be commented out */
   &count = &biDocs.GetCount("Service_Rate");
   While (&I < &count)
      &ServiceRateDoc = &biDocs.GetDoc("Service_Rate");
      &ret = &ServiceRateDoc.GetValue("Service_Type", &SERVICE_TYPE);
      &ret = &ServiceRateDoc.GetValue("Guaranteed_By", &GUAR_BY);
      &ret = &ServiceRateDoc.GetValue("Rate", &RATE);
      If &ret = 0 Then
         If &I > 1 Then
            &ROWSET.InsertRow(&I - 1);
         End-If;
         UpdateValue(QE_COST_RES.QE_SVC_TYPE, &I, &SERVICE_TYPE);
         UpdateValue(QE_COST_RES.QE_GUAR_BY, &I, &GUAR_BY);
         UpdateValue(QE_COST_RES.QE_RATE, &I, &RATE);
         &I = &I + 1;
/* Possible fix: the following line may need to be added here:
         &ret = &ServiceRateDoc.GetNextDoc(); */
      End-If;
   End-While;
End-If; /* If NOT &RSLT ... */

Examples of the Inputs and Outputs for the Transactions

The following example shows the structure of the inputs for the Calculate Cost transaction.

Inputs for the Calculate Cost(Domestic) transaction

The following example shows the structure of the outputs for the Calculate Cost transaction.

Outputs for the Calculate Cost(Domestic) transaction

Naming Inputs and Outputs With Limitations

Within the PeopleCode program using Business Interlinks, the input and output for a BIDocs object should not have the same name. This situation can arise when using the BI PeopleCode auto generation feature, or if you name the input and output BIDocs with the same name. If the BI definition has a BIDoc with the same name in both the Inputs and Outputs sections, when you drag and drop to generate the PeopleCode, the code template that is generated will have BIDocs with the same name in both the Input and Output sections.

In the following example, the following Business Interlink definition, LogOn, has an input and output with the same name: cXML.

Business Interlink Definition: inputs and outputs with the same name

When you drag and drop this Business Interlink definition to create a PeopleCode template, you get the following code:

/* ===> Add inputs: */
&inDoc = &QE_PSQA_IMPRE_1.GetInputDocs("");
&cXMLDoc = &inDoc.AddDoc("cXML");
&ret = &cXMLDoc.AddValue("version", <*>);
 
&outDoc = &QE_PSQA_IMPRE_1.GetOutputDocs("");
&cXMLDoc = &outDoc.GetDoc("cXML");
&ret = &cXMLDoc.GetValue("version", <*>);

This code contains docs with the same name in the input and output sections. This PeopleCode will not run properly.

To fix the problem, you can rename the input doc or the output doc so that they have different names. For example:

/* ===> Add inputs: */
&inDoc = &QE_PSQA_IMPRE_1.GetInputDocs("");
&cXMLInDoc = &inDoc.AddDoc("cXML");
&ret = &cXMLInDoc.AddValue("version", <*>);
 
&outDoc = &QE_PSQA_IMPRE_1.GetOutputDocs("");
&cXMLOutDoc = &outDoc.GetDoc("cXML");
&ret = &cXMLOutDoc.GetValue("version", <*>);