I am often asked how to automate the creation of an Oracle Integration instance. There are a variety of different ways to create an instance. In this blog, we discuss the pros and cons of each method.

Overview of Options

There are basically four different ways to create an Oracle Integration instance. These are introduced in the table, which gives a high level view of the complexity of the method and the pros and cons of the method.

Method Complexity Benefits Challenges
User interface Low Simple to use. Provides a web form-driven approach. Doesn’t lend itself to automation. Certain scenarios cannot be implemented using this method.
Command Line Medium Can be scripted using any shell that has the OCI command line configured. Supports all use cases. Requires looking up OCIDs of various parameters such as compartment ID and potentially the identity domain. Expects the OCI environment to be configured.
Terraform Medium Can be easily integrated with creation of other resources such as compartments. Supports all use cases. Requires retrieving OCIDs either through variables from other terraform actions or as directly-injected values. Expects the OCI environment to be configured.
API High Supports all use cases. Can be used with a variety of programming languages. Requires getting OCIDs. Expects the OCI environment to be configured.

Note that the first three methods are just wrappers for the API. All lifecycle operations are performed using the API.

Let’s look at each option in more detail.

Control Plane User Interface

After logging into an OCI tenancy, it is possible to create an Oracle Integration instance by selecting the Developer Services > Integration menu item and clicking Create Instance.

OCI Console Integration Menu Item

 

 

 

 

 

 

 

 

 

 

This invokes the Create instance page, where we can name our instance and select the correct edition, shape, license type, and other options. Note that your screen may differ slightly from the one shown. For example, you may have a SaaS subscription. In which case, your consumption model is Subscription rather than Metered. Not all regions have the development shape; therefore, this option may not show.

The benefit of using the user interface in the control plane is that the options are displayed for you as selection panels or drop-down searches. There is no need to look up OCIDs or remember defined values for parameters. This makes the user interface the easiest way to create an Oracle Integration instance. However, note that certain capabilities are not available, such as support for cross-tenancy resources including identity domains that can be accessed through the other instance creation methods.

Mandatory Fields

Lets quickly review the mandatory fields in this form. These fields also exist in all the other creation mechanisms, so we will cover them here. However, they apply to all methods for creating an instance.

Create Instance Oracle Integration basic options

Name

This is how you refer to your instance in the user interface. The name is used as the basis of the endpoint URL for your instance and also as the basis of the instance identifier that is passed to the design time. The more unique your name, the more of it that appears in the endpoint URL.

Edition

This allows you to choose the edition of Oracle Integration that you want to provision. Different editions have different capabilities and different costs. See Oracle Integration Editions in the documentation for more details.

Shape

The shape determines when an Oracle Integration instance is updated to the next release. Development shapes are updated at least two weeks prior to production shapes. Note that not all regions have development shapes or support all features of Oracle Integration. To see which features are available in which regions, see Availability in the documentation.

License Type

This option is mandatory for the universal credit consumption model and is normally the Subscribe to a new Oracle Integration license option. If you have unused WebLogic Suite, SOA Suite, and enterprise edition BPM Suite licenses, then you can apply them to your Oracle Integration instance. The specific details and conversion ratio are summarized below, but the definitive description is in Oracle PaaS and IaaS Universal Credits Service Descriptions. Search for BYOL Required Licenses. BYOL stands for Bring Your Own License.

Edition BYOL License Requirements Conversion Factor
Standard Oracle SOA Suite for Oracle Middleware AND Oracle WebLogic Suite AND applicable application adapter(s) (if being used) 1 Processor license is 2 OCPU, which equates to 40,000 messages per hour
25 Named User Plus licenses is 1 OCPU, which equates to 20,000 messages per hour
Enterprise Oracle SOA Suite for Oracle Middleware AND Oracle WebLogic Suite AND Oracle Unified BPM Suite AND applicable application adapter(s) (if being used) 1 Processor license is 2 OCPU, which equates to 40,000 messages per hour
25 Named User Plus licenses is 1 OCPU, which equates to 20,000 messages per hour
Healthcare No BYOL option No BYOL option

Message packs

This scales your Oracle Integration instance appropriately. Note that in addition to determining the expected number of messages to be processed, it also determines your concurrency. See Message Pack Usage and Synchronous Requests in the documentation for more details. Note that asynchronous concurrency is half the synchronous concurrency.

Compartment

Note that there is no way to select the compartment on the Create Instance page. The compartment is determined by the compartment selected on the Integration Instances page.

Oracle Integration instances screen

Optional Fields

The Show advanced options section allows you to configure additional settings for your instance, such as choosing a specific identity domain or enabling disaster recovery.

Screen to select advanced options for Oracle Integration instance creation

Identity domain

This allows you to select the identity domain associated with your new Oracle Integration instance. Only users, groups, and applications in this identity domain can be granted access to the instance. The identity domain cannot be changed once the instance has been created. Note that only identity domains in the tenancy can be selected.

Network access

You can use the network access tab to restrict access to your new instance based on an access control list (ACL). The ACL can restrict access based on either source IP or source virtual cloud network. Note that unlike the identity domain selection, you can enter a virtual cloud network OCID that allows for cross-tenancy access. If using cross-tenancy access, make sure you have the correct cross-tenancy policies in place.

Disaster recovery

This option automatically creates a second disaster recovery instance in a separate region. Disaster recovery is not available in all regions and the specific paired region is fixed. For details on supported regions and their paired region, see Availability in the documentation.

Tags

The creation process automatically creates two tags in the Oracle-Tags tag namespace – CreatedBy and CreatedOn. You can use this option to add additional tags for tracking purposes.

Command Line

After the user interface, the command line is probably the easiest way to create an Oracle Integration instance. To use the command line, it is required that you configure the OCI Command Line Interface (CLI) as explained in the documentation. If you don’t want to go through all that effort, then you can use the OCI Cloud Shell, which is available from the OCI Console and is already configured with the OCI CLI.

CLI Command

The following CLI command is used to create an Oracle Integration instance. Details are in the CLI Oracle Integration create documentation.

oci integration integration-instance create -c <compartment_ocid> --display-name "Test Instance" --is-byol false --message-packs 1 --domain-id <domain_ocid>

Required Parameters

The following are listed as required parameters in the documentation and correspond to the same options as in the user interface.

  • Compartment (-c or –compartment-id)
  • Name (–display-name)
  • License Type (–is-byol)
  • Message Packs (–message-packs)
  • Edition (–type)
    • Allowed values are Standardx, Enterprisex, and Healthcare. Other values were used in Oracle Integration Generation 2.
  • Identity domain (–domain-id)
    • Not listed as required in the documentation, but is needed.

Note that you cannot provide the OCID of an identity domain outside your tenancy.

The shape is not a required parameter; it defaults to Production, but I highly recommend specifying it.

Optional Parameters

The following are optional parameters.

  • Consumption model (–consumption-model)
    • Normally not required, but if you have both Subscription and UCM entitlements, then you need to specify this.
    • Allowed values are OIC4SAAS and UCM. The GOV option should not be used anymore.
  • Namespace Tags (–defined-tags)
    • Sample parameter value 
      {"Enterprise-OIC":{"Environment":"Non-Production"}}

  • Freeform Tags (–freeform-tags)

    • Sample parameter value

      {"SampleTag":"TagValue", "SampleTag2":"TagValue2"}

  • Disaster recovery (–is-disaster-recovery-enabled)

  • Network access (–network-endpoint-details

    • Sample parameter value

      {
  "networkEndpointType":"PUBLIC",
  "allowlistedHttpIps":["129.1.2.0/24","1.2.3.0/24"],
  "allowlistedHttpVcns":["<vcn_ocid1>", "<vcn_ocid2>"],
  "isIntegrationVcnAllowlisted":true
}

  • Shape (–shape)

    • Valid values are PRODUCTION or DEVELOPMENT.

Obsolete Parameters

The following parameters were supported in Oracle Integration Generation 2, but are not currently supported in Oracle Integration 3. In Oracle Integration 3, you need to perform update operations to enable some of these features.

  • Alternate Custom Endpoints (–alternate-custom-endpoints)
    • Not supported currently in Oracle Integration 3, supported in Visual Builder.
  • Custom Endpoint (–custom-endpoint)
  • IDCS Authentication Token (–idcs-at)
  • File Server (–is-file-server-enabled)
    • Configure through the update command.
  • Visual Builder (–is-visual-builder-enabled)
    • Configure through the update command.

Terraform

Terraform allows you to define a necessary state and the tool issues appropriate commands to transform the current state to the necessary state. This allows you to keep your configuration as code. When it is modified, you let terraform decide how to reconcile the differences between the necessary and the actual state. Details on Create an Oracle Integration Instance Using a Terraform Script are in the documentation. For more information about terraform, see the Getting Started section in the documentation.

Details on the oci_integration_integration_instance terraform resource can be found in the Terraform Registry.

Note that the Oracle Integration default terraform provider requires some work on your part to support all the features. This is because only the parameters listed in the CLI are available on creation. The provider is not smart enough to create with only those parameters and then make subsequent changes. In a later blog post, I will focus on how to configure these additional capabilities in terraform by using multiple linked resources.

Here is a sample Oracle Integration terraform script. Items prefixed with var are variables that are defined either from other resources such as a compartment terraform resource, or from explicit values such as the number of message packs. Comments are used to indicate the option/parameter/field names as used in the earlier sections.


resource "oci_integration_integration_instance" "test_integration_instance" {
    # Required
    compartment_id = var.integration_inst_compartment.id # Compartment
    display_name = var.integration_inst_name # Name
    integration_instance_type = var.integration_inst_type # Edition
    is_byol = var.integration_inst_is_byol # License Type
    message_packs = var.integration_inst_message_packs # Message packs
    domain_id = var.domain_ocid # Identity domain

    # Optional
    consumption_model = var.integration_inst_consumption_model # Consumption model
    defined_tags = {"namespace.tag"= "value"} # Namespace Tags
    freeform_tags = {"tag"= "value"} # Freeform Tags
    is_disaster_recovery_enabled = var.integration_inst_is_disaster_recovery_enabled # Disaster recovery
    shape = var.integration_inst_shape # Shape

    network_endpoint_details { # Network access
        network_endpoint_type = "Public"
        allowlisted_http_ips = var.integration_inst_net_endpt_details_allowlisted_http_ips
        allowlisted_http_vcns {
            # Required
            # id = var.integration_inst_net_endt_details_allowlisted_http_vcns_id

            # Optional
            # allowlisted_ips = var.integration_inst_net_endpt_details_allowlisted_http_vcns_allowlisted_ips
        }
        is_integration_vcn_allowlisted = var.integration_inst_net_endpt_details_is_integration_vcn_allowlisted
    }
}

 

API

Oracle Integration lifecycle operations, including instance creation, are part of the OCI APIs. In particular, the CreateIntegrationInstance API supports creation of new Oracle Integration instances. In addition to supporting a REST API, there are also multiple language bindings.

Supported Languages

The following languages are supported :

  • REST
    • The foundation for everything in this article. Everything else mentioned here uses the REST API under the covers.
    • Can be used with Postman or Oracle Integration, for example.
  • Java
  • Python
  • Go
  • TypeScript
  • .NET
  • Ruby

The Software Development Kits and Command Line Interface in the documentation explains how to install and use the various language bindings for the OCI API, including the Oracle Integration APIs.

Calling CreateIntegrationInstance from an Oracle Integration Flow

The CreateIntegrationInstance API can be called using the REST Adapter from within an Oracle Integration flow. This section explains the steps required to call the API from an invoke action.

Set Up REST Connection

In order to invoke the CreateIntegrationInstance API, we need to have a connection to the OCI API. We can create a REST Adapter connection to connect to the API and use the OCI ServiceInvocation security policy, which means that access is allowed based on OCI policies. This requires that the Oracle Integration instance be a member of a dynamic group. See RPST and OCI Service Invocation Security Policy Use in the documentation for details about what is required.

OCI API Connection

Invoke CreateIntegrationInstance

You can invoke CreateIntegrationInstance as a POST operation as shown below.

Invoke dialog in an Oracle Integration flow

When invoking CreateIntegrationInstance use the following sample payload:

{
  "compartmentId": "string",
  "consumptionModel": "UCM|GOV|OIC4SAAS",
  "definedTags": {
    "tagNamespace1": {
      "tagKey1": "tagValue1",
      "tagKey2": "tagValue2"
    },
    "tagNamespace2": {
      "tagKey1": "tagValue1",
      "tagKey2": "tagValue2"
    }
  },
  "displayName": "string",
  "domainId": "string",
  "freeformTags": {
    "tagKey1": "tagValue1",
    "tagKey2": "tagValue2"
  },
  "isByol": true,
  "isDisasterRecoveryEnabled": true,
  "messagePacks": 1,
  "networkEndpointDetails": {
    "allowlistedHttpIps": [
      "string",
      "string"
    ],
    "allowlistedHttpVcns": [
      {
        "allowlistedIps": [
          "string",
          "string"
        ],
        "id": "string"
      },
      {
        "allowlistedIps": [
          "string",
          "string"
        ],
        "id": "string"
      }
    ],
    "isIntegrationVcnAllowlisted": true,
    "networkEndpointType": "PUBLIC"
  },
  "shape": "DEVELOPMENT|PRODUCTION",
  "integrationInstanceType": "STANDARDX|ENTERPRISEX|HEALTHCARE"
}

Note that the edition or type parameter is the integrationInstanceType attribute. Other attributes map onto previously discussed items with equivalent names.

You can generate a sample JSON load for any OCI command by using the –generate-full-command-json-input option on the CLI command.

Summary

We have discussed the different ways to create an Oracle Integration instance. The technique to use depends on what meets your needs.

  • If you create multiple environments with multiple different components, such as databases and compute instances using terraform, that is the right tool for creating your Oracle Integration instances.
  • If you rarely create Oracle Integration instances, the user interface may be more appropriate.
  • If you have lots of scripting of environments in python, the API is the way to go. 
  • If you script in a shell language, use the CLI!

Whatever your requirement Oracle Integration has a mechanism for you. For more details about Provisioning and Administering Oracle Integration 3, you can read the docs!

Learn more about why Oracle Integration is right for you at oracle.com/integration.