Partner Assignment Guide

Partner assignments define who funds which services, at which locations, and for how long. This guide explains the full workflow for creating, reading, updating, and deleting assignments, plus how frontend components consume the same information. The technical details are translated into human-friendly explanations so administrators and developers share the same understanding.

Why partner assignments matter

• Assignments tell the platform which partner is responsible for specific indicators in a dataset.
• Invoices, dashboards, and exports rely on accurate assignments to display correct totals.
• Assignments limit what partners can see, protecting confidential information from unrelated organizations.
• The records act as historical proof of funding coverage, useful for audits and donor reporting.

Key terms

• Dataset – Collection of indicators grouped for payment or quality scoring.
• Data element – Individual indicator within a dataset.
• Partner – Organization funding or supervising services.
• Organisation unit – Facility, district, or group of facilities that receive support.
• Assignment period – Start and end dates during which the assignment is valid.

Planning assignments

Before touching the system, gather the following information:

1. Confirm which datasets the partner funds and whether the coverage is national or limited to specific regions.
2. Review the list of data elements that fall under the partnership agreement.
3. Decide whether the assignment applies to individual facilities, whole districts, or predefined organisation unit groups.
4. Determine the start and end dates, aligning them with contractual agreements or fiscal years.
5. Collect the internal identifiers (or DHIS2 IDs) for datasets, data elements, partners, and organisation units to speed up data entry.

Creating a new assignment

Follow these steps to register a fresh assignment without overwhelming the system or missing required fields:

Understanding the API in plain language

Even if you never call the API directly, knowing what happens behind the scenes helps you troubleshoot issues.

Create action

• The platform accepts a create request with dataset ID, data element IDs, partner ID, valid dates, and one or more coverage options. Internal IDs are the most efficient choice, though DHIS2 IDs also work.
• If you supply organisation units, the system links the assignment to those specific facilities. You can also provide organisation unit levels or groups to cover broader areas.
• Successful creation returns the assignment with full names included, so the interface can display human-readable details without extra lookups.

Read action

• Listing assignments supports filters for partner, dataset, data element, organisation unit, and period. Use filters to narrow large datasets into manageable results.
• Each assignment includes nested information: dataset name, partner name, data elements, and organisation units. This structure keeps the frontend responsive because it already has the required context.
• Fetching a single assignment returns the same enriched structure, which is useful for editing forms or inspection dialogs.

Update action

• When updating, you can send only the fields that changed. For example, extend the end date or adjust the coverage list.
• Arrays such as data elements or organisation units replace previous values entirely when provided. Double-check your selections to avoid accidentally removing coverage.
• The system blocks updates that would cause overlapping periods for the same partner and dataset to prevent double counting.

Delete action

• Deleting an assignment removes it from active coverage and returns the deleted details for auditing. Use this action cautiously and prefer archiving when policy requires historical records.

Non-technical summary for administrators

• Tell the system who sponsors the services, where, and for how long.
• Provide the list of indicators and facilities. The system checks for overlaps automatically.
• Confirm everything looks right in the summary before saving. You can always edit later, but overlapping coverage is blocked.
• When removing a partnership, ensure invoices for the affected period are already processed, then delete or retire the assignment.

Working with the frontend helpers

Developers building or maintaining the user interface use helper functions from the pbf-backbone package. Administrators benefit because consistent tooling reduces the risk of mistakes.

• Initial load: The interface first fetches partner and dataset lists only. This keeps the page fast for administrators opening the module.
• Dataset chosen: Once a dataset is selected, the UI requests the relevant data elements and caches them for the session.
• Listing assignments: When you filter by partner or dataset, the frontend calls a paginated endpoint so only the current page loads, preventing long wait times.
• Lazy metadata: The UI fetches organisation units, levels, or groups only when you open the selection panel, ensuring the app stays responsive.
• Name display: Because responses include names, you do not need to memorize IDs; the system shows readable labels everywhere.

Editing existing assignments

• Open the assignment list and filter for the partner or dataset you need.
• Click the row to open the detail panel. You can view coverage, data elements, and active dates at a glance.
• Choose Edit to adjust fields. Update only what changed, such as extending an end date or swapping facilities.
• Save and confirm the success notification. The list refreshes automatically with the new values.

Removing coverage safely

• Before deleting an assignment, verify that no invoices or partner reports depend on the upcoming period.
• Consider setting the end date in the past instead of deleting the record. This preserves history while preventing new coverage.
• Notify partners and relevant internal teams about the change so they update their plans.

Coordinating assignments with other modules

• Tariffs: Ensure the partner’s funded indicators have appropriate tariffs configured so payouts match expectations.
• Bank management: If partners receive direct payments, their assignments should match the bank accounts registered under their organization.
• User management: Confirm that partner staff accounts align with the facilities they fund, especially if they access dashboards or exports.

Best practices for clean data

• Use consistent naming conventions for datasets and organisation units to avoid confusion in reports.
• Keep assignments concise. If a partner covers the entire dataset nationwide, select high-level organisation unit groups instead of hundreds of individual facilities.
• Set calendar reminders for assignment renewals so you can extend or close them before they expire.
• Regularly export assignments and review them with partner focal points to confirm nothing changed without notice.

Troubleshooting scenarios

Assignments missing from the list Check your filters and ensure the assignment dates overlap the period you selected. Also confirm your user role permits viewing all partners.

Cannot save due to overlap Review existing assignments for the same partner and dataset. Either adjust the dates or consolidate the coverage into a single record.

Facilities not showing up in coverage selector Confirm the dataset is shared with those facilities in DHIS2 and that your account has permission to see them.

Partner complains about missing indicators Verify that the data elements were selected when the assignment was created. If necessary, edit the assignment to include the missing indicators.

Slow loading during editing Large datasets can introduce delay when loading data elements. Encourage administrators to filter by dataset before opening the creation form so only relevant indicators load.

Frequently asked questions

Can we assign multiple partners to the same indicator? Yes, but split coverage by organisation unit or time period to avoid overlapping assignments for the same dataset and partner combination.

Do assignments sync with DHIS2 automatically? Assignments reference DHIS2 IDs where available, but they are managed within the PBF dashboard. Update them manually when DHIS2 sharing changes.

How far in advance should we create assignments? Create assignments at least one reporting cycle ahead. This ensures partners see their coverage before data entry begins.

What happens when an assignment expires? Once the end date passes, the partner no longer has coverage. Update the assignment if they renew funding or create a new record for the next cycle.

Can we export assignments? Yes. Use the export button at the top of the module. The file includes partner names, datasets, coverage details, and validity dates for record keeping.

Key reminders

• Keep assignment data accurate to maintain trust with partners and auditors.
• Coordinate changes with finance, monitoring, and partner engagement teams.
• Review assignments regularly to catch expiring agreements before they disrupt reporting.
• Leverage the provided frontend tools for efficient workflows and consistent user experiences.
• Document every change so you can explain the configuration during audits or donor reviews.