MINISTRYPLATFORM CUSTOM WIDGET
Personnel Directory — Installation Guide
A searchable directory of the people who serve your diocese — clergy, staff, religious, or any mix — showing each person's photograph, primary role and location, phone number and email address, with their other current assignments listed beneath. Public or behind a login, whichever suits.
This guide assumes you have read Getting Started. It is the third page in the Organization Directory suite, alongside the Organization Directory and its detail page.
What the page does
The widget reads current Personnel records, joins each to its Contact for the name and contact details, and works out one primary assignment per person for the role and location shown at the top of the card. Everything else current appears under Other Assignments.
- Search — narrows as the visitor types, matching name, role, location, category and the other assignments.
- Category selector — appears only when more than one Personnel Category comes back, so a clergy-only page is not cluttered with a control that does nothing.
- Clickable contact details
— the phone number is a
tel:link, the email amailto:link, both with the same icons the rest of the suite uses. - Linked organizations — each location links through to the Organization Detail page when you configure it.
- Photographs — from the DEFAULT file on the Contact record. Anyone without one gets their initials in a brand-coloured circle, never a broken image.
Read this before you publish it
Decide public or private deliberately.
requireLogin: false
publishes names, roles, phone numbers and email addresses to anonymous visitors, and anything on a public page can be harvested. A diocesan clergy list with office numbers is normal and useful. A full staff list with mobile numbers is not. Set requireLogin: true
and the page stays hidden until a parishioner signs in, and belongs alongside the site's standard MP Login widget.
Choose the phone source with that in mind. The three options are the Contact's Company Phone, the Location Phone of the primary assignment, or the Contact's Mobile Phone. Publishing mobile numbers to an anonymous page is rarely what anyone intends.
Company Phone is frequently empty.
It is empty for every Contact on the demo instance. Rather than publish blank cards the procedure falls through to the other sources and reports what it used in a Phone_Source
column. Where the number matters more than the completeness, set phoneStrictSource: true
and anything obtained by falling back is dropped instead.
Primary_Assignment is not unique in practice. Several clergy on the demo instance carry two assignments both flagged primary. Taken literally that lists the same person twice, so the procedure ranks them and takes one: flagged primary first, then open-ended before dated, then latest start, then lowest ID. Everything else current becomes an other assignment. If someone's card names an unexpected parish, that ranking is why, and the fix is on the assignment records rather than in the widget.
What you need before starting
SQL Server Management Studio access, edit access to the website, and the three files below.
-
deploy_PersonnelDirectory.sql— creates and registers the procedure. -
deploy_PersonnelDirectory_photos.sql— run second; adds photographs from each Contact's DEFAULT file attachment. -
personnel-directory-embed.html— the front end.
The embed downloads as a .txt
file.
The content management system will not serve an .html
attachment, so it is published as personnel-directory-embed.html.txt
. The contents are unchanged — open it in a text editor, or save it as personnel-directory-embed.html
if you prefer. Nothing needs editing before you paste it, beyond the configuration block.
If you do not have a dedicated hosting plan or the required SQL Server skills, reach out to the professional services team for assistance. Normal hourly rates will apply.
Step 1 Run the database scripts
Open each in SSMS, confirm the database dropdown shows the MinistryPlatform database and not master
, and execute it. Run them in order — deploy_PersonnelDirectory.sql
first, then deploy_PersonnelDirectory_photos.sql
— because the photos script replaces the procedure the first one creates. Running them the other way round loses the photograph column.
The first script creates dbo.api_custom_PersonnelDirectory
, registers it in dp_API_Procedures
, and links it to the Administrators role in dp_Role_API_Procedures
. That role link is the step most often missed.
The API checks role links, not SQL permissions.
Personnel
is a secured record type in MinistryPlatform.
It carries salary, benefits, citizenship and passport fields, none of which this procedure selects. If your security team asks, the procedure returns name, category, role, location, one phone number and one email address, and nothing else.
Read verification queries 4e and 4f before configuring
The script ends with two queries listing the Personnel Categories and Alternate Email Types on your instance, each with a count. Use those IDs rather than any in this guide — a stock instance ships Catechist, Clergy, Religious, Staff, Volunteer and Seminarian, but only the ones actually in use are worth putting in the configuration.
Step 2 Verify the API can reach the procedure
https://yourdiocese.cloudapps.ministryplatform.cloud/sky/api/CustomWidget?storedProcedure=api_custom_PersonnelDirectory
You should see JSON with two result sets: DataSet1
, one row per person, and DataSet2
, their other assignments.
Watch the Phone_Source
column in the response.
If most rows read Location (fallback)
or Mobile (fallback)
, the source you intended is not populated on your instance. If they read None
, nobody has any phone number at all.
Testing with parameters by hand needs spParams
, with %26
between parameters:
...?storedProcedure=api_custom_PersonnelDirectory&spParams=@PersonnelCategoryIDs=2%26@PhoneSource=2
Appending &@PhoneSource=2
on its own does nothing — the API ignores it and returns the defaults, which looks exactly like a setting having no effect.
Step 3 Add the page and configure it
Create a page and add the whole of personnel-directory-embed.html
into a single HTML embed. Everything an administrator touches is in the PN_CONFIG
block at the top.
| Setting | What it does |
|---|---|
dataHost
|
Required. Your MP host prefix. |
requireLogin
|
true
hides the directory until the visitor signs in. Put such a page alongside the site's MP Login widget. |
personnelCategoryIDs
|
Who is listed. ""
for every category, "2"
for clergy only, "2,4"
for clergy and staff. From query 4e. |
congregationIDs
|
Restrict to people whose primary assignment is at these Congregations. ""
for the whole diocese. |
phoneSource
|
1
Company Phone, 2
Location Phone of the primary assignment, 3
Mobile Phone. |
phoneStrictSource
|
true
publishes nothing rather than falling back to another source. |
alternateEmailTypeID
|
Prefer an Alternate Email of this type over the Contact address, falling back where a person has none. ""
always uses the Contact address. From query 4f. |
organizationDetailURL
|
Makes each location a link to the Organization Detail page. Everything up to the identifier; the Congregation ID is appended. ""
renders plain text. |
pageTitle
, pageIntro
|
Overrides for the derived wording. |
brandColor
, brandColorDark
|
Accent colours. |
showPhotos
, fileBaseUrl
|
Photographs. Needs the photos script. |
debug
|
Logs the widget's activity, and a tally of which phone sources were actually used, to the browser console. |
The title writes itself.
Leave pageTitle
blank and one or two categories give "Clergy Directory" or "Clergy and Staff Directory"; three or more give "Personnel Directory".
organizationDetailURL
only produces a link where there is a Congregation ID to send.
A location whose record has none stays plain text rather than sending visitors to a "we could not find that record" panel.
Step 4 Test
- Open the page. You should see the toolbar, a count line and one card per person.
- Check the heading names the categories you configured.
- Search for part of a name, then a role, then a parish name. All three should narrow the list.
- If you configured more than one category, use the selector, then Reset.
- Click a phone number on a phone. It should dial. Click an email. It should open a compose window.
- Click a location. It should open the Organization Detail page for that organization.
- Check somebody with more than one assignment. The extras should be listed under Other Assignments.
- If
requireLoginis true, open the page signed out. You should get the sign-in panel, and the list should appear once you sign in. - Set
debug: trueonce and read the console tally of phone sources. Then set it back tofalse.
MinistryPlatform configuration
| Field | Requirement |
|---|---|
| Personnel → Personnel Category | Required, and drives the filter, the selector and the derived title. |
| Personnel → End Date, Termination Date | Both are honoured. A person with either in the past drops out of the directory. |
| Personnel Assignments → Primary Assignment | Marks the role and location shown at the top of the card. Where more than one is flagged, see the ranking note above. |
| Personnel Assignments → Assignment End | Used as the "still current" test: empty or in the future counts as current. Historic assignments are excluded automatically. |
| Personnel Assignments → Assignment Role, Location | The role and location shown. A location supplies the Location Phone option and the link to Organization Detail. |
| Contacts → Company Phone, Mobile Phone, Email Address | The contact details. Company Phone is often empty; see the note above. |
| Alternate Emails | Optional. Lets you publish a diocesan address rather than a personal one. |
| dp_Files on the Contact | Optional photograph, flagged DEFAULT in the Files panel. |
Check the photographs in a private window.
Paste one of the GUIDs from the photos script's verification output into https://{host}.ministryplatform.net/ministryplatformapi/files/{GUID}
in a private browsing window. In a normal window you are probably signed in to the Platform, which hides the fact that a file is unreachable by an anonymous visitor.
Troubleshooting
Nobody is listed.
Either no Personnel record is current, or personnelCategoryIDs
names a category nobody is in. Query 4e reports the current count per category.
Everyone's phone number is missing, or is not the one I expected.
Read Phone_Source
in the API response. A (fallback)
value means the source you chose is empty for that person; None
means they have no number at all. Company Phone being empty across the board is common.
Somebody appears twice.
They should not — the procedure collapses multiple primary assignments to one. If it happens, there are two Personnel records for the same person rather than two assignments.
Somebody's primary parish looks wrong.
They have more than one assignment flagged primary and the ranking picked the other one. Correct the assignment records; the widget will follow.
A location is not a link.
Either organizationDetailURL
is blank, or that assignment's Location has no Congregation, so there is no ID to link to.
The page shows the sign-in panel when I am already signed in.
The page is missing the site's standard MP Login widget, or its URL is not on the permitted list you asked support to whitelist. Both produce the same symptom.
"Procedure … does not exist or user does not have access to it."
Almost always the role link in dp_Role_API_Procedures
. If the verification queries all pass, see If the script succeeded but the API still doesn't see it
in Getting Started.
Photographs do not appear.
Confirm you ran deploy_PersonnelDirectory_photos.sql
after the main script, and check its verification output for NO DEFAULT FILE
. A contact with no attachment, or one not flagged DEFAULT, falls back to initials.
Attribution
Built on the MinistryPlatform Custom Widget framework ( MPCustomWidgets).