1. Developing SOA Applications with Oracle SOA Suite
  2. Completing Your Application
  3. Deploying SOA Composite Applications

47 Deploying SOA Composite Applications

This chapter describes how to deploy SOA composite applications. You can 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.

This chapter includes the following sections:

See Administering Oracle SOA Suite and Oracle Business Process Management Suite for instructions about deploying SOA composite applications from Oracle Enterprise Manager Fusion Middleware Control and WLST Command Reference for SOA Suite for instructions about deploying SOA composite applications with the WLST utility.

47.1 Introduction to Deployment

This chapter describes the following deployment life cycle topics:

  • Deployment prerequisites

  • Packaging details

  • Anatomy of a composite

  • Target environment preparation

  • Target environment configuration tasks

  • Composite deployment

  • Postdeployment configuration tasks

  • Testing and troubleshooting composite applications

For more information about the deployment life cycle, see Administering Oracle Fusion Middleware.

47.2 Deployment Prerequisites

This section describes the basic prerequisites required for creating and deploying a SOA composite application.

47.2.1 Creating the Oracle SOA Suite Schema

Oracle SOA Suite components require schemas that must be installed in the Oracle or Microsoft SQL Server database. You create and load these schemas in your database with the Repository Creation Utility (RCU). For information about installing and configuring your schemas, see Installing and Configuring Oracle SOA Suite and Business Process Management and Creating Schemas with the Repository Creation Utility.

If you use the Oracle SOA Suite Quick Start installation in a development environment, the schema is automatically created in the Java database for you. For more information, see Installing SOA Suite and Business Process Management Suite Quick Start for Developers.

47.2.2 Creating a SOA Domain

After installation, you use the Oracle Fusion Middleware Configuration Wizard to create and configure a new Oracle WebLogic Server domain, and choose products such as Oracle SOA Suite to configure in that domain. This new domain contains the administration server and other managed servers, depending on the products you choose to configure. For more information, see Installing and Configuring Oracle SOA Suite and Business Process Management.

If you install the Oracle SOA Suite Quick Start, you can configure the Integrated WebLogic Server's default domain in Oracle JDeveloper. For information, see Installing SOA Suite and Business Process Management Suite Quick Start for Developers.

47.2.3 Configuring a SOA Cluster

You can deploy a SOA composite application into a clustered environment. For more information on creating and configuring a clustered environment, see High Availability Guide.

47.3 Understanding the Packaging Impact

You can separately package all required artifact files within the project of a SOA composite application into a SOA archive (SAR) JAR file though use of the following tools:

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:

47.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:

  • Binding components and service components.

  • References to Oracle B2B agreements, Oracle Web Service Manager (OWSM) policies, and human workflow task flows.

  • 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.

47.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.

47.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 47-1 require JDBC data sources and queues to be configured before deployment.

Table 47-1 Oracle JCA Adapter Tasks

Adapter Configuration Task See Section...

Database adapter

JDBC data source

“Deployment" of Understanding Technology Adapters

AQ adapter

JDBC data source

“Configuring the Data Sources in the Oracle WebLogic Server Administration Console" of Understanding Technology Adapters

JMS adapter

Queue

“Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter" of Understanding Technology Adapters
47.5.1.1 Script for Creation of JMS Resource and Redeployment of JMS Adapter

The following example provides a script for creating the JMS resource and redeploying the JMS adapter:

Note:

This script is for demonstration purposes. You may need to modify this script based on your environment.

# lookup the JMSModule 
    jmsSOASystemResource = lookup("SOAJMSModule","JMSSystemResource")
        
    jmsResource = jmsSOASystemResource.getJMSResource()
    
    cfbean = jmsResource.lookupConnectionFactory('DemoSupplierTopicCF')
    if cfbean is None:
        print "Creating DemoSupplierTopicCF connection factory"
        demoConnectionFactory =
 jmsResource.createConnectionFactory('DemoSupplierTopicCF')
        demoConnectionFactory.setJNDIName('jms/DemoSupplierTopicCF')
        demoConnectionFactory.setSubDeploymentName('SOASubDeployment')

    topicbean = jmsResource.lookupTopic('DemoSupplierTopic')
    if topicbean is None:
        print "Creating DemoSupplierTopic jms topic"
        demoJMSTopic = jmsResource.createTopic("DemoSupplierTopic")
        demoJMSTopic.setJNDIName('jms/DemoSupplierTopic')
        demoJMSTopic.setSubDeploymentName('SOASubDeployment')
        
try:
    save()
    # activate the changes
    activate(block="true")
    print "jms topic and factory for SOA Fusion Order Demo successfully created"
except:
    print "Error while trying to save and/or activate!!!"
    dumpStack()
    
print "Creating jms adapter connection factory information"
try:
     redeploy('JmsAdapter', '@deployment.plan@', upload='true', stageMode='stage') 
    
except:
    print "Error while modifying jms adapter connection factory"

For information about JMS queues and topics and connection factories, see Section "Configuring Basic JMS System Resources" of Administering JMS Resources for Oracle WebLogic Server.

47.5.1.2 Script for Creation of the Database Resource and Redeployment of the Database Adapter

The following example provides a script for creating the database resource and redeploying the database adapter.

Note:

This script is for demonstration purposes. You may need to modify this script based on your environment.

import os
connect(userName,passWord,'t3://'+wlsHost+':'+adminServerListenPort)
edit()
startEdit()

soaJDBCSystemResource1 = create('DBAdapterTestDataSource',"JDBCSystemResource")
soaJDBCResource1 = soaJDBCSystemResource1.getJDBCResource()
soaJDBCResource1.setName('DBAdapterDataSource')

soaConnectionPoolParams1 = soaJDBCResource1.getJDBCConnectionPoolParams()
soaConnectionPoolParams1.setTestTableName("SQL SELECT 1 FROM DUAL")

soaConnectionPoolParams1.setInitialCapacity(10)
soaConnectionPoolParams1.setMaxCapacity(100)

soaDataSourceParams1 = soaJDBCResource1.getJDBCDataSourceParams()
soaDataSourceParams1.addJNDIName('jdbc/dbSample')
soaDriverParams1 = soaJDBCResource1.getJDBCDriverParams()
soaDriverParams1.setUrl('jdbc:oracle:thin:@'+db_host_name+':'+db_port+':'+db_sid)
soaDriverParams1.setDriverName('oracle.jdbc.xa.client.OracleXADataSource')
soaDriverParams1.setPassword('my_password')

soaDriverProperties1 = soaDriverParams1.getProperties()
soaProperty1 = soaDriverProperties1.createProperty("user")
soaProperty1.setValue('scott')

varSOAServerTarget = '/Servers/'+serverName
soaServerTarget = getMBean(varSOAServerTarget)

soaJDBCSystemResource1.addTarget(soaServerTarget)

dumpStack()

try : 

save()

activate(block="true")

except:
    print "Error while trying to save and/or activate!!!"
    dumpStack()

print "Creating DB adapter resource  information"
try:
     redeploy('DBAdapter', '@deployment.plan@', upload='true', stageMode='stage') 
    
except:
    print "Error while modifying db adapter connection factory"

For information about JDBC data sources, see Section "Configuring JDBC Data Sources" of Administering JDBC Data Sources for Oracle WebLogic Server.

47.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.

For information about creating connection factories and connection pools, see Understanding Technology Adapters.

47.5.3 How to Enable Security

If you are using an identity service provider with human workflow or attaching authentication and authorization policies, you must perform additional setup tasks.

  • Identity service provider for human workflow

    By default, the identity service uses the embedded LDAP server in Oracle WebLogic Server as the default authentication provider. If you are using human workflow, you can configure Oracle WebLogic Server to use an alternative identity service provider, such as Oracle Internet Directory, Microsoft Active Directory, or Oracle iPlanet. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite. The embedded LDAP server is not supported in clustered environments.

  • Authentication provider (OWSM policies)

    Policies that use certain types of tokens (for example, the username, X.509, and SAML tokens) require an authentication provider. For information about selecting and configuring an authentication provider, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

  • Authorization provider (OWSM policies)

    After a user is authenticated, you must verify that the user is authorized to access a web service with an authorization policy. You can create an authorization policy with several types of assertion templates. For information about authorization policies and which resources to protect, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

47.5.4 How to Set the Business Flow Instance Name or Composite Instance Name at Design Time

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

47.5.4.1 Setting the Business Flow Instance Name in Oracle Mediator

To set the business flow instance name in Oracle Mediator:

Use the XPath expression function oraext:setFlowInstanceTitle() in an assign activity. For example: 

<assign>
   <copy
      target="$out.property.tracking.setFlowInstanceTitle"
      expression="oraext:setFlowInstanceTitle("sample")"
      xmlns:med="http://schemas.oracle.com/mediator/xpath"/>
</assign>
47.5.4.2 Setting the Business Flow Instance Name in a BPEL Process

A business flow instance corresponds to an end-to-end business transaction. Business flows consist of a single SOA composite application or multiple SOA composite applications connected together to fulfill a specific business process.

To set the business flow instance name in a BPEL process:

  1. Use the Java BPEL exec extension bpelx:exec. This extension includes the built-in method setFlowInstanceTitle(String title)for setting the business flow instance name.

    For more information about business flow instances, see Chapter "Tracking Business Flow Instances" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.5.4.3 Setting the Composite Instance Name in a BPEL Process

The setCompositeInstanceTitle method is provided for backward compatibility. The composite instance name is different from the business flow instance name. More than one composite instance can participate in a single business flow instance. There is a one-to-many relationship between the flow instance name and the composite instance name.

To set the composite instance name in a BPEL process:

  1. Use the Java BPEL exec extension bpelx:exec. This extension includes the built-in method setCompositeInstanceTitle(String title)for setting the instance name.

47.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 Using Oracle B2B.

  • Deploying the task flow

    You must deploy the task flow to use it in Oracle BPM Worklist. For more information, see Deploying the Profile.

47.5.6 How to Create an Application Server Connection

To deploy a SOA composite application that does not share data with another composite, use the Create Application Server Connection wizard to create an application server connection. For more information, see Creating an Application Server Connection.

47.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 Creating a SOA-MDS Connection.

47.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 Resources window, the file may not load correctly. Only open a composite from the Applications window.

For information about the Oracle MDS Repository, see Administering Oracle Fusion Middleware.

47.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.

47.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.

47.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 Map Editor. 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 Map Editor in Oracle JDeveloper when moving to and from test, development, and production environments. This ensures that the XSLT Map Editor 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 Map Editor, see Creating Transformations with the XSLT Map Editor .

  • 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.

47.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:

    • All import WSDLs

    • All reference binding.ws locations

The composite.xml file looks as shown in the following example: 

<composite .....>
  <import namespace="http://example.com/hr/"
 location="http://myserver17.us.example.com:8888/hrapp/HRAppService?WSDL"
 importType="wsdl"/>
  <service name="readPO">
    <interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/readPO/#wsdl.interface(Read
_ptt)"/>
    <binding.jca config="readPO_file.jca"/>
    <property name="inFileFolder" type="xs:string" many="false"
 override="may">/tmp/inFile</property>
  </service>
  <reference name="HRApp">
    <interface.wsdl
 interface="http://example.com/hr/#wsdl.interface(HRAppService)"/>
    <binding.ws
port="http://example.com/hr/#wsdl.endpoint(HRAppService/HRAppServiceSoapHttpPort)"
 location="http://myserver17.us.example.com:8888/hrapp/HRAppService?WSDL"/>
    <binding.java serviceName="{http://example.com/hr/}HRAppService"
 registryName="HRAppCodeGen_JBOServiceRegistry"/>
  </reference>
</composite>

The configuration plan file looks as shown in the following example:

<?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="FileAdaptorComposite">
    <service name="readPO">
      <binding type="*">
        <property name="inFileFolder">
          <replace>/mytestserver/newinFileFolder</replace>
        </property>
      </binding>
    </service>
  </composite>
  <!-- For all composite replace host and port in all imports wsdls -->
  <composite name="*">
    <import>
      <searchReplace>
        <search>myserver17</search>
        <replace>test-server</replace>
      </searchReplace>
      <searchReplace>
        <search>8888</search>
        <replace>8198</replace>
      </searchReplace>
    </import>
    <reference name="*">
      <binding type="ws">
        <attribute name="location">
          <searchReplace>
            <search>myserver17</search>
            <replace>test-server</replace>
          </searchReplace>
          <searchReplace>
            <search>8888</search>
            <replace>8198</replace>
          </searchReplace>
        </attribute>
      </binding>
    </reference>
  </composite>
</SOAConfigPlan>

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.

47.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:

  1. User A creates SOA composite application Foo.

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

  3. 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.

  4. 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.

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

47.6.1.3.1 How to Use a Configuration Plan when Creating Environment-Independent Processes

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.

  1. User A creates SOA composite application Foo.

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

  3. 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.

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

  5. User B checks out Foo from source control.

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

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

  8. User B checks in both Foo and configuration plan B (which matches user B's environment).

  9. User A checks out Foo again, along with both configuration plans.

47.6.1.4 How to Create a Configuration Plan in Oracle JDeveloper

This section describes how to create and use a configuration plan. In particular, this section describes the following:

  • Creating and editing a configuration plan

  • Attaching the configuration plan to a SOA composite application JAR file

  • Validating the configuration plan

  • Deploying the SOA composite application JAR or ZIP file in which the configuration plan is included

To create a configuration plan in Oracle JDeveloper:

  1. Open Oracle JDeveloper.
  2. In the Applications window, right-click the composite_name file (also known as the composite.xml file) of the project in which to create a configuration plan, and select Generate Config Plan. Figure 47-1 provides details.

    Figure 47-1 Generate a Configuration Plan

    Description of Figure 47-1 follows
    Description of "Figure 47-1 Generate a Configuration Plan"

    The Composite Configuration Plan Generator dialog appears, as shown in Figure 47-2.

    Figure 47-2 Composite Configuration Plan Generator Dialog

    Description of Figure 47-2 follows
    Description of "Figure 47-2 Composite Configuration Plan Generator Dialog"
  3. Create a configuration plan file for editing, as shown in Table 47-2.

    Table 47-2 Generate a Configuration Plan

    Field Description

    Specify the file name (.xml) for the configuration plan

    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 Deploying the Profile.

    Overwrite existing file

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

    This creates and opens a single configuration plan file for editing. You can modify URLs and properties for the composite.xml, WSDL, and schema files of the SOA composite application. Figure 47-3 provides details.

    Figure 47-3 Configuration Plan Editor

    Description of Figure 47-3 follows
    Description of "Figure 47-3 Configuration Plan Editor"
  5. 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.
  6. From the File menu, select Save All.
  7. Above the editor, click the x to the right of the file name to close the configuration plan file.
  8. In the Applications window, right-click the composite_name file again, and select Validate Config Plan.

    The Composite Configuration Plan Validator appears, as shown in Figure 47-4.

    Figure 47-4 Validate the Configuration Plan

    Description of Figure 47-4 follows
    Description of "Figure 47-4 Validate the Configuration Plan"
  9. 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.
  10. 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.

  11. 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 Deploying the Profile prompts you to select the configuration plan to include in the SOA composite application archive.

  12. Select the configuration plan to include with the SOA composite application.
  13. Click OK.
47.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:

  • Generate a configuration plan for editing:

    sca_generatePlan(configPlan, sar, composite, overwrite, verbose)

  • Attach the configuration plan file to the SOA composite application JAR file:

    sca_attachPlan(sar, configPlan, overwrite, verbose)

  • Validate the configuration plan:

    sca_validatePlan(reportFile, configPlan, sar, composite, overwrite, verbose)

  • Extract a configuration plan packaged with the JAR file for editing:

    sca_extractPlan(sar, configPlan, overwrite, verbose)

For information about using these commands, see WLST Command Reference for SOA Suite.

47.6.1.6 How to Attach a Configuration Plan with ant Scripts

As an alternative to using Oracle JDeveloper, you can use ant scripts to attach the configuration plan file to the SOA composite application JAR or ZIP file during deployment. For instructions, see How to Use ant to Deploy a SOA Composite Application.

47.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.

For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.7 Deploying SOA Composite Applications or Projects in Oracle JDeveloper

This section describes how to deploy SOA composite applications or projects in JDeveloper in the following topics:

Note:

Oracle recommends that you deploy SOA projects that are developed in Reference Configuration mode to a server that is in a Reference Configuration domain. Contact your server administrator to move the server into a Reference Configuration domain. If the SOA project is developed in Classic mode and the server to which it is deployed is in a Reference Configuration domain, or vice versa, JDeveloper displays a Mismatch notification in the Deploy Composite Wizard. You can click OK and deploy the SOA project even when there is a configuration mismatch. In this case, deployment will proceed as normal and any Reference Configuration property settings will be ignored by the domain.

Note that the integrated WebLogic server in JDeveloper does not support a Reference Configuration domain.

47.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.

47.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 using the IntegratedWebLogicServer connection available with the Oracle SOA Suite Quick Start installation, see Installing SOA Suite and Business Process Management Suite Quick Start for Developers.

Note:

You can also create an application server connection by selecting Window > Application Servers, then right-clicking the Application Servers node in the Applications window and selecting New Application Server. This option prompts you to create a standalone server connection or Integrated WebLogic Server connection.

To create an application server connection:

  1. From the File main menu, select New.
  2. In the General list, select Connections.
  3. Select Application Server Connection, and click OK.

    The Name and Type page appears.

  4. In the Connection Name field, enter a name for the connection.
  5. In the Connection Type list, select WebLogic 12.x to create a connection to Oracle WebLogic Server.
  6. Click Next.

    The Authentication page appears.

  7. In the Username field, enter the user authorized for access to the application server.
  8. In the Password field, enter the password for this user.
  9. Click Next.

    The Configuration page appears.

  10. In the Weblogic Hostname (Administration Server) field, enter the host on which the Oracle WebLogic Server is installed.
  11. In the Port and SSL Port fields, enter appropriate port values or accept the default values.
  12. If you want to use secure socket layer (SSL), select the Always use SSL check box. Table 47-3 describes what occurs when you select this check box.

    Table 47-3 Deployment to HTTPS and HTTP Servers

    If This Check Box 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.

  13. In the WebLogic Domain field, enter the Oracle SOA Suite domain. For additional details about specifying domains, click Help. Figure 47-5 provides details.

    Figure 47-5 Server Name and Domain Selection

    Description of Figure 47-5 follows
    Description of "Figure 47-5 Server Name and Domain Selection"
  14. Click Next.
  15. Click Test Connection to test your server connection.
  16. If the connection is successful, click Finish. Otherwise, click Back to make corrections in the previous dialogs. Even if the connection test is unsuccessful, a connection is created. Figure 47-6 provides details.

    Figure 47-6 Application Server Connection Test

    Description of Figure 47-6 follows
    Description of "Figure 47-6 Application Server Connection Test"
47.7.1.2 Optionally Creating a Project Deployment Profile

A required deployment profile is automatically created for your project. The application profile includes the JAR files of your SOA projects. If you want, you can create additional profiles.

To create a project deployment profile:

  1. In the Applications window, right-click the SOA project.
  2. Select Project Properties.

    The Project Properties dialog appears.

  3. Click Deployment.
  4. Click the New Profile icon.

    The Create Deployment Profile dialog appears.

  5. Enter the values shown in Table 47-4.

    Table 47-4 Create Deployment Profile Dialog Fields and Values

    Field Description

    Profile Type

    Select SOA-SAR File.

    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).

    Deployment Profile Name

    Enter a deployment profile name.

    Description

    Enter a description for the profile name.
  6. Click OK.

    The SAR Deployment Profile Properties dialog appears, as shown in Figure 47-7.

    Figure 47-7 SAR Deployment Profile Properties

    Description of Figure 47-7 follows
    Description of "Figure 47-7 SAR Deployment Profile Properties"
  7. Optionally specify the target folder in which to save the SAR file.
  8. Click OK to close the SAR Deployment Profile Properties dialog.

    The deployment profile shown in Figure 47-8 displays in the Project Properties dialog.

    Figure 47-8 Project Profile

    Description of Figure 47-8 follows
    Description of "Figure 47-8 Project Profile"
47.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 Creating an Application Server Connection.

To deploy the profile:

  1. In the Applications window, right-click the SOA project.

  2. Select Deploy > project_name.

    The value for project_name is the SOA project name.

    The Deployment Action page of the Deploy Project_Name wizard appears. Figure 47-9 provides an example.

    Figure 47-9 Deployment Action Page

    Description of Figure 47-9 follows
    Description of "Figure 47-9 Deployment Action Page"

  3. Select one of the following deployment options:

    • Deploy to Application Server

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

    • Generate SAR File

      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.

    The page that displays differs based on your selection.

  4. Select the deployment option appropriate for your environment. Table 47-5 provides details.

    Table 47-5 Deployment Target

    If You Select... Go to...

    Deploy to Application Server

    Step 44.a

    Generate SAR File

    Step 44.b

    1. View the Deploy Configuration page shown in Figure 47-10.

      Figure 47-10 Deploy Configuration Page for Application Server Deployment

      Description of Figure 47-10 follows
      Description of "Figure 47-10 Deploy Configuration Page for Application Server Deployment"

    2. View the Deploy Configuration page shown in Figure 47-11.

      Figure 47-11 Deploy Configuration Page for Generate SAR File Deployment

      Description of Figure 47-11 follows
      Description of "Figure 47-11 Deploy Configuration Page for Generate SAR File Deployment"

  5. Provide values appropriate to the deployment option you selected in Step 4, as described in Table 47-6. If you selected to deploy to an application server, additional fields are displayed.

    Table 47-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. You can specify a new value or continue to use the current value. This revision ID becomes the value for the ${composite.revision_id} variable in the application name. For example, if you enter 2.0 as the new revision ID for a composite named OrderBooking, ${composite.revision_id} is replaced with _rev2.0 (sca_OrderBooking_rev2.0.jar).

    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.

    See How to Use Configuration Plans to Customize SOA Composite Applications for the Target Environment for instructions on creating a configuration plan.

    BPEL Monitor

    Expand to display details about BPEL monitors.

    • Ignore BPEL Monitor deployment errors

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

    Deselect this check box to display BPEL Monitor deployment errors. This check box 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.

    This 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.

    This 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 being aborted. 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 check box 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 aborted and deployment is successful. If they are incompatible, deployment fails unless you select this check box.

    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.

  6. When finished, click Next.

  7. 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 47-12.

    Otherwise, go to Step 10.

    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.

    Figure 47-12 Task Flow Deployment Page

    Description of Figure 47-12 follows
    Description of "Figure 47-12 Task Flow Deployment Page"

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

    Table 47-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 check box 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 check box 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 check box 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.

    For information about deploying SOA composite applications with task flows to multiple partition environments, see What You May Need to Know About Deploying Human Task Composites with Task Flows to Partitions.

  9. Click Next.

  10. 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 47-13 provides details.

    If you selected to generate a SAR file in Step 3, go to Step 15.

    Figure 47-13 Select Server Page

    Description of Figure 47-13 follows
    Description of "Figure 47-13 Select Server Page"

  11. Click Next.

  12. 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 47-14 provides details.

  13. 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.

    Figure 47-14 SOA Servers Page

    Description of Figure 47-14 follows
    Description of "Figure 47-14 SOA Servers Page"

  14. Click Next.

  15. Review the archive details on the Summary page shown in Figure 47-15, and click Finish.

    Figure 47-15 Summary Page

    Description of Figure 47-15 follows
    Description of "Figure 47-15 Summary Page"

  16. If you selected to deploy to an application server in Step 3, view the messages that display in the Deployment log window at the bottom of Oracle JDeveloper.

  17. Enter the user name and password, and click OK.

    If deployment is successful, the following actions occur:

    • A JAR file for the SOA project is created with a naming convention of sca_composite_name_revrevision_number.jar.

    • The project is displayed in the Resources window under application_server_connection_name > SOA > SOA_server_name > partition_name.

    • The project is displayed in the Application Servers window under application_server_connection_name > SOA > SOA_server_name > partition_name.

    You are now ready to monitor your application from Oracle Enterprise Manager Fusion Middleware Control. See Administering Oracle SOA Suite and Oracle Business Process Management Suite for details.

    If deployment is unsuccessful, view the messages that display in the Deployment log window and take corrective actions. For more information, see Testing and Troubleshooting.

    For information about creating partitions, see the following documentation:

    Note:

    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 check box on the Deploy Configuration page.

47.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). The following example provides details: 

<hwTaskFlows
 xmlns="http://xmlns.oracle.com/bpel/workflow/hwTaskFlowProperties">
   <ApplicationName>worklist</ApplicationName>
   <LookupType>LOCAL</LookupType>
   <TaskFlowDeploy>false</TaskFlowDeploy>
   <PartitionName>partition2</PartitionName>

If you want to deploy the task flow for the SOA composite application on all partitions, leave PartitionName blank. If you want to use different task flows for the composites on different partitions, then PartitionName must be specified.

In addition, if you want to reuse the same task flow project for another partition, you must change the web context root.

47.7.2 How to Deploy Multiple SOA Composite Applications in Oracle JDeveloper

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.

Note:

  • This section assumes you have created an application server connection. If not, see Creating an Application Server Connection for instructions.

  • 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:

  1. From the Application menu, select Application Properties, as shown in Figure 47-16.

    Figure 47-16 Application Properties

    Description of Figure 47-16 follows
    Description of "Figure 47-16 Application Properties"
  2. In the Application Properties dialog, click Deployment.
  3. Click New.

    The Create Deployment Profile dialog appears.

  4. In the Archive Type list, select SOA Bundle.
  5. In the Name field, enter a name.

    Figure 47-17 provides details.

    Figure 47-17 Select the SOA Bundle

    Description of Figure 47-17 follows
    Description of "Figure 47-17 Select the SOA Bundle"
  6. Click OK.
  7. In the navigator on the left, select the Dependencies node.
  8. Select the SARs you want to include in this bundle, as shown in Figure 47-18.
  9. Click OK.
  10. Click OK to close the Application Properties dialog.
  11. Select the Application menu again, then select Deploy > SOA_Bundle_Name.

    This invokes the deployment wizard.

  12. See Step 3 for details about responses to provide.

47.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.

Note:

  • 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/credit card, the JAR file must include the demo/credit card 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

47.7.3.1 Create a JAR Profile and Include the Artifacts to Share

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

  1. In the Applications window, right-click the SOA project.
  2. Select Project Properties.

    The Project Properties dialog appears.

  3. Click Deployment in the navigational tree on the left.
  4. Click New.

    The Create Deployment Profile dialog appears.

  5. From the Archive Type list, select JAR File.
  6. In the Name field, enter a name (for this example, shared_archive is entered).

    The Create Deployment Profile dialog looks as shown in Figure 47-19.

    Figure 47-19 JAR File Selection

    Description of Figure 47-19 follows
    Description of "Figure 47-19 JAR File Selection"
  7. Click OK.

    The JAR Deployment Profile Properties dialog appears.

  8. Select JAR Options from the navigational tree on the left.
  9. Deselect Include Manifest File (META-INF/MANIFEST.MF), as shown in Figure 47-20.

    This prevents the archive generator from adding the manifest file (META-INF/MANIFEST.MF) into the JAR file.

    Figure 47-20 JAR File Options

    Description of Figure 47-20 follows
    Description of "Figure 47-20 JAR File Options"
  10. Select File Groups > Project Output > Contributors from the navigational tree on the left.
  11. Deselect the Project Output Directory and Project Dependencies options, as shown in Figure 47-21.

    This prevents the archive generator from adding the contents of the project output and project dependencies into the archive.

    Figure 47-21 Contributors

    Description of Figure 47-21 follows
    Description of "Figure 47-21 Contributors"
  12. Click Add to add a new contributor.

    The Add Contributor dialog appears. This dialog enables you to add artifacts to your archive.

  13. Click Browse.
  14. Select the folder in which your artifacts reside, as shown in Figure 47-22. This selection also determines the hierarchy of artifacts in the archive.

    Figure 47-22 Artifact Selection

    Description of Figure 47-22 follows
    Description of "Figure 47-22 Artifact Selection"
  15. Click Select to close the Choose Directory dialog.
  16. Click OK to close the Add Contributor dialog.
  17. Select File Groups > Project Output > Filters from the navigational tree on the left.
  18. Select only the artifacts to include in the archive, as shown in Figure 47-23. For this example, the archive contains the following XSD files:

    • SOADemoComposite/xsd/DemoProcess.xsd

    • SOADemoComposite/xsd/Quote.xsd

    • SOADemoComposite/xsd/VacationRequest.xsd

    Figure 47-23 Artifacts to Include in the Archive

    Description of Figure 47-23 follows
    Description of "Figure 47-23 Artifacts to Include in the Archive "
  19. Click OK to save changes to the JAR deployment profile.
  20. Click OK to save the new deployment profile.
  21. From the File main menu, select Save All.
47.7.3.2 Create a SOA Bundle that Includes the JAR Profile

To create a SOA bundle that includes the JAR profile:

  1. From the Application Menu, select Application Properties > Deployment.
  2. Click New to create a SOA bundle profile.

    The Create Deployment Profile dialog appears.

  3. From the Archive Type list, select SOA Bundle. A bundle is a collection of multiple SOA composite applications.
  4. In the Name field, enter a name (for this example, sharedArtifactBundle is entered). Figure 47-24 provides details.

    Figure 47-24 SOA Bundle Creation

    Description of Figure 47-24 follows
    Description of "Figure 47-24 SOA Bundle Creation"
  5. Click OK.
  6. Select Dependencies from the navigational tree on the left.
  7. 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 47-25 provides details.

    Figure 47-25 Deployment Profile Dependencies

    Description of Figure 47-25 follows
    Description of "Figure 47-25 Deployment Profile Dependencies"
  8. Click OK to save the SOA bundle deployment profile changes.
  9. Click OK to save the new deployment profile.
  10. From the File main menu, select Save All.
47.7.3.3 Deploy the SOA Bundle with Oracle JDeveloper

To deploy the SOA bundle with Oracle JDeveloper:

  1. Right-click the Application menu and select Deploy > SOA_Bundle_Name.

    This invokes the deployment wizard.

  2. See Step 3 of Deploying the Profile for details about responses to provide.

    This deploys the SOA bundle to the application server (shared artifacts are deployed to the Oracle MDS Repository database of Oracle SOA Suite).

47.7.3.3.1 To deploy the SOA bundle with ant:
47.7.3.4 Use Shared Data

This section describes how to browse and select the shared data you created in How to Deploy and Use Shared Data Across Multiple SOA Composite Applications in Oracle JDeveloper.

47.7.3.4.1 Creating a SOA-MDS Connection

To create a SOA-MDS connection:

  1. From the File menu, select New > Application > Connections > SOA-MDS Connection.

    The Create SOA-MDS Connection dialog shown in Figure 47-26 is displayed.

    Figure 47-26 Create SOA-MDS Connection Dialog

    Description of Figure 47-26 follows
    Description of "Figure 47-26 Create SOA-MDS Connection Dialog"
  2. Provide values appropriate to your environment, as shown in Table 47-8.

    Table 47-8 Create SOA-MDS Connection Dialog

    Field Description

    Create Connection In:

    Ensure that IDE Connection is selected. This option enables the connection to display in the Resources window 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 Resources window.

    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.
  3. Click OK.

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

47.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:

  1. Create a new BPEL process service component in a different application.
  2. In the Create BPEL Process dialog, click the Browse icon to the right of the Input field.

    The Type Chooser dialog appears.

  3. In the upper right corner, click the Import Schema File icon.

    The Import Schema File dialog appears.

  4. To the right of the URL field, click the Browse icon.

    The SOA Resource Browser dialog appears.

  5. At the top of the dialog, select SOA-MDS.
  6. Select shared data. For this example, the Quote.xsd file that you selected to include in the archive in Step 18 of "Create a JAR Profile and Include the Artifacts to Share is selected.
  7. Click OK.
  8. In the Import Schema File dialog, click OK.
  9. In the Type Chooser dialog, select a node of Quote.xsd (for this example, QuoteRequest), and click OK.
  10. In the Create BPEL Process dialog, click OK to complete creation.
  11. In the Applications window, select the WSDL file for the BPEL process.
  12. Click Source.

    The WSDL file includes the following definition.

    <wsdl:types>
  <schema xmlns="http://www.w3.org/2001/XMLSchema">
    <import namespace="http://www.mycompany.com/ns/salesquote"
 schemaLocation="oramds:/apps/SOADemoComposite/xsd/Quote.xsd" />
  </schema>
</wsdl:types>
  13. Continue modeling the BPEL process as necessary.
  14. Deploy the SOA composite application that includes the BPEL process.

    The Type Chooser dialog includes a Recent Files folder in which information is kept for the duration of the Oracle JDeveloper session. For example, if you create a new BPEL process and want to define the input variable from a schema in the SOA Design-Time MDS Repository, you go there once. When you want to define the output variable from the same schema, the schema remains visible in the Recent Files folder.

47.7.4 How to Deploy an Existing SOA Archive in Oracle JDeveloper

You can deploy an existing SOA archive from the Application Servers window in Oracle JDeveloper.

Note:

  • 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 > Application > Connections > Application Server Connection to create a connection.

To deploy an existing SOA archive from Oracle JDeveloper:

  1. From the Window menu, select Application Servers.
  2. In the Applications window, expand your connection name.
  3. Right-click the SOA folder.
  4. Select Deploy SOA Archive.

    Figure 47-27 SOA Archive Deployment from the Applications Window

    Description of Figure 47-27 follows
    Description of "Figure 47-27 SOA Archive Deployment from the Applications Window"

    The Deploy SOA Archive dialog shown in Figure 47-28 appears.

    Figure 47-28 Deploy SOA Archive Dialog

    Description of Figure 47-28 follows
    Description of "Figure 47-28 Deploy SOA Archive Dialog"
  5. Provide responses appropriate to your environment, as described in Table 47-9.

    Table 47-9 Deploy SOA Archive 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.

    Archive Location

    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.

    For information about creating configuration plans, see How to Create a Configuration Plan in or How to Create a Configuration Plan with the WLST Utility.

    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.

    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 aborted.
  6. Click OK.

For more information on deploying and testing SOA composite applications from the Application Servers window, see Managing and Testing a SOA Composite Application.

47.8 Deploying and Managing SOA Composite Applications with the WLST Utility

You can manage SOA composite applications with the WLST utility. This utility is well-suited for automation and can be easily integrated into existing release processes. For instructions, see WLST Command Reference for SOA Suite.

47.9 Deploying and Managing 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.

Note:

Before using the Oracle SOA Suite ant scripts, you must first run the setDomainEnv.sh script (for Linux) or setDomainEnv.cmd script (for Windows). This script adds the necessary JAR files for using ant to the classpath.

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

Table 47-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.xml undeploy

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.xml startComposite

Starts a SOA composite application.

ant-sca-mgmt.xml stopComposite

Stops a SOA composite application.

ant-sca-mgmt.xml activateComposite

Activates a SOA composite application.

ant-sca-mgmt.xml retireComposite

Retires a SOA composite application.

ant-sca-mgmt.xml assignDefaultComposite

Assigns a default revision version.

ant-sca-mgmt.xml listDeployedComposites

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.xml createPartition

Creates a partition in the SOA Infrastructure.

ant-sca-mgmt.xml deletePartition

Undeploys all composites in a partition before deleting the partition.

ant-sca-mgmt.xml startCompositesInPartition

Starts all composites in a partition.

ant-sca-mgmt.xml stopCompositesInPartition

Stops all composites in a partition.

ant-sca-mgmt.xml activateCompositesInPartition

Activates all composites in a partition.

ant-sca-mgmt.xml retireCompositesInPartition

Retires all composites in a partition.

ant-sca-upgrade.xml

Migrates BPEL and Oracle Enterprise Service Bus (ESB) release 10.1.3 metadata to release 11g.

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.

For additional information about ant, visit the following URL: 

http://ant.apache.org

47.9.1 How to Use ant to Automate the Testing of a SOA Composite Application

The following provides an example of executing a test case. Test cases enable you to automate the testing of SOA composite applications:

ant -f ant-sca-test.xml -Dscatest.input=MyComposite
-Djndi.properties=/home/jdoe/jndi.properties

Table 47-11 describes the syntax.

Table 47-11 ant Testing Commands

Argument Definition 
scatest

Possible inputs are as follows:

  • java.passed.home

    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).

  • scatest.input

    The name of the composite to test.

  • scatest.format

    The format of the output file (defaults to native; the other option is junit).

  • scatest.result

    The result directory in which to place the output files (defaults to temp_dir/out).

  • jndi.properties.input

    The jndi.properties file to use. 

jndi. properties

Absolute path to the JNDI property file. This is a property file that contains JNDI properties for connecting to the server. For example:

java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
java.naming.provider.url=t3://myserver.us.example.com:8001/soa-infra
java.naming.security.principal=weblogic
dedicated.connection=true
dedicated.rmicontext=true

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.

For more information on creating and running tests on SOA composite applications, see Automating Testing of SOA Composite Applications and Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.9.2 How to Use ant to Compile a SOA Composite Application

The following provides an example of compiling a SOA composite application, which validates it for structure and syntax:

ant -f ant-sca-compile.xml 
-Dscac.input=/myApplication/myComposite/composite.xml

Table 47-12 describes the syntax.

Table 47-12 ant Compiling Commands

Argument Definition 
scac

Possible inputs are as follows:

  • java.passed.home

    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.

  • 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. This argument is optional only when you compile the SOA composite application from within the project directory.

  • scac.displayLevel

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

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

The following 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.

ant -f ant-sca-package.xml 
-DcompositeDir=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POPr
ocessing 
-DcompositeName=POProcessing 
-Drevision=6-cmdline 
-Dsca.application.home=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProces
sing

Table 47-13 describes the syntax.

Table 47-13 ant Packaging Commands

Argument Definition 
compositeDir

Absolute path of a directory that contains composite artifacts.

 
compositeName

Name of the composite.

 
revision

Revision ID of the composite.

 
sca.application.home

Absolute path of the application home directory. This property is required if your SOA composite application accesses shared artifacts in the MDS Repository. If not, it is optional.

 
oracle.home

Optional. The oracle.home property.

47.9.4 How to Use ant to Deploy a SOA Composite Application

The following provides an example of deploying a SOA composite application. You can also use this command to deploy shared data such as WSDLs, XSDs, and other file types across SOA composite applications. For information about shared data, see How to Deploy and Use Shared Data Across Multiple SOA Composite Applications in Oracle JDeveloper. 

ant -f ant-sca-deploy.xml 
-DserverURL=http://localhost:8001 
-DsarLocation=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POPro
cessing\deploy\sca_POProcessing_rev6-cmdline.jar 
-Doverwrite=true 
-Duser=weblogic 
-DforceDefault=true 
-Dconfigplan=C:\demo\end2end-105-POProcessing\po\solutions\ch9\POProcessing\POProc
 essing\demed_cfgplan.xml
-Dscac.user.classpath=C:\jarfolder\custom.jar
-Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-14 describes the syntax.

Table 47-14 ant Deployment Commands

Argument Definition

serverURL

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.

47.9.5 How to Use ant to Undeploy a SOA Composite Application

The following provides an example of undeploying a SOA composite application.

ant -f ant-sca-deploy.xml undeploy 
-DserverURL=http://localhost:8001 
-DcompositeName=POProcessing 
-Drevision=rev6-cmdline
-Duser=weblogic 
-Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-15 describes the syntax.

Table 47-15 ant Undeployment Commands

Argument Definition

serverURL

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.

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

The following provides an example of exporting a composite into a SAR file.

ant -f ant-sca-deploy.xml exportComposite -DserverURL=server.url
 -DupdateType=update.type -DsarFile=sar.file
 -DcompositeName=composite.name -Drevision=revision -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-16 describes the syntax.

Table 47-16 ant Export Commands

Argument Definition

serverURL

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

updateType

The type of postdeployment changes to be included:

  • none: No postdeployment changes are included.

  • all: All postdeployment changes are included.

  • property: Property changes are included (binding component properties, composite properties such as audit level settings and payload validation status, and policy attachments).

  • runtime: Postdeployment runtime changes are included (rules dictionary and domain value maps (DVMs)).

sarFile

The absolute path of the SAR file to be generated.

compositeName

The name of the composite to be exported.

revision

The revision of the composite to be exported.

user

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

password

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

The following example shows how to export a composite without including any postdeployment changes:

ant -f ant-sca-deploy.xml exportComposite -DserverURL=http://myhost:8001
 -DupdateType=none
 -DsarFile=/tmp/sca_HelloWorld_rev1.0.jar -DcompositeName=HelloWorld
 -Drevision=1.0

The following example shows how to export a composite with all postdeployment changes:

ant -f ant-sca-deploy.xml exportComposite -DserverURL=http://myhost:8001
 -DupdateType=all
 -DsarFile=/tmp/sca_HelloWorld_rev1.0-all.jar -DcompositeName=HelloWorld
 -Drevision=1.0

The following example shows how to export a composite with property postdeployment updates:

ant -f ant-sca-deploy.xml exportComposite -DserverURL=http://myhost:8001
 -DupdateType=property
 -DsarFile=/tmp/sca_HelloWorld_rev1.0-prop.jar -DcompositeName=HelloWorld
 -Drevision=1.0

The following example shows how to export a composite with runtime/metadata postdeployment updates:

ant -f ant-sca-deploy.xml exportComposite -DserverURL=http://myhost:8001
 -DupdateType=runtime
 -DsarFile=/tmp/sca_HelloWorld_rev1.0-runtime.jar
 -DcompositeName=HelloWorld -Drevision=1.0

47.9.7 How to Use ant to Export Postdeployment Changes of a Composite into a JAR File

The following provides an example of exporting postdeployment changes of a composite into a JAR file.

ant -f ant-sca-deploy.xml exportUpdates -DserverURL=server.url
 -DupdateType=update.type -DjarFile=jar.file
 -DcompositeName=composite.name -Drevision=revision -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-17 describes the syntax.

Table 47-17 ant Postdeployment Export Commands

Argument Definition

serverURL

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

updateType

The type of postdeployment changes to be exported.

  • all: Includes all postdeployment changes.

  • property: Includes only property postdeployment changes (binding component properties, composite properties such as audit level settings and payload validation status, and policy attachments).

  • runtime: Includes only runtime (rules dictionary and domain value maps (DVMs)).

jarFile

The absolute path of the JAR file to be generated.

compositeName

The name of the composite to be exported.

revision

The revision of the composite to be exported.

user

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

password

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

The following example shows how to export all postdeployment updates:

ant -f ant-sca-deploy.xml exportUpdates -DserverURL=http://myhost:8001
 -DupdateType=all
 -DjarFile=/tmp/all-HelloWorld_rev1.0.jar -DcompositeName=HelloWorld
 -Drevision=1.0

The following example shows how to export property postdeployment updates:

ant -f ant-sca-deploy.xml exportUpdates -DserverURL=http://myhost:8001
 -DupdateType=property
 -DjarFile=/tmp/prop-HelloWorld_rev1.0.jar -DcompositeName=HelloWorld
 -Drevision=1.0

The following example shows how to export runtime/metadata postdeployment updates.

ant -f ant-sca-deploy.xml exportUpdates -DserverURL=http://myhost:8001
 -DupdateType=runtime
 -DjarFile=/tmp/runtime-HelloWorld_rev1.0.jar -DcompositeName=HelloWorld
 -Drevision=1.0

47.9.8 How to Use ant to Import Postdeployment Changes of a Composite

The following provides an example of importing postdeployment changes of a composite.

ant -f ant-sca-deploy.xml importUpdates -DserverURL=server.url -DjarFile=jar.file
 -DcompositeName=composite.name -Drevision=revision -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-18 describes the syntax.

Table 47-18 ant Postdeployment Import Commands

Argument Definition

serverURL

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

jarFile

The absolute path of the JAR file that contains postdeployment changes.

compositeName

The name of the composite into which the postdeployment changes are imported.

revision

The revision of the composite to which the postdeployment changes are imported.

user

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

password

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

The following example shows how to import postdeployment changes of a composite:

ant -f ant-sca-deploy.xml importUpdates -DserverURL=http://myhost:8001
 -DjarFile=/tmp/prop-HelloWorld_rev1.0.jar -DcompositeName=HelloWorld
 -Drevision=1.0

47.9.9 How to Use ant to Export Shared Data of a Given Pattern into a JAR File

The following provides an example of exporting shared data of a given pattern into a JAR file.

ant -f ant-sca-deploy.xml exportSharedData -DserverURL=server.url
 -DjarFile=jar.file -Dpattern=pattern -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-19 describes the syntax.

Table 47-19 ant Shared Data Export Commands

Argument Definition

serverURL

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.

The following example shows how to export shared data of a given pattern into a JAR file.

ant -f ant-sca-deploy.xml exportSharedData -DserverURL=http://myhost:8001
 -DjarFile=/tmp/MySharedData.jar
 -Dpattern="/Project1/**"

47.9.10 How to Use ant to Remove a Top-level Shared Data Folder

The following provides an example of removing a top-level shared data folder, even if there are composites deployed in the service engine:

ant -f ant-sca-deploy.xml removeSharedData -DserverURL=server.url
 -DfolderName=folder.name -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-20 describes the syntax.

Table 47-20 ant Shared Data Folder Removal Commands

Argument Definition

serverURL

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

foldername

The name of the top-level shared data folder to remove.

user

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

password

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

The following example shows how to remove a top-level shared data folder named Project1: 

ant -f ant-sca-deploy.xml removeSharedData -DserverURL=http://myhost:8001
 -DfolderName=Project1

47.9.11 How to Use ant to Start a SOA Composite Application

The following provides an example of starting a SOA composite application:

ant -f ant-sca-mgmt.xml startComposite -Dhost=myhost -Dport=8001 -Duser=weblogic
  -DcompositeName=HelloWorld -Drevision=1.0 -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-21 describes the syntax.

Table 47-21 ant SOA Composite Application Startup Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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.

47.9.12 How to Use ant to Stop a SOA Composite Application

The following provides an example of stopping a SOA composite application:

ant -f ant-sca-mgmt.xml stopComposite -Dhost=myhost -Dport=8001 -Duser=weblogic
-DcompositeName=HelloWorld -Drevision=1.0 -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-22 describes the syntax.

Table 47-22 ant SOA Composite Application Stop Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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.

47.9.13 How to Use ant to Activate a SOA Composite Application

The following provides an example of activating a SOA composite application.

ant -f ant-sca-mgmt.xml activateComposite -Dhost=myhost -Dport=8001
-Duser=weblogic-DcompositeName=HelloWorld -Drevision=1.0 -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-23 describes the syntax.

Table 47-23 ant SOA Composite Application Activation Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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.

47.9.14 How to Use ant to Retire a SOA Composite Application

The following provides an example of retiring a SOA composite application:

ant -f ant-sca-mgmt.xml retireComposite -Dhost=myhost -Dport=8001 -Duser=weblogic
-DcompositeName=HelloWorld -Drevision=1.0 -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-24 describes the syntax.

Table 47-24 ant SOA Composite Application Retirement Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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.

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

The following provides an example of assigning the default version to a SOA composite application.

ant -f ant-sca-mgmt.xml assignDefaultComposite -Dhost=myhost -Dport=8001
-Duser=weblogic -DcompositeName=HelloWorld -Drevision=1.0 -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-25 describes the syntax.

Table 47-25 ant SOA Composite Application Default Version Assignment Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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.

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

The following provides an example of listing the deployed SOA composite applications.

ant -f ant-sca-mgmt.xml listDeployedComposites -Dhost=myhost -Dport=8001
-Duser=weblogic

Note:

After specifying the user name, enter the password when prompted.

Table 47-26 describes the syntax.

Table 47-26 ant SOA Composite Application Deployment List Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

47.9.17 How to Use ant to List All Available Partitions in the SOA Infrastructure

The following provides the syntax for listing all available partitions in the SOA Infrastructure.

ant -f ant-sca-mgmt.xml listPartitions -Dhost=host -Dport=port -Duser=user

Note:

After specifying the user name, enter the password when prompted.

Table 47-27 describes the syntax.

Table 47-27 ant SOA Infrastructure Partitioning List Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

The following provides an example of listing all available partitions in the SOA Infrastructure:

ant -f ant-sca-mgmt.xml listPartitions -Dhost=myhost10 -Dport=8001

47.9.18 How to Use ant to List All Composites in a Partition

The following provides the syntax for listing all composites in a partition.

ant -f ant-sca-mgmt.xml listCompositesInPartition -Dhost=host -Dport=port -Duser=user -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-28 describes the syntax.

Table 47-28 ant Composite Partitioning List Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition.

The following provides an example of listing all composites in a partition named myPartition. 

ant -f ant-sca-mgmt.xml listCompositesInPartition -Dhost=myhost10 -Dport=8001 -Dpartition=myPartition

47.9.19 How to Use ant to Create a Partition in the SOA Infrastructure

The following provides the syntax for creating a partition in the SOA Infrastructure.

ant -f ant-sca-mgmt.xml createPartition -Dhost=host -Dport=port -Duser=user
-Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-29 describes the syntax.

Table 47-29 ant Partition Creation Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition to create.

The following provides an example of creating a partition in the SOA Infrastructure named myPartition: 

ant -f ant-sca-mgmt.xml createPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.20 How to Use ant to Delete a Partition in the SOA Infrastructure

The following provides the syntax for deleting a partition in the SOA Infrastructure. This command undeploys all composites in the partition before deleting the partition.

ant -f ant-sca-mgmt.xml deletePartition -Dhost=host -Dport=port -Duser=user
-Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-30 describes the syntax.

Table 47-30 ant Partition Deletion Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition to delete.

The following provides an example of deleting a partition in the SOA Infrastructure named myPartition: 

ant -f ant-sca-mgmt.xml deletePartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.21 How to Use ant to Start All Composites in the Partition

The following provides the syntax for starting all composites in the partition:

ant -f ant-sca-mgmt.xml startCompositesInPartition -Dhost=host -Dport=port
-Duser=user -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-31 describes the syntax.

Table 47-31 ant Partition Startup Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition.

The following provides an example of starting all composites in the partition named myPartition: 

ant -f ant-sca-mgmt.xml startCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.22 How to Use ant to Stop All Composites in the Partition

The following provides the syntax for stopping all composites in the partition:

ant -f ant-sca-mgmt.xml stopCompositesInPartition -Dhost=host -Dport=port
-Duser=user -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-32 describes the syntax.

Table 47-32 ant Partition Composite Stop Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition.

The following provides an example of stopping all composites in the partition named myPartition: 

ant -f ant-sca-mgmt.xml stopCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.23 How to Use ant to Activate All Composites in the Partition

The following provides the syntax for activating all composites in the partition.

ant -f ant-sca-mgmt.xml activateCompositesInPartition -Dhost=host -Dport=port
-Duser=user -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-33 describes the syntax.

Table 47-33 ant Partition Composite Activation Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition.

The following provides an example of activating all composites in the partition named myPartition: 

ant -f ant-sca-mgmt.xml activateCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.24 How to Use ant to Retire All Composites in the Partition

The following provides the syntax for retiring all composites in the partition:

ant -f ant-sca-mgmt.xml retireCompositesInPartition -Dhost=host -Dport=port
 -Duser=user -Dpartition=partition.name

Note:

After specifying the user name, enter the password when prompted.

Table 47-34 describes the syntax.

Table 47-34 ant Partition Composite Retirement Commands

Argument Definition

host

Hostname of the Oracle WebLogic Server (for example, myhost).

port

Port of the Oracle WebLogic Server (for example, 7001).

user

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

password

Password for the user name.

partition

The name of the partition.

The following provides an example of retiring all composites in the partition named myPartition: 

ant -f ant-sca-mgmt.xml retireCompositesInPartition -Dhost=myhost10 -Dport=8001
-Dpartition=myPartition

47.9.25 How to Use ant to Manage SOA Composite Applications

You can use ant scripts to compile, package, and deploy the application. You can create the initial ant build files by selecting New > Application > Ant > Buildfile from Project from the File main menu.

Figure 47-29 shows the build.properties and build.xml files that display in the Applications window after creation.

Figure 47-29 ant Build Files

Description of Figure 47-29 follows
Description of "Figure 47-29 ant Build Files"

  • build.properties

    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.

  1. Modify the build.properties file to reflect your environment.
  2. From the Build menu, select Run Ant on project_name.

    This builds targets defined in the current project's build file.

47.10 Deploying SOA Composite Applications from Oracle Enterprise Manager Fusion Middleware Control

You can deploy SOA composite applications from Oracle Enterprise Manager Fusion Middleware Control. You must first create a deployable archive in Oracle JDeveloper or through the ant or WLST command line tools. The archive can consist of a single SOA composite application revision in a JAR file or multiple composite application revisions (known as a SOA bundle) in a ZIP file. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.11 Deploying SOA Composite Applications with No Servers Running

You can deploy SOA composite applications and shared data (for example, WSDL and XSD files) with no managed SOA servers or administration servers running (known as offline deployment mode). When the servers are restarted, the SOA composite applications and shared data are deployed.

Offline deployment is beneficial for the following use cases:

  • Shared data and new SOA composite applications (for example, the system is new and does not have any deployed composites).

  • One-off patches that may contain a single SOA composite application (new or patched) or a resource bundle of shared data.

Note the following guidelines when using offline deployment:

  • The SOA composite applications and shared data are available in read-only format in the Oracle home directory. You cannot delete or update the composites.

  • The same SOA composite application or shared data file can be included in one or all of the supported use cases when offline deployment occurs. However, for a particular SOA composite application, only one composite SAR or shared data file is in the data location relative to the product data root directory. All cases must point to the same root product data directory. The same composite data is overwritten by the order of applied use cases.

  • You cannot redeploy or undeploy the SOA composite application through offline deployment.

  • Shared data (resource bundle) redeployment is supported since there is no revision concept with shared data.

  • WLST commands are provided for adding and removing individual SOA composite applications and shared data to and from offline deployments. For information, see SOA Composite Application Offline Management Deployment in WLST Command Reference for SOA Suite.

  • Configuration plans are not supported with offline deployments.

For information about SAR file naming conventions, see Deployed Service Archives.

For information about shared data, see How to Deploy and Use Shared Data Across Multiple SOA Composite Applications in Oracle JDeveloper.

Note:

  • You cannot deploy ZIP files in offline mode. This is because ZIP files contain other archives.

  • You can only deploy a particular composite SAR file into one partition through offline deployment.

47.11.1 Offline Deployment Configuration Files

Two configuration files control offline deployment:

  • soa-configuration.xml (offline deployment configuration list file).

  • composite-offline-deployments-version_number.xml (offline deployment configuration file). The version_number can be any value, but the composite-offline-deployments- part is fixed and required.

47.11.1.1 Offline Deployment Configuration List File

The offline deployment configuration list file identifies the location from which to read the offline deployment configuration files. The file is named soa-configuration.xml and appears in the $DOMAIN/config/fmwconfig directory. The offline deployment process uses this configuration file to generate a consolidated configuration list to use in offline deployment. The following example shows a soa-configuration.xml file in which two directory locations are listed: 

<?xml version="1.0" encoding="UTF-8"?>
<soa-configuration xmlns="http://xmlns.oracle.com/config/soa">
    <soa-directories>
<soa-directory>/scratch/aime/appTop/common/soa-composiste/soa1</soa-directory>
<soa-directory>/scratch/aime/appTop/common/soa-composiste/soa2</soa-directory>
    </soa-directories>
</soa-configuration>
47.11.1.2 Offline Deployment Configuration File

The offline deployment configuration file specifies the following elements for offline deployments.

  • Partitions are created, as necessary, before the SOA composite applications and shared resources are deployed. Note the following order of precedence for partition use:

    • The partition specified in the <partition> element is created.

    • If a partition used in <composite-deployment> is not specified in the <partition> element, it is created implicitly.

    • If the partition attribute is not specified in the <composite-deployment> element, the composite is deployed into the default partition.

  • Shared resources

    Shared resources are deployed before the SOA composite applications.

  • SOA composite applications

    You can list multiple SOA composite applications in the file. However, they are not deployed in the order in which they are listed in the file.

The file naming convention is composite-offline-deployments-version_number.xml, where version_number can be any value, but the composite-offline-deployments- part is fixed and required.

The following example shows the structure of the offline deployment file. The file is divided into the three sections to represent partitions, SOA composite applications, and shared data.

<offline-configuration>
    <partitions>?
        <partition name="partition_name"/>*
    </partitions>
    <composite-deployments>?
        <composite-deployment location="/some/path" partition="partition_name"?>*
    </composite-deployments>
    <shared-resources>?
        <shared-resource location="/some/path"/>*
    </shared-resources>
</offline-configuration>

The following example shows an offline deployment configuration file in which the following is defined:

  • Partition one and two are created.

  • The composite SAR file /some/path/sca_composite1.jar is deployed into partition one.

  • The composite SAR file /another/path/sca_composite2.jar is deployed into partition two.

  • The composite SAR file /yet/another/path/sca_composite3.jar is deployed into the default partition.

  • The shared data JAR files /some/path/shareddata1.jar and /another/path/shareddata2.jar are deployed into the shared data location. 

<offline-configuration>
    <composite-deployments>
        <composite-deployment location="/some/path/sca_composite1.jar"
 partition="one">
        <composite-deployment location="/another/path/sca_composite2.jar"/
 partition="two">
        <composite-deployment location="/yet/another/path/sca_composite3.jar"/>
    </composite-deployments>
    <shared-resources>
        <shared-resource location="/some/path/shareddata1.jar"/>
        <shared-resource location="/another/path/shareddata2.jar"/>
    </shared-resources>
</offline-configuration>

The following example shows an offline configuration deployment file in which the following occurs:

  • The shared data JAR file named shareddata.jar is deployed.

  • The composite SAR file named sca_soaApp1.jar is deployed into the myPartition partition.

  • The composite SAR file named sca_soaApp2.jar is deployed by default into the default partition because no partition is explicitly defined. 

<offline-configuration>
    <composite-deployments> 
        <composite-deployment
            location="/scratch/aime/appTop/soa1/sca_soaApp1.jar“ 
            partition=“myPartition“/>
        <composite-deployment
            location="/scratch/aime/appTop/soa1/sca_soaApp2.jar“/>
           </composite-deployments> 
    <shared-resources> 
        <shared-resource location="/scratch/aime/appTop/soa1/shareddata.jar"/> 
    </shared-resources> 
</offline-configuration>

The following example shows an offline deployment configuration file in which only shared data located in the two defined directories is deployed:

<offline-configuration>
    <shared-resources>
        <shared-resource location="/some/path/shareddata1.jar"/>
        <shared-resource location= "/another/path/shareddata2.jar"/>
    </shared-resources>
</offline-configuration>

The following example shows an offline deployment file in which partition one and two are created. No SOA composite applications or shared data are deployed: 

<offline-configuration>
    <partitions>
        <partition name="one"/>
        <partition name="two"/>
    </partitions>
</offline-configuration>
47.11.1.3 Relative Configuration File Paths

Relative paths are also supported in the offline deployment configuration file. The following example shows the soa-configuration.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<soa-configuration xmlns="http://xmlns.oracle.com/config/soa">
    <soa-directories>
<soa-directory>/scratch/aime/appTop/common/soa-composiste/soa1</soa-directory>
    </soa-directories>
</soa-configuration>

The following example shows the offline deployment composite-offline-deployments-1.0.xml file. The two composite SAR files and one shared data JAR file are all located in the soa1 directory shown in the preceding example. 

<offline-configuration>
    <composite-deployments>
        <composite-deployment location="sca_soaApproval.jar" >
        <composite-deployment location="sca_soaNotification.jar">
    </composite-deployments>
    <shared-resources>
        <shared-resource location="soashareddata.jar"/>
    </shared-resources>
</offline-configuration>
47.11.1.4 Order of Deployment

Offline deployments are processed in the following order:

  • The soa-configuration.xml offline deployment configuration list file is read to identify the location of the offline deployment configuration files (composite-offline-deployments-version.xml).

  • The composite-offline-deployments-version.xml files are read and a consolidated list is created based on the file location. The consolidated list contains the partitions, shared data files, and SOA composite application files.

  • The consolidated list is processed in the following order:

    • Partitions

    • Shared data files

    • SOA composite application files

47.11.2 How to Deploy SOA Composite Applications and Shared Data with No Server Running

This section provides an overview of the procedures for deploying SOA composite applications and shared data with no server running.

To deploy SOA composite applications and shared data with no server running:

  1. Create an offline deployment configuration list file. This file identifies the location from which to read the offline deployment configuration files. For examples of the contents of this file, see Offline Deployment Configuration List File.
  2. Create offline deployment configuration files. This file specifies the elements to include in the offline deployment (partitions, shared data, or SOA composite applications). For examples of the contents of this file, see Offline Deployment Configuration File.
  3. Restart the SOA servers.

    The composites are deployed and displayed in the Deployed Composites tab of the SOA Infrastructure in Oracle Enterprise Manager Fusion Middleware Control. For more information, see "Managing the State of All Applications at the SOA Infrastructure Level" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

    If troubleshooting is required, you can view deployment results in the SOA server diagnostic log file.

47.11.3 What You May Need to Know About Offline Composite Deployment in a Cluster Environment

When the server starts up during offline composite deployment, the SOA composite application is deployed to all nodes in the cluster. The registration files are supported in one physical domain location, rather than synchronizing the files across all physical domain locations in the cluster. If the cluster is configured where the domain location is present on different physical hosts, select the domain directory on one host and use that as the offline registration location.

47.11.4 What You May Need to Know About Deploying SOA Composite Applications that Reference Shared Data That is Not in the MDS Repository

Offline deployment enables a SOA composite application that references shared artifacts in the MDS Repository to be deployed when the shared data is not present in the MDS Repository.

This is the expected behavior. To save time during server startup, offline deployment uses lazy loading by default. With lazy loading, you do not see a deployment error when the composite is deployed during server startup if the composite is referencing nonexistent shared data. However, you do see the failure when you invoke the composite for the first time. The composite fails if it references non-existent, shared data. With lazy loading, the failure point is different; it is not in the deployment, but in the first invocation.

47.12 Importing XSLT Customizations into a Deployed SOA Composite Application

Use WLST commands to update XSLT customizations in an existing SOA composite application.

To import XSLT customizations into an existing SOA composite application:

  1. Start WLST:
    sh FMW_HOME/oracle_common/common/bin/wlst.sh
  2. Use the sca_exportUpdates command to export the customizations to a .jar file.

    For example:

    sca_exportUpdates('http://soa_server_host:soa_server_port', 'all',
'/tmp/test/sca_SupplierMaintenance_updates.jar', 'SupplierMaintenance',
'1.0', user='weblogic', password='weblogic1')

    Note:

    If there are no previous customizations, this command will not create a .jar file. In this case, simply create a dummy .jar file using zip. For example, /tmp/test/sca_SupplierMaintenance_updates.jar.
  3. Connect to the SOA server.
    connect('weblogic','weblogic1','t3://soa_server_host:soa_server_port')
  4. Use the exportMetadata command to export the existing XSLT (.xsl) file.
    exportMetadata(application='soa-infra',server='soa_server1',toLocation='/tmp/test/',docs='/deployed-composites/default/SupplierMaintenance_rev1.0/Transformations/Transformation_InitializeBusinessRule.xsl')
  5. Edit the .xsl with required updates.
  6. Add the updates to the .jar file.

    For example:

    zip -r sca_SupplierMaintenance_updates.jar Transformations/*

    Now the .jar file includes the updated .xsl file under the same directory structure.

  7. Use the sca_importUpdates command to import the update back into the SOA composite application to save the customization.

    For example:

     sca_importUpdates('http://soa_server_host:soa_server_port', '/tmp/test/sca_SupplierMaintenance_updates.jar', 'SupplierMaintenance', '1.0', user='weblogic', password='weblogic1')
  8. Use the sca_exportUpdates command to export the updates again and confirm the changes are in place.

    For example:

     sca_exportUpdates('http://soa_server_host:soa_server_port', 'all', '/tmp/test/sca_SupplierMaintenance_updates.jar', 'SupplierMaintenance', '1.0', user='weblogic', password='weblogic1')

47.13 Postdeployment Configuration

This section describes postdeployment configuration tasks.

47.13.1 Security

For information about securing SOA composite applications, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.13.2 Updating Connections

Ensure that any connections that you created to the application server or MDS Repository are recreated to point to servers applicable to the next target environment. For more information, see Creating an Application Server Connection and Creating a SOA-MDS Connection.

47.13.3 Updating Data Sources and Queues

Ensure that all JDBC data source, queue, and connection factory locations that you previously configured are applicable to the next target environment. For more information, see How to Create Data Sources and Queues and How to Create Connection Factories and Connection Pooling.

47.13.4 Attaching Policies

You can attach policies to a deployed SOA composite application during runtime in Oracle Enterprise Manager Fusion Middleware Control. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.14 Testing and Troubleshooting

This section describes how to test and troubleshoot your SOA composite application.

47.14.1 Verifying Deployment

You can verify that you have successfully deployed your SOA composite application to the SOA Infrastructure. If successful, the deployed composite displays in the Deployed Composites tab of the SOA Infrastructure page of Oracle Enterprise Manager Fusion Middleware Control. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.14.2 Initiating an Instance of a Deployed Composite

You can initiate an instance of a deployed SOA composite application from the Test Web Service page in Oracle Enterprise Manager Fusion Middleware Control. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.14.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 run from either Oracle JDeveloper or Oracle Enterprise Manager Fusion Middleware Control.

For information about creating and running test cases from Oracle JDeveloper, see Automating Testing of SOA Composite Applications.

For information about running test cases from Oracle Enterprise Manager Fusion Middleware Control, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.14.4 Recompiling a Project After Receiving a Deployment Error

If you receive the error shown in the following example 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. 

Error deploying BPEL suitcase.
error while attempting to deploy the BPEL component file
"/scratch/aime1/work/mw9507/user_projects/domains/WLS_SOAWC/deployed-composites
/ManagementChainParticipantRuleComposite_rev1.0/sca_ManagementChainParticipantR
uleComposite_rev1.0/soa_59d10d76-08a5-41f0-ba89-32dcc2250002";
the exception reported is: java.lang.Exception: BPEL 1.1 compilation failed
 
This error contained an exception thrown by the underlying deployment module.
Verify the exception trace in the log (with logging level set to debug mode).
 
at
com.collaxa.cube.engine.deployment.DeploymentManager.deployComponent(Deployment
Manager.java:197)
at
com.collaxa.cube.ejb.impl.CubeServerManagerBean._deployOrLoadComponent(CubeServ
erManagerBean.java:820)
at
com.collaxa.cube.ejb.impl.CubeServerManagerBean.deployComponent(CubeServerManag
erBean.java:119)

47.14.5 Reducing Java Code Size to Resolve Java Compilation Errors

If you receive the Java compilation error shown in the following example in your server log files, you may have too much code in your Java classes. 

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)

To reduce Java code size to resolve Java compilation errors:

  1. Open the $MIDDLEWARE_HOME/user_projects/domains/domain_name/bin/SetDomainEnv.sh file (for Linux) or SetDomainEnv.bat file (for Windows).
  2. 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.
  3. 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: 

    32,16
16,8
8,4
4,2
  4. Save your changes.
  5. Restart the server.
  6. Recompile your SOA composite application.

47.14.6 Troubleshooting Common Deployment Errors

This section describes how to troubleshoot common deployment errors.

For information about general composite application troubleshooting issues, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

47.14.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 Applications window, 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 Applications window, 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.

  • Optionally enter a new revision ID (optional) and select the configuration plan (if any).

  • 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 check box 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 the following example. 

    Compilation of project 'FirstComposite.jpr' finished. Check '/scratch/myhome/
jdevWorkarea/mywork/Application11/FirstComposite/SCA-INF/classes/scac.log' for
details.

  • After compilation is successful, a SAR/SOA bundle archive is built for the composite. For a SAR archive, the message shown in the following example is displayed in the Deployment tab. 

    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 the following example is displayed in the Deployment tab. 

    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 the following example in the Deployment tab. 

    Received HTTP response from the server, response code=200 Successfully deployed
archive soa_bundle_name.zip to soa_server_name

  • If deployment fails, the message shown in the following example is displayed in the Deployment tab with an error message (if any) from the server. 

    Error deploying the archive. Check server log for more details.
Connection refused.
Elapsed time for deployment: 8 seconds

  • 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.

47.14.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. The following example provides details. 

    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.

47.14.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.

You can use WLST to deploy SOA composite applications to a managed Oracle WebLogic Server without starting an Oracle WebLogic Administration Server. See Deploying and Managing SOA Composite Applications with the WLST Utility for details.

47.14.6.4 Deploying to a Two-Way, SSL-Enabled Oracle WebLogic Server

Deployment from Oracle JDeveloper to a two-way, SSL-enabled Oracle WebLogic Server is not supported.

47.14.6.5 Deploying with an Unreachable Proxy Server

You can receive an error similar to that shown in Figure 47-30 during SOA composite application deployment if you have a proxy server set in Oracle JDeveloper that is not reachable from your host.

Figure 47-30 Deployment Error Message

Description of Figure 47-30 follows
Description of "Figure 47-30 Deployment Error Message"

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:

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

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

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

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

47.14.6.6 Releasing Locks to Resolve ADF Task Form EAR File Deployment Errors

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:

  1. Log in to the Oracle WebLogic Server Administration Console.
  2. Below the console banner at the top of the page, click Preferences > User Preferences.
  3. Deselect Automatically Acquire Lock and Activate Changes.
  4. 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).

47.14.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.

  1. Open the ant-sca-compile.xml file in the $ORACLE_HOME/bin directory.
  2. Under the scac element, increase the memory setting. For example:
    <jvmarg value="-Xmx512M"/>
47.14.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.

47.14.6.9 ADF Binding Service Names Must Be Unique Across All Deployed SOA Composite Applications

All ADF bindings must have a unique service name across all deployed SOA composite applications.

For example, assume you perform the following steps:

  1. Build and successfully deploy a SOA composite application that includes multiple composites to the SOA server.
  2. Change one of the composites in the SOA composite application by adding new components and an outbound external reference.
  3. Compile and successfully build the updated SOA composite application as revision 2.0.
  4. Deploy the updated SOA composite application to the same partition or a different partition.

    You can receive the following error: 

    <Oct 7, 2013 11:52:01 AM EDT> <Error> <ServletContext-/soa-infra>
<BEA-000000> <Error during deployment
oracle.fabric.common.FabricException: Deployment Failed: The serviceName
attribute "OrderProcessorService" has already been used.   ServiceName must
be unique among all deployed composites.  The new service will overwrite the
old one.
        at
oracle.integration.platform.blocks.deploy.StandaloneCompositeDeploymentCoordin
atorImpl.coordinateCompositeDeployment(StandaloneCompositeDeploymentCoordinato
rImpl.java:99) 
. . .
. . .

    This error occurred because all ADF bindings must have a unique service name across all deployed SOA composite applications.

  5. As a workaround, you must edit the composite.xml file and assign a different name for the service in the.adf binding.adf section. For example: 
    <binding.adf serviceName="OrderProcessorService_v2" registryName=""/>
    <!-- exposed for using via direct binding api -->

47.15 Patching Running Instances of a SOA Composite

Oracle SOA Suite 12c (12.2.1) supports Composite Instance Patching, which enables you to patch running instances of a composite and recover faulted instances after patching the runtime. You can only include those fixes in the patch that are compatible with Composite Instance Patching. Use the SOA Patch Developer role in Oracle JDeveloper to make the fixes and create the patch.

Composite Instance Patching enables you to deliver urgent composite fixes that can be picked up by long running instances. You can make compatible/allowed changes without aborting in-flight instances. If a patched running instance comes across a business process that has been fixed by the patch, say a BPEL transformation, then it picks up the fixes applied to the business process.

Note:

This SOA Suite feature is part of Oracle Integration Continuous Availability. Please refer to the Oracle Fusion Middleware Licensing Information for more details on Oracle SOA Suite for Middleware Options.

When designing the patch, the SOA Patch Developer mode in JDeveloper automatically disables changes that cannot be made to the patch. Some of the compatible changes that you can make include:

  • Non-schema related XSLT changes, changes to fault policy, sensor data, and analytics data.

  • Compatible BPEL changes such as transformation activity, assign operations, etc.

  • JCA Adapter configuration properties.

You do not specify any composite version during deployment. The composite revision that you create the patch for, in Oracle JDeveloper, is the composite revision to which the patch is deployed.

You can validate the patch before deploying.

Use the following steps to create and deploy the patch to runtime.

  1. Use the SOA Patch Developer role in Oracle JDeveloper to make changes to your composite and create the patch.
  2. Validate and deploy the patch using the WLST command-line utility.
    See Verifying and Deploying the Patch Using WLST for details.

    If the patch contains fixes to your composite, you can recover faulted instances in Enterprise Manager Fusion Middleware Control after deploying the patch.

47.15.1 Using the SOA Patch Developer Mode in JDeveloper

Use the SOA Patch Developer mode in Oracle JDeveloper to create a patch, containing fixes, for your deployed composite. The patch created in this mode can be applied to the currently deployed composite without changing the version number of the deployed composite. You can apply the patch to runtime even if the composite has running instances.

To use the SOA Patch Developer mode in JDeveloper:
  • If you already have your project open in JDeveloper, you need to switch to the SOA Patch Developer mode. Select Tools > Switch Roles > SOA Patch Developer from the Oracle JDeveloper menu bar.
    Tools > Switch Roles > SOA Patch Developer
    The Confirm Restart dialog appears.

    Confirm Restart dialog

    The dialog reminds you of the fact that you can make only limited edits in the SOA Patch Developer mode. Click OK to restart JDeveloper.

  • If you do not have Oracle JDeveloper open, start JDeveloper and select the SOA Patch Developer role in the Select Role dialog.
    Select Role dialog
After JDeveloper starts in the SOA Patch Developer mode, you’d notice that the composite editor has the SOA Patch mode label. This reminds you that you can only make edits that are compatible with the patch mode.

SOA Patch Mode appears on top right

Also, when you are editing a BPEL component, for example, the BPEL editor has the Patch mode label.

Patch Mode label appears on BPEL editor.

Only certain activities in the BPEL process are available for editing, the rest of them appear in gray. Also, notice that the Components window shows only those components that are available for use in the SOA Patch Developer mode. A number of properties appear in read-only mode.

47.15.1.1 Generating the Patch XML File

When you make changes to your composite in the SOA Patch Developer mode of Oracle JDeveloper, and save the changes, a patch.xml file is automatically generated. The patch.xml file indicates the changes that you have made to the composite.

The following steps discuss creating and viewing the patch.xml file in JDeveloper
Make sure that you are in the SOA Patch Developer mode and your SOA composite is open for editing.
  1. Affect the changes, or fixes, required to the composite.
    Only limited changes are allowed in the SOA Patch Developer mode. These are changes that can be deployed to the runtime without affecting running instances.
    For example, you might want to make fixes to an XSLT map associated with a BPEL transformation activity.
  2. Save all your files in JDeveloper.
    You can click on the Save All button in the JDeveloper main toolbar, for example.
    A patch.xml file is automatically created under project_directory/SOA/SCA-INF directory. The patch.xml file gets updated every time you make and save changes to your composite in the SOA Patch Developer mode.
  3. Optionally view the patch.xml file.
    You can select Application > Overview from the main menu bar and select patch.xml under XML Files. Click Edit to open the patch.xml file.
    The following image shows a sample patch.xml file. You can see that an XSL transformation and a BPEL process have been patched.

    sample patch.xml

    Note:

    The patch also includes any sensor information. This ensures that any Design-Time at Runtime (DT@RT) related changes are retained.

47.15.1.2 Creating a Sparse Deployment Profile

After creating a patch in the SOA Patch Developer mode, create a sparse deployment profile for deploying the changes to runtime. This creates a patch jar file in the deploy directory that you can deploy to runtime.

Use the following steps to create a sparse deployment profile using JDeveloper.
  1. Right-click the project name in the Applications window, and select Deploy > Your_Project_Name.
    You can also choose to create a new deployment profile.
    The Deploy Project_Name wizard appears.
  2. Complete the wizard steps, as you would do to deploy a project.
    Notice that the Deploy Configuration screen does not allow you to create a new version, or overwrite an existing version. This is because the patch would be deployed to runtime without creating another version, and without affecting running instances.

    Deploy Configuration screen

    The Summary screen shows you the name and path of the sca_projectname_patch.jar file that is created in the deploy directory.

  3. Click Finish to create the patch jar file.
    The project_name/deploy directory should now contain the patch jar in addition to the original project jar.

    You can open the patch jar to view the components included in it. The patch jar contains only those components that you modified in the SOA Patch Developer mode.

47.15.2 Verifying and Deploying the Patch Using WLST

You can validate and deploy the patch jar file using the WLST command-line tool. Use the sca_validatePatch and sca_patchComposite commands to validate and deploy the path file respectively.

Use the following steps to verify and deploy the packaged jar (composite SAR) to runtime.
  1. Use the sca_validatePatch command to validate your patch jar file.
    You can use help(‘sca_validatePatch’) to get detailed information on the sca_validatePatch command syntax and arguments.
    For example: 
    sca_validatePatch('http://my_soa_server:8001', 'weblogic', 'welcome', '/home/sca_HelloWorld_patch.jar')

    The preceding command validates if the sca_HelloWorld_patch.jar patch file can be successfully deployed to the my_soa_server SOA server runtime.

    The following message indicates that the patch was successfully validated:
    Composite patch has been validated successfully.
  2. Use the sca_patchComposite command to deploy your patch jar file to runtime.
    You can use help(‘sca_patchComposite’) to get detailed information on the sca_patchComposite command syntax and arguments.
    For example: 
    sca_patchComposite('http://my_soa_server:8001', 'weblogic', 'welcome', '/home/sca_HelloWorld_patch.jar')

    The preceding command uses the sca_HelloWorld_patch.jar patch file to patch the HelloWorld composite on the my_soa_server runtime.

    The following message indicates that the patch was successfully applied:
    Composite has been patched successfully.
You have successfully patched the composite on runtime. If you had any previously faulted flow instances in Enterprise Manager Fusion Middleware Control that can be recovered after applying this patch, you may attempt to recover them now.

47.15.3 Deleting the Patch File

If you try to open a SOA project in JDeveloper using a role other than SOA Patch Developer, and if the composite has a previously existing patch file, you get a warning stating that you should delete the patch.xml file before you can edit the project.

If you have already applied the patch, you can safely choose the option to delete the patch.xml file.

Patch File Found dialog

You can now continue to edit the SOA project.