43 Deploying SOA Composite Applications

This chapter describes the deployment life cycle of SOA composite applications. It describes how to deploy single composites, multiple composites, and composites using shared data such as WSDLs, XSDs, and other file types with Oracle JDeveloper and the ant scripting tool, and create configuration plans for moving SOA composite applications to and from different environments. Deployment prerequisite, packaging, preparation, and configuration tasks are also described. A reference to documentation for deploying with the Oracle WebLogic Scripting Tool (WLST) utility is also provided.

A SAR file is a special JAR file that requires a prefix of sca_ (for example, sca_HelloWorld_rev1.0.jar).

In addition, when you deploy a SOA composite application with the Deploy to Application Server option on the Deployment Action page in Oracle JDeveloper, all required artifact files within a project are automatically packaged into one of the following files:

43.4 Anatomy of a Composite

When you deploy a SOA composite application in Oracle JDeveloper, the composite is packaged in a JAR file (for a single composite application) or a ZIP file (for multiple SOA composite applications). These files can include the following artifacts:

Shared data such as WSDL and XSD files. All shared data is deployed to an existing SOA Infrastructure partition on the server. This data is deployed under the /apps namespace. When you refer to this artifact in Oracle JDeveloper using a SOA-MDS connection, the URL is prefixed with oramds.

43.5 Preparing the Target Environment

The target environment is the SOA Infrastructure environment to which you want to deploy your SOA composite application. This is typically a development, test, or production environment. Depending upon the components, identity service provider, and security policies you are using in your composite application, additional configuration steps may be required as you move your application from one target environment to another. This section describes these tasks.

43.5.1 How to Create Data Sources and Queues

A Java Database Connectivity (JDBC) data source is an object bound to the Java Naming and Directory Interface (JNDI) tree that includes a pool of JDBC connections. Applications can look up a data source in the JNDI tree and then reserve a database connection from the data source. You create queues in which to enqueue outgoing messages or dequeue incoming messages. The Oracle JCA adapters listed in Table 43-1 require JDBC data sources and queues to be configured before deployment.

43.5.2 How to Create Connection Factories and Connection Pooling

The Oracle JCA adapters are deployed as JCA 1.5 resource adapters in an Oracle WebLogic Server container. Adapters are packaged as Resource Adapter Archive (RAR) files using a JAR format. When adapters are deployed, the RAR files are used and the adapters are registered as connectors with the Oracle WebLogic Server or middle-tier platform. The RAR file contains the following:

The ra.xml file, which is the deployment descriptor XML file containing deployment-specific information about the resource adapter

Declarative information about the contract between Oracle WebLogic Server and the resource adapter

Adapters also package the weblogic-ra.xml template file, which defines the endpoints for connection factories.

43.5.4 How to Set the Composite Instance Name at Design Time

You can set the instance name of a SOA composite application during design time for Oracle Mediator and Oracle BPEL Process Manager. The instance name appears in the Name column on the Instances page of a SOA composite application in Oracle Enterprise Manager Fusion Middleware Control. When you specify a search criteria on the Instances page of a SOA composite application or the SOA Infrastructure in Oracle Enterprise Manager Fusion Middleware Control, you can specify this name in the Name field.

43.5.4.1 Setting the Composite Instance Name in Oracle Mediator

Note:

The function setCompositeInstanceTitle cannot be used if Audit Level is set to Off on the SOA Infrastructure Common Properties page in Oracle Enterprise Manager Fusion Middleware Control. This results in the following error:

Composite instance ID is null. A composite instance may not be
created based on audit trail settings. Check the user guide for
detail.

To set the composite instance name in Oracle Mediator:

Use the XPath expression function med:setCompositeInstanceTitle in an assign activity. For example:

The expression med:setCompositeInstanceTitle("sample") executes the entire function in setting the title. The value provided in the target is a dummy value and used only for the assign activity to work correctly.

Use the setCompositeInstanceTitle(title) XPath expression function in the XSLT Mapper.

43.5.5 How to Deploy Trading Partner Agreements and Task Flows

If you are using Oracle B2B or a human task, you must perform additional setup tasks.

To deploy trading partner agreements and task flows:

Deploying trading partner agreements

A trading partner agreement defines the terms that enable two trading partners, the initiator and the responder, to exchange business documents. It identifies the trading partners, trading partner identifiers, document definitions, and channels. You must deploy the agreement from the design-time repository to the run-time repository. For more information, see Oracle Fusion Middleware User's Guide for Oracle B2B.

43.5.7 How to Create a SOA-MDS Connection

To deploy a SOA composite application that shares data with other composites, use the Create SOA-MDS Connection wizard to create a connection to a database-based Oracle MDS Repository server. For more information, see Section 43.7.3.4.1, "Creating a SOA-MDS Connection."

43.5.7.1 What You May Need to Know About Opening the composite.xml File Through a SOA-MDS Connection

If you create a SOA-MDS connection in Oracle JDeveloper, expand the connection, and attempt to open the composite.xml file of a composite from the Resource Palette, the file may not load correctly. Only open a composite from the Application Navigator.

43.6 Customizing Your Application for the Target Environment Before Deployment

Not all customization tasks must be manually performed as you move to and from development, test, and production environments. This section describes how to use a configuration plan to automatically configure your SOA composite application for the next target environment.

43.6.1 How to Use Configuration Plans to Customize SOA Composite Applications for the Target Environment

As you move projects from one environment to another (for example, from testing to production), you typically must modify several environment-specific values, such as JDBC connection strings, hostnames of various servers, and so on. Configuration plans enable you to modify these values using a single text (XML) file. The configuration plan is created in either Oracle JDeveloper or with WLST commands. During process deployment, the configuration plan searches the SOA project for values that must be replaced to adapt the project to the next target environment.

43.6.1.1 Introduction to Configuration Plans

This section provides an overview of creating and attaching a configuration plan:

You create and edit a configuration plan file in which you can replace the following attributes and properties:

Any composite, service component, reference, service, and binding properties in the SOA composite application file (composite.xml)

Attribute values for bindings (for example, the location for binding.ws)

schemaLocation attribute of an import in a WSDL file

location attribute of an include in a WSDL file

schemaLocation attribute of an include, import, and redefine in an XSD file

Any properties in JCA adapter files

Policy references for the following:

Service component

Service and reference binding components

Note:

The configuration plan does not alter XSLT artifacts in the SOA composite application. To modify any XSL, use the XSLT Mapper. Using a configuration plan is not useful. For example, you cannot change references in XSL using the configuration plan file. Instead, they must be changed manually in the XSLT Mapper in Oracle JDeveloper when moving to and from test, development, and production environments. This ensures that the XSLT Mapper opens without any issues in design time. However, leaving the references unchanged does not impact runtime behavior. For more information about transformations and the XSLT Mapper, see Chapter 43, "Deploying SOA Composite Applications."

You attach the configuration plan file to a SOA composite application JAR file or ZIP file (if deploying a SOA bundle) during deployment with one of the following tools:

During deployment, the configuration plan file searches the composite.xml, WSDL, and XSD files in the SOA composite application JAR or ZIP file for values that must be replaced to adapt the project to the next target environment.

43.6.1.2 Introduction to a Configuration Plan File

The following example shows a configuration plan in which you modify the following:

An inFileFolder property for composite FileAdaptorComposite is replaced with mytestserver/newinFileFolder.

A hostname (myserver17) is replaced with test-server and port 8888 is replaced with 8198 in the following locations:

A policy is replaced if a policy for the same URI is available. Otherwise, it is added. This is different from properties, which are modified, but not added.

43.6.1.3 Introduction to Use Cases for a Configuration Plan

The following steps provide an overview of how to use a configuration plan when moving from development to testing environments:

User A creates SOA composite application Foo.

User A deploys Foo to a development server, fixes bugs, and refines the process until it is ready to test in the staging area.

User A creates and edits a configuration plan for Foo, which enables the URLs and properties in the application to be modified to match the testing environment.

User A deploys Foo to the testing server using Oracle JDeveloper or a series of command-line scripts (can be WLST-based). The configuration plan created in Step 3 modifies the URLs and properties in Foo.

User A deploys SOA composite application Bar in the future and applies the same plan during deployment. The URLs and properties are also modified.

The following steps provide an overview of how to use a configuration plan when creating environment-independent processes:

Note:

This use case is useful for users that have their own development server and a common development and testing server if they share development of the same process. Users that share the same deployment environment (that is, the same development server) may not find this use case as useful.

User A creates SOA composite application Foo.

User A deploys Foo to their development server, fixes bugs, and refines the process until it is ready to test in the staging area.

User A creates a configuration plan for Foo, which enables the URLs and properties in the process to be modified to match the settings for User A's environment.

User A checks in Foo and the configuration plan created in Step 3 to a source control system.

User B checks out Foo from source control.

User B makes a copy of the configuration plan to match their environment and applies the new configuration plan onto Foo's artifacts.

User B imports the application into Oracle JDeveloper and makes several changes.

Enter a specific name or accept the default name for the configuration plan. The file is created in the directory of the project and packaged with the SOA composite application JAR or ZIP file.

Note: During deployment, you can specify a different configuration file when prompted in the Deploy Configuration page of the deployment wizard. For more information, see Section 43.7.1.3, "Deploying the Profile."

Overwrite existing file

Click to overwrite an existing configuration plan file with a different file in the project directory.

Click OK.

This creates and opens a single configuration plan file for editing, similar to that shown in Example 43-4. You can modify URLs and properties for the composite.xml, WSDL, and schema files of the SOA composite application. Figure 43-3 provides details.

Add values for server names, port numbers, and so on to the existing syntax. You can also add replacement-only syntax when providing a new value. You can add multiple search and replacement commands in each section.

From the File menu, select Save All.

Above the editor, click the x to the right of the file name to close the configuration plan file.

Select the configuration plan to validate. This step identifies all search and replacement changes to be made during deployment. Use this option for debugging only.

Note the directory in which a report describing validation results is created, and click OK.

The Log window in Oracle JDeveloper indicates if validation succeeded and lists all search and replacement commands to perform during SOA composite application deployment. This information is also written to the validation report.

Note:

The old composite.xml, WSDL, and XSD files are not replaced with files containing the new values for the URLs and properties appropriate to the next environment. Replacement occurs only when the SOA composite application is deployed.

Deploy the SOA composite application by following the instructions in one of the following sections:

During deployment in Oracle JDeveloper, the Deploy Configuration page shown in Step 4 of Section 43.7.1.3, "Deploying the Profile" prompts you to select the configuration plan to include in the SOA composite application archive.

Select the configuration plan to include with the SOA composite application.

Click OK.

43.6.1.5 How to Create a Configuration Plan with the WLST Utility

As an alternative to using Oracle JDeveloper, you can use the WLST command line utility to perform the following configuration plan management tasks:

43.6.1.7 How to Create Global Token Variables

You can define global token variables for specific URIs in SOA composite applications. For example, instead of updating the SOA composite application name in ten different configuration plans, you can set the name globally. The value is retrieved and replaces the value of the global token variable for the composite name in the composite.xml file of the deployed SOA composite application.

43.7 Deploying SOA Composite Applications

This section describes how to deploy the following types of SOA composite applications.

Deploying a single composite in Oracle JDeveloper

Deploying multiple composites in Oracle JDeveloper

Deploying and using shared data in Oracle JDeveloper

Deploying an existing SOA archive in Oracle JDeveloper

Managing SOA composite applications with WLST and ant scripts

Deploying from Oracle Enterprise Manager Fusion Middleware Control

Deploying SOA composite applications to a cluster

43.7.1 How to Deploy a Single SOA Composite in Oracle JDeveloper

Oracle JDeveloper requires the use of profiles for SOA projects and applications to be deployed to Oracle WebLogic Server.

43.7.1.1 Creating an Application Server Connection

You must create a connection to the application server to which to deploy a SOA composite application. The following instructions describe how to create a connection to Oracle WebLogic Server. For information about creating a connection to other application servers such as IBM WebSphere Server, see Oracle Fusion Middleware Third-Party Application Server Guide.

To create an application server connection:

From the File main menu, select New.

In the General list, select Connections.

Select Application Server Connection, and click OK.

The Name and Type page appears.

In the Connection Name field, enter a name for the connection.

In the Connection Type list, select WebLogic 10.3 to create a connection to Oracle WebLogic Server.

Click Next.

The Authentication page appears.

In the Username field, enter the user authorized for access to the application server.

In the Password field, enter the password for this user.

Click Next.

The Configuration page appears.

In the Weblogic Hostname (Administration Server) field, enter the host on which the Oracle WebLogic Server is installed.

In the Port and SSL Port fields, enter the appropriate port values or accept the default values.

If you want to use secure socket layer (SSL), select the Always use SSL checkbox. Table 43-3 describes what occurs when you select this checkbox.

Table 43-3 Deployment to HTTPS and HTTP Servers

If This Checkbox Is...

Then...

Selected

An HTTPS server URL must exist to deploy the composite with SSL. Otherwise, deployment fails.

If the server has only an HTTP URL, deployment also fails. This option enables you to ensure that SSL deployment must not go through a non-SSL HTTP URL, and must only go through an HTTPS URL.

Not selected

An HTTP server URL must exist to deploy to a non-SSL environment. Otherwise, deployment fails.

If the server has both HTTPS and HTTP URLs, deployment occurs through a non-SSL connection. This option enables you to force a non-SSL deployment from Oracle JDeveloper, even though the server is SSL-enabled.

A SAR is a deployment unit that describes the SOA composite application. The SAR packages service components such as BPEL processes, business rules, human tasks, and Oracle Mediator routing services into a single application. The SAR file is analogous to the BPEL suitcase archive of previous releases, but at the higher composite level and with any additional service components that your application includes (for example, human tasks, business rules, and Oracle Mediator routing services).

Name

Enter a deployment profile name.

Click OK.

The SAR Deployment Profile dialog appears.

Click OK to close the SAR Deployment Profile Properties dialog.

The deployment profile shown in Figure 43-5 displays in the Project Properties dialog.

43.7.1.3 Deploying the Profile

You now deploy the project profile to Oracle WebLogic Server. Deployment requires the creation of an application server connection. You can create a connection during deployment by clicking the Add icon in Step 10 or before deployment by following the instructions in Section 43.7.1.1, "Creating an Application Server Connection."

Creates a JAR file for the selected SOA project and deploys it to an application server such as Oracle WebLogic Server.

Deploy to SAR

Creates a SAR (JAR) file of the selected SOA project, but does not deploy it to an application server such as Oracle WebLogic Server. This option is useful for environments in which:

Oracle WebLogic Server may not be running, but you want to create the artifact JAR file.

You want to deploy multiple JAR files to Oracle WebLogic Server from a batch script. This option offers an alternative to opening all project profiles (which you may not have) and deploying them from Oracle JDeveloper.

Provide values appropriate to your environment, as described in Table 43-6. If you selected to deploy to an application server, additional fields display in the page.

Table 43-6 SOA Deployment Configuration Dialog

Field

Description

Composite Revision ID

Expand to display details about the project.

Project

Displays the project name.

Current Revision ID

Displays the current revision ID of the project.

New Revision ID

Optionally change the revision ID of the SOA composite application.

SOA Configuration Plan

Expand to display details about the configuration plan.

The configuration plan enables you to define the URL and property values to use in different environments. During process deployment, the configuration plan is used to search the SOA project for values that must be replaced to adapt the project to the next target environment.

Do not attach

Select to not include a configuration plan with the SOA composite application JAR file. If you have not created a configuration plan, this field is disabled. This is the default selection.

Configuration_plan.xml

Select the specific plan. A configuration plan must already exist in the SOA project for this selection to be available.

Note: This checkbox only appears if there is at least one .monitor file in the application.

Deselect this checkbox to display BPEL Monitor deployment errors. This checkbox corresponds to the ignoreErrors property in the monitor.config BPEL project file. This file defines runtime and deployment properties needed to connect with Oracle BAM Server to create the Oracle BAM data objects and dashboards.If Oracle BAM Server is unreachable, and ignoreErrors is set to true, deployment of the composite does not stop. If set to false and Oracle BAM Server is unavailable, deployment fails.

Mark composite revision as default

If you do not want the new revision to be the default, you can deselect this box. By default, a newly deployed composite revision is the default. This revision is instantiated when a new request comes in.

The option only displays if you selected Deploy to Application Server on the Deployment Action page.

Overwrite any existing composites with the same revision ID

Select to overwrite any existing SOA composite application of the same revision value.

The option only displays if you selected Deploy to Application Server on the Deployment Action page.

Keep running instances on after redeployment

Note: This option is displayed if Oracle BPM Suite is installed in Oracle JDeveloper, and only supported for the deployment of Oracle BPM composites. Do not select this option if you are deploying:

A SOA composite application from an Oracle JDeveloper environment in which Oracle BPM Suite is also installed.

An Oracle BPM composite that includes a durable BPEL process, regardless of whether that process has been modified. Durable BPEL processes are those that take time to complete execution. Examples of durable BPEL processes are asynchronous processes (which are always durable) and synchronous processes that include a durable activity such as a wait activity.

If you select this option and attempt to redeploy a durable BPEL process, then deployment fails.

Select to enable existing instances of the overwritten revision to continue running instead of going stale. These instances run side by side with any new instances that you create with the new revision of the Oracle BPM composite application.

Force deployment of incompatible processes

This option is only displayed for Oracle BPM Suite composites.

If Keep running instances on after redeployment is checked, this option is displayed. Select this checkbox to force deployment of incompatible BPM processes. When a composite with BPM processes is overwritten, the system checks to see if the BPM processes being overwritten are compatible with the processes being deployed. If they are compatible, running instances of these processes are not marked as stale and deployment is successful. If they are incompatible, deployment fails unless you select this checkbox.

Use the following SOA configuration plan for all composites

Click Browse to select the same configuration plan to use for all composite applications. This option is used when deploying multiple composite applications.

Click Next.

If the SOA project you selected for deployment includes a task flow project defined for a human task, you are prompted with the Task Flow Deployment dialog, as shown in Figure 43-9.

You create or configure an Enterprise Resource Archive (EAR) file for the task flow forms of human tasks. The EAR file consists of a Web Resource Archive (WAR) profile that you select in the Deployable Taskflow Projects table of this dialog.

Provide values appropriate to your environment, as described in Table 43-7.

Table 43-7 Task Flow Deployment Dialog

Field

Description

Application Name

Select the EAR file to include in the deployment. This list displays all available EAR profiles in the current Oracle JDeveloper application. These EAR profiles are used as a template to create an EAR profile to deploy based on the WAR profiles selected in the Deployable Taskflow Projects table. You can also enter any EAR profile name to deploy.

Deploy to specific composite revision & partition

Select to append the revision number of the composite to the EAR file name. If selected, this checkbox includes the composite revision in the EAR name, WAR profile, and context root. This option enables you to deploy an application specific to a composite revision.

Add generated profiles to application

Select to add the generated EAR profile to the current SOA composite application's EAR deployment profile list. The application may have to be saved to persist the generated EAR profile. Once the deployment profile is available, you can deploy the EAR profile by selecting Application > Deploy. This option enables you to avoid using the SOA deployment wizard, if only task flow application deployment is necessary.

Overwrite Existing Application

Select to overwrite the existing version of the EAR file on the server.

Deployable Taskflow Projects

Select the task flow project WAR profiles to include in the EAR file. The task flow project WAR profiles are grouped in accordance with the composites that include the human task related to the task flow project. The context root of the WAR changes if the Add generated profiles to application checkbox is selected.

Note: If you do not select a WAR profile, no task flows are deployed.

Projects

Select from the list of deployable task flow projects or select the Projects checkbox to choose all available task flows. The task flows that display are based on the composites included in the SOA project or bundle selected for deployment.

WAR Profiles

Select the task flow project WAR files. Only the most recently created or modified task flow of the human task is available for selection.

App Context Root

Displays the application context root directory based on your selection for the WAR profile.

When you deploy a task form for a human task, as part of notification, the task form details are included in an email. For dynamic payloads, this email includes the content of the payload as it appears at that particular time.

If you selected to deploy to an application server in Step 3, the Select Server page appears for selecting an existing connection to an application server such as Oracle WebLogic Server from the list or clicking the Add icon to create a connection to a server. Figure 43-10 provides details.

Select the target SOA servers to which to deploy this archive. If there are multiple servers or cluster nodes, select to deploy to one or more servers or nodes. Figure 43-11 provides details.

Select the partition in which to deploy this archive. If the server contains no partitions, you cannot deploy this archive. Also, if the server is not in a running state, you cannot deploy this archive. By default, a partition named default is automatically included with Oracle SOA Suite. You create partitions in the Manage Partitions page of Oracle Enterprise Manager Fusion Middleware Control.

Note:

Human workflow artifacts such as task mapped attributes (previously known as flex field mappings) and rules (such as vacation rules) are defined based on the namespace of the task definition. Therefore, the following issues are true when the same SOA composite application with a human workflow task is deployed into multiple partitions:

For the same task definition type, mapped attributes defined in one partition are visible in another partition.

Rules defined on a task definition in one partition can apply to the same definition in another partition.

If you want to redeploy the same version of a SOA composite application, you cannot change the composite name. You can deploy with the same revision number if you selected the Overwrite any existing composites with the same revision ID checkbox on the Deploy Configuration page.

43.7.1.4 What You May Need to Know About Deploying Human Task Composites with Task Flows to Partitions

To deploy a SOA composite application with a task flow from Oracle JDeveloper to a multiple partition environment, select the task flows to be deployed to the same partition in which the SOA composite application is being deployed.

When the task flow is deployed using only the EAR profile (deploying the task flow using the EAR deployer), the task flow is not partition-aware. Therefore, you must modify the hwtaskflow.xml file to include the partition name in the generated EAR file (the project version of the file remains unchanged). This file is located under the TaskForm project adfmsrc directory (for example, HelpDeskRequestTaskFlow\adfmsrc\hwtaskflow.xml). Example 43-5 provides details.

You can deploy multiple SOA composite applications to an application server such as Oracle WebLogic Server at the same time by using the SOA bundle profile. This profile enables you to include one or more SAR profiles in the bundle and deploy the bundle to an application server.

You cannot deploy multiple SOA applications that are dependent upon one another in the same SOA bundle profile. For example, if application A calls application B, then you must first deploy application B separately.

To deploy multiple SOA composite applications:

From the Application menu, select Application Properties, as shown in Figure 43-13.

43.7.3 How to Deploy and Use Shared Data Across Multiple SOA Composite Applications in Oracle JDeveloper

This section describes how to deploy and use shared data such as WSDLs, XSDs, and other file types across multiple SOA composite applications.

Shared data is deployed to the SOA Infrastructure on the application server as a JAR file. The JAR file should contain all the resources to share. In Oracle JDeveloper, you can create a JAR profile for creating a shared artifacts archive.

All shared data is deployed to an existing SOA Infrastructure partition on the server. This data is deployed under the /apps namespace. For example, if you have a MyProject/xsd/MySchema.xsd file in the JAR file, then this file is deployed under the /apps namespace on the server. When you refer to this artifact in Oracle JDeveloper using a SOA-MDS connection, the URL becomes oramds:/apps/MyProject/xsd/MySchema.xsd.

Notes:

You always deploy to the /apps location. The directory hierarchy must exist in the JAR file to deploy. Do not create the directory hierarchy in the Oracle MDS Repository first and then deploy the JAR file to that location. For example, to deploy to /apps/demo/creditcard, the JAR file must include the demo/creditcard directory hierarchy inside it.

Files that begin with a period (for example, .designer) cannot be shared across SOA composite applications.

This section describes how to perform the following tasks:

Create a JAR profile and include the artifacts to share

Create a SOA bundle that includes the JAR profile

Deploy the SOA bundle to the application server

43.7.3.1 Create a JAR Profile and Include the Artifacts to Share

To create a JAR profile and include the artifacts to share:

In the Application Navigator, right-click the SOA project.

Select Project Properties.

The Project Properties dialog appears.

Click Deployment in the navigational tree on the left.

Click New.

The Create Deployment Profile dialog appears.

From the Archive Type list, select JAR File.

In the Name field, enter a name (for this example, shared_archive is entered).

Select the JAR file and SOA-SAR profiles you previously created (for this example, named shared_archive and sharedArtifactBundle, respectively). You have the option of a JAR, a SOA-SAR, or both. Figure 43-22 provides details.

Ensure that IDE Connection is selected. This option enables the connection to display in the Resource Palette and be available to multiple applications.

You cannot create a connection with the Application Resources option. This selection is disabled.

Connection Name

Enter a connection name. Upon successful completion of this connection creation, this name displays under SOA-MDS in the Resource Palette.

Connection Type

Select a connection type. An Oracle MDS Repository can be file-based or database-based. The dialog is refreshed based on your selection.

DB Based MDS

For most production environments, you use a database-based repository. Most components, such as Oracle SOA Suite, require that a schema be installed in a database, necessitating the use of a database-based repository. To use a database-based repository, you must first create it with the Repository Creation Utility.

File Based MDS

Choose a database connection

Select an existing connection or create a new connection to the Oracle SOA Suite database with the MDS schema.

Select MDS Partition

Select the MDS partition (for example, soa-infra).

Test Connection

Click to test the SOA-MDS connection.

Note: Even if the connection test fails, a connection is created.

Status

Displays status of the connection test.

Click OK.

You can now browse the connection in the Resource Palette and view shared artifacts under the /apps node.

43.7.3.4.2 Creating a BPEL Process

You can now browse and use the shared data from a different SOA composite application. For this example, you create a BPEL process service component in a different application.

To create a BPEL process:

Create a new BPEL process service component in a different application.

In the Create BPEL Process dialog, click the Browse icon to the right of the Input field.

43.7.4 How to Deploy an Existing SOA Archive in Oracle JDeveloper

You can deploy an existing SOA archive from the Application Server Navigator in Oracle JDeveloper.

Notes:

The archive must exist. You cannot create an archive in the Deploy SOA Archive dialog.

These instructions assume you have created an application server connection to an Oracle WebLogic Administration Server or another supported application server on which the SOA Infrastructure is deployed. Creating a connection to an Oracle WebLogic Administration Server enables you to browse for SOA composite applications deployed in the same domain. From the File main menu, select New > Connections > Application Server Connection to create a connection.

Provide responses appropriate to your environment, as described in Table 43-9.

Table 43-9 Create Deployment Profile Dialog Fields and Values

Field

Description

SOA Server

Select the SOA server to which to deploy the archive.

Partition

Select the partition in which to deploy the archive. If the server contains no partitions, you cannot deploy this archive. By default, a partition named default is automatically included with Oracle SOA Suite.

Status

Displays the status of the server. If the server is not in a running state, you cannot deploy this archive.

Server URL

Displays the URL of the server.

Choose target SOA server(s) to which you want to deploy this archive

Select the Oracle WebLogic Administration Server to which to deploy the archive.

SOA Archive

Click Browse to select a prebuilt SOA composite application archive. The archive consists of a JAR file of a single application or a SOA bundle ZIP file containing multiple applications.

Configuration Plan (Optional)

Click Browse to select a configuration plan to attach to the SOA composite application archive. The configuration plan enables you to define the URL and property values to use in different environments. During process deployment, the configuration plan is used to search the SOA project for values that must be replaced to adapt the project to the next target environment.

If you do not want the new revision to be the default, you can deselect this box. By default, a newly deployed composite revision is the default. This revision is instantiated when a new request comes in.

Overwrite any existing composites with the same revision ID

Select to overwrite (redeploy) an existing SOA composite application with the same revision ID. The consequences of this action are as follows:

A new version 1.0 of the SOA composite application is redeployed, overwriting a previously deployed 1.0 version.

The older, currently-deployed version of this revision is removed (overwritten).

If the older, currently-deployed version of this revision has running instances, the state of those instances is changed to stale.

43.7.6 How to Manage SOA Composite Applications with ant Scripts

You can manage SOA composite applications with the ant utility. ant is a Java-based build tool used by Oracle SOA Suite for managing SOA composite applications. The configuration files are XML-based and call out a target tree where various tasks are executed. The ant utility is well-suited for automation and can be easily integrated into existing release processes.

Table 43-10 lists the ant scripts available in the Middleware_Home\SOA_Suite_Home\bin directory.

Table 43-10 ant Management Scripts

Script

Description

ant-sca-test.xml

Automates the testing of SOA composite applications.

ant-sca-compile.xml

Compiles a SOA composite application.

ant-sca-package.xml

Packages a SOA composite application into a composite SAR file.

ant-sca-deploy.xml

Deploys a SOA composite application.

ant-sca-deploy.xmlundeploy

Undeploys a SOA composite application.

ant-sca-deploy.xml exportComposite

Exports a composite into a SAR file.

ant-sca-deploy.xml exportUpdates

Exports postdeployment changes of a composite into a JAR file.

ant-sca-deploy.xml importUpdates

Imports postdeployment changes of a composite.

ant-sca-deploy.xml exportSharedData

Exports shared data of a given pattern into a JAR file.

ant-sca-deploy.xml removeSharedData

Removes a top-level shared data folder.

ant-sca-mgmt.xmlstartComposite

Starts a SOA composite application.

ant-sca-mgmt.xmlstopComposite

Stops a SOA composite application.

ant-sca-mgmt.xmlactivateComposite

Activates a SOA composite application.

ant-sca-mgmt.xmlretireComposite

Retires a SOA composite application.

ant-sca-mgmt.xmlassignDefaultComposite

Assigns a default revision version.

ant-sca-mgmt.xmllistDeployedComposites

Lists deployed SOA composite applications.

ant-sca-mgmt.xml listPartitions

Lists all available partitions in the SOA Infrastructure.

ant-sca-mgmt.xml listCompositesInPartition

Lists all composites in a partition.

ant-sca-mgmt.xmlcreatePartition

Creates a partition in the SOA Infrastructure.

ant-sca-mgmt.xmldeletePartition

Undeploys all composites in a partition before deleting the partition.

Note: If any Java code is part of the project, you must manually modify the code to pass compilation with an 11g compiler. For BPEL process instance data, active data used by the 10.1.3 Oracle BPEL Server is not migrated.

Since a composite test (in a test suite) is executed on the SOA Infrastructure, this properties file contains the connection information. For this example, these properties create a connection to the SOA Infrastructure hosted in myserver.us.example.com, port 8001 and use a user name of weblogic. You are prompted to specify the password.

You typically create one jndi.properties file (for example, in /home/myhome/jndi.properties) and use it for all test runs.

The script picks this from the environment value of JAVA_HOME. Provide this input to override.

wl_home

This is the location of Oracle WebLogic Server home (defaults to Oracle_Home/.../wlserver_10.3).

scac.input

The composite.xml file to compile.

scac.output

The output file with scac results (defaults to temp_dir/out.xml).

scac.error

The file with scac errors (defaults to temp_dir/out.err).

scac.application.home

The Oracle JDeveloper application home directory of the SOA composite application being compiled that contains the .adf directory in it.

scac.displayLevel

Controls the level of logs written to scac.output file. The value can be 1, 2, or 3 (this defaults to 1).

43.7.6.3 How to Use ant to Package a SOA Composite Application into a Composite SAR File

Example 43-8 provides an example of packaging a SOA composite application into a composite SAR file. The outcome of this command is a SOA archive. Check the output of the command for the exact location of the resulting file.

URL of the server that hosts the SOA Infrastructure application (for example, http://myhost10:8001).

sarLocation

Absolute path to one the following:

SAR file.

ZIP file that includes multiple SARs.

overwrite

Optional. Indicates whether to overwrite an existing SOA composite application on the server.

false (default): Does not overwrite the file.

true: Overwrites the file.

user

Optional. User name to access the composite deployer servlet when basic authentication is configured.

password

Optional. Password to access the composite deployer servlet when basic authentication is configured.

If you enter the user name, you are prompted to enter the password if you do not provide it here.

forceDefault

Optional. Indicates whether to set the version being deployed as the default version for that composite application.

true (default): Makes it the default composite.

false: Does not make it the default composite.

configplan

Absolute path of a configuration plan to be applied to a specified SAR file or to all SAR files included in the ZIP file.

sysPropFile

Passes in a system properties file that is useful for setting extra system properties, for debugging, for SSL configuration, and so on.

If you specify a file name (for example, tmp-sys.properties), you can define properties such as the following:

javax.net.debug=all

scac.user.classpath

Optional. The name of the external custom library. If you have a SOA composite application with a BPEL process service component that refers to a custom JAR file, set this property.

partition

Optional. The name of the partition in which to deploy the SOA composite application. The default value is default. If you do not specify a partition, the composite is automatically deployed into the default partition.

Note:

Human workflow artifacts such as task mapped attributes (previously known as flex field mappings) and rules (such as vacation rules) are defined based on the namespace of the task definition. Therefore, the following issues are true when the same SOA composite application with a human workflow task is deployed into multiple partitions:

For the same task definition type, mapped attributes defined in one partition are visible in another partition.

Rules defined on a task definition in one partition can apply to the same definition in another partition.

URL of the server that hosts the SOA Infrastructure application (for example, http://myhost10:7001).

compositeName

Name of the SOA composite application.

revision

Revision ID of the SOA composite application.

user

Optional. User name to access the composite deployer servlet when basic authentication is configured.

If you enter the user name, you are prompted to enter the corresponding password.

password

Optional. Password to access the composite deployer servlet when basic authentication is configured.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

43.7.6.6 How to Use ant to Export a Composite into a SAR File

Example 43-11 provides an example of exporting a composite into a SAR file.

The URL of the server that hosts the SOA Infrastructure application (for example, http://myhost:8001).

jarFile

The absolute path of the JAR file to be generated.

pattern

The file pattern supported by Oracle MDS Repository transfer APIs. Use the semicolon delimiter (;) if multiple patterns are specified. Exclude the shared data namespace /apps in the pattern. For example:

/Project1/**;/Project2/**

This example exports all documents under /apps/Project1 and /apps/Project2.

user

Optional. The user name for accessing the server when basic configuration is configured.

password

The password for accessing the server when basic configuration is configured. This parameter is optional.

Example 43-23 shows how to export shared data of a given pattern into a JAR file.

Example 43-23 Exporting Shared Data of a Given Pattern into a JAR File

User name for connecting to the running server to get MBean information (for example, weblogic).

password

Password for the user name.

compositeName

Name of the SOA composite application.

revision

Revision of the SOA composite application.

label

Optional. Label of the SOA composite application. The label identifies the MDS artifacts associated with the application. If the label is not specified, the system finds the latest one.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

User name for connecting to the running server to get MBean information (for example, weblogic).

password

Password for the user name.

compositeName

Name of the SOA composite application.

revision

Revision of the SOA composite application.

label

Optional. Label of the SOA composite application. The label identifies the MDS artifacts associated with the application. If the label is not specified, the system finds the latest one.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

User name for connecting to the running server to get MBean information (for example, weblogic).

password

Password for the user name.

compositeName

Name of the SOA composite application.

revision

Revision of the SOA composite application.

label

Optional. Label of the SOA composite application. The label identifies the MDS artifacts associated with the application. If the label is not specified, the system finds the latest one.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

User name for connecting to the running server to get MBean information (for example, weblogic).

password

Password for the user name.

compositeName

Name of the SOA composite application.

revision

Revision of the SOA composite application.

label

Optional. Label of the SOA composite application. The label identifies the MDS artifacts associated with the application. If the label is not specified, the system finds the latest one.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

43.7.6.15 How to Use ant to Assign the Default Version to a SOA Composite Application

Example 43-30 provides an example of assigning the default version to a SOA composite application.

Example 43-30 Assigning the Default Version to a SOA Composite Application

User name for connecting to the running server to get MBean information (for example, weblogic).

password

Password for the user name.

compositeName

Name of the SOA composite application.

revision

Revision of the SOA composite application.

partition

Optional. The name of the partition in which the SOA composite application is located. The default value is default. If you do not specify a partition, the default partition is searched for the SOA composite application. However, no other partitions are searched.

43.7.6.16 How to Use ant to List the Deployed SOA Composite Applications

43.7.6.25 How to Use ant to Upgrade a SOA Composite Application

43.7.6.26 How to Use ant to Manage SOA Composite Applications

The WebLogic Fusion Order Demo application provides an example of using ant scripts to compile, package, and deploy the application. You can create the initial ant build files by selecting New > Ant > Buildfile from Project from the File main menu.

Figure 43-26 shows the build.properties and build.xml files that display in the Application Navigator after creation.

A file that you edit to reflect your environment (for example, specifying Oracle home and Java home directories, setting server properties such as hostname and port number to use for deployment, specifying the application to deploy, and so on).

build.xml

Used by ant to compile, build, and deploy composite applications to the server specified in the build.properties file.

43.9.3 Automating the Testing of Deployed Composites

You can create, deploy, and run test cases that automate the testing of SOA composite applications. Test cases enable you to simulate the interaction between a SOA composite application and its web service partners before deployment in a production environment. You create test cases in Oracle JDeveloper and include them in a SOA composite application that is then deployed and administered from Oracle Enterprise Manager Fusion Middleware Control. You then run the test cases from Oracle Enterprise Manager Fusion Middleware Control.

43.9.4 Recompiling a Project After Receiving a Deployment Error

If you receive the error shown in Example 43-48 when deploying a SOA composite application from Oracle JDeveloper, recompile the project and redeploy the composite. This error is intermittent and should not occur again.

43.9.5 Reducing Java Code Size to Resolve Java Compilation Errors

If you receive the Java compilation error shown in Example 43-49 in your server log files, you may have too much code in your Java classes.

Example 43-49 Java Compilation Error

Failed to compile bpel generated classes.
failure to compile the generated BPEL classes for BPEL process
"Review_Supply_Plan_ProcessProcess" of composite "default/Review_Supp
ly_Plan_Process!1.0*a9ca2907-8540-4375-b672-ceb560d7b826"
The class path setting is incorrect.
Ensure that the class path is set correctly. If this happens on the server
side, verify that the custom classes or jars which this BPEL process is
depending on are deployed correctly. Also verify that the runtime is using
the same release/version.
. . .
. . .
at
com.collaxa.cube.lang.compiler.template.CubeProcessGenerator.compile(CubeProce
ssGenerator.java:304)
at
com.collaxa.cube.lang.compiler.template.CubeProcessGenerator.generate(CubeProc
essGenerator.java:164)
at
com.collaxa.cube.lang.compiler.BPEL1Processor.transform(BPEL1Processor.java:25
7)
at
com.collaxa.cube.lang.compiler.BPEL1Processor.process(BPEL1Processor.java:161)

Locate the EXTRA_JAVA_PROPERTIES="-Dorabpel.codegen.density" property in this file. If this property is not explicitly set, it defaults to values of 64,32.

Reduce the values:

EXTRA_JAVA_PROPERTIES="-Dorabpel.codegen.density=32,16"

By reducing these two values, you increase the number of classes and methods that are generated for the compiled process map. As a best practice, if the process fails to compile using the default settings, set the property with smaller values. The following values are good combinations to try:

43.9.6.1 Common Oracle JDeveloper Deployment Issues

This section provides a list of common deployment issues to check.

If you are deploying a single composite application, ensure that you are deploying from the Project menu. Right-click the project name in the Application Navigator, and select Deploy > SOA_profile_name.

If you are deploying multiple composite applications, ensure that you are deploying from the Application menu. (Right-click the application name in the Application Navigator, and select Deploy > SOA_bundle_profile_name).

Once you click Deploy and select the profile name, ensure that the Deployment Action page of the deployment wizard is displayed.

If the composite application you are deploying is already located on the server with the same revision ID, then check the Overwrite any existing composites with the same revision ID checkbox in the Deploy Configuration page of the deployment wizard. Without selecting this option, deployment fails.

If compilation fails, a compiler error occurred, and not a deployment error. You only see this error when you compile your project.

If compiler messages are not obvious, check the compiler log. A link to this log file (scac.log) is displayed in the Messages tab. The message looks similar to that shown in Example 43-50.

After compilation is successful, a SAR/SOA bundle archive is built for the composite. For a SAR archive, the message shown in Example 43-51 is displayed in the Deployment tab.

Example 43-51 Archive Message

Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/FirstComposite/deploy/sca_
FirstComposite_rev1.0.jar

For a SOA bundle archive, the message shown in Example 43-52 is displayed in the Deployment tab.

Example 43-52 Archive Message

Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/SecondComposite/deploy/sca_
SecondComposite_rev1.0.jar
Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/FirstComposite/deploy/sca_
FirstComposite_rev1.0.jar
Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/deploy/soabundle1.zip

Ensure that all SAR file URLs look as follows:

sca_CompositeName_revRevisionID.jar

For example, sca_FirstComposite_rev1.0.jar.

After this occurs, Oracle JDeveloper sends the archive binaries to the server. The following message is displayed in the Deployment tab. At this point, Oracle JDeveloper's deployment role ends and the server (SOA Infrastructure) takes control of deployment.

Deploying sca_FirstComposite_rev1.0.jar to myhost19:7001

Upon successful deployment, you see the message shown in Example 43-53 in the Deployment tab.

In most cases, the server provides some information about the error that occurred on the server. If you do not receive any error message from the server, then check soa_server1-diagnostic.log on the server to find additional information (where soa_server1 is the name of the managed server). This file is located on the server in domain_home/servers/soa_server1/logs.

43.9.6.2 Common Configuration Plan Issues

This section provides a list of common configuration plan issues to check.

If you selected a configuration plan to deploy, and it is not taking effect on the server, open the SAR file containing the configuration plan. You can find the file location from the Deployment tab in Oracle JDeveloper. Example 43-55 provides details.

Example 43-55 Archive Message

Wrote Archive Module to
/scratch/myhome/jdevWorkarea/mywork/Application11/FirstComposite/deploy/sca_
FirstComposite_rev1.0.jar

Open the JAR file and ensure that it contains the soaconfigplan.xml file. This file is generated during deployment based on the configuration plan you selected.

If this file is not present, try deploying the composite application again to ensure that you have correctly selected the configuration plan in the Deploy Configuration page of the deployment wizard.

43.9.6.3 Deploying to a Managed Oracle WebLogic Server

If you start a managed Oracle WebLogic Server without starting an Oracle WebLogic Administration Server (known as running in independence mode) and attempt to deploy a SOA composite application from Oracle JDeveloper, you receive the following error:

Deployment cannot continue! No SOA Configured target servers found

The Oracle WebLogic Administration Server must be running. Deployment uses the Oracle WebLogic Administration Server connection to identify the servers running Oracle SOA Suite. In addition, do not create an application server connection to a Managed Server; only create connections to an Oracle WebLogic Administration Server.

You can also receive a similar error if the condition of the SOA-configured Oracle WebLogic Server is not healthy. This condition displays in the Health column of the Servers page of Oracle WebLogic Server Administration Console.

A valid proxy setting is necessary for accessing a SOA Infrastructure (for example, soa_server1) outside the network. If the SOA Infrastructure is within the network, perform one of the following actions:

To change the proxy setting:

From the Tools menu, select Preferences > Web Browser and Proxy.

Perform one of the following tasks if the SOA server is within the network:

Deselect Use HTTP Proxy Server if you can directly access the SOA Infrastructure without any proxy.

In the Exceptions field, enter the hostname of the unreachable SOA server.

If you deploy a SOA composite application JAR file and ADF task form EAR file, and the SOA JAR file is deployed successfully, but while deploying the EAR file, the following errors are displayed:

[wldeploy] weblogic.management.ManagementException: [Deployer:149163]The
domain edit lock is owned by another session in non-exclusive mode - this
deployment operation requires exclusive access to the edit lock and hence
cannot proceed. If you are using "Automatically Aquire Lock and Activate
Changes" in the console, then the lock will expire shortly so retry this
operation.

This error means you must first release the lock from Oracle WebLogic Server Administration Console to successfully deploy the EAR file.

To release locks to resolve ADF task form EAR file deployment errors:

Log in to the Oracle WebLogic Server Administration Console.

Below the console banner at the top of the page, click Preferences > User Preferences.

Deselect Automatically Acquire Lock and Activate Changes.

Click Save and note that buttons such as Lock and Edit and Release Configuration are visible.

Note the following description that is displayed in the Oracle WebLogic Server Administration Console:

Automatically acquire the lock that enables configuration editing and
automatically activate changes as the user modifies, adds and deletes items
(for example, when the user clicks the 'Save' button). This feature is not
available in production mode.

This error can occur regardless of the deployment method you are using (for example, deploying through Oracle JDeveloper or through ant scripts).

43.9.6.7 Increasing Memory to Recover from Compilation Errors

If you receive out-of-memory errors during compilation of a SOA composite application, perform the following step to increase memory.

Under the scac element, increase the memory setting. For example:

<jvmarg value="-Xmx512M"/>

43.9.6.8 Oracle JDeveloper Compilation Error When Property Alias Definition is Missing for a Receive Activity with a Correlation Set

When a property alias definition is missing for a receive activity with a correlation set, the Oracle JDeveloper compiler fails with SCAC-50012 error.

Scripting on this page enhances content navigation, but does not change the content in any way.