X

It's All About the Platform.

Using the Web Service for Enterprise Scheduling Service (ESS)

Richard Bingham
Senior Development Manager

 

 

 

 

Introduction

This article takes you through the basics of submitting a Enterprise Scheduler Service job request using a web service call. This may be useful for various functional requirements, such as kicking-off  specific processes, run extract or import jobs, or to generating BI Publisher reports.

This is done using ESSWebservice which is deployed to all instances of the ESS app (i.e. one per product), and contains operations such as submitRequest, cancelRequest, deleteRequest, as well as others to get the details from a specific request. Ensure you have the latest Patches4FA applies, and you can find its WSDL using the following URL:

  • https://[ESSHost]/ess/esswebservice?wsdl

The embedded video below demonstrates the process involved in submitting a new request using the SoapUI testing tool, however this article also goes into a little more detail.

Step 1 - Get The Host Server for your Job

As all jobs are run by their own application, you'll first need to make sure you connect to the right host. For example with an Oracle HCM Cloud job you'll need to use a host like https://hcm-[server][pod].oracleoutsourcing.com or for a Sales Cloud job you need to use https://crm-[server][pod].oracleoutsourcing.com.

Please note that many products have multiple applications running to support the complete environment. Look at the job definition (see #2 below) itself to verify which application it uses, and hence which host to use.

 

Step 2 - Match the Job to the Right ESS Application

Every job has a definition which can be used to get the details for your web service request. Use the Setup and Maintenance menu from the Navigator, and select the task 'Manage Custom  Enterprise Scheduler Jobs For [Your Product]'. This lists out the jobs within that particular product area. Click on the edit button for the job of interest and note down the Job Application Name value.

For reference the following is the complete list.

Step 3 - Enable The Required Security

 

Just like it's native scheduling functionality, the ESSWebservice originates from the middleware technology and as such has some additional security configuration requirements when compared to the product web services from Fusion Applications. There is no additional technology, just adding the following to your request payload.

  • A WS addressing header
  • A WS Security header

SoapUI allows you to add these easily. Once you have added your user account in the "Aut" tab at the bottom of the request window, right-click on the payload and select "Add WSS Username Token". From the popup choose the default "Specify Password Text". You will see the security header added to the XML. Next click the "WS A" tab at the bottom to the request window. From the properties shown WS-A should be enabled by default, however you need to scroll down and check "Randomly generate MessageId".

Step 4 - Complete the Request Payload

Now just complete the values in the request XML. In the example below the fields to note are highlighted in yellow, and as mentioned above you can get the values by editing the job definition on the Setup and Maintenance - 'Manage Custom  Enterprise Scheduler Jobs For [Your Product]' task.

  • name = The jobs internal name
  • packageName = The Path to the job.
  • type = The static value JOB_DEFINITION
  • requestStartTime = Either a specific time/date or null for immediate.

The following is an example for the Address Validation job hosted by the CRM application

Step 4 - Use the Response

The response from the above submitRequest operation simply returns the Job requestId, as shown below.

This can then be used in operations such as getRequestState to verify the current status. If you need more details on the request, use the getRequestDetails operation, as shown in the video. Note the web service also supports a callback onJobCompletion operation which notifies the client when a specific request reaches a specific status, to reduce the need to repeatedly make a status call.

 

Troubleshooting and References

The following generic error may be seen when testing the web service call, and below are some actions you can take to resolve it.

 

ESS-02002
User [your username] does
not have
sufficient
privilege to
perform
operation
submitRequest
  • Make sure your user can submit the same job online, using the Scheduled Processes form.
  • Make sure your security headers are included and there are no typo's or mistakes.
  • Make sure your request <sch:application> value matches the one in the job definition page.
  • Make sure you are using the right host in the URL for the web service request, ensuring it matches the application and the job.

For more information about the ESSWebservice please review the FMW Guide to Developing Applications for ESS - Chapter 16

If you are connecting to ESS from a design-time environment, particular from a SOA composite application, then also take a look at this A-Team article.

Join the discussion

Comments ( 20 )
  • Micha Tuesday, April 14, 2015

    Hello Richard,

    it looks like this web service is not exposed on all customer cloud pods. In our case it works on our Stage pods, but not in Production.

    I've also checked some other pods from previous clients and the WSDL is often not accessible.

    Either some pods are configured differently, or the functionality is maybe not meant to work until the April Patch Bundle / P4FA?

    Could you confirm this please?

    Do you recommend raising an SR on this?

    Thanks

    Micha


  • Richard Bingham Tuesday, April 14, 2015

    Hi Micha,

    Thanks for raising this. The content above is from an external R9 Sales Cloud environment, however it is possible that production instance specific enablement is required. I was informed this was an external facing service and believe it's not related to a recent patch bundle.

    Yes I think this is something that the Cloud Operations team need to verify. Please raise a SR and I will also follow up internally too.

    My apologies for any inconvenience.

    Richard


  • guest Wednesday, April 15, 2015

    Thanks for this - very interesting.

    There seems to be some overlap with some of the capabilities of FinancialUtilService to submit and monitor ESS jobs. What are the differences, and any recommendations on when to use each?


  • Richard Bingham Wednesday, April 15, 2015

    Hi.

    Yes several product families have services that allow you to submit ESS jobs too, although most are specific about the jobs they support - relating only to those from their functionality. What is discussed here is the underlying generic ESS service for use where product-specific options do not exist.

    Kind regards,

    Richard


  • Micha Saturday, April 18, 2015

    Hi Richard,

    it seems indeed that the April P4FA patch enabled this in all Cloud pods.

    Our production pod has just received this patch this weekend, and now I can access the WSDL.

    Our Stage pods got it two weeks ago. That's why the service worked already before.

    We're an HCM customer by the way.

    Looks like everything is good now.

    Thanks for the article.

    Micha


  • Richard Bingham Monday, April 20, 2015

    Hi.

    OK thanks for verifying this, and mentioned in the text also.

    Kind regards

    Richard


  • Bharath Wednesday, November 18, 2015

    Is there any rest service for the same? Please clarify.

    Thanks

    Bharath


  • Richard Bingham Wednesday, November 18, 2015

    Hi

    At this time (release 10) there is no RESTful web service specifically for ESS as described above. I would recommend logging this requirement, with use-cases, with Oracle Support to get this considered for future release.

    Kind regards

    Richard


  • guest Tuesday, May 10, 2016

    Hi Richard,

    The Article was indeed very userful and helped me a lot. I have followed the step by step process mentioned in the Video but at the end i am getting the below error message.

    InvalidSecurityToken : The security token is not valid.

    Request your help in this.

    Thanks

    Vamsi.


  • Richard Bingham Monday, May 16, 2016

    Hi.

    Sounds like either a mis-step in #3 above, or perhaps a configuration issue in your environment. Check the setup and raise a SR if the issue persists.

    Thanks

    Richard


  • Vamsi Tuesday, May 17, 2016

    Hi Richard,

    Thanks very much for the reply and the issue got resolved and I am able to submit the Ess Job request from the SOAP Editor.

    My requirement is to use the same code to be submitted from the PL/SQL Code from EBS Environment, do you have any sample code to achieve the same.

    Thanks

    Vamsi.


  • guest Tuesday, May 17, 2016

    Hi Vamsi

    I am afraid we don't have an E-Business Suite (or PLSQL) example. It's been many years since I worked with EBS directly so I couldn't give you the latest options and features myself.

    I would recommend you look at the Oracle E-Business Suite Technical blog which I can see has details on this topic, such as this https://blogs.oracle.com/stevenChan/entry/how_to_publish_pl_sql

    Also you can find webservice-PL/SQL tutorials on the web, such as this: https://youtu.be/6JPZAir3UP4

    Kind regards

    Richard


  • john Friday, June 17, 2016

    What is the difference between this service and a similar service in erpIntegration named submitEssJobRequest?

    Also, is it possible to submit a null value as a parameter?


  • carl Thursday, September 22, 2016

    To pass null value for a parameter try #NULL as in <paramList>#NULL</paramList>


  • guest Thursday, February 23, 2017

    Hi Richard,

    Quick question, i know you can call specific jobs via WSDL passing respective params/arguments. Can we call the Job Set in a similar way. If yes then What will be the jobset wsdl or is it a product limitation.

    Regards

    SP


  • guest Friday, April 7, 2017

    This is a great article. Thank you for posting Robert.

    Can you advise how can we post parameters in a SOAP UI payload?

    The ESS job i am using accepts 2 parameters, but i cannot seem to identify how to get the parameter name for those.

    Thanks

    AJ


  • Richard Tuesday, April 11, 2017

    Hi

    Parameters are passed inside the payload in the sch:requestParameters XML element tag. These should be simple name:value pairs as per the WSDL/XSD.

    Kind regards

    Richard


  • guest Friday, April 21, 2017

    Hi Richard,

    Thanks for the note.

    The ESS job I am trying to submit using APIs is Export Changed Taleo Objects.

    When executing the job, the parameters appear as "Export Object" (which is a drop down) and "Export Data Range"

    When I looked at the job definition, I am unable to identify the code which should be used for these fields, as this is an internal job, and I cannot edit the job definition.

    However, when I look at one of the completed jobs, I see them as Attribute 1 and Attribute 2, which is why its making things unclear.

    Can you please shed some light on how we can extract this information from the system?

    Thanks

    AJ


  • Jeremy Lopez Monday, January 15, 2018
    Hello Richard:

    an ESS job can have parameters and user properties. your example shows parameters. how do you submit a web service with user properties.

    JL
  • Wojciech Friday, September 14, 2018
    Hi Richard,

    Do you have a tutorial presents how to schedule a process with hour occurrence till the end of month for example.

    Best
    Mr W
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha