What does integration mean?
Integration is a term used to describe the linking together of different computing systems and software applications functionally, to act as a coordinated whole.
Why does Club OS need integration?
Today, every Club OS customer has more than one software system because no application handles all the needs of a health club. By integrating Club OS with our various partners, it provides them a unified, full-featured experience for their business. Without integration, our customers would have to manually copy data from one system to the other.
What types of systems does Club OS integrate with?
* Membership and Personal Training Billing Systems
* ABC Financial
* Club Hub
* MindBody Online
* A few others, full list [here]
* Search Engine Marketing / Marketing Systems (Hubspot)
* Social Media (Facebook)
* Member Mobile Apps (Netpulse/Perkville)
How are the systems linked together?
In order to link accounts between two systems, the systems need to share unique IDs. These IDs can represent locations, prospects or members, agreements, events, and more. Any object being shared between systems could have an ID. The most common shared IDs Club OS uses are Prospect User ID, Member User ID, Location ID, and Agreement ID.
Integration Data & Direction
What type of data is being sent?
Club OS can integrate many different types of data, including:
* Membership and Purchase Data
* Calendar Events
* Marketing Sources
How does data flow between the two systems?
For each system that Club OS integrates, a combination of the following methods are used to provide a full integration:
* Club OS pushes data to the other system
* The other system pushes data to Club OS
* Club OS pulls data from the other system (at specified sync times)
It is critical to know which of the above methods our integrated partner uses when assessing customer issues.
Club OS pulls data from other systems
For integrations that require Club OS to pull data from the other system, Club OS offers "sync times". Sync time refers to how often Club OS will pull the data from the other system. Some examples are hourly, every three hours, or nightly. Sync times can be different for each customer, even if those customers use the same integrated system.
Club OS pushes data to other systems
Club OS pushes information to other systems such as new prospects, or changes to events. All data pushes to other systems are performed in near real-time of the action being done within Club OS.
The other system pushes data to Club OS
For integrations that require the other system to push data to Club OS, Club OS offers three different options, depending on the desired functionality.
1. Legacy Vendor API
Primarily used for marketing / website integration to collect new prospect information, this API offers a large list of services that various customers and partners take advantage of.
2. Vendor API v2
This project is the foundation of the Club OS Vendor API will work in the future. It is currently only used for the AF Member Mobile app, but will be expanded upon.
3. Tracker Endpoints
Tracker endpoints allow other systems to send us data that is processed the same way as they would be when Club OS pulls data from them. They offer an alternative to Club OS needing to pull data from the other system. Tracker endpoints can be used anytime, and offer a more real-time experience to the end users.
Systems that use Tracker Endpoints
1. Membership Billing Endpoints
1. Club Hub
4. Club Systems
2. Lead Gen Endpoints
2. Facebook Lead Ads
Mapping Data between Systems
For each integration, Club OS and the other system must determine how fields from one system will convert, or map, to fields in the other system. This is determined by the engineering teams of both systems. Field mappings for our integrations can be found [here]
* "From" means Club OS is pulling the data from the billing provider.
* "To" means Club OS is pushing the data to the billing provider.
Converting Prospects to Members
Member data coming from other systems will include membership information, which is how Club OS can tell when a sale is made. When processing a sold membership for the first time, Club OS will attempt to find an existing Prospect account in the system and convert that account to a Member account. The system will look for an existing prospect account first with a matching external billing ID. If a Prospect is NOT found with that ID, it will then look for an account with identical first and last name plus an identical email or phone number. If a record is found in any case, the prospect is converted to a member. If the account is already a member account, the account will be updated per the rules of the integration. Otherwise, the system will create a new Member account.
Active Members By Default
By default, when pulling Members from other systems, Club OS will only include active Members, or Members who are in good standing (they don't owe the club any money, and have not canceled or expired their membership). The reason is because many systems have thousands of inactive member accounts, many of which are very, very old. For most integrations, we can pull these members upon request of the customer, but we default to skipping them. If a customer asks why their member isn't there, or why a prospect did not convert to a member, make sure they have an active membership in the other system.
Club OS allows it's customers to define Memberships that should be ignored. This is done through the Club OS System Admin app. By adding ignored memberships, the integration code will skip members with an Agreement Name that matches these memberships. This is a common cause of confusion. If you get asked "Why didn't this membership sync to Club OS", the first thing to look at is the Agreement Name from the other system, and ensure we aren't skipping that membership name.
Membership Status Changes
Integrated systems will provide some type of status on their agreements, such as active, canceled, delinquent, and more. Changes to those agreement statuses will directly affect the Club OS follow-up system, and move the member into the various follow-up statuses. Be sure to understand the statuses for each customer (using the mapping documentation) and how those statuses translate into Club OS follow-up functionality.
Determining the Salesperson
Unfortunately, it's not always easy to determine who the salesperson when a membership is sold. Sometimes the person selling is not the person ringing up the agreement, so Club OS makes its best effort to figure out the salesperson based on the data that is available.
The rules for determining whom to assign as the salesperson in Club OS are applied in this order:
1. If the billing partner is ABC, and the agreement has a web sign up designation, this process is skipped and no salesperson is assigned to the agreement. (The rest of the billing providers (and Club Hub) do not pass web sign up designations.) If the membership was not flagged as a web sign up or this flag is not available in the integration itself, move to the next rule.
2. If a tour event exists on the agreement sale date, we assign the event owner as the salesperson. If no event exists that meets these conditions, move to the next rule.
3. If the billing provider has passed a salesperson on the agreement, assign the sale to the salesperson (and if the salesperson was not found in Club OS, create them in Club OS). Note that Rule 2 supersedes this one--if the tour owner is a different person than the salesperson passed by the billing provider, the sale goes to the _tour owner_.\* If no salesperson was passed for the agreement, move to the next rule.
4. If the client has an assigned follow-up person who works at the same location for which the membership was sold, the sale is assigned to them. If the client has no currently assigned salesperson, or if the currently assigned follow-up person is at a different location than the membership was sold at, move to the next rule.
5. Assign the location default member sales account as the salesperson.
If a salesperson is assigned via one of the rules in 3-5, a walk-in tour event will be created on the assigned salesperson's calendar to represent the closed opportunity. The appointment will be created at 8:45pm local time to help distinguish these events as having been created by the integration.
Hourly vs. Full Sync
Some systems that integrate with Club OS allow us to decide how much data we pull during each sync by providing a filter to only return data that has changed in a certain time period. Club OS always prefers to pull less data, so when an integrated system allows for this type of pull, Club OS will take advantage of that and only pull "hourly" data throughout the day. Hourly data limits the results of what is returned by some date range. For example, only members that have bought a new agreement or made an agreement change in the past day. At the end of each day, Club OS always runs a "full" sync to ensure that all accounts are updated from the beginning of time as a backup precaution (in case any data was missed throughout the day)..