Skip to content

Commit

Permalink
Updates to the documentation (#131)
Browse files Browse the repository at this point in the history 
* updated documentation with benefits/drawbacks and getting started guide for developers

* updated index and added introduction pages to user and developer guides

* fixed table of contents

* Added placeholder for Mac / Windows installation instructions.

* changed copyright year

* Made changes to the developer guide documentation

* Added contributor documentation

* Minor changes to the developer guide

* Fixed relative URLs for images

* minor changes to documentation

* minor changes to configuration document

* fixed minor grammar error
  • Loading branch information
@jmiranda
jmiranda committed Feb 17, 2017
1 parent 7c40202 commit 4510039
Show file tree
Hide file tree
Showing 16 changed files with 473 additions and 117 deletions.
44 changes: 44 additions & 0 deletions docs/benefits.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Benefits of using OpenBoxes

## Free, open-source software
* OpenBoxes is entirely free to use. This can be a significant advantage in the face of limited operational resources.

## Inventory Visibility & Tracking
* Not only does OpenBoxes allow you to view your inventory at a glance, it provides a historical record of inventory
transactions. This data is invaluable to accurately understand and forecast demand for future planning periods.
* OpenBoxes allows you to set inventory max, min, and reorder points — this allows the user to quickly
assess if supplies are overstocked, at appropriate stock levels, or in danger of being out of
stock if not reordered soon.
* OpenBoxes allows you to record the movement of goods from multiple sources and across different
levels of the organization:
* From central warehouses to your facility depot
* From other hospital facilities to your facility depot
* From vendor warehouses to your facility depot
* From one warehouse to other warehouses within your network
* From your facility depot to pharmacies and wards within your facility
* Record lot numbers for items that have an expiry date to help identify stock that has expired or is about to expire. Lot numbers
also provide a means to locate stock when a manufacturer recalls a certain item.
* Record serial numbers for items that require lifecycle management (including assets such as computers, routers, hospital beds).
* Upload and manage documents for each product (e.g. data sheets, product manuals, hazardous material handling requirements).

## Shipping Documents
* OpenBoxes offers the user the ability to produce Certificates of Donation, Packing Lists, and other documents
required for shipping with just a few mouse clicks.
* Documents can also be uploaded to OpenBoxes to allow operational leadership to save all the
relevant shipping documents to a particular shipment within the system.

## Grant Compliance
* Certain grants require that inventory be tracked in very specific ways. Using OpenBoxes comprehensively would allow a
site to account for the movement of goods bought with grant monies from vendor, to country, to facility — and the
consumption of those items at a facility level.

## Integration with Demand & Forecasting software
* While the OpenBoxes stock usage history can provide a high-level picture of future demand for any particular item,
integrating with demand forecasting software will allow those processes to be automated and more accurate.

## Integration with Data Replication software
* While OpenBoxes supports a hierachy of locations, sometimes it's not possible for all locations to access a
centralized server due to power and Internet limitations at that site. In this case, you can manage multiple server
installations (a central OpenBoxes server for most locations with good Internet) and separate OB server for each
location that does not have a reliable connection to the Internet. Using [SymmetricDS](http:https://symmetricds.org),
you can bi-directionally sync all data changes between each of these servers.
217 changes: 110 additions & 107 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,113 @@
# Configuration

## openboxes-config.properties (sample)
```
# Database connection settings
dataSource.url=jdbc:mysql:https://localhost:3306/openboxes
dataSource.username=openboxes
dataSource.password=openboxes
# OpenBoxes administrator emails
[email protected],[email protected]
# Only used on local machines when dataSource.url is overriden
openboxes.fixtures.enabled=false
# OpenBoxes Identifier Formats
# N: Numeric, L: Letter, A: Alphanumeric
# For example, NNNLLL might lead to the following random identifier being generated 123ABC.
openboxes.identifier.order.format = NNNLLL
openboxes.identifier.product.format = LLNN
openboxes.identifier.requisition.format = NNNLLL
openboxes.identifier.shipment.format = NNNLLL
openboxes.identifier.transaction.format = AAA-AAA-AAA
# OpenBoxes Identifier Characters
openboxes.identifier.numeric = 0123456789
openboxes.identifier.alphabetic = ABCDEFGHJKMNPQRSTUVXYZ
openboxes.identifier.alphanumeric = 0123456789ABCDEFGHJKMNPQRSTUVWXYZ
# Report logo header (not supported yet)
# openboxes.report.header.logo = file:https:///home/jmiranda/Desktop/images.jpg
openboxes.report.header.logo = http:https://localhost:8080/openboxes/images/hands.jpg
openboxes.report.header.title = OpenBoxes
# OpenBoxes Error Email feature (bug report)
# Use your own address if you want to handle bug reports yourself. Otherwise leave as-is and OpenBoxes
# support these support requests.
openboxes.mail.errors.enabled = true
openboxes.mail.errors.recipients = [email protected]
# OpenBoxes Barcode Scanner detection
# NOTE: This feature is an experimentation. If enabled you can scan barcode on any page and the app will
# try to locate an object (product, shipment, etc) that is associated with that barcode. If an object is
# found, the app just redirects to the details page for that database object. In the future, I'm hoping to
# improve the barcode scanner to integrate with workflows (e.g. add item to purchase order).
openboxes.scannerDetection.enabled = true
# Used to specify default roles for newly registered users (implies automatic activation)
#openboxes.signup.defaultRoles=ROLE_MANAGER,ROLE_ASSISTANT
# General mail settings
grails.mail.enabled=true
grails.mail.host=<smtp server>
grails.mail.port=<smtp port>
grails.mail.username=<username>
grails.mail.password=<password>
grails.mail.from=<from address>
# Example of general mail settings
#[email protected]
#grails.mail.host=smtp.gmail.com
#grails.mail.port=465
#[email protected]
#grails.mail.password=password
#grails.mail.props = ["mail.smtp.auth":"true", "mail.smtp.socketFactory.port":"465", "mail.smtp.socketFactory.class":"javax.net.ssl.SSLSocketFactory", "mail.smtp.socketFactory.fallback":"false"]
# Error email properties
mail.error.debug=true
mail.error.server=<smtp server>
mail.error.username=<smtp username>
mail.error.password=<smtp password>
mail.error.port=<smtp port>
mail.error.to=<to address>
# Example of error email properties
#mail.error.server=localhost
#mail.error.server=smtp.pih.org
#mail.error.username=openboxes
#mail.error.password=password
#[email protected]
#Possible values: default|dynamic|alternate
mail.error.appender=dynamic
# OpenBoxes > Choose Location > Required Activities
# The supported activities required in order for a location a location to show up on Choose Location page.
# Possible values: MANAGE_INVENTORY, PLACE_ORDER, PLACE_REQUEST, FULFILL_ORDER, FULFILL_REQUEST, SEND_STOCK, RECEIVE_STOCK, EXTERNAL
openboxes.chooseLocation.requiredActivities = MANAGE_INVENTORY
# Amazon web service (not supported yet)
aws.s3.domain=s3.amazonaws.com
aws.s3.accessKey=0123456789ABCDEFG
aws.s3.secretKey=0123456789ABCDEFGHIJKLMNOPQRS
aws.s3.bucketName=files
# Google Product Search (no longer supported -- Google deprecated API)
# URL: https://www.googleapis.com/shopping/search/v1/public/products?key=${google.productSearch.key}&country=US&q=${q}&alt=scp&crowdBy=brand:1
google.api.key=<no longer supported>
# Hipaaspace.com NDC Lookup (not supported yet)
hipaaspace.api.key=<not supported yet>
# RXNorm (not supported yet)
# URL: http:https://rxnav.nlm.nih.gov/REST/
rxnorm.api.key=<not supported yet>
# Google analytics
google.analytics.enabled = false
google.analytics.webPropertyID = <enter your google analytics property ID>
```

## Configuration file location
As mentioned in the installation instructions, you can override application configuration properties by creating a file called `$USER_HOME/.grails/openboxes-config.properties`. If you are a developer, `$USER_HOME` should resolve to your home directory (e.g. `/home/jmiranda` on Ubuntu). If you are deploying the application to Tomcat, the file is usually located under the `TOMCAT_HOME/.grails/openboxes-config.properties`.

Expand Down Expand Up @@ -92,110 +202,3 @@ openboxes.identifier.shipment.format = NNNLLL
openboxes.identifier.transaction.format = AAA-AAA-AAA
```

## Example openboxes-config.properties
```
# OpenBoxes administrator emails
[email protected],[email protected]
# Only used on local machines when dataSource.url is overriden
openboxes.fixtures.enabled=false
# OpenBoxes Identifier Formats
# N - Numeric, L - Letter, A - Alphanumeric
openboxes.identifier.order.format = NNNLLL
openboxes.identifier.product.format = LLNN
openboxes.identifier.requisition.format = NNNLLL
openboxes.identifier.shipment.format = NNNLLL
openboxes.identifier.transaction.format = AAA-AAA-AAA
# OpenBoxes Identifier Characters
openboxes.identifier.numeric = 0123456789
openboxes.identifier.alphabetic = ABCDEFGHJKMNPQRSTUVXYZ
openboxes.identifier.alphanumeric = 0123456789ABCDEFGHJKMNPQRSTUVWXYZ
# Report logo header (not supported yet)
# openboxes.report.header.logo = file:https:///home/jmiranda/Desktop/images.jpg
openboxes.report.header.logo = http:https://localhost:8080/openboxes/images/hands.jpg
openboxes.report.header.title = Last Mile Health
# OpenBoxes Error Email feature (bug report)
# Use your own address if you want to handle bug reports yourself. Otherwise leave as-is and OpenBoxes
# support these support requests.
openboxes.mail.errors.enabled = true
openboxes.mail.errors.recipients = [email protected]
# OpenBoxes Barcode Scanner detection
#
# NOTE: This feature is an experimentation. If enabled you can scan barcode on any page and the app will
# try to locate an object (product, shipment, etc) that is associated with that barcode. If an object is
# found, the app just redirects to the details page for that database object. In the future, I'm hoping to
# improve the barcode scanner to integrate with workflows (e.g. add item to purchase order).
openboxes.scannerDetection.enabled = true
# Used to specify default roles for registered users (implies automatic activation)
#openboxes.signup.defaultRoles=ROLE_MANAGER,ROLE_ASSISTANT
# Database connection settings
dataSource.url=jdbc:mysql:https://localhost:3306/openboxes?autoReconnect=true&zeroDateTimeBehavior=convertToNull&sessionVariables=storage_engine=InnoDB
dataSource.username=openboxes
dataSource.password=openboxes
# General mail settings
grails.mail.enabled=true
grails.mail.host=<smtp server>
grails.mail.port=<smtp port>
grails.mail.username=<username>
grails.mail.password=<password>
grails.mail.from=<from address>
# Example of general mail settings
#[email protected]
#grails.mail.host=smtp.gmail.com
#grails.mail.port=465
#[email protected]
#grails.mail.password=password
#grails.mail.props = ["mail.smtp.auth":"true", "mail.smtp.socketFactory.port":"465", "mail.smtp.socketFactory.class":"javax.net.ssl.SSLSocketFactory", "mail.smtp.socketFactory.fallback":"false"]
# Error email properties
mail.error.debug=true
mail.error.server=<smtp server>
mail.error.username=<smtp username>
mail.error.password=<smtp password>
mail.error.port=<smtp port>
mail.error.to=<to address>
# Example of error email properties
#mail.error.server=localhost
#mail.error.server=smtp.pih.org
#mail.error.username=openboxes
#mail.error.password=password
#[email protected]
#Possible values: default|dynamic|alternate
mail.error.appender=dynamic
# OpenBoxes > Choose Location > Required Activities
# The supported activities required in order for a location a location to show up on Choose Location page.
# Possible values: MANAGE_INVENTORY, PLACE_ORDER, PLACE_REQUEST, FULFILL_ORDER, FULFILL_REQUEST, SEND_STOCK, RECEIVE_STOCK, EXTERNAL
openboxes.chooseLocation.requiredActivities = MANAGE_INVENTORY
# Amazon web service (not supported yet)
aws.s3.domain=s3.amazonaws.com
aws.s3.accessKey=0123456789ABCDEFG
aws.s3.secretKey=0123456789ABCDEFGHIJKLMNOPQRS
aws.s3.bucketName=files
# Google Product Search (no longer supported -- Google deprecated API)
# URL: https://www.googleapis.com/shopping/search/v1/public/products?key=${google.productSearch.key}&country=US&q=${q}&alt=scp&crowdBy=brand:1
google.api.key=<no longer supported>
# Hipaaspace.com NDC Lookup (not supported yet)
hipaaspace.api.key=<not supported yet>
# RXNorm (not supported yet)
# URL: http:https://rxnav.nlm.nih.gov/REST/
rxnorm.api.key=<not supported yet>
# Google analytics
google.analytics.enabled = false
google.analytics.webPropertyID = <enter your google analytics property ID>
```
42 changes: 42 additions & 0 deletions docs/developer-guide/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Contributing
There are many ways to contribute to OpenBoxes, and not just through making changes to the source code.
Here are a few examples of areas we need a considerable amount of help.

* Develop a new feature
* Patch a bug / hotfix
* Improve translations
* Improve documentation
* Write unit, integration, functional tests

## Procedure

1. Find or create an issue for the feature or bug in [GitHub Issues.](https://github.com/openboxes/openboxes/issues)

1. Fork the [openboxes/openboxes](https://github.com/openboxes/openboxes) GitHub repository. ![Fork Repo](../img/fork-repo.png)

1. Create a branch for your changes (create a `hotfix` for bugs if working off `master` or a `feature` branch for
features if working off `develop`). **NOTE:** The use of the `hotfix` or `develop` prefix will help us identify which
branch we need to merge your changes into.

git checkout -b hotfix/123-short-summary-of-issue
git checkout -b feature/123-short-summary-of-issue

1. Implement your feature or hotfix in your new branch.

1. Write a test for your changes (if you have trouble with this step please comment in your ticket that you'd like some help). **NOTE:** Tests are required for features and bug fixes, but not for documentation and translation changes.

1. Run tests.

grails test-app unit:
grails test-app integration:

1. Commit your changes

git commit -m "Implemented feature #123"

1. Push to your fork.

git push
1. Submit a pull request.

Loading

0 comments on commit 4510039

Please sign in to comment.