Call Web Services from Order Management Extensions

Use an order management extension to get data from a source that resides outside of Order Management before you do default logic or validation logic.

Use ServiceInvoker in your extension code to call a web service and get the data. ServiceInvoker is available from the context object. You use the ExecutionContext method.

You will create an example extension that:

• Allocates sales credits to a salesperson for order lines that include an item that satisfies a condition.

• References the purchase order number and item number when it calls a web service so it can get the name of the salesperson and the percent sales credit to allocate.

• Extracts the salesperson name and percent allocation from the web service response, then creates a new row in the sales credit row set that it gets from the order line.

Summary of the Steps

1. Register the web service.

2. Call the web service.

3. Determine item of interest.

This topic uses example values. You might need different values, depending on your business requirements.

Register the Web Service

1. Go to the Manage Connector Details page, then set the value.

   Attribute	Value
   Invocation Mode	Synchronous Service You must use Synchronous Service with an order management extension.

   For details, see Manage Connector Details Between Order Management and Your Fulfillment System.

2. Go to the Manage Order Management Extensions page and create a new extension.

3. Set up the call.

   Code	Description
   def lines = header.getAttribute("Lines");	Get the row set for the order lines.
   while( lines.hasNext() )	Determine whether more lines exist that we must process.
   def line = lines.next(); def itemNumber = line.getAttribute("ProductNumber");	Get the item number that the line specifies.
   if( itemOfInterest(itemNumber) )	Determine whether the item number satisfies a condition.
   allocateSalesCredits(line);	Call the method that allocates sales credits for this line.

Call the Web Service

Add code that calls the web service so it can get the sales credit allocation.

Code	Description
void allocateSalesCredits(def line, String itemNumber) { def serviceInvoker = context.getServiceInvoker();	Get the handle that you use to call the web service.
def poNumber = header.getAttribute("CustomerPONumber");	Get the value of attribute Purchase Order Number for the customer from the order header.
String payLoad = "<ns1:GetSalesCreditAllocation xmlns:ns1=\"http://www.your_company.com/SalesCreditWS/\">" + "<ns1:poNumber>" + poNumber + "</ns1:poNumber>" + "<ns1:itemNumber>" + itemNumber + "</ns1:itemNumber>" + "</ns1:GetSalesCreditAllocation>";	Concatenate the strings so you can prepare the payload. As an option, you can also use an XML API to concatenate the string.
def responseBody = serviceInvoker.invokeSoapService("SalesCreditAllocationService", payLoad).getSoapBody();	Use the interface name of the web service and the request payload to call the web service. You must specify the interface name in the Connector Name attribute on the Manage External Interface Web Service Details page. For this example, you specify SalesCreditAllocationService as the connector name. Caution: You must not register a connector that references an Oracle internal web service. For more, see Connect Order Management to Your Fulfillment System.
def salesPerson = //;	Extract the salesperson name from the response payload.
def percent = //	Extract the percent allocation from the response payload.
def salesCredits = line.getAttribute("SalesCredits");	Get the row set for the sales credit from the current line.
def salesCredit = salesCredits.createRow();	Create a sales credit row.
sc.setAttribute("Salesperson", salesPerson);	Set the value for the salesperson attribute.
sc.setAttribute("Percent", new BigDecimal(percent));	Set the value for the percent allocation attribute.
sc.setAttribute("SalesCreditTypeCode", 1L);	Set the sales credit type. In this example, assume that 1 equals Revenue credits.
salesCredits.insertRow(salesCredit); }	Insert the new row in the row set.

The code uses parameters.

• param line. Line where we will allocate the sales credit.

• param itemNumber. Number of the item that you specify on the line.

Determine Item of Interest

Add code that returns a boolean value to indicate whether we are interested in the item that the web service sent.

Code	Description
boolean itemOfInterest(String itemNumber) {	For brevity, this example doesn't include details about how to implement this method. The logic you use is specific to your business requirement.
if condition return true; else return false }	condition is code you write. It decides whether the item number is of interest.

Entire Code

Here's the code for this example.

//get the lines row set. 
def lines = header.getAttribute("Lines");                                     

//if more lines exist.
while( lines.hasNext() ) {                                                     

  def line = lines.next();                                                     
                               
//then get the item number that the line specifies.
  def itemNumber = line.getAttribute("ProductNumber");                         
   
//determine whether the item number satisfies the condition.
  if( itemOfInterest(itemNumber) ) {                                           

//call method to allocate sales credits for this line.
    allocateSalesCredits(line);                                                                           
  } 
} 
   
/** 
 * Call a web service that gets sales credit allocation for the order line.
 * @param line identifies the line where you allocate sales credit.
 * @param itemNumber is the number of the item that the line specifies.
 */ 
void allocateSalesCredits(def line, String itemNumber) { 

//get a handle for the method that calls the web service.
  def serviceInvoker = context.getServiceInvoker();                           
   
//get the customer attribute for the purchase order number from the order header.
  def poNumber = header.getAttribute("CustomerPONumber");                     
   
String payLoad = "<ns1:GetSalesCreditAllocation 

//concatenate the strings to prepare the payload. 
xmlns:ns1=\"http://your.address/SalesCreditWS/\">" +        
//As an alternative, you can also use this code: 
  "<ns1:poNumber>" + poNumber + "</ns1:poNumber>" +         
  //XML APIs 
  "<ns1:itemNumber>" + itemNumber + "</ns1:itemNumber>" + 
  "</ns1:GetSalesCreditAllocation>"; 
   
  def responseBody = 

//use the web service name and the constructed payload to call the service.
serviceInvoker.invokeSoapService("SalesCreditAllocationService", 
payLoad).getSoapBody(); 
   
//get the salesperson name from the web service response.
  def salesPerson = //;                                                       

//get the percent allocation from the service response.
  def percent = //                                                             
   
//get the row set for the sales credit for the current line.
  def salesCredits = line.getAttribute("SalesCredits");                       

//create a new row for the sales credit.
  def salesCredit = salesCredits.createRow();                                 

//set the salesperson attribute.
  sc.setAttribute("Salesperson", salesPerson);                                 

//set the percent allocation attribute.
  sc.setAttribute("Percent", new BigDecimal(percent));                         

//set the sales credit type. This code assumes your implementation uses the value 1 for revenue credits.
  sc.setAttribute("SalesCreditTypeCode", 1L);                                 

//set a unique identifier in case more than one SalesCredit exists. For example, 5768342869.         
  salesperson.setAttribute("SourceTransactionSalesCreditIdentifier',5768342869);                     

//insert the new row in the rowset.
  salesCredits.insertRow(salesCredit);       

} 
  
/** 
 *Return a boolean that indicates whether the item is of interest. 
 */ 
boolean itemOfInterest(String itemNumber) { 

//For brevity, and to keep focus on calling the web service, 
//this example does not include details about how to implement this method. 
//The logic you use is specific to your business process.
  
//Decide whether the item number is of interest. Pseudocode:
  // if (some condition) 
        return true; 
  // else 
  //    return false 
} 

Here's the same code without comments.

def lines = header.getAttribute("Lines");                                     

while( lines.hasNext() ) {                                                     
  def line = lines.next();                                              
  def itemNumber = line.getAttribute("ProductNumber");                         
   
  if( itemOfInterest(itemNumber) ) {                                           
    allocateSalesCredits(line);                                        
  } 
} 
void allocateSalesCredits(def line, String itemNumber) { 
  def serviceInvoker = context.getServiceInvoker();                           
  def poNumber = header.getAttribute("CustomerPONumber");                     
   
String payLoad = "<ns1:GetSalesCreditAllocation 

xmlns:ns1=\"http://your.address/SalesCreditWS/\">" +        

serviceInvoker.invokeSoapService("SalesCreditAllocationService", 
payLoad).getSoapBody(); 
  def salesPerson = //;                                                       
  def percent = //                                                             
  def salesCredits = line.getAttribute("SalesCredits");                       
  def salesCredit = salesCredits.createRow();                                 
  sc.setAttribute("Salesperson", salesPerson);                                 
  sc.setAttribute("Percent", new BigDecimal(percent));                         
  sc.setAttribute("SalesCreditTypeCode", 1L);                                 
  salesperson.setAttribute("SourceTransactionSalesCreditIdentifier',5768342869);
  salesCredits.insertRow(salesCredit);       

} 
boolean itemOfInterest(String itemNumber) { 

//implement this method.
  
//Decide whether the item number is of interest. Pseudocode:
  // if (some condition) 
       return true; 
  // else 
  //   return false 
}