---
description: Syncs data to Salesforce in real-time
---

# Salesforce

### I. Integration configuration

#### Install Salesforce CRM Package

You can initiate the installation process **by clicking on the provided link**, which will direct you to the installation\
page where you can follow step-by-step instructions for a seamless integration. If you have any questions or need assistance\
during the installation, our dedicated support team is here to help you every step of the way.

To ensure a successful installation, please follow these steps:

1. We recommend selecting the **"Install for all users"** option;
2. Click on the **"Install" button**;
3. Make sure to **check the box to grant access to these third-party websites**; and
4. Once completed, you'll have **successfully installed** the Swallow Salesforce App.

Please note that the installation process may take a few minutes to complete. However, rest assured that you will receive an email confirmation once the installation is finished.

#### Webhook config: sync real-time data

To set up the webhook URL for real-time data syncing between Swallow and Salesforce, follow these steps:

1. Return to your newly created site.
2. Locate the **Custom URLs** section.
3. Copy the **domain name** (e.g., swallow.my.salesforce-sites.com).
4. Add the `https://` prefix to this domain name (e.g., `https://swallow.my.salesforce-sites.com`).
5. Append `/services/apexrest/swallow/api/Webhooks/incoming/pushDetails/` to the domain name (e.g., `https://swallow.my.salesforce-sites.com/services/apexrest/swallow/api/Webhooks/incoming/pushDetails/`).

To edit Public Access Settings for your new site:

1. Visit the site and click **Public Access Settings**.
2. In the **Enabled Apex Class Access** section, click "edit."
3. Add `SwallowWebHookSubscriptionController` to **Enabled Apex Classes**.
4. Save your changes.

When creating a new site, follow these steps:

1. Set a unique **Site Label**.
2. Specify a unique **Site Name**.
3. Optionally, add a **Site Description**.
4. Ensure the **Site Contact** and **Default Record Owner** are filled.
5. Set the **Default Web Address** prefix to `getPushNotification`.
6. Choose `SiteLogin` as the **Active Site Home Page**.
7. Don't forget to **save the new site**.
8. **Activate the newly created site** by going to the Site Details and clicking the `Activate` button.
9. Click the gear icon in the upper right to access **Salesforce Setup**.
10. Search and navigate to the Sites section.
11. Create a new Site.

After installation in Salesforce CRM, set up a webhook URL in Salesforce to receive real-time data from Swallow. This involves **configuring a new "Site" in Salesforce's setup section**. Note that the four main actions described below should be performed by a Salesforce Admin and are only required during the initial setup.



Now, go to your Swallow app and paste this webhook into the webhook's settings:

<figure><img src="https://1110149073-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu89vYHjuY9Vj4vhZX5IZ%2Fuploads%2FP6vxxJXfHSmHt7WPlRko%2Fimage.png?alt=media&#x26;token=4ce6799f-5ec2-40ef-bf00-df5e8e91ff60" alt=""><figcaption></figcaption></figure>

1. Within Swallow, navigate to **Settings**;
2. Visit the **Webhooks** page
3. Paste your Salesforce webhook URL
4. Save this webhook endpoint.

Congratulations! You're ready to sync real-time data from Swallow to Salesforce!

**Option 1: Configure a standard API Base URL**\
To establish a connection between your Swallow instance and the Salesforce Package, follow these steps:

1. Access Salesforce and locate the **App Launcher**;
2. Find and open the Swallow app you recently installed;
3. Within the Swallow Base Configuration tab:

* Provide your **Swallow API Key** (located in Swallow's Developer Section)
* Enter your Swallow **API base URL**. `https://api.llow.io/sw/`.
* Enter Swallow app URL (**Front End Base URL**). By default, the valid URL is `https://app.llow.io/` (it will be different for self-hosted).

4. **"Save and validate"** your connection; and

* If the **Swallow API Key** is valid then only **Start Data Sync** button will be enabled.

5. Click the **"Start Data Sync"** to finalize the connection between Swallow and Salesforce.

Please note that data synchronization is available only for Swallow customers with an \`external\_salesforce\_id\` and an existing Salesforce Account.

**Option 2: Configure a custom API Base URL**\
If you use your own Swallow API base URL (self-hosting) or one for a different server instance,\
you can customize it directly in Salesforce:

1. Navigate to Salesforce's Setup;
2. Search for and select Remote Site Settings;
3. Find and access the remote site for the Swallow App;
4. Click the Edit button to modify the remote site's details;
5. Update the Remote Site URL with your preferred URL; and
6. Save the changes.

### II. Sync data from Swallow to Salesforce

If your webhook endpoint is configured correctly, your **billing data will flow seamlessly in real-time**.

Please note that Subscriptions and Invoices will be created in Salesforce via webhooks seamlessly

#### Sync customers to Salesforce

To synchronize Swallow Customer data with Salesforce Accounts (native object), ensure that your\
Salesforce Account is created first, and that the Swallow Customer's `external_salesforce_id` is explicitly populated.

1. Begin by creating a new Account in Salesforce or accessing an existing one;
2. Next, create a customer in Swallow and populate the `external_salesforce_id` field for a Swallow Customer with the Salesforce Account Id; and
3. Finally, your Salesforce Account and Swallow Customer are synchronized!

Billing data will not sync unless these requirements are met. Swallow does not create Salesforce Accounts. Before syncing billing data, you need to create or retrieve an existing Account in Salesforce and populate the Swallow customer field called \`external\_salesforce\_id\`.

#### Sync subscriptions to Salesforce

Whenever a subscription is created for a Swallow Customer, the subscription details will be automatically\
synced in real-time with Salesforce using the `Swallow Subscriptions` custom object.

Here is a list of Subscription fields that are automatically synced.\
Note that this subscription is automatically linked to a Salesforce Account:

* Subscription Id;
* Subscription Name;
* Subscription Start Date;
* Subscription Status;
* Subscription Termination Date (synced when the subscription is terminated);
* Subscription Billing Time (either `calendar` or `anniversary`); and
* Plan Code.

#### Sync invoices to Salesforce

Whenever an invoice is issued for a Swallow Customer, the invoice details will be automatically\
synced in real-time with Salesforce using the `Swallow Invoices` custom object.

Here is a list of Subscription fields that are automatically synced:

* Invoices Number;
* Invoice Payment Status;
* Invoice Type (`subscription` or `one-off`);
* Invoice Issuing Date;
* Invoice Amount;
* Invoice File Url; and
* Invoice Currency.

#### Sync credit notes to Salesforce

Whenever a credit note is issued for a Swallow Invoice, the credit note details will be automatically\
synced in real-time with Salesforce using the `Swallow CreditNotes` custom object.

#### Sync Plans, Add-Ons to Salesforce

Plans and Add-ons are synced to Salesforce when we initially click on **Start Data Sync** from Swallow Base Configuration page.

* Plans are synced to `Swallow Plans` object and `Product2` standard object. We also create a _price book entry_ for all the products in `Standard Price Book` price book
* Add-Ons are synced to `Swallow Add-Ons` object and `Product2` standard object. We also create a _price book entry_ for all the products in `Standard Price Book` price book.

#### Schedule Sync from Swallow To Salesforce

We also provide option to schedule the data sync from Swallow to Salesforce.

* `SwallowSyncScheduleable` -- a schedulable class which helps us schedule either all the data or any one of them.
* To schedule the sync of any _ONE_ of the object:
  * Create a new instance of class by passing any one of the following string: `CUSTOMER`, `SUBSCRIPTION`, `PLAN`, `ADDON`, `INVOICE`, `CREDITNOTE`
    *   Ex: To sync Plans from Swallow to Salesforce everyday at 1PM, execute below anonymous code in Anonymous window in Developer Console. ([click here to learn more about CRON expression](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_scheduler.htm))

        ```
        //Create a new instance. Pass 'PLAN' in brackets.  
        swallow.SwallowSyncScheduleable syncPlan = new swallow.SwallowSyncScheduleable('PLAN');  
        //CRON expression to schedule a job everyday at 1 PM  
        String schedule_cron = '0 0 13 * * ?';  
        //schedule(name, cron_expression, class_instance)  
        System.schedule('Sync Swallow Plan', schedule_cron, syncPlan);  
        ```
* To schedule the sync of _ALL_ the objects:
  * create a new instance of class by passing `true`
    *   Ex: To sync **all** objects from Swallow to Salesforce everyday at 1PM, execute below anonymous code in Anonymous window in Developer Console. ([click here to learn more about CRON expression](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_scheduler.htm))

        ```
        //Create a new instance. Pass true in brackets.  
        swallow.SwallowSyncScheduleable syncAll = new swallow.SwallowSyncScheduleable(true);  
        //CRON expression to schedule a job everyday at 1 PM  
        String schedule_cron = '0 0 13 * * ?';  
        //schedule(name, cron_expression, class_instance)  
        System.schedule('Sync Swallow all', schedule_cron, syncAll);  
        ```

### III. Actions from Salesforce to Swallow

Beyond just syncing data from Swallow to Salesforce, you can also initiate actions in Swallow directly from Salesforce.\
You can leverage Salesforce `Flows` to execute actions in Swallow. Swallow provides several customizable templates for creating customers from Salesforce Accounts, directly assigning subscriptions to customers from Salesforce, creating one-off invoice from salesforce.

#### Create customers

**Flow: `Swallow Template - Create Customer in Swallow on Account Create`**

To create a customer in Swallow upon the creation of a Salesforce Account, utilize the Flow template provided by Swallow.

1. Log into your Salesforce instance;
2. Access the Setup section via the settings wheel icon in Salesforce;
3. Find and select `Flows` under Process Automation in the sidebar;
4. Locate and open the `Swallow Template - Create Customer in Swallow on Account Create`;
5. Click 'Save As' to create and save your own version of the template; and
6. Do not forget to click the `Activate` button to activate your flow.

You have the **flexibility to modify various aspects of this flow, including the trigger conditions and field mappings**.\
By default, the action is initiated when a Swallow ID is absent. Additionally, you can customize how fields are mapped from your Salesforce instance to Swallow.

#### Create subscriptions (automation)

Assigning a plan to a customer, adjusting negotiated prices, and initiating the subscription upon winning an opportunity represents a key action from Salesforce to Swallow.\
This enables sales teams to remain within Salesforce, their primary tool, and activate billing processes directly, without the need to switch platforms.

To assign a subscription and set prices in Swallow directly from Salesforce, use the provided two flows via following Swallow Flow templates.

**Swallow Template - Create Swallow SObject Records**

This Flow is used to create intermediate records in Swallow Objects - `Swallow Subscription`

1. Log into your Salesforce instance;
2. Access the Setup section via the settings gear icon in Salesforce;
3. Find and select `Flows` under Process Automation in the sidebar;
4. Locate and open the `Swallow Template - Create Swallow SObject Records`;
5. Click 'Save As' to create and save your own version of the template; and
6. Do not forget to click the `Activate` button to activate your flow.

The default setting triggers plan assignment when a Salesforce Account links to a Swallow customer and the opportunity status changes to closed-won. You can customize this flow to suit your specific needs. Moreover, you have the option to adjust the subscription fields and subscription charge fields being synchronized from Salesforce to Swallow.

1. Create an opportunity by assigning an expected close date and a stage.
2. Add a Swallow plan to this opportunity as a product (Salesforce will automatically retrieve all plans from Swallow in the `Standard Price Book`).
3. Specify `1` as the quantity for the plan.
4. You can override the default price if needed.
5. Add any Swallow add-ons to this opportunity as additional products.
6. Set the opportunity status to "Closed Won."
7. Save the opportunity.

Once the opportunity is saved with a "Closed Won" status, the flow will automatically trigger and create a Swallow Subscription record in Salesforce. You can

1. Navigating to the related Account;
2. Checking the "Swallow Subscriptions" related list; and
3. Confirming that a new Swallow Subscription record has been created.







































































