Analyze and document required external export formats (compatibility versions, scripts, and Liquibase usage)

[filiperochalopes]

User story

As a release maintainer, I want clarity on which external export formats and versions must be supported so we can keep backward compatibility for systems using CIEL and avoid maintaining obsolete exports.

Use case

Review current export options and consumers, decide which versions/formats are required, and document the scripts and validation expectations for each export.

Requirements

• Identify how many export variants/versions are needed for backward compatibility with systems that consume CIEL.
• Define which export variants will be maintained going forward and which will be considered obsolete.
• Inventory existing export scripts:
  • What scripts exist today
  • Where they are versioned (repo/path)
  • Which export variant each script produces
• Clarify the “Liquibase test” step:
  • What it means in this release context
  • Whether any unit/system uses Liquibase to version CIEL content in an EHR (and if so, which)
• Produce a short written document summarizing the decisions and answers.

Acceptance criteria

• A documented list of required export variants/versions exists, including which are maintained vs obsolete.
• All current export scripts are identified and their locations are documented.
• The Liquibase test question is answered with a clear decision: what it is, whether it is required, and whether any consumer actually uses it.

[askanter]

Should this include the actual process for generating and testing these backward compatible files? I believe we were thinking of subscribing CIELAdmin to OCL and just running the liquibase scripts

[filiperochalopes]

At one point, the idea was roughly:

flowchart LR
  A[Release] --> B[Deploy to OCL]
  A --> C[Deploy to CIEL Admin]

Loading

That made sense as a transitional model until we had enough confidence that the OCL-based flow was fully ready.

From what I understand now, though, the direction seems different: move fully into the OCL workflow and stop treating CIEL Admin as a parallel target. Even so, with the Liquibase SQL scripts, you could still generate something similar locally when needed.

flowchart LR
  A[Release] --> B[Deploy to OCL]
  B --> C[Export files]
  C --> D[CIELAdmin v1.1 SQL zip]
  C --> E[CIELAdmin vN SQL zip]
  C --> F[Liquibase ready version]

Loading

What I am less sure about is whether an automated reverse export back into CIEL Admin is still important at this stage. Especially because, if someone edits something in CIEL Admin, there is currently no support in CIEL Lab to push that back into OCL HEAD. In that case, we would end up with two sources of truth.

That raises the core question: if edits can happen in both OCL and CIEL Admin, how would we merge those two origins safely? Unless we define one system as authoritative, the reverse-sync path seems likely to create ambiguity and operational complexity.

[filiperochalopes]

In any case, I still need @bmamlin input to understand the current process and the Liquibase formats. The scripts we already have could help me quite a bit in my development process. @jamlung-ri

[askanter]

The only reason to do this is to generate legacy files for people using SQL on old versions of OpenMRS. Turns out that the OCL module only goes back as far as 2.1 so perhaps we need a different method for generating those SQL versions...

[filiperochalopes]

Yes, we may use the CIEL Lab release scripts for older versions if needed. @jamlung-ri, do we have the release @bmamlin release scripts stored anywhere and the versioned scripts for older v1.1- OpenMRS schema?