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’.
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.
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 METHOD | CRUD | ENTIRE COLLECTION (E.G. /USERS) | SPECIFIC ITEM (E.G. /USERS/123) |
| POST | Create | 201 (Created), ‘Location’ header with link to /users/{id} containing new ID. | Avoid using POST on single resource |
| GET | Read | 200 (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. |
| PUT | Update/Replace | 404 (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. |
| PATCH | Partial Update/Modify | 404 (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. |
| DELETE | Delete | 404 (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.
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.
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.
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.
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.
LOGOUT SERVICE
12. To add another service to the Collection in Postman, click on the […] button, and select Add Request.
13. As we are going to execute this service last as part of our Collection, we will name it ’99 Logout’. Press ‘Save’.
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’.
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:
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.
17. In the Java Details : Payslip window, click on the ‘REST Web Service’ tab.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
- 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.
34. Run the PrePayments concurrent program.
35. Run the BACS concurrent program.
36. Run the Payslip Generation – Self Service concurrent program.
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.)
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
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.
- 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
Clear the cookies by pressing on the X for each cookies listed.
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:
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’.
49. When the Collection Runner window opens, hit the ‘Run ISG Authentic…’ button.
Once the 3 REST services have run the Run Results should look like this.
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.
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.
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 Name | VERB | REST URL | Authorization | Body Type | Payload Type | Payload Content |
| 11 Get Payslip Information – GROSS | POST | http://apps.example.com:8000/ webservices/rest/payslips/ getPayslipDataDetails/ | Inherit auth from parent | Raw | JSON (application/json) | { |
| 12 Get Payslip Information – DEDUCTIONS | POST | http://apps.example.com:8000/ webservices/rest/payslips/ getPayslipDataDetails/ | Inherit auth from parent | Raw | JSON (application/json) | {} |
Reorder the tests in the collection by grabbing the test and repositioning correctly in the right order.
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:
You can either run each test in the collection as a whole (as before)…
… or manually run each of them in order in separate tabs on the main Postman canvas.
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….
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.
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/logsA 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.
Note to self 
2 thoughts on “Using Oracle Integrated SOA Gateway – a worked example”