Skip to content

Commit 205bfda

Browse files
aditya-07aditya-07
authored
Added docs for Activity flow (#2735)
* Added docs * Added activity flow to the guide * Review comments: Added diagram * Added video for demo * changed video type * Review changes: updated text and diagram * updated video
1 parent f0f7260 commit 205bfda

6 files changed

+158
-2
lines changed

‎docs/use/WFL/Demo-app.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Demo App
2+
3+
The *Workflow Demo* app demonstrates the capabilities of CarePlan Generation API and the Activity Flow API. The app has a Patient card in the top showing the details and a carousel in the bottom with each card representing a particular phase of the activity flow.
4+
5+
To run this app in Android Studio, [create a run/debug configuration](https://developer.android.com/studio/run/rundebugconfig) for the `workflow_demo` module using the [Android App](https://developer.android.com/studio/run/rundebugconfig#android-application) template and run the app using the configuration.
6+
7+
Alternatively, run the following command to build and install the debug APK on your device/emulator:
8+
9+
```shell
10+
./gradlew :workflow_demo:installDebug
11+
```
12+
13+
## Instructions
14+
1. Click on the **Initialize** button to install the required dependencies for an activity flow. The dependencies are already bundled in the assets folder of the workflow demo app. After the dependencies are successfully installed, **Start** Button becomes enabled in the _Proposal_ card.
15+
2. Now, click on the **Start** to generate a CarePlan which intern has a _Proposal_ Resource. This resource is then used by the app to create a new Activity Flow and the _Proposal_ card now shows the details of the resource with the **Start** button disabled now. The carousel auto moves to the next Phase Card i.e. _Plan_.
16+
3. Repeat step 2 to move forward through the phases.
17+
4. To restart the Activity click **Restart** Flow that removes all the resources related to the flow and moves the app back to step 2.
18+
5. The overflow menu on the action bar may be used to switch between various Activities supported in the demo app.
19+
20+
![Workflow Demo](workflow_demo_app.gif)

‎docs/use/WFL/Run-an-Activity-Flow.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# ActivityFlow
2+
3+
![Activity Flow](activity_flow.svg)
4+
5+
The `ActivityFlow` class manages the workflow of clinical recommendations according to the [FHIR Clinical Practice Guidelines (CPG) specification](https://build.fhir.org/ig/HL7/cqf-recommendations/activityflow.html#activity-lifecycle---request-phases-proposal-plan-order). It implements an activity flow as defined in the FHIR CPG IG, allowing you to guide clinical recommendations through various phases (proposal, plan, order, perform).
6+
7+
You can start new workflows with an appropriate request resource from the generated [CarePlan](Generate-A-Care-Plan.md) or resume existing ones from any phase.
8+
9+
**Important Considerations:**
10+
11+
* **Thread Safety:** The `ActivityFlow` is not thread-safe. Concurrent changes from multiple threads may lead to unexpected behavior.
12+
* **Blocking Operations:** Some methods of `ActivityFlow` and its associated `Phase` interface may block the caller thread. Ensure these are called from a worker thread to avoid UI freezes.
13+
14+
## Creating an ActivityFlow
15+
16+
Use the appropriate `ActivityFlow.of()` factory function to create an instance. You can start anew flow with a `CPGRequestResource` or resume an existing flow from a `CPGRequestResource` or `CPGEventResource` based on the current state.
17+
18+
**Example:**
19+
```kotlin
20+
val repository = FhirEngineRepository(FhirContext.forR4Cached(), fhirEngine)
21+
val request = CPGMedicationRequest( medicationRequestGeneratedByCarePlan)
22+
val flow = ActivityFlow.of(repository, request)
23+
```
24+
25+
## Navigating phases
26+
27+
An `ActivityFlow` progresses through a series of phases, represented by the `Phase` class. Access the current phase using `getCurrentPhase()`.
28+
29+
**Example:**
30+
```kotlin
31+
when (val phase = flow.getCurrentPhase( )) {
32+
is Phase.ProposalPhase -> { /* Handle proposal phase */ }
33+
is Phase.PlanPhase -> { /* Handle plan phase */ }
34+
// ... other phases
35+
}
36+
```
37+
38+
## Transitioning between the phases
39+
40+
`ActivityFlow` provides functions to prepare and initiate the next phase:
41+
42+
* **`prepare...()`:** Creates a new request or event for the next phase without persisting changes.
43+
* **`initiate...()`:** Creates a new phase based on the provided request/event and persists changes to the repository.
44+
45+
**Example:**
46+
```kotlin
47+
val preparedPlan = flow.preparePlan().getOrThrow( )
48+
// ... modify preparedPlan
49+
val planPhase = flow.initiatePlan(preparedPlan).getOrThrow( )
50+
```
51+
52+
## Transitioning to Perform Phase
53+
54+
The `preparePerform()` function requires the event type as a parameter since the perform phase can create different event resources.
55+
56+
**Example:**
57+
```kotlin
58+
val preparedPerformEvent = flow.preparePerform( CPGMedicationDispenseEvent::class.java).getOrThrow()
59+
// ... update preparedPerformEvent
60+
val performPhase = flow.initiatePerform( preparedPerformEvent). getOrThrow( )
61+
```
62+
63+
## Updating states in a phase
64+
65+
* **`RequestPhase`:** (`ProposalPhase`, `PlanPhase`, `OrderPhase`) allows updating the request state using `update()`.
66+
```kotlin
67+
proposalPhase.update(
68+
proposalPhase.getRequestResource().apply { setStatus(Status.ACTIVE) }
69+
)
70+
```
71+
* **`EventPhase`:** (`PerformPhase`) allows updating the event state using `update()` and completing the phase using `complete()`.
72+
```kotlin
73+
performPhase.update(
74+
performPhase.getEventResource().apply { setStatus(EventStatus.COMPLETED) }
75+
)
76+
```
77+
## API List
78+
### Factory functions
79+
80+
* `ActivityFlow.of(...)`: Various overloads for creating `ActivityFlow` instances with different resource types. Refer to the code for specific usage.
81+
82+
### Phase transition API
83+
84+
* `preparePlan()`: Prepares a plan resource.
85+
* `initiatePlan(...)`: Initiates the plan phase.
86+
* `prepareOrder()`: Prepares an order resource.
87+
* `initiateOrder(...)`: Initiates the order phase.
88+
* `preparePerform(...)`: Prepares an event resource for the perform phase.
89+
* `initiatePerform(...)`: Initiates the perform phase.
90+
91+
### Other API
92+
* `getCurrentPhase()`: Returns the current `Phase` of the workflow.
93+
94+
### Request phase API
95+
96+
* `getRequestResource()`: Returns a copy of resource.
97+
* `update(..)`: Updates the resource.
98+
* `suspend(..)`: Suspends the phase.
99+
* `resume(..)`: Resumes the phase.
100+
* `enteredInError(..)`: Marks the request entered-in-error.
101+
* `reject(..)`: Rejects the phase.
102+
103+
### Event phase API
104+
105+
* `getEventResource()`: Returns a copy of resource.
106+
* `update(..)`: Updates the resource.
107+
* `suspend(..)`: Suspends the phase.
108+
* `resume(..)`: Resumes the phase.
109+
* `enteredInError(..)`: Marks the event entered-in-error.
110+
* `start(..)`: Starts the event.
111+
* `notDone(..)`: Marks the event not-done.
112+
* `stop(..)`: Stop the event.
113+
* `complete(..)`: Marks the event as complete.
114+
115+
116+
## Supported activities
117+
The library currently doesn't implement all of the activities outlined in the [activity profiles](https://build.fhir.org/ig/HL7/cqf-recommendations/profiles.html#activity-profiles). New activities may be added as per the requirement from the application developers.
118+
119+
| Activity | Request | Event |
120+
|--------------------|-------------------------|-----------------------|
121+
| Send a message | CPGCommunicationRequest | CPGCommunication |
122+
| Order a medication | CPGMedicationRequest | CPGMedicationDispense |
123+
124+
## Additional resources
125+
126+
* [FHIR Clinical Practice Guidelines IG](https://build.fhir.org/ig/HL7/cqf-recommendations/)
127+
* [Activity Flow](https://build.fhir.org/ig/HL7/cqf-recommendations/activityflow.html#activity-flow)
128+
* [Activity Profiles](https://build.fhir.org/ig/HL7/cqf-recommendations/profiles.html#activity-profiles)

‎docs/use/WFL/activity_flow.svg

+1
Loading

‎docs/use/WFL/index.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ The [Workflow](https://build.fhir.org/workflow.html) Library provides decision s
66

77
1. The [PlanDefinition](https://build.fhir.org/plandefinition.html) resource describes a plan or protocol for the care of a given patient. This could include a treatment plan for a specific condition, a discharge plan for a hospitalized patient, or a care plan for managing chronic illness. The output of this operation will be a CarePlan resource, which represents the plan that has been tailored and applied to the specific patient or group of patients. The CarePlan resource will include details about the actions that are part of the plan, the timing and frequency of those actions, and any relevant supporting information. It may also include references to other resources that are relevant to the plan, such as observations or procedures that are part of the plan. The Apply operator can be used to determine the specific actions or interventions that should be taken as part of a care plan, based on the patient's current status and other relevant factors. For example, it could be used to determine which medications a patient should be prescribed or to identify any necessary referrals to other healthcare providers.
88

9+
1. The [Activity Flow](https://build.fhir.org/ig/HL7/cqf-recommendations/activityflow.html#activity-flow) is based on the workflow module in FHIR. It is used to create activities for the request resources generated in a CarePlan and take them through the various phases(proposal, plan, order, and perform) of the activity lifecycle.
10+
911
1. The [Library](https://build.fhir.org/library.html) resource describes a container for clinical knowledge assets. One of these assets is a shareable library of clinical logic, written in Clinical Quality Language (CQL). Users of the Workflow library can call an evaluation operator directly from the Library resource and run individual expressions at will. The output will be Parameters resource with the results of each expression evaluated. This operator should be used when the use case does not fit into a PlanDefinition or a Measure Evaluate.
1012

1113
It's recommended that these 3 types of resources are authored within the scope of a [FHIR IG](https://www.hl7.org/fhir/implementationguide.html). The IG can then be published online and imported by the Android SDK. To import an IG, Android SDK users must simply copy the required files from the IG package into the `assets` folder and parse those files using the regular FHIR Parser.
@@ -14,14 +16,17 @@ The workflow library is dependent on the [Engine library](../FEL/index.md). Oper
1416

1517
Future features of the library will provide support for Tasking and other Workflow related requirements
1618

17-
## Next Steps
19+
## Next steps
1820

1921
* [Getting Started](Getting-Started.md)
20-
* Guides
22+
* Workflow Guides
2123
* [Generate a Care Plan](Generate-A-Care-Plan.md)
24+
* [Run an Activity Flow](Run-an-Activity-Flow.md)
2225
* [Evaluate a Measure](Evaluate-a-Measure.md)
26+
* Other Operations
2327
* [Evaluate a Library](Evaluate-a-Library.md)
2428
* [Compile CQL](Compile-and-Execute-CQL.md)
29+
2530

2631
## Data safety
2732

‎docs/use/WFL/workflow_demo_app.gif

11.4 MB
Loading

‎mkdocs.yaml

+2
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ nav:
3939
- use/WFL/Evaluate-a-Measure.md
4040
- use/WFL/Evaluate-a-Library.md
4141
- use/WFL/Compile-and-Execute-CQL.md
42+
- use/WFL/Run-an-Activity-Flow.md
43+
- Demo App: use/WFL/Demo-app.md
4244
- use/extensions.md
4345
- API Doc: use/api.md
4446
- Use Snapshots: use/snapshots.md

0 commit comments

Comments
 (0)