Administrators and users allowed the Configure Agency Security Settings permission have a swift and scalable way to manage Evidence.com groups. The Import Groups feature lets you use comma-separated value (CSV) files to create groups and to define group members and monitors. The Import Groups feature is available on the Admin Portal page.
Import Groups provides separate processes for defining groups and for configuring group members and monitors. A different CSV file is required for each process. For more information about the CSV files, see Import Groups and Define Members and Monitors.
Strategies for Importing Groups, Members, and Monitors
It is recommended that you consider how your organization can best make use of the Import Groups feature.
Setup by Import, Maintain by Import
The primary use for the Import Groups feature is to enable agencies to keep their Evidence.com group configurations in sync with groups in other applications, such as with an on-premises Microsoft Active Directory implementation.
With this strategy, it is recommended that your groups CSV file and members-and-monitors CSV file reflect the complete configuration of all groups and their members and monitors. It is also recommended that you ensure that the CSV files are backed up reliably.
Setup by Import, Maintain Manually
If you have no need to synchronize group configuration with an external source, consider using the Import Groups feature when you are setting up groups for the first time. Rather than creating groups one at a time, you can define the groups and their members and monitors using CSV files, and then import the files.
After importing groups and defining members and monitors, you can review your group configuration in Evidence.com and update it as needed. If a large number of changes are needed, it is likely more efficient to update the CSV files and reimport them.
When you are satisfied with your initial group configuration, you can begin maintaining groups individually, as described in Edit Group Members, Monitors, and Other Settings.
Empty Groups
You cannot use the Define Members and Monitors feature to empty an existing group of all members and monitors. It is recommended that you delete a group rather than trying to maintain an empty group. You can always create the group again later, when it is needed.
Import Groups
The CSV file for importing groups must contain a header row and must have three columns. A sample ImportGroups.csv file is available on the Import Groups page. The following table describes the required values in the CSV file for importing groups:
Column | Header Value | Value |
A | EXTERNAL_ID |
External group ID — A unique value that identifies the group. This ID should be persistent and unchanging for the life of the group. The ID is assigned by your organization. It is recommended that you determine a group ID strategy that best suits your needs. If you are manually synchronizing the groups in your Evidence.com agency with groups in another application, you may want to use an ID value provided by the other application, such as a GUID. To find the external group ID for an existing group, view the Group Profile page for the group. You can also simply assign a descriptive name. Valid external group IDs can be up to 255 characters. |
B | NAME |
Group title — A meaningful name for the group. Because EXTERNAL_ID value provides the persistent identifier for the group, you can change the NAME value as needed. Valid group titles can be up to 255 characters. |
C | SHARE_ACCESS |
Sets the access levels for the group and corresponds to the Manage Access Settings. Valid values are the following three words:
|
Note: Older versions of the Import Groups csv with the VISIBLE_TO_FEDERATED column will be accepted for upload, but the values imported will be converted to the new SHARE_ACCESS setting as follows:
VISIBLE_TO_FEDERATED = TRUE is converted to SHARE_ACCESS = ANY
VISIBLE_TO_FEDERATED = FALSE is converted to SHARE_ACCESS = FORBIDDEN
For more information about valid CSV formatting, see https://tools.ietf.org/html/rfc4180
- If you have already prepared your groups CSV file, skip to step 9.
- On the menu bar, click Admin and then, under Users, click Import Groups.
- With the Import Option set to Create groups or Synchronize groups, click Download Example File to save the example csv file to your computer.
- Make a copy of the ImportGroups.csv file and assign it a meaningful file name.
This new file is your groups CSV file.
- Open the file in a spreadsheet application, such as Microsoft Excel.
- Delete the second, third, and fourth rows. Do not delete the first row. Evidence.com expects the first row to contain the column names.
- For every group that you want to add, include a row in the file that specifies values for the group, as described in the preceding table. Ensure that each value is in the cell beneath the applicable header.
- Save your groups CSV file.
- Return to the Import Groups page in Evidence.com.
- Select the appropriate Import Option for the action you want to complete.
- Select Create groups if you want to add the groups in the CSV file without affecting any existing groups.
- Select Synchronize groups if you want to completely replace all groups currently in your agency with the groups in your groups CSV file.
- Under Upload file, click Select File and, in the dialog box that opens, select the groups CSV file on your computer, and then click Open. Then click Upload.
Evidence.com displays a list actions taken based on the groups found in the uploaded file. This includes information about errors that Evidence.com detected and about the deletion of previously existing groups that were not defined in the groups CSV file. - Review the list of actions taken.
- If you need to correct errors, update the CSV file as needed, click Import Another File, and repeat this procedure.
- Click Finished.
The All Groups page appears.
Define Members and Monitors
You can import definitions for group members and monitors. You define the members and monitors in a CSV file.
Note: If License Tiers are enforced or in preview mode for your agency, Group Monitors must be assigned to a Pro Tier role.
Each row in the members-and-monitors CSV file defines a single member or monitor for a single group. For example, if you wanted to add a user as both a member and a monitor to a group, the CSV file would include two rows: one row for adding the user as a member and a second row for adding the user as a monitor.
Note: Only the groups referenced in column A of the members-and-monitors CSV file are affected when you define members and monitors. For example, if groups 1 and 2 each have several members assigned and then you import a members-and-monitors CSV file that only includes rows that define members and monitors for group 1, Evidence.com takes no action on group 2.
The members-and-monitors CSV file must contain a header row and must have four columns. A sample ImportMembersAndMonitors.csv file is available on the Import Groups page. The following table describes the required values in the CSV file for defining members and monitors:
Column | Header Value | Value |
A | EXTERNAL_ID |
External group ID — The ID of the group to which the member or monitor is added. This ID must match the external group ID used to create the group. For more information, see Import Groups. If you specify an external group ID that does not correspond to an existing group in your agency, Evidence.com does not create the member or monitor and an error message appears in the list of actions taken. Valid external group IDs can be up to 255 characters. |
B | MEMBERSHIP_TYPE |
Member or monitor — Whether the row in the CSV file defines a member or a monitor. Valid values are the following two words:
|
C | ENTITY_TYPE |
User or group — Whether the member or monitor is a user or a group. Valid values are the following two words:
|
D | ENTITY_ID |
Identifier of the member or monitor.
|
For more information about valid CSV formatting, see https://tools.ietf.org/html/rfc4180
- If you have already prepared your members-and-monitors CSV file, skip to step 9.
- On the menu bar, click Admin and then, under Users, click Import Groups.
- With the Import Option set to Add members and monitors or Synchronize members and monitors, click Download Example File to save the example csv file to your computer.
- Make a copy of the ImportMembersAndMonitors.csv file and assign it a meaningful file name.
The new file is your members-and-monitors CSV file.
- Open the file in a spreadsheet application, such as Microsoft Excel.
- Delete the second, third, fourth, and fifth rows. Do not delete the first row. Evidence.com expects the first row to contain the column names.
- For every member or monitor that you want to add to a group, include a row in the CSV file that specifies values for the member or monitor, as described in the preceding table. Ensure that each value is in the cell beneath the applicable header.
- Save the file.
- In Evidence.com, if your session has timed out, sign in again and return to the Import Groups page by clicking Admin and then, under Users, clicking Import Groups.
- Select the appropriate Import Option for the action you want to complete.
- Select Add members and monitors if you want to add the groups in the CSV file without altering any existing group members and monitors.
- Select Synchronize members and monitors if you want to add new members or monitors and remove any members or monitors that are not specified in the CSV file.
- Under Upload file, click Select File and, in the dialog box that opens, select the member and monitor CSV file on your computer, and then click Open. Then click Upload.
Evidence.com displays a list actions taken based on the members and monitors found in the uploaded file. This includes information about errors that Evidence.com detected. - Review the list of actions taken.
- If you need to correct errors, update the CSV file as needed, click Import Another File, and repeat this procedure.
- Click Finished. The All Groups page appears.