Objective Description Templates

1. What does this feature do? (High-Level Overview)

This feature makes BIP objective descriptions dynamic instead of manually maintained text. Staff now choose a template, and the system builds the final STO or LTO description automatically from the current plan and objective values so the app view and PDF export stay aligned.

2. Who is this for? (Roles & Permissions)

• Superadmin/Admin/Owner/Manager, or any role with manage_bips: Can create objectives from templates, change the selected template, update objective values, and use the bulk objective creator.
• Users with view_bips only: Can review the rendered objective descriptions in read-only BIP views.
• Users with export_bip: Can export PDFs that include the rendered objective descriptions.

Required permissions used by this feature path:

• manage_bips: Required to create, edit, reorder, or bulk-create objectives in the BIP workflow.
• view_bips: Required to open BIP views where rendered objective descriptions are displayed.
• export_bip: Required to generate the PDF that includes the rendered descriptions.

3. Business Rules & Enforcements

• Rule 1: The system stores the selected objective template and renders the visible description from current plan and objective values instead of relying on manually maintained final text.
• Rule 2: Users can select a predefined template or choose Other (custom) to write their own template text.
• Rule 3: Available templates depend on the objective type and plan category, so STO and LTO options change based on the goal context.
• Rule 4: Template previews update automatically when the user changes values such as start point, target, weeks to complete, order, or plan context.
• Rule 5: The same rendered description is used consistently in objective lists, objective detail views, reductions tables, and PDF export.
• Rule 6: STO templates support an automatic objective number placeholder so the system can show labels such as STO#1, STO#2, and replacement labels such as STO#3R.
• Rule 7: If an STO is marked as modified/revised, that STO keeps its normal number and the next STO becomes the replacement entry with the R suffix. If the following STO is also modified/revised, the same replacement label continues until the next non-modified STO resumes the normal sequence.
• Rule 8: The modified/revised status is only valid for STO objectives.
• Rule 9: When creating or editing an objective through the template flow, a predefined or custom template must be selected. Custom templates must include meaningful text; placeholders are optional.
• Rule 10: Legacy objectives without a saved template can still be displayed through fallback text until a template is selected for them.

4. UI Placement

1. Medical > client actions > BIP View / Update.
2. Inside the BIP tabbed plan editor:
   • Short Term Objectives section
   • Long Term Objectives section
   • Objective detail modal
   • Bulk STO creation dialog
3. Read-only BIP profile and reductions tables, where the rendered descriptions are displayed.
4. BIP Export PDF, where the same rendered descriptions are included in the generated document.

5. How-To Guide (Step-by-Step)

Scenario A: Create a new STO or LTO with a template

1. Open BIP View / Update for the client.
2. Go to the relevant plan and click Add STO or Add LTO.
3. Select one of the available templates for that objective type and plan category, or choose Other (custom) to write a custom template.
4. For custom STO templates, keep {objective_number}: when possible so the objective order and replacement labels stay visible.
5. Enter the objective values such as start point, target, weeks to complete, dates, and status.
6. Review the live preview.
7. Click Save. The system stores the template and shows the rendered description in the objectives list.

Scenario B: Change the template of an existing objective

1. Open the objective from the plan editor.
2. In the objective detail modal, open the template selector.
3. Choose a different template option.
4. Review the updated preview.
5. Save the change. The objective now displays the new rendered description everywhere the objective appears.

Scenario C: Generate objectives in bulk

1. Open a plan in BIP View / Update.
2. Click Create objectives in bulk.
3. Select the STO template and, if needed, the LTO template.
4. Enter the shared configuration, including start point, target, weeks to complete, and comparison operator.
5. Review the generated proposal with rendered descriptions.
6. Choose whether to append to or replace the current STOs.
7. Create the objectives. The saved objectives keep the templates and render their descriptions dynamically afterward.

Scenario D: Review how revised objectives are numbered

1. Open a plan with multiple STOs.
2. Mark an STO as Modified/Revised when clinically appropriate.
3. Review the next STO in the sequence.
4. Confirm that the modified objective keeps its original STO number and the next STO shows the replacement number with R.
5. If additional consecutive STOs are also modified, confirm that the same replacement label continues until a normal STO resumes the sequence.

Scenario E: Export the BIP to PDF

1. Open the client BIP and click Export PDF.
2. Select the sections to include.
3. Generate the PDF.
4. Review the objective tables in the exported document.
5. Confirm that the objective descriptions match the same rendered wording shown in the app.

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if someone changes the start point or target after the objective was created?

  • A: The description updates automatically because it is rendered from the saved template and the current objective values.

• Q: What happens if an older objective does not have a template yet?

  • A: The system can still show the existing fallback description until a user selects a template for that objective.

• Q: What happens if a user wants to type a custom template manually?

  • A: They can choose Other (custom) and write the template text. The app supports the same placeholders as predefined templates, including {objective_number} for STO numbering.