Report backwards compatibility

[Chris-Petty]

The problem

• We need to update reports for newer OMS versions with new gql options
• We need old installations to keep using older report versions that use the gql old versions actually support

We have on occasion already broken old reports by changing gql schema.

Additional Context

Some work being done to add context to report definitions so that they can automatically be included in mSupply Legacy builds with automation: https://github.com/msupply-foundation/open-msupply-reports/pull/68

Solutions

Have a version in reports

A report can have target OMS versions. e.g.

2 reports A and B, with targets v1.1.6 and v2.1.0 respectively:

• OMS 1.1.6 uses report A
• OMS 1.5.0 uses report A
• OMS >=2.1.0 uses report B

mSupply Central Server would need to be changed to support storing multiple reports for a given context along with versioning value(s) recorded.

Include default reports in OMS repo itself

We bundle in default reports for all contexts in OMS, so that when OMS is upgraded on a device it has the right reports immediately.

We'd still potentially need a solution like versioning though, as many clients will request customised reports which we’d want to sync out to all sites from the central server

[Chris-Petty]

Side thought - with OMS central server we could add OMS reports configuration to OMS instead?

If we were, would it make sense to move most of the report repo into this repo as a mono repo? We could more easily include report JSON files that way and manage in here. We'd still need to private repo for custom reports, though.

[clemens-msupply]

In general graphql APIs or report SQL tables should never change in a breaking manner. However, a new report that uses new API additions might not work on old omSupply versions.

If a report has an associated version the remote server could just pick the latest compatible report.
Question: How to identify report across versions? e.g. how to say that these two report are the same but with different versions: { id: "abc0", version: "1.0.0" }, { id: "abc1", version: "2.0.0" }. We might have to add a new unique identifier which doesn't change across versions to the report table?

We could include the report version into the generated report json file. The mSupply UI could then get the version from the uploaded report and populate the report table automatically. This means only the report designer needs to specify the version and the version doesn't need to be configured in another step.

Another idea would be to bundle multiple versions into a single report json file. However, I can imagine this could lead to quite a bit of confusion when generating and maintaining multiple report version? but maybe worth to investigate.

[Chris-Petty]

Yea an idea I suggested on https://github.com/msupply-foundation/open-msupply-reports/pull/68 was to add a config.json along side the html template that can include extra info in the output json. e.g. context, report name, version, id?

Agree that separate report files for each version would be better than one giant one with all the report versions.