Import data into a new instance

This guide will show you how to to go from an empty instance of OpenBoxes to a version that is ready for go live! It shows each import you will need and illustrates the order in which to complete them. Required elements are highlighted in yellow. Other elements are optional depending on your desired configuration. All of the referred to import templates can be found in OpenBoxes in configuration>import data. Downloading them directly from OpenBoxes will ensure that the imports align with your version.

Step 1: Define and Import Locations
Before importing your locations, make sure you have determined you location structure and types. Be sure to read the articles on Configuring organizations and locations, Configuring location groups, and Location types and supported activities. Please note, while location set up CAN be very complicated, many organizations do not require all of the advanced features available. If you have just one location where you are managing inventory, skip step 1a location groups.

1a. Create you location groups. If you are using location groups, you must first add them directly in OpenBoxes so you can reference them in the import template. Go to configuration>location groups, and click add location group to add the groups you want.

1b. Update your parent organization. All instances start up with one organization created called "Main organization." Go to configuration>Organizations to select that organization and edit it. Update the name of the organization to the name of the organization using the instance. For example, if you are standing up this instance for a Central Medical Store, you might want the organization name to be "CMS" or "MOHS" since all depots and purchases will be under that organization. If you are planning to use the purchasing feature, click "add party roles" under role and add "ROLE_BUYER." If you have a complex set up with multiple offices all issuing their own POs, please refer to the article on PO configuration for help.

1c. Import your locations. Import your locations following the instructions here. It is possible to import all locations in the same sheet, but often users find it easier to import locations by type since each type is slightly different. Some tips by location type:

- Suppliers: Suppliers require an organization name, which should usually be the same as the supplier name. The import will create the organizations and tag them as suppliers. If you are using the PO feature, you will want to add an address for each supplier so that it can appear on the PO or on any custom shipping documents

- Depots: Depots should be assigned to the organization you edited in step 1b. If you are using location groups, all depots should be assigned to a group. You will want to add an address to each depot so it can appear on POs and custom shipping documents.

- Delivery locations (Dispensaries, Pharmacies, Wards): These do not require an organization. If you are using location groups, all locations should be assigned to a group. Addresses may or may not be relevant depending on the shipping docs you want to generate.

1d: Edit your depot supported activities. When using the location import, all locations are created with default settings for that type. However, depots can be customized based on the activities you want to perform in that depot. Go to locations and click on the depot you want to edit. You can add and remove supported activities based on whether you plan to do purchasing, bin location tracking, or partial receiving in that location. See Location types and supported activities for more details.

Step 2: Import Users and People
The next step is to add users and people to the system. Users can log into and use the system. People are other actors within the organization that cannot access the system personally but can get update emails. Read more in manage users and manage people.

2a. import Users: Import your list of users using the "users" import template. For permissions, choose the lowest permission level that you want a user to have in any location. If you want to set different permissions for specific locations, you can do that in the next step. All users will be created with the password "password." Instruct users to change their password on first log in. 

2b. Import location specific permission for users. If you want users to have different permissions in different depots, download the "User locations" template. Enter the username of the user you have just created, the name of the location, and the role you want them to have in that location. Each user needs a row for each location where they have permissions.

2c. Import people: Download the "persons" template. Enter the first name and last name of each person you want to reference in the system. If you want this persons to receive email updates, enter their email. Phone numbers are optional and Openboxes will not send text updates.

Step 3: Build your product master
Before starting work on your product master, make sure you have read product configuration basics. Advanced users may also want to consider using product types to manage different categories of products.

3a. Define your product numbering system. OpenBoxes can generate product codes in multiple formats. Users can choose between a random number and letter combination, a random number combination, an auto-incrementing number, and any of these formats with a set prefix. Starting in version 0.8.20, users can set the code format within the system on the product type page. For older versions, the format must be set in the external configuration file. Once the format is set, OpenBoxes will generate codes in the proper format upon import. 

 3b. Import your category tree. All products must be assigned a category. Determine how you want to structure your category tree, referring to the advice in manage categories. If you have multiple levels of categories, please note that you will need to import the parent categories, then download the category list to get the id that you can reference as the parent id for the child categories.

 3c. Define your general ledger codes. If you are not planning on capturing general ledger codes via the PO feature, skip this step. For users that intend to use purchase orders and invoicing with required budget information, each product will need to be associated with a general ledger code. To do this, you must first define your general ledger accounts in openboxes. Go to configuration>GL Accounts to add the GL accounts that your organization uses.

  3d. Import your product list. Download the product import template, and fill it out following the instructions here. Within the template, assign a category to each product (and a GL account if using). Import the template to create your product master list!

 3e. Add custom fields. If you would like to add custom fields to your products, you can do that using attributes. Attributes are custom fields that can be added to products or to product sources. Follow the instructions here to add an attribute in the system. Once you have added attributes, you can use the import "Product attribute" to set the values for each product. 

3f. Assign products to catalogs. To easily sort and filter your products into a range of custom lists, users can assign products to catalogs. use the import "Product Catalog" to create the catalogs you want within the system. Use the import "Product Catalog Item" to assign products to different

Step 3: Import your inventory
Once you have added products and locations, you will be able to import the inventory for each of your depots. If you have multiple depots, you will need to complete these steps for each depot.

1a. Import bin locations. For depots that are tracking stock by bin, bins must be created before the inventory import. Follow these instructions to import bins into each depot.

1b. Import inventory. Follow the instruction here to import your inventory to each depot.

1c. Import inventory levels. In addition to adding inventory, users can also add inventory levels to indicate minimum, maximum, and reorder quantities for a given product in a depot. This article provides more information about how to use and import inventory level.

Levels on bins: Inventory levels can also be set on specific bins in order to inform replenishment processes within a given depot. The same template can be used. However, these currently can bot be entered by import.

Step 4: Import Purchasing and Sourcing Data
For organizations using the PO feature, there are opportunities to add budget coding data and product supplier data that can be referenced in the PO feature. 

4a. Import budget codes. Budget code import in development. Codes can be added manually in configuration>budget codes.

4b. Import product supplier information. Product supplier records allow users to save preferred or approved suppliers and manufacturers for a product, and the most recent price paid for that product. Follow the instructions in the "product source" import to add this data.

- Attributes (custom fields). As for products, custom fields can be added to product supplier records using attributes. First add the attributes in OpenBoxes, then use the "product source attributes" import to add values for those custom fields.

- Preference types. OpenBoxes has preset preference types preferred, approved, qualified, not qualified, and do not order which can be added to products via the "product source" import. If the user would like to set custom preference types, they can go to configuration>preference type. These preference types can then be assigned via the "product source" import. The "product source references" import is only used in cases where there are multiple different offices issuing purchase orders.

Step 5. Import Stock Lists:
Stock lists are an optional but incredibly useful feature for management of distribution in OpenBoxes. Stock lists must be added one by one, but stock list items can be imported from excel once the header is created. Read this article to learn how to create and import stock lists.