Permissions for Stock Management in 3.1

Goal

This page outlines a simple permissions model for Stock Management first introduced in OpenLMIS 3.1.0. It follows the pattern first used in Requisition in 3.0.0 to create similar Rights (permissions) that are used by Stock Management in 3.1. This includes using the existing Home Facilities (for each user), Requisition Groups, and Supervisory Node hierarchy. This wiki page was originally created in response to ticket OLMIS-2109: Design permission model using Requisition permissions for Stock 3.1DonePreview.

See the Role Based Access Control page for more background on the different types of rights and roles.

Rights and Roles

STOCK_INVENTORIES_EDIT (supervision type):
A user with this right can create a physical inventory and can submit a physical inventory within a specific Program and HomeFacility/SupervisoryNode. What we mean by "HomeFacility/SupervisoryNode" is that this right, just like any supervision type right, is assigned for a single Program along with either the user's home facility or a supervisory node. If assigned for a Supervisory Node, the permissions apply to all facilities below that node in the hierarchy. The hierarchy may have multiple "child" supervisory nodes until it ultimately reaches Requisition Groups that contain one or more facilities. The STOCK_INVENTORIES_EDIT right only works with a single Program. So if a user should have permissions to conduct physical inventories for multiple programs, you would need to assign the right individually for each program to that user.

STOCK_INVENTORIES_VIEW (supervision type):
A user with this right gets view permissions to view (and print) any submitted and past/historical physical inventories with a specific Program and Node. This right does not give users the ability to view drafts.

STOCK_ADJUST (supervision type):
A user with this right can make a stock adjustment, potentially altering the SOH, for any Orderable that is part of a specific Program and HomeFacility/Node.

STOCK_CARDS_VIEW (supervision type): 
Can view all the stock cards and line items for any Orderable that is part of a specified Program and HomeFacility/Node.

STOCK_CARD_TEMPLATES_MANAGE (admin type): 
Can configure the stock card templates.

STOCK_SOURCES_MANAGE and STOCK_DESTINATIONS_MANAGE (admin type): 
Can configure the valid sources and destinations for all programs/facilities in the system.
Assumption: since this functionality is not in v3.1 scope, it may be removed or disabled before release.

STOCK_CARD_LINE_ITEM_REASONS_MANAGE (admin type):
Can configure the reasons, including which reasons map to which facilityTypes and programs.

ORGANIZATIONS_MANAGE (admin type):
Cane configure the list of outside organizations.
Assumption: since this functionality is not in v3.1 scope, it may be removed or disabled before release.

Rights to Remove

A handful of STOCK_* rights are already built into the bootstrap data, but we suggest removing them for 3.1:

• STOCK_SOURCES_VIEW (see No Permissions Checks section below)

• STOCK_DESTINATIONS_VIEW
  
  

• STOCK_CARD_LINE_ITEM_REASONS_VIEW
  
  

• STOCK_EVENT_CREATE: Events are a concept under the hood. But Adjustments and Physical Inventories are the "nouns" that users can act on via the API. We don't want the concept of an "event" to have its own right(s).
  
  

No Permissions Checks

These endpoints will be visible to all logged-in users (no rights need to be checked other than a valid login token):

• GET /api/organizations

• GET /api/stockCardLineItemReasons

• GET /api/reasonCategories (or reasonTypes)

• GET /api/validReasons

• GET /api/validDestinations

• GET /api/validSources
  
  
  

NOT in v3.1

• Creating a Stock Card: This is not a right, because we expect the system will create a stock card on-the-fly on an as-needed basis. This might happen during a physical inventory, or even while recording an adjustment. The other rights cover those cases. For example, if a user can adjust stock for Program A at Facility Z, then their activities in the system can also result in creation of a stock card at A and Z.
  

• Editing a Stock Card: This is not a right, because currently there is nothing to edit. The stock card has no fields other than its identification as a combination of a Program, Product (Orderable) and Facility. It also has Line Items, but those are covered above.
  

• Issuing and Receiving: There are not specific rights for this. We may decide in the future to create a new right when this functionality is added.
  

• Receiving by POD: (also not in scope yet)

Dropdown Lists for Program, Facility and Orderable

Create a Physical Inventory—Program Dropdown List and Facility Dropdown List

When starting to create a new physical inventory (see this mockup: Mock Ups-physical inventory program name): Show only the Programs where the current user has STOCK_INVENTORIES_EDIT right. Use the /api/users/{userId}/hasRight endpoint in ReferenceData to check rights.

If* there is also a facility already selected, then filter the Programs dropdown to only show Programs where the current user has the STOCK_INVENTORIES_EDIT right for that facility (meaning their home facility if the Right is a Home Facility right, or meaning all the facilities below a Supervisory Node in the hierarchy if the Right is at a Supervisory Node).

*The current mockups do not have a Facility field shown when creating a new physical inventory, but I believe you must also pick a Facility in order to create a physical inventory. The facility dropdown will show all the facilities where the current user has STOCK_INVENTORIES_EDIT right. If there is already a Program selected, then filter the Facilities dropdown to only Facilities where the user has STOCK_INVENTORIES_EDIT right for the chosen Program.

In summary, the combination of Program and Facility dropdowns will only let the user create a new physical inventory for a valid combination of Program and Facility where they have the STOCK_INVENTORIES_EDIT right.

While Conducting Physical Inventory—Program Dropdown List

The mockups (like this one) do still show a Programs dropdown on the top left while the user is conducting a physical inventory. It's my understanding that dropdown would offer a filtering feature to filter the grid of products while the user is conducting an inventory. But that filter is only needed later if/when we decide to allow a physical inventory to be conducted on multiple programs at once. For now, we might not need this filter at all (I added a new comment on the mockups page about that too).

Regardless of all that, if we do decide to have a Programs filter on this page while conducting a Physical Inventory now, then it would simply show all of the Programs that were included in this physical inventory. So if the physical inventory contains 4 programs, those 4 programs would show on the dropdown to filter the grid. We do not need to check permissions for this dropdown—just use the program values that are in this physical inventory they are editing. The system would have already checked permissions (STOCK_INVENTORIES_EDIT) to let the user in to edit this physical inventory.