Jump to

• Request
• Response
• Examples

Test New Application Connection

post

/essbase/rest/v1/applications/{applicationName}/connections/actions/test

Tests a new or updated application connection, using specified inputs, without saving it.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• applicationName(required): string

  Application name.

Query Parameters

• validateName: boolean

  Validate if connection name already exists.

  Default Value: false

Body ()

Connection details.

Root Schema : connection

Type: object

Show Source

• aiConnection: string
• availability: string
• catalog: boolean
• chatCredential: string
• chatModel: string
• datasource: string
• dbDriver: string

  Optional. If type is DB and you are configuring Essbase to use a generic JDBC driver, provide the fully qualified class name of the JDBC driver. For example, oracle.jdbc.driver.OracleDriver.

• dbURL: string

  URL to an external RDBMS database, or, discovery URL to an Essbase instance. For connections to other Essbase instances, this parameter is an alternative to providing the host and port. Example of Essbase discovery URL https://192.0.2.1:443/essbase/agent. For examples of other uses, see documentation for global Get Connection endpoint.

• description: string

  A descriptive string for this connection.

• embedModel: string
• encrypted: boolean
• hidden: boolean
• host: string

  Host server name or IP. Required for Oracle Database connections. Required for Essbase connections, unless dbURL is used instead.

• links: array links
• maxPoolSize: integer(int32)

  Maximum connection pool size. Default is 50. If you get connection errors you may need to adjust minimum and maximum connection pool sizes. See About Controlling the Pool Size in UCP in Universal Connection Pool Developer's Guide.

• minPoolSize: integer(int32)

  Minimum connection pool size. Default is 5. If you get connection errors you may need to adjust minimum and maximum connection pool sizes. See About Controlling the Pool Size in UCP in Universal Connection Pool Developer's Guide.

• name(required): string

  A name for this connection.

• narrateDocDirectory: string
• narrateIndexName: string
• narrateProfileName: string
• ociAPIFormat(required): string
• ociCompartmentId: string
• password: string

  Required. Password of the user ID with authorization to access the remote source for this connection.

• path: string

  Required for file type connections. Catalog path to the file source of data. Example: /gallery/Technical/Drill Through/DrillthroughDS.csv

• port: integer(int32)

  Port number on the remote host. Required for connections when host is given.

• region: string
• repoWallet: boolean

  Set to true if you are using an Autonomous Data Warehouse connection which is already available (a repository connection). In this case, you do not need to upload a wallet.

• schema: string
• service: string

  Service name, if you are defining an Oracle Database connection.

• sid: string

  The Oracle System ID (SID) that uniquely identifies an Oracle Database. Required for Oracle Database connections unless service is used instead.

• subtype: string
  Allowed Values: [ "TEMPLATE", "EXCELFILE", "DB", "DELIMITEDFILE", "FIXEDWIDTHFILE", "BI", "ESSBASE", "JDBC", "SPARK", "MS_SQL", "MYSQL", "DB2", "ORACLE", "FILE", "AI" ]

  The type of external source. Supported sources and versions are listed in the Database section of the certification matrix (Platform SQL table).

• token: string
• transferTimeout: string
• type(required): string
  Allowed Values: [ "FILE", "DB", "ESSBASE", "BI", "AI" ]

  Required. Type of connection. FILE to connect to a file on the server, DB to connect to an external source system, or ESSBASE to connect to another cube.

• url: string
• user: string

  Required. User ID with authorization to access the remote source for this connection.

• vectorCredential: string
• walletPath: string

  Path to a wallet file, if required for your connection to Autonomous Data Warehouse (if repoWallet = false). Example: /system/wallets/EssbaseADWS. Obtain a wallet file by selecting Download Client Credentials (Wallet) from your Autonomous Data Warehouse Administration page in Oracle Cloud Infrastructure. If you are using a connection which is already available (a repository connection), you do not need to upload a wallet.

{
    "type":"object",
    "required":[
        "name",
        "ociAPIFormat",
        "type"
    ],
    "properties":{
        "description":{
            "type":"string",
            "description":"<p>A descriptive string for this connection.</p>"
        },
        "name":{
            "type":"string",
            "description":"<p>A name for this connection.</p>"
        },
        "type":{
            "type":"string",
            "description":"<p>Required. Type of connection. <code>FILE</code> to connect to a file on the server, <code>DB</code> to connect to an external source system, or <code>ESSBASE</code> to connect to another cube.</p>",
            "enum":[
                "FILE",
                "DB",
                "ESSBASE",
                "BI",
                "AI"
            ]
        },
        "path":{
            "type":"string",
            "description":"<p>Required for file type connections. Catalog path to the file source of data. Example: /gallery/Technical/Drill Through/DrillthroughDS.csv</p>"
        },
        "catalog":{
            "type":"boolean"
        },
        "host":{
            "type":"string",
            "description":"<p>Host server name or IP. Required for Oracle Database connections. Required for Essbase connections, unless <i>dbURL</i> is used instead.</p>"
        },
        "port":{
            "type":"integer",
            "format":"int32",
            "description":"<p>Port number on the remote host. Required for connections when <i>host</i> is given.</p>"
        },
        "user":{
            "type":"string",
            "description":"<p>Required. User ID with authorization to access the remote source for this connection.</p>"
        },
        "password":{
            "type":"string",
            "description":"<p>Required. Password of the user ID with authorization to access the remote source for this connection.</p>"
        },
        "encrypted":{
            "type":"boolean"
        },
        "token":{
            "type":"string"
        },
        "sid":{
            "type":"string",
            "description":"<p>The Oracle System ID (SID) that uniquely identifies an Oracle Database. Required for Oracle Database connections unless <i>service</i> is used instead.</p>"
        },
        "service":{
            "type":"string",
            "description":"<p>Service name, if you are defining an Oracle Database connection.</p>"
        },
        "schema":{
            "type":"string"
        },
        "dbURL":{
            "type":"string",
            "description":"<p>URL to an external RDBMS database, or, discovery URL to an Essbase instance. For connections to other Essbase instances, this parameter is an alternative to providing the <i>host</i> and <i>port</i>. Example of Essbase discovery URL <code>https://192.0.2.1:443/essbase/agent</code>. For examples of other uses, see documentation for global Get Connection endpoint.</p>"
        },
        "dbDriver":{
            "type":"string",
            "description":"<p>Optional. If <i>type</i> is <code>DB</code> and you are configuring Essbase to use a generic JDBC driver, provide the fully qualified class name of the JDBC driver. For example, <code>oracle.jdbc.driver.OracleDriver</code>.</p>"
        },
        "datasource":{
            "type":"string"
        },
        "subtype":{
            "type":"string",
            "description":"<p>The type of external source. Supported sources and versions are listed in the Database section of the certification matrix (Platform SQL table).</p>",
            "enum":[
                "TEMPLATE",
                "EXCELFILE",
                "DB",
                "DELIMITEDFILE",
                "FIXEDWIDTHFILE",
                "BI",
                "ESSBASE",
                "JDBC",
                "SPARK",
                "MS_SQL",
                "MYSQL",
                "DB2",
                "ORACLE",
                "FILE",
                "AI"
            ]
        },
        "walletPath":{
            "type":"string",
            "description":"<p>Path to a wallet file, if required for your connection to Autonomous Data Warehouse (if <i>repoWallet</i> = false). Example: <code>/system/wallets/EssbaseADWS</code>. Obtain a wallet file by selecting Download Client Credentials (Wallet) from your Autonomous Data Warehouse Administration page in Oracle Cloud Infrastructure. If you are using a connection which is already available (a repository connection), you do not need to upload a wallet.</p>"
        },
        "repoWallet":{
            "type":"boolean",
            "description":"<p>Set to <b>true</b> if you are using an Autonomous Data Warehouse connection which is already available (a repository connection). In this case, you do not need to upload a wallet.</p>"
        },
        "minPoolSize":{
            "type":"integer",
            "format":"int32",
            "description":"<p>Minimum connection pool size. Default is 5. If you get connection errors you may need to adjust minimum and maximum connection pool sizes. See <b>About Controlling the Pool Size in UCP</b> in <i>Universal Connection Pool Developer's Guide</i>.</p>"
        },
        "maxPoolSize":{
            "type":"integer",
            "format":"int32",
            "description":"<p>Maximum connection pool size. Default is 50. If you get connection errors you may need to adjust minimum and maximum connection pool sizes. See <b>About Controlling the Pool Size in UCP</b> in <i>Universal Connection Pool Developer's Guide</i>.</p>"
        },
        "hidden":{
            "type":"boolean"
        },
        "availability":{
            "type":"string"
        },
        "aiConnection":{
            "type":"string",
            "xml":{
                "name":"ai_connection"
            }
        },
        "chatCredential":{
            "type":"string",
            "xml":{
                "name":"chat_credential"
            }
        },
        "vectorCredential":{
            "type":"string",
            "xml":{
                "name":"vector_credential"
            }
        },
        "chatModel":{
            "type":"string",
            "xml":{
                "name":"chat_model"
            }
        },
        "ociCompartmentId":{
            "type":"string",
            "xml":{
                "name":"oci_compartment_id"
            }
        },
        "region":{
            "type":"string"
        },
        "url":{
            "type":"string"
        },
        "embedModel":{
            "type":"string",
            "xml":{
                "name":"embed_model"
            }
        },
        "transferTimeout":{
            "type":"string",
            "xml":{
                "name":"transfer_timeout"
            }
        },
        "ociAPIFormat":{
            "type":"string",
            "xml":{
                "name":"oci_apiformat"
            }
        },
        "narrateIndexName":{
            "type":"string",
            "xml":{
                "name":"narrate_index_name"
            }
        },
        "narrateProfileName":{
            "type":"string",
            "xml":{
                "name":"narrate_profile_name"
            }
        },
        "narrateDocDirectory":{
            "type":"string",
            "xml":{
                "name":"narrate_doc_directory"
            }
        },
        "links":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/Link"
            }
        }
    },
    "xml":{
        "name":"connection"
    }
}

Nested Schema : links

Type: array

Show Source

• Array of: object Link

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/Link"
    }
}

Nested Schema : Link

Type: object

Show Source

• href: string
• method: string
• rel: string
• type: string

{
    "type":"object",
    "properties":{
        "rel":{
            "type":"string"
        },
        "href":{
            "type":"string"
        },
        "method":{
            "type":"string"
        },
        "type":{
            "type":"string"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

OK

The connection tested successfully.

400 Response

Bad Request

Error occurred while testing connection.

Back to Top

Examples

The following example shows how to test a new application connection before creating it.

This example uses cURL to access the REST API from a Windows shell script. The calling user's ID and password are variables whose values are set in properties.bat.

Script with cURL Command

call properties.bat
curl -X POST -i "https://myserver.example.com:9001/essbase/rest/v1/applications/Sample/connections/actions/test" -H Accept:application/json -H Content-Type:application/json --data "@./app_conn_details.json" -u %User%:%Password%

The cURL example above delivers a JSON payload in app_conn_details.json. The details you include in the payload determine what kind of connection would be created. The example below is for testing a DB2 connection.

Sample JSON Payload - IBM DB2

The following sample JSON payload, passed to REST API in app_conn_details.json, is an example for testing a connection to DB2. The required parameters are name, type, subtype, dbDriver, host + port+ service (OR dbURL), user, and password.

{
  "name" : "DB2Conn",
  "type" : "DB",
  "subtype" : "DB2",
  "dbDriver" : "com.oracle.bi.jdbc.db2.DB2Driver",
  "host" : db2host.example.com",
  "port" : 50000,
  "user" : "user1",
  "password" : "cGE1NXdvcmQx",
  "service" : "dbname"
}

For more examples of JSON payloads you can use to test, update, and create connections to sources supported by Essbase, see the Create Connection endpoint.

Example of Response Body

Returns header information (if -i was used), beginning with the status code 200 (if the test was successful). The header information is truncated to show only the status code.

HTTP/1.1 200 OK

Back to Top