Example Scenario

Your Oracle Cloud Applications test instance is preconfigured with VB Studio. You want to consume an OIC REST API in your extension. You have an OIC test instance, say https://oic-test.integration.mycorpcloud.com, that has a REST API /ic/api/integration/v1/flows/rest/HELLO_WORLD/1.0/names/ that you want to connect to the extension that's deployed on the test instance. However, when deploying to production, you'd like to use your OIC production instance, say https://oic-prod.integration.mycorpcloud.com, in your service connection.

Prerequisites

Steps

Locate the Oracle Cloud Applications OAuth Client application in IDCS

1. In IDCS (connected to the Test instance), navigate to “Oracle Cloud Services” from the hamburger menu.
2. From the list of all the services shown, find the one that represents the Oracle Cloud Applications Test instance and select it.
3. To confirm this, navigate to the Configuration > Resources section.

   The primary audience or the secondary audience URL is the Oracle Cloud Applications Test instance's base URL.

   

Add the required scope of the OIC instance to the Oracle Cloud Applications OAuth Client application

1. In the Oracle Cloud Applications OAuth client, navigate to the Client Configuration > Token Issuance Policy > Resources - Add scope.

   A popup opens.

2. Choose the scope from the existing resource applications in IDCS.

   

3. Navigate through the list of resources and locate the resource application that represents the OIC instance.
4. Click the > button to select this resource app.

   The available scopes are displayed.

5. Select the scope that represents your REST API.

   For OIC, this will usually be the urn:opc:resource:consumer::all scope.

   

6. Note the scope https://<test uuid>/ic/api because you'll be adding it later in the VB Studio extension.
7. Click Add to add this scope to the Oracle Cloud Applications OAuth Client application.
8. Click Save to persist your changes.

Set up a backend and a service connection in the extension

1. In VB Studio, create a custom backend.

   See Create a Backend for more information.

   Set the following attributes:

   1. Specify a valid name, like oicBackend, for example, for your custom backend.
   2. Make the type custom.
   3. In the Server details page:
      • Set URL to the service connection's base URL (https://oic-test.integration.oraclecloud.ocp.com in our example).
      • Set Authentication to OAuth 2.0 User Assertion.

        If you can't see this option, see the Tip below.

      • Set Scope so it corresponds to the IDCS OIC REST application (for example https://<test_uuid>/urn:opc:resource:consumer::all).

      Tip:

      If the version of VB Studio you're using is older than 22.04), you may not be able to see the OAuth 2.0 User Assertion option in the Authentication selection menu. Follow these steps to assign the authentication mechanism and scope:

      1. Create the backend and set Authentication to None.

      2. From Backends, navigate to the Source tab and locate the "servers" section for the oicBackend in the catalog.json file.

      3. Add the authentication mechanism and the scope in the "servers" section:

         "servers": [
                 {
                     "url": "https://oic-test.integration.oraclecloud.com",
                     "description": "OIC Backend",
                     "x-vb": {
                         "authentication": {
                             "authenticated": {
                                 "type": "oauth2_user_assertion",
                                 "scope": "https://<test uuid>/ic/api"
                             }
                         }
                     }
                 }
             ], 
         

2. Click Create.

   The backend is created in a file called catalog.json, as shown.

   Now that we've created a backend that represents the OIC system, we'll create a service connection that uses this backend. The advantage of using a backend is that you can create multiple service connections based on it, without having to add the Server and Authentication details each time.

3. Add the service connection to the extension.

   See Create a Service Connection to learn about multiple ways you can create service connections. The example we show in this step uses the Define by Endpoint option, which is explained in greater detail in Create a Service Connection from an Endpoint, but you could use one of the other options to create the service connection too.

   Create the service connection by endpoint:

   1. Click + Service Connection.
   2. Click on the URL field to display a list of existing backends.
   3. Select the backend you just created (for example, oicBackend) and the URL will become vb-catalog://backends/<extn>:oicBackend.
   4. Add the rest of the URL path to the service connection (for example, /ic/api/integration/v1/flows/rest/HELLO_WORLD/1.0/names.
   5. Click Next and add an appropriate Service Name.
   6. Then add other details, like headers, query parameters etc., if any are needed.
4. Navigate to the Test tab and test the service connection.
5. When you're done, click Create.
6. Note the name of the service connection. You'll be using it later.

   Let's use the name "icApi" in this example. The source for this service connection is in the extension1/sources/services/self/icApi/openapi3.json file. You can confirm this by looking at the source tree.

   

Deploy the extension to the Test instance

1. Follow the instructions in Preview Your App UI to run (preview) the extension and check if it was successful.
2. If it was successful, commit the sources and push (or merge) them to the branch you'll be packaging from.
3. If the extension hasn't been configured already, follow the instructions in Set Up the Project for Testing to configure it.
4. Deploy the extension on the test instance.
5. Test the deployed extension and ensure that it works correctly in the test instance.

Deploy to the Production instance or to other instances

1. Repeat the steps in Locate the Oracle Cloud Applications OAuth Client application in IDCS and Add the required scope of the OIC instance to the Oracle Cloud Applications OAuth Client application for the production IDCS, production Oracle Cloud Applications pod, or production Oracle Integration Cloud instance.

   Note:

   Since you hardcoded the URL and the scope in the Backend source, you'll need to change them before deploying them to production pods if the OIC production instance is different than the test instance.
2. To do so, in the pipeline, add a preprocessing step that changes the URL and scope to that of the OIC production instance:
   1. Follow the instructions in Create and Configure Production Build Jobs to create the production build pipeline.
   2. Open the Packaging Build job in the pipeline and click Configure.

      

   3. From the menu Common Build Tools select Unix Shell and add a new step.

      

   4. • In the script area, add the command to change the OIC test instance URL and scope to that of the production catalog.json file. Use this format for the commands:

      sed -i 'originalText+modifiedText+g' filename_with_fullpath

      For our example, we'll use this:

      sed -i 's+https://oic-test+https://oic-prod+g' extension1/sources/services/self/catalog.json
      
      sed -i 's+<test uuid>+<prod uuid>+g' extension1/sources/services/self/catalog.json

   5. Click the up arrow to move the newly added step to the top of the job, before the Application Extension Packaging step.

      

   6. Save the job.
   7. Run the production pipeline and check the deployed extension.
   8. Perform the same steps for any other instances where the extension needs to be deployed.