medic / cht-stock-monitoring-workflow

GNU Affero General Public License v3.0
4 stars 2 forks source link

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

License

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