Importing deployment environment definitions based on design documents using the administrative console

You can import an existing deployment environment definition based on a design document from another deployment manager to use as a base for configuring a new deployment environment.

Before you begin

On the administrative console of the deployment manager navigate to Servers > Deployment Environments.
You must have a copy of an exported deployment environment design document from another deployment manager.
You must be able to access the deployment environment design document (an XML file) from the deployment manager into which you are importing the deployment environment design.
The deployment manager that imports the deployment environment definition must support at least all of the functions that are defined in the deployment environment design document. For example, you can import a deployment environment design that was created on a WebSphere® Enterprise Service Bus deployment manager into an IBM® Business Process Manager deployment manager but not vice versa.

Required security role for this task: When security and role-based authorization are enabled, you must log in to the administrative console as an administrator or configurator to perform this task.

Important: You cannot import multiple deployment environment design documents from a compressed file at the same time. You must extract the design documents from the compressed file and then import the XML files one at a time.

About this task

Importing an existing deployment environment design to create a new one can minimize the amount of time you spend configuring a deployment environment. If an existing environment is similar to the one you want to create, export it and then import it into the deployment manager you are configuring.

Procedure

Click Import in the Deployment Environments page to launch the Deployment Environment Configuration wizard.
The wizard starts with Create a deployment environment based on an imported design selected.
Click Browse to select the deployment environment design document (XML file) to import or type the full path to it.
Click Next to load the configuration and launch the Import deployment environment wizard.
The wizard displays the Select Nodes page.
Optional: From the list of possible nodes on the Select Nodes page, select the nodes to include in the deployment environment and click Next.
To include a node, select the check box next to the node name. Use Node Mapping to map the selected node to another node name.

Important: If you specified an initial port when creating the deployment environment, that same initial port will be used for creating the clusters on the new node. If a node already exists on that physical system, port conflicts could result. These port conflicts must be resolved manually by changing the port values.

Note: Next is not available if the nodes selected do not meet the constraints imposed by the imported deployment environment design. For example, if there is a requirement for the deployment environment to contain a node named "Mandatory_Node" and 3 other nodes with any name, you will be unable to continue until you select "Mandatory_Node" and 3 other nodes.
Optional: On the Clusters page, assign the required number of cluster members and the initial port to use on each node for each cluster type (Application Deployment Target, Messaging Infrastructure and Supporting Infrastructure) of the deployment environment.
By default one cluster member is assigned on each node for each function. You change the number by replacing the number in each column. If you are unfamiliar with the different cluster roles and functions provided by each type of cluster, see "Topology types and deployment environment patterns."

A 0 (zero) value for a node means that the node does not contribute to the selected function, based on features that you have selected.

After assigning cluster members, you can click Next to display the Cluster naming pages for each cluster type of the deployment environment. The Cluster naming sub-steps that display will vary depending on the deployment environment pattern selected.

You can specify the initial port using the Specify the port number for the first cluster group (Optional): text box. Port numbers are reserved and assigned to each node for the cluster members using the port number that is specified. If you specify an initial port when you create the deployment environment, that same initial port specified would be assigned to the first cluster member and subsequent cluster groups would be assigned ports after increasing the port value by 20. For example, if the port number for the first cluster group is 2000, the port numbers of the cluster members would be 2000, 2001, 2002, and so on. The port number of the second cluster group would be 2020 and the port numbers for the members of the second cluster group would be 2020, 2021, 2022, and so on. The port number of the third cluster group would be 2040.
Note: If there is already a node on that physical system then there may be port conflicts and these would need to be resolved manually by changing the port values.

The system generates default values for cluster names and cluster member names. The system also generates default values for the cluster short name and cluster member short name.

If you do not want to customize cluster names or cluster member names, you can use the wizard navigation pane to go directly to the REST Services page in a following step.

Each substep page is structured in the same fashion, and is described in Customize the cluster names and cluster member names.
1. Optional: Customize the cluster names and cluster member names.
  Use the Cluster Naming page to customize cluster names or cluster member names for the cluster type. You can also modify cluster short names and cluster member short names. There is one substep page for each cluster type in the pattern that you have selected. For example, if you selected a Remote messaging and remote support pattern, there are 3 sub-steps, one for each type of cluster (Application Deployment Target, Messaging Infrastructure and Supporting Infrastructure) in that pattern.
  
  The information on each substep page is as follows:
  Cluster
  A read-only field specifying the functional role of the cluster.
  The value varies depending on the cluster type, as follows:
  Application Deployment Target
  
  Messaging Infrastructure
  
  Supporting Infrastructure
  
  Web Application Infrastructure
  
  For information on the functional role provided by each cluster type, see Topology types and deployment environment patterns
  Cluster Name
  Contains the system-generated default value for the cluster name.
  The default values are based on a naming convention of <Deployment Environment Name>.<Cluster type name>, wherecluster type name is one of the following values:
  AppTarget
  For clusters performing the role of application deployment target
  
  Messaging
  For clusters performing the role of messaging infrastructure
  
  Support
  For clusters performing the role of supporting infrastructure
  
  Web
  For clusters performing the role of supporting web applications.
  Note: This cluster type name applies for BPM configurations in which WebSphere Business Monitor is the primary feature / product.
  Cluster Short Name
  You can leave this field blank or enter a short name of your choosing.
  Cluster short names cannot exceed 8 characters in length, and must be unique so as to avoid naming collisions. At creation time, the system checks against the following rules to ensure the validity of the cluster short name:
  Must be one to eight characters in length
  
  Must contain only alphanumeric or national language characters
  
  Cannot start with a number
  
  Must be unique in the cell
  
  Cannot be the same as the value specified on the ClusterTransitionName custom property of any non-clustered server
  Cluster Member Name
  
  Accept the system-generated default value or specify a name of your choosing.
  The default value for the cluster member name is based on the following naming convention: <cluster name>.<node name>.<node number sequence>.
  
  The number of cluster member names that display in the table match the number of cluster members that you entered for the cluster type column and node row on the Clusters page. See the preceding step for the Clusters page.
  
  Cluster Member Short Name
  Accept the system-generated default value or specify name of your choosing.
  The system-generated value for cluster member short name is based on a naming convention of <deployment environment name>[0:5]<cluster type name>.
  
  The cluster member short name is limited to 7 characters and MUST BE UNIQUE.
  
  If the cluster member short name is not unique, the system appends a unique number to it.
  
  As an example, for a deployment environment named DEPENV, the system-generated short name for the application target cluster member is DEPENVAT.
  
  The option for cluster member short name displays when the following configuration conditions exist:
  If any one known node in the cell is on a z/OS® platform, then the cluster member short name displays. The node metadata should support the platform on which the node resides.
  
  If the Deployment Manager resides on a z/OS platform.
On the REST Services page, configure service endpoints for Representational State Transfer (REST) application programming interfaces (APIs).
If you want widgets to be available in Business Space, you must configure the REST service endpoints for those widgets.
1. Configure a full URL path for all REST services by selecting either https:// or http:// from the Protocol list.
2. Enter a name in the Host Name or Virtual Host in a Load-Balanced Environment field.
3. In the Port field, enter the port that a client needs to communicate with the server or cluster.
4. In the table of REST services, if you want to modify the description of the REST service endpoint, overtype the entry in the Description field. The other fields are read-only.
5. Click Next to go to the Import the database configuration page.
On the Import the database configuration page, click Browse to go the database design document, or enter the path to the database design document. Then click Next to go to the Data sources page.
Note:
- For DB2® for z/OS databases, you must import a database design document. For other database types, this step is optional.
- The database design document that you import must be available on the local file system from which the administrative console is being accessed. If you ran the database design tool from your IBM Business Process Manager for z/OS installation in order to create the database design document, you must use FTP to transfer the file from the UNIX System Services environment to the local file system, and then import the file.
The design document can be based on a database design that you created using the database design tool, or it can be the supplied design document based on the pattern and feature that you have selected.

The design document can be based on a database design that you created using the database design tool.

Note: The database design document that you import for the deployment environment does not change the commonDB created at Profile Creation time.
Required: On the Database page, configure the database parameters for data sources of the deployment environment, then click Next to go to the Security page.
Note: The database specified in this panel must already exist. Deployment environment configuration never creates a new database.

For DB2 and SQL Server databases, IBM Process Server and IBM Performance Data Warehouse should not use the same database as the rest of the components. However, if you are using an Oracle database, IBM Process Server and IBM Performance Data Warehouse can use the same database instance, but should use different users.

On this page, define the database information for the components that are included in this deployment environment. Where possible, the wizard supplies default information for the parameters, but change those values to match the values that you defined when you planned the environment.

Note: If you imported a database design document, the information on the Database page reflects the data source configuration as it exists in the database design document that you imported.

Whether or not this step displays for a fast path deployment environment configuration is conditional. This step displays for a fast path deployment environment configuration if more than one database has been defined.

This step always displays if you are using DB2 for z/OS or an Oracle database provider.

Note: The default schema names that are displayed on this page might conflict with your site naming convention or might conflict with existing schemas. As such, it is likely that you will need to change the schema name. Pay close attention to the values specified to avoid potential naming conflicts.
Oracle database considerations:
- Make sure that the username and schema name are exactly the same. The user specified should exist in the database before generating the environment.
SQL Server considerations:
- Make sure that the username and schema exist before the configuration is done. The schema value should be the default schema for the user chosen.
- To indicate that users will connect to the databases using Windows credentials, select the individual data source, click Edit, and select Apply Windows authentication.
For a production environment, you should set the same values for User name and Schema name and clear Create tables. For a production environment, create the required schemas manually and use the SQL files generated to create the tables.

Note: You cannot select Create tables for Business Space (the option is unavailable for selection). The SQL files for Business Space need to be run manually. For information on running the SQL manually for Business Space, see Configuring Business Space database tables: .

Note: The Deployment Environment Configuration wizard does not generate the scripts for the SIBus messaging engines. You must either set the create tables flag on the messaging store or generate the DDLs for the SIBus messaging engines using the sibDdlGenerator command. Refer to The sibDDLGenerator command (WebSphere Application Server) in the WebSphere Application Server product information.

You can edit all key parameters, such as the database name, whether or not to create tables, the data source runtime user name, and the password for the deployment environment.

You can select which database to use for the given component.

DB2 for z/OS: The Create tables option cannot be used if you are using a DB2 for z/OS database provider.

Steps that cannot be completed through the Deployment Environment Configuration wizard, and which need to be completed manually, are listed on the Deferred Configuration page.
On the Security page, configure the authentication aliases WebSphere uses when accessing secure components.
You can change the authentication alias user name and password on this page. These aliases are used to access secure components but do not provide access to data sources.
On the Business Process Choreographer page, set parameters for the Business Process Choreographer configuration and then click Next to display the Web application context roots page. On this page you specify the values for:
- Security roles
- Authentication aliases
Optional: On the Web application context roots page, set the context root for component-based web applications in your deployment environment or accept the system-provided default values for the context roots. Then click Next to display the Summary page.
The Web application context roots page displays for deployment environments using the Remote Messaging, Remote Support, and Web Applications pattern.
The table contains the following control information.
Web Application
The name of the web application.
Some of the components that are part of the deployment environment you are creating contain web applications. The Web Application column can include the following components:
Business Space

Business Process Choreographer Explorer

Business Process Rules Manager
Context Root

The current value of the context root for the component.
By default, the default context root for the web application applies. You can change the context roots by typing over the value in the Context Root field.

Note: The Business Space context root is read only and cannot be edited.

Description

The description of the web application context root.
Verify that the information on the Summary page is correct and perform the following substeps:
1. Optional: If you do not want to save the deployment environment configuration, you can click Cancel.
2. Optional: If you want to exit without generating the configuration, click Finish.
  To get back to the panel (if you exited without completing), perform the following from the administrative console: Deployment Environments > name of deployment environment > Generate Environment.
3. To save the deployment environment configuration, click Finish and from within the Messages window, click Save.
  Clicking Save saves the deployment environment to the master configuration. If an error occurs during deployment environment generation, the configuration settings are saved to the master configuration.
4. Check for deferred configuration steps.
  Select Deployment Environments > name of deployment environment > Deferred Configuration.
  
  You need to address any existing deferred configuration steps before starting the Deployment Environment.
5. If you are satisfied with the deployment environment configuration and you have addressed any of the deferred configuration steps, click Finish and Generate Environment to save and complete the configuration of the deployment environment.

Results

When the configuration completes, you can examine the configuration files to view the changes.

What to do next

Either save the changes to the master configuration or discard them.

Tip: After you have configured a network deployment environment, if you test the data store connection (for example, in the administrative console, on the page Resources > JDBC > Data sources), you get a message saying that the test connection operation failed with the exception com.ibm.wsspi.runtime.variable.UndefinedVariableException: Undefined Variable WAS_INSTALL_ROOT. This does not necessarily indicate that there will be a problem accessing the data source at run time. Ensure that the location of your JDBC driver files is accessible to every client that must use the data source, and configure the variable with the full path of that location. Disregard the test connection error unless you are also experiencing trouble connecting to the data store at run time. For additional information, see the WebSphere Application Server documentation about the test connection service.

Important: If you use additional servers with unique ports, WebSphere Application Server does not automatically configure the virtual host for the server. Specifically, WebSphere Application Server does not automatically add the host alias ports to a virtual host. However, you can use the administrative console to add a new host alias for each of the ports that are used by the new server. For more information, see the WebSphere Application Server documentation about configuring virtual hosts.