Oracle® Fusion Middleware
Example Promoting from Development to Testing Environment

This topic describes a step-by-step example of promoting configuration from a Development environment to a Testing environment. If further promotions to more upstream environments are required, you can repeat steps 4 and 5 only.

Example Topology

This example assumes the following simple environment topology:

The policy developer in the Development environment uses Policy Studio to create policies, users, certificates, listeners, and so on as required for the business solution they are developing. The policy developer will most likely edit and deploy the configuration to the Dev Payment API Group repeatedly until they are finished with the configuration.

Deploying in Policy Studio

The policy developer deploys the configuration in Policy Studio by clicking the Deploy button in the toolbar when editing the configuration. This displays the following screen:

Select the Group and API Gateway instance(s) to which you wish to deploy, and click Deploy. This uploads the configuration to the Admin Node Manager for the group, and then deploys it to the API Gateway instance(s) on the host(s).

When the policy developer is developing policies in an iterative manner as described in Step 1, they may choose not to consider what settings are environment-specific yet, or they may choose to environmentalize these settings as they go along. Either way, before promotion can occur, all settings that are environment-specific must be environmentalized to prepare the configuration for promotion to upstream environments.

Displaying Environmentalized Configuration

You must first enable the display of configuration settings that are assigned for environmentalization in Policy Studio. Select Window > Preferences > Environmentalization in the main menu, and select Allow environmentalization of fields.

Environmentalizing Configuration Settings

For example, the developer chooses to environmentalize the following settings in the configuration:

The policy developer edits the Database Connection, Connect to URL filter, HTTPS Interface, and LDAP Connection. You can select the Environmentalize button ( globe icon) on the right of the fields shown in the following examples. Alternatively, you can environmentalize a selected field by pressing Ctrl-E.

For example, select External Connections > Database Connections > Default Database Connection > Edit, and click Environmentalize in the appropriate fields:

Select Policies > QuickStart > Virtualized Services > REST > Get Products > Connect to Heroes' REST Service, and click Environmentalize in the URL field:

Select Listeners > API Gateway > OAuth 2.0 Services > Ports > OAuth 2.0 Interface, and click Environmentalize in the X.509 Certificate field:

Select External Connections > LDAP Connections > Sample Active Directory Connection > Edit, and click Environmentalize in the appropriate fields:

When configuration settings have been environmentalized, the corresponding node in the Policy Studio tree is displayed with a globe icon and bold text.

Viewing Environment Settings

After environmentalizing the fields, the following nodes are available under the Environment Settings tree in Policy Studio:

Updating Environment Settings

Assuming the policy developer has already entered values for the fields that they have selected to be environmentalized, these values are automatically specified in the Environment Settings tree. If the developer wishes to update the setting values for the Development environment, they must do so using the Environment Settings tree.

For example, using the example environmentalized settings, the following screen is displayed when you select Environment Settings > External Connections > Database Connections > Default Database Connection:

Deselecting Environment Settings

If the policy developer no longer wants to environmentalize a setting, they can right-click its node in the Environment Settings tree, and select Remove. This also deselects the field in the screen used to edit the configuration setting (for example, Database Connection). The value configured before environmentalization is displayed again.

Alternatively, you can click the Jump to configuration link, and return to the screen used to edit the configuration setting, and deselect the Environmentalize button on this field, or press Ctlr-E. This also removes the field as a setting to be configured under the Environment Settings tree. The value configured before environmentalization is displayed again.

Deploying the Configuration

After all environment-specific fields have been selected, and appropriate values set for the Development environment, the policy developer should deploy and test the updated configuration. For details on deploying to the group, see Step 1. The deployment package (.fed) deployed to the Dev Payment API Group will contain entries in the Environment Settings store, and the associated values suitable for the Development environment.

Environmentalizing Reference Fields

Configuration fields that point to other fields are known as reference fields. For example, in an HTTPS Interface or XML Signature filter, you environmentalize a reference to an X.509 certificate. You can also environmentalize references to complex types such as Authentication Repositories. If a reference to an Authentication Repository is environmentalized, you could set the repository to the Local User Store in the Development environment, and to an LDAP Repository in the Testing environment.

The standard way to environmentalize a certificate at group level is to click Environmentalize on its configuration screen. Environmentalizing a certificate, or any other reference field, is the same as all other fields. For example, when you environmentalize the signing certificate in an XML Signature filter. The Environment Settings tree where you enter environment-specific values displays a node for the XML Signature filter. The screen on the right includes a Signing Key button to display a list of available certificates. You must select one of these certificates in Configuration Studio or Policy Studio. This field will most likely be prepopulated in Policy Studio if you already selected a certificate before clicking Environmentalize.

Alternatively, you can environmentalize a certificate using an alias. For example, in the Development environment, the XML Signature filter could use a certificate named MySigningCert. The policy package (.pol) created from the Development environment must be merged with an environment package (.env) that contains a certificate with the same alias.

The policy developer finishes editing and environmentalizing the configuration that they are running with, and deploys it to the API Gateway. They must then save the policy package in Policy Studio to enable promotion to the Testing environment. To save the policy package, perform the following steps:

A policy package (.pol) file is created on disk. The policy developer must transfer this file to the Testing environment using some external mechanism (for example, FTP or email).

This step depends on whether this is a first cycle promotion or a subsequent cycle promotion.

First Cycle Promotion—Open the Policy Package

If this is a first cycle promotion, the Testing API Gateway administrator uses the Configuration Studio to open the policy package created in the Development environment by the policy developer in Step 3. The administrator does not need to open an environment package for a first cycle promotion. To open the policy package, perform the following steps:

Subsequent Cycle Promotion—Open the Policy and Environment Packages

If this is a subsequent cycle promotion, the Testing API Gateway administrator uses the Configuration Studio to open the policy package created in the Development environment by the policy developer in step 3. You must also open the currently deployed environment package for the Testing environment. If you do not open the currently deployed environment package at this point, you may need to re-enter certificates and settings that you entered for the previous promotion.

Specifying Environment Settings

The administrator must navigate the Environment Settings tree in the Configuration Studio, and enter values that are specific to the Testing environment. Values from the Development environment are not displayed. The Environment Settings tree displays any settings without values with a question mark indicator on the tree node. For a first cycle promotion, initially all environment setting values will be empty. Assuming a first cycle promotion with the sample data from Step 1, the Environment Settings tree is displayed in the Configuration Studio as follows:

For subsequent cycle promotions, settings that are still required by the new policy package from the Development environment, and that existed in previously promoted policy packages, will have values configured. Any certificates, keys, user, and user groups previously created will also be shown. Environment settings that existed in previously promoted configuration but are no longer required will be removed. New settings in the new policy package are listed with no value.

For example, assuming a first cycle promotion using the example environmentalized settings, the following screen is displayed when you select Environment Settings > External Connections > LDAP Connections > Sample Active Directory Connection:

Updating Certificates and Users

The administrator can add, edit, or remove new certificates, keys, users, and user groups in Configuration Studio in the same way as in Policy Studio. For more details, see the following topics:

Updating Package Properties

At any time, the API Gateway administrator can edit the environment package properties by selecting the Package Properties > Environment tree node in Configuration Studio. For example:

If the API Gateway administrator selects the Package Properties > Policy tree node, this displays a read-only view of the policy package properties on a similar screen. For example:

Saving the Environment Package

When you have entered all the environment-specific settings for the Testing environment, select File > Save > Environment Package in the Configuration Studio. An environment package (.env) file is saved to disk.

The Testing API Gateway administrator takes the policy package unchanged from the Development environment created in Step 3, and the environment package created using Configuration Studio for the Testing environment created in Step 4, and deploys them to the Testing Payment API Group using API Gateway Manager or scripts.

For example, to deploy using API Gateway Manager, perform the following steps:

This section describes how to update environment-specific settings using the Configuration Studio, and if necessary, using Policy Studio.

Updating Environment Settings Using Configuration Studio

If further updates are required to the environment-specific settings in the Testing environment, the Testing API Gateway administrator can open the policy package and environment package files in Configuration Studio at any time, and update the contents for the environment package file. The administrator can then deploy the policy package and updated environment package files to the Testing Payment API Group using API Gateway Manager or scripts.

Updating Environment Settings Using Policy Studio

Normally the policy package will be promoted through to upstream environments without any updates. However, in some cases, a single policy package for all environments will not be possible. For example, you may wish to use different Authorization filters in Development and Testing environments. But the policy developer may not have sufficient knowledge to create the necessary configuration for all upstream environments in the policy package. In this case, the API Gateway administrator in the upstream environment must use Policy Studio to make the required changes.

The administrator will open a policy package from the Development environment and the current Testing environment package (if one exists) in Policy Studio, before making the Testing environment-specific updates to the configuration. The administrator can save a policy package (.pol) and an environment package (.env) from Policy Studio. They can deploy them as usual to the Testing Payment API Group using API Gateway Manager or scripts. Alternatively, they can save a single deployment package (.fed), and deploy this package.