Database Connection Web Services

Overview

Universal Controller supports the following RESTful-based web services for Database Connection operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about property requirements, are provided.

Create a Database Connection


Description

URI

HTTP Method

POST

Description

Creates an Database Connection.

Example URI

http://localhost:8080/uc/resources/databaseconnection

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Create a Database Connection: Example Request, below.

Example Response

  • Status 200 /OK
    Successfully created the Database Connection with sysId {sysId}.
  • Status 400 /Bad Request
    Create Database Connection failed. A duplicate value has been detected. Name must be unique.

Database Connection Properties

See Database Connection Properties, below.

Create a Database Connection: Example Request

XML Request

JSON Request

 XML Request
<databaseConnection retainSysIds="true">
    <credentials />
    <dbDescription />
    <dbDriver>com.mysql.jdbc.Driver</dbDriver>
    <dbMaxRows />
    <dbType>My SQL</dbType>
    <dbUrl>jdbc:mysql://localhost:3306/uc</dbUrl>
    <name>Database Connection 1</name>
    <opswiseGroups />
    <sysId>62701879a6264107bb757a952bcc65cc</sysId>
</databaseConnection>
 JSON Request
{
    "credentials": null,'
"dbDescription": null, "dbDriver": "com.mysql.jdbc.Driver", "dbMaxRows": null, "dbType": "My SQL", "dbUrl": "jdbc:mysql://localhost:3306/uc", "name": "Database Connection 1", "opswiseGroups": null, "retainSysIds": true, "sysId": "62701879a6264107bb757a952bcc65cc" }

Database Connection Properties

Property

UI Field Name

Description

Specifications

Required

credentials

Credentials

Credentials for this Database Connection.


N

dbDescription

Description

Description of this record.


N

dbDriver

Driver

Name of the JDBC driver.


Y

dbMaxRows

Maximum Rows

If necessary, specifies a limit to the number of rows you want returned by the SQL statement.


N

dbType

Database Type

Type of Database.

Valid Values:


  • As String = MySQL (or My SQL), As Value = 1


  • As String = MS SQL Server, As Value = 2


  • As String = Oracle, As Value = 3


  • As String = DB2, As Value = 4


  • As String = Sybase SQL Anywhere, As Value = 5


  • As String = Other, As Value = 6


Default is MySQL (1).

Y

dbUrl

Connection URL

URL of the database.


Y

exportReleaseLevel

n/a

Universal Controller release that the record was exported from.

read onlyN

exportTable

n/aRecord table information.read onlyN

name

Connection Name

Name used within the Controller to identify this Database Connection.


Y

opswiseGroups

Member of Business Services

Business Services that this record belongs to.
 
XML


<opswiseGroups>
      <opswiseGroup>group1</opswiseGroup>
      <opswiseGroup>group2</opswiseGroup>
</opswiseGroups>


 
JSON


"opswiseGroups": ["group1","group2"]


N

retainSysIds

n/a

Specification for whether or not the Create a Database Connection web service will persist the sysId property.

  • If retainSysIds="true" and sysId is included in the request/response, sysId will be persisted to the database.
  • If retainSysIds="false" and sysId is included in the request/response, sysId will be ignored; it will be autogenerated by the Controller.


Note

In XML web services, retainSysIds is specified as an attribute in the <databaseConnection> element.

Valid values: true/false (default is true).

N

sysId

n/a

System ID field in the database for this Database Connection record.

Persisted only if retainSysIds is set to true.

N

Delete a Database Connection


Description

URI

http://host_name/uc/resources/databaseconnection

HTTP Method

DELETE

Description

Deletes a Database Connection.

URI Parameters

See Delete a Database Connection: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/databaseconnection?connectionname=Test4

Example Response

  • Status 200 /OK
    Database Connection deleted successfully.
  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify connectionname and connectionid at the same time.
  • Status 404 /Not Found
    a Database Connection with {name/id} "test" does not exist.

Delete a Database Connection: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

connectionid

ID used within the Controller to identify this Database Connection.

String; URI parameter.

Y
(unless connectionname
is specified)

connectionname

connectionname

Name used within the Controller to identify this Database Connection.

String; URI parameter.

Y
(unless connectionid
is specified)

connectionid

List Database Connections


Description

URI

HTTP Method

GET

Description

Retrieves information on all Database Connections.

Example URI

http://localhost:8080/uc/resources/databaseconnection/list

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

See List Database Connections: Example Response, below.

Database Connection Properties

See Database Connection Properties.

List Database Connections: Example Response

XML Response

JSON Response

 XML Response
<databaseConnections>  
    <databaseConnection exportReleaseLevel="7.2.0.0" exportTable="ops_database_connection" version="3">
        <credentials />
        <dbDescription />
        <dbDriver>com.mysql.jdbc.Driver</dbDriver>
        <dbMaxRows />
        <dbType>My SQL</dbType>
        <dbUrl>jjdbc:mysql://localhost:3306/uc</dbUrl>
        <name>Database Connection 1</name>
        <opswiseGroups />
        <sysId>62701879a6264107bb757a952bcc65cc</sysId>
    </databaseConnection>
    <databaseConnection exportReleaseLevel="7.2.0.0" exportTable="ops_database_connection" version="6">
        <credentials />
        <dbDescription />
        <dbDriver>com.mysql.jdbc.Driver</dbDriver>
        <dbMaxRows />
        <dbType>My SQL</dbType>
        <dbUrl>jdbc:mysql://localhost:3306/uc</dbUrl>
        <name>Database Connection 2</name>
        <opswiseGroups />
        <sysId>3d7a03053ad64de1b21b6849e6deafd9</sysId>
    </databaseConnection>
<databaseConnections>
 JSON Response
[ 
    {
    "credentials": null,
    "dbDriver": "com.mysql.jdbc.Driver",
    "dbMaxRows": null,
    "dbType": "My SQL",
    "dbUrl": "jdbc:mysql://localhost:3306/uc",
    "dbDescription": null,
"exportReleaseLevel": "7.2.0.0",
"exportTable": "ops_database_connection",
"name": "Database Connection 1", "opswiseGroups": null, "sysId": "62701879a6264107bb757a952bcc65cc", "version": 3 }, { "credentials": null, "dbDescription": null, "dbDriver": "com.mysql.jdbc.Driver", "dbMaxRows": null, "dbType": "My SQL", "dbUrl": "jdbc:mysql://localhost:3306/uc",
"exportReleaseLevel": "7.2.0.0",
"exportTable": "ops_database_connection", "name": "Database Connection 2", "opswiseGroups": null, "sysId": "3d7a03053ad64de1b21b6849e6deafd9", "version": 6 } ]

Modify a Database Connection


Description

URI

HTTP Method

PUT

Description

Modifies the Database Connection specified by the sysId.

Example URI

http://localhost:8080/uc/resources/databaseconnection

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Modify a Database Connection: Example Request, below.

Database Connection Properties

See Database Connection Properties.

Example Response

  • Status 200 /OK
    Successfully updated the Database Connection with sysId <sysId> to version <version>.

Modify a Database Connection: Example Request

XML Request

JSON Request

 XML Request
<databaseConnection>
    <credentials />
    <dbDescription />
    <dbDriver>com.mysql.jdbc.Driver</dbDriver>
    <dbMaxRows />
    <dbType>My SQL</dbType>
    <dbUrl>jdbc:mysql://localhost:3306/uc</dbUrl>
    <name>Database Connection 1</name>
    <opswiseGroups>
        <opswiseGroup>Accounting</opswiseGroup>
    </opswiseGroups>
    <sysId>62701879a6264107bb757a952bcc65cc</sysId>
</databaseConnection>
 JSON Request
{
    "credentials": null,
    "dbDescription": null,
    "dbDriver": "com.mysql.jdbc.Driver",
    "dbMaxRows": null,
    "dbType": "My SQL",
    "dbUrl": "jdbc:mysql://localhost:3306/uc",
    "name": "Database Connection 1",
    "opswiseGroups": [ "Accounting" ],
    "sysId": "62701879a6264107bb757a952bcc65cc"
}

Read a Database Connection

URI

http://host_name/uc/resources/databaseconnection

HTTP Method

GET

Description

Retrieves information on a specific Database Connection.

URI Parameters

See Read a Database Connection: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/databaseconnection?connectionname=Test4

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

See Read a Database Connection: Example Response, below.

Database Connection Properties

See Database Connection Properties.

Read a Database Connection: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

connectionid

ID used within the Controller to identify this Database Connection.

String; URI parameter.

Y
(unless connectionname
is specified)

connectionname

connectionname

Name used within the Controller to identify this Database Connection.

String; URI parameter.

Y
(unless connectionid
is specified)

connectionid

Read a Database Connection: Example Response

XML Response

JSON Response

 XML Response
<databaseConnection exportReleaseLevel="7.2.0.0" exportTable="ops_database_connection" retainSysIds="true" version="1">
    <credentials />
    <dbDescription />
    <dbDriver>com.mysql.jdbc.Driver</dbDriver>
    <dbMaxRows />
    <dbType>My SQL</dbType>
    <dbUrl>jdbc:mysql://localhost:3306/uc</dbUrl>
    <name>Database Connection 1</name>
    <opswiseGroups />
    <sysId>62701879a6264107bb757a952bcc65cc</sysId>
</databaseConnection>
 JSON Response
{
    "credentials": null,
    "dbDescription": null,
    "dbDriver": "com.mysql.jdbc.Driver",
    "dbMaxRows": null,
    "dbType": "My SQL",
    "dbUrl": "jdbc:mysql://localhost:3306/uc",
"exportReleaseLevel": "7.2.0.0",
"exportTable": "ops_database_connection",
"name": "Database Connection 1", "opswiseGroups": null, "retainSysIds": true, "sysId": "62701879a6264107bb757a952bcc65cc", "version": 1 }