Administration & Configuration Guide

July 2021

How it Works: The Building Blocks

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) and allows service providers to report and make educated decisions to assist in these locations.


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.


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, 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.


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 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.

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


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.


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, the “Registration” form group might contain the forms “Child’s Details,” “Care Arrangements,” and “Interview Details.” 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 guilde.

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 generally 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). 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:

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.

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. 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.

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:


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.

Country Code

Country Name

Country Name (Jordanian Arabic)

Governorate Code

Governorate Name

Governorate Name (Jordanian Arabic)

District Code

District Name

District Name (Jordanian Arabic)


























Wadi Essier

وادي السير
















Updating Locations

Note: At this point in Primero v2, there is no way for administrators to edit or disable Locations therefore the locations that are uploaded must be the final list. This functionality is still in development.

Components of User Management

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


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.

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 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. You can 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.


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.

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.

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

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



[Set by default on case creation]


Fill out the Assessment Start Date field.


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.


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.


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.


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.


Set Case Status to "Closed"



Perform Reopen action


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.

[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.