Connecting Salesforce to Ionic

Overview

Ionic connects to Salesforce through “Ionic by DemandScience” - an External Client App (Salesforce’s term for this kind of integration app) that DemandScience owns and maintains, and that gets installed directly into your Salesforce org. Once it’s installed, its OAuth policies are configured, and you complete a one-time login approval, Ionic can securely read the CRM records it needs - Accounts, Contacts, Leads, Opportunities, and a few related objects - and keep them in sync going forward.

Today, this connection is read-only: Ionic pulls data from Salesforce but does not write anything back. Write-back is planned but not yet available.

Rule of thumb: No package, no connection. The package has to be installed and its policies configured in Salesforce before the connection will succeed. The Ionic setup wizard walks you to the install link directly - you don’t have to go find it separately.

Here’s what’s actually involved, piece by piece:

• The External Client App (“Ionic by DemandScience”) - a Salesforce app, owned and maintained by DemandScience, that you install into your org. It’s what makes the connection possible; nothing else has to be built on the Salesforce side beyond installing it and setting its policies.
• The OAuth Connection - the secure, authorized login that lets Ionic talk to your org after you approve it. This is the “Authorize” half of the Connect step.
• Field Mapping - by default, every supported object syncs automatically with its required fields (as long as the connected user has access to it). The Map Fields step is where you turn on optional standard fields and any custom fields you want included; it’s not required to get a baseline sync going.
• Filters (optional, Account only today) - simple “field equals value” filters that narrow which Account records sync (for example, only Accounts where Type = “Customer”). Only exact-match filters are supported today, with more robust filter logic (e.g. other objects, additional operators) planned.
• Cohort / Fiscal Year Setting (optional) - despite the name “Cohort” in the wizard, this step only sets which month your fiscal year starts, so pipeline and revenue reporting lines up with your company’s calendar. It is not a CRM segment or list mapping.
• The Sync - the ongoing process that keeps Ionic’s copy of your data current after you confirm and start it. Sync runs daily, and the first sync pulls the last 24 months (730 days) of history - both fixed today, not user-adjustable in the wizard.

Important: Ionic only reads the Salesforce data described below. It does not create, update, or delete records in your Salesforce org today - write-back is planned but not yet built.

Required Salesforce Permissions

The person (or dedicated integration account) who installs the package and completes the connection needs:

• API Enabled, required to use the Salesforce API at all.
• A Salesforce user license (for a real person completing this manually) or a Salesforce Integration license (if a dedicated API-only account is used instead).

Ionic also uses Salesforce’s change-tracking feature (Change Data Capture) to detect deleted records on five objects: Account, Contact, Lead, Opportunity, and Campaign Member (see Salesforce Objects & Fields Ionic Can Sync below for why it’s just those five). If that’s being configured, the installing user additionally needs:

• Author Apex
• Manage Profiles and Permission Sets
• Assign Permission Sets

The External Client App itself is pre-configured (by DemandScience) to request API access and persistent-refresh access; you don’t set those scopes yourself. What you do configure, in the next section, is how those permissions behave for your org (who can self-authorize, how long the connection stays valid without use, etc.).

Setting Up the Connection

1. Select Salesforce

In Ionic, go to Integrations → CRM, click Connect CRM, and choose Salesforce.

2. Connect - Install the Package (in Salesforce)

The Connect step opens showing an Install Package stage first. Ionic tells you plainly: “Your Salesforce admin needs to install a managed package before you can connect. This is a one-time setup per Salesforce org.” Click Install Salesforce Package - this opens the install flow in a new tab. The direct install link can be found here.

In that new tab (or via the link above):

1. Log in to your Salesforce org if prompted.
2. Choose Install for All Users.
3. Accept the terms and click Install.
4. Confirm it worked: in Salesforce Setup, search for Installed Packages and check that “Ionic by DemandScience” appears in the list.

3. Connect - Configure the OAuth Policies (in Salesforce)

This step isn’t shown inside the Ionic wizard; it’s a one-time policy setup you do directly in Salesforce Setup:

1. Search for External Client App Manager and open Ionic by DemandScience.
2. Go to the Policies tab and click Edit.
3. Under OAuth Policies, set Permitted Users to “All users may self-authorize.”
4. Under App Authorization, set:

• Refresh Token Policy → “Expire refresh token if not used for specific time”, with a Refresh Token Validity Period of 30 Days. (Salesforce enforces an idle-expiration limit here; “valid until revoked” is no longer an available option, even though some of Ampersand’s own published guides haven’t caught up to this change yet.)
• IP Relaxation → “Relax IP restrictions”

5. Click Save.

Also confirm the connecting user has access - see Required Salesforce Permissions above.

4. Connect - Authorize

Back in the Ionic wizard, move to the Authorize stage of the Connect step. Log in with the same Salesforce credentials used to install the package in Step 2, and approve the access request. Ionic confirms the connection and automatically moves you to the next step.

5. Map Your Fields

By default, every object listed below syncs automatically with its required fields, as long as the connected user has access to it; you don’t have to do anything here to get a baseline sync. This step is where you turn on optional standard fields and any custom fields you want included per object. Required fields are pre-mapped and can’t be turned off; custom fields load once authorization completes.

6. Filters (Optional, Account Records Only)

This step currently applies only to Account records; optionally narrow which Accounts sync using simple “field equals value” rules. This step is entirely skippable, and only exact-match (“equals”) logic is supported today, with more robust filtering planned.

7. Cohort - Fiscal Year (Optional)

Optionally set your fiscal year start month so Ionic’s quarter labels match your company’s calendar. This step is also skippable and defaults to a January (calendar-year) start.

8. Review & Start Sync

The last screen summarizes your setup: sync frequency, backfill period, objects synced, filters, and fiscal year start. Click Review & Start Sync, confirm in the dialog, then click Start Sync. Ionic begins pulling the last 24 months of history and keeps syncing daily from there.

Salesforce Objects & Fields Ionic Can Sync

Ionic supports syncing the following Salesforce objects. Required fields are the minimum needed for the object to sync usefully; optional fields can be turned on if you want that data in Ionic too.

A few things worth knowing:

• Amount and Annual Revenue can be remapped. If your org tracks deal value or company revenue in a different field, that gets handled in Ionic’s field-mapping step, not on the Salesforce side.
• Every object syncs its required fields by default, so you don’t need to map anything to get a baseline sync started, as long as the connected user has access to that object.
• Custom fields are supported. Beyond the standard fields above, most objects support mapping a number of your org’s custom fields as well (the exact number depends on the object).
• Deleted-record detection is limited to five objects (Account, Contact, Lead, Opportunity, Campaign Member) because Salesforce caps how many objects an org can watch for deletions. Deletions on the other objects above won’t automatically remove the record from Ionic. Setting this up needs a few extra permissions; see Required Salesforce Permissions above.
• Sync runs daily, and the initial sync covers the last 24 months. Both the sync frequency and the backfill window are fixed today and aren’t adjustable from the setup wizard.

Quick Do’s & Don’ts

Do:

• Install the package and configure its OAuth policies in Salesforce as soon as the wizard’s Connect step prompts you to; the wizard links you straight to the install flow.
• Use a user (or dedicated integration account) with API Enabled and the right license type.
• Come back to the field-mapping, filter, or fiscal-year settings any time to adjust them.

Don’t:

• Don’t expect Ionic to write back to Salesforce yet; today it’s read-only. Write-back is planned but not yet available.
• Don’t assume every field syncs automatically; required fields do by default, but optional and custom fields only sync once you map them.
• Don’t expect deletions on objects outside the five listed above to disappear from Ionic automatically.
• Don’t expect a date-range or “greater than” filter, or filtering on objects other than Account; only exact-match (“equals”) filters on Account records are supported today.

FAQ

We already connected Salesforce to Ionic before (e.g. for the ABM platform) - why do we need to do this again?

That earlier connection used a separate, legacy Salesforce Connected App; it isn’t reused or migrated here. “Ionic by DemandScience” is a net-new External Client App, and every customer connects through it going forward, regardless of any prior Salesforce connection.

This isn’t a DemandScience-specific choice. Salesforce itself now blocks creating new Connected Apps by default and is moving all integrations to the newer, more secure External Client App model. See Salesforce’s own documentation: External Client Apps and Connected Apps.

What is “Ionic by DemandScience” in my Salesforce org?

It’s an External Client App - Salesforce’s term for this newer kind of integration app - owned and maintained by DemandScience. It has to be installed, with its OAuth policies configured, before you can complete the Connect step in Ionic.

Does Ionic need write access to our Salesforce data?

No, not today. Ionic only reads the objects and fields you map; it doesn’t create, update, or delete anything in Salesforce. Write-back capability is planned but not yet available.

What happens if we skip the OAuth policy configuration step?

The connection attempt inside Ionic will fail. The package has to be installed and its OAuth policies configured (Permitted Users, Refresh Token Policy, IP Relaxation), done directly in Salesforce Setup, not inside the Ionic wizard, before the connection will succeed.

Can we use a dedicated integration user instead of a real person’s login?

Yes. A Salesforce Integration license works for an API-only account, as long as it also has API Enabled turned on.

Will Ionic pick up deleted Salesforce records automatically?

Only for Account, Contact, Lead, Opportunity, and Campaign Member. Salesforce limits how many objects can be watched for deletions per org, and those five are what Ionic uses. Deletions on the other supported objects won’t automatically clear from Ionic.

Can we filter which records sync?

Yes, but only for Account records today, and only using exact-match (“equals”) rules, for example, only syncing Accounts where Type equals a specific value. Filtering other objects, and more flexible match logic, is planned but not available yet.

Can we change which fields, filters, or fiscal-year setting sync after the initial setup?

Yes. None of these are one-time choices; you can revisit field mapping, filters, and the fiscal year setting in Ionic at any time.

Does the “Cohort” step in the wizard map our Salesforce segments or lists to Ionic?

No. Despite the name, that step is only a fiscal year start month setting, used to align pipeline/revenue reporting with your company’s calendar. There isn’t a CRM segment- or list-mapping feature in the setup wizard today.

How often does the sync run, and how much history do we get on day one?

Sync runs daily. The initial sync pulls the last 24 months (730 days) of history. Both are fixed today and can’t be changed from the setup wizard.

Does the connection ever need to be re-approved?

Not on a fixed schedule, but it isn’t indefinite either: Salesforce’s current policy is “Expire refresh token if not used for 30 days.” As long as the connection is actively used at least that often, it keeps working without re-approval. (This is a recent Salesforce-side policy change; “valid until revoked” is no longer an available setting, even though not all of Ampersand’s public documentation reflects that yet.)