Skip to main content




Service Studio version:

Integrate with an External Database

  • Edit
    Collaborate with us
    Edit this page on GitHub
  • OutSystems integrates with your existing databases. This allows you to develop applications that access data on external databases using OutSystems entities in Service Studio and without having to worry about data migration. For a list of supported external database engines and their supported versions check the System Requirements.

    When you are done developing your integration with an external database and you want to deploy the application to another Environment (e.g. quality assurance environment) check out this step by step guide.

    The creation of an integration with an external database involves the following general steps:

    1. In Service Center, define a connection to the external database.
    2. In Integration Studio, create an extension module to map tables or views in the external database to OutSystems entities.
    3. In Service Center, configure the extension to use a database connection.
    4. In Service Studio, reference and use the extension in your application.

    The following sections go throught each one of these general steps in detail.

    Define a Connection to the External Database

    To use tables and views from external databases, create a database connection:

    1. Open the Service Center management console of your OutSystems environment.

      Tip: Open Service Center directly from Service Studio by clicking Environment Management....

    2. On the Administration tab, select Database Connections.

    3. Click New Database Connection and fill in the fields to set up the connection to the external database.

      If you need to fine-tune the database connection, choose the option Advanced configuration. This allows you to define your own connection string.

    4. Click Test Connection to check if the connection is working correctly.

      The database user must have permissions to:

      • List the necessary tables and views on the external database.
      • Perform the operations Create, Read, Update, and Delete on those tables and views.
    5. Click Create to create the Database Connection.

    Map Tables or Views to Entities in an Extension Module

    After configuring a database connection in Service Center, use Integration Studio to create an extension that maps the tables or views in the external database to OutSystems entities:

    1. Go back to Service Studio, open your Application, select New Module and create a new Extension Module.

    2. In Integration Studio, Connect to your environment.

    3. Right-click the Entities folder in the Extension Tree and select Connect to External Table or View....

    4. Follow the steps of the wizard.

      Make sure that you:

      • Select the database connection configured previously.
      • Select the necessary tables and views.
      • Define a logical database name that you will use to connect the extension to a physical database connection in the next section.
    5. After closing the wizard, review the imported entity names, descriptions and data types for each attribute.

    6. Select 1-Click Publish to publish the Extension Module.

      After publishing the extension, OutSystems warns you that you still need to configure which database connection the extension will use.

    7. In the 1-Click Publish summary window, select the Missing Configuration warning and then select Configure.

    Configure the Extension to Use a Database Connection

    After mapping the tables or views, use Service Center to configure which database connection the extension will use:

    1. In Service Center, make sure you are in the Operation tab of Factory > Extensions > <your extension name>.

    2. Associate the logical database name of the extension to the database connection that the extension will use in runtime.

    In some cases you need to select the database based on runtime data. Typically, the applicable databases share the same schema but they contain different data.

    In these scenarios you can use the action DatabaseConnection_SetConnectionStringForSession of the PlatformRuntime API.

    Use the Extension in your application

    The Extension is now ready to be used in OutSystems applications:

    1. In your application, click Manage Dependencies....

    2. Add a dependency to the Extension and select the Entities that you will use in your application.

    You can now use the entities of the extension to manipulate data on the external databases just like you do with the standard OutSystems entities.