Please rate how useful you found this document: 
Average: 2.8 (5 votes)

Database Connections

The current methods implemented for data connections in the ProcessMaker API designer are listed below:

Database Connections:

Name Description Type Value
dbs_uidDatabase connection UIDStringString with the database connection UID
dbs_typeDatabase typeString"mysql" (String verified with the DB engine type)
dbs_serverAddress of the database serverString“192.168.11.4” (String)
dbs_database_nameDatabase nameString"mydatabase" (Alphanumeric string)
dbs_usernameUsername in database serverString"root" (Alphanumeric string)
dbs_portDatabase server portString"3306" (Numeric)
dbs_encodeDatabase encodingString"utf8" (Alphanumeric string)
dbs_passwordDatabase server user password (This field is checked by type Database "dbs_type")String"root" (string verified with the types of encoding as "dbs_type")
dbs_descriptionDescription of the connection to the databaseString"My new database" (Alphanumeric string)

Information about each method is written in the sections below:

Get Database Connections List: GET project/{prj_uid}/database-connections

Gets the list of the database connections in a project.

GET /api/1.0/{workspace}/project/{prj_uid}/database-connections

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProject UID

Result:

TypeDescription
arrayReturns an array of database connection objects

Example:

Response

 200 (OK)
 Content-Type: application/json
 [
  {
     "dbs_uid": "17969179752e27c4b3027c3006962937",
     "pro_uid": "444446641528a7318e16744023753627",
     "dbs_type": "mysql",
     "dbs_server": "192.168.11.71",
     "dbs_database_name": "wf_test",
     "dbs_username": "root",
     "dbs_password": "password",
     "dbs_port": 3306,
     "dbs_encode": "utf8",
     "dbs_description": "My database connection description"
  },
  {
     "dbs_uid": "41091498852e27cab755345053537160",
     "pro_uid": "444446641528a7318e16744023753627",
     "dbs_type": "mysql",
     "dbs_server": "192.168.11.71",
     "dbs_database_name": "wf_test1",
     "dbs_username": "root",
     "dbs_password": "password",
     "dbs_port": 3306,
     "dbs_encode": "utf8",
     "dbs_description": "My database connection description"
   }
 ]

Get Database Connection: GET project/{prj_uid}/database-connection/{dbs_uid}

Gets information about a database connection.

GET /api/1.0/{workspace}/project/{prj_uid}/database-connection/{dbs_uid}

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProcess UID
dbs_uidStringDatabase UID

Result:

TypeDescription
objectReturns an object with the database connection data

Example:

Response

 200 (OK)
 Content-Type: application/json
 {
     "dbs_uid": "41091498852e27cab755345053537160",
     "pro_uid": "444446641528a7318e16744023753627",
     "dbs_type": "mysql",
     "dbs_server": "192.168.11.71",
     "dbs_database_name": "wf_test",
     "dbs_username": "root",
     "dbs_password": "password",
     "dbs_port": 3306,
     "dbs_encode": "utf8",
     "dbs_description": "My database connection description"
 }

Create Database Connection: POST project/{prj_uid}/database-connection

Creates a new database connection.

Permission:

Users must have the PM_FACTORY permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/project/{prj_uid}/database-connection

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProject UID

Required Fields:

NameTypeDescription
dbs_typeStringDatabase type
dbs_serverStringAddress of the database server
dbs_database_nameStringDatabase name
dbs_portIntegerDatabase server port
dbs_encodeStringEncoding Database

Optional Fields:

NameTypeDescription
db_usernameStringDatabase username
dbs_passwordStringUser password of the database server (This field is checked by type Database "dbs_type")
dbs_descriptionStringDescription of the database connection

Result:

TypeDescription
objectReturns an object containing information about the new database connection

Example:
Request

 Content-Type: application/json
 {
    "dbs_uid": "97821011252e67eb4c6c5d7069642907"
    "pro_uid": "444446641528a7318e16744023753627"
    "dbs_type": "mysql",
    "dbs_server": "192.168.56.11",
    "dbs_database_name": "My database",
    "dbs_username": "root",
    "dbs_password": "sample",
    "dbs_port": 3306,
    "dbs_encode": "utf8",
    "dbs_description": "Database description"
}

Response

 {
    "dbs_type": "mysql",
    "dbs_server": "192.168.56.11",
    "dbs_database_name": "My database",
    "dbs_username": "root",
    "dbs_password": "sample",
    "dbs_port": 3306,
    "dbs_encode": "utf8",
    "dbs_description": "Database description"
 }

Test Database Connection: POST project/{prj_uid}/database-connection/test

Tests a database connection with the provided settings.

Permission:

Users must have the PM_FACTORY permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/project/{prj_uid}/database-connection/test

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProject UID

Required Fields:

NameTypeDescription
dbs_typeStringDatabase type
dbs_serverStringAddress of the database server
dbs_database_nameStringDatabase name
dbs_portIntegerDatabase server port
dbs_encodeStringEncoding Database

Optional Fields:

NameTypeDescription
db_usernameStringDatabase username
dbs_passwordStringUser password of the database server (This field is checked by type Database "dbs_type")
dbs_descriptionStringDescription of the database connection

Result:

TypeDescription
arrayReturns an array of objects containing information about the connection.

Example:
Request

 Content-Type: application/json
 {
    "dbs_type": "mysql",
    "dbs_server": "192.168.56.11",
    "dbs_database_name": "My database",
    "dbs_username": "root",
    "dbs_password": "sample",
    "dbs_port": 3306,
    "dbs_encode": "utf8",
    "dbs_description": "Database description"
}

Response

 201 (Created)
 [
   {
      "test": "Resolving Host Name 192.168.11.79"
   },
   {
      "test": "Checking port 3306",
      "error": "Error Testing Connection: Checking port FAILED : Destination Port Unreachable"
   },
   {
      "test": "Trying to connect to host 192.168.11.79:3306",
      "error": "Error Testing Connection: Trying to connect to host FAILED : Destination Port Unreachable"
   },
   {
      "test": "Trying to open database [wf_jc]",
      "error": "Error Testing Connection: Trying to open database FAILED : Destination Port Unreachable"
   }
 ]

Update Database Connection: PUT project/{prj_uid}/database-connection/{dbs_uid}

Updates a database connection with the provided settings.

Permission:

Users must have the PM_SETUP permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/project/{prj_uid}/database-connection/{dbs_uid}

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProject UID
dbs_uidStringDatabase connection UID

Required Fields:

NameTypeDescription
dbs_typeStringDatabase type
dbs_usernameStringDatabase user name. Required field as of ProcessMaker 3.3.1
dbs_encodeStringEncoding Database
dbs_connection_typeStringConnection type in Oracle that could be "Normal" or "TNS". Required field if dbs_type is Oracle. New required field as of ProcessMaker 3.3.1
dbs_tnsStringTNS connection web. Required field if dbs_type is Oracle. New required field as of ProcessMaker 3.3.1
dbs_passwordStringUser password of the database server (This field is checked by type Database "dbs_type"). Required field if the password is different to empty. Required field as of ProcessMaker 3.3.1
dbs_serverStringAddress of the database server. Not required if dbs_type is Oracle and dbs_connection_type is TNS
dbs_database_nameStringDatabase name. Not required if dbs_type is Oracle and dbs_connection_type is TNS
dbs_portIntegerDatabase server port. Not required if dbs_type is Oracle and dbs_connection_type is TNS

Optional Fields:

NameTypeDescription
dbs_descriptionStringDescription of the database connection

Result:

TypeDescription
emptyNo return

Example:

Request

  • MySQL connection:
     Content-Type: application/json
     {
         "dbs_type": "mysql",
         "dbs_server": "192.168.56.11",
         "dbs_database_name": "My database",
         "dbs_username": "root",
         "dbs_port": 3306,
         "dbs_encode": "utf8",
         "dbs_description": "Changing the description"
     }
  • Oracle connection with password different to empty:
     Content-Type: application/json
     {
         "dbs_type": "oracle",
         "dbs_username": "root",
         "dbs_encode": "utf8",
         "dbs_password": "root",
         "dbs_connection_type": "TNS",
         "dbs_tns": "192.168.56.11/XE",
         "dbs_description": "Changing the description"
     }

Response

  • If everything is OK, the 200 response displays:
     200 (OK)
  • If the Oracle password is incorrect, the following message displays:
    {
      error: {
        code: 400,
        message: "Bad Request: Error Testing Connection: Opening database type TNS failed, Oracle connection refused"
      }
    }

Delete Database Connection: DELETE project/{prj_uid}/database-connection/{dbs_uid}

Deletes the specified database connection.

Permission:

Users must have the PM_FACTORY permission assigned to their role to perform this action.

Structure:

DELETE /api/1.0/{workspace}/project/{prj_uid}/database-connection/{dbs_uid}

Parameters:

NameTypeDescription
workspaceStringWorkspace name
prj_uidStringProject UID
dbs_uidStringRelation UID

Result:

TypeDescription
emptyNo return

Example:

Response

 200 (OK)