Using Open Interface REST Services

Overview

Similar to concurrent program REST services, open interface tables and views can now be deployed as REST services. This allows you to leverage the deployed open interface REST services to update or import data directly into Oracle E-Business Suite base tables or make the base table data available for selection.

Note: Open interface tables and views can be available as REST services only. The custom open interfaces are not supported in this release.

To locate an open interface table or view, in the Search page, select "Open Interface" or "Interface View" as the interface type and enter additional search criteria if desired to retrieve your desired interface. An integration administrator can then deploy it as a REST service with supported HTTP methods.

Service Invocation Examples

To better understand how to use open interface REST services to modify Oracle E-Business Suite base tables, this chapter includes examples of using HTTP methods to insert, update, fetch, and delete data through the use of an open interface table REST service.

Using an Open Interface Table REST Service

REST Service Invocation Scenario

An open interface table 'AR Autoinvoice' (RAXMTR) is used in this example to explain how you can test and use an open interface table REST service.

In this example, a few HTTP requests are received to insert, retrieve, and remove invoice data from Oracle Receivables. The RA_INTERFACE_LINES_ALL REST operation contained in the 'AR Autoinvoice' interface is invoked to execute these requests.

After each successful service invocation, the client will receive a REST response message to indicate the invoice line data has been successful inserted, updated, retrieved, or removed from Oracle Receivables.

Invoking an Open Interface REST Service

Based on the REST service invocation scenario, this chapter includes the following topics:

1. Deploying a REST Service

2. Creating a Security Grant

3. Recording Resource Information from Deployed WADL

4. Invoking a REST Service Using Command Lines

Deploying a REST Service

Use the following steps to deploy the open interface table 'AR Autoinvoice' (RAXMTR):

1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role.

   Select the Integrated SOA Gateway responsibility and the Integration Repository link from the navigation menu.

2. In the Integration Repository tab, click Search to access the main Search page.

3. Enter the following key search values as the search criteria:

   • Internal Name: RAXMTR

   • Interface Type: Open Interface

4. Click Go to execute the search.

   Click the 'AR Autoinvoice' interface name link to open the interface details page.

5. In the REST Web Service tab, enter the following information:

   Open Interface Table Interface Details Page with REST Web Service Tab

   

   • Service Alias: autoinvoice

     The alias will be displayed as the service endpoint in the WADL and schema for the selected method or operation.

   • Select Desired Service Operations

     In the first row 'AR Autoinvoice', select the four HTTP method check boxes (GET, POST, PUT, and DELETE). The rest of the open interface table names shown as the method names listed in the table are all automatically selected.

6. Click Deploy to deploy the service to an Oracle E-Business Suite WebLogic environment.

Creating a Security Grant

After deploying the 'AR Autoinvoice' as a REST service, the integration administrator can create a security grant to authorize the service or method access privileges to a specific user, a user group, or all users.

Use the following steps to create a security grant:

1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link from the navigation menu.

2. Perform a search to locate the AR Autoinvoice service the administrator just deployed earlier.

3. In the interface details page of the selected AR Autoinvoice, click the Grants tab.

4. Select the RA_INTERFACE_LINES_ALL method check box and then click Create Grant.

5. In the Create Grants page, select "All User" as the Grantee Type.

   Note: In this example, the RA_INTERFACE_LINES_ALL service operation is granted to all users. In actual implementation, you should define strict security rules. Create grant to a user or more appropriately to a group of users defined by roles and responsibilities.

   Click Create Grant. This grants the selected method access privilege to all Oracle E-Business Suite users.

Recording Resource Information from Deployed WADL

To obtain service resource information from the deployed 'AR Autoinvoce' service, an integration developer clicks the View WADL link in the REST Web Service tab. This displays the WADL description in a different window.

Copy or record the REST service endpoint from the WADL description. This will be used later when invoking the service.http://<hostname>:<port>/webservices/rest/autoinvoice/RA_INTERFACE_LINES_ALL/

Replace autoinvoice, the alias in this sample deployment, with the alias name you used in your deployment.

Invoking a REST Service Using Command Lines

In this example, we use a third party command line tool called cURL to transfer data using URL syntax. This tool is available by default on most Linux environments.

Note: You can test the REST service invocation using any REST client.

This section includes the following invocation scenarios:

1. Inserting Data to Oracle Receivables Using the HTTP POST Method

2. Updating Data in Oracle Receivables Using the HTTP PUT Method

3. Fetching Data from Oracle Receivables Using the HTTP GET Method

4. Deleting Data in Oracle Receivables Using the HTTP DELETE Method

Inserting Data to Oracle Receivables Using the HTTP POST Method

Creating a File with Input Payload

When an HTTP request is received to insert invoice data to Oracle Receivables, before invoking the REST service, you need to create the following xml file called lines.xml with required data as input payload.

<?xml version="1.0" encoding="UTF-8"?>
<RA_INTERFACE_LINES_ALL_Input>
        <RESTHeader>
                <Responsibility>RECEIVABLES_VISION_OPERATIONS</Responsibility>
        <RespApplication>AR</RespApplication>
        <SecurityGroupE>STANDARD</SecurityGroup>
        <NLSLanguage>AMERICAN</NLSLanguage>
        <Org_Id>204</Org_Id>
        </RESTHeader>
<Select>INTERFACE_LINE_ID, BATCH_SOURCE_NAME</Select>
<InputParameters>
<RA_INTERFACE_LINES_ALL_REC>
                <INTERFACE_LINE_ATTRIBUTE9>1</INTERFACE_LINE_ATTRIBUTE9>
           <INTERFACE_LINE_ATTRIBUTE11>1</INTERFACE_LINE_ATTRIBUTE11>
     <INTERFACE_LINE_ATTRIBUTE10>1</INTERFACE_LINE_ATTRIBUTE10>
     <ORG_ID>204</ORG_ID>
                <COMMENTS>Test REST1</COMMENTS>
     <QUANTITY>1</QUANTITY>
     <TRX_NUMBER>trxpj1</TRX_NUMBER>
     <CONVERSION_RATE>1</CONVERSION_RATE>
                <CONVERSION_DATE>11-APR-2018</CONVERSION_DATE>
     <CONVERSION_TYPE>Use</CONVERSION_TYPE>
                <ORIG_SYSTEM_SHIP_ADDRESS_ID>1030</ORIG_SYSTEM_SHIP_ADDRESS_ID>
                <ORIG_SYSTEM_SHIP_CUSTOMER_ID>1004</ORIG_SYSTEM_SHIP_CUSTOMER_ID>
                <ORIG_SYSTEM_BILL_ADDRESS_ID>1030</ORIG_SYSTEM_BILL_ADDRESS_ID>
                <ORIG_SYSTEM_BILL_CUSTOMER_ID>1004</ORIG_SYSTEM_BILL_CUSTOMER_ID>
     <TERM_ID>4</TERM_ID>
     <TERM_NAME>30 Net</TERM_NAME>
                <CUST_TRX_TYPE_ID>1</CUST_TRX_TYPE_ID>
                <CUST_TRX_TYPE_NAME>Invoice</CUST_TRX_TYPE_NAME>
     <AMOUNT>1000.00</AMOUNT>
     <CURRENCY_CODE>USD</CURRENCY_CODE>
     <DESCRIPTION>Project Invoices</DESCRIPTION>
     <LINE_TYPE>LINE</LINE_TYPE>
     <SET_OF_BOOKS_ID>1</SET_OF_BOOKS_ID>
     <BATCH_SOURCE_NAME>PROJECTS INVOICES</BATCH_SOURCE_NAME>
     <INTERFACE_LINE_ATTRIBUTE7>Line</INTERFACE_LINE_ATTRIBUTE7>
        <INTERFACE_LINE_ATTRIBUTE6>1</INTERFACE_LINE_ATTRIBUTE6>
           <INTERFACE_LINE_ATTRIBUTE5>xxxxx, Mr. xxxxx</INTERFACE_LINE_ATTRIBUTE5>
     <INTERFACE_LINE_ATTRIBUTE4>Vision Operations</INTERFACE_LINE_ATTRIBUTE4>
     <INTERFACE_LINE_ATTRIBUTE3>Services 01</INTERFACE_LINE_ATTRIBUTE3>
        <INTERFACE_LINE_ATTRIBUTE2>3</INTERFACE_LINE_ATTRIBUTE2>
           <INTERFACE_LINE_ATTRIBUTE1>ATZ Services</INTERFACE_LINE_ATTRIBUTE1>
     <INTERFACE_LINE_CONTEXT>PROJECTS INVOICES</INTERFACE_LINE_CONTEXT>
  </RA_INTERFACE_LINES_ALL_REC>
        </InputParameters>
</RA_INTERFACE_LINES_ALL_Input>

Invoking the REST Service Using Command Line Tool

Once the xml file is created, place it in the directory where you are going to test the invocation. Execute the following command to invoke the service to transfer each invoice line data into Oracle Receivables based on the input payload sent from the request:

curl -H 'Content-Type: application/xml' -u <usernmae>:<password> -d @lines.xml 
https://<ebshost>:<port>/webservices/rest/<alias>/RA_INTERFACE_LINES_ALL/

• Replace <username> with an Oracle E-Business Suite user name who has the privilege of accessing the open interface table AR Autoinvoice.

• Replace <alias> with autoinvoice in this example.

Viewing the Response Message

When the REST service is successfully invoked, the following output in XML format appears:

<?xml version = '1.0' encoding = 'UTF-8'?>
<OutputParameters xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/ra_interface_lines_all">
 <Summary>
        <SuccessCount>1</SuccessCount>
        <ErrorCount>0</ErrorCount>
 </Summary>
 <Result>
  <Output>
    <Index>0</Index>
    <Status>SUCCESS</Status>
          <Message></Message>

         <RA_INTERFACE_LINES_ALL_REC>
                <INTERFACE_LINE_ID/>
                <BATCH_SOURCE_NAME>PROJECTS INVOICES</BATCH_SOURCE_NAME>
   </RA_INTERFACE_LINES_ALL_REC>
   </Output>
  </Result>
</OutputParameters>

Updating Data in Oracle Receivables Using the HTTP PUT Method

When a request of updating data in Oracle Receivables is received, we can use the PUT method to update data based on condition.

For example, we need to update the values of QUANTITY and COMMENTS for record with TRX_NUMBER equal to 'Demo1' and ORG_ID equal to 204 in RA_INTERFACE_LINES_ALL.

Creating a File with Input Payload

In this situation, we need to first create a file linesUpdate.xml with the following content as the payload:

<?xml version="1.0" encoding="UTF-8"?>
<RA_INTERFACE_LINES_ALL_Input>
        <RESTHeader>
                <Responsibility>RECEIVABLES_VISION_OPERATIONS</Responsibility>
        <RespApplication>AR</RespApplication>
        <SecurityGroupE>STANDARD</SecurityGroup>
        <NLSLanguage>AMERICAN</NLSLanguage>
        <Org_Id>204</Org_Id>
        </RESTHeader>
  <Select>DESCRIPTION,TRX_NUMBER</Select>
  <InputParameters>
    <Update>
                <Filter>ORG_ID==204;TRX_NUMBER==Demo1</Filter>
     <RA_INTERFACE_LINES_ALL_REC>
        <COMMENTS>Quantity updated to 5</COMMENTS>
        <QUANTITY>5</QUANTITY>
     </RA_INTERFACE_LINES_ALL_REC>
   </Update>
 </InputParameters>
</RA_INTERFACE_LINES_ALL_Input>

Invoking the REST Service Using Command Line Tool

Execute the following curl command to update QUANTITY and COMMENTS for records with TRX_NUMBER equal to 'Demo1' and ORG_ID equals to 204 in RA_INTERFACE_LINES_ALL.

curl -H 'Content-Type: application/xml' -u <usernmae>:<password> -X PUT -d @ linesUpdate.xml  
'https://<ebshost>:<port>/webservices/rest/<alias>/RA_INTERFACE_LINES_ALL/'

• Replace <username> with an Oracle E-Business Suite user name who has the grants to access the open interface table AR Autoinvoice.

• Replace <alias> with autoinvoice in this example.

Viewing the Response Message

When the REST service is successfully invoked, the following output in XML format appears:

<?xml version="1.0" encoding="UTF-8"?>
<OutputParameters xmlns="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/ra_interface_lines_all">
 <Summary>
        <SuccessCount>1</SuccessCount>
        <ErrorCount>0</ErrorCount>
 </Summary>
 <Result>
  <Output>
    <Index>1</Index>
    <Status>SUCCESS</Status>
          <Message/>
     <UpdateCount>1</UpdateCount>
          <RA_INTERFACE_LINES_ALL_REC>
      <DESCRIPTION>Project Invoices</DESCRIPTION>
      <TRX_NUMBER>Demo1</TRX_NUMBER>
     </RA_INTERFACE_LINES_ALL_REC>
   </Output>
  </Result>
</OutputParameters>

Fetching Data from Oracle Receivables Using the HTTP GET Method

When a request of fetching data from Oracle Receivables is received, we can use the GET method to fetch data based on condition.

Invoking the REST Service Using Command Line Tool

For example, execute the following curl command to fetch values of TRX_NUMBER, QUANTITY, and COMMENTS from RA_INTERFACE_LINES_ALL for records with TRX_NUMBER equal to 'Demo1' in ORG_ID 204.

curl -u <usernmae>:<password> -X GET 
'https://<ebshost>:<port>/webservices/rest/<alias>/RA_INTERFACE_LINES_ALL/?filter=ORG_ID==204;TRX_NUMBER==Demo1&select=TRX_NUMBER,QUANTITY,COMMENTS'

• Replace <username> with an Oracle E-Business Suite user name who has the privilege of accessing the open interface table AR Autoinvoice.

• Replace <alias> with autoinvoice in this example.

Viewing the Response Message

When the REST service is successfully invoked, it may return the following response:

{
  "OutputParameters" : {
    "@xmlns" : "http://xmlns.oracle.com/apps/ar/concurrentprogram/rest/autoinvoice/ra_interface_lines_all",
    "Summary" : {
      "Select" : "TRX_NUMBER,QUANTITY,COMMENTS",
      "Filter" : "ORG_ID==204;TRX_NUMBER==Demo1",
      "Offset" : "0",
      "Limit" : "200",
      "Sort" : null,
      "GetCount" : "1",
      "TotalCount" : "1"
    },
    "Result" : {
      "Output" : {
        "RA_INTERFACE_LINES_ALL_REC" : {
          "TRX_NUMBER" : "Demo1",
          "QUANTITY" : "1",
          "COMMENTS" : "Create"
        }
      }
    }
  }
} 

Deleting Data in Oracle Receivables Using the HTTP DELETE Method

When a request of removing data from Oracle Receivables is received, we can use the DELETE method to delete data.

Invoking the REST Service Using Command Line Tool

For example, execute the following curl command to delete data from RA_INTERFACE_LINES_ALL with TRX_NUMBER equal to 'Demo1' in 204 ORG_ID:

curl -u <usernmae>:<password> -X DELETE 
''https://<ebshost>:<port>/webservices/rest/<alias>/RA_INTERFACE_LINES_ALL/?filter=ORG_ID==204;TRX_NUMBER==Demo1'

• Replace <username> with an Oracle E-Business Suite user name who has the privilege of accessing the open interface table AR Autoinvoice.

• Replace <alias> with autoinvoice in this example.

Viewing the Response Message

When the REST service is successfully invoked, it may return the following response message:

{
  "OutputParameters" : {
    "@xmlns" : "http://xmlns.oracle.com/apps/ar/concurrentprogram/rest/autoinvoice/ra_interface_lines_all",
    "Result" : {
      "Status" : "SUCCESS",
      "Message" : null,
      "DeleteCount" : "1"
    }
  }
}