# Creating Integrations on Truto > Source: https://truto.one/docs/guides/integrations/creating-integrations/ ## Overview Truto allows you to install pre-built integrations or create custom ones tailored to your needs. This step-by-step guide will walk you through creating an integration on Truto, using Salesforce as an example to make it easy to follow. ## Adding a New Integration 1. **Navigate to the Catalog** Start by going to the `Catalog` section and clicking the `Create Integration` button. ![Create Integration](https://docs-assets.truto.one/create-integrations.png) 2. **Open the Create Integration Page** Clicking the button takes you to the `Create Integration` page where you’ll configure all details. ![Integration Landing Page](https://docs-assets.truto.one/creating-integrations.png) ## Step-by-Step Integration Creation ### Step 1: Adding Basic Details In the **Basic Details** section, you'll enter foundational information about the integration. #### Crucial Fields: - **Label**: The name of your integration. This will be visible in the catalog (e.g., “Salesforce”). - **Identifier**: A unique code that makes your integration different from others and helps with OAuth callbacks. This will be used in the OAuth callbacks, [Link SDK](/docs/guides/link-sdk/how-to-embed), Unified Model Mapping. #### Optional Fields: - **Category**: Categorize your integration to make it easy to find. - **Logo & Icon**: These help visually represent the integration. This is used in the Truto Connection UI. - **Is Beta?**: Check this if the integration is still in testing. For our Salesforce example, these details might look like this: ![Salesforce Basic Details](https://docs-assets.truto.one/salesforce-integration-basic.png) --- ### Step 2: Configuring Authentication and Variables **Authentication** is how you securely connect your integration to an external service like Salesforce. Depending on the authentication type you choose, the **Variables** section adjusts to collect the necessary inputs. #### Authentication Options 1. **OAuth 2.0 Authorization**: - **What it is**: Users log in through the external service to grant access. - **Why use it**: Secure and easy to manage; it’s the recommended way. 2. **API Key Authentication**: - **What it is**: Users provide an API key, similar to a password. - **Why use it**: Simple but less secure compared to OAuth. 3. **Keka OAuth Authentication**: - **What it is**: A specific OAuth type used only for Keka integrations. 4. **OAuth 2.0 Client Credentials Flow**: - **What it is**: A server-to-server way to authenticate, used when users don't need to log in. - **Why use it**: Ideal for backend services. #### Salesforce Example: OAuth 2.0 Authorization For Salesforce, **OAuth 2.0 Authorization** is used. Here’s what the configuration looks like: ![Salesforce OAuth](https://docs-assets.truto.one/salesforce-integration-oauth.png). Also, refer to our blog on [Creating an OAuth App on Salesforce](https://truto.one/blog/integrate-salesforce) - **Redirect URL**: This URL tells Salesforce where to send users after logging in (`https://api.truto.one/connect/salesforce/callback`). You must add this to your Salesforce OAuth app settings. - **Client ID and Client Secret**: Think of these as the “username” and “password” for Salesforce. You get these values when you create the OAuth app in Salesforce. - **Authorization Host and Path**: These are provided by Salesforce and indicate where users log in to give you access. - **Token Host and Path**: This URL is used to get the access token that allows you to make API calls on behalf of the user. These are provided by Salesforce in their documentation. Read more on [Authentication](/docs/guides/integrations/configuration-reference#authentication) --- #### Variables Section **Variables** let you add specific information needed for your integration, like a `subdomain` or `client_id`. This makes the integration reusable for each user. This section gets enabled after an authentication is selected. For instance, if Salesforce uses a unique subdomain for each customer, you can use a **variable** (`subdomain`) in the **Base URL** instead of hardcoding it. This way, every customer can provide their own subdomain when they connect their Salesforce account. ![Integration Variables Screenshots](https://docs-assets.truto.one/integration-variables-oauth.png) For Salesforce, we use a variable called `subdomain`: ![Salesforce OAuth Variables](https://docs-assets.truto.one/salesforce-oauth-variables.png) Read more on [Variables](/docs/guides/integrations/configuration-reference#variables) --- #### Token Details Towards the end of the **Authentication** section, fill in additional token details based on Salesforce’s documentation. ![Salesforce OAuth Tokens](https://docs-assets.truto.one/oauth-salesforce-token.png) --- ### Step 3: Authorization Options With Salesforce, the **Bearer Token** is used to authorize every API request. Essentially, the access token needs to be added to each request like this: ``` Authorization: Bearer {{access_token}} ``` Truto automatically includes this token to make sure that Salesforce knows you’re authorized to access the data. Select the format as mentioned in the documentation. Here’s how it looks: ![Salesforce Authorization](https://docs-assets.truto.one/salesforce-authorization-integration.png) Read more on [Authorization](/docs/guides/integrations/configuration-reference#authorization) --- ### Step 4: Configuring Base URL and Headers The **Base URL** and **Headers** sections define how API requests will be sent to Salesforce (or any other system). #### Base URL The **Base URL** is like the home address for all API calls. For Salesforce, it looks like this: ``` https://{{subdomain}}.my.salesforce.com ``` - **Subdomain**: This variable (`subdomain`) is provided by the user during account connection and makes sure that each request reaches the correct Salesforce environment. #### Headers ![Base URL & Headers](https://docs-assets.truto.one/salesforce-base-url-integration.png) Read more on [Base URL and Headers](/docs/guides/integrations/configuration-reference#base-url-and-headers) --- ### Step 5: Configuring Query Parameters The **Query Parameters** section lets you add specific key-value pairs to your API request URLs. These parameters help customize what data you’re getting from the API. Click on the format supported and add the query parameters. For example, you could add: - **`filter`**: To filter the results (e.g., get only active accounts). - **`sort`**: To sort the data in a particular order. - **`limit`**: To limit the number of records returned. These parameters make the API requests more specific and useful. ![Salesforce Query Parameters](https://docs-assets.truto.one/salesforce-query-integration.png) **Note**: These query parameters are included in every API request unless you set different ones for a specific resource in the `Resources` section. Read more on [Query Parameters](/docs/guides/integrations/configuration-reference#query-parameters) --- ### Step 6: Configuring Pagination Some APIs limit how much data they return in a single response. **Pagination** allows you to get all the data in smaller chunks or pages. #### Salesforce Example for Pagination For Salesforce, you set up pagination by defining: - **Cursor Path**: Salesforce uses `nextRecordsUrl` to show where the next page of data is. - **Is Cursor Link**: This is checked because `nextRecordsUrl` is a full link. - **Use Path from Cursor Link**: Salesforce provides a link, so Truto uses that path for the next request. ![Salesforce Pagination Setup](https://docs-assets.truto.one/pagination-salesforce-integration.png) This setup makes sure that your integration can handle large amounts of data in manageable pages. Read more on [Pagination](/docs/guides/integrations/configuration-reference#pagination) --- ### Step 7: Configuring Rate Limiting APIs often limit how many requests you can make within a given timeframe. **Rate Limiting** lets you handle these limits without getting blocked by the API. #### Truto’s Default Values Truto automatically handles rate limits if the response status code is `429` (Too Many Requests). Truto also looks for a `Retry-After` header to determine how long to wait before retrying. You can configure this with JSONata expressions, but Truto’s default settings work well for most cases. ![Salesforce Rate Limit](https://docs-assets.truto.one/rate-limit-salesforce-integration.png) This ensures that your integration stays compliant with the API’s rate limits, preventing disruptions. Read more on [Rate Limiting](/docs/guides/integrations/configuration-reference#rate-limiting) --- ### Step 8: Setting Up Resources The **Resources** section is where you define the core data you want to work with, like **accounts**. You also specify what operations you can perform on this data, such as listing accounts, retrieving a single account, creating, or updating an account. You can add multiple resources in an Integration. Truto uses the **CRUD** model (Create, Read, Update, Delete) to define resources - which means that we try convert the underlying product's API into CRUD APIs. ### Key Elements of Resources: 1. **Resource Name**: This is the type of data you’re working with (e.g., `accounts`). 2. **Method (Operations)**: Define actions such as: - **List**: Fetch all records (`GET /services/data/v57.0/query`). - **Retrieve**: Get a single record by ID (`GET /services/data/v57.0/sobjects/Account/{{id}}`). - **Create**: Add a new record (`POST /services/data/v57.0/sobjects/Account`). - **Update**: Modify an existing record (`PATCH /services/data/v57.0/sobjects/Account/{{id}}`). 3. **Path**: The API endpoint for each method. For Salesforce, it might be something like `/services/data/v57.0/query`. The **SOQL endpoint** is called for the list method and for other methods, the REST APIs are called. 4. **Response Path**: Salesforce returns account data inside an object called `records`. This path helps Truto understand where to find the list of accounts in the response. 5. **Query Parameters**: Add any queries that help you refine or filter your data. These **Query Parameters** are included in every API request. If you add **Query Parameters** for a specific resource, they will be combined with the global ones defined in the `Query Parameters`. ![Salesforce Accounts Resource](https://docs-assets.truto.one/salesforcer-resources-integration.png) This setup ensures your integration knows what data to interact with and what actions to perform on it. Read more on Resources [here](/docs/guides/integrations/configuration-reference#resources) --- ### Step 9: Setting Up Actions **Actions** are automated tasks that run after an account is connected. Think of them as pre-set instructions your integration follows. #### General Steps for Actions: 1. **Get Context**: Gather information 2. **Transform**: Use this information to make changes or add context (e.g., format the subdomain into a label). Use a **JSOnata** transformation expression. 3. **Update Context**: Save this transformed information for use across the integration. For Salesforce, after connecting a user’s account: 1. **Get Context**: Retrieve the Salesforce subdomain that the user provides. 2. **Transform**: Create a label for the integrated account, using the subdomain. 3. **Update Context**: Save this label for later use. These steps make sure the integration runs smoothly and users can easily identify their connected accounts. ![Salesforce Actions](https://docs-assets.truto.one/salesforce-post-install.png) Once the Integrated Account is connected for a user, this is how the label shows up in the Integrated Account - ![Salesforce Integrate Account Label](https://docs-assets.truto.one/salesforce-integration-label.png) Read more on Actions [here](/docs/guides/integrations/configuration-reference#actions) If you need further assistance, refer to the [Configuration References](/docs/guides/integrations/configuration-reference) for additional guidance.