docs: PI disaggregation categoryCombo note and section cleanup (DHIS2-18745)

src/user/configure-programs-in-the-maintenance-app.md

@@ -1051,7 +1051,7 @@ A filter that uses both attributes and data elements looks like this:
 > page](http://commons.apache.org/proper/commons-jexl/reference/syntax.html)
 > to learn how you can create more sophisticated expressions
 
-## Setting up new Program disaggregation Mappings { #program_disaggregation_mapping } 
+## Setting up new program disaggregation mappings { #program_disaggregation_mapping } 
 
 DHIS2 v42 introduces the ability to assign Disaggregation Category Combinations to a Program Indicator and create a mapping between the program data and each category option contained in the combination. This creates a relationship between the tracker and aggregate data models which allows for analysing individual data in the same way and alongside aggregated data.
 
@@ -1062,43 +1062,53 @@ The Program Indicator Disaggregation mappings, defined at the Program level, pro
 
 ![Table Example](resources/images/program/Table_Example.png){ width=60% }
 
-1. Install or update the new Maintenance app (Preview)
+1. Install or update the new Metadata Management app
 
-    If your instance does not already have the new version of the maintenance app installed go to the App Management App and search for Maintenance in the App Hub and install the app. If you already have it installed, then you should update the app to the latest version. Updates to this app are continuously released so it is good to make sure that you are using the most recent release.
+    If your instance does not already have the Metadata Management app installed go to the App Management App and search for Metadata Management in the App Hub and install the app. If you already have it installed, then you should update the app to the latest version. Updates to this app are continuously released so it is good to make sure that you are using the most recent release.
 
     ![Note Version 0.63.0 might be superseded by a newer version by the time you read this, update to the latest](resources/images/program/App_Management_Maintenance_App_Preview.png)
 
 
-2. Load the Program Disaggregation section of the Maintenance (Preview) App by selecting Program Disaggregations under the Other section or browsing to _yourinstanceurl_/apps/maintenance-preview#/programDisaggregations/
+2. Load the Program Disaggregation section of the Metadata Management app by selecting Program Disaggregations under the Programs section or browsing to _yourinstanceurl_/apps/metadata-management#/programDisaggregations/
 
-    ![Program Disaggregation screen](resources/images/program/Maintenance_App_PI_Disaggregation.png)
+    ![Program Disaggregation screen](resources/images/program/Maintenance_App_PI_Disaggregation.png){ width=100% }
 
-3. Select a Program from the drop down to enter the edit section and add Mappings to, for this example we will use the **Inpatient morbidity and mortality** program
+3. Select a Program from the drop-down to enter the edit section and add Mappings to, for this example we will use the **Inpatient morbidity and mortality** program
 
 4. This will load the Program Indicator Mapping and Categories definition screen
 
-    ![Program Indicator Selection](resources/images/program/Edit_PI_DIsaggregation.png)
+    ![Program Indicator Selection](resources/images/program/Edit_PI_DIsaggregation.png){ width=100% }
 
-3. Select a Program Indicator from the drop down list, in this example we will use **BMI**
+5. Select a Program Indicator from the drop-down list, in this example we will use **BMI**
 
-4. Under Disaggregation category combination Select **Gender and U5y** (you may need to create a new category combination containing the categories **Gender** and **Under 5/5 and above of age** if not present)
+6. Under Disaggregation category combination select **Gender and U5y** (you may need to create a new category combination containing the categories **Gender** and **Under 5/5 and above of age** if not present)
 
-    ![](resources/images/program/Disaggregation_Category.png)
+    ![](resources/images/program/Disaggregation_Category.png){ width=100% }
+
+    > [!NOTE]
+    > If you are setting up this configuration directly via the metadata API (for example in a scripted or automated import) rather than through this screen, setting `categoryMappings` on the Program and `categoryMappingIds` on the Program Indicator is enough for the mapping to be used in analytics, such as in the Data Visualizer. However, the Program Indicator's own `categoryCombo` (or `attributeCombo`, for attribute-type mappings) must also be set to a Category Combination that contains the mapped Category. This screen uses that field to work out which mappings to display and let you manage. If it is left as the `default` Category Combination, the mapping still works in analytics but shows as "None" here and cannot be edited through this screen.
+    >
+    > **This screen prevents you from creating an invalid or ambiguous configuration, but the metadata API does not.** There is currently no server-side validation when you create or update a Program or Program Indicator via the API — an incomplete or conflicting configuration will save successfully and only fail later, when a query actually runs against it in analytics. In particular:
+    >
+    > - Every Category in the Program Indicator's `categoryCombo`/`attributeCombo` must have a corresponding entry in `categoryMappingIds`. A missing one causes an analytics query error at query time, not at save time.
+    > - A Program's `categoryMappings` can contain more than one mapping for the same Category (for example two different "Gender" mappings, each with its own filter logic). If a Program Indicator's `categoryMappingIds` ends up referencing more than one mapping for the same Category, analytics queries that need that Category will fail with an unhandled server error rather than a clear validation message.
+    >
+    > If you configure this via the API, make sure each Program Indicator's `categoryMappingIds` includes exactly one mapping per Category, covering every Category in its `categoryCombo`/`attributeCombo`, and verify with a real query (for example in Data Visualizer) before relying on it.
 
     Loading this category combination will display the Mapping selection drop down for each of the categories defined, as this is the first time these categories have been selected there are no mappings currently available.
 
 7. Under the Disaggregation categories section you should see both of the categories from the combination added as suggestion. Click **Add category** for both **Gender** and **U5y**
 
-    ![](resources/images/program/Disaggregation_Mappings.png)
+    ![](resources/images/program/Disaggregation_Mappings.png){ width=100% }
 
 
 ### Create the category mappings
 
 8. In the text field under each Category enter an expression using the Program Data Elements and Attributes that defines the category. The expression uses the same syntax as the Filter section of the Program Indicator creation screen.  It is recommended to open a Program Indicator within the Program you are mapping, use the Filter screen to construct the expression and then copy it into this field. This allows you to use the inbuilt expression validation of the Program Indicator filter builder.
-   [Program Indicator functions and Variale operators](https://docs.dhis2.org/en/use/user-guides/dhis-core-version-242/configuring-the-system/programs.html#program_indicator_functions_variables_operators)
+   [Program Indicator functions and Variable operators](#program_indicator_functions_variables_operators)
 
-    ![](resources/images/program/Disaggregation_Mappings_Expanded.png)
-    ![](resources/images/program/Program_Indicator_Filter_Expression.png){ .center width=60% }
+    ![](resources/images/program/Disaggregation_Mappings_Expanded.png){ width=100% }
+    ![](resources/images/program/Program_Indicator_Filter_Expression.png){ width=100% }
 
     This example is linking the value selected in the **Gender** data element in the Program to the category option. Since the Option set in this case is a text field the expression is set to match the text ‘Female’. The next example for age shows a different way to define the relationship.
 
@@ -1108,34 +1118,40 @@ The Program Indicator Disaggregation mappings, defined at the Program level, pro
 
     ![](resources/images/program/PI_Disaggregation_Age_Mapping.png)
 
-10. When mappings for all the category options are complete, click Save and exit
+9. When mappings for all the category options are complete, click Save and exit
 
+    > [!NOTE]
+    > A warning icon is shown next to a category option if its mapping is missing or invalid, but this does not prevent you from saving. Make sure every category option has a valid mapping before relying on the disaggregated data in analytics.
 
-11. Open Data Visualizer, first let’s look at how these data were previously displayed. To do this create a visualisation to show the data of the 5 existing Program indicators with the built in disaggregations shown below.
+
+10. Open Data Visualizer, first let’s look at how these data were previously displayed. To do this create a visualization to show the data of the 5 existing Program indicators with the built in disaggregations shown below.
 
     ![](resources/images/program/DV_Before.png){ .center width=60% }
 
-    ![](resources/images/program/DV_Before2.png)
+    ![](resources/images/program/DV_Before2.png){ width=100% }
 
-12. Now remove the 4 Program Indicators with disaggregations specified and leave only the BMI Program Indicator.
+11. Now remove the 4 Program Indicators with disaggregations specified and leave only the BMI Program Indicator.
 
-    ![](resources/images/program/DV_only_PI.png)
+    ![](resources/images/program/DV_only_PI.png){ width=100% }
 
-14. You can now add **Gender** and **Under 5/5 and above of age** as disaggregation categories from the Your Dimensions column for the Program Indicator, click update and see the results.
+12. You can now add **Gender** and **Under 5/5 and above of age** as disaggregation categories from the Your Dimensions column for the Program Indicator, click update and see the results.
 
-    ![](resources/images/program/DV_PI_Disaggregated.png)
+    ![](resources/images/program/DV_PI_Disaggregated.png){ width=100% }
 
     You can now compare the data from the two separate program indicators and the single program indicator that has been disaggregated.
 
 ### Transferring Program Indicator data via the Aggregate data exchange app
 
-In addition to viewing a disaggregated Program Indicator in the Data Visualiser you can now transfer the Program Data, via the Disaggregated Program indicator, into a Data Element that shares the same Category Combination.
+In addition to viewing a disaggregated Program Indicator in the Data Visualizer you can now transfer the Program Data, via the Disaggregated Program indicator, into a Data Element that shares the same Category Combination.
 
 ![](resources/images/program/PI_Disaggregation_Data_Exchange.png)
 
-By adding the ID of a Data Element in the **Data element for aggregate data export** field and then setting up the aggregate data exchange app* to transfer data you can save Program data in the aggregate data model
+By adding the ID of a Data Element in the **Data element for aggregate data export** field and then setting up the [Data Exchange app](#data_exchange) to transfer data, you can save Program data in the aggregate data model. This field only accepts the Data Element's ID as free text; it is not validated against the Data Element's Category Combination, so make sure the two share a Category Combination as described above.
+
+> [!NOTE]
+> If the Program Indicator's Disaggregation or Attribute category combination is left as `default` (see the note above), the corresponding **Category option combination for aggregate data export** or **Attribute option combination for aggregate data export** field appears instead, letting you enter the ID of the Category/Attribute Option Combination to export to directly.
 
-![](resources/images/program/PI_Disaggregation_DE_for_Data_Exchange.png)
+![](resources/images/program/PI_Disaggregation_DE_for_Data_Exchange.png){ width=100% }
 
 
 ## Configure program rules { #configure_program_rule }