Blog

Configuration Plans for SOA Suite 12C

In this blog, I’ll cover how to replace URLs and other environment specific fields in a SOA composite. The 3 options I will discuss are:

  1. Composite specific configuration plan
  2. Shared Configuration Plan
  3. Global tokens

For each of these approaches to cleaning up environment specific fields, we will show how the Oracle capability works, then show how Flexagon’s FlexDeploy product supports each approach. My example will be using CreateOrderService Composite that has a call to GetOrderDiscount composite. I am running it on a local 12c SOA Server, and need to deploy it to a central 12C test server. Although this Blog is written for SOA 12C, the capability is virtually identical to the 11G capability. To see the required fix up in this composite, I open the composite.xml, see the local reference highlighted below:

We will clean up this URL using the 3 above techniques to show the strengths of each approach. The blog today will cover composite specific configuration plans, in future blogs we will cover the shared configuration plan and global tokens.

1. Composite Specific Configuration Plan

With the composite specific configuration plan, we will generate a plan, and customize it specifically for the CreateOrderService composite.

Generating the Configuration Plan with JDeveloper

To generate the configuration plan in JDeveloper, right click on the composite.xml. Select “Generate Config Plan” and give the plan a name. This name is often specific to an environment because each environment will have its only values that you will need to set the URL to. For example, the Dev URL might start with http://devsoa01:8001, but in the QA environment being fronted by a load balancer, the URL is http://soaqa01:80.

Adjusting the Plan

Once the plan is generated, we can open the plan and adjust it for the environment we are going to deploy the composite to. In this case, we need to adjust the location for the reference SOAP_GetOrderDiscount. At times, you may need to handle environment specific content in your imports, services or other parts of the composite.xml. You can also adjust other files like JCA files or WSDLs. Note how specific this generated plan is, it has been generated specifically for the CreateOrderService composite. The section of the generated plan requiring fix up is below:

After updating the location url, the Configuration plan looks like:

Deploying with the Configuration Plan with JDeveloper

Now we are ready to deploy the composite to the development environment. When deploying from JDeveloper, select the checkbox indicating that we will use the config plan, then select the plan you would like to use. Then proceed with the remaining deployment screens. The Config plan you selected will perform the required fix up.

Using a Specific Plan with FlexDeploy

To use the configuration plan with Flexagon’s FlexDeploy, generate the plan as described above. In the SOA deploy workflow, open the soaDeploy step and configure the configuration plan. In the example below, I use the Environment Code (DEV in this case) and the project name (CreateOrderService in this case). The plugin will then apply this plan when you deploy from FlexDeploy.

Using Workflow Properties in a Config Plan

FlexDeploy provides the ability to create user-defined workflow properties that can be set based on environment. In this case, I defined a property named SOAURLPREFIX. We now only need one configuration plan for the composite. When using these workflow properties, I would change the name of the config plan to be CreateOrderService_configplan.xml (it is not specific to an environment anymore!). This property replacement will handle mapping the URL for each environment. Central administrators can manage the actual values in FlexDeploy instead of each developer setting the actual URL in the config plan, you just reference the property name.

I now update my config plan to use this property. To reference a property in your config plan use ${{…}} to delimit the property name. The updated config plan is below:

Then we can configure this property in FlexDeploy on the DEV environment for the SOA instance:

Useful link

Oracle 12C documentation:

https://docs.oracle.com/middleware/1213/soasuite/develop-soa/soa-composite-deploy-jdev.htm

2. Shared Configuration Plan

The shared configuration plan is a great approach (my preferred). You no longer need to generate and customize the configuration plan for every composite, instead you have generic plans you use by environment. So if you have a dev, test, and prod, you would have 3 configuration plans, one for each environment. These generic plans can also be less error prone, since they can be set up once and used by everybody. The shared configuration plan uses the search and replace capability to find and replace the hostnames in your composite.

Here is an example Shared Configuration Plan:

<?xml version=”1.0″ encoding=”UTF-8″?>
<SOAConfigPlan xmlns:jca=”http://platform.integration.oracle/blocks/adapter/fw/metadata”
xmlns:wsp=”http://schemas.xmlsoap.org/ws/2004/09/policy”
xmlns:orawsp=”http://schemas.oracle.com/ws/2006/01/policy”
xmlns:edl=”http://schemas.oracle.com/events/edl”
xmlns=”http://schemas.oracle.com/soa/configplan”>
    <composite name=”*”>

        <import>

            <searchReplace>

                <search>
http://localhost:7001</search>

                <replace>http://badhost</replace>

            </searchReplace>

        </import>

        <reference name=”*”>

            <binding type=”ws”>

                <attribute name=”location”>

                    <searchReplace>

                        <search>http://localhost:7001</search>

                        <replace>http://testhost</replace>

                    </searchReplace>

                </attribute>

            </binding>

        </reference>

    </composite>

    <wsdlAndSchema name=”*”>

        <searchReplace>

            <search>
http://localhost:7001</search>

            <replace>http://testhost</replace>

        </searchReplace>

    </wsdlAndSchema>

</SOAConfigPlan>

You will notice that in the imports, I am replacing the host to a badhost. The reason is we leverage MDS or relative pathing for XSDs and abstract WSDLs, so we would not be intentionally importing anything that would be referenced through our server. Occasionally, someone forgets to clean up an import, this helps remind them (they will fail).

There also may be other properties that you need to replace based on your organization, this includes endpointURI, oracle.webservices.auth.userid and oracle.webservices.auth.password as examples. To replace these, you can use the same pattern as above.

Another challenge with shared configuration plans in 12c is you may be testing locally on your desktop and not on a shared server. Which means the hostname you search for could be different for each developer. I recommend using localhost in this case during development so you can use the consistent hostname in the search as I did above.

You will typically save these shared configuration plans where you can access them when deploying. If you are deploying from JDeveloper, you will select the shared configuration plan as below, then follow the normal deployment steps.

Using Shared Configuration Files in FlexDeploy

To use a shared configuration plan, it works basically the same as it did in the last blog. In the SOA deploy workflow, we open the SOA deploy plugin call and set the input to the name of the configuration plan.

Other Useful Links

An 11g overview of shares configuration plans:

http://javaoraclesoa.blogspot.com/2013/01/generic-configuration-plan-for-soa.html

3. Global Tokens

Global Tokens allow you to define name/value pairs for the host, port, and protocol. In the createOrderService composite, I am going to use SOAServerURL as the “name” with a “value” of http://testhost:80. Using tokens puts the configuration back into the administrator’s hands and provides a central definition of the various URLs used by an organization.

Global tokens are pretty simple, but have a few limitations.

  • Tokens only work in the composite.xml
  • They are only supported for the host, port, and protocol at the ws.binding location and any property under the reference tag
  • Tokens will not work for import element of the composite.xml file.

There is a preconfigured token “serverURL” that can be set on the SOA Infrastructure -> Common Properties page. It can be used for any calls to services on the same SOA server. I will not be using the serverURL in this blog, but it can be useful.

Configuring the Token

Let’s configure a token on our SOA server and update the composite.xml to use it. First we log into EM, go to SOA Infrastructure -> Common Properties -> Token Configurations as below:

091015_2054_Configurati1.png

When the Token Configuration screen comes up, we will manually configure our token by selecting the Modify Configuration File option and completing it similar to below:

091015_2054_Configurati2.png

Once you saved the value, the token will be available for use.

Back in JDeveloper, we will update the composite to refer to the token using ${Token Name}, in our case ${SOAServerURL}.

091015_2054_Configurati3.png

You can now redeploy your process, we do not need to use a configuration plan this time since the URL fix up will be handled by the Token replacement at runtime.

Other Useful Links:

12c Oracle documentation on Global Tokens:

https://docs.oracle.com/middleware/1213/soasuite/administer/soa-infrastructure-configur.htm#SOAAG97785

A-Team Chronicles on the usage of Global Tokens in 11g:

http://www.ateam-oracle.com/using-global-token-in-ps6-11-1-1-7/

What’s Your Preference?

What is your preferred method to replace URLs and other environment specific fields in a SOA composite? Let us know in the comments!

2 thoughts on “Configuration Plans for SOA Suite 12C”

  1. RAVISH KUMAR JHA

    Hello Greg,

    Thanks for the article. Its indeed very useful.

    One thing I have noticed though that config plan doesn’t work on Cloud adapter’s .jca files. E.g. Let’s say in .jca file for Salesforce adapter it using below property :

    If I want to replace “SFDC-XYZ-KEY” by “SFDC-ABC-KEY” using wsdlAndSchema/searchReplace then its not working and after deployed the value remains as same as what is mentioned in .jca file.

    Did you come cross this scenario ever and how did you get over it?

  2. It surprises me that config plan is not working on a jca file. A couple of options if you cannot get the config plan to replace a specific value is:

    1. With FlexDeploy, you can use workflow properties and replace ${{PROPERTYNAME}} in a jca file without using a configuration plan.

    2. If you are not using FlexDeploy, a simple script can expand the sar, replace values (using a tools like sed), and re-jar the sar file.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top