Data Source Connected Systems

This page provides details about data source connected systems. For information that pertains to all connected systems, see Connected System Object.

What is a data source connected system?

A data source connected system is any connected system that to an Appian-supported database. When you create a connected system and select a database type (such as MariaDB or PostgreSQL), the result is a data source connected system.

Data source connected systems store the authentication credentials and connection URL for the database, allowing you to manage the connection as a reusable, securable object.

Supported data sources

Data source connected systems support the following database types:

• Aurora MySQL
• Aurora PostgreSQL
• DB2
• MariaDB
• MySQL
• Oracle
• PostgreSQL
• SQL Server

Choose how to connect to data sources

You can connect to data sources using either a data source connected system or the Admin Console. In most cases, a data source connected system is the better choice. However, the Admin Console is required for certain configurations.

If you already have data sources configured in the Admin Console, you can migrate them to data source connected systems. See Migrate data sources from the Admin Console for details.

Benefits of using a data source connected system

Data source connected systems provide the following benefits:

• Object security: Control access to your data source details using role map security.
• Cross-environment deployment: Deploy authentication information for data sources across environments.
• Rename flexibility: Rename data sources without manually updating all objects that reference the data source.
• Connection pool control: Specify the maximum number of active connections that can be allocated to the database from the data source.

Reference a data source in a plug-in

If you are using a plug-in that connects to a data source, reference that data source by using the a!getDataSourceForPlugin() function.

Create a data source connected system

To create a data source connected system:

1. In your application, go to the Build view.
2. Click NEW > Connected System.

3. From the Create Connected System dialog, select one of the supported data sources from the list.

   

   Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

4. Configure the data source properties.
5. Click CREATE.

Properties

Data source connected systems have the following properties:

Field	Description
Name	The name of the data source connected system that appears in Appian design objects, such as data store objects.
Description	Supplemental information about the data source connected system.
System Logo	An image document used to visually represent the external system or service being connected to. The logo appears in the integration designer and in the Process Modeler on integrations that connect to this system (using the Call Integration Smart Service). If no document is selected, a default logo is used instead.
Connection URL*	The URL for the data source. The Connection URL must include the hostname, port, and database name of the data source. The exact syntax varies by database type. If you do not know the URL for the data source, consult your database administrator. See Configuring Relational Databases for special considerations when configuring databases for use with Appian.
Authentication	The authentication method used by this data source connected system: Basic Authentication or OAuth 2.0 Client Credentials Grant. OAuth can be used to authenticate with Oracle, SQL Server, or PostgreSQL data sources.
Maximum Connection Pool Size*	The maximum number of active connections to the database that can be allocated from this data source at the same time. The default value is 100. Since there is a limited number of connections that applications can make to the database, this field prevents one connected system from consuming the entire connection pool. You can raise or lower this number to control the number of connections for a data source. For example, if you have a data source for an application with low usage, you can lower this number to limit the connections for that application.
Additional Connection Properties	A list of properties that are passed to a JDBC driver to create database connections. Additional connection properties can be driver-dependent and must be separated by semicolons.
Data Source Shortcut	Determines whether to show the data source connected system as a data source shortcut in the record type configuration.
Shortcut Display Name	The name of the data source shortcut option. The Shortcut Display Name property only appears when Data Source Shortcut is selected.

*This value is included in import customization files so that you can specify a different value for each environment.

Automating property updates

This object's properties can also be updated programmatically using the Update Connected System endpoint. This lets you change passwords, API keys, and other values without needing to sign in to Appian.

The following properties can be included in the JSON request body of the PATCH /connected-system/<UUID> call.

• connectionUrl
• username
• password
• maxConnections

Migrate data sources from the Admin Console

If you migrate your data sources from the Admin Console to a data source connected system, you must update any objects that reference the data source. The following objects require updates:

• Data stores: Update the data source reference in each data store.
• Record types: Update the source of each record type.
• Process models: Update Query Database smart service nodes that reference the data source.

Enable one-way SSL/TLS connections

You can use Secure Socket Layer (SSL) or Transport Layer Security (TLS) in Appian to encrypt a connection to a supported database. SSL/TLS connections provide an additional layer of security by encrypting data transferred between Appian and your database instance or cluster.

In one-way SSL, only Appian validates the server certificate to ensure that it receives data from the intended database server.

To enable one-way SSL/TLS connections to an Appian-supported database:

1. Enable SSL/TLS on your database server.
2. Ensure that a valid SSL certificate has been uploaded to the Trusted Server Certificates in the Admin Console, especially if you are using a self-signed or private certificate authority (CA) signed SSL certificate on your database server.

3. Add SSL connection properties to your database connection URL.

   The following list example connection URLs for each supported database:

   • MariaDB:
     jdbc:mariadb://yourserver.example.com:3306/your_db_name?useOldAliasMetadataBehavior=true&useSSL=true&sslMode=VERIFY_IDENTITY
   • MySQL:
     jdbc:mysql://yourserver.example.com:3306/your_db_name?useOldAliasMetadataBehavior=true&useSSL=true&sslMode=VERIFY_IDENTITY
   • Oracle:
     jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=yourserver.example.com)(PORT=2484))(CONNECT_DATA=(SERVICE_NAME=YOUR_DB_NAME)))
   • SQL Server:
     jdbc:sqlserver://yourserver.example.com:1433;databaseName=your_db_name;encrypt=true;sslProtocol=TLS;trustServerCertificate=false
   • PostgreSQL:
     jdbc:postgresql://yourserver.example.com:5432/your_db_name?escapeSyntaxCallMode=callIfNoReturn&ssl=true&sslmode=verify-full

Control access to data using Appian Cloud database schemas

If you are using the Appian Cloud database, members of the Database Administrators group can create new schemas in the database. Creating a schema generates credentials that you can use to create MariaDB data source connected systems. You can then grant specific developers access to specific schemas.

For example, you can restrict access to human resources data so that only developers working on human resources applications can connect. You can also grant developers access in development environments while restricting access in testing and production environments.

For instructions on creating schemas in the Appian Cloud database, see Appian Cloud Database Administration.

Set the maximum connection pool size

The maximum connection pool size controls the number of active connections from Appian to the database. Every Appian system has at least one application server that communicates with the data source through the connected system. The application server can open concurrent connections up to the number you enter for the maximum connection pool size property. For example, if you set the maximum connection pool size to 100, Appian can open 100 concurrent connections to the data source.

Your Appian system may include features, such as autoscale, that affect the total number of connections. The following examples show how system features interact with the connection pool configuration:

• Autoscale: Sites with autoscaled processes can have additional process engines. Each process engine can create connections to the data source. For example, if your environment can have up to five process engines and your connected system is configured for a maximum of 100 connections, a single process engine allows up to 100 concurrent connections. If all five process engines are active, the number of concurrent connections can reach 500. Adding the Appian application server raises the total to 600 connections.
• High availability: Highly available sites have three application servers. If you set the connection pool size to 100, your application can have up to 300 concurrent connections to the data source.
• Combined: A highly available site with autoscale enabled has a combined maximum connection pool of 800.

To view the system features that impact your number of connections, go to the header bar of Appian Designer and select > About Appian. The About This Environment dialog appears.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Deploy data source connected systems

Keep the following caveats in mind when deploying data source connected systems between environments.

Create Appian Cloud database schemas before deploying

If you are using additional schemas in the Appian Cloud database to control access to data, create the schema in the target environment before deploying the data source connected system.

Deploy database scripts separately from the connected system

If your application includes a data source connected system, the connected system object must exist in the target environment before you can run database scripts against it. When a data source connected system object is part of a direct deployment, you cannot run database scripts for that data source in the same deployment.

If you are creating or updating a data source connected system object and deploying database scripts at the same time, use the following two-part process for direct deployments:

1. Deploy a package that contains the connected system object but does not include database scripts for the data source being deployed.
2. After the first package deploys successfully, deploy a package that includes the database scripts and any relevant design objects but leaves out the connected system object.

Avoid updating multiple schemas in one SQL script

If you are using additional schemas in the Appian Cloud database to control access to data, each schema has a different database user. Each database user can access only its own schema and the default "Appian" schema.

Compare and deploy uses the database user for the selected data source. If you are using compare and deploy to run SQL scripts, do not update additional schemas in the same script.

Feedback