Prediction App 2024.5 - API updates

This describes the changes going from API v2 to v3. If nothing is specified in new fields, you should check out the documentation for this new version to understand how to use the new field.

APIs for v2 stay unchanged and can still be used, yet some bugs have been fixed:

• Examples do match now with API specifications

• “all” is now accepted as keyword for attribute known as “All (including future values)” in the UI

• Order attribute in Phases is now taking into account

• Some tables (e.g. Phases) and some attributes (e.g. kitsPerProduct in Dispensing Units) were skipped during POST request, this issue is now fixed.

1. Changes across multiple endpoints

1.1. multi-reference

In previous versions, when multiple codes had to be referenced, they needed to be an array of objects with a property code. This was updated so that the property can also be an array of strings.

For example, for the body of the endpoint trials/{id}/scenarios (POST), the property demandBuffers is an array with each item requiring a property packageTypes. Previously, only the following format was accepted (note that in the following examples not all required properties are displayed)

{
  "demandBuffers": [{
    "packageTypes": [{"code": "Active kit"}]
  }]
}

Now, the following format is also accepted :

{
  "demandBuffers": [{
    "packageTypes": ["Active kit"]
  }]
}

Furthermore, when applicable, it is now possible to use keyword “all” to refer to the value known as “All (including future values)”, for example :

{
  "demandBuffers": [{
    "packageTypes": "all"
  }]
}

There is a difference between using “all” compared to listing explicitly all possible codes known at the time of the POST. In the first case, if other codes (new package types in the example) are added later by the user, these new codes will be captured and the property (demandBuffers in the example) will also apply to these new codes. In the second case, new codes will not be captured and the user would have to pay attention to either add them explicitly to the list or switch from the UI to “All (including future values)” to ensure the property (demand buffer) is applied to the new codes.

1.2. removal of data cubes from scenario results

From v3 on, Data cubes are removed from the scenario results. Reasons that led this choice are:

• size of the output was too high for multiple scenarios

• redundancy with the other properties

• lack of stability across versions of the APIs

N-SIDE will soon provide example scripts to show how to reproduce similar advanced data structure using the raw structures remaining available

1.3. trials/{trialId}/scenarios

POST

Change in the request body

Property
handlingConditions	NEW - optional
packageTypes.handlingConditionCode	NEW - optional
packageTypes.costFix	PROPERTY removed This was removed from packageTypes, instead this information should now be added to the guideline associated to the package type.
packageTypes.costVar	PROPERTY removed This was removed from packageTypes, instead this information should now be added to the guideline associated to the package type.
depots.leadTime	PROPERTY REMOVED This was removed from depots, instead this information should now be communicated through the new array depotShipments.
siteGroups.leadTime	PROPERTY removed This was removed from siteGroups, instead this information should now be communicated through the new siteShipments.
siteGroups.dateStop	new - optional
depotShipments	new - optional
siteShipments	new - optional
phases.isInjection	PROPERTY removed The isInjection property is replaced by the optional DND. Essentially DND (= do not dispense) gives more granularity, you can consider the transformation as follows: isInjection = true → dnd = 0 isInjection = false → dnd = null (or not specified)
phases.dnd	new - optional
guidelines.leadTime	new - optional This encapsulates the packaging lead time that was previously specified by package type.
guidelines.dateSync	new - optional
guidelines.costFix	new - optional This encapsulates the fix cost that was previously specified by package type.
guidelines.costVar	new - optional This encapsulates the variable cost that was previously specified by package type.

1.4. projects/{projectId}/scenarios

POST

Change in the request body

Property
manufacturingProcesses	new - optional
manufacturingSites	new - optional
manufacturingLines	new - optional
handlingConditions	new - optional
products.handlingConditionCode	new - optional
guidelines.manufacturingProcessCode	new - optional
guidelines.manufacturingLineCode	new - optional

1.5. trialScenarios/{scenarioId}/results

GET

Change in the response body

Property
monthlyCohortSiteGroup	removed
monthlyProductLabelGroup	removed
monthlyPackageTypeLabelGroup	removed

1.6. projectScenarios/{scenarioId}/results

GET

Change in the response body

Property
monthlyProductMetrics	removed
monthlyProductStudyMetricTiming	removed
monthlyProductCategoriesMetrics	removed