Administration & Configuration Guide

August 2022


How it Works: The Building Blocks

Primero is an information management system that allows for data entry and reporting for child protection (CPIMS+) and gender-based violence (GBVIMS+). The system helps intake relevant information via multiple sources, consolidates the information into relevant record types (Cases / Incidents) and allows service providers to report and make educated decisions to assist in these locations.

Records

Primero uses three types of "records" to represent protection-related information:

Each of these three "record types" will contain a different set of information, depending on the system's configuration, and which Primero Modules are in use.

Users

Primero Users are the individuals working for service-providing organizations and agencies who use the system.

User Groups

User Groups represent teams of users working together.

For example in CPIMS+, there may be a team of social workers in a particular district providing services to children. There may be another team responsible for the child’s best interest determination. A manager of a user group will have some level of access to all of the data managed by that group, but not to the data managed by a different group.

For example in GBVIMS+, there may be a team of GBV Case Workers in a particular district providing services to survivors of GBV. There may be a GBV case management supervisor who needs to review safety plans to ensure effective case management. The case management supervisor of a user group will have some level of access to all of the data managed by that group, but not to the data managed by a different group.

Roles

Users will have a Role, which defines what particular users are allowed to do: for instance viewing records, editing records, creating reports, or configuring the system. Examples of roles in CPIMS+ are Social Worker, CP Manager, and CP Administrator.

Along with defining what actions the user is allowed to perform, roles also limit what kind of information is visible about individual records for a specific user. For example, a CP Social Worker may be allowed to view and edit personally identifiable information (such as name, age, and sex) about a particular client, while a CP Manager may only see a reduced set of information about that same person (age and sex, but not the name), and may not be allowed to edit any of it.

Examples of roles are GBV Case Worker, GBV Case Management Supervisor, and GBV Organization Focal Point.

Along with defining what actions the user is allowed to perform, roles also limit what kind of information is visible about individual records for a specific user. For example, a GBV Case Worker may be allowed to view and edit personally identifiable information (such as name, age, and sex) about a particular survivor, while a Case Management Supervisor may see the case and incident record for that same person, but may not be allowed to edit any of it.

The general term for these limits to what the user can do and what a user can see is authorization.

Fields

field (data field) is information within a record. Fields are attributes like name, age, date of birth. Sometimes one field can be used to store several values like a list of protection concerns or all the languages spoken. Fields types include:

Each of these field types is defined in the Form and Field Configuration section of this guide.

Forms

A Form contains a set of fields for a record. By configuring the Primero application, you can specify new fields on a form, reorder the fields, or allow different forms to share the same field. In general, fields are organized into forms which represent steps in the user’s workflow. For instance, an administrator may add the “Risk Level,” and “Protection Concerns” fields to a “Preliminary Assessment” form on the Case record, since case workers collect both these pieces of information during the Preliminary Assessment step of the case management process.

Form Groups

Form Groups appear in the form navigation menu on the left side of the screen when a user is creating, viewing, or editing a record. When a user clicks a form group, it expands or collapses to either show or hide the forms it contains.

For example in CPIMS+, the “Registration” form group might contain the forms “Child’s Details,” “Care Arrangements,” and “Interview Details.” Form Groups keep the form navigation menu organized.

For example in GBVIMS+, the “Record Information” form group when creating, viewing or editing cases, might contain the forms “Record Information,” “Approvals,” and “Incidents.” Form Groups keep the form navigation menu organized.

Getting Started

Where to Make Configuration Changes

It is recommended that configuration design take place on a separate sandbox or “demo” instance. This will buffer live end users from experiencing potential errors from misconfigured forms and roles. Once the configuration has been successfully modified, it can then be applied to production as an import of the Configuration. For more information on how to send configuration from a sandbox or “demo” site to a production site, please see the Managing Configurations section of this guide.

Sequencing Configuration Work

Some elements of Primero configuration depend on others. For this reason, we recommend configuring your system in the following order:

Note: You can configure the Contact Information at any point.

Navigating Settings

To begin configuring Primero, click on the Settings link in the navigation menu.

Note that both “Forms” and “Lookups” can be found in the “Forms” section of the Settings navigation menu.

Form and Field Configuration

Forms determine how information is organized in Primero and help control which users can see which types of information about a record.

Form contains a set of fields for a record. As an administrator in Primero, you can create a new form, modify the existing forms, specify new fields on a form, reorder the fields, or allow different forms to share the same field.

A Field (data field) is information within a record. Fields are attributes like name, age, date of birth. Sometimes one field can be used to store several values like a list of protection concerns or all the languages spoken. The same field can be ‘shared’ on different forms so that you can enter a date of birth on one form and see it on multiple forms.

The Forms List

To configure Forms, first click on the “Forms” section within the Settings navigation menu, then click the “Forms” link that appears.

Here, you will see Forms organized by Form Group. Click on a Form Group to expand it and see the forms contained within.

Note that this list only shows Forms for a given Module and Record Type at a given time (e.g. CP Cases or GBV Cases). You can use the filters on the right side of the page to change which Forms you are viewing.

Reordering Forms

To update the order in which Forms appear, click the “Reorder” button at the top of the list. Then drag and drop Forms and Form Groups into the desired order. Click the “Save Changes” button once you are finished.

Creating a Form

To create a new form, click the “New” button at the top of the Forms List.

Fill in the following information about the form:

        

If you create a new form group for your form, it will appear later in one of the Form Group lookups. You will be able to edit and provide a translation for your form group there. For more information on how to edit form groups, see the section Managing Form Groups.

If you want the form to appear by itself and not as part of a Form Group, you must enter your Form’s name in the Form Group Name field, then click the option to create a new Form Group with this name.

Be sure to specify whether your form is visible.

Press the Save button when all the desired information is entered.

Adding and Updating Fields

You must create and save a Form before you are able to add fields to it. Once you have saved the Form, click the “Fields” tab.

Here, you can add, update, or reorder any fields in this form.

To add a field to the form, select the ADD button. The following will appear:

You have two options:

Create New Field

If you select the “Create New Field” option, you will be prompted to select a field type. Please be careful selecting the field type: once you have selected a field type and saved the field, you will not be able to change the field type.

 

A brief description of each field type and any additional information to build the field is detailed below:

See example below from GBVIMS+: the Survivor Assessment form contains a number of fields about a survivor (e.g. “Survivor’s family situation,” “Survivor’s current living situation,” “Survivor’s occupation or role”). There is a Separator above these fields with the label, “Survivor Profile” to distinguish these points from the “Key Assessment Points” below.”

In GBVIMS+, a case worker can complete the Psychosocial Functionality Scale with a survivor multiple times throughout the case management process. For this reason, this questionnaire appears in the “PSS” Subform, where the user adds an entry for each survey completed by the survivor. See example below:

Once a type of field is selected, the fields required to create that type of field will appear.

Below are the attributes you will need to specify for a field, though you will only need to specify some of these, depending on which field type you selected.

General Field Attributes

Specifying Field Options

For Select Drop Downs, Multi-Selects, and Radio Buttons, there are two ways to specify options:

To specify a Lookup to use for your field’s options, click the “Use Pre-Defined Lookup” tab in the “Options” section of the form. Then begin typing in the “Find Lookup” field to search for the Lookup you want.

Once you have selected a Lookup, you can also choose one of the Lookup’s options to be selected by default when a user creates a new record.

To specify unique options, click the “Create Unique Values” tab. Add as many options as you want. Use the radio buttons in the “Default” column to select which option should be populated by default when a user creates a new record. You can drag-and-drop options to rearrange them.

NOTE: Please be careful when selecting options. Once you have saved a field, you will not be able to ...

Setting Visibility

At the bottom of the Add Field pop-up, you will see four tick boxes which control where the field appears.

Specialized Attributes

Some form attributes only appear for specific types of fields:

Adding a Subform

If you select “Subform” as the field type, you will specialized attributes for Subforms.

Once Boys and Girls are added, the tally looks like this on the form:

Add Existing Field

To copy a field to your form which has already been created on another form, click the “Add Existing Field” button after clicking the Add field button.

In the search box, type to find a field. Click the ‘+’ next to the field you want to add.

Once you have selected the field, search for other fields to add. If you want to deselect a field, click the ‘-’ which appears where the ‘+’ was previously. Click the “Select” button when you are done.

Updating Fields

To edit a field, go to the Fields tab of the form editor, then click the field you want to edit. Editing a field is very similar to adding a field, with the following exceptions:

Note: You cannot delete fields in Primero. If you created a field by mistake or do not want it to appear in the forms anymore, you can hide it using the “Visibility” tick boxes in the Edit Field modal.

Editing an Existing Form

To edit an existing form, go to the Forms list and click the form you would like to edit. You will automatically arrive at the Edit Form page. Once you have made changes, be sure to click the Save button. If you do not click Save, your changes will be lost.

Editing a form is mostly similar to creating a form. Note that you cannot add fields or translations for your form until you have saved it.

Change the Field Order within a Form

While editing a form, you can change the order of fields. Drag and drop fields using the “grip” at the left side of the fields table.

Change the Form Group

While creating or editing a form, you can change the form group by clicking into the Form Group field. Begin typing the name of the form group you want and then select one of the results that appears.

To add a new form group, type the name of the new form group in the field. Then click the “Add” option that appears. Once you save the Form, this new Form Group will be added.

Providing Translations

NOTE: You cannot provide translations for a form until it has been saved. You must create and save a form with its English name before you can provide translations.

To provide translations for a Form’s main attributes, click the Manage Translations button on the Settings tab.

The Manage Translations modal will open. Select a language from the “Select language” dropdown, then enter your translations. Click the Update button when you are done.

You can also provide translations by clicking on the Translations tab in the Form Editor. Here, you can provide translations for settings like the Form Title and Description, as well as for the display names of any fields. Be sure to select your translation language before entering translation text.

If you would like to provide more detailed translations for a field, click the Manage button next to that field. The Manage Translations modal will appear for that field. Select the language, provide translations, and click Update when done.

You can also provide translations for field attributes in the Edit Field modal. Go to the Fields tab of the Form Editor and click a Field to edit it. Then, inside the Edit Field modal, click the Manage Translations button.

The same Manage Translations modal will appear for the field. Select a language, enter translation text, then click Update when you are done.

Once again, please be sure to click the Save button at the top of the Form Editor page once you are done making any changes to Form or Field translations.

Note: While you can manage unique field options in the Manage Translations modal, you cannot use this interface for translating Lookup options. For information on how to translate Lookup options, please see the Lookup Values Management section of this guide.

Lookup Values Management

“Lookup” is the term used for a set of values that might be used as the dropdown options for multiple fields. For example, the Country Lookup (containing the names of all the world’s countries) is used by fields like “Nationality” and “Country of Origin.” Using a lookup helps you avoid specifying the same options multiple times when configuring forms. To view all configured lookups, click the Settings link in the navigation menu. In the Settings navigation menu, open the “Forms” group, then click the Lookups link. You will then arrive at the Lookups list.

Creating a Lookup

To create a new lookup, click the New button at the top of the page.

Specify a name for the Lookup you are creating, then use the Add button to add options. To add translations for the Lookup name or options, select a language in the “Language” dropdown at the top of the page, then fill in the translation text.

Editing a Lookup

To edit an existing Lookup, go to the Lookups list, click on the Lookup you would like to edit, then, on the Show Lookup page, click Edit.

To rearrange the Lookup options, use the “grip” on the left side of the option row to drag-and-drop an option into a new position.

Note that you cannot delete options from a Lookup. Instead, you can “disable” an option. This will prevent users from selecting this option in the future. To do this, un-check the box next to the option in the “Enabled?” column of the Options list.

Remember to click the Save button after you have finished making changes.

Managing Form Groups

As you scroll through the list of lookups, you will notice that there is a lookup for the form groups for each type of record. In CPIMS+, Find the lookup labelled "Form Groups - CP Case” you will see that the options include all of the Form Groups see when viewing a CP Case.

In GBVIMS+, find the lookup labelled “Form Groups - GBV Case” you will see the options include all the Forms Groups see when viewing a GBV Case.

To update or provide translations for the Form Groups, find the lookup that corresponds to the Module and Record Type of the Form Groups you want to update, click into the Lookup, and click Edit. You can now add, update, translate, and reorder the Form Groups the same way you would manage the options for any other Lookup.

Other Important Lookups[a]

There are other Lookups which impact key Primero functionality. Here are a few of them:

Locations

To view all Locations currently configured in the system, click the Settings link in the navigation menu. Then, in the Settings navigation menu, click Locations. You will see a list of all system locations.

Importing Locations

To import locations, click the Actions menu at the top-right of the screen, then click the Import action.

The Import Locations modal will appear. Here, you can upload the CSV file containing your Locations. Select your file, then click Import to begin creating Locations.

Formatting the Locations File

The CSV file containing your locations must be precisely formatted for your Locations to be created properly.

Below is a sample of the first few rows of a properly-formatted Location CSV file containing place name translations for Jordanian Arabic. Note: we strongly suggest uploading 10,000 locations at a maximum in order to not impact performance. Click here to download a template for both CPIMS+ and GBVIMS+: https://drive.google.com/file/d/1qHYUs9hgZJ0IuHPJi6I2-VExulnfH65U/view?usp=sharing 

Country Code

Country Name

Country Name (Jordanian Arabic)

Governorate Code

Governorate Name

Governorate Name (Jordanian Arabic)

District Code

District Name

District Name (Jordanian Arabic)

#country+code

#country+name

#country+name+ar-JO

#admin1+code

#admin1+name

#admin1+name+ar-JO

#admin2+code

#admin2+name

#admin2+name+ar-JO

JOR

Jordan

الأردن

JOR

Jordan

الأردن

JOR005

Amman

عمَان

JOR

Jordan

الأردن

JOR005

Amman

عمَان

JOR005009

Wadi Essier

وادي السير

JOR

Jordan

الأردن

JOR006

Tafiela

الطفيلة

JOR

Jordan

الأردن

JOR006

Tafiela

الطفيلة

JOR006001

Hasa

الحسا

Updating Locations

Administrators can enable and disable Locations but we recommend the locations that are uploaded must be the final list. When an administrator disables a location, users will then see that location act like a disabled option whenever they are creating or editing a record and using a location field.

When an administrator enables a location, users should then see that location act like a normal, enabled option whenever they are creating or editing a record and using a location field.

When a user is editing a record where a location was saved in a field, but the location is now disabled, the user will still see the fully-translated location value in the field, but if they de-select that value, they cannot re-select it.

When a user is creating a record or editing a record and clicking into a location field with no previously-selected value, they will not see disabled locations as valued.

Components of User Management

As described above, each Primero user must have one role and at least one user group, allowing them to access the functions and records necessary to perform their day-to-day work. User management consists of the following three elements:

Creating and Editing Roles

In the Settings navigation menu, click Roles. To create a new role, click the New button, or to edit an existing Role, click a Role in the list, then click the Edit button on the Show Role page.

General Settings

In the first section of the new/edit Role page, you will see the below fields

Permissions

Scrolling down the page, you will see that a Role’s “Permissions” are organized by record type. This includes both the three main record types (Cases, Incidents, and Tracing Requests), as well as record types like “User” and “Report” which pertain to system configuration, and which usually only administrators can access.

Please note that you can expand or collapse the section for a particular resource type by clicking on the header of that section. This makes scrolling through the page easier.

You can update permissions for the following record types:

Each resource type has a different set of permissions, each of which represents a specific action that a User with this Role can perform. To see an explanation for a permission, hover your mouse over the text for that permission. A box will appear with a short description. When in doubt, always check these explanations for guidance on how to configure a Role.

A few specific permissions warrant explanation here:

        

Form Access

Scrolling down the page, you will arrive at the “Forms” section. Here, you specify which forms this Role will have access to for each of the three main record types: Cases, Incidents, and Tracing Requests.

This dictates which information a Role can access and modify. For instance, Roles with the “Show and Edit” permission on Cases, and with access to the “Child’s Details” form will be able to edit information for any field contained in this form. Roles with “Hide” permission, will not be able to view the “BID Status” form. Roles with “Show” permission will be able to view but cannot edit the “Assessment” form.

Please note that you can expand or collapse the sections for each record type (e.g. “Forms - Case”) within the Forms section by clicking on the header of the section.

Other restrictions on administrative Roles

Superusers and User Admins

There are two important types of roles which we must discuss here, since the system treats them differently. The first is the Superuser role.

Superuser role is a role has the all-encompassing "manage" permission for CasesIncidentsReportsRolesUsersUser GroupsAgenciesSystem Settings, and Forms and Lookups. A superuser, meanwhile, is a user who has been assigned such a role. Since this user has a great deal of power within the system, only superusers can view or edit the attributes of other superusers. For similar reasons, superuser roles cannot be edited within Primero's administrative interface.

The second special type of role is the User Admin role. A user admin role has less power than a superuser role, but is defined as having the all-encompassing "manage" permission for RolesUsersUser GroupsAgenciesSystem Settings, and Forms and Lookups. Once again, a user admin user is a user who has a user admin role. Only superusers and other admin users can view or edit the attributes of user admin users. Similarly, only superusers can edit a user admin role.

Please note that Superusers are never enabled except for situations of emergency maintenance and support.

Note: As a security measure, admins will not be able to access roles they create and the Primero team will need to provision the access to any newly created roles. If the programme team does not agree with this security measure, the Primero team can remove the role access permission so this does not become an impediment in the programme.

User Groups

User Groups are teams of users. Users within this group with managerial Roles will be able to access all the records managed by the other users in the group. As with Roles, User Groups should be created before you create individual users. As we discussed in the Creating and Editing Roles section, each role has one of the following “access” levels:

The actions the user can perform once they have access to a record are driven by the privileges set with their role. These permissions given to a user apply to all records they have access to. If a user has the “Edit” permission on Cases, and also happens to have access to the Cases of all the Users in their User Group, then they will also be able to edit the Cases of all the Users in their User group.

The following diagram helps explain the relationship between Users, Roles, and User Groups through a hypothetical Role/User Group setup, where the different roles are given specific permissions regarding their ability to see records within different User Groups:

To see the User Groups currently configured in your system, click the Settings link in the navigation menu, then click the User Groups link in the Settings navigation menu. You will arrive at the User Groups list.

Limited Access to User Groups

Note that, local administrators who manage the User accounts for their team will only see User Groups in this list which they are part of. Similarly, when this local administrator creates or updates a User account, they will only be able to assign a User to the User Groups that the  local administrator is part of. This specifically applies to Users whose Roles have the “All records or users in my group” access level.

For example, imagine a User with the “Camp Supervisor” Role manages User accounts for all the User Groups in Camp 1. The “Camp Supervisor” Role would have the “All records or users in my group” access level, and this Supervisor User would be part of all the User Groups for Users in Camp 1 (for example: “Camp 1 Block 1,” “Camp 1 Block 2,” and “Camp 1 Block 3”). When this supervisor goes to the User Groups list, they would only see these three User Groups, and when they created a User account, they would only be able to assign the User to one of these three User Groups.

Creating and Editing User Groups

To edit a user group, click one in the list. Once you have reached the Show User Group page, click the Edit button. Make changes, then click Save.

To create a new user group, click the New button at the top of the User Groups List page. Specify a Name and Description, then click Save.

Please note that User Groups cannot be deleted. To prevent a User Group from being assigned to Users in the future, or to prevent it from appearing in filters, dashboards, or Reports, edit the User Group and check the “Disabled?” tick box.

Agencies

Agencies represent the actual organizations using Primero. You must set up Agencies before creating User accounts. To view the Agencies currently configured in your system, click the Settings link in the navigation menu, then click the Agencies link in the Settings navigation menu. You will arrive at the Agencies List page.

Please note that Agency Administrators, whose Roles have the “View (Within Agency)” permission on Users, will only see their own Agency in this list. Similarly, when they are creating new User accounts, they will only be able to assign a User to their own Agency. For more information on this restriction, please see the Permissions section under Creating and Editing Roles.

Creating and Editing Agencies

To edit an existing Agency, click the Agency in the list. Then, on the Show Agency page, click Edit.

To create a new Agency, click the New button at the top of the Agencies List page.

Agency Logos

You can configure an Agency with logo images. If you would like to have the logo appear, you must upload two images:

In addition to specifying which images to use for an Agency’s logo, you can choose where these logos appear using the below settings:

Agency Services

Each Agency can be configured with a list of Services it provides. The options which appear here come from the Service Type Lookup.

Specifying services for your Agency is very important for controlling the Service and Referral workflow in Primero, as explained below:

Once you are done making changes, please remember to click the Save button at the top of the page.

Note: Once an agency has been created, it cannot be deleted. The agency can only be disabled. To do this, edit the Agency, check the “Disabled?” tick box, then save.

Users

To see all users currently in the system, click on the Settings link in the navigation bar, then click the Users link in the Settings navigation menu. You will now arrive at the Users List page. You can filter users by Agency, User Group, and whether or not they are Enabled, using the filters panel on the right side of the page.

Note that local administrators and supervisors will likely only see Users in their own User Groups or Agency.

Creating Users

To create a new User account, click the New button at the top of the Users List page.

For each user, you must specify the following information:

Note: Since a User’s Location, and Services settings are used to determine whether a User appears as a potential recipient for a Service or a Referral, it is important that administrators regularly update users' accounts to reflect any changes to the Services they provide or their Location. For more information on the Referral workflow, please see the Agency Services section of this guide.

Note: If no email exists, then the administrator will select “I will set the password” in the user profile and in the email that can be entered in the user profile is "their username"@”instance URL” so it would look like: jpanchalingam@newyork.primero.org

Editing Users

To edit an existing user, click on the User in the Users List. Then, on the Show User page, click the Edit button. Editing a User account is mostly the same as creating one, with the exception that you cannot update a User’s username once their account has been saved.

Once you are done making changes, please remember to click Save.

Limitations on editing your own account

Please note that, while users may sometimes be able to edit their own user accounts, no user may edit which role, user groups, modules, or agency are assigned to their user account. Primero uses this precaution to ensure users do not grant themselves additional power and endanger the data confidentiality of clients.

Updating Passwords

There are two ways to update a User’s password.

In addition, Users can always reset their password by clicking the Forgot your password? link at the bottom of the Login page.

The User will see a modal where they can enter the email address associated with their User account. They will then receive an email containing a link they can use to reset their password.

Note: Because Primero often uses password reset emails to help Users set their password, it is extremely important that administrators specify an email address for User accounts whenever possible.

Managing Identity Providers

Some implementations in Primero v2 will use identity providers to manage User accounts (i.e. Users can login using their organizational credentials, such as a UNICEF or IRC username / email address). In implementations configured to use identity providers, creating and updating user accounts will work slightly differently.

Organizations Without Identity Providers

In some systems which have been configured to use identity providers, there will still be some organizations who do not use an identity provider. To create User accounts for these organizations, use the “Primero” identity provider.

Once you have selected the “Primero” provider, you will enter a username which ends in the Primero site’s URL.

When you create this User account, the User will receive a welcome email containing a temporary password. Note: At this point, you as the administrator will be responsible for sending the user their Primero username so that they can login.

If the User clicks on the link in the email, they arrive at the Login page, where they click Login with Primero username.

At this point, a separate window will open where the User will be prompted to enter their Primero username, then their temporary password.

Note that, once the User resets their password and signs in, they will be prompted to set up and verify a recovery email address and phone number. This is important, to ensure that Users have a way of recovering their account should they lose access.

The User may also be asked if they would like to “stay signed in.” For security reasons, it is not recommended that Users do so.

From this point forward, all password management and resets will be handled through the Primero identity provider interface accessed through the Login page. In order to update the password for users using the Primero Identity, please go to https://aka.ms/sspr. 

Disabling Users

Please note that Users cannot be deleted. Instead, administrators can “disable” a User account by editing the User, then checking the “Disabled” tick box. Disabling a username will prevent that username from being used to log in to Primero.

Other Settings

Managing Workflow Statuses for CPIMS+

The below table outlines which fields set each Case Workflow Status:

Workflow Status

How to set this status (Trigger field)

Trigger field ID

Developer settings

NOTES

New

[Set by default on case creation]

Assessment

Fill out the Assessment Start Date field.

assessment_requested_on

Only appears as a workflow status if the module has the "use_workflow_assessment" attribute set to true. This attribute defaults to false, so if you do not set this attribute, this workflow status will not appear by default.

Case Plan

Fill out the Case Plan Initiated field.

date_case_plan

Only appears as a workflow status if the module has the "use_workflow_case_plan" attribute set to true. This attribute defaults to false, so if you do not set this attribute, this workflow status will not appear by default.

Response Type 1, Response Type 2, etc.

Service created with a Response Type value of Response Type 1, Response Type 2, etc.

service_response_type

Options are set in the Service Response Type lookup. If all service provisions fall under the same step in your workflow, we suggest changing the Service Response Type lookup to have a single option, labelled "Service Implementation", and set this to be the default value for the "service_response_type" field.

Each of these is intended to represent a different category of service provision, which represents a different stage of case management.

Services Implemented

All services are implemented (Service Implemented field has value "implemented"). User sets a service as implemented by filling out the Service Implemented On field.

service_implemented_day_time

Only appears as a workflow status if the module has the "use_workflow_service_implemented" attribute set to true. This attribute defaults to true, so if you do not set this attribute, the status will show automatically.

Closed

Set Case Status to "Closed"

child_status

Reopened

Perform Reopen action

case_status_reopened

Managing Configurations

As you make configuration changes, you can save your settings in a Configuration. This acts as a snapshot of all your configuration settings at a point in time. Later, when you have made other configuration changes, if you want to undo them, you can find your saved Configuration and apply it to return your system to how things were configured at that point in time.

What do configurations include?

What do configurations NOT include?

To view all your saved Configurations, click the Settings link in the navigation menu, then click the Configurations link in the Settings navigation menu. You will arrive at the Configurations List page.

Creating Configurations

To create a new Configuration, click the New button at the top of the page.

Enter a Name and Description, then click Save.

Applying Configurations

To apply a Configuration you had previously created, click into the Configuration in the Configurations list. You will see information on the Configuration, including when it was created, who created it, and when it was last applied.

Click the Apply button at the top of the page. The site will be unavailable momentarily to all users while the Configuration is applying. For this reason, it is important to only apply Configurations during periods of low site usage.

Once your Configuration has applied, Users should experience the system configuration as it existed when the Configuration was first created.

Note: You will not be able to apply a Configuration which was created on a higher version of Primero than the one you are using. For instance, if you create a Configuration on your sandbox site, which is running Primero v2.1.1, then send that Configuration to your production site, which is running Primero v2.1.0, you will not be able to apply the Configuration on production until the production site is also upgraded to v2.1.1.

Note: Applying a past Configuration will not delete configuration records such as Agencies and User Groups which were created after that Configuration was saved. Instead, these will be disabled, which will limit their visibility in the system. For instance, suppose you save a Configuration titled “Added Agency A” on March 1, then create Agency B on March 2. If, on March 3, you apply the “Added Agency A” Configuration, Agency B will still exist in your system, but will be disabled. This will mean that any Users assigned to Agency B on March 2 will still exist and function normally, but administrators will no longer be able to assign new Users to Agency B.

Sending Configurations to Production

As mentioned in the Where to Make Configuration Changes section, it is recommended that you make configuration changes on a sandbox or “demo” site, test them, then send them to your production site to be applied. This translates into the below steps:

To send a configuration from your sandbox site to your production site, go to the Configurations list on your sandbox site. Click into the Configuration you want to send. Click the Send button at the top of the page.

You will see a confirmation message warning you that the Configuration will need to be manually applied on the production site. Click Send again.

Login to your production site and go to the Configurations list. Find the Configuration you just sent from the sandbox site and click it. Click the Apply button to apply the Configuration to your production site.

Limits on Configuration management in Production

Note that, since you will be making most of your configuration changes on the sandbox or “demo” site, you will not be able to make some configuration changes on the production site except by applying a saved Configuration. This means you will not be able to create or update the following resources on the production site:

You will still be able to make changes to the following resources on production:

Note: the configuration changes made to production directly do not need to be saved in production. The reports, user groups, users, contact information and locations will remain in production.

Code of Conduct

When initially logging onto Primero, users will be prompted to review and accept a code of conduct:

The code of conduct is editable through the “Settings” under “Code of Configuration”. Administrators can modify the terms of the code of conduct as defined by the programme.


Primero System Settings Configuration for Software Teams and Developers Only

 

Primero is an information management system that allows for data entry and reporting for child protection. The system helps intake relevant information via multiple sources, consolidates the information into relevant record types (Cases / Incidents / Tracing Requests) and allows service providers to report and make educated decisions to assist in these locations.

In version 1 of Primero, there were many features that needed to be updated by a developer. In v2, many of these features are enabled through the front-end UI for system administrators to be able to manage their programme. This includes:

 

Though many configuration choices can be made directly by a system administrator or a Primero Technical Team member, there are configuration choices that can be requested for a new deployment of Primero which must be made by a developer.

 

Languages

When deploying a new instance of updating an instance of Primero, system administrators, or focal points responsible for setting up the instance, can request languages to suit the programme/context. Application strings must be translated through Transifex. Forms can be translated through Transifex or through the Forms editor. Languages have corresponding locale codes for example:

This is key to note, as these locales will be referenced and used when importing locations.

 

Reporting

The "Reporting location config" in the System Settings sets the location levels used for the Dashboard and Filters. Note the "role" permission which has a reporting location for the role technically overrides it.

 

Search by ID

Search by ID modal is a pop-up that allows users to search by an ID before creating a case. This can be turned on and off in the Modules:

 module_options: {

    allow_searchable_ids: true,

  },

Search Bar

The fields which are used in the search bar are configurable. For instructions on which fields are searchable and how to modify those fields go to the instruction here: https://community.primero.org/t/how-can-i-see-what-fields-are-searchable-how-do-i-refine-my-searches-so-i-only-pull-back-relevant-data/526 

 

Composite Case ID

Composite Case ID can be updated to a specific format requested by the programme which ends in a 7-figure Case ID GUID (case_id_display). For example, the programme may request “Registration Date” and “Case ID” which would look like “12/24/2022/u8347di”. For instructions on how to update this in v2, follow steps in this instruction: https://community.primero.org/t/modifying-the-composite-id-in-primero-v2/531 

 

Age Range

The age ranges can be updated through the system settings by a developer by updating these fields:

age_ranges: {

      primero: [0..2, 3..4, 5..9, 10..12, 13..14, 15..17, 18..999],

      unhcr: [0..4, 5..11, 12..17, 18..59, 60..999]

    }

Alerts

You can update the label for the alerts for Assessment, Case Plan and Closure for each language in Primero. For example for English you can change the approval labels here:

approvals_labels_en: {

      assessment: "BIA",

      case_plan: "Case Plan",

      closure: "Closure",

      action_plan: "Action Plan",

      gbv_closure: "GBV Closure"

    },

You can also set which forms have the alerts appear, for example, you can change alerts to appear on “Basic Identity”:

approval_forms_to_alert: {

    assessment_status: 'assessment',

    cp_case_plan: 'case_plan',

    closure_form: 'closure'

  },

You can also turn off all alerts:

show_alerts: true,

Emails

There are notification emails which can be turned on or off for any functionality regardless of the “User” receiving emails:

notification_email_enabled: true

Welcome email is set at the deployment and can be turned off in the user profile:

welcome_email_enabled: true,

The content of the Welcome Email can be configured in the “welcome_email_text:” and is pre-configured in the baseline.

Data Protection and Privacy/Legitimate Basis

“data_protection_case_create_field_names” should be an empty array if you would like to turn this feature off.

 

Full Name Field

By default the CPIMS+ includes an auto-generation of Full Name where users fill in the First, Middle, and Last Name fields and the Full Name is auto-populated from those fields.  The Full Name field is not editable.The property to add to the field in the config is hidden_text_field with a value of true or false. And this can also be turned off in the Forms section as an administrator.

 

Services Tasks

Another attribute in the System Settings portion of the configuration bundle which cannot be edited through the administrator interface is that which controls how services become due. The 'due_date_from_appointment_date' attribute, set to be false by default, can be manually set to true in order to make each service become due based on the the "Appointment Date" field (or any field on the services subform with the id "service_appointment_date"). When this attribute is instead set to false, a service instead comes due based on the "Implementation Timeframe" field (or any other field on the services subform with the id "service_response_timeframe").

 

API

In order to set up the API role properly you will follow these steps:

  1. The development team will set up a API form. This form will be composed of fields that should be shared for interoperability.
  2. The development team will set up a role for interoperability. The role itself will need to be provided both read and edit access to the forms needed for interoperability such as the API form, and the the Services form (if you are doing service referrals).
  3. The development team will set up a user for interoperability using the above role.

If a time sync is needed OpenFn can set this, and the webhook can be triggered every time an update is made on a case.

All API documentation can be found here: https://github.com/primeroIMS/primero/blob/master/doc/api.md 

 

Workflow Status Bar

A combination of lookups and attributes in the System Settings can be used to control the various workflow statuses that a case can have. Please note that any changes to the workflow statuses should only be made after significant testing on VMs and discussion with the local steering committee.

Three workflow statuses are always enabled, and will display in the workflow bar no matter what values exist in the lookups. These are "New," "Reopened," and "Closed." It is important to note that only one of the first two of these will display at a given time, with "New" appearing in the bar by default, and "Reopened" only appearing if the case has been reopened after being closed. In this scenario, the "New" status will not appear at all.

Some statuses (associated with the service currently being implemented) come from the "Service Response Type" lookup. The default values for this lookup are "Care plan," "Action plan," and "Service provision." However, any entries made here will appear in the workflow status bar. If a user adds a non-implemented service to an open case and gives it a response type, the case's workflow status will be set to this new service's response type. For example, if I have an open case, and I have added a service that has not yet been implemented and has a response type of "Action plan," the workflow status for the case will then be "Action plan." If multiple non-implemented services have been added, the case's workflow status will be the response type of the most recently-added service. Note: Since the settings in the following section can only be set manually in the user bundle, this section is only for developers working on the user bundle.

There are three more potential workflow values: "Assessment," "Case Plan," and "Service Implemented." Although none of these are set to appear in the workflow status bar by default, each can be enabled for a given module using the use_workflow_assessment, use_workflow_case_plan, and use_workflow_service_implemented attributes, respectively, for whichever module where you want to use the status. Set any one of these attributes to true to use the corresponding workflow status. For instance, to enable the "Assessment" workflow status in the default configuration bundle, search for "PrimeroModule." You should come to a list of all the modules in the system. By default, there should be only one, with an id of "primeromodule-cp." Within the object representing this module, set the use_workflow_assessment attribute to true. You may end up with something looking like the lines pictured below. If you then re-import the bundle with this change, you should see the "Assessment" workflow status show up in the workflow status bar.

For example, case plan and service implemented are turned on if:

use_workflow_service_implemented: true,

    use_workflow_case_plan: true,

    use_workflow_assessment: false,

Remove Password Encryption from Exports

In the Helm release, developers can disable password encryption by updating the PRIMERO_ZIP_FORMAT;"none"


Frequently Asked Questions

How do I set up Primero to test out Referrals?

When testing out Primero’s referral functionality, you may decide to set up some test agencies, roles, and users, so that you can fully play out the referral workflow: planning a service, referring the case, logging in as the referral recipient and accepting the referral, then finally recording service details and marking the service as done.

Here are the configuration items you will want to put in place before performing the referral workflow:

Example

[a]Note: This list is not complete. We may add more entries here as we get configuration-related questions from administrators which relate to "Important Lookups."

[b]NOTE: Thus far in Primero v2, we are not using this setting for anything, but I'm leaving this section in here in case we decide to leverage it for Interoperability purposes.

[c]Note, this is deprecated, and we will probably be removing it.