@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:

• Stock Count: Monitor stock quantities
• Stock Supply: Manage the supply of stock items
• Stock Supply Confirmation: Confirm stock supplies
• Stock Discrepancy Resolution: Resolve discrepancies in stock counts
• Stock Return: Handle stock returns
• Stock Return Confirmation: Confirm stock returns
• Stock Order: Place stock orders
• Stock Order Supply: Fulfill stock orders
• Stock Out Task: Triggered for low stock situations
• Stock count contact summary: Display stock count summaries for contacts
• Stock logs: Create stock-related logs

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. hello@medic.org

License

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