Using Oracle Integrated SOA Gateway – a worked example

Back in 2019 I was working for a client that was using Oracle eBusiness Suite (EBS) 12.2.8, and Oracle SOA Suite for their integation middleware. We ended up using a few Oracle Integrated SOA Gateway (ISG) services – exposed as SOAP – but I also had some time to explore the REST services that can be enabled on EBS.

At the time in 2019 I thought that it was pretty cool stuff (for a non-geek) and wrote down a few things to share with my Fujitsu colleagues. In this blog I’ll share what I did and found out with you too.

Overview

This worked example will show you how you can use a REST service test tool, like Postman, to execute REST services on Oracle eBusiness Suite (EBS) 12.2.

It will guide you, the end user / developer, to locate and use seeded authentication and authorization services, and show an example of how to enable a service (e.g. get a list of available payslips) and to test the execution of these in Postman.

There is an optional section to try, or at least read through, to give you an insight into just some of the seeded services you can expose on the Integrated SOA Gateway on an eBusiness Suite 12.2 instance.

environment used

Oracle E-Business Suite Vision Install 12.2.8 – with ISG. Refer to the following blog: EBS 12.2.8 VM Virtual Appliance Now Available

Follow the guide to help you get the Vision instance running.

Download and install Postman.

ASSUMPTIONS

Your eBusiness Suite Application or VM has already been patched to run the Integrated SOA Gateway (reference to Oracle Support Document 1311068.1).

Setup / link a new test user

1. For this we exercise we will create a test user ‘JCARRINGTON’ and link this account to the person ‘Jackson Carrington’ in the Vision instance. We will then gave the user the ‘Employee Self-Service’ responsibility.

Hint: Login and change the first-time use password for ‘JCARRINGTON’.

Figure 1 – New User – JCARRINGTON

OUT-OF-THE-BOX AUTHENTICATION AND AUTHORIZATION SERVICES

When you patch the Oracle EBS 12.2 instance to enable the Integrated SOA Gateway you are given a few pre-enabled services for Authentication and Authorisation.

2. Login to the Oracle EBS as the ASADMIN or SYSADMIN user. Both these users have been setup in Vision instance with the ‘Integrated SOA Gateway’ responsibility.

NAV > Integration SOA Gateway > Integration Repository

Press the ‘Search’ button (top right), and expand the ‘Show More Search Options’.

Category: Interface Subtype

Category Name: Security Services

Press ‘Go

This will display 2 Security Services.

Note that these are both Active.

3. Click on the ‘Authentication Services’ hyperlink.

Figure 2 – Seeded Authentication Services

The ‘Java Details : Authentication Services’ screen shows that there are 4 methods presented as part of this service.

You will note that the REST Web Service is Deployed. The REST Verb is POST. The table below shows the HTTP Methods typically made available as part of a REST service.

HTTP METHODCRUDENTIRE COLLECTION (E.G. /USERS)SPECIFIC ITEM (E.G. /USERS/123)
POSTCreate201 (Created), ‘Location’ header with link to /users/{id} containing new ID.Avoid using POST on single resource
GETRead200 (OK), list of users. Use pagination, sorting and filtering to navigate big lists.200 (OK), single user. 404 (Not Found), if ID not found or invalid.
PUTUpdate/Replace404 (Not Found), unless you want to update every resource in the entire collection of resource.200 (OK) or 204 (No Content). Use 404 (Not Found), if ID not found or invalid.
PATCHPartial Update/Modify404 (Not Found), unless you want to modify the collection itself.200 (OK) or 204 (No Content). Use 404 (Not Found), if ID not found or invalid.
DELETEDelete404 (Not Found), unless you want to delete the whole collection — use with caution.200 (OK). 404 (Not Found), if ID not found or invalid.

4. Click on the ‘View WADL’ hyperlink to view the definitions for the REST services.

Note from the WADL the resources base, and the resources path entries. It is the combination of these and the method which are used to reference the REST APIs.

Figure 3 – http://apps.example.com:8000/webservices/rest/AuthenticationService?WADL snippet

For example, the snippet above is from the WADL for the Authentication Service to logout of the Oracle EBS application (GET method). It shows the resource base as http://apps.example.com:8000/webservices/rest/ and the path as logout, so the completed URL of the REST service you would use is:

http://apps.example.com:8000/webservices/rest/logout

The [base]/[path] pattern is a good way to determine from the WADL the REST service target endpoint.

5. Start Postman, and click the New button (top left) to create a new Collection. Give it the name ‘ISG Authentication and Payslip List Test’. On the Authorisation tab choose Basic Auth, and set the username to ‘JCARRINGTON’ with the correct changed password from Step 1.

6. For now, click the ‘Create’ button.

Figure 4 – Setting Basic Authentication in Postman

LOGIN SERVICE

7. For the EBS Login service we are going to use the ‘GET’ method. In our instance (and looking at the WADL for this service) it is located at http://apps.example.com:8000/webservices/rest/login so enter this address in Postman.

Figure 5 – Adding a service URL to a Postman Test

8. Press ‘Save’.

9. When the ‘Save Request’ window appears, change the name to ‘1 Login’, and select the ‘ISG Authentication and Payslip List Test’ collection.

10. Press ‘Save’.

Figure 6 – Saving a Postman test to a collection

As we have already set the ‘Authorisation’ parameters (JCARRINGTON/[password]) when we created the Postman Collection we do not have to set them separately for each subsequent test as they now form part of the ‘Inherit auth from parent’ option.

Figure 7 – Running a manual test in Postman

11. Test the ‘1 Login’ REST service by pressing the ‘Send’ button.

The REST service execution will result in a payload being returned back. For example,

<?xml version = '1.0' encoding = 'UTF-8'?>
<data>
    <accessToken>R8OWdEwMqEiBpq1MTFBgWlZElW</accessToken>
    <accessTokenName>EBSDB</accessTokenName>
    <ebsVersion>12.2.8</ebsVersion>
    <userName>JCARRINGTON</userName>
</data>

You will also see that the Status of 200 OK was returned, which means that the service has been executed successfully.

Importantly, 2 cookies have also been set. Simply put, a cookie it a piece of data that can be stored and subsequently used by a browser in a session to assist with transactions that may occur later. In this example the cookies for ESBDB and JSESSIONID have been created. You will note that the values for <accessTokenName> for <accessToken> returned from the call to the login service have been captured as the name/value pair for the entry EBSDB.

EBSDB is the database service name on which this example Vision eBusiness Suite instance is running.

Figure 8 – Postman acting like a browser and saving cookies

LOGOUT SERVICE

12. To add another service to the Collection in Postman, click on the […] button, and select Add Request.

Figure 9 – Make changes to a Postman collection

13. As we are going to execute this service last as part of our Collection, we will name it ’99 Logout’. Press ‘Save’.

Figure 10 – Adding another request to a collection

For the new ’99 Logout’ service we will enter the request URL (by referring again to the WADL) as http://apps.example.com:8000/webservices/rest/logout and as this service also can use the GET method we will choose this too.

14. Press ‘Save’.

Figure 11 – Saving a new test

The cookies that were set as part of executing the ‘1 Login’ REST service should still be available and, if the Oracle EBS application hasn’t already timed out, the session for ‘JCARRINGTON’ should be available in the background.

15. We should be able to press the ‘Send’ button to test it. If the Oracle EBS application session for that user has already expired then you will see this message:

Figure 12 – Response when an EBS session has expired

If however you still have an active session (or if not and re-run the ‘1 Login’ test again to create a new JSESSIONID and Oracle EBS application session), then you should see this message.

Figure 13 – Successful session logout from EBS

The value for <accessToken> of -1 means that the session created for ‘JCARRINGTON’ has now been closed.

DEPLOY A NEW SEEDED ISG SERVICE (PAYSLIP LIST)

In this worked example we are going to enable a seeded Payroll service which will list (up to) the last 12 payslips that are available for an employee.

16. Again as ASADMIN login to the Oracle EBS, and choose the ‘Integrated SOA Gateway’ responsibility.

NAV > Integrated SOA Gateway > Integration Repository

Integration Repository > Human Resource Suite > Payroll > HR Person(1) From the Interface List : HR Person(1) window, select the ‘Payslip’ link.

Figure 14 – Integration Repository – Payslip Services

17. In the Java Details : Payslip window, click on the ‘REST Web Service’ tab.

Figure 15 – Integration Repository – Payslip service details
Figure 16 – Adding a service alias and deploying

18. The ‘REST Web Service’ window shows us the services and the HTTP methods available for us to deploy. The ‘Service Alias’ will be the Path in the eventual URL for the REST API service so will we give it a friendly name of payslips.

19. Tick any of the GET and POST services that you are intending to deploy for use later. Press the ‘Deploy’ button.

You will see this message once the REST services have been deployed.

GRANTING ACCESS TO ISG SERVICES

Whereas the Authorisation Services we’ve looked at already did not need any additional access granted to them, most ISG REST services require us grant a specific user, group of users (i.e. by application responsibility) or all users access to interact with the ISG services.

20. On the Grants tab, select the object that you which grant the use of and press the ‘Create Grant’ button.

Figure 17 – Selecting a service for grants

In our example, we will restrict the ‘Get List of Available Payslips’ service to those employees who have been given the ‘Employee Self-Service’ responsibility.

21. In the “Grant All Selected” section, change the Grantee Type to ‘Group Of Users’ and in the Grantee Name search and select the ‘Employee Self-Service’ responsibility.

Figure 18 – Configuring Grants in ISG

22. Click on the ‘Create Grant’ button (top right) to save and return back to previous screen. You will see next to the service ‘Get List of Available Payslips’ a record listed under the Grant column of the table now.

TESTING THE NEW ISG SERVICE IN POSTMAN

Now we have created, deployed and granted the REST service it can be tested. For this we will add it to our existing ‘ISG Authentication and Payslip List Test’ collection in Postman.

23. As before, add another service to the Collection in Postman, click on the […] button, and select Add Request.

Request Name: 10 Get List of Available Payslips

24. Save the new request.

25. In the ‘ISG Authentication and Payslip List Test’ collection, reorder the requests show that the new ‘10 Get List of Available Payslips’ request sits between the Login and Logout request tests created earlier.

Figure 19 – List of requests in Postman

26. Go back the Integration Repository window in eBusiness Suite and click on the ‘REST Web Service’ tab for the Payslip service, click on the ‘View WADL’ link.

Figure 20 – View WADL in the Integration Repository
Figure 21 – http://apps.example.com:8000/webservices/rest/payslips?WADL snippet

The figure above shows the WADL file contents. Using the resource base and path we can construct the REST service request URL as: http://apps.example.com:8000/webservices/rest/payslips/getPayslipListDetails/ with the method as POST.

The Payslip service in Oracle EBS contains a list of parameters that the REST service will require in the payload when the REST service is executed.

Figure 22 – Expected parameters

27. For the test of this service in Postman we will construct the following JSON payload.

{
  "InputParameters": {
    "personId": "24250",
    "legCode": "US",
    "bgID": "202"
  }
}

28. In Postman, for the getPayslipListDetails service, click on the Body tab, then select raw. Change the expected format to JSON (application/json). Paste the JSON payload into the area below.

Figure 23 – JSON payload added to the test body

29. Press Save.

EXECUTE THE LOGIN, GETPAYSLIPLISTDETAILS AND LOGOUT TESTS

30. On the Collections pane click the play button that will appear when you hover over the ‘ISG Authentication and Payslip List Test’ collection.

Figure 24 – Running a test collection

31. Press the Run button to start the tests. Our expected results will be that Postman will:

  • login as the ‘JCARRINGTON’ user, and receive back a JSESSIONID cookie
  • execute the ‘getPayslipListDetails’ service, obtaining a list of available payslips
  • logout of the Oracle EBS session
Figure 25 – Collection runner summary window

Once the test run has completed you can examine the requests and drill into the inbound and outbound payloads.

In our example test run below we can see that the Login and Logout services both executed without an issue as they returned a status of 200 OK.

The ‘getPayslipListDetails’ service however generated a 500 Internal Server Error status. The Response Body provides us with an explanation as to why that is, namely that the payroll for this employee on the Vision instance has not run within the last 12 months, and therefore there are no payslips available to them to list.

Figure 26 – Collection runner results window

OPTIONAL TESTS – RUNNING PAYROLLS TO GENERATE RESULTS

In the Vision instance we can run a payroll processes for a few months to generate some more recent payslips so we can view them in Postman. (I did this using a user AGOLDING who has the correct ‘UK HRMS Manager – PS LG’ responsibility in the Vision instance.)

32.

  1. Logging in as ‘AGOLDING’: UK HRMS Manager – PS LG’ responsibility…

NAV –> Payroll –>Description

Query on payroll Name: LG Monthly Change the Number of Years to 21, and Save. This will create new payroll periods that can be used to run new Payrolls up to the end of 2019.


NOTE: when you run the BACS concurrent program you will get an error relating to a file directory missing in the Vision build.

Use WinSCP or putty to login onto the server and create the following directory:

/tmp/EBSDB


The correct payroll process order is to run the following current programs:

Payroll Run UK à PrePayments à BACS à Payslip Generation – Self Service… (I started with month 1, April 2019, i.e. 01-APR-2019 to 30-APR-2019, then continued for May, June and July 2019)

33. Run the Payroll Run UK concurrent program.

Figure 27 – Payroll Run UK

34. Run the PrePayments concurrent program.

Figure 28 – PrePayments

35. Run the BACS concurrent program.

Figure 29 – BACS

36. Run the Payslip Generation – Self Service concurrent program.

Figure 30 – Payslip Generation – Self Service

In total, 4 current months of payroll processes were run. (April, May, June and July 2019) The Vision employee ‘Daniels, Mr. William (Bill)’ is assigned to the ‘LG Monthly’ UK based payroll.

37. Create a new user WDANIELS against the employee ‘Daniels, Mr. William (Bill)’, and give the account the ‘Employee Self Service V3’ responsibility. (Remember to login at least once as WDANIELS in order to set a permanent password.)

Figure 31 – Create new WDANIELS user for existing employee

38. Granting access to ISG services section above, grant the specific user WDANIELS (Daniels, Bill) to access to payslip services:

  • Get List of Available Payslips, and
  • Get payslip information
Figure 32 – Add Grants to the User

39. In Postman, clone the ‘ISG Authentication and Payslip List Test’ collection by hitting the button and selecting ‘Duplicate’. Rename the duplicate collection to ‘ISG Authentication and Payslip List Test – WDANIELS’.

40. Edit the collection by pressing the button again, and select Edit.

41. In the Authorisation tab, change the user to WDANIELS, and make sure the password is correct. Press the Update button to save and close the ‘Edit Collection’ screen.

42.

  1. If you have any other Postman sessions open you may need to close them, or you will need to clear the Cookies in Postman as we are starting a new session with the WDANIELS user.

Click on Cookies

Figure 33 – Postman Cookies Link

Clear the cookies by pressing on the X for each cookies listed.

Figure 34 – Manage Cookies in Postman

43. Try the Login, getPayslipListDetails, Logut scripts again for the WDANIELS collection.

44. As we are dealing with a new employee for this round of tests you will need to update the JSON payload for values relating to the new employee ‘Daniels, Mr. William (Bill)’ for the ‘10 Get List of Available Payslips’ test. The new input payload for the body of the getPayslipListDetails service is:

{
  "InputParameters": {
    "personId": "7453",
    "legCode": "GB",
    "bgID": "1668"
  }
}

45. Once updated it should look like this:

Figure 35 – Test service body – JSON payload

46. Press the Save button and close the tab.

47. Hit the ‘Play’ button for the ‘WDANIELS’ collection.

48. When this screen opens press ‘Run’.

Figure 36 – Run a test collection

49. When the Collection Runner window opens, hit the ‘Run ISG Authentic…’ button.

Figure 37 – Collection Runner Summary

Once the 3 REST services have run the Run Results should look like this.

Figure 38 – Collection Runner Results

All three service calls have complete with status 200 OK messages.

When you hover over the ’10 Get List of Available Payslips’ line it will display to you the ability to drill into the payloads delivered / received by the test including:

  • Request URL
  • Request Headers
  • Request Body
  • Response Headers
  • Response Body

50. Expand the ‘Response Body’ to review the reply JSON payload. Make a note of the ‘ActionContextId’ (see Figure 38 – Collection Runner Results).

As a reminder, the seeded Payslip REST services from Oracle in the Integration Repository contains several services including the ‘Get List of Available Payslips’ we’ve already tested.

Figure 39 – Integration Repository – Payroll Services – HR Person(1)

The ‘Get Payslip Information’ service is also available which allows for more detail to be exposed relating to a payslip based on the action context ID and the payslip category.

Figure 40 – getPayslipDataDetails service

As we have already granted the user ‘WDANIELS’ access to execute the ‘Get Payslip Information’ in a previous step (Step 38) we can create two new tests in the ‘ISG Authentication and Payslip List Test – WDANIELS’collection.

52. Press the button on the collection, and choose Add Request.

52. Create 2 new requests based on using the parameters detailed in the table below:

Postname Test NameVERBREST URLAuthorizationBody
Type
Payload TypePayload Content
11 Get Payslip Information – GROSSPOSThttp://apps.example.com:8000/
webservices/rest/payslips/
getPayslipDataDetails/
Inherit auth from parentRawJSON (application/json){
"InputParameters": {
"personId": "7453",
"legCode": "GB",
"bgID": "1668",
"category": "GROSS",
"actContextId" :"16136420"
}
}
12 Get Payslip Information – DEDUCTIONSPOSThttp://apps.example.com:8000/
webservices/rest/payslips/
getPayslipDataDetails/
Inherit auth from parentRawJSON (application/json){
"InputParameters": {
"personId": "7453",
"legCode": "GB",
"bgID": "1668",
"category": "DEDUCTIONS",
"actContextId" :"16136420"
}
}

Reorder the tests in the collection by grabbing the test and repositioning correctly in the right order.

Figure 41 – Reordering tests in a Postman collection

Once you have completed adding and re-ordering the new tests the collection for ‘ISG Authentication and Payslip List Test – WDANIELS’ should look like this:

Figure 42 – Ordered Postman Collection

You can either run each test in the collection as a whole (as before)…

Figure 43 – Running a collection automatically

… or manually run each of them in order in separate tabs on the main Postman canvas.

Figure 44 – Running a single test manually

That’s it! Hope you enjoyed this blog post and maybe learnt something useful. Let me know.

As an extra, here’s some other stuff I noted down….

Useful Notes

Authentication in the Header

You can set the username and password as part of header payload. This is useful to know when it comes to running REST services in a live scenario.

The Authorization for the service is cleared and set to ‘No Auth’.

The Header for the REST service contains many seeded keys, one of which is ‘Authorization’.


Base64 encoded username/password

The value for the ‘Authorization’ key is made up of:

‘Basic’ + [Base64 encoded username and password].

Use on online tool like this one https://www.base64encode.org/ to encode the username/password value

WDANIELS/Fred4321

The Base64 encoded value is

V0RBTklFTFMvRnJlZDQzMjE=

The ‘Authorization’ key is therefore ‘Basic V0RBTklFTFMvRnJlZDQzMjE=

If you test the Login service using the ‘Authorization’ header key value it will respond in the same way as before.

Figure 45 – Calling a REST service with an Authorization entry in the header

Issues and Fixes – ISG_SERVICE_AUTH_FAILURE

Sometimes when you have configured an ISG service it will look like it should work, but doesn’t.

First thing to look at is the log file. It is located under the oafm_server logs area.

For example,

/u01/install/APPS/fs1/FMW_Home/user_projects/domains/EBS_domain/servers/oafm_server1/logs

A typical error you will see in POSTMAN is the ISG_SERVICE_AUTH_FAILURE exception:

{
  "ISGServiceFault": {
    "Code": "ISG_SERVICE_AUTH_FAILURE",
    "Message": "User is not authorized to execute the service",
    "Resolution": "Please check whether the user has the requisite grants.",
    "ServiceDetails": {
      "ServiceName": "xxdhl_message_status_rest",
      "OperationName": "message_status",
      "InstanceId": "0"
    }
  }
}

This exception suggests that you have not created the Grants correctly, but actually the server is having a caching issue, especially for newly created services.

Notes on the fix…

The fix is to bounce both the application servers and database servers (i.e. the entire stack). The REST service will work as expected thereafter as caches are cleared and ISG services are recompiled.

2 thoughts on “Using Oracle Integrated SOA Gateway – a worked example

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s