@medic/cht-stock-monitoring-workflow

Is a useful tool that is designed to help you save time in adding stock monitoring workflow to an existing CHT application.

Installation

To add the stock monitoring package in an existing CHT application:

1. Clone your CHT application
2. Open the CHT application in your desired IDE
3. Open the terminal in your working directory
4. Run below command

npm install @medic/cht-stock-monitoring-workflow

Features

This tool enables you to add comprehensive stock monitoring workflows to your existing CHT (Community Health Toolkit) application. The following features are included:

[!NOTE] For more details please check features documentation here: docs/features

Known issues

After adding an item, or any other action that update the existing forms, this form may be broken. To fix it, you need to try to repair manually by opening it with excel.

Initialization

To initialize the stock monitoring workflow in your CHT application project, run:

npx cht-stock-monitoring-workflow init

The above command generates a default configuration for the stock count form in a config file named stock-monitoring.config.json in your CHT application directory and updates translation messages files accordingly.

Question parameters

| Name | Type | Description | Required | | ----------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | monitoring_type | 2_levels or 3_levels | Stock monitoring type. 2 levels means monitoring between a supervisor (level 2) and a chw (level 1). 3 levels add a Health center levels feature like Stock order | true | | levels[x]contact_type | string | Contact type of each level (c52_supervisor or c52_supervisor) | true | | useItemCategory | boolean | Whether to categorize items or not | true | | stock_count.form_name | string | ID of the stock count form name (will be the form and properties file name alse) | true | | stock_count.contact_types | string | For which contacts types to display the stock account | true | | stock_count.type | action or task | If stock count form is an action of task. | true | | stock_count.frequency | end_of_week or middle_of_month or end_of_month | If stock_count.type = task, display the task at the end of each week (end_of_week), middle of each month (middle_of_month) or end of each month | true, if stock_count.type = task | | stock_count.title[lang] | string | Stock count form title in each cht app languages | true |

Results

1. File stock-monitoring.config.json: It is the most important change in the projet. This can regenarate all the stock monitoring changes in the app
2. Stock count form and properties file
3. translations-[lang].properties updated with new strings

Note: Stock monitoring starts with a stock count. It means that without stock count report stock status won't be display on contact summary

Add item

To add an item to an existing form, use:

npx cht-stock-monitoring-workflow add item

Questions parameters

| Name | Type | Description | Required | | ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | | categoy.name | string | The item category name (It is possible to select an existing category) | true | | category.label[lang] | string | The category label in each app language | true | | category.description[lang] | string | The category description in each app language | true | | item.name | string | The item name | true | | item.label[lang] | string | The item label in each app language | true | | item.unit | string | The item unit | true | | item.warning_total | number | Item total will be displayed in orange in total <= item.warning_total and total > item.danger_total | true | | item.danger_total | number | Item total will be displayed in red in total <= item.danger_total | true | | item[form].deduced_type | by_user or custom_formular | Whether user enter the quantity used (by_user) or it's calculated using the form values (custom_formular) | true | | item[form].formular | string | If deduced_type = by_user, it's the field relevant and field calculation if deduced_type = custom_formular | true |

Add features

To add features, use:

npx cht-stock-monitoring-workflow add feature

[!NOTE] For more details about available features please check features documentation here: docs/features

Task configuration

To incorporate stock monitoring configurations into the task.js file, follow these steps:

1. Import the necessary configurations from the stock-monitoring.config.json file:

   const configs = require('./stock-monitoring.config.json');

2. Import the getStockMonitoringTasks function from the @medic/cht-stock-monitoring-workflow package:

   const { getStockMonitoringTasks } = require('@medic/cht-stock-monitoring-workflow');

3. Export the getStockMonitoringTasks function with the provided configurations:

   module.exports = [
     ...getStockMonitoringTasks(configs)
   ];

Summary contact configuration

To include stock monitoring configurations in the contact-summary.template.js file, proceed as follows:

1. Import the required configurations from the stock-monitoring.config.json file:

   const configs = require('./stock-monitoring.config.json');

2. Import the getStockMonitoringSummaryCards function from the @medic/cht-stock-monitoring-workflow package:

   const { getStockMonitoringSummaryCards } = require('@medic/cht-stock-monitoring-workflow');

3. Export the getStockMonitoringSummaryCards function and generate the cards using the configurations and reports:

   const cards = [
     ...getStockMonitoringSummaryCards(configs, reports)
   ];

Note:

1. Make sure to upload settings after updating configuration files.

2. Perform an upload and conversion of forms after making changes to the forms.

3. To regenerate forms, use the following command:

   npx cht-stock-monitoring-workflow build

Development

Commit format

The commit format should follow this conventional-changelog angular preset. Examples are provided below.

Type | Example commit message | Release type -- | -- | -- Bug fixes | fix(#123): infinite loop when materialized views doesn't exist | patch Performance | perf(#789): Refresh materialized views faster | patch Features | feat(#456): Support real-time sync | minor Non-code | chore(#123): update README | none Breaking| perf(#2): remove support for pg 7 BREAKING CHANGE: postgres 7 no longer supported | major

Releasing

1. Create a pull request with prep for the new release (see above).
2. Get the pull request reviewed and approved.
3. When doing the squash and merge, make sure that your commit message is clear and readable and follows the strict format described in the commit format section bellow. If the commit message does not comply, automatic release will fail.
4. In case you are planning to merge the pull request with a merge commit, make sure that every commit in your branch respects the format.

Releasing betas

1. Checkout the default branch, for example main
2. Run npm version --no-git-tag-version <major>.<minor>.<patch>-beta.1. This will only update the versions in package.json and package-lock.json. It will not create a git tag and not create an associated commit.
3. Run npm publish --tag beta. This will publish your beta tag to npm's beta channel.

To install from the beta channel, run npm install @medic/cht-stock-monitoring-workflow@beta.

Copyright

Copyright 2013-2024 Medic Mobile, Inc. [email protected]

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.