soaDeploy

Performs environment-specific property replacement, determines next composite revision and deploys the SCA artifact or the patch artifact (12.2.1+ only) to the server or cluster. You must have built SCA artifact or the patch artifact (12.2.1+ only) as part of soaBuild operation prior to running deploy, i.e. soaBuild execution generates artifact file and is recorded in FlexDeploy as project version and then deployment is done using that project version to specific environments. Composite specific configuration plans or global configuration plans can be used during deploy, see information on project property and plugin input below.

Composite revision purging is an optional feature that allows the developer to control the number of revisions actively deployed on the server upon successful deployment of the composite.

This operation should be run on any SOA managed server endpoint. 

Configure SOA Server Host and Port for any SOA managed server and after deployment composite will be available on all managed servers in the SOA cluster.

Environment/Instance Properties

Property Name

Property Code

Required

Description

SOA Server Host

FDSOA_SERVER_HOST

Yes

Host name of the SOA managed server.

SOA Server Port

FDSOA_SERVER_PORT

Yes

Port number of the SOA managed server.

Weblogic Admin User

FDWLS_ADMIN_USER

Yes

Admin user name for WebLogic server.

Weblogic Admin Password

FDWLS_ADMIN_PASSWORD

Yes

Weblogic Admin User password for WebLogic server.

MDS UserID

FDMDS_USERID

Yes

User name for MDS access.

MDS Password

FDMDS_PASSWORD

Yes

Password for MDS UserID.

MDS JDBC URL

FDMDS_JDBCURL

Yes

Database URL for MDS access.

Oracle SOA Home

FD_ORACLE_SOA_HOME

Yes

Oracle SOA Home, indicates where SOA Suite is installed.

SOA Extend Classpath

FDSOA_EXT_CLASSPATH

No

Ability to extend the plugin classpath for external java classes or custom xpath functions

Composite Revisions To KeepFDSOA_REVISIONS_TO_KEEPNoNumber of composite revisions to retain on the server after successful deployment

Project Properties

Property Name

Property Code

Required

Description

SOA Composite Name

FDSOA_COMPOSITE_NAME

Yes

Name of composite that is being deployed.

SOA Deploy Config Plan

FDSOA_DEPLOY_CFG_PLAN

No

Ability to define config plan specific to a composite. (see soaDeploy#configurationplans section below).

When using composite specific configuration plans, they are stored in configPlans folder in artifacts, but you do not need to specify configPlans folder in this property value, just provide name of the configuration plan file as appropriate. You can also override this property for various environments to use different value for each environment. For example, mycomposite-cfgplan.xml

SOA Partition

FDSOA_PARTITION

Yes

Name of the partition to hold the composite on the server.

SOA Overwrite Revision

FDSOA_OVERWRITE_REVISION

Yes

Flag to indicate if the composite revision on the server should be overwritten or a new revision created (soaDeploy#compositerevision).

SOA Make Default Revision

FDSOA_MAKE_DEFAULT_REVISION

Yes

Flag to indicate if the deployed composite should be marked as the default revision.

Inputs

Input Name

Input Code

Required

Description

Deploy Config Plan

FDSOA_INP_DEPLOY_CFG_PLAN

No

Deployment config plan that is to be used for the composite deployment. Takes a Wildcard expression or filename. Can be a relative or absolute path (see soaDeploy#configurationplans section below).

Composite Revision

FDSOA_INP_REVISION

No

Provide the composite revision, this input will override the SOA Overwrite Revision project property (soaDeploy#compositerevisions).

Stop On Purge FailureFDSOA_INP_STOP_ON_PURGE_FAILNoProvides the ability to control whether a failed purge stops the workflow (default is False)
Activate Purge On DeployFDSOA_INP_ACTIVATE_PURGENoActivates the composite revision purge on deploy feature (default is False)
Preview Mode For PurgeFDSOA_INP_PURGE_PREVIEWNoActivates the purge preview mode. If purge is activated, preview mode will show in the logs the composite revisions that would have been purged with no purge occurring.  (default is False) soaDeploy#CompositeRevisionPurge for examples
Stop After DeployFDSOA_INP_STOP_AFTER_DEPLOYNo

Stops the most recently deployed composite revision after successful deployment (default is False).  If other revisions are active, this input will adjust the default revision.

Note that the shutdown is asyncronous, so it is possible that a polling composite could poll before it is shutdown. This is the same caveat that would apply to all SOA deployments whether performed through Ant or the Oracle APIs. The shutdown will happen within moments of the deployment.

Outputs

Output Name

Required

Description

FDSOA_DEPLOYED_REVISION

Yes

Revision of the composite for this deployment.

FDSOA_LAST_DFLT_REVISION

Yes

Revision of the composite for the previous default revision.

Artifacts

This operation consumes an SCA composite jar from the artifacts repository.

Endpoint Selection

This operation will select all available endpoints associated to the Environment/Instance.

Endpoint Execution

This operation will execute on any one of the selected endpoints and will be random in the determination of which one.

Special Considerations

Utilize the SOA Extend Classpath environment variable to extend the plugin classpath to allow the compile to succeed with custom java classes or xpath functions.

NOTE: when patching a long running process revision that isn't the default revision, the patching process will make the patched revision the default revision.

Composite Revisions 

The revision for a composite is calculated unless either Composite Revision (plugin input) is used or SOA Overwrite Revision (project property) is checked.  The input will override all revision logic and use the value that is passed in.  If the input is empty and the project property is unchecked, then the plugin will determine the largest revision on the server and increment the revision before deploying.  The revision format is N.nn[.nn][.nn] with an initial value of 1.0, with

  • N – initial segment that will increment with no limitation
  • nn – 0 through 99, when segment hits 100 it rolls to the next higher segment


Current revision

Next revision
1.01.01
1.992.00
1.0.01.0.01
1.0.991.01.00

Composite Revision Purge 

The composite revision purge will undeploy specific revisions based on the "Composite Revisions To Keep" environment/instance property, defaulted to 1.  The retained revisions will start at the default revision and retain composites until the property value is met.  If there are more recent revisions than the default revision, those recent revisions will also be retained but will not count against the property value.  Default revision is bold and Composite Revisions To Keep is 2.

Revision Ex 1Action
Revision Ex 2Action
1.01purged
1.01purged
1.02purged
1.02kept due to property count
1.03purged
1.03kept due to default revision
1.04kept due to property count
1.04kept due to more recent than default revision
1.05kept due to default revision
1.05kept due to more recent than default revision

In addition, the Preview Mode For Purge input can activate the preview feature that will show the revisions that would have been purged in the logs.  No purge will occur in preview mode.

Configuration Plans 

Configuration plans are used to automatically cleanup environment specific information in a composite.xml file during deployment. Information that can be changed includes URL hosts and retry values, to name a few items. Configuration plans can utilize property replacement to utilize FlexDeploy properties.  Utilizing FlexDeploy properties allows configuration plans to become re-usable.

Composite specific configuration plans that were captured during build in configPlans sub-folder, are available during deploy step along with SCA Jar file.

Configuration plan can be specified using SOA Deploy Config Plan project property and/or Deploy Config Plan plugin input. The plugin input will take precedence over the project property. Deploy Config Plan input can be either an absolute path to a global configuration plan or composite configuration plans file name. Composite configuration plans are placed in FD_TEMP_DIR by FlexDeploy SOA Plugin (from configPlans artifact directory), so you do not need to qualify it, just provide name when using composite specific configuration plans.

There are two approaches to Configuration Plans:

Composite specific

A composite specific configuration plan is created directly in the composite project using the JDeveloper wizard.  Right click on the composite.xml file and select "Generate Config Plan".  Provide the plan a name and it is recommended that you add the FlexDeploy environment code in the name.  

When a configuration plan is generated the file will contain most of the composite.xml content, there will be many lines that contain static content and will change infrequently. Removing all static content from the file will keep the configuration plan easier to update. Also, if static content is changed in the composite.xml file but the configuration plan is unchanged, the configuration plan will overwrite the composite.xml changes on deployment.

Composite specific approach will require a configuration plan for each environment for each composite since the goal is to cleanup host names as we progress through environments. The two blocks below show examples of what a configuration plan would look like for a DEV (hard code the host name) and QA (utilizing FlexDeploy property replacement) environment. You can decide to either hard code such values in each environment specific Configuration Plan or you can use FlexDeploy property replacement support.

DEV Configuration Plan (HostName is hardcoded)
<?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="processOrder">
      <reference name="validateCredit">
         <!--Add search and replace rules for the binding properties-->
         <binding type="ws">
            <attribute name="location">
               <replace>http://soalt06.flexagon:8001/soa-infra/services/order/validateCredit/validateCredit_client_ep?WSDL</replace>
            </attribute>
         </binding>
      </reference>
   </composite>
   <wsdlAndSchema name="Schemas/processOrder.xsd|WSDLs/processOrder.wsdl">
      <searchReplace>
         <search/>
         <replace/>
      </searchReplace>
   </wsdlAndSchema>
</SOAConfigPlan>
QA Configuration Plan (using FlexDeploy property replacement)
<?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="processOrder">
      <reference name="validateCredit">
         <!--Add search and replace rules for the binding properties-->
         <binding type="ws">
            <attribute name="location">
               <replace>http://${{FDSOA_SERVER_HOST}}:8001/soa-infra/services/order/validateCredit/validateCredit_client_ep?WSDL</replace>
            </attribute>
         </binding>
      </reference>
   </composite>
   <wsdlAndSchema name="Schemas/processOrder.xsd|WSDLs/processOrder.wsdl">
      <searchReplace>
         <search/>
         <replace/>
      </searchReplace>
   </wsdlAndSchema>
</SOAConfigPlan>


On the soaDeploy operation used in the deployment workflow, change the FDSOA_INP_DEPLOY_CFG_PLAN input to a groovy expression similar to:

"./" + FD_ENVIRONMENT_CODE + "*_cfgplan.xml".  

This will allow the workflow to remain re-usable across all composite deployments even though the configuration plans are specific to a composite.

Shared (recommended method)

A shared configuration plan provides the same functionality as a composite specific configuration plan but with the added benefit of not needing to remember to generate a configuration plan for new composites or new environments.  The shared configuration plan will be managed seperately from the composites and deployed independently to a common location on the servers.  With a shared configuration plan, utilizing FlexDeploy property replacement is a must.  Shared configuration files can be either environment specific or global across all environments due to the use of property replacement.

You will notice that in the import section of the conguration plan, any host name is being replaced with a string "change to mds ref".  The reason is that when leveraging MDS or relative paths for XSDs or abstract WSDLs, there should be no references to the server.  When a developer forgets to clean up the composite correctly, this helps to remind them because the deploy will fail with a message that includes the string above.

There may be other properties that need to be replaced based on your organization, which include endpointURI, oracle.webservices.auth.userid and oracle.webservices.auth.password, as examples.  These can be replaced utilizing the same pattern as above.

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>localhost</search>
			<replace>change to mds ref</replace>
		 </searchReplace>
       </import>
	  
	  <reference name="*">
         <!--Add search and replace rules for the binding properties-->
         <binding type="ws">
            <attribute name="location">
			    <searchReplace>
				   <search>localhost</search>
				   <replace>${{FDSOA_SERVER_HOST}}</replace>
				</searchReplace>
            </attribute>
         </binding>
      </reference>
   </composite>
</SOAConfigPlan>


On the soaDeploy operation used in the deployment workflow, change the FDSOA_INP_DEPLOY_CFG_PLAN input to a groovy expression similar to following if the shared plan is environment specific:

"/shared/location/" + FD_ENVIRONMENT_CODE + "*_cfgplan.xml"

If the shared plan is global, use an expression like: 

"/shared/location/acme_cfgplan.xml"

This will allow the workflow to remain re-usable across all composite deployments even though the configuration plans are specific to a composite.

Replacement Properties 

All files with the following suffix ("xml", "txt", "wsdl", "bpel", "jca", "xsd", "componentType", "dvm", "xref") within the composite file structure are pre-processed by the plugin to transform any defined replacement properties.

A deployment config plan file or composite.xml will have server host names within it and will vary from environment to environment.

The following macros are not currently supported in the footer:
  • style