Using PCO Sync V2

This guide covers what happens after installation: setting up what syncs, understanding the sync job, and working with the plugin day to day. For installation and subscription setup, see the PCO Sync V2 installation guide. This guide describes version 2.8.0.

How the Sync Thinks (Two-Minute Version)

A few concepts explain almost everything the plugin does:

  • True two-way sync. Neither Rock nor Planning Center is "the master." When the same information differs, the most recently changed side wins.
  • Only serving people sync. A person enters the sync if they are actively serving in Planning Center Services, or if they're in a Rock group or tag you've connected to PCO. Your whole database is never pushed to PCO.
  • People are matched, then linked. The first time the sync sees a person, it matches them across systems by name plus email or mobile phone. Once matched, the link is remembered permanently — future syncs update the linked record rather than re-matching.
  • Groups and tags opt in with a marker. A Rock group or tag syncs only when its PCO Marker attribute points at something in Planning Center (a team, a position, or a tag). Everything else is invisible to the sync.
  • Changes are applied on the schedule. Nothing syncs the instant you edit it. Changes are picked up the next time the sync job runs.

First-Time Setup

Work through these once, after installation, in this order.

1. Review your PCO account settings

On PCO V2 → Manage Accounts, check two settings on your account:

  • On Conflict Use Data From (Rock or Planning Center): decides which system's value wins when the two disagree and the sync can't tell which side changed. Once you're syncing that is rare, but on your first sync every difference is a conflict, so this setting decides all of them. Pick Rock if Rock is your system of record; choosing Planning Center means PCO's birthdates, campuses, emails and other details overwrite Rock's on that first run. It does not make the sync one-way.
  • Map First and Nick Name — controls whether Rock's First/Nick names map to PCO's legal/goes-by names. Pick the arrangement that matches how your PCO data is entered.

2. Map your campuses

If you use campuses in Planning Center, open PCO V2 → Campus Mapping and pair each Rock campus with its PCO campus. Skip this only if you're a single-campus organization that doesn't use campuses in PCO.

3. Add the PCO Marker attribute(s)

Everything that syncs — whether imported or linked by hand — is connected through an attribute using the PCO Marker field type. Create the one(s) you need before going further:

  • For groups: on the group type your serving groups use (e.g. Serving Team), add a group attribute with field type PCO Marker (edit the group type → Group Attributes).
  • For tags: add an entity attribute on Tag with field type PCO Marker (Admin Tools → System Settings → Entity Attributes).

Add whichever applies — groups, tags, or both. The importers below require this too: Folder Import asks you to pick the group type and its PCO Marker attribute, and Tag Import needs the tag attribute.

4. Connect your serving structure

This step defines who syncs. There are three ways to connect things, and you can mix them freely:

Folder Import (PCO V2 → Assistants → Folder Import) mirrors your Planning Center folders, service types, and teams as a tree of Rock groups. You'll choose a Team Structure:

  • One group per team with a positions attribute (recommended). Each PCO team becomes a single Rock group. Every member gets a PCO Positions field where you check which positions they hold — including a "Team Leader" checkbox. The checkbox options are always that team's real positions, kept current automatically.
  • A group for each position (classic). Each position on a team becomes its own child group, plus a "Team Leader" group per team. This is the pre-2.0 structure; choose it if you've built processes around it.

Tag Import (PCO V2 → Assistants → Tag Import) creates a Rock tag for each Planning Center tag, named by a template you control. Use it if tags are how you organize people in PCO.

Both importers are safe to re-run — they update rather than duplicate.

Tip

Use a dedicated parent group (e.g. "PCO Teams") for the Folder Import, and if you sync more than one PCO account, give each account its own parent group.

Link groups or tags by hand. You don't have to use the importers at all. Edit any existing Rock group (of a group type that has the marker attribute from step 3) or any tag, and set its PCO Marker attribute — the picker walks you through your PCO account to a tag, a team position, or an entire team (which enables the positions-attribute behavior described above, set up automatically on the next sync). This is the right approach when you only want a handful of things synced, or when your Rock groups already exist and you just want to connect them.

Two rules apply however you connect things: one PCO item should only ever be linked to one Rock group or tag (the picker warns you if it's already taken), and anything without a PCO Marker value simply doesn't sync.

5. Run your first sync carefully

  1. Open the Job Configuration Assistant and set Stoppage Percent to 0. This makes the sync pause and show you every proposed change instead of applying anything. (From version 2.8.0 the Install Assistant starts new installs at 0, so this is already done for you; check it anyway.)
  2. Run the PCO v2 Sync job (or wait for its schedule).
  3. Open PCO V2 → Sync History, click into the run, and review the pending operations. This is your chance to catch a mis-mapped group or unexpected matching before anything is written. Don't be alarmed if a first run lists everyone as Added New Person — that label is provisional. The final duplicate check runs as changes are applied, and people whose name and email line up with an existing Rock record are linked to it rather than duplicated.
  4. Click Approve to apply, or Cancel to discard and fix your setup.
  5. Once a run or two looks right, raise Stoppage Percent to a sane guard value (many churches use 10–20%). Leaving it at 0 means every run waits for a human — fine during rollout, painful forever.

The Sync Job

The PCO v2 Sync job does all the work. Recommended schedule: every 4 hours (the Job Configuration Assistant sets this up).

Job settings

SettingWhat it does
Stoppage PercentIf more than this percentage of synced people would change in one run, the job pauses in Awaiting Review and notifies you instead of applying. Your safety net against surprises (a mass update in either system, a mis-mapped group).
Max New Records Without ReviewDefault 10. If one run would create more than this many brand-new people in either system (people the sync couldn't match to an existing record), the job pauses for review even when Stoppage Percent isn't exceeded. Blank turns this check off.
Notification GroupWho gets emailed when a run pauses for review or logs problems. Put your Rock admins here — don't leave it empty. The Job Configuration Assistant requires one whenever Stoppage Percent is set.
Refresh Group StructureOn (default): every run re-checks Planning Center and updates your imported group tree — new folders, service types, teams, and positions appear automatically; things deleted in PCO get their Rock group marked inactive (never deleted). Turn off only if you want the structure frozen.
Inactivate Instead of RemoveOff (default): someone removed from a synced team, position, or tag in PCO is removed from the mapped Rock group (archived, if the group type keeps history). On: their membership is marked Inactive instead, and setting it back to Active in Rock re-adds them in PCO. See When a person is removed in Planning Center below.
Organization Key / Secret (Legacy)Only used by older installs. Once your 9 Embers API Key is in place these clear themselves — you can ignore them.

What each run does, in order

  1. Checks your subscription with 9 Embers (see Licensing & Trial below).
  2. Refreshes the group structure from PCO (if enabled).
  3. Reads both systems, compares against the last completed sync, and works out what changed where.
  4. Checks the Stoppage Percent and Max New Records Without Review. Over either limit → pauses in Awaiting Review and emails your Notification Group, with the reason it paused.
  5. Applies the changes to both systems, then records the new state for next time.

One sync at a time

Only one sync can run at once — enforced at the database level, even across multiple Rock servers. If a run is triggered while another is still going (for example, clicking Run Now during a scheduled run), the second one simply skips with a warning in the job history. It's harmless; the next scheduled run picks up normally.

Reading job status

  • Success — ran and applied cleanly.
  • Warning — the run completed, but wants your attention. The message says why: you're in the trial period, the 9 Embers server couldn't be reached (grace period countdown), or specific people have data conflicts (see Warnings That Repeat).
  • Error — the run stopped. The message says why: authentication failed, trial expired, or a fatal problem during the run. Check Sync History for details.

Day to Day: How Changes Flow

Adding someone to a serving team (team-structure groups)

From Rock: add the person to the team group, then edit their membership and check at least one position (or "Team Leader") in the PCO Positions field. On the next sync they're created/updated in PCO and assigned to those positions.

Tip

A member with no positions checked doesn't sync — they're a Rock-only roster entry. This is by design: Planning Center has no concept of "on the team but in no position." If someone was added but never appeared in PCO, this is the first thing to check.

From PCO: assign the person to a position (or make them a team leader). The next sync adds them to the Rock group with the right boxes checked.

Changing positions works from either side — check/uncheck in Rock, or reassign in PCO. Unchecking someone's last position removes them from the team in both systems (or marks their Rock membership inactive instead, if Inactivate Instead of Remove is on — see below).

Team leaders are just the "Team Leader" checkbox — a person can be a leader and hold positions at the same time.

Positions stay current automatically

Add, rename, or remove a position in Planning Center and the checkbox list on the Rock group updates on the next sync. Renames are seamless — nobody loses their assignment.

Teams that use tags ("tag teams")

Some PCO teams don't assign people to positions directly — people qualify through tags. For those teams the sync manages team leaders only; sync the people themselves by connecting the relevant PCO tags (Tag Import or the PCO Marker picker on a tag). The team group's positions field will only offer "Team Leader" — that's correct, not a bug.

Tags

Add or remove a synced Rock tag on a person and the matching PCO tag follows, and vice versa. One caution: Planning Center tag groups can be limited to one tag per person. Rock has no such rule, so if someone in Rock ends up with two tags from a single-choice PCO tag group, the sync keeps the one PCO already has, skips the other, and logs a warning naming the person and tags. Remove the extra tag in Rock to resolve it.

Person details

Names, email, birthdate, gender, campus, home and mobile phone, home address, and family/household membership all sync both ways. A few things worth knowing:

  • Blanks don't overwrite. After a person's first sync, an empty value never wipes out a real value on the other side.
  • Birthdays without a year. Planning Center has no "no year" option. Its own help says to enter such a birthday with the year 1885, which hides the age. The sync reads 1885 as "year unknown" and stores it in Rock the Rock way, with no birth year; a Rock birthday with no year goes to Planning Center as 1885. A birthday with no year never replaces a real one: if one system has 9/21/1968 and the other has 9/21 with no year, the sync leaves both as they are, and removing the year in one system does not remove it from the other. Adding a year does sync: when someone fills in the year on a birthday that had none, the other system gets the full date. (Version 2.8.0 and later. Older versions could copy 1885 into Rock as a real year.)
  • PCO can reject an email address (some domains are disallowed). If it does, the sync logs a warning with the person's name and a link to their Rock profile, keeps everything else syncing, and repeats the warning each run until the address is corrected in Rock.

When something is removed in Planning Center

Delete or archive a team (or folder, or service type) in PCO and its Rock group is marked inactive on the next run — never deleted, and it reactivates automatically if the PCO item comes back. Once a group is inactive, it stops syncing. If you're sure it's gone for good, you can delete the inactive group whenever you like.

One caution: this automatic cleanup only covers groups that came from a Folder Import, and only while Refresh Group Structure is on. A group you connected by hand, or one imported on an older plugin version, can stay active after its PCO team is archived — and while it stays active, the sync keeps pulling in whoever Planning Center still shows assigned to that team's positions (PCO keeps those assignments on archived teams). If people from an archived team ever show up in a sync run, look for a still-active Rock group connected to that team: mark it inactive (or clear its PCO Marker), and clear the leftover position assignments in Planning Center.

The reverse also works as an off switch: mark a Rock group inactive to stop it syncing without disconnecting anything.

When a person is removed in Planning Center

By default, removing someone from a synced team position or tag in PCO removes them from the mapped Rock group on the next run (Rock archives the membership instead when the group type keeps history).

Prefer to keep the roster visible in Rock? Turn on Inactivate Instead of Remove in the job settings. Then:

  • The membership is marked Inactive instead of removed. On team groups the position boxes stay checked on the inactive record, so you can see what the person used to hold.
  • Setting the member back to Active in Rock puts them back in PCO — same team and positions, or the tag — on the next sync.
  • If PCO re-adds the person first, the sync reactivates the existing inactive membership rather than creating a duplicate. Their positions reset to what PCO now says, so a position that was deliberately removed earlier doesn't sneak back.
  • Rock person tags are unaffected either way — a tag removed in PCO is still removed from the person in Rock, because tags have no inactive state.

One caution for groups mapped to tags in a single-choice PCO tag group: inactive memberships accumulate as people move between the sibling tags, and reactivating someone in group A while PCO still has them in sibling tag B won't switch the tag — PCO's current tag wins and a warning repeats each run (see Warnings That Repeat). To move someone from the Rock side, activate them in the new group and inactivate or remove them in the old one before the next sync.

Monitoring & Maintenance

Sync History is your window

PCO V2 → Sync History lists every run. Click into one to see each operation (who changed, what changed, which system the change came from) and any errors or warnings. When a run is Awaiting Review, this is where you approve or cancel it. Approving applies the whole run — there's no picking and choosing rows, so if part of a proposal is wrong, cancel, fix the cause, and re-run. The operations grid has the standard Excel export, which is handy for reviewing a big proposal offline and for keeping a record: housekeeping permanently clears cancelled and completed runs about two weeks after they ran (a run waiting for review is never auto-cleared).

Warnings that repeat until you fix the data

Some warnings describe a genuine data conflict only a human can resolve — so they repeat on every run, on purpose, until someone fixes the underlying record:

  • Multiple tags in a single-selection PCO tag group → remove the extra tag from the person in Rock.
  • PCO rejected an email address → correct the address on the person in Rock.
  • One Rock person is linked to multiple records in the connected system → the person has duplicate records in Planning Center (one may be hidden or archived there). Merge the duplicates in Planning Center — merging the people in Rock will not resolve it.

These warnings include the person's name and a direct link to their Rock profile, so resolving them is usually a one-minute job. Your Notification Group sees them too.

A sensible routine

  • After any run pauses for review: look at what tripped it before approving. A mass change is sometimes intentional (you re-organized PCO) and sometimes a mistake worth catching.
  • Weekly-ish: glance at Sync History for repeating warnings and clear them.
  • PCO V2 → Synced Persons shows exactly who is linked and to which PCO record — the place to check when you suspect a wrong match or duplicate.

Replacing a Planning Center account or token

Every group, tag, person and campus mapping remembers which PCO account it belongs to. If you delete an account on PCO V2 → Manage Accounts and add it again (for example with a new Personal Access Token), the old mappings still point at the old account and those groups and tags stop syncing. Editing the existing account instead keeps them working, so prefer that when you change a token.

If it has already happened, Manage Accounts shows a warning panel, Mappings for a Planning Center account that isn't set up (version 2.8.0 and later). Pick the old account id under Mapped To (Not Set Up), the account to move them to under Move To, and click Move Mappings. Before moving anything, the plugin looks up a few of the linked people with the new account; if none of them exist there, it's a different Planning Center organization and nothing is moved. When the account you add is your only account and there's just one old account id, the mappings move automatically when you save.

Deleting an account asks for confirmation and says how many group, tag, person and campus mappings still belong to it.

Licensing, Trial & Connectivity

  • New installs get a 14-day trial. The setup wizard's 9 Embers step has a "Skip for Now (Start 14-Day Trial)" option — with no key entered, the sync runs normally for 14 days from its first run, and each run completes with a Warning showing the days remaining. Enter your key any time on the Job Configuration Assistant; when the trial expires the job stops until you do.
  • Subscribed installs are verified every run. If the 9 Embers server can't be reached (outage, network), your sync keeps working for 7 days from the last successful check — completing with a Warning and a countdown — then pauses until verification succeeds again. A brief 9 Embers outage will never stop your nightly sync.
  • "Organization could not be authenticated" means the server was reached and said no — check your subscription status with 9 Embers.

Quick Answers

SituationWhat's going on
"I added someone to a team group and they never appeared in PCO."No position is checked on their membership. Check at least one position or Team Leader.
"A new position I created in PCO isn't in the checkbox list yet."It appears after the next sync run (the run also syncs anyone already assigned to it).
"A team group suddenly went inactive."The team was deleted or archived in Planning Center. It reactivates automatically if the team returns.
"People from an archived PCO team showed up in a sync run."A Rock group connected to that team is still active. Mark it inactive (or clear its PCO Marker) and remove the leftover position assignments in Planning Center.
"The job finished with a Warning."Read the message — trial countdown, a 9 Embers connectivity grace period, or a per-person data conflict. The sync itself completed.
"The job says another sync is already running."Two runs overlapped (e.g. Run Now during a scheduled run). The second skipped safely; nothing to do.
"The same warning shows up every run."It's a data conflict waiting for a human — the message names the person (with a profile link) and the fix.
"Birthdates in Rock changed to 1885."1885 is Planning Center's placeholder for a birthday with no year, and versions before 2.8.0 could copy it into Rock as a real year. Update the plugin, then enter the real year in Rock wherever you know it; it syncs to Planning Center. Recent runs on Sync History show the old values.
"Groups or tags stopped syncing after we re-added our PCO account."The mappings still point at the old account. Use Move Mappings on Manage Accounts (see Replacing a Planning Center account or token).
"Someone shows twice in Planning Center."Duplicate PCO profiles. Merge them in PCO (keep the original), and the sync reconciles its links on the following run.
"I want a group to stop syncing."Mark the Rock group inactive (reversible), or clear its PCO Marker attribute (disconnects it).

For duplicate-record errors, fatal request errors, and bulk group cleanup, see the FAQ in the installation guide — and the Plugin Support Form is always available.