Milestone Tracker — Installation Guide

A login-protected page that shows a parishioner their progress through a MinistryPlatform Journey. Each step in the journey appears as a milestone: completed steps show a green check and the date achieved, while steps still to do show an empty box and — when there is an online form or event to complete them — a Get Started button that takes the parishioner straight to it. When a linked form is submitted, the milestone can be recorded automatically, with no staff data entry.

The Tracker comes in two versions that install together from one set of files. The Individual version shows the signed-in parishioner their own milestones; the Family version shows every member of the signed-in parishioner's household, each in their own section. You deploy both with the same steps below and simply embed whichever page(s) you want.

Built on the MinistryPlatform Custom Widget framework, with a login gate that matches the one used by the "My Household" widget.

Throughout this guide we use the Confirmation Preparation journey as the worked example, but nothing here is Confirmation-specific — the Milestone Tracker works with any Journey and its Milestones. Wherever you see a Confirmation value (the journey, the group, the milestones, the forms), substitute your own. See "Using a different Journey" near the end.

What you need before starting

You will need SQL Server Management Studio access to the MinistryPlatform database, edit access to the church website, an existing Journey with its Milestones defined, and a Group whose current participants are the people on that journey. The Tracker takes the parish (Congregation) from that group, so people can complete their journey at a parish other than their home parish.

The following files ship with this guide. Run them in the order shown (database scripts first, web pages last):

All scripts are safe to re-run: they use CREATE OR ALTER and IF NOT EXISTS guards so a second run won't create duplicates.

If you do not have a dedicated hosting plan or don't have the required SQL Server skills, reach out to the professional services team for assistance. Normal hourly rates will apply.

Step 1 — Create the mapping table and its page

Open each script in SSMS, confirm you are connected to the MinistryPlatform database(not master — check the database dropdown), and execute it.

Run create_Milestone_Forms.sql to create the Milestone_Forms table. A row in this table says "for this Congregation, this Milestone is completed via this Form and/or this Event." Both the Form and the Event are optional. The script also brings an already-existing table up to date automatically.

Then run register_Milestone_Forms_Page.sql to add the Milestone Forms page to the Platform. Note that this only defines the page — until it is added to one or more security roles, it will not appear in the navigation menu for any user. Once the page is defined, grant access to each role that should see it, as appropriate: in the Platform go to Administration → Security Roles → (the role) → Pages, add "Milestone Forms" to a navigation section (the same one as Milestones/Journeys is a good home), and grant rights. Repeat for every role that should have access.

Step 2 — Deploy the display procedures (Individual & Family)

Run both deploy_JourneyMilestonesIndividual.sql and deploy_JourneyMilestonesFamily.sql . Each one does three things, all required:

  1. Creates the read stored procedure ( dbo.api_custom_JourneyMilestonesIndividual_JSON or dbo.api_custom_JourneyMilestonesFamily_JSON ), which returns a journey's milestones along with the signed-in user's completion status and the correct form/event link for the parish.
  2. Registers the procedure in dp_API_Procedures so the MinistryPlatform API is allowed to call it.
  3. Links the procedure to the Administrators security role in dp_Role_API_Procedures . This step is easy to miss, and the page will not load without it — the API checks role links, not SQL permissions.

Each script ends with verification queries that should each return a row ("Proc exists", "API registered", "Role linked").

Step 3 — Deploy the automatic milestone recording

This step lets a submitted form record its milestone with no staff action. Run create_proc_FormResponse_CreateMilestone.sql first (it creates the procedure), then create_Process_FormResponseMilestone.sql (it creates the Process and its step). Together they create a Process named Form Response – Create Milestone that fires when a Form Response is created and, if the submitted form is mapped in Milestone_Forms , records the milestone for that participant.

Important — the Process Manager service. Automatic execution depends on the MinistryPlatform Process Manager service running on your server; that is what actually executes a Process step. If milestones are not being created after form submissions, confirm that service is active. The display pages (Steps 2 and 5) work regardless — this step only affects automatic recording.

Step 4 — Map your milestones to forms and events

Open the Milestone Forms page and add one row for each milestone a parishioner completes online. For each row choose the Congregation(the parish running the journey), the Milestone, and either a Form or an Event:

  • Form — the online form that completes the milestone (for example, "Declare Sponsor and Choose Confirmation Name").
  • Event — use this when the milestone is completed by attending an event, such as a retreat. If a row has both, the page links to the Event.

One requirement for automatic recording: a mapped Form must have a Program assigned (a milestone record requires a Program, and the Program is taken from the form). If a mapped form has no Program, the automation from Step 3 flags it for an administrator rather than creating the milestone. Set a Program on each form used in a mapping.

Step 5 — Add the web page(s)

Create a login-gated page on the website for each version you want and add an HTML embed containing the full contents of journey-milestones-individual.html and/or journey-milestones-family.html . All the settings an administrator normally touches live in one place: the JOURNEY_CONFIG block at the very top of each file — you should not need to hunt through the rest of the code. The settings are identical across both versions:

 const JOURNEY_CONFIG = {
  dataHost:   "yourprefix",   // the part of your Platform URL before .ministryplatform.net
  journeyId:  18,             // the Journey to display (Journeys.Journey_ID)
  groupId:    136,            // the group whose participants are shown; its
                              //   Congregation is the parish used for links
  formBaseUrl:      "/your-form-page?id=",          // form GUID is appended automatically
  eventDetailsPage: "/your-event-detail-page?id=",  // Event ID is appended automatically
  requireLogin: true,
  pageHeading:  "My Confirmation Journey",          // Family version: "Our Confirmation Journey"
  showAllGetStartedButtons: true   // false = show a button only on the next step
};
  • dataHost — your MP host prefix (the part of your Platform URL before .ministryplatform.net ), e.g. "catholicdemo" .
  • journeyId — the Journey_ID to display. Change this to point the Tracker at any journey.
  • groupId — the group whose current participants are shown. Its Congregation is used as the parish when resolving form and event links. (On the Individual page this also limits the view to members of that group.)
  • formBaseUrl/ eventDetailsPage — the base URLs of your form page and your event-detail page. The form's GUID or the event's ID is appended automatically to build each "Get Started" link.
  • requireLogin — leave true so the list stays hidden until a parishioner signs in.
  • pageHeading — the heading shown above the list.
  • showAllGetStartedButtons — true shows a button on every incomplete step; false shows a button only on the first incomplete step, so the parishioner focuses solely on their next step.

Important — the login requirement. Because these pages require a signed-in MinistryPlatform user, place them on a page that also carries the site's standard MP Login widget (the same one used on the My Household page). When requireLogin is true , the page shows a brief "please sign in" panel and then reveals the milestones automatically once the visitor signs in — no page refresh needed.

Because each embed points at its own journeyId and groupId , a single set of procedures can power any number of Tracker pages — a separate page per journey, all sharing the same Milestone_Forms table.

Step 6 — Test

As a quick server-side check that the read procedure is reachable, open this URL in a browser (replace yourprefix with your host prefix and use your own journey and group IDs). You should see JSON listing your group's members and their milestones:

 https://yourprefix.cloudapps.ministryplatform.cloud/sky/api/CustomWidget?storedProcedure=api_custom_JourneyMilestonesFamily_JSON&spParams=@JourneyID=18%26@GroupID=136

Then open the new page(s) while signed out — you should see the "please sign in" panel. Sign in through the site's Login; the milestones should appear on their own. On the Individual page you'll see every milestone in the journey, completed ones dated and the rest offering a link. On the Family page you'll see one section per member of your household who is in the group. Finally, submit a mapped form and confirm the milestone is recorded (subject to the Process Manager note in Step 3).

Using a different Journey

Nothing about the Tracker is tied to Confirmation. To use it for another Journey — OCIA / Becoming Catholic, marriage preparation, new-member onboarding, volunteer formation, and so on — make sure the Journey and its Milestones exist and that there is a group of current participants; add the Milestone Forms rows that map those milestones to their forms or events (Step 4); then set journeyId and groupId in each embed and reword pageHeading to suit. You can run as many Trackers as you like, one page per journey, all from the same procedures and the same table.

Troubleshooting

The page shows only the "please sign in" panel and never reveals the milestones.
The page looks for the signed-in MinistryPlatform user that the standard Login widget stores in the browser. Make sure the page (or its layout) includes the site's MP Login widget and that you actually completed sign-in. To view the page without logging in during troubleshooting, set requireLogin: false in the config (data still requires a signed-in user).

No milestones appear at all.
Confirm the signed-in person is a current participant of the configured group, and that journeyId and groupId are correct for this system. Remember that Journey_ID and Group_ID differ between databases.

A milestone shows no "Get Started" button.
There is no Milestone_Forms row for that milestone at the group's Congregation, or the row has no Form or Event. Steps that are handled offline (recorded by staff) are intentionally left blank.

A form was submitted but the milestone wasn't recorded.
Two common causes: the mapped form has no Program(see Step 4), or the MinistryPlatform Process Manager service isn't running (see Step 3). The display pages are unaffected either way.

The Family page shows other families.
Confirm you deployed the current Family procedure; it scopes members to the signed-in user's own household.

MinistryPlatform Configuration

Journey & Milestones — Your journey and its milestones must exist. Each milestone has a Sort_Order (the order shown on the page) and, optionally, a Font Awesome class in its Icon field for the little icon beside each step.

Group — A group whose current participants are the people on the journey. The group's Congregation is the parish the Tracker uses to resolve form and event links, so a participant can complete the journey at a parish other than their home parish.

Forms & Events — The forms and events that complete the milestones. Any form used for automatic recording needs a Program assigned. These forms should require login: when a signed-in parishioner opens the form, MinistryPlatform lets them choose which household member the response is for, and that selected person becomes the participant on the response. Parents commonly complete forms on behalf of a child — the parent is signed in, but the child is the one attached to the form and credited with the milestone.

Users, Contacts, and Participants — Parishioners need a MinistryPlatform User login (what the site's Login widget authenticates), linked to a Contact, which has a Participant record. The Tracker resolves the signed-in user through Users → Contacts → Participants.

Security Role — The read procedures are linked to the Administrators role by the deploy scripts. To use a different role, change the Role_Name value in each script before running it.