Improve the specification of how initial states for INSTRUCTIONS/ACTIVITIES are assigned, adding some examples.
1. From the specs, definition of state "INITIAL: initial state, prior to planning activity (default starting state for computable representation of state machine)."
In some contexts, creating the INSTRUCTION is actually planning, but from the specs it is not clear how to get from INITIAL to PLANNED when the INSTRUCTION is created (Heath mentioned that an ACTION instance should be included in the committed COMPOSITION, I added this might be a placeholder ACTION just to change the state from INITIAL to PLANNED, SCHEDULED or ACTIVE, but this ACTION is not a real data container).
Considering this, if no ACTION is yet created for an existing INSTRUCTION/ACTIVITY, then those are on the INITIAL state.
2. All examples are focused on medication
We should add examples for other types of INSTRUCTIONS like non-drug treatments and procedures. We should ask the community for clinically valid flows or maybe propose a couple and let the community review them, add the mapping of the flow to the ISM states and provide full examples of how states change in function of ACTIONs committed. Full step-by-step examples are better for developers.
From our discussion on the mailing list I add my related comments:
Clarify that INITIAL is a pseudo state, like UML black filled circle. As such it can not exist and there must always be an ACTION to instantiate the state machine.
Consider renaming Instruction State Machine (ISM) to Activity State Machine (ASM). The ISM is actually the state machine of each ACTIVITY in the INSTRUCTION. ACTIONS drive the SM forward by changing the state of individuel ACTIVITIES. It poses considerable pedagogic strain to explain this when introducing new people to OpenEHR.
I also add my last point, although it is actually a proposed change rather than a clarification:
There seems to be a missing transition “do” that goes directly from INITIAL to COMPLETED. This is needed both for ad hoc ACTIONS as well as one time ACTIVITIES that have already been done by the time of doing the “paper work”. It seems overly formal to have to model this through two ACTIONS.
This issue is non-trivial, and we need to investigate current behaviours in archetyping tools, which will take time. I'm moving it up to Release-1.1.0.