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

Clone your CHT application
Open the CHT application in your desired IDE
Open the terminal in your working directory
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

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
Stock count form and properties file
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:

Import the necessary configurations from the stock-monitoring.config.json file:
```
const configs = require('./stock-monitoring.config.json');
```
Import the getStockMonitoringTasks function from the @medic/cht-stock-monitoring-workflow package:
```
const { getStockMonitoringTasks } = require('@medic/cht-stock-monitoring-workflow');
```
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:

Import the required configurations from the stock-monitoring.config.json file:
```
const configs = require('./stock-monitoring.config.json');
```
Import the getStockMonitoringSummaryCards function from the @medic/cht-stock-monitoring-workflow package:
```
const { getStockMonitoringSummaryCards } = require('@medic/cht-stock-monitoring-workflow');
```
Export the getStockMonitoringSummaryCards function and generate the cards using the configurations and reports:
```
const cards = [
  ...getStockMonitoringSummaryCards(configs, reports)
];
```

Note:

Make sure to upload settings after updating configuration files.
Perform an upload and conversion of forms after making changes to the forms.
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

Create a pull request with prep for the new release (see above).
Get the pull request reviewed and approved.
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.
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

Checkout the default branch, for example main
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.
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

License

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