3 Create an Oracle Aconex Cloud Adapter Connection

A connection is based on an adapter. You define connections to the specific cloud applications that you want to integrate.

Prerequisites for Creating a Connection

Every integration with Oracle Aconex APIs must be registered with Oracle, and you will receive the credentials required to uniquely identify the integration.

The first step is to decide which API Security method will be used, as the registration process differs depending on the chosen method.

The available methods are:

  • Register an OAuth Integration
  • Register a Basic Authentication Integration

For details about both methods, see Register a Customer integration in Aconex Support Central.

It is crucial to complete the registration process for the selected security method to establish a secure and successful connection between the adapter and Oracle Aconex.

OAuth Integration Registration: Necessary Steps

For OAuth-based integration, there are specific prerequisites and steps that need to be followed. One of the first steps is determining the type of OAuth integration that aligns with the requirements of the application.

Note:

The adapter uses the Non-Interactive Integration type for establishing connections - an integration that has no user interaction. This is a trusted client that uses JWT Bearer (otherwise known as User Assertion) grant type.

For detailed instructions about implementing OAuth in a Non-Interactive Integration, see Implement OAuth in a Non-Interactive Integration.

For additional information, see Getting started with APIs in the Oracle Aconex REST API documentation.

Create a Connection

Before you can build an integration, you must create the connections to the applications with which you want to share data.

Note:

You can also create a connection in the integration canvas. See why working with projects is preferred.

To create a connection in Oracle Integration:

  1. Decide where to start:
    • Work in a project (see why working with projects is preferred).
      1. In the navigation pane, click Projects.
      2. Select the project name.
      3. Click Integrations Integrations icon.
      4. In the Connections section, click Add if no connections currently exist or + if connections already exist. The Create connection panel opens.
    • Work outside a project.
      1. In the navigation pane, click Design, then Connections.
      2. Click Create. The Create connection panel opens.

  2. Select the adapter to use for this connection. To find the adapter, scroll through the list, or enter a partial or full name in the Search field.

  3. Enter the information that describes this connection.
    Element Description
    Name

    Enter a meaningful name to help others find your connection when they begin to create their own integrations.

    Identifier

    Automatically displays the name in capital letters that you entered in the Name field. If you modify the identifier name, don't include blank spaces (for example, SALES OPPORTUNITY).

    Role

    Select the role (direction) in which to use this connection.

    Note: Only the roles supported by the adapter you selected are displayed for selection. Some adapters support all role combinations (trigger, invoke, or trigger and invoke). Other adapters support fewer role combinations.

    When you select a role, only the connection properties and security policies appropriate to that role are displayed on the Connections page. If you select an adapter that supports both invoke and trigger, but select only one of those roles, you'll get an error when you try to drag the adapter into the section you didn't select.

    For example, assume you configure a connection for the Oracle Service Cloud (RightNow) Adapter as only an invoke. Dragging the adapter to a trigger section in the integration produces an error.

    Keywords

    Enter optional keywords (tags). You can search on the connection keywords on the Connections page.
    Description

    Enter an optional description of the connection.
    Share with other projects

    Note: This field only appears if you are creating a connection in a project.

    Select to make this connection publicly available in other projects. Connection sharing eliminates the need to create and maintain separate connections in different projects.

    When you configure an adapter connection in a different project, the Use a shared connection field is displayed at the top of the Connections page. If the connection you are configuring matches the same type and role as the publicly available connection, you can select that connection to reference (inherit) its resources.

    See Add and Share a Connection Across a Project.

  4. Click Create.

    Your connection is created. You're now ready to configure the connection properties, security policies, and (for some connections) access type.

  5. Follow the steps to configure a connection.

    The connection property and connection security values are specific to each adapter. Your connection may also require configuration with an access type such as a private endpoint or an agent group.

  6. Test the connection.

Configure Connection Properties

Enter connection information so your application can process requests.

  1. Go to the Properties section.
  2. In the Aconex instance URL field, enter the URL of your Oracle Aconex instance.

    This is the physical location where your project data is stored.

  3. From the Connection Type list, select REST API Base URL.

Configure Connection Security

Configure security for your connection.

  1. Go to the Security section.
  2. In the Security policy field, select which security policy you want to use.
    Security policy Options
    Basic Authentication
    • User Name — Enter the user name of your Oracle Aconex integration account.
    • Password — Enter the password of your Oracle Aconex integration account.

    Note:

    Oracle Aconex login is changing, and as a result of this, Basic Authentication will be deprecated in the Oracle Aconex Cloud Adapter. From August 2024, all users must sign in to Oracle Aconex using a Lobby account. For more information, see Aconex login is changing in Aconex Support Central.
    OAuth using JWT User Assertion

    • Access Token URI — Enter the URI of the POST request to the token endpoint of the Lobby. For example:

      https://constructionandengineering.oraclecloud.com/auth/token

    • JWT Headers in JSON Format — Upload a JSON file with the User Assertion JWT header. For example:
      {
    "kid":"MyCertificateAlias",
    "typ":"JWT",
    "alg":"RS256"
}
    • JWT Payload in JSON Format — Upload a JSON file with the User Assertion JWT body. For example:
      {
  "sub":"patrick.oleary@majestic.com", 
  "iss":"MyClientID",
  "aud":"https://identity.oraclecloud.com/",
  "exp":1708778535,
  "iat":1708774935,
  "jti":12345,
  "user_id":1879050130,
  "user_site":"https://au1.aconex.com"
}

    • JWT Private Key Alias — Enter the name of the private key that you uploaded to Oracle Integration certificates, matching the public certificate that was uploaded to the Lobby. This key will be used to verify that the User Assertion is signed by your application.

      To add a private key to Oracle Integration:

      1. In the navigation panel, select Settings, then Certificates.
      2. Click Upload.
      3. Enter the information that describes this certificate:

        1. Alias Name: Enter the name of the JWT signing Private key.

          For example: Oracle-Aconex-Private-key

        2. Description: Enter an optional description of the private key.
        3. Type: Select Signing key.
        4. Category: Select Private.
        5. Key File: Upload the private key in PEM format that will be used to verify that the User Assertion is signed by your application.
      4. Click Upload.
    • Expand the Optional Security section
      • Scope — Enter the scope, if applicable.
      • Access Token Request — Enter the POST request to the token endpoint of the Lobby, specifying client credentials using Basic Authentication in the header (Base64 encoding of the Client ID and Secret joined by a colon ':'). Include the pre-configured fields as parameter variables in the request. The format you specify can vary by service provider. For example: 
        -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic <base64 encoded Client ID and Secret>' \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${user_assertion}&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=${client_assertion}' \
${access_token_uri}

Test the Connection

Test your connection to ensure that it's configured successfully.

  1. In the page title bar, click Test.

    The test starts automatically and validates the inputs you provided for the connection.

  2. Wait for a message about the results of the connection test.
    • If the test was successful, then the connection is configured properly.
    • If the test failed, then edit the configuration details you entered. Check for typos and verify URLs and credentials. Continue to test until the connection is successful.
  3. When complete, click Save.