Documents editing, tracking of changes, and workflows.
The mapping tool supports a variety of actions to edit map records, add notes, assign advice, etc. All of the "map objects" (see Domain Model) are audited, meaning all changes to these objects are recorded with each commit. Thus assignment of a new code, movement through the worfklow, addition of advice, and any other changes are recorded. All prior states of map records can be searched and retrieved as needed.
There is no log of changes, per se, but each prior state of a map object can be viewed and read. In the "mapped concept view" in the application, the prior history of a map record is shown, with the last state of each map record for a particular concept (within the focus project) being displayed. Currently, there is no interface for seeing all of the incremental changes to a map record, though something like that would be fairly straightforward (but probably too fine-grained to be useful).
If editing causes any undesirable changes, admin tools can be developed to recover any prior state of a map record.
Note, prior states of objects not audited cannot be recovered. This is most important when considering changes in terminology content due to loading new versions, processing deltas (e.g. "drip feed") and tree position recomputation. This is intentional to improve performance and limit the number of archived states. Terminology objects include version information so auditing a change in version would cause an entire copy of the terminology to be recorded in the audit trails - this is the main reason they are not audited.
Map records undergo a complex workflow in which individual specialists edit their own copies of the record and submit them for comparison. When conflicts are detected, new records owned by the corresponding lead are created and at that time, all current states for all the records are available for review by the lead. A mechanism is used to connect the specialists' records to the lead record, called "origin ids". When a record is created from another record (or collection of records), the origin ids of that record and that record's id itself are added as origin ids of the later record. What this means is that for any workflow, records retain information about the prior records that were used ultimately to generate them. Thus the chain of "provenance" is recorded and can be searched.
At the moment, there are no services to query or use origin ids in sophisticated ways, however the tracking of what records lead to what other records is faithfully preserved and can be reported on. Consider the following chain of events
Following are the standard "workflow paths" that a record can follow while it is being edited.
This domain object represents the complete known state of the workflow, including information about:
Workflow path
Summary workflow status - an aggregation of statuses of the underlying map records.
The workflow model is built around actions that affect the various workflows in a variety of ways.
ASSIGN_FROM_SCRATCH
Workflow Paths
The mapping tool supports a number of different workflows that have different actions and state transition diagrams. The currently supported (and planned) workflows include:
Workflow Status
Some workflow status values are reused by different paths and some are specific to certain workflow paths.
CONFLICT_DETECTED - when a conflict between two EDITING_DONE records is detected, the EDITING_DONE records are set to this.
CONFLICT_IN_PROGRESS - when a lead has started editing a conflict but not yet finished
CONFLICT_NEW - created when a conflict is detected
CONFLICT_RESOLVED - when a conflict is resolved but has not yet been sent to publication
CONSENSUS_IN_PROGRESS - unimplemented
CONSENSUS_NEEDED - unimplemented
CONSENSUS_NEW - unimplemented
The supported workflow paths are described in detail here.
The Non-Legacy Workflow Path describes the process by which a concept is mapped independently by two specialists, with conflicts arising resolved by the lead.
INITIAL STATE:
FINAL STATE:
Workflow Status Combination | Action | Result | Trigger |
---|---|---|---|
The combinations of map records that exist for a given | The legal actions that can be requested for each workflow status combination. | Description of map records added, modified, or deleted as a result of the requested action. | User action in Mapping Tool resulting in requested action. |
Specialist Level Work: User's record marked in bold | |||
[NO RECORDS – INITIAL STATE ] | ASSIGN_FROM_SCRATCH | Record created with NEW status. | User clicks Assign Concept on Available Work widget |
NEW | SAVE_FOR_LATER | Specialist's record saved without validation and set to EDITING_IN_PROGRESS. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked EDITING_DONE. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
EDITING_IN_PROGRESS | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked EDITING_DONE. | Specialist clicks Finish from either:
| |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
EDITING_DONE | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved. No workflow modification. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
NEW + NEW | SAVE_FOR_LATER | Specialist's record saved without validation and set to EDITING_IN_PROGRESS. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If record valid:
| Specialist clicks Finish from Map Record editing page.
| |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
EDITING_IN_PROGRESS + NEW | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow change. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If record valid:
| Specialist clicks Finish from either:
| |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget | |
EDITING_DONE + NEW | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow change. | Specialist clicks Save For Later on Map Record editing page |
FINISH_EDITING | Specialist's record validated. If validation successful, record saved. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | User clicks Unassign on Assigned Work widget | |
CONFLICT_DETECTED + CONFLICT_DETECTED
| SAVE_FOR_LATER | Specialist's record saved without validation. No workflow change. | User clicks Save for Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, compare this
| User clicks Finish on Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget | |
ASSIGN_FROM_SCRATCH | Record created with CONFLICT_NEW status | Lead clicks Assign Conflict from Available Work widget. | |
Lead Level Work: User's record is marked in bold | |||
CONFLICT_DETECTED | SAVE_FOR_LATER | Lead's record saved without validation and marked CONFLICT_IN_PROGRESS. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record | Lead clicks Finish from Compare Records editing page. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. | |
CONFLICT_DETECTED | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked CONFLICT_RESOLVED | Lead clicks Finish from either:
| |
UNASSIGN | Lead's record deleted | Lead clicks Unassign on Assigned Work widget. | |
CONFLICT_DETECTED | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked CONFLICT_RESOLVED | Lead clicks Finish from Compare Records editing page. | |
PUBLISH | Lead's record set to READY_FOR_PUBLICATION. LEADS TO FINAL STATE. | Lead clicks Publish from Assigned Work widget. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. |
This section describes each possible combination of workflow statuses attached to a tracking record for a concept and project.
Status 1 | Status 2 | Status 3 | Explanation |
---|---|---|---|
NEW | One specialist has claimed the concept, but has not begun editing | ||
EDITING_IN_PROGRESS | One specialist has begun editing, and has saved work. | ||
EDITING_DONE | One specialist has completed editing. | ||
NEW | NEW | Two specialists have claimed the concept, but neither have begun editing. | |
NEW | EDITING_IN_PROGRESS | Two specialists have claimed the concept. The first has not begun editing; the second has saved editing work. | |
NEW | EDITING_DONE | Two specialists have claimed the concept. The first has not begun editing; the second has completed editing. | |
EDITING_IN_PROGRESS | EDITING_IN_PROGRESS | Two specialists are both still editing records. | |
EDITING_IN_PROGRESS | EDITING_DONE | One specialist has finished editing the record and the other is still editing. | |
EDITING_DONE | EDITING_DONE | Exists only temporarily until conflict analysis occurs, at which point either a conflict is detected and the status changes, or a conflict is not detected and these records are removed. | |
CONFLICT_DETECTED | CONFLICT_DETECTED | Two specialists have completed work, and mappings are in conflict. Requires lead review. | |
CONFLICT_DETECTED | CONFLICT_DETECTED | CONFLICT_NEW | A lead has claimed a conflict for review, but has not begun editing. |
CONFLICT_DETECTED | CONFLICT_DETECTED | CONFLICT_IN_PROGRESS | A lead has begun resolving a conflict, and has saved work. |
CONFLICT_DETECTED | CONFLICT_DETECTED | CONFLICT_RESOLVED | A lead has finished reviewing a conflict. |
Legacy Workflow Path
UNIMPLEMENTED
UNIMPLEMENTED
The Fix Error Workflow Path describes the process by which a concept with publication-ready mappings is inserted into the workflow by a specialist or lead for re-editing. The edited record is then reviewed by a lead.
INITIAL STATE:
FINAL STATE:
Workflow Status Combination | Action | Result | Trigger |
---|---|---|---|
The combinations of map records that exist for a given | The legal actions that can be requested for each workflow status combination. | Description of map records added, modified, or deleted as a result of the requested action. | User action in Mapping Tool resulting in requested action. |
Specialist Level Work: User's record marked in bold | |||
READY_FOR_PUBLICATION INITIAL STATE: No tracking record | ASSIGN_FROM_INITIAL_RECORD | Map record marked PUBLISHED or READY_FOR_PUBLICATION is | User clicks Edit Record on either:
|
REVISION + NEW | SAVE_FOR_LATER | Specialist's record saved without validation and set to EDITING_IN_PROGRESS. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked REVIEW_NEEDED. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. Record marked REVISION marked as previous workflow state (either PUBLISHED or READY_FOR_PUBLICATION) | Specialist clicks Unassign on Assigned Work widget. | |
REVISION + EDITING_IN_PROGRESS | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked REVIEW_NEEDED. | Specialist clicks Finish from either:
| |
UNASSIGN | Specialist's record deleted. Record marked REVISION marked as previous workflow state (either PUBLISHED or READY_FOR_PUBLICATION) | Specialist clicks Unassign on Assigned Work widget. | |
REVISION + REVIEW_NEEDED | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved. No workflow modification. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. Record marked REVISION marked as previous workflow state (either PUBLISHED or READY_FOR_PUBLICATION) | Specialist clicks Unassign on Assigned Work widget. | |
ASSIGN_FROM_SCRATCH | Record created with REVIEW_NEW status | Lead clicks Assign on Available Work widget | |
Lead Level Work: User's record is marked in bold | |||
REVISION | SAVE_FOR_LATER | Lead's record saved without validation and marked REVIEW_IN_PROGRESS. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record | Lead clicks Finish from Compare Records editing page. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. | |
REVISION | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | Lead clicks Finish from either:
| |
UNASSIGN | Lead's record deleted | Lead clicks Unassign on Assigned Work widget. | |
REVISION | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | Lead clicks Finish from Compare Records editing page. | |
PUBLISH | Lead's record set to READY_FOR_PUBLICATION. LEADS TO FINAL STATE. | Lead clicks Publish from Assigned Work widget. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. |
This section describes each possible combination of workflow statuses attached to a tracking record for a concept and project.
Status 1 | Status 2 | Status 3 | Explanation |
---|---|---|---|
REVISION | NEW | One specialist has claimed the concept from the publication-ready map records, but has not begun editing | |
REVISION | EDITING_IN_PROGRESS | One specialist has begun editing, and has saved work. | |
REVISION | REVIEW_NEEDED | One specialist has completed editing. | |
REVISION | REVIEW_NEEDED | REVIEW_NEW | A lead has claimed specialist's work for review, but has not begun editing. |
REVISION | REVIEW_NEEDED | REVIEW_IN_PROGRESS | A lead has begun reviewing the specialist's work, and has saved work. |
REVISION | REVIEW_NEEDED | REVIEW_RESOLVED | A lead has finished reviewing the specialist's work. |
The Review Project Workflow Path describes the process by which a concept is mapped by a single specialist, whose work is then reviewed by a Lead.
INITIAL STATE:
FINAL STATE:
Workflow Status Combination | Action | Result | Trigger |
---|---|---|---|
The combinations of map records that exist for a given | The legal actions that can be requested for each workflow status combination. | Description of map records added, modified, or deleted as a result of the requested action. | User action in Mapping Tool resulting in requested action. |
Specialist Level Work: User's record marked in bold | |||
[NO RECORDS – INITIAL STATE ] | ASSIGN_FROM_SCRATCH | Record created with NEW status. | User clicks Assign Concept on Available Work widget |
NEW | SAVE_FOR_LATER | Specialist's record saved without validation and set to EDITING_IN_PROGRESS. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked REVIEW_NEEDED. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
EDITING_IN_PROGRESS | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved and marked REVIEW_NEEDED. | Specialist clicks Finish from either:
| |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
REVIEW_NEEDED | SAVE_FOR_LATER | Specialist's record saved without validation. No workflow modification. | Specialist clicks Save For Later on Map Record editing page. |
FINISH_EDITING | Specialist's record validated. If validation successful, specialist's record saved. No workflow modification. | Specialist clicks Finish from Map Record editing page. | |
UNASSIGN | Specialist's record deleted. | Specialist clicks Unassign on Assigned Work widget. | |
ASSIGN_FROM_SCRATCH | Record created with REVIEW_NEW status | Lead clicks Assign on Available Work widget | |
Lead Level Work: User's record is marked in bold | |||
REVIEW_NEEDED + REVIEW_NEW | SAVE_FOR_LATER | Lead's record saved without validation and marked REVIEW_IN_PROGRESS. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record | Lead clicks Finish from Compare Records editing page. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. | |
REVIEW_NEEDED + REVIEW_IN_PROGRESS | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | Lead clicks Finish from either:
| |
UNASSIGN | Lead's record deleted | Lead clicks Unassign on Assigned Work widget. | |
REVIEW_NEEDED + REVIEW_RESOLVED | SAVE_FOR_LATER | Lead's record saved without validation. No workflow change. | Lead clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Lead's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | Lead clicks Finish from Compare Records editing page. | |
PUBLISH | Lead's record set to READY_FOR_PUBLICATION. LEADS TO FINAL STATE. | Lead clicks Publish from Assigned Work widget. | |
UNASSIGN | Lead's record deleted. | Lead clicks Unassign on Assigned Work widget. |
This section describes each possible combination of workflow statuses attached to a tracking record for a concept and project.
Status 1 | Status 2 | Explanation |
---|---|---|
NEW | One specialist has claimed the concept, but has not begun editing | |
EDITING_IN_PROGRESS | One specialist has begun editing, and has saved work. | |
REVIEW_NEEDED | One specialist has completed editing. | |
REVIEW_NEEDED | REVIEW_NEW | A lead has claimed specialist's work for review, but has not begun editing. |
REVIEW_NEEDED | REVIEW_IN_PROGRESS | A lead has begun reviewing the specialist's work, and has saved work. |
REVIEW_NEEDED | REVIEW_RESOLVED | A lead has finished reviewing the specialist's work. |
The QA Workflow Path describes the process by which a concept with publication-ready mappings is inserted into the workflow by an admin or through the QA report process. The concept is available to either specialists or leads, and requires only one-step review before being marked publication-ready.
INITIAL STATE:
FINAL STATE:
Workflow Status Combination | Action | Result | Trigger |
---|---|---|---|
The combinations of map records that exist for a given | The legal actions that can be requested for each workflow status combination. | Description of map records added, modified, or deleted as a result of the requested action. | User action in Mapping Tool resulting in requested action. |
Specialist or Lead Work: User's record is marked in bold | |||
READY_FOR_PUBLICATION INITIAL STATE: No tracking record | CREATE_QA_RECORD | Map record marked PUBLISHED or READY_FOR_PUBLICATION is | User clicks Edit Record on either:
|
REVISION + QA_NEEDED | UNASSIGN | NOT YET IMPLEMENTED Will remove the QA record and return the REVISION record to its earlier | N/A |
REVISION | SAVE_FOR_LATER | User's record saved without validation and marked REVIEW_IN_PROGRESS. | User clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | Users record validated. If validation successful, lead's record | User clicks Finish from Compare Records editing page. | |
UNASSIGN | User's record deleted. | User clicks Unassign on Assigned Work widget. | |
REVISION | SAVE_FOR_LATER | User's record saved without validation. No workflow change. | User clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | User's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | User clicks Finish from either:
| |
UNASSIGN | User's record deleted | User clicks Unassign on Assigned Work widget. | |
REVISION | SAVE_FOR_LATER | User's record saved without validation. No workflow change. | User clicks Save for Later on Compare Records editing page. |
FINISH_EDITING | User's record validated. If validation successful, lead's record saved and marked REVIEW_RESOLVED | User clicks Finish from Compare Records editing page | |
PUBLISH | User's record set to READY_FOR_PUBLICATION. LEADS TO FINAL STATE. | User clicks Publish from Assigned Work widget. | |
UNASSIGN | User's record deleted. | User clicks Unassign on Assigned Work widget. |
This section describes each possible combination of workflow statuses attached to a tracking record for a concept and project.
Status 1 | Status 2 | Status 3 | Explanation |
---|---|---|---|
REVISION | QA_NEEDED | Concept with publication-ready mapping has been marked for QA | |
REVISION | QA_NEEDED | REVIEW_NEW | User has claimed the concept marked for QA, but has not begun editing. |
REVISION | QA_NEEDED | REVIEW_IN_PROGRESS | User has begun QA editing, and has saved work. |
REVISION | QA_NEEDED | REVIEW_RESOLVED | User has completed QA editing. |