Setup guide

Before you start

• Lightning Experience is turned on.
• You know which objects hold your NPIs (for example Contacts, Accounts, or your own Providers or Locations objects) and which fields on them hold the NPI. An object can hold several NPI fields.
• Your org can reach data.cms.gov. The CMS list is public and needs no login or key.
• The person who schedules the nightly run (Step 3) must be able to see the NPI records, because the run uses that person's access. They need read access to each mapped object, read access to every NPI field and to the status field you filter on, and, if your sharing settings are private, access to all the records you want checked. A record that person cannot see is silently not checked.

Step 1: Install

Install the package for Admins Only, then open the Ziurta CMS Sync app from the app launcher.

Step 2: Give people access

Assign the permission sets from each person's own user page:

1. Open Setup > Users > Users and click the person's name.
2. In Permission Set Assignments, choose Edit Assignments.
3. Move CMS Sync Admin (or CMS Sync User, the permission set named CMS Sync Viewer in older versions) into Enabled Permission Sets, then Save.

(You can also use Setup > Permission Sets > CMS Sync Admin > Manage Assignments > Add Assignment. In a new org, its user list can look empty. Salesforce shows only the list view you pick under Select a List View, and a new org may have only Recently Viewed, which is empty until you have opened some users. The steps above avoid this.)

Check the connections once. In Setup > Named Credentials > External Credentials, open CMS Sync API Credential and CMS Sync NPPES API Credential. The principal of each is covered by the CMS Sync Admin permission set, so any user with that set can call CMS (due dates and reassignments) and the NPI Registry (NPPES details). If a run later fails with a credential message, start here. If only the NPPES step reports a credential problem, check the second credential; the rest of the sync does not depend on it.

Step 3: Choose who will schedule the nightly run

Salesforce runs a scheduled job as the person who scheduled it, which is whoever chooses Schedule on the Sync Setup tab in Step 6. That person must stay active in your org. If they are deactivated, the nightly run stops. The Sync Setup tab warns you when this happens, and the Sync Runs tab stops getting new entries. So have an administrator schedule it who is unlikely to leave or change roles. This guide calls that person the scheduling user.

The scheduling user also decides what the run can see, so they need:

• the CMS Sync Admin permission set, which also gives the connection to CMS;
• read access to each object you map, and to every NPI field and the status field you filter on;
• access to all the records you want checked. If your sharing settings are private, an administrator who can see all data is the simplest choice;
• edit access to any lookup fields you add yourself.

A System Administrator usually has all of this already. If that person leaves, have another administrator with the same access log in and choose Schedule again. That replaces the old schedule. The Ran As column on the Sync Runs tab shows who each run ran as, and the Sync Setup tab shows who the schedule runs as.

Step 4: Tell it where your NPIs are

Open the Sync Setup tab and find Where NPIs come from. Choose Add mapping. You make one mapping for each object that holds NPIs.

How many mappings? Most orgs need one to three, and one mapping can use several NPI fields on the same object. The sync is built and tested for that range. Each active mapping adds one query to every step of the nightly run, so a very long list of mappings, especially on objects where the same NPI appears on many records, can hit a Salesforce limit. If that happens the run log says a lookup step failed, nothing is marked as not listed, and the NPIs are retried the next night. If you need more than about 20 mappings, contact support@ziurta.com before adding them.

1. Object that holds NPIs. Pick it from the list.
2. Fields that hold an NPI. Move every field on that object that holds an NPI into the right-hand list. If a Locations object has separate DME, FQHC and RHC NPI fields, move all of them. Text and long text fields are offered.
3. Only include active records. Under Filter on this field, choose the field your team uses to mark a record active, then the value. This keeps NPIs of inactive providers out, so they never create NPI Checks or enrollment records. It can be a standard field (such as Is Active) or your own (such as Status). A checkbox offers true or false, and a picklist lets you choose one or several values. In a text field, separate several accepted values with a semicolon, for example Active;Provisional. Leave it on No filter: use every record to check every record. Records already saved for someone who later becomes inactive are kept, but they stop being refreshed.
4. CMS Enrollment Records link to. Choose the lookup field that points at this object. The results then appear as a related list on that object's pages. Contact and Account are ready to use. For any other object you add the lookup once (see below).
5. NPI Checks link to (optional). The same idea, so a page can also show NPIs that CMS had nothing for. 5a. Assign enrollment ownership from. Each CMS Enrollment Record is owned by the person who owns the matching record in your org, so work can be sorted and reported by owner. The default is the record's own owner. If your object has a lookup to a user, such as a coordinator, choose it here instead. A person can reassign an enrollment by hand at any time (the record's owner, a manager above them in the role hierarchy, or an administrator), and the sync never overwrites that. Until someone does, it follows the source record's owner. An inactive owner, or one without the CMS Sync User permission set, is skipped, and the run log says how many. 5b. NPPES Records link to (optional). Choose the lookup on NPPES Record that points at this object, so each record shows the NPI Registry details (name, taxonomy, addresses) as a related list on its pages. Contact and Account are ready to use. For any other object you add the lookup once (see below). Leave it on No link if you only want the NPPES section on enrollment records.
6. Choose Test mapping. It counts the records that hold an NPI (an exact total), and, in the first 2,000 of them, the valid NPIs, values that are not valid NPIs, values with spaces or hyphens, and NPIs that appear on more than one record. Nothing is saved.
7. Choose Save.

If your object has no lookup yet. The form tells you. Add it once:

If your object has no NPPES Record lookup yet. Add it the same way: Setup > Object Manager > NPPES Record > Fields & Relationships > New > Lookup Relationship, choose your object, and continue. On the field-level security step, give the scheduling user's profile edit access to the field (or grant it in your own permission set), and give the people who will see it read access. Then reopen the mapping and choose it under NPPES Records link to. The nightly run fills the lookup, one night after the NPPES Record is first saved.

Setup > Object Manager > CMS Enrollment Record > Fields & Relationships > New > Lookup Relationship, choose your object, and continue. On the field-level security step, give the scheduling user's profile access to the field and make it editable. If your org uses permission sets for field access instead, create your own permission set that grants edit access to the new field and assign it to the scheduling user (and read access for your viewers). Return to the form and choose Re-check.

NPIs should be plain digits. An NPI stored as 1234-567893 is still looked up, but cannot be linked to its record until the field holds only digits. The run log counts these. Spaces at the start or end are removed by Salesforce itself.

Step 5: Show the results on your pages

Salesforce does not let a package change your page layouts, so do this once for each mapped object. The Sync Setup tab lists each mapped object under Show the results on your pages, with a button that opens that object's page layouts and the exact steps.

1. On the CMS Enrollment Record page. Setup > Object Manager > CMS Enrollment Record > Page Layouts > CMS Enrollment Layout. Drag your lookup field into the Linked Records section, then Save.
2. On your object's page (for example Service Location). Setup > Object Manager > your object > Page Layouts. In Related Lists, drag CMS Enrollment Records onto the layout. Use the wrench icon on that related list to choose its columns. We suggest Enrollment State Code, Provider Type Text and Revalidation Due Date.
3. Optional. If you also chose an NPI Checks link to field, add the NPI Checks related list the same way. It shows NPIs that CMS had nothing for.

The NPI Check and CMS Enrollment Record pages come with the CMS Reassignments related list already on them. If you changed either layout before installing a version that includes reassignments, Salesforce keeps your layout as it was, so add CMS Reassignments to it yourself the same way (and CMS Reassignments to This Organization on the CMS Enrollment Record layout).

1. Optional. If you chose NPPES Records link to for an object, drag the NPPES Records related list onto that object's layout the same way. It shows one row: the NPI Registry name, status, taxonomy and address for that record's NPI. Use the wrench icon to choose its columns.

The CMS Enrollment Record layout comes with the NPPES Record section, and the NPI Check layout with its NPPES Record link and NPPES Status. If you customized either layout before installing a version that includes NPPES, Salesforce keeps your layout as it was, so add the NPPES Record section's fields (the ones starting with "NPPES") and the NPPES Record and NPPES Status fields on NPI Check yourself.

Optional: add your own pages to the app's navigation

The Ziurta CMS Sync app shows only our own tabs: CMS Enrollment Records, NPI Checks, Sync Runs, Reports, and Sync Setup. It leaves out your own objects (for example Hospitals, Providers or Service Locations) because every org is different. Anyone can add them to their own view of the app:

1. Open the Ziurta CMS Sync app.
2. At the right end of the navigation bar, choose the pencil icon (Edit Navigation Items).
3. Choose Add More Items, search for your object (or Accounts, Contacts, or any other tab), select it, then Add and Save.

This changes only that person's own view. If you want every user to see the same navigation, create your own app instead: Setup > App Manager > New Lightning App, add our tabs and yours, and assign it to the profiles you choose. Our app stays as it is.

Step 6: Run it

On the Sync Setup tab:

• Run now starts a run immediately. Use it the first time, and after you clean up data.
• Pick a time under Run every day at and choose Schedule. Do this while logged in as the scheduling user from Step 3; the run will run as you. The tab then shows who it runs as. Stop schedule ends it.

A run works in six steps: it collects the NPIs from your mappings, asks CMS about them in batches (due dates and reassignments), asks CMS which individuals are reassigned to each stored organization enrollment (one organization at a time, so this step is slower on rosters with many organizations), asks the NPI Registry (NPPES) about NPIs that have no NPPES Record yet or whose record is more than 30 days old (about 50 at a time, up to 5,000 NPIs per run), and then marks any stored enrollment or reassignment that CMS no longer returns as "not listed". The last two steps only happen after a run with no errors. Large rosters take longer; watch Sync Runs for the result and for the NPPES Records Saved, NPPES Not Found and NPPES Failed counts.

The first run asks NPPES about every NPI, at roughly 100 NPIs a minute, so 3,000 NPIs take about half an hour in that step and a very large roster spreads over several nights. Later runs only refresh records older than 30 days. A problem in the NPPES step shows as Succeeded with warnings and never stops the CMS results.

Only one run goes at a time. If a run is still going when tonight's starts, tonight's start is skipped. A run that never finishes stays labeled Running in the log, but after six hours it no longer blocks the next one.

Your plan

Plans are sized by NPIs: the number of distinct, valid NPIs a run finds in your active NPI Sources. The top of the Sync Setup tab shows your plan and how many NPIs the latest run found. Each Sync Run also records the number as NPIs Found.

• Trying it in a sandbox, or without a plan. The sync checks the first 50 NPIs, in NPI order, and tells you how many more it found and which plan would cover them all.
• With a plan. Every NPI is checked, always. If you grow past your plan, nothing stops; Sync Setup shows a notice, and your subscription renews on the plan that fits your NPI count 30 days before your renewal date.
• Keeping the count down. Only records your NPI Sources include are counted. A status filter on a source (Step 4) leaves inactive providers out of both the sync and the count.

NPPES details for every NPI

The nightly run also asks the NPI Registry (NPPES) about each NPI the sync tracks and keeps what it holds as an NPPES Record: name, credential, status, both addresses, phone numbers, the primary taxonomy, and (as readable lists) every taxonomy, other practice location, identifier, other name and endpoint. An NPI that has no NPPES record is marked Found in NPPES unchecked, and details already saved are kept. A deactivated NPI shows its status and deactivation date.

• On a CMS Enrollment Record, the NPPES Record section shows the main details (name, entity type, status, credential, primary taxonomy, addresses, phone, authorized official, dates). They read through the NPI Check, so they appear after the NPPES step has run for that NPI. The NPPES Name is a link that opens the full NPPES Record, with every address, taxonomy, identifier, other name and endpoint. The NPI Check also has an NPPES Record link.
• On your own objects: in a mapping, choose NPPES Records link to (Contact and Account are ready; for another object add a lookup on NPPES Record pointing at it, as you did for CMS Enrollment Records). The record then shows as a NPPES Records related list on that object's pages (use the page helper on Sync Setup). The link is filled by the nightly run, one night after the NPPES Record is first saved.
• Pace and age: each NPI is checked when it has no NPPES Record yet and again once its record is more than 30 days old, up to 5,000 NPIs per run, so a large first load spreads over several nights. To change them: Setup > Custom Metadata Types, find Sync Configuration, choose Manage Records, open Default, choose Edit, and set NPPES Refresh Days (how old a record must be before it is checked again) and NPPES Max NPIs Per Run. Leave them blank for 30 days and 5,000.
• Access: only NPIs are sent, to npiregistry.cms.hhs.gov, which the CMS Sync NPPES API Credential (covered by CMS Sync Admin) allows. If NPPES says to slow down, the rest of that run's NPPES step is skipped and the run log says so; the NPIs are retried next run.
• Names from NPPES arrive in capital letters. The Display Name is Title Case; credentials and organization names are left exactly as NPPES sends them.
• Copying into your own fields (writing NPPES values into Contact or Provider fields) is planned for a later version.

Working the list

The Needs attention view is the team's to-do list: listed enrollments that are Not Started and past due or due within 180 days. My revalidations shows the records you own that are Not Started or In Progress and due within 180 days (a record you have started stays on it until you mark it Complete). Open a record, or edit the Revalidation Status column straight in the list, and choose:

• In Progress when someone has started.
• Complete when it is done.
• Not Ours when your organization does not manage it.

Use Revalidations by Owner and Status on the Reports tab to see work by owner, and the Revalidation Overview dashboard, opened from the Home tab, for the whole picture.

A board view. To work the list as cards, open Needs attention or My revalidations, choose the display control (the table icon at the top right of the list), then Kanban, and group by Revalidation Status. Drag a card between Not Started, In Progress and Complete to change its status. This is a display setting you switch on yourself; it is not saved in the package. To hand a record to someone else, use Change Owner on it; the sync keeps your choice.

Adding a case or an assignee. The package does not ship a Case field, because not every org uses Cases. To link a case, go to Setup > Object Manager > CMS Enrollment Record > Fields & Relationships > New > Lookup Relationship, choose Case (or Task, or your own work object), and add the field to the page layout and to a list view. Your own lookup works as a filter, for example "Case equals nothing" to find records with no case yet. The same steps add a "Coordinator" lookup to User if you want a person separate from the owner.

Reading the results

What the fields mean

• Revalidation Status is how your team tracks the work: Not Started (nobody has started), In Progress, Complete, or Not Ours (your organization does not manage this revalidation). Each new record starts Not Started. The sync sets it back to Not Started when CMS publishes a different due date, because that is a new cycle. A cleared date, or an enrollment that comes back with the same date, changes nothing.
• PECOS, CMS I&A and NPPES NPI Registry are links in the Revalidation Processing section. PECOS is where a revalidation is submitted, CMS I&A manages users and their PECOS access, and the NPI Registry link opens the public page for this record's NPI. They open in a new tab; PECOS and I&A are login pages, so they cannot open on a single provider.
• Revalidation Due Date is the date CMS lists. CMS keeps old dates until it publishes the next one, so many records show past-due dates.
• Adjusted Due Date is filled only if CMS provides one. It is blank today.
• Earliest Due Date (on the NPI Check) is the earliest date among that NPI's enrollments, past due included.
• PAC ID (PECOS Associate Control ID) is a number CMS assigns to each provider or organization in Medicare's enrollment system. It stays the same across all of that entity's enrollments and NPIs. CMS sometimes drops leading zeros.
• Is Listed is cleared, with a date, when CMS stops returning an enrollment. It does not mean the provider revalidated.
• Treat the fields the sync writes as read-only. The page layout marks them read-only, but administrators can still edit them, and the sync replaces its own fields whenever CMS returns the row.

Run results: Succeeded; Succeeded with warnings (read the messages); Completed with errors (some NPIs were not checked and are retried the next night, and nothing was marked "not listed"); Failed (the run could not start, with the reason).

If something is not right

What leaves your org

Only NPIs are sent, in web requests to data.cms.gov for the due date list and the reassignment list, and to npiregistry.cms.hhs.gov for the NPPES details. NPIs are public identifiers. No other record data leaves your org, and the CMS list is public data.

Need help or more?

Questions, problems, or something not working: support@ziurta.com. Include the run log message and, if you can, the NPI involved. Please do not send patient or other personal information.

Something built around this data, such as creating a Case or task as a due date approaches, routing work to a team, or custom reports and dashboards: Ziurta offers customization as a project. Contact: salesforceproject@ziurta.com.