Milestone Tracker — Installation Guide

This guide assumes you have read Getting Started. It covers only where the Milestone Tracker differs from the standard path.

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

What you need before starting

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:

• create_Milestone_Forms.sql — creates the Milestone_Forms table that maps each Milestone, per parish, to the Form and/or Event used to complete it.
• register_Milestone_Forms_Page.sql — registers a Milestone Forms page so staff can manage those mappings in the Platform.
• deploy_JourneyMilestonesIndividual.sql — the read procedure behind the Individual page.
• deploy_JourneyMilestonesFamily.sql — the read procedure behind the Family page.
• create_Process_FormResponseMilestone.sql — the MinistryPlatform Process that records a milestone automatically when a mapped form is submitted. The logic runs inline within the Process step.
• journey-milestones-individual.html — the Individual web page.
• journey-milestones-family.html — the Family web page.

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

Step 1 Create the mapping table and its page

Open each script in SSMS, confirm you are connected to the MinistryPlatform database and 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.

Step 2 Deploy the display procedures

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

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_Process_FormResponseMilestone.sql , which creates a Process named Form Response – Create Milestone. The milestone-creation logic runs inline within the Process step, using the record token dp_RecordID , so there is no separate stored procedure to deploy.

The Process fires when a Form Response is created or its Contact is set and, if the submitted form is mapped in Milestone_Forms , records the milestone for that participant. The script is an upsert, so you can re-run it to apply changes.

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:

Step 5 Add the web pages

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 . Everything an administrator normally touches lives in one place: the JOURNEY_CONFIG block at the very top of each file. 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
}; 

Step 6 Test

As a quick server-side check that the read procedure is reachable, open this URL in a browser, replacing yourprefix with your host prefix and using 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 pages while signed out — you should see the "please sign in" panel. Sign in through the site's Login and the milestones should appear on their own.

On the Individual page you will see every milestone in the journey, completed ones dated and the rest offering a link. On the Family page you will 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 and Becoming Catholic, marriage preparation, new-member onboarding, volunteer formation, and so on:

1. Make sure the Journey and its Milestones exist, and that there is a group of current participants.
2. Add the Milestone Forms rows that map those milestones to their forms or events, as in Step 4.
3. 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 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 while troubleshooting, set requireLogin: false in the config — the data still requires a signed-in user.

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.

There is no Milestone_Forms row for that milestone at the group's Congregation, or the row has no Form or Event. Steps handled offline and recorded by staff are intentionally left blank.

Two common causes: the mapped form has no Program, covered in Step 4, or the MinistryPlatform Process Manager service is not running, covered in Step 3. The display pages are unaffected either way.

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

The role link in dp_Role_API_Procedures . If the verification queries all pass and the API still refuses, see If the script succeeded but the API still doesn't see it in Getting Started.

MinistryPlatform configuration