Create and Use Environments

5 Create and Use Environments

An environment defines the target Oracle Cloud Applications, Visual Builder, Oracle Cloud SaaS, or Oracle Cloud Infrastructure service instance as a single entity. You'll define an environment to deploy an application to a service instance or to get information from a service instance.

Define Your Environments

An environment lets you define and manage Oracle Cloud PaaS, and Oracle Cloud SaaS service instances as a single entity.

You might create an environment for your QA team with an Oracle Database Cloud Service instance to host data, say, and maybe an Oracle Java Cloud Service instance to deploy the application to and run Selenium tests. You could then create a Stage environment that uses the same Oracle Database Cloud Service instance as the QA environment, but a different Oracle Java Cloud Service instance to deploy the application to.

If you're working with Oracle Cloud Applications extensions, you'll have a VB Studio Development environment that points to your Oracle Cloud Applications development instance (this environment is created automatically if the Application Extension template was used to create the project). You can create additional environments for Oracle Cloud Applications and add the production instance of your current identity domain, or an external Oracle Cloud Applications instance from another identity domain. Note that you can only add one Oracle Cloud Applications instance to an environment. See Add the Oracle Cloud Application's Production Instance to an Environment in Administering Visual Builder Studio for more information.

If you're working with visual applications, you'll have a VB Studio Development environment that points to your Visual Builder development instance (this environment is created automatically if the Visual Application template was used to create the project). You can create additional environments for visual apps and add the production instance of your current identity domain, or an external Visual Builder instance from another identity domain. Note that you can add only one Visual Builder instance to an environment. See Add the Visual Builder Production Instance to an Environment in Administering Visual Builder Studio for more information.

You can access and manage the project’s environments from the Environments page:

Description of devcs_environments.png follows

Description of the illustration devcs_environments.png

From the Environments page, you can:

Create and delete environments
Add or remove service instances from existing environments
Update the details of the environment
The Details tab displays details, such as name and description, for the selected environment. You can also instantly see the health of all service instances comprising each environment right on the Project Home page or on the Environments page.
View the details of its service instances
The Service Instance tab captures information, such as the health status of and response times for service instances, their account names, and service IDs, for each environment in a single place, so you won’t have to hunt for it later.
View deployments
The Deployments tab shows deployments for extensions and visual apps. Use the Application Extensions toggle to show deployments for all projects associated with this environment or use the Visual Applications toggle to show deployments for the current project only.

Set Up an Environment

You can create an environment and add service instances to it from different identity domains. For example, you can add an Oracle Database Cloud Service instance from one identity domain and an Oracle Java Cloud Service instance from another identity domain.

To add or remove a PSM-based service instance, you need credentials of a user who is assigned the administrator role for the service type. To assign or modify roles, see Modifying Identity Cloud Service User Roles in Managing and Monitoring Oracle Cloud.

In the left navigator, click Environments .
Click Create (or Create Environment if the page is empty).
In Environment Name, enter a unique name. In Description, enter a description.
Click Create.
In the Service Instances tab, click Add.
In the Add Service Instances dialog box, select the type of service instance (Visual Builder, Oracle Cloud Applications, or Infrastructure Services), then select the check boxes of service instances and click Add.
By default, the dialog box shows the service instances that you can access from the current identity domain.

If you have a PSM entitlement, you'll see both service instances and IDCS resources in this list. In the Type column, the current identity domain's service instances are marked as IDCS Resource and PSM instances are marked as Visual Builder or Integration (if you're an Oracle Integration user). Selecting a service instance is slightly preferable, since it gives you not only a cleaner URL, but also indicates status and provides access to actions like starting and stopping instances, and more.

To search for services from another identity domain or account, click Edit and enter the details in the popup that opens.

To search for a service in another identity domain, enter the identity domain ID and region in the Visual Builder and Infrastructure Services tab. You can't change the identity domain for Oracle Cloud Applications. You can only see the list of Oracle Cloud Applications from the current identity domain.
To add a standalone Visual Builder instance or a Visual Builder instance that's part of Oracle Integration in another identity domain to an environment, you'll need one of these:
- The instance's identity domain ID, region, and a user's credentials who can access the instance
- The Visual Builder instance's base URL and a user's credentials who can access the instance
Note:
Typically, the Visual Builder instance added to your visual application's environment uses the same identity domain as your Visual Builder Studio instance. If you choose a Visual Builder instance from a different identity domain as your deployment environment, you'll see a warning about setting up the Allowed Origins configuration. If you see this, you'll need to talk to your administrator to make sure your instance's domain is added to its list of allowed origins, as described in Allow Other Domains Access to Services.
See Add the Visual Builder Production Instance to an Environment .

To add an Oracle Cloud Applications instance to an environment, you'll need the base Oracle Cloud Application's URL and the credentials of a user who can access the instance.

See Add the Oracle Cloud Application's Production Instance to an Environment.

To add an Infrastructure Services instance, such as Oracle Integration, OIC Gen 2, or JCS, or OCI resources such as Compute, Storage, or databases, to an environment, you'll need the instance's region, identity domain ID, and a user's credentials who can access the instance to display a list of the resources you can add to the environment:

Note:
To connect to an IDCS-based instance, instead of a traditional identity domain name, you'll need to provide an IDCS tenant name, which looks something like "IDCS-XXXXXXXXXXXXXXX", in the configuration dialog .
If necessary, repeat steps 5 and 6 to find and add additional service instances from different identity domains and data centers.

Manage Trust Certificates in an Environment Definition

Visual Builder Studio uses trust certificates to connect with external services. If a service/endpoint needs a special certificate, you can get it from the service you're trying to connect with, and then upload it from the Certificates tab on the Environments page. After you do that, any time you use that environment, you'll get all the certificates that were added to it.

You can use the Certificates tab to upload and remove certificate files for services. Uploading a service’s certificate file to the truststore will allow all applications that use that environment to communicate with that service. The Certificates tab displays a list of certificates that have been added. You can click Delete in a row to remove the certificate.

To upload a certificate:

In the left navigator, click Environments .
Click the Certificates tab.
The Certificates page displays a list of the trust certificates that have already been uploaded for the environment, similar to this:

Description of the illustration vbs_list_certs.png
Click + Add Certificate to open the Add Certificate dialog.
You use the Add Certificate dialog shown here to create an alias for the certificate and upload the service’s certificate file from your local system:

Description of the illustration vbs_add_cert.png
Type the alias in the Alias field.
The alias is used to identify the certificate in the table on the Certificates page.
Drag the certificate file from your local system to the upload target area, or click the upload target area to browse your local system to locate, select, and add the file.
Click Upload to add the certificate to the environment's truststore.

Create and Edit VB Studio Custom Backends from the Environments Page

After an environment has been created and a Visual Builder instance has been added to it, you can click the Backends button on the Environments page's Service Instances tab, and the catalog editor for that specific environment will be loaded. You can use the editor to modify the existing backend or create a new one.

Backends define servers that your visual applications and extensions can access. The VB Studio catalog of predefined services includes backends, such as Oracle Cloud Applications, Integration Applications, and Process Applications. With the Backends button on the Environments page's Service Instances tab, you can create custom backends to access services that aren't listed in this catalog.

For each backend, you can use the following tabs to view and edit the backend's details:

Tab	Description
Overview	Displays the name and type of the backend (which can be Integration Applications, Oracle Cloud Applications, Process Applications, or a custom backend). You can use the topmost + button to create a new backend or use the lower + button to create a child backend.
Servers	Displays the servers associated with the backend and includes the instance URL and the application profile associated with the instance. You can add, edit, or remove backend servers. You may have one or more servers if the backend is hosted on different instances. You use the + Add Server button to add new servers where you specify details such as: The application profile to associate with the server Headers Security and connection details
Headers	Displays the static headers defined for the backend at the server level. You can add and edit headers in the tab.
Source	Displays the description of the backend stored in the environment-level `catalog.json` file. If you override the environment-level definition, this file shows the contents of the application-level catalog from the `services/catalog.json` file. You can edit the entries in the Source tab, if you want.

See What Are Backends? to learn more about backends.

To learn more about adding an Oracle Cloud Application instance to a visual application, or creating a backend, custom backend, or child backend, see Manage Backends in Your Visual Application.

To learn more about selecting authentication and connection types for backends, see Configure Authentication and Connection Types for Service Connections and Backends.

Manage an Environment

After creating an environment, you can add and manage its instances, as shown here:

Action	How To
Edit an environment's name and description	In the Details tab, click Edit. Edit the details and click Save.
Add a new service instance to an environment	In the Service Instances tab, click Add. In the Add Service Instances dialog box, use the toggle to select the type of service instance (Visual Builder, Oracle Cloud Applications, or Infrastructure Services), then select the check boxes of service instances and click Add. By default, the dialog box shows the service instances that you can access from the current identity domain. If you have a PSM entitlement, you'll see both service instances and IDCS resources in this list. In the Type column, the current identity domain's service instances are marked as IDCS Resource and PSM instances are marked as Visual Builder or Integration (if you're an Oracle Integration user). Selecting a service instance is slightly preferable, since it gives you not only a cleaner URL, but also indicates status and provides access to actions like starting and stopping instances, and more. To search for services from another identity domain or account, click Edit and enter the details in the popup that opens. To search for a service in another identity domain, enter the identity domain ID and region in the Visual Builder or the Infrastructure Services tabs. You can't change the identity domain for Oracle Cloud Applications. You can only see the list of Oracle Cloud Applications from the current identity domain. To add a standalone Visual Builder instance or a Visual Builder instance that's part of Oracle Integration in another identity domain to an environment, you'll need one of these: The instance's identity domain ID, region, and a user's credentials who can access the instance The Visual Builder instance's base URL and a user's credentials who can access the instance Note: Typically, the Visual Builder instance added to your visual application's environment uses the same identity domain as your Visual Builder Studio instance. If you choose a Visual Builder instance from a different identity domain as your deployment environment, you'll see a warning about setting up the Allowed Origins configuration. If you see this, you'll need to talk to your administrator to make sure your instance's domain is added to its list of allowed origins, as described in Allow Other Domains Access to Services. See Add the Visual Builder Production Instance to an Environment . To add an Oracle Cloud Applications instance to an environment, you'll need the base Oracle Cloud Application's URL and a user's credentials who can access the instance. See Add the Oracle Cloud Application's Production Instance to an Environment. Note: If a provisioning failure occurs after you add a Visual Builder or FA service instance to an environment, the status icon in the Environments page will reflect one of the following states: failed provisioning, provisioning, or timed out. If provisioning fails, mouse-over the service instance in the Service Instances tab, click Action , and select Refresh to see if the state has changed. If it hasn't, select Retry Provisioning. To add an Infrastructure Services instance, such as Oracle Integration, OIC Gen 2, or JCS, or OCI resources such as Compute, Storage, or databases, to an environment, you'll need the instance's region, identity domain ID, and a user's credentials who can access the instance. Note: To connect to an IDCS-based instance, instead of a traditional identity domain name, you'll need to provide an IDCS tenant name, which looks something like "IDCS-XXXXXXXXXXXXXXX", in the configuration dialog .
Start, stop, or restart an instance	In the Service Instances tab, mouse-over the service instance, click Action , and select Start, Stop, or Restart. To check the status of the service, select Refresh Status from the Action menu.
Check a service instance's response time	The Response Time column provides information about the service instance: A green dot indicates that the response time is less than 5 seconds. A yellow dot indicates that the response time was between 5 and 30 seconds. A red dot indicates that the response time was greater than 30 seconds or that the connection timed out.
Remove a service instance from an environment	In the Service Instances tab, mouse-over the service instance, click Action , and select Remove. Note: An instance can't be removed if it's associated with any workspace. If you try, an error message displays, listing the impacted users and the number of workspaces they have. You'll be instructed to ask those users to delete their workspaces. Once this has been done, you can go back and retry the Remove operation.
Delete an environment	In the environments list, mouse-over the environment, click Action , and select Delete. Remember that service instances of the environment aren’t deleted. Note: An environment can't be deleted if it's associated with any workspace. If you try, an error message displays, listing the impacted users and the number of workspaces they have. You'll be instructed to ask those users to delete their workspaces. After they do that, you can go back and try to delete the environment again.

Use Service Instance Statuses to Troubleshoot Problems

You can use the service instance statuses and troubleshooting/support information in this section to understand and correct problems indicated by error statuses. Understanding what these error conditions result from can shed light on what could be causing the problems and point to what you need to do to fix them.

Here are the current Service Instance statuses and some of their causes:

Status	Description
Unauthorized	Usually occurs when the user can't be validated with the target instance: For an IDCS resource, ensure that the logged-in user is a valid user in the target instance. For an application endpoint connection, ensure that the user and credentials specified are valid. For an Oracle Cloud Applications target instance, ensure that the VB Studio instance has been whitelisted. If all the causes have been ruled out, the problem may be due to an infrastructure issue. Contact Oracle Support.
Timeout	The target instance didn't return a response in an acceptable length of time. The request to return status may eventually complete, at which time the status will change, but this status indicates a problem with the target instance's health and should be investigated if it persists.
Available	The target instance is available and responding to API requests.
Not Available	The target instance reported an Unavailable status (HTTP 503).
Error	An unexpected error occurred while contacting the target instance for its status. If this condition persists, contact Oracle Support.
Not Found	An HTTP 404 error was returned when contacting the target instance: For an IDCS resource, ensure that the instance is up and running and there is a network route between the VB Studio and target instances. For an application endpoint connection, ensure that the URL is specified correctly and points to a VB, Integration Cloud, or Oracle Cloud Applications instance. Could also be caused by proxy timeouts, network connection issues, or load balancer problems.
Deactivated	IDCS resources were deactivated. Returned for an IDCS resource only, indicating that the resource has been deactivated in IDCS, preventing access to that resource. Contact your IDCS administrator to reactivate it or remove the IDCS resource from the environment.
Unknown	This is the default status before the target instance is contacted and verified. It should change to one of the other statuses listed in this table. If the status persists in this state, contact Oracle Support.