[[TOC]]
= Organisation Developer Guidelines =

== Site Super Entity == 
The following are instances of the site super entity: 
 * org_office 
 * cr_shelter 
 * hms_hospital 
The Site Super Entity allows the following components to be shared between these resources through the use of a single foreign key ({{{site_id}}}): 
 * org_staff 
 * inv_inv_item 
 * inv_recv 
 * inv_send 
 * req_req 
 * req_commit 

== Staff Permissions == 
Staff ({{{org_staff}}}) can be added as components of site instances (offices, hospitals and shelters) and organisations. There are a number of Use Cases where you may want to apply permissions based on the staff of a resource: 
 * Only staff of an organisation have permissions (READ, CREATE, UPDATE and/or DELETE) for their organisation resource. 
 * Only staff stationed at a certain site have permissions (READ, CREATE, UPDATE and/or DELETE) for their site resource. 

For further flexibility, there are 2 boolean fields for staff: 
 * {{{no_access}}} - If this is true, this staff member has no additional privileges (labelled as 'Read-only') 
 * {{{supervisor}}} - This gives the options for more permissive permissions for some staff. 

If a user creates a resource (Site or Organisation) then they are automatically given the Supervisor role for that resource. 

The roles are created by the {{{shn_create_record_roles}}} function in {{{models/05_org.py}}}, which can be called from an org or site create_onaccept by configuring the model as following: 
{{{
# Create roles for each organisation / site instance 
s3xrc.model.configure(table,  
                       create_onaccept = shn_staff_join_onaccept_func(tablename))   
}}}
(This code should be called after the resource table is defined in the model) 

=== Enabling Staff Permissions === 
 1. Set: 
{{{
deployment_settings.security.policy = 3 # Controller-ACLs. 4 & 5 will also work 
deployment_settings.aaa.has_staff_permissions = True 
deployment_settings.aaa.staff_acl = Permissions for staff role: Create, Read, Update & or Delete 
deployment_settings.aaa.supervisor_acl = Permissions for supervisor role: Create, Read, Update & or Delete 
# eg.
# deployment_settings.aaa.staff_acl_setting = acl.CREATE | acl.READ | acl.UPDATE
# or
# deployment_settings.aaa.staff_acl_setting = dict( org = acl.CREATE | acl.READ | acl.UPDATE,
#                                                   inv = acl.CREATE | acl.READ | acl.UPDATE,
#                                                   hms = acl.CREATE | acl.READ | acl.UPDATE,
#                                                   req = acl.READ ) 
("org", Storage( 
    .... 
    restricted = True, 
}}}
 2. When a new organisation or site instance is created:  
  i. New roles (staff & supervisor) are automatically created for that record (tablename_recordid Staff of recordname & tablename_recordid Supervisors of recordname). 
  i. The current user is added as a member of both of those roles. 

 3. Add staff to organisations and sites to grant them the appropriate permissions 

=== Inheriting Permissions === 
To allow other components inherit the same permissions as the primary resource, the following function can be called, to add a onaccept function which will copy the "owned_by_role" from the primary resource. This onaccept should be added to the onaccept for the component resource.  
{{{
# Update owned_by_role to the site's owned_by_role     
s3xrc.model.configure( 
    table,  
    onaccept = shn_component_copy_role_func(component_name = tablename,  
                                            resource_name = "org_site",  
                                            fk = "site_id", 
                                            pk = "site_id") 
)     
}}}

The staff component resource itself currently inherit permissions from sites not organisations, because this is LESS permissive. This may need to become a deployment setting. 

== Inventory Management == 
Inventories can be added to any site instance, by adding {{{shn_show_inv_tabs(r)}}} to the rheader tabs for that site instance.  

----
BluePrintOrganisationRegistry

DeveloperGuidelines