ACME Product Support

ACME/Salesforce Integration Solution

Solution Overview

ACME’s Salesforce integration is a native force.com app that connects to ACME via APIs to facilitate data integration. This real-time data integration includes the sync of all membership, customer and organization data between the two systems. Venues can process memberships in ACME or Salesforce and know the data will always be in sync. Members benefit too, as they will be able to use their entitlements immediately after purchase. The integration also allows for customer ticketing data to be sent from ACME to Salesforce to unlock analytics and marketing opportunities from within Salesforce.  The integration is currently optimized for NPSP.  

Features

• Memberships can be sold, uploaded, or edited in either system and data will flow both ways in near real time. 

• Basic donations can be sold in either system and they will flow both ways on a schedule.

• Contacts/Customers created or edited in either system will flow both ways in near real time.

• Organizations created or edited in either system will flow both ways in near real time.

• Ticket sale data will flow to Salesforce on a schedule for reporting and marketing purposes.

Supported Business Processes

• In-office Membership Sales in Salesforce

• Membership Fulfillment in Salesforce for ACME PoS and eCommerce sales transactions

• ACME eCommerce membership verification 

• ACME PoS membership verification

• Visitation analysis and marketing communication based on ACME order data

• Import of Memberships to Salesforce, processed in a system external to ACME with Membership Import feature (beta)

Assumptions

• ACME Managed Package and associated data model is required for the features described in this document to function. 

• The operation of the ACME Managed Package is ideally done by a trained Salesforce Admin. 

• ACME is not responsible for training users on general Salesforce operations, only on the functions of ACME Managed Package.

• ACME is not responsible for troubleshooting or implementing Salesforce processes outside of the ACME Managed Package and integration.

• The following are the responsibility of the client, (outside of the ACME Managed Package):

  • Household / Contact Management (because Salesforce is master)

  • Duplicate Contact Management (because Salesforce is master)

  • Address Management (because Salesforce is the master)

  • Member Card Printing / Fulfillment from Salesforce (because the fulfillment process is Client specific)

  • Donor management (because ACME is not a donor management platform)

  • Marketing (ACME sends transactional emails only)

  • Any customizations to support Client specific business processes

  • Business Process Rules / Workflows / Triggers

  • API integrations other than the ACME Managed Package

  • Any Salesforce Data Model changes (new fields, objects) that are not included in the standard ACME Managed Package 

  • Batch membership payment processing 

Limits

• The Visualforce app does not support ticket sales.

• Only named customers and their associated membership, donation, and visitation data are synced to Salesforce from ACME.

• ACME Forms data and Donations custom fields do not sync from ACME to Salesforce due to the variability in how the fields can be configured per client.

• ACME only supports a 2 way integration with a single CRM at a time. However, if a venue wishes, it is possible to push data from ACME into another CRM (one direction only).

• One ACME tenant cannot integrate with multiple Salesforce instances.

Roles and Responsibilities

Integration Components 

1. ACME Managed Package

   1. The ACME Managed Package gets installed on the Salesforce side and includes the following:

      1. ACME custom objects and Integration field mappings

      2. ACME custom fields on standard objects

      3. Visualforce sales flow for Memberships and Donations

      4. Triggers that copy data from one object to another for improved usability (ie - copying the lifecycle action used in a membership transaction from the order item to the membership object)

      5. Triggers that populate lookup fields

      6. ACME settings tab

      7. Workflow rules to trigger Outbound messages 

      8. Membership Import (beta) logic - looks for records flagged in a certain way to put into a queue and pass to ACME

2. Integration Framework

   1. The integration framework handles real time data exchange between Salesforce and ACME.

3. ACME APIs

   1. The APIs pass the data into ACME from the integration framework. Validations in the code check for data issues, and successful data gets populated in the ACME databases.

   2. The ACME Salesforce Integration Tool allows users to see error logs around why data did not flow correctly between Salesforce and ACME (in both directions) so the user can self-correct.

Object Mapping

Installation and Set Up

• ACME recommends a trial implementation in a sandbox environment before going live.  

• ACME will need administrator access to your Salesforce environment.

• ACME Engineers will activate the integration via the ACME Managed Package after it is installed.

• ACME will require a SysAdmin user license on a permanent basis.

Installation Requirements

Clients must create a Salesforce user record for ACME with the following info:

• First Name - leave blank

• Last Name - ACME Integration

• Username - acmeintegration@{client’s domain}

• Email - sfdc-integration@acmeticketing.com

• Role - not required

• Profile - System Administrator

• Marketing User - TRUE

Test Environment

It is recommended that the client install and test the ACME integration in a sandbox before going to production, including testing any applicable data migration process. We recommend that you run a suite of end to end tests to ensure everything is configured correctly and data is flowing as expected. ACME’s CSM team will help with this process. 

When performing a data refresh of your Salesforce test environment, it is imperative that this happens in tandem with an ACME data refresh. This will ensure that data between the two systems is in sync and the integration runs as expected.

Once the ACME Managed Package has been installed in your Production Salesforce environment, it maintains a link to your ACME Production environment. Any copies of your Production Salesforce environment will include the ACME Managed Package and all the production integration settings as an expected part of the process, and will need to be disabled prior to use. Please coordinate with your ACME CSM to schedule a Salesforce data refresh during the next ACME sandbox data refresh.

Visualforce Membership Sales

Use Cases

The Visualforce sales flow can be utilized by a Salesforce user in the Development or Membership department to process memberships in-office. These memberships are typically received via mail or inbound call. The below membership actions can be performed for all types of memberships.

• New Membership: a membership is added to a new or existing contact who has no membership history. This can be processed for an existing contact or as a gift.

• Renew Membership: an existing membership is renewed for another term, at the same or different membership level.

• Upgrade Membership: an existing membership is upgraded to a higher level during the current membership term. The member pays the difference in membership dues.

• Downgrade Membership: an existing membership is downgraded to a lower level during the current membership term. The member is refunded the difference in membership dues (if applicable).

• Cancel Membership: a membership is terminated prior to the expiration date.

• Rejoin Membership: a membership which has lapsed beyond the renewal window is renewed for a new term, at the same or different membership level.

Additional use cases supported:

• Donations: can also be processed using the sale flow in the Visualforce application. Users can add a donation to a membership order, or sell a donation as a stand alone order.  

• Member Card replacement: if a venue chooses to charge a customer for a new Membership Card, this sale can be processed in the Visualforce application.

Inputs

• Existing Contact in Salesforce to which you want to: sell a membership, perform a lifecycle action, or charge a donation

• Mailed membership appeal responses

• Inbound call from member

Outputs

• Membership and Card(s) are created in Salesforce. Opportunity is created in Salesforce.

• In real time, Membership and order data is sent to ACME through the integration.  

• In real time, Membership and Card(s) are updated in Salesforce to contain the ACME Database IDs, Level IDs, and Price Point IDs.

• On a schedule, the payment and financial data is sent from ACME back to Salesforce to update the Opportunity.

• Salesforce membership communications can be produced based upon the membership data entered (e.g. Acknowledgement emails or letters, Membership Card fulfillment).

• Salesforce membership reports can be generated with the data entered in the Visualforce flow.

Exceptions

The Visualforce flows may fail to process correctly under the following conditions:

• A custom validation rule prevents data from being saved

• A custom process prevents data from being saved

• A custom required field prevents data from being saved

• The user does not have permissions to access an object or record type

• Workflow Rules or Validation Rules do not exclude the ACME Integration user

• ACME Managed Package picklist values have been changed or deleted

• ACME Managed Package workflow rules or Outbound Messages have been changed or deleted

• ACME records in the Product or PriceBook tables have been changed or deleted, or the Standard Pricebook has been deactivated

• Values in the ACME Settings tab (with the exception of the Send Order Summary Email checkbox) have been changed

• Data in the ACME Field Mappings table has been changed in ANY way

• ACME External ID field values on any object have been changed or deleted

• Membership Level or Offering settings have been changed in ACME

• User’s internet is down

• Interruption in ACME API connection

Controls

All membership processing rules are defined in ACME Back Office, including:

• Qualified timeframe in which a membership can be renewed, rejoined, upgraded, downgraded, or cancelled

• Eligible membership levels for upgrade or downgrade

• Membership price points

Verification/Validation Process

• Membership and Card(s) created in Salesforce and in ACME, with the ACME External IDs populated

• Order data created in ACME

• Opportunity created in Salesforce with line items and transactions

Data Flow Diagram

Membership Import (beta)

Use Cases

The Membership Import (Bulk) feature can be utilized to process a high volume of memberships from an external source, such as a caging facility or telemarketing firm. This process allows for data files to be uploaded in lieu of data entry directly into Salesforce through the Visualforce flow. 

Use cases include uploading membership data for New, Renew, Upgrade, Downgrade, and Rejoin membership scenarios for Individual memberships and Corporate Memberships (Note: Corporate memberships have additional required fields).

Inputs

• Upload files for Memberships and Membership Cards

• Inbound data requests which prompt a user to edit a Membership

Outputs

• After correctly flagging the necessary fields (Status = Pending, IsBulk = True), the scheduled sync will pick up the records and sync them to ACME.

• Memberships are added to existing Contacts in Salesforce and ACME.

• Membership Card(s)s are added to new Memberships in Salesforce and ACME.

• Membership updates are reflected in Salesforce and ACME.

• Successfully synced records will have the status of “Synced to ACME” in Salesforce.

Exceptions

• Validations are checked by ACME’s API. If errors are caught, records will be stuck in Completed.  (See “ACME/Salesforce Membership Import Feature Guide” document: Membership Import Sync Process -> Validation section).

• The ACME Salesforce Integration Tool allows users to see error logs around why data did not flow correctly between Salesforce and ACME (in both directions) so the user can self-correct.

Controls

• ACME syncs data in batches for the Membership Import process. The integration will segment all records in the queue into batches of 20 records, and it will send all batches when it runs. Any records that do not meet the requirements will not be sent, and will remain in the queue. The queue is ordered by SFDC Updated Date, with the oldest at the beginning.

Salesforce Edits to Existing Membership Data 

Use Cases

Users may opt to directly edit a membership record in Salesforce in the event of:

• Data entry mistake (e.g. misspelled name on Card)  

• Membership was not initially processed as a Gift Membership

• To extend the Membership expiration date (member recovery/customer service reason)

• To add a customer to an existing secondary Membership Card

• To cancel a Membership

• To restore a deleted Membership

Inputs

Fields that can be directly edited by a user in Salesforce as a part of the real time integration: 

• IsGift

• Gifter

• End Date on Membership or Card (* see exception below)

• Name on Card

• Adding a contact to an existing Membership Card

If edits are made to any of the following fields, the user must also check the “IsBulk” checkbox to TRUE and set the Membership and Membership Card(s) status fields to “Pending” so the Membership Import (beta) sync process will send the updates to ACME. 

• Join Date on Membership

• Standing on Membership

• Start Date on Membership

• Start Date on Membership Card

• Type on Membership Card

• Standing on Membership Card

Edits made through the UI can also be sent via the "Update in ACME" button from the Membership detail page in Salesforce. This button will correctly set the membership and membership cards with the right settings so it will be picked up and synced to ACME in the next import run. It sets the membership and all associated cards to "Is Bulk" = true and "Status" = Pending.

In order to use this button, your Salesforce Admin will need to update your membership layout to include the "Update in ACME" button.

Outputs

When the above fields are edited and saved, the changed data will be synced to ACME, and

• Memberships will have a Status of “Synced to ACME”

• Membership Card(s) will have a Status of “Synced to ACME”

• Edits will be visible in B2B

Exceptions 

• *If a membership has a status of “Dropped", its expiration dates cannot be edited. The membership must be rejoined before any edits can be made.

• Currently, memberships must have the same value for “ACME Membership Number" and “External Membership ID" in order to appear with the same membership number in both systems and ACME does not support manually updating the “Name" field in SF to a different value.

• If a Membership or Card has been deleted in ACME, the sync will fail.

• Edits done in Salesforce will not sync to ACME if:

  • Membership or Card(s) is missing required data point(s)

  • Membership or Card(s) does not have “IsBulk” checked

  • Membership Import process has been deactivated in Salesforce

• Validations are checked by ACME’s API. If errors are caught, records will be stuck in Completed.  (See “ACME/Salesforce Membership Import Feature Guide” document: Bulk Sync -> Validation section).

Controls

• It is not recommended to unlock editing capability for other membership fields for standard user profiles, since these changes will not be included in the sync to ACME.

• ACME syncs data in batches for the Membership Import process. The integration will segment all records in the queue into batches of 50 records, and it will send all batches when it runs. Any records that do not meet the requirements will not be sent, and will remain in the queue. The queue is ordered by SFDC Updated Date, with the oldest at the beginning.

Merging Data in Salesforce

In Salesforce, you can use the native merge functionality and merge accounts and contacts. This action will send the resulting data via the ACME APIs and update the data inside ACME as well. After merging Accounts or Contacts, the entity that is going to remain after the merge will inherit any orders that were associated to the prior Account or Contact. Both Accounts/Contacts need to exist in ACME and in Salesforce for it to be considered a merge. There is not yet a membership merge API.

If there are memberships associated to a merged Account or Contact (ie the entity that’s getting removed), ACME doesn’t yet have a way to associate an existing customer to an existing membership card. If the account/customer you want to keep is not associated to a membership, but the one you want to merge/remove IS associated to a membership, after you merge the contacts or accounts, send any memberships that were associated to the no removed contact to ACME via the Membership Import Sync process so they will be updated in ACME and associated to the correct customer/contact in both systems.

Note: Objects that do not sync back to ACME when updated (ie Opportunities) can be managed as needed in Salesforce, and there will not be any sync back to ACME, therefore no impact on the data in ACME. Our recommendation is to only delete/update orders that you are confident will not change, and are closed/historical orders, because if someone edits an order in ACME that was deleted from Salesforce, the edit will cause the updated information to get pushed to Salesforce and recreate the opportunity but with only the changed information. This would result in a data mis-match between the systems. 

Deleting Memberships from Salesforce and ACME

In Salesforce, you can delete a membership version from Salesforce and that membership will also be deleted out of ACME. This will help you ensure your systems are in sync. When a membership record is deleted in Salesforce, the real time sync will immediate delete the membership and all its cards out of ACME. This should mostly be used in cases where there was an accidental membership version created in Salesforce, which propagated into ACME. If the membership was created as a result of an order and needs to be cancelled, you can cancel the membership as before via ACME or Visualforce. If you need to refund a membership but do not wish to cancel the membership, please reach out to ACME support with the details, as a data adjustment may be needed on the order. 

If the membership was deleted in Salesforce by accident and the user restores it on the Salesforce side, you can use the Membership Import (beta) feature to send the membership version back to ACME. First, delete the ACME External ID from both the membership and the membership cards, then simply click the "Update in ACME button" on the membership record and all of the correct fields will be set to have the membership get picked back up in the next batch and go to ACME. This will recreate the previously deleted version in ACME, but it will have a new ACME External ID (version number).

Note: Deleting a membership version does not cause any automatic updates to prior membership versions. If the most recent membership version is deleted, an earlier version of the membership will need to be restored to allow the member to use their membership. This will require a data fix request to be submitted to ACME Product Support to update the older version to be flagged as the "latest" version in ACME, and be updated to an Active status. The "latest" flag is what controls a membership record appearing in search in Back Office and the POS, as well as allowing members to verify online. In order to avoid a data fix in the case of a duplicate record, you can delete the previously created version which is no longer the latest, and keep the "latest" version and make any needed adjustments to that record.

ACME to Salesforce Data Flow

Use Cases

Data is sent to Salesforce from ACME to enable Salesforce users to run various business processes such as data analysis, marketing, and membership management. The following data is synced to Salesforce when a create or update happens in ACME:

• Customers

• Organizations & Organization Contacts

• Memberships & Cards

• Order & Transaction data

Visitation runs from ACME to SF hourly, sending orders and transactions to SF in their own queue. Orgs, contacts, addresses, households, customers, and memberships will run in a separate queue from ACME to SF and is sent in real time.

Integration Triggers

The following actions initiate the sync of data from ACME to SFDC:

• Customers

  • Adding a customer through the ticket sale process

  • Editing a customer’s details at P0S

  • Adding or editing a customer through the Membership Card form (see tips section)

• Organizations & Organization Contacts

  • Adding or editing an organization

  • Adding a contact to an organization

  • Editing a contact on an organization

• Membership

  • Selling a new membership

  • Lifecycle management of a Membership: Renew, Upgrade, Downgrade, Rejoin, Cancel

  • Cardholder management: edit dates, add/remove Cardholders, edit Cardholder details, primary member vs. secondary member designation

• Order & Transaction data

  • Event ticket sale for a named customer

  • Add on sale for a named customer

  • Donation sale to a named customer

  • Membership sale

Data mapping

• The data mapping between ACME and Salesforce is controlled by the ACME Managed Package. See “ACME Data Model as represented in Salesforce - NPSP” document for a field by field data mapping.  

• Including additional fields in the ACME Managed Package would require a project to be approved and scheduled by ACME’s engineering team, and these requests will be considered on a case by case basis.

Exceptions

• There are times when processes configured by the client on the Salesforce side can interrupt the sync and cause data not to flow into Salesforce. Examples include:  

  • A larger-than-usual batch causing a CPU limit exception

  • Poorly formatted email addresses from ACME will prevent a customer/contact record from syncing to Salesforce

  • A custom validation rule, process, or other non-ACME requirement interferes with the integration 

  • Client’s custom Workflow Rules or Validation Rules do not exclude the ACME Integration user

  • ACME Managed Package settings are changed or deleted such as

    • Picklist values 

    • Workflow rules or Outbound Messages 

    • ACME records in the Product or Price Book tables 

    • Standard Price Book has been deactivated

    • Values in the ACME Settings tab

    • The ACME Field Mappings table

  • Existing ACME External ID field values are edited

• If any of these issues occur, please contact Product Support

• The ACME Salesforce Integration Tool allows users to see error logs around why data did not flow correctly between Salesforce and ACME (in both directions) so the user can self-correct.

Tips

When editing Membership cardholders at PoS, please keep these tips in mind:

• Adding a new Card with a NEW Customer will sync the new Card and create a new Contact in Salesforce.  (Note: There is not currently a way to associate an existing Customer to a Card outside of the sale process on PoS)

• Swapping primary and secondary Cards will sync to Salesforce.

• Deactivating a Card via PoS by unchecking the checkbox will expire the Card and sync the expiration date to Salesforce.

• When there is already a customer associated to a Card, (“External Customer Id" is present on the cardholder record), then changes made to that Customer’s details in the PoS cardholder edit process will sync back to the linked Contact in Salesforce.

  • Only use this process to edit the existing customer’s details (ie - customer got married and needs to change last name, repairing misspellings or typos, customer changed email addresses, or moved and has a new address).

  • Do not replace one customer on a card with another customer. Instead expire the existing card and add a new Card for the new person.

• When there is a “cardholder only” record, this means that there is not a Customer associated to the Card (“External Customer Id” or “ACME Customer Id” is not present) and only the “Name on Card” field is populated. Adding a Customer to a Card that does not already have one associated can be done at PoS for Individual/Family membership levels by editing the Card and filling out First Name, Last Name, and at least one of Phone, Email, or Address. This will create a Customer in ACME and a corresponding Contact in Salesforce.

  • Note: This process will not de-dupe against existing Customers in ACME. If a duplicate Customer is created in this process, the duplicate Contacts can be merged in Salesforce and the results will flow back to ACME to clean up the duplicates.  

  • Note: ACME does not associate Customers with Cards for Corporate membership levels. 

Salesforce to ACME Data Flow

Use Cases

Data is sent to ACME from Salesforce so that:

• Members can use their entitlements via ACME sales channels (ie member discounted tickets).

• Members can manage their memberships within the ACME sales channels.

• Organizations and Contacts can be managed in Salesforce and the updates are sent to ACME for use across the sales channels.

• Staff can sell a membership to an existing customer who is not yet a member via the PoS 

Integration Triggers

The following actions initiate the sync of data from SFDC to ACME:

1. Method 1: Real-time Sync - This is the process by which the ACME integration picks up changes made in Salesforce to the fields in the ACME Managed Package and sends them to ACME. The following changes are sent via real-time sync:

   1. Adding or editing a Contact, Household, or Account

   2. Selling a membership lifecycle action in the Visualforce flow

   3. Selling a donation or Member Card replacement in the Visualforce flow

   4. Editing the fields on a Membership or Card (see Salesforce Edits to Existing Membership Data section)

   5. Deleting a membership (see Deleting Memberships from Salesforce and ACME section)

2. Method 2: Membership Import (beta) feature - This is the process by which users can send a large number of memberships which have already been sold through other channels to ACME. The main use case this method facilitates is for a venue that processes a large volume of memberships via a caging facility or external process. This method can also be used to send edits on individual records over to ACME. (See the ACME/Salesforce Membership Import Feature Guide) 

Outbound Messages (OBM)

Memberships will sync from Salesforce to ACME via OBM when:

• An ACME External ID is present, the membership record has a status other than Pending, and any changes to a membership record are made on one of the following fields:

  • End Date (cannot be edited on a Dropped membership)

  • IsGift

  • Gifter

  • “DoNotSync” is false

Customers will sync from Salesforce to ACME via OBM when:

• Any change on a contact record in SF, where ALL the following criteria are met:

• An ACME Customer ID is present

• The account record type is household

• “DoNotSync” is false

Membership card edits will sync from Salesforce to ACME via OBM for the following fields:

• Name on card

• Type (Primary vs Secondary)

• Contact

• “DoNotSync” is false

Note: If a change is made via a nightly process to calculate giving, or a roll-up process runs, those do trigger an outbound message. However, if that message has no corresponding action for ACME to take, then it does not impact the flow of data in the integration, since there is no further action required.

Data Mapping

• The data mapping between ACME and Salesforce is controlled by the ACME Managed Package. See “ACME Data Model as represented in Salesforce - NPSP” document for a field by field data mapping.  

• Including additional fields in the ACME Managed Package would require a project to be approved and scheduled by ACME’s engineering team, and these requests will be considered on a case by case basis.

Exceptions

The "Do Not Sync" flag will prevent real time updates on the applicable object from being sent from Salesforce to ACME. When set to true, this flag will only prevent real time updates from being sent and it does not impact data flowing from ACME to SF, and updates to real time synced fields can still be sent to ACME via updates triggered by the Membership Import Sync process.

See other exceptions noted in the following sections:

• Visualforce Membership Sales

• Membership Import

• Salesforce Edits to Existing Membership Data

Appendix A: Troubleshooting Tips

• ACME recommends creating a report of bulk memberships grouped by status to help identify problem records.

• If you are running a large batch of bulk memberships, they may take up to several hours to be processed. 

• If records are not moving out of the Pending status, double-check that all required fields are filled out, including IDs.

• If records are not moving out of the Completed status, please contact Product Support.

• If a newly-created membership level or offering is not appearing in the Visualforce page, double-check the Channel Transaction Policies to make sure it’s available for Salesforce.

• If a membership level is missing from the upgrade or downgrade Visualforce flow, double-check the Lifecycle Rules.

• If you get an error when processing a membership in Visualforce, please copy or screenshot the error and contact Product Support.

• If a customer is not syncing from ACME to Salesforce, check that the email address does not contain invalid characters (comma, space, etc). This is the most common issue preventing customer sync.

• If a membership or order is not syncing from ACME to Salesforce, please contact Product Support.

Appendix B: Entity Relationship Diagram

References

1. ACME/Salesforce Membership Import Feature Guide

2. ACME/Salesforce Visualforce Feature Guide

3. ACME Data Model as represented in Salesforce - NPSP

Change History

The content of this document is owned by ACME Technologies, Inc. and is strictly confidential. Unauthorized use, disclosure, or copying of this information is prohibited. 

Attachments

ACME Salesforce Integration Solution with Membership Import v2 PDF