Admin interface basics

Authorization

There are two types of admin users: regular admins and super admins

Capabilities of regular admins:

• Can access their organization's data
• Can access locations (and all associated entities) to which they have been added as an admin
• Cannot create new organizations
• Can create new locations for their organization
• Can create new services for their locations

Capabilities of super admins:

• Can access the entire database
• Can create, edit, and delete all entities

Note that if there aren't any Organizations in the database yet, the "Add a new location" and "Add a new program" buttons on the admin home page will be hidden because Locations and Programs require a parent organization.

How authorization is determined

For regular admins who sign in with their organization email, such as john.doe@example.org

The app looks in the database for the domain name part of their email address (example.org). If it finds it, it gives them access to the organizations, locations and services that contain that domain name.

For regular admins who sign in with a generic email, such as john.doe@gmail.com

They will get access to entities that are associated with locations to which they have been added as an admin. If there are none, they can request access to a specific location by asking a super admin or someone who already has access to that location. An admin can be added to a location by visiting that location in the admin interface, then clicking the Add a new admin email button, entering the email address, and clicking the Save changes & apply edits to database button at the bottom of the page.

The list of domain names that are considered to be generic is customizable in settings.yml.

How to make a user a super admin

For security reasons, this needs to be done manually by someone who has access to the database. Instructions are provided in the installation documentation.

Creating Entities

Organizations

You must be a super admin to create a new organization. Once the organization is created, you can create Contacts for it by visiting the organization and scrolling all the way down to the Contacts section. To create a Location for an Organization:

1. Click the Add a new location button from the admin home page

2. Click inside the field labeled "Choose an organization", then start typing the name of the organization for which you wish to create a location

3. Once results appear, select the one you want

4. Fill out the rest of the form

5. Click Create Location

Programs

Any admin who has access to at least one organization can create a new program. Once a program is created, a Service can be associated with it by visiting the Service, then selecting the Program it should be associated with at the top of the Service form. Easy access to all Services is provided on the admin home page.

Locations

Any admin who has access to at least one organization can create a new location. Once the location is created, you can create Contacts and Services for it by visiting the location and scrolling all the way down to the Contacts and Services sections.

Services

Services must belong to a Location and a Location only. Therefore, they are created through Locations. To create a Service, you must first visit the Location that provides that Service, then create the Service for that Location. Once the Service is created, you can create Contacts for it by visiting the service and scrolling all the way down to the Contacts section.

Deleting Entities

Organizations

Deleting an Organization will delete all of its Contacts, all of its Locations, all of its Programs, as well as all entities that get deleted when Contacts, Locations and Programs are deleted.

Programs

Deleting a Program will delete all of its Services.

Locations

Deleting a Location will delete its Address, its Mail Address, all of its Contacts, all of its Phones, all of its Regular Schedules, all of its Holiday Schedules, all of its Services, and all entities that get deleted when Contacts and Services are deleted.

Services

Deleting a Service will delete all of its Contacts, all of its Regular Schedules, all of its Holiday Schedules, and all entities that get deleted when Contacts are deleted.

Contacts

Deleting a Contact will delete all of its Phones. Unlike the entities above, deleting Contacts happens immediately after clicking the button in the Danger Zone. Use responsibly.

Editing Entities

Ensuring data consistency

Some fields allow you to enter multiple values, such as languages, funding sources, and service areas. To make sure that the data is entered consistently, and to eliminate the chance of duplicates and spelling errors, it is recommended that you define a list of accepted values in settings.yml. Out of the box, values are already provided for accepted_payments, funding_sources, languages, required_documents, and valid_service_areas, but you are encouraged to edit them to suit your needs, and to add entries for other fields as you see fit.

The fields that don't have default values are accreditations, licenses, and keywords. Values for those can be created on the spot by entering the term, then pressing the comma key on the keyboard, as shown below:

Converting a field from freeform entry of multiple items into a selection of predefined items (for developers)

If your data already has clearly defined accepted values for a field like accreditations or licenses, you may wish to convert that field in the admin interface so that it only allows you to choose from a predefined list that you define in settings.yml. This commit is an example of the changes that would need to be made.

How to extract all the possible values for a field from your data (for developers)

In order to determine whether your data conforms to your desired predefined list for a particular field, or if you want to create that predefined list based on your data, you can find out all the possible values for a field by running a command similar to the one below in the Rails console:

Service.pluck(:funding_sources).flatten.uniq.sort

This will show you all the unique funding sources terms that have been associated with a service. Now, let's say you want to make sure all the terms are capitalized, but in some cases, they are not. First, you'll need to fetch all Services that have a misspelled funding source, like "federal", instead of "Federal" for example:

services = Service.where('funding_sources @@ :q', q: 'federal')

Then go through each of them and replace "federal" with "Federal":

services.each do |service|
  new_fs = service.funding_sources.map { |fs| fs.gsub('federal','Federal') }
  service.update!(funding_sources: new_fs)
end

Changing the Organization associated with a Location

This is not common. If you find that many Locations are associated with the wrong Organization, or Services that are associated with the wrong Location, it indicates your original data is corrupted. In that case, you should fix your data and import it again.

If you only have a very small number of entities to fix, you can follow these steps:

• Click the "Add new location" button
• Select the correct Organization at the top of the form
• Fill out the rest of the details for this location, and click the "Create location" button
• Click the link for your new location
• Add Contacts and Services to it
• Go to the original "bad" location and delete it.