OutSystems Integration Builder (O11) generates fully-typed integration modules for SAP OData, Salesforce, Microsoft Dataverse, SharePoint, and Dynamics 365 — no API code to write. For external databases (SQL Server, Oracle, MySQL, PostgreSQL), use Service Center → Database Connections. For ODC, Integration Builder is not available — use External Libraries (C# .NET 8 SDK) or direct REST API consumption instead.
Pre-Built Connectors vs Custom REST Integration
Writing REST API integration code from scratch takes time and expertise. OutSystems provides Integration Builder — a visual tool that connects to enterprise systems via their standard APIs (SAP OData, Salesforce REST, Microsoft Dataverse) and generates a fully-typed OutSystems module with ready-to-use Server Actions. For database-level integrations, Service Center provides direct external database connections. And the Forge marketplace offers community and supported connectors for hundreds of SaaS platforms. This tutorial covers when to use each approach and how to set them up correctly.
Prerequisites
- OutSystems 11 environment with access to Integration Builder (integrationbuilder.outsystems.com)
- Credentials for the target system (SAP client credentials, Salesforce Connected App credentials, Microsoft Azure app registration, or external database connection string)
- Service Studio installed and connected to your O11 environment
- For Forge components: Service Studio → Forge marketplace access
Step-by-step guide
Understand which connector approach to use
Understand which connector approach to use
Choose the right tool based on what you need to integrate: Integration Builder (O11 only, recommended for enterprise systems): - Salesforce: bidirectional CRUD, Apex triggers, bulk API - SAP OData: S/4HANA entities, standard OData operations - Microsoft Dataverse: Dynamics 365, Power Platform entities - SharePoint: lists, libraries, files - Dynamics 365: sales, service, finance entities - Use when: the target system is in the supported list AND you want generated, type-safe code External Databases (O11 and ODC with limitations): - Direct table/view access via JDBC - SQL Server, Oracle, MySQL, PostgreSQL, IBM Db2 - Use when: you need direct database access, not an API layer Forge Marketplace connectors: - OpenAI/ChatGPT, Stripe, Twilio, Slack, Google services, AWS, JIRA, Zendesk - Community-maintained (verify quality ratings and last update date) - Use when: Integration Builder doesn't cover the platform Custom REST consumption (always available): - Any REST API not covered above - Use the outsystems-rest-api-consume approach ODC approach: No Integration Builder, no external databases. Use External Libraries (C# .NET 8) for complex integrations, or direct REST API consumption for standard API-based integrations.
Expected result: You have selected the appropriate connector approach for your specific integration target.
Set up a Salesforce integration with Integration Builder
Set up a Salesforce integration with Integration Builder
Integration Builder is a web-based tool at integrationbuilder.outsystems.com — separate from Service Studio. 1. Go to integrationbuilder.outsystems.com → log in with your OutSystems credentials 2. Click New Integration → select Salesforce 3. Authenticate: enter your Salesforce Connected App Client ID and Client Secret (create one in Salesforce Setup → App Manager → New Connected App) 4. Select which Salesforce objects to generate actions for (e.g., Account, Contact, Opportunity, Case) 5. Choose which CRUD operations to expose: Get by Id, Get All, Create, Update, Delete, Search 6. Click Save and Publish → Integration Builder deploys a new module to your O11 environment In Service Studio: 7. Module → Manage Dependencies (Ctrl+Q) → find the generated Salesforce module (named SalesforceIntegration or similar) 8. Import the Server Actions you need (e.g., Account_GetById, Account_Create, Contact_Search) 9. Call these actions from your own Server Actions like any other OutSystems action The generated module handles OAuth2 token management, Salesforce API versioning, and error translation automatically.
Expected result: The Salesforce integration module is available in Service Studio. Account_GetById and similar actions appear in Manage Dependencies and can be called from your application logic.
Set up a SAP OData integration with Integration Builder
Set up a SAP OData integration with Integration Builder
SAP is the most common enterprise integration in OutSystems deployments. 1. Integration Builder → New Integration → SAP OData 2. Enter SAP system details: - OData Service URL: https://your-sap-host:port/sap/opu/odata/sap/API_BUSINESS_PARTNER - Authentication: Basic (SAP username/password) or OAuth2 (SAP OAuth server) 3. Integration Builder reads the OData metadata ($metadata endpoint) and lists available entity sets 4. Select entity sets (e.g., A_BusinessPartner, A_Customer, A_SalesOrder) 5. Select operations per entity: Read, Create, Update, Delete 6. Publish to your OutSystems environment Credential storage: Integration Builder stores SAP credentials encrypted. In Service Studio, the generated module reads credentials from Site Properties — set production values in Service Center without redeploying. Key SAP OData features supported by Integration Builder: - $filter, $orderby, $top, $skip query options (mapped to OutSystems aggregate-like parameters) - Expand navigation properties (related entities) - Batch operations for performance - SAP error message parsing (SAP OData errors are inside the 2xx response body)
Expected result: The SAP integration module is deployed. SalesOrder_GetById and similar actions are available in Service Studio.
Connect to an external database via Service Center
Connect to an external database via Service Center
For direct database access (when the system doesn't expose an API): Step 1 — Create the database connection in Service Center: 1. Open Service Center: https://yourserver/ServiceCenter 2. Navigate to Administration → Database Connections → Create New Connection 3. Fill in: Name (e.g., LegacyERP_DB), DBMS (SQL Server, Oracle, MySQL, PostgreSQL, DB2), Server, Database/Schema, Username, Password 4. Click Test Connection — must show "Connection successful" 5. Click Create Step 2 — Create the integration extension in Integration Studio: 1. Open Integration Studio (separate tool, installed alongside Service Studio) 2. File → New Extension → name it LegacyERP_Extension 3. Click Connect to External Table/View 4. Select the database connection created in Service Center 5. Browse the tables/views → select the ones you need 6. Click Import → Integration Studio generates OutSystems Entity elements mapping to the external tables 7. 1-Click Publish the extension Step 3 — Use in Service Studio: 1. Module → Manage Dependencies (Ctrl+Q) → find LegacyERP_Extension 2. Import the generated entity and actions 3. Use them exactly like internal OutSystems entities (they appear in Aggregates as sources) External database entities support all standard entity operations: GetById, Create, Update, Delete, and inclusion in Aggregates.
Expected result: External database tables appear in Service Studio as entities. You can query them with Aggregates and perform CRUD operations using the generated entity actions.
Install and configure a Forge connector for SaaS platforms
Install and configure a Forge connector for SaaS platforms
The OutSystems Forge marketplace (forge.outsystems.com) has connectors for Stripe, Slack, Twilio, OpenAI, JIRA, Google APIs, AWS services, and hundreds more. Install a Forge component: 1. In Service Studio, go to the Forge tab (bookshelf icon in the top-left toolbar) OR visit forge.outsystems.com 2. Search for the platform (e.g., "Stripe" or "Slack") 3. Review: Quality rating, last update date, author (OutSystems-supported vs community), compatibility (O11/ODC badge) 4. Click Install → select your environment → Install 5. After installation, the component module appears in your environment Configure credentials: 1. Module → Manage Dependencies (Ctrl+Q) → import the Forge component's Server Actions and Structures 2. Most Forge connectors use Site Properties for API keys — set them in Service Center → Factory → [ForgeModule] → Site Properties Example for Stripe Forge connector: - Import: Charge_Create, Customer_Create, PaymentIntent_Create actions - Set Site Properties: Stripe.SecretKey = "sk_live_..." - Call from your Server Actions like any native action Forge quality guidance: prefer connectors with the 'Supported' badge (maintained by OutSystems), green quality shield, 4+ stars, and updated within the last 12 months.
Expected result: The Forge connector is installed and its actions are available in your module via Manage Dependencies. API credentials are configured in Site Properties.
Implement the ODC approach to external integrations
Implement the ODC approach to external integrations
ODC does not support Integration Builder or external database connections. The two ODC-compatible patterns are: Pattern A — Direct REST consumption (for API-based integrations): Use the standard REST API consume workflow in ODC Studio (Logic tab → Integrations → REST → right-click → Consume REST API). Salesforce, SAP Cloud, Dataverse all have REST APIs — consume them directly. Store credentials in Secret Settings (ODC Portal → App → Settings → Secret Settings). Pattern B — External Libraries (for complex integrations, binary protocols, or non-standard formats): 1. Create a C# .NET 8 class library project 2. Reference the OutSystems.ExternalLibraries.SDK NuGet package 3. Implement your integration logic (call SAP RFC, parse custom binary formats, etc.) 4. Annotate methods with [OSAction] attribute to expose them as OutSystems actions 5. Build and zip the project 6. Upload in ODC Portal → [App] → External Logic → Upload 7. The actions are then available in ODC Studio as Server Actions External Libraries run on AWS Lambda (isolated from the app container), support any .NET library, and are versioned independently from the app. This replaces both Integration Studio and external database connections from O11.
Expected result: External integrations work in ODC through either direct REST consumption or External Libraries deployed through ODC Portal.
Organize integration modules in the 4-Layer Canvas architecture
Organize integration modules in the 4-Layer Canvas architecture
Regardless of which connector type you use, follow the OutSystems 4-Layer Canvas architecture to keep integrations maintainable: Foundation Layer (bottom): - Integration Builder generated modules live here - External Library wrapper modules live here - Forge connector modules live here - These are never modified directly — only updated via their source tool Core Layer: - Create a wrapper/service module (e.g., SalesforceService_CS) that imports Foundation Layer actions - Add business logic on top: validation, error translation, caching, logging - Expose only the actions your application layers need End-User Layer (top): - Screens and UI modules call Core Layer services - Never import Integration Builder actions directly into UI modules Benefit: if Salesforce changes their API and you update the Foundation module, only the Core Layer wrapper module needs adjustment — not every UI module in your application.
Expected result: Integration dependencies follow the 4-Layer Canvas pattern. Architecture violations are not flagged by AI Mentor Studio or TrueChange.
Complete working example
1/* Core Layer Server Action: GetAccountWithContacts2 Module: CRM_Core_Services (Core layer module)3 Dependencies: SalesforceIntegration (Foundation layer — Integration Builder generated)4 Input: AccountId (Text)5 Output: Account (SalesforceAccount structure), Contacts (List of SalesforceContact), IsSuccess (Boolean), ErrorMessage (Text)6*/78Start9 |10 v11[If] Length(Trim(AccountId)) = 012 |13 True -->14 [Assign] IsSuccess = False, ErrorMessage = "AccountId is required."15 v16 End17 |18 False -->19 v20[Account_GetById] -- Foundation layer action from SalesforceIntegration module21 Id = AccountId22 |23 v24[If] Account_GetById.IsSuccess = False25 |26 True -->27 [LogError]28 Module = "CRM_Core_Services"29 Message = "Salesforce Account_GetById failed: " + Account_GetById.ErrorMessage30 [Assign] IsSuccess = False, ErrorMessage = "Unable to load account. Please try again."31 v32 End33 |34 False -->35 v36[Contact_Search] -- Foundation layer action37 Filter = "AccountId = '" + AccountId + "'"38 MaxResults = 5039 |40 v41[Assign]42 Account = Account_GetById.Account43 Contacts = Contact_Search.Results44 IsSuccess = True45 ErrorMessage = ""46 |47 v48End4950[Exception Handler: Communication Exception]51 |52 v53[LogError] Message = "Salesforce connectivity failure", Detail = CommException.ExceptionMessage54[Assign] IsSuccess = False, ErrorMessage = "CRM service temporarily unavailable."55 |56 v57EndCommon mistakes
Why it's a problem: Referencing Integration Builder or Forge connector actions directly from UI (End-User layer) modules
How to avoid: Create a Core layer service module that wraps the Foundation layer connector. UI modules import from the Core layer only. This isolates UI modules from Foundation layer changes and keeps the architecture maintainable as the integration evolves.
Why it's a problem: Using Integration Builder in an ODC project
How to avoid: Integration Builder is O11-only. In ODC, use direct REST API consumption (Logic tab → Integrations → REST → Consume REST API) for Salesforce, SAP Cloud, and Dataverse — all of which have REST APIs. For complex integrations requiring SDK access, use External Libraries with the OutSystems.ExternalLibraries.SDK.
Why it's a problem: Connecting to an external database using a database admin account with full read/write/DDL permissions
How to avoid: Create a dedicated read-only or application-specific database user with only the permissions needed. Full admin credentials in Service Center database connections are a security risk — if the OutSystems connection string is ever exposed, it gives attackers full database access.
Why it's a problem: Installing multiple Forge connectors for the same platform without evaluating which is best maintained
How to avoid: Search Forge for a platform and you may find 3-5 connectors. Filter by: Supported badge (OutSystems-maintained), quality shield color (green = good), last updated date (within 12 months), and active issue/comment activity. Installing an abandoned Forge connector ties your production app to unmaintained code.
Best practices
- Always place Integration Builder-generated modules and Forge connectors in the Foundation layer of the 4-Layer Canvas — never reference them directly from UI modules.
- Create a Core layer wrapper module for each external integration to add business-layer error handling, logging, caching, and interface stability against external API changes.
- Test Forge components in a Development environment before installing in production — review the component's dependency list, quality shield rating, and last update date.
- For external database connections, create read-only database user accounts with only SELECT permissions when you only need to query data — follow the principle of least privilege.
- Cache frequently-accessed external system data (Salesforce lookup fields, SAP configuration data) in OutSystems entities with a TTL to reduce API call volume and improve response times.
- Store all external system credentials in Site Properties (O11, marked as Secret) or Secret Settings (ODC) — never in code, Forge component default values, or exported module files.
- When using Integration Builder-generated modules, re-generate the integration when the external system publishes a new API version rather than manually modifying the generated code.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I'm building an OutSystems 11 application that needs to sync customer data between OutSystems and Salesforce. The integration needs to: 1) fetch Account and Contact records from Salesforce by AccountId, 2) create new Leads in Salesforce when users register in OutSystems, 3) handle Salesforce API rate limits (daily limit 150,000 requests). Using Integration Builder's generated module as the Foundation layer, help me design the Core layer wrapper module with proper caching, rate limit tracking, and error handling.
I need to connect my OutSystems 11 module to a legacy SQL Server database that contains an Orders table (OrderId, CustomerId, OrderDate, TotalAmount, Status) and OrderLine table (LineId, OrderId, ProductCode, Quantity, UnitPrice). After creating the external database connection in Service Center and importing the tables via Integration Studio, write the OutSystems Aggregate and Server Action logic to: fetch the last 30 days of orders for a specific customer with their line items, using OutSystems join syntax (Only With / With or Without).
Frequently asked questions
Does Integration Builder support bidirectional data sync, or only read operations?
Integration Builder generates both read and write operations. For Salesforce, it creates Get (by ID), GetAll (with filters), Create, Update, Delete, and Search actions. For SAP OData, it generates Read, Create, Update, and Delete operations based on which are enabled in the OData service metadata. The generated module handles all API serialization, authentication token management, and error translation — you just call the actions.
Can I query an external database table in an OutSystems Aggregate the same way I query internal entities?
Yes. After importing external tables via Integration Studio and referencing them in Service Studio via Manage Dependencies, the external entities appear as sources in the Aggregate editor just like internal entities. You can add them, apply filters, join them with internal entities (with important caveats — cross-database joins require all entities to be in the same database catalog, otherwise you get the 'aggregate cannot join data from multiple databases' error).
What is the difference between Integration Builder and Integration Studio in OutSystems?
Integration Builder is the newer, web-based tool (integrationbuilder.outsystems.com) for generating ready-to-use modules for Salesforce, SAP, Dataverse, and SharePoint. It requires no coding. Integration Studio is the older desktop tool used for creating .NET code extensions (.xif files) — used for external databases, custom C# logic, and advanced SOAP integrations. Integration Builder uses Integration Studio internally for some generated code, but you interact only with Integration Builder's GUI.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation