Archive for the 'ESS' Category

SOA 12c – Using Schedule Job activity in BPEL

In this post, we will learn how to use the Schedule Job activity to submit a ESS request from BPEL process during orchestration. And we will use the ESS job created from this post.

Create a Sync BPEL process and drag Schedule Job activity into BPEL from Components –> Oracle Extensions as shown below.



We need to create a MDS connection so that we can do the lookup for the ESS jobs. Create a new SOA-MDS Connection in Resources –> IDE Connections and select MDS partition essUserMetadata as shown below.


Double click on Schedule Job activity in BPEL to being up the below editor and select the required ESS job as shown in following screenshots. This way, we can also explore ESS jobs deployed to partition using different namespaces.




Similarly, we can select Schedule if required as shown below.


Navigate to Application Properties tab and give the value for Job Propetires using XPath expression as shown below.




We can also verify the ESS Job system properties in System Properties tab.


Click OK to observe a sequence of activities are created in your BPEL flow as shown below. We can click each of these activities and observe what has been done automatically for us.



On selecting the job, we will see following artifacts get created automatically in our project.


Since our composite using ESS abstract WSDL it will result into build errors. So modify your ESS partner link entry in composite.xml to add bindings and port as highlighted below.

<reference name="EssService"
  <interface.wsdl interface=""
  < port=""
    < port=""/>

Or generate configuration plan for composite and give port and binding along with ESS Webservice location as shown below.

<reference name="EssService">
      <binding type="ws">
        <attribute name="port">
        <attribute name="location">
        <binding type="ws">
          <attribute name="port">

We can always verify ESS Webservice WSDLs by navigating to Webservices section in url >:>/ess">http://<<host>>:<<port>>/ess.

Deploy your SOA project using above configuration plan and Test.  Now we will observe the following error as ESS Webservices can’t be run with anonymous user credentials. To get away with that, modify the ESS webservice by attaching OWSM policy as detailed by Lucas in his blog.


Since ESS Webservice is secured we need to attach the corresponding client policy to our Partner link and need to pass on the credentials of valid user. So as a first step, create a credential store key ESS_KEY_USER with weblogic credentials using the following steps in EM Console.




Now attach the corresponding client policy to our partner link as shown below.



Click pencil icon and modify OWSM policy to specify csf-key as shown below.


This would populate wsm-assembly.xml file with the policy details as below.


Now again deploy the SOA composite and run. This time composite run will be successful and can observe the Request ID of ESS job as the response.


Navigate to ESSAPP –> Search Job Requests to see our job is submitted as expected and shows user as weblogic which is used in csf-key.


You can find sample project here.


There is some run time error coming during BPEL process testing when we specified job description for Schedule Job activity as above. This is due to the missing quotes around so we have to manually open assign activity and surround your job description in quotes as shown below.



SOA 12c – ESS Articles

Creating ESS Job metadata using EM Console

Creating ESS Job metadata using JDeveloper

Creating ESS Schedule metadata

Creating ESS Incompatibility metadata

Creating ESS Job Sets metadata

Retry functionality in ESS Jobs

Creating Async ESS Job Definition

Using Schedule Job activity in BPEL

SOA 12c – Creating ESS Async Job Definition

In the post, we have seen creating ESS Job Definition using synchronous web service. Now, we will look at creating Job Definition using  Asynchronous BPEL web service having 5 min Wait activity to simulate the delayed response.

We will also take a look at other changes required for deployment when new job definition is created in existing ESS application in new package structure.

Create Async Job Definition with help of following screenshots. Make sure that you always use the concrete WSDL.








You need to modify MAR profile to include the new job definition and also adf-config.xml file to include the valid namespace as shown below.



Now deploy ESS application and submit a new request using this job definition. You would observe that ESS job status is in Running state but waiting for the response from BPEL web service as shown below.


Once ESS job receives the response from asynchronous BPEL web service the job will be finished and shows status as Succeeded as shown below.


You will see the similar behavior as above even when you use ADF BC service.

SOA 12c–Retrying ESS Job Request

ESS provides the retry functionality through System Parameter SYS_retries and retry happens when a system error occurs during processing of ESS job request. By default, the value is 0 which means no retries will be performed.

We can set the value or override this property while submitting the request as shown below or can add this parameter at design time in JDeveloper.


Click OK and you can observe this in Parameters section as shown below.


You can observe the number of retries performed in Request Search page by navigating to ESSAPP –> Job Requests –> Search Job Requests as shown below.


SOA 12c–Creating ESS Job Set metadata

Often, we may have to run multiple jobs to finish some functional process. ESS lets you do this using Job Set where we can add multiple jobs as steps in the metadata and submit them as single unit. We can also specify the relationship among these steps either as Serial or Parallel.

Job Set also allows another Job Set to be included so that a parallel job set can have a Serial Job set and vice versa so that more more complex Job Sets can be created.

To create Job Set, select File –> New –> Enterprise Scheduler Metadata –> Job Set.


Give a meaningful name and use the same package as used in previous post.


Click OK and you can observe new Job Set shown in Project Explorer and a new tab is opened.



Let us create Serial Job Set at first. Click + in the Job Set Steps option to add jobs. We can also specify any System Application properties at each step using the respective tabs shown below.


Now your Job Set Steps visual diagram look like below. After the execution, each job step can assume any of the statuses Success, Warning and Error represented by icons in below screenshot. Here, you can define relationship of steps with other steps based on the status. So the following diagram depicts that Job Set execution to stop on occurrence of Error or Warning and proceed to next step (if any) on Success.


Similarly add another step as shown below.



Now modify the relationships of Step1 as shown below.


Now save your changes and deploy to ESS server using the steps mentioned in previous post.

To view the newly created Job Set in EM console, navigate to ESSAPP –> Job Metadata–> Job Sets and do search for EssNativeHostingApp as shown below.


Navigate to ESSAPP –> Job Requests –> Submit Job Request and submit Job Set as shown below.



Run this Job Set when the service is down so that we can see it’s behavior when an error occurred during execution. Observe that both of the steps are resulted into an error as shown below.


And Search Job Requests page shows these requests as below where each step is executed as child request and we can also observe the serial execution by looking at Processing Start Time and Run Time.


Now modify Step1 to Stop on occurrence of error. Now save you changes and deploy your application to ESS server.


Submit request using this Job Set and observe the Job Status as shown below. Now you can clearly observe that only Step1 has been executed because of the above changes.



Now bring up service and submit the Job Set to observe both of the steps are successful.


By default, each step status does determine the terminal state of Job Set. To override this behavior you can define the system property SYS_selectState at step level as shown below and set value to false.










In Parallel job set, all steps execution will start at same time hence we can’t define relationships among steps based on step execution status similar to Serial job set. However, you can still define the step level system parameter SYS_selectState to override default behavior.

Now save changes and deploy application to ESS server. Submit a request using this new Job Set and observe the parallel runtime behavior as shown below.



You can find more information about Job Sets in ESS documentation here and sample project used in this blog can be downloaded from here.

Using EM Console to Create Job Set

We can also create a Job Set in EM console as shown below and the steps look similar to above.






SOA 12c–Creating ESS Incompatibility metadata

We often come across following restrictions when we use ESS jobs because of data corruption issue or for some other functional reason.

  • Only single instance of Job definition should run at particular time.
  • Some jobs should not be run during the run of other jobs irrespective of parameters.
  • Some jobs should not be run during the run of other jobs when acting on same object i.e. having same value for a particular parameter.

In ESS, all of above requirements are addressed by using Incompatibility definition. The first requirement is addressed by using Self Incompatible option. Second and third requirements are addressed by using Global and Domain type incompatibility definitions. In this blog post, we will learn how to create Incompatibility catering to above requirements.

To create Incompatibility metadata, select File –> New –> Enterprise Scheduler Metadata –> Incompatibility.


Give a meaningful name and use the same package as used in previous post. Here we are creating Global type.


Click OK and you can observe the new Incompatibility file shown in the project explorer and a new tab is opened.



Click + icon in Entities section to start adding the jobs.


Select the required jobs and click OK. If we try to save , we will get an error as shown below. As shown below, aAn Incompatibility definition mandates us to select Self Incompatible option when we are adding just single job (entity).


To set this option, double click job in Entities section and choose the option as shown below and click OK. This would make ESS request processor run only single instance of this job at a particular time.


Now save your changes and deploy to ESS server using the steps mentioned in previous post.

To view newly created Incompatibility in EM console, navigate to ESSAPP –> Job Metadata–> Incompatibilities and do search for EssNativeHostingApp as shown below.


To verify the effect of incompatibility, let us submit 2 instances of the same job and schedule them to run at same time as shown below.


On the scheduled time, we can observe that one of the requests is blocked as shown below because of our incompatibility definition.


Once the job with request id 205 is completed, 206 will be kick started by request processor which is evident from the start times shown in the below screenshot.


If you want to make 2 job incompatible with each other, add the other job in the incompatibility definition as shown below.



Similar to above, you can observe the same blocked behavior for these 2 jobs in following screenshots when submitted in EM console at the same scheduled time.



Domain type Incompatibility

You can create incompatibility definition of Domain type using the following screenshots.



Double click on each job in Entities section to select the property to be used for defining the incompatibility. Note that, we can have different property names to define the incompatibility definition.



Now your incompatibility definition should look like below.


Now deploy your ESS project to verify effect of new incompatibility definition. Note that you have to remove SecondOSBJob from previous incompatibility definition before deployment as that is of Global type and is necessary to see effect of this domain type incompatibility which is based on properties.

When used different values for the parameters, you can observe that both jobs started execution at same time which is evident from the date values shown below.


When used same values for the parameters, you can observe that one of the requests is blocked which is evident from the following screenshots.



Using EM Console to Create Schedule

We can also create a Incompatibility in EM console as shown below  and the steps look similar to above.







You can find more information in the documentation here and sample project used in this blog can be downloaded from here.

SOA 12c–Creating ESS Schedule metadata

The real strength of ESS comes from the ability of scheduling a job which is a common use case. ESS provides Schedule as the job metadata to enable the user to schedule job either based on recurrence or on explicit dates. In this post, we will see how to create this Schedule metadata and use it for our ESS job created in the previous post.

To create Schedule metadata, select File –> New –> Enterprise Scheduler Metadata –> Schedule.


Give a meaningful name for the schedule and use the same package as used in previous post.


Click OK and you can observe the new schedule in project explorer.


Let us define a schedule so that ESS job runs for every 2 min thrice considering Start and End dates as shown below. You can also give explicit dates to be included regardless of recurring settings in the respective section. Observe that we are not specifying any ESS job while defining the schedule which enables the reuse of schedule and can be used for any ESS jobs.


Now save your changes and deploy to ESS server using the steps mentioned in previous post.

To view the newly created Schedule in EM console, navigate to ESSAPP –> Job Requests –> Define Schedule and do search for EssNativeHostingApp as shown below.


You can also set the recurrence settings using Every field for seconds, Hours, Days, Weeks etc.. as shown below.


And appropriate selection of days, weeks etc.. will be enabled based on the selected frequency as shown below.


Navigate to ESSAPP –> Job Requests –> Submit Job Request and select the job definition as shown below. Go to Schedule section and click search icon for Use existing schedule.


Select the appropriate schedule and click OK.



To see submitted requests, navigate to ESSAPP->Job Requests –> Search Job Requests and do search for this job.


In the above screenshot, you can observe 3 requests (used 3 as the count in Schedule) have been submitted as child jobs. Click on Parent ID and Request ID to see more information on these job requests.



Using EM Console to Create Schedule

We can also create a schedule using EM console directly as shown below.





SOA 12c–Creating ESS Job metadata (JDeveloper)

In the previous post, We have seen how to use EM Console to create the Job metadata. This did not provide the much information about development and deployment details of ESS application. So in this post, we will use JDeveloper to create ESS Job metadata to call the Service Bus proxy services however the steps remain same for BPEL services too.

Before proceeding with actual creation of job metadata, we will know the terms Hosting and Client Applications.

Hosting Application

ESS Jobs always execute in context of hosting application. When we configure domain for ESS, we get EssNativeHostingApp which is pre-deployed native hosting application that is well suited for custom remote jobs like EJB and web service jobs. However, we can’t execute custom Java jobs.

Client Application

Client applications are typically J2EE application used to submit jobs, query job status and optionally perform updates to ESS metadata. We cannot add ESS job metadata (using MAR archive) directly to the pre-deployed native hosting application and have to deploy through a client application or using metadata API.

More information can be found in ESS documentation here

Creating ESS Application

Select File –> New –> Applications –> Custom Application as shown below.


Enter Application Name.


Choose the Project Features as shown below and click Next.



Choose the EJB Version and select Generate ejb-jar.xml as shown below.


Enter a meaningful value for Application Id.


Click Finish and verify that following files got generated in project.


Creating Job Metadata – Job Definition

Create Job Definition following the screenshots below. Select File-> New –> Enterprise Scheduler Metadata –> Job Definition.


Enter Job name. Since we are going to call a OSB Synchronous service select the corresponding Job type as shown below. Make sure that location includes essmeta directory.


Note that MW_HOME env variable has to be set as shown below to be able to see and select Job Type.


Click Web service icon to select the WSDL.


Select Service Bus as web service type and click search icon.


Enter Service Bus Proxy Service WSDL as shown below and click OK. Make sure that you give the URL of concrete WSDL.


Verify that Service and Port Type are automatically populated. Select the operation and parameterize payload using ESS_REQ as shown below. This context is used to access ESS Parameters defined for Job. Hence we need to create CustomerId parameter. Click OK.


Verify that System Properties are populated as shown below.


Click + in Application Defined Properties section and add CustomerId parameter as shown below and click OK.


Since our job should run in context of the pre-deployed hosting application EssNativeHostingApp, add parameter SYS_effectiveApplciation in System Properties section as shown below.



Make sure you only have the following library references in this file.




Add following contents in this file (See the Observations section below).

        <description>Runtime Session Bean</description>
        <description>Metadata Session Bean</description>
        <description>Async Request Bean</description>


If the EAR file generated from this application is to be deployed, certain MDS partition entries must be specified in this file, so add the following contents. The data source referenced here is automatically created when we configure the domain to include ESS. The namespace mentioned over here (highlighted below) should match the package structure we used for creating job definition.

<adf-mds-config xmlns="">
    <mds-config version="" xmlns="">
                <namespace path="/oracle/apps/ess/custom/osb" metadata-store-usage="ess_custom_metadata"/>
                <metadata-store-usage id="ess_custom_metadata" deploy-target="true" default-cust-store="false">
                    <metadata-store class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
                        <property name="jndi-datasource" value="jdbc/mds-ESS_MDS_DS"/>
                        <property name="repository-name" value="mds-ESS_MDS_DS"/>
                        <property name="partition-name" value="essUserMetadata"/>


We have to create the following deployment profiles to be able to deploy:

  • Project level EJB JAR deployment profile.
  • Application level MAR deployment profile.
  • Application level EAR deployment profile

EJB JAR Deployment Profile

Use the following screen shots to create project level EJB JAR profile.






MAR Deployment Profile

Use the following screen shots to create application level MAR profile.






EAR Deployment Profile

Use the following screen shots to create application level EAR profile.






Deploy the EAR file of ESS application as shown in following screenshots.






Here, essUserMetadata is partition used by EssNativeHostingApp. We can observe deployment log as shown below.


Submitting the request

In EM Console, navigate to Scheduling Services –> ESSAPP-> Job Requests –> Submit Job Request. Select application as EssNativeHostingApp and choose the job definition as below and select OK.



Once the job run is successful, you can see the status as shown below.


The sample application can be downloaded from here.


  • Though we add only ESS Job Support and ESS Client Support features during application creation, we see ESS Host Support as well in Project feature section as shown below.


  • Unable to see the Job definitions in ESS while submitting requests, when used package structure (which is effectively a namespace) that does not contain /oracle/apps/ess. Section 1.2.10 of this documentation clearly mentioning that the  job definition must be created in  the namespace /oracle/apps/ess/custom.
  • Unable to refer the WSDL from SOA_MDS or File System in the Web Service chooser during Job definition creation and is resulting into the following error as shown below.



  • The data source mds-ESS_MDS_DS is to be  targeted to AdminServer as shown below, so that we will be able to select data source during deployment.


  • Initially thought, there is no need of ejb-jar.xml in this ESS application as it’s used predominantly to specify Application Name. But was getting following error during deployment when this file is not present in application or the file has empty contents. So at minimum, this file should have the contents as mentioned above.

         <May 19, 2015 8:47:48 PM IST> <Error> <Deployer> <BEA-149205> <Failed to initialize the application "Ear_EssSampleAppl" due  to error Error parsing META-INF/application.xml Error parsing META-INF/application.xml

SOA 12c–Creating ESS Job metadata (EM Console)

In this post, We will use the EM Console to create ESS Job metadata  to call the Service Bus proxy services however the steps remain same for calling BPEL service too.


During domain creation, we should select the following options to create ESS Managed Server and EM Plugin for ESS. EM Plugin for ESS enable us to monitor and manage submitted ESS jobs.


You should see the EM Console as shown below on successful domain creation and starting the Admin and ESS servers. Observe that Scheduling Services is shown having ESSAPP.


If you don’t select EM plugin for ESS option during domain creation, your EM console will look like below with no Scheduling Services.


You can do ESS health check using >:>/ess">>:>/ess">>:>/ess">http://<<hostname>>:<<port>>/ess which brings up the following screen.


Click Check Health for this ESS Server which submits a sample job and give us back the status of ESS server as shown below.


You can verify status of this sample job from Search Job Requests as shown below. The navigation to this page is given later in this post.


You can find more information inn ESS documentation here.

Creating Job Definition

First, we need to create Job Metadata so that we can execute the ESS job or schedule as and when required. Job Definition contains all required metadata to run the job. We can use JDevloper or EM Console to create job definition. In this post, we will demonstrate usin EM Console.

Right click on ESSAPP and select Job Definitions as shown below.


Click Create to proceed with creation of new ESS Job Definition.


Provide Job name and other information as shown below. We need to select Job Type as SyncWebserviceJobType as we want to call a service bus Proxy Service. Click Select Web Service to select the WSDL of service.


Provide WSDL URL and choose Web Service Type as Service Bus. Click OK.


Observe that the services listed in WSDL are shown. Select the Port Type and Operation as required which shows up the sample payload as shown below. Since we want to allow user to enter Customer ID, we have to parameterize payload using ESS_REQ token which is used to access request arguments. So in our case, we need to define an argument with name CustomerId.


Click OK and observe lot of System Properties are populated automatically as shown below.


To define argument for ESS job, click + icon in Application Defined Properties section to bring up following Popup. Given name as CustomerId and Type as String as shown below and click OK.


Now observe that a new Job Definition is created as shown below.


Submitting Job

We can manually submit ESS job or use a schedule to run it programmatically. For now, let us proceed with manual submission so right click ESSAPP and choose Submit Job Request as shown below.


Choose Job Definition by clicking search icon as shown below.



Click OK and enter value for CustomerID Job Parameter as shown below.


Click OK to submit ESS job and observe the status and log as shown below. Since it’s a simple service call, the ESS job did not take much time.


You can open log file shown above and verify the output as expected.  Since it’s a sync call, we have received service response and same is logged.


To manage the submitted jobs, we can navigate to the Search Job Requests page using navigation shown below.


Here, you can search for submitted jobs using different search criteria and also can do Cancel, Hold and Resume of job depending on current status of Job.


Note: The use case considered here does not actually qualify as ESS job and not of batch job nature and used just for demonstration purpose. ESS is more suitable for batch jobs as you can schedule and run asynchronously in it’s own JVM.


Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 379 other subscribers

Enter your email address to follow this blog and receive notifications of new posts by email.

%d bloggers like this: