Oracle® Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack 11g Release 1 (11.1.1.7) Part Number E17364-07 |
|
|
PDF · Mobi · ePub |
This chapter discusses the approach to create Deployment Plans for SOA artifacts extended using AIA Extension mechanism. AIA Deployment Plan Generator utility helps generate Deployment Plans for extended artifacts and AIA Installation Driver (AID) helps deploy them. The chapter also outlines the approach to deploy non-native SOA artifacts. The Pre-Built Integrations or direct integrations delivered by Oracle AIA use the features outlined in this chapter to deploy both native SOA artifacts and non-native artifacts.
This chapter includes the following sections:
AIA Project Lifecycle Workbench contains the integration specific details of the Pre-Built Integration or direct integrations, like the tasks involved and the service components involved in each task. Project Lifecycle Workbench supports only Oracle SOA artifacts which are created using FMW technologies such as BPEL or Mediator. These are called native artifacts and they are supported by AIA Foundation Pack tools such as Project Lifecycle Workbench, Harvester, Deployment Generator, and AID. When a composite is harvested, the annotation details of the composite are stored in the lifecycle database. The Bill of Material (BOM) of a Pre-Built Integration can be exported as BOM.xml using the Generate BOM feature in AIA Lifecycle Workbench. The existing artifacts can be modified and new natively supported artifacts can be added using AIA Lifecycle Workbench and a BOM.xml file can be generated.
The BOM.xml file consists of a list of artifacts that constitute a project and their ensuing annotations. Deployment Plan Generator reads the annotations and other information in BOM.xml file as input and generates deployment plan for the selected services. The deployment plan is used to perform the required configurations and deploy the services to the Fusion Middleware server using AID.
Figure 8-1 illustrates the flow for extending and deploying native artifacts.
You may be required to deploy artifact types that are not supported by the Project Lifecycle Workbench and AIA Harvester. For instance, your integration may require the use of Java Web Services or interaction with third-party services. In such cases, the deployment of those artifacts is supported by invoking custom scripts such as Shell scripts or ANT scripts from the Deployment plan. AID supports deployment of these supplementary artifacts. However, modify and add new non-native artifacts outside AIA Lifecycle Workbench.
Figure 8-2 illustrates the flow for extending and deploying non-native artifacts.
The following files are used in the deployment plan generation and deployment of AIA artifacts:
<PIP_Name>DP.xml: This deployment plan file orchestrates the deployment of natively supported services and the configuration required for those services. Oracle AIA delivered Pre-Built Integrations usually have their deployment plans under AIA_HOME/PIPS/<pip name>/DeploymentPlans. Oracle AIA Foundation Pack customers are also advised to save their Deployment plans under the corresponding folder in the AIA_HOME/PIPS/ folder.
<PIP_Name>SupplementaryDP.xml: Supplementary Deployment Plan contains configuration required for deployment of non native services. A Pre-Built Integration installation may or may not constitute the deployment of non-native artifacts. If it does, then the corresponding Pre-Built Integration supplies a Supplementary deployment plan at AIA_HOME/PIPS/<pip name>/DeploymentPlans.
<PIP_Name>HS.xml:HS is a Harvester Settings file that harvests the deployed services to OER for a Pre-Built Integration project from the SOA runtime. When a Pre-Built Integration is installed, the file can be located in AIA_HOME/PIPS/<pip name>/HarvesterSettings folder.
For more information about the Harvester settings file, see Chapter 5, "Harvesting Oracle AIA Content."
You can also generate deployment plans for ODI and include them in your deployment plans.
For information about generating a deployment plan for ODI, see Chapter 9, "Generating a Deployment Plan for ODI."
Note:
You can deploy the artifacts only after installing Foundation Pack.
For information about installing Foundation Pack, see Oracle Fusion Middleware Installation and Upgrade Guide for Oracle Application Integration Architecture Foundation Pack.
Oracle AIA Foundation Pack provides a comprehensive mechanism to extend the Oracle shipped deployment plans. Most often, integration scenarios require modifications to AIA-shipped integrations or Pre-Built Integrations before they are deployed to customer environments. The modifications include changes to Pre-Built Integration functionality, and they often manifest on the changes to Pre-Built Integration deployment configurations. This section discusses how to modify or extend both native and non-native artifacts that are shipped with Oracle AIA.
If you must modify the native artifacts or add new natively supported artifacts, modify existing annotations or add new annotations, generate a BOM.xml using Project Lifecycle Workbench. Use the BOM.xml to run Deployment Plan Generator to generate a new deployment plan. As this is the process employed by Oracle AIA, this file will be equivalent to <PIP_Name>DP.xml. However, save it at a different file path with a different name.
Note:
You can modify and add new native artifacts and generate a deployment plan to include both. However, Oracle AIA strongly recommends that you generate a new deployment plan on a different name so that these extensions do not get affected when upgrades are done or patches are applied. For example, <PIP_Name>CustomDP.xml
For more information about modifying AIA Artifacts or making custom extensions to AIA Artifacts and generating the BOM XML input file, seeChapter 6, "Working with Project Lifecycle Workbench Bills of Material."
To modify non-native artifacts or add new non-native artifacts, copy-paste AIA-shipped <PIP_Name>SupplementaryDP.xml with a different name, for example <PIP_Name>CustomSupplementaryDP.xml and modify the artifacts manually. This ensures that your customizations do not get overwritten during AIA upgrades or patch updates. If the Pre-Built Integration does not supply a SupplementaryDP.xml file, create one and add the artifacts to be modified manually.
As non-native artifacts cannot be harvested using the Project Lifecycle Workbench UI, you cannot generate a deployment plan using DPG. Deploy non-native artifacts in the <PIP_Name>CustomSupplementaryDP.xml using the deployment command and also undeploy the artifacts manually.
Note:
You cannot modify and add new non-native artifacts in the same AIA-shipped <PIP_Name>SupplemenatryDP.xml.
This section discusses the input required for Deployment Plan Generator, the process for generating the deployment plan, and the output generated
Deployment Plan Generator takes the following four command line inputs.
BOM.xml: The BOM file is exported from the Project Lifecycle Workbench UI for the projects that are selected. BOM.xml contains the annotations to the services that are specified by users. These annotations are read by the Deployment Plan Generator to generate the deployment plan for the selected services. This deployment plan is used to configure the required configuration and deploy the services to the FMW server.
ODIBOM.xml: This ODIBOM file is to be generated manually. It should contain the list of artifacts to be imported to ODI along with the list of tokens to be replaced and encrypted. These annotations, in addition to some other information, are read by Deployment Plan Generator to generate the deployment plan for ODI.
File path for the Deployment Plan to be generated: The naming convention for the deployment plan is <projectCode>DP.xml. The Deployment Plan Generator gives a warning message if the given input argument for deployment plan does not follow the naming standards.
File path of the HarvesterSettings.xml to be generated: The naming convention for the HarvesterSettings is <projectCode>HS.xml. The Deployment Plan Generator gives a warning message if the given input argument for Harvester Settings does not follow the naming standards. Set the path for the file to AIA_HOME/pips/<projectCode>/HarvesterSettings as the deployment plan refers to this file during execution.
To execute Deployment Plan Generator:
Set environment variables by running the commands specific to your platforms:
For UNIX/Linux based systems, run source <AIA_HOME>/aia_instances/<instance_name>/bin/aiaenv.sh
For Microsoft Windows, run <AIA_HOME>/aia_instances/<instance_name>/bin/aiaenv.bat
Run the following command for executing the Deployment Plan Generator. This can be executed from any location.
ant –f ${AIA_HOME}/Infrastructure/Install/AID/AIADeploymentPlanGenerator.xml –Dinput=<full file path of lifecycle BOM.xml> -DDeploymentPlan=<output file path of the generated deploymentplan. For example ${AIA_ HOME}/PIPS/<pipName>/DeploymentPlans/<pipName>DP.xml> -DHarvesterSettings=<output file path of the generated HarvesterSettings file. For example ${AIA_HOME}/PIPS/<pipName>/HarvesterSettings/<pipName>HS.xml> [-DODIinput=<ODI BOM file name along with absolute path of the file>]
Note:
While executing the deployment plan using automated scripts in addition to the above command line arguments, pass weblogic username and password. For example, -DUsername=<weblogic admin username> -DPassword=<weblogic admin password>.
Note:
AIA recommends that the output for the run-time Harvester Settings file be AIA_HOME/pips/<PIP_Name>/HarvesterSettings as deployment plan refers to this file during execution.
Provide at least BOM.xml or ODIBOM.xml as input. If you are providing both files as input, ensure that the ProjectCode is same for both the BOM files. If you are providing only ODIBOM.xml as input, then skip the HarvesterSettings.xml filepath input.
Deployment Plan Generator produces the following output:
Deployment Plan: The deployment plan that is generated is very specific to the BOM.xml and ODIBOM.xml which are given as input. The services which are specified in BOM.xml can be deployed and configured by using this deployment plan. The artifacts list provided in the ODIBOM.xml is processed and imported into the ODI with the deployment plan. Deployment Plan Generator generates a combined deployment plan if both the BOM and ODIBOM are provided. This deployment plan is executed by feeding it to AID.
Undeployment Plan: The undeployment plan is generated at the same location as the deployment plan. The naming convention for the undeployment plan is <projectCode>UndeployDP.xml. This contains undeploy tasks for all the services that are deployed and the Configurations done as part of Deployment Plan. There is no undeployment plan for ODI artifacts. The undeployment plan is also executed using the AID.
Harvester Settings File: A Deployment Plan Generator utility generates a HarvesterSettings.xml file for harvesting the deployed services to OER. The list of services to be harvested are taken from the BOM.xml.
You can set conditions to your deployment plans for the following scenarios:
Choose artifacts to be deployed depending on the version of participating application.
Define conditional logics depending on deployments and sequences for two different projects. For example, project A may lay out certain artifacts which must be conditionally kept or removed while deploying project B.
Define the conditions in a deployment policy file. The deployment policy file supports all the artifact types in configurations and deployments except the adapter types (JmsAdapter, DbAdapter, AqAdapter, OracleAppsAdapter). However, for composites define an additional condition.
The deployment policy file is passed as an additional input to AID through -DDeploymentPolicyFile variable. When AID begins execution, it checks if -DDeploymentPolicyFile variable is passed as a command line input. When it finds the variable, AID creates a copy of the original deployment plan with the name <Original_DP_Name>-Conditional.xml. AID checks whether there are changes required to the original deployment plan based on inputs from the deployment policy file, picks up the modified deployment plan and executes them during installation.
Create the deployment policy file manually. The sample deployment plan shown in Example 8-1 helps you understand deployment policy file.
Example 8-1 Sample Deployment Plan File
<DeploymentPlan component="AIADemo" version="3.0"> <PreInstallScript> </PreInstallScript> <Configurations> <Datasource name="FODDS" jndiLocation="jdbc/fodDS" wlserver="fp" database="participatingapplications.AIADemo.db.aiademoparticipatingapp" action="create" xa-enabled="true"/> <JMSResource wlserver="fp" jmsResourceType="ConnectionFactory" jmsResourceName="AIADemoCF" jmsresourcejndi="jms/aia/AIADemoCF" action="create" jmsModuleName="AIAJMSModule" jmsSubDeploymentName="AIASubDeployment"/> </Configurations> <Deployments> <Application name="WebServices_WebLogicFusionOrderDemo_ CreditCardAuthorization" filelocation="${AIA_ HOME}/samples/AIADemo/Services/CreditCardAuthorization/deploy/WebServices_ WebLogicFusionOrderDemo_CreditCardAuthorization.war" wlserver="fp" failonerror="true" action="deploy"/> <Composite compositeName="AIADemoUpdateSalesOrderEBS" compositedir="${AIA_ HOME}/samples/AIADemo/EBS/AIADemoUpdateSalesOrderEBS" revision="1.0" wlserver="fp" action="deploy"/> <Composite compositeName="AIADemoSyncCustomerPartyListCRMProvDBAdapter" compositedir="${AIA_ HOME}/samples/AIADemo/Adapters/AIADemoSyncCustomerPartyListCRMProvDBAdapter" revision="1.0" wlserver="fp" action="deploy"/> </Deployments> </DeploymentPlan>
If this is your deployment plan file, create a deployment policy file as illustrated in Example 8-2.
Example 8-2 Deployment Policy File
<DeploymentPlan component="AIADemo" version="3.0"> <Conditions component="AIADemo" version="3.0"> <if> <equals arg1="${pip.foo.boo}" arg2="11.5.7"/> <then> <UpdateDP artifacttype="Datasource" name="FODDS" action="no-action" /> <UpdateDP artifacttype="JMSResource" name="AIADemoCF" action="no-action" /> <UpdateDP artifacttype="Composite" name="AIADemoUpdateSalesOrderEBS" action="no-action" /> </then> </if> </Conditions> </DeploymentPlan>
When AID executes the policy file, the contents between <Conditions> tag are written to a temporary build file and executed. Ensure that the contents inside conditions are valid ant tasks. A policy file can have only one conditions tag and all the conditions should be written inside this tag.
UpdateDP task is implemented as a taskdef in AID. The taskdef updates the action attribute of configuration and deployment tasks. In the UpdateDP task:
artifactype refers to the valid task names in deployment plan.
name refers to the name of the artifact created in the tag.
action refers to the new action value to which the value in deployment plan should be updated.
For a Composite tag, create an additional attribute: dir="<new directory path>". This attribute updates the compositedir attribute in the corresponding composite tag of deployment plan. Only one of the action and dir attributes can be specified for the composite artifact type.
AIA executes the deployment plan for UpdateDP in the following sequence:
Reads the deployment plan from "DeploymentPlan" environment variable.
If artifacttype != 'Composite', verifies whether dir attribute is passed as an input. If it is, AID throws incompatible attributes exception and shows usage.
If artifacttype = 'Composite', verifies whether both 'dir' and 'action' attributes are passed as an input. If they are, AID throws incompatible attributes exception and shows usage.
Reads name and action attributes, and updates deployment plan tasks accordingly.
Writes the file back to disk.
For the Macrodef that you do not want deployed by AID, set the action attribute in the listed macros to "no-action" action. The AID then skips the macro execution and proceeds to the next task. This is like removing the corresponding task from the deploymentPlan. "no-action" value for the action attribute is supported by the following Macrodefs:
Configurations
Datasource
JMSResource
JMSConnectionFactory
For Deployments you can add the "no-action" attribute value for Composite macrodef.
Note:
To facilitate durability across upgrades and patch updates, place custom modified files in a different directory path from AIA-shipped <PIP_Name>DP.xml and <PIP_Name>SupplementaryDP.xml.
The deployment of the artifacts is done by AID. AID takes the deployment plan and AIAInstallProperties.xml file as input. Based on the tags specified in the deployment plan, AID configures and deploys the artifacts onto the server.
AID supports three types of deployment plans:
Main Deployment Plan is auto generated by the Deployment Plan Generator whereas Supplementary Deployment Plan and Custom Deployment Plan are handcoded. Support to add custom deployment tags to the main deployment plan is available through Pre-Install and Post-Install sections in the Deployment plan. However, the problem with using these sections is that the deployment plan may not be upgrade-safe. To mitigate the issue, supplementary and custom deployment plans are introduced. The supplementary deployment plan is used mostly by the internal Pre-Built Integration development team. Use custom deployment plan to meet the requirement of non-native artifact deployment plan.
The execution sequence of deployment plans followed by AID is Main Deployment Plan -> Supplementary Deployment Plan -> Custom Deployment Plan. Here Supplementary Deployment Plan and Custom Deployment Plan are optional.
The following sections show the deployment commands for various deployment scenarios.
This scenario does not involve any customizations. The following command takes the main deployment plan and the supplementary deployment plan which are shipped with the Pre-Built Integration installer as input.
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>DP.xml -DSupplementaryDeploymentPlan =<AIA_ HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>SupplementaryDP.xml -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>ConditionalPolicy.xml
This section discusses how to deploy modified AIA-shipped native and non-native artifacts.
For modified native artifacts scenario, re-harvest the modified artifacts and regenerate the deployment plan, and name it <PIP_Name>CustomDP.xml. This has to be passed as the main deployment plan instead of the shipped deployment plan. The AID command is:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>CustomDP.xml -DSupplementaryDeploymentPlan =<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>SupplementaryDP.xml -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>ConditionalPolicy.xml
For the original native artifacts and modified non-native artifacts scenario, copy the contents of the shipped supplementary DP to a new file, name it <PIP_Name>CustomSupplementaryDP.xml, and modify the new file with the customizations. This is passed as the supplementary deployment plan instead of the shipped supplementary DP. The AID command is:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>DP.xml -DSupplementaryDeploymentPlan =<AIA_ HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>CustomSupplementaryDP.xml -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>ConditionalPolicy.xml
This section discusses how to deploy newly added native and non-native artifacts.
If you are introducing new native artifacts, harvest the new artifacts and regenerate the deployment plan for the new artifacts along with the shipped ones, and name it <PIP_Name>CustomDP.xml. Pass this as the main deployment plan instead of the shipped deployment plan. The AID command is:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>CustomDP.xml -DSupplementaryDeploymentPlan =<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>SupplementaryDP.xml -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>ConditionalPolicy.xml -l <AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIPDeploymentPlanName>.log
For new non-native artifacts scenario, add customizations to <PIP_Name>CustomDP.xml which is an empty DP shipped with the Pre-Built Integration. This Custom DP is in the same location as the main DP. Pass this as Custom Deployment Plan to AID. The AID command is:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>DP.xml -DSupplementaryDeploymentPlan =<AIA_ HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>SupplementaryDP.xml -DCustomDeploymentPlan=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>CustomDP.xml> -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>ConditionalPolicy.xml
The PropertiesFile, AIAInstallProperties.xml, contains the details of the AIA environment and is located here: <AIA_HOME>/aia_instances/<instance_name>/config.
The undeployment plan is generated at the same location as the deployment plan with the name <PIP_Name>UndeployDP.xml. The undeployment plan is generated only for native artifacts modified through the Project Lifecycle Workbench. This contains undeploy tasks for all the services deployed and the configurations done as part of Deployment Plan. The undeployment plan is executed using the AID.
The undeployment command is similar to the deployment plan command except for the Deployment Plan input argument and an additional argument "Uninstall".
For example, if you have used the following command to deploy modified native artifacts:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml -DDeploymentPlan=<AIA_HOME>\pips\<PIP_ name>\DeploymentPlans\<PIP_name>DP.xml -DSupplementaryDeploymentPlan =<AIA_ HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>SupplementaryDP.xml -DDeploymentPolicyFile=<AIA_HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_ name>ConditionalPolicy.xml
then the undeployment command will be:
ant -f <AIA_HOME>\Infrastructure\Install\AID\AIAInstallDriver.xml -DPropertiesFile=<AIA_HOME>\aia_instances\<AIA_Instance_ name>\config\AIAInstallProperties.xml Uninstall -DDeploymentPlan=<AIA_ HOME>\pips\<PIP_name>\DeploymentPlans\<PIP_name>UndeployDP.xml
However, for non-native artifacts, generate the undeployment plan manually. Take a copy of the supplementary deployment plan and name it <PIP_Name>UndeploySupplementaryDP.xml or <PIP_Name>UndeployCustomSupplementaryDP.xml depending on the supplementary deployment plan name. In the new deployment plan change the action attributes of all the tasks from "deploy
" to "undeploy
" or from "create
" to "delete
".