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.0.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:

• Primary Database Source — used only to break ties when the same field changed in both systems between syncs. 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.

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.
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.
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

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. Over the limit → pauses in Awaiting Review and notifies you.
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.

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. Two 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.
• 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 a person 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. Inactive groups stop syncing entirely. If you're sure it's gone for good, you can delete the inactive group whenever you like.

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 removs 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 Inactive 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 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 site, activate them in the 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.

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.
• 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.

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

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.