Custom fields are a powerful tool to address specific scenarios. This document is intended to serve both as a training aid for using custom fields in CommunitySuite and as a guide to thinking about ways to use them.
In contrast to standard fields that exist in every CommunitySuite instance, custom fields allow each foundation to add their own fields to the database. This may be useful where specific information is being captured that does not have a designated location provided in the standard Foundant database. Because custom fields are unique to the organization, there are functional limitations that are important to understand:
- Custom fields can be used for reporting and tracking, but cannot be used for workflows.
- Custom fields are partially supported in filtering. Filter lists that show a specific pre-defined list of fields (profiles, donations, grants, pledges, scholarships, general ledger) do not support custom fields. Filter lists where you see a “[filter]” link (such as in grants buckets) do support custom fields.
- Custom field data is only available using custom reports. Standard reports will not include custom field data. As a result, custom fields work well for specific needs like basic coding of grants or coding an organization by a particular interest area where you want to be able to pull a custom report with that specific data.
Creating a Custom Field
Let’s start with how to build a custom field. First, a custom field has to be attached to a particular system record. A record is something that exists in the various areas of the system. Records that can have custom fields are profiles, general ledger accounts, grants, scholarships, funds, donations, split interest agreements, internal loans, invoices, opportunities and vouchers.
A custom field is defined by going to the appropriate area for the record listed previously and clicking Custom Fields in the left menu.
When you click Create to add a custom field, you will see a screen like this:
See below for more information about each field that's available when creating a custom field.
Custom Field Name
This is the text you will see on the screen whenever someone views or edits a record.
Custom Field Type
Custom Field Type refers to the type of data that will be contained in the field. See below for more info about each available field type.
Dropdown is used to hold a list where the user can select a single option.
Multiselect allows for the selection of multiple values. The same notes as Dropdown apply for changing, rearranging, inactivating values and migrating into these fields.
Nested List allows you to select from a list with primary and sub values (i.e. create a second level of coding).
Date Field allows a user to enter a date.
Text is used to hold anything that someone can type in, like a description.
Description allows you to enter reference notes about how the field is used.
Required means that this field must be given a value when a record is created or edited.
Active means the value in a field can be set or edited.
Display Order allows you to change the way fields appear on the screen when there are more than one custom fields for a record type.
Import Code is used in two ways:
- Referencing the field in a template.
- Referencing the field value when it's imported into the system in custom migrations.
Apply to Profile Types
Specifies whether or not the field applies to individual, household, or organization profiles.
Field Design Best Practices
One pitfall to custom fields is the risk of creating messy data over the long term. With too many or unused fields, it can become hard to find the data you need. Custom fields can become like a junk drawer, and we have a few pointers to avoid this:
- First, ask “Why do we need this custom field?” Will it be used to help make decisions or is it just informational/reporting? Is there a way to accomplish this in the system already without adding the field? Do you already have another field that serves a similar purpose?
- These questions also help clarify how you would design the field. If it is informational, it is OK to have it be a plain text field where anything can be entered. But if it is going to be used for decisions or more advanced reporting, you may want to enforce particular values.
- Next, ask “Where should I attach a field?” The simplest way to think about where you want to put it is to ask “Where would I look for this if I wanted to change the value?”
- Also think about things like having more than one possible value. The more you add, the more you have to maintain. And once added, don’t be afraid to delete the field if it is no longer being used.
- Last, it's important to control who can add/delete custom fields from your list. We recommend keeping tight control of this permission to avoid over-use.
Permissions for Custom Field Maintenance
Custom fields have their own separate permission that can be accessed in Group Permissions (look for “Custom Fields” in the list) or from the Custom Field Objects Screen (click the permissions link). Once there, you will see something similar to this:
By default, the admin group has full permissions and all others have view permissions. It is highly recommended that you leave it this way. Changing it to “None” for a group will remove their ability to display the list and access details of the custom field such as the import code value, which is needed if working with the field in other areas.
Advanced permission allows you to separate the create, delete and edit permissions as well. If you want a few people to add but only one to delete, you could accomplish this with a second group. Both groups would use advanced permissions but only one would have delete as an option (or have full which includes delete).
Example Scenarios for Custom Fields
Now that you know how to define a custom field, it is time to put them to use. We’re going to use a few different examples for some custom field scenarios to learn some things we can do with them.
- Adding a donation source to donations
- Grant coding and reporting
- Grant program workflow filtering
Example 1: Adding a Donation Source to Donations (Basic Tracking)
One item that has been different for foundations in terms of what (or even if) they want to track is a donation source code. For some foundations, this would be like a dropdown field, while for others it may be a multi-select field. For our example, we’ll make it a dropdown field so there is only one value.
Let’s begin by creating the field. In your Sandbox site, go to the Donations module and click Custom Fields in the left menu. Click Create and create a field that uses what you see below.
In this example, Dropdown has been selected to only allow one source for the donation. If you wanted to allow multiple values, you could change it to a Multiselect. Once you have created the field, create a donation. At the bottom of the donation, you will see this.
You can click the  link to assign a value. You can also click edit in the left menu to edit the entire record. Either one should get you a Dropdown list that looks like this.
Note that you can only select one value and (other than blank) it has to be one of the values you entered as possibilities. This makes reporting easier and more consistent. In this example, it is highly probable that someone would want to see donations broken down by these source values. Since summarization is possible, we want to make sure our users are consistent with how they enter a value. Using a Dropdown enforces that consistency.
Important: This is one of our single most important skills when you add a custom field. Always think about how it will be used once it has been entered. Is it just being listed or do you want to summarize on this field?
Let’s move on to our next scenario and do some reporting. In this case, we’re going to add the UN Sustainable Development Goals (or SDG) to our grant coding. We’re also going to see how to mass update a series of grants to enter in a specific answer.
Example 2: Grant Coding and Reporting (Using Custom Reporting and Bulk Setting Values)
In your Sandbox site, navigate to the Grants module and select Custom Fields from the left menu. Click Create and enter a field like this.
We now have a list of possible values. If we’re adding grant coding, we probably want to populate these codes on our historic grants. To do this, we need to create a custom report on grants. It doesn’t matter what fields you put in the custom report as long as Grant ID is one of them (in fact it can be the only field). Once you have created the report, add a filter to bring your list down. Most likely for this one, you would use Grantee.
In the screenshot below, you see a quick report with ID and Grantee and then filter for the grantee “Sawgrass Nature Center and Wildlife Hospital Inc”.
Note the highlighted link for Set Custom Field. This link only appears if the ID is shown (so for profiles, use Profile ID, for funds use funit_id, grants use grant_id and so on…). Once you click the link, you'll arrive at a screen like this.
This allows you to choose which field you want to answer for everything in the report. In this case, there is only one field available. Click the link for “UN SDG”. Now you can set your answer with a screen that looks like this.
For this particular grantee, they work heavily with Goals 14 and 15. Check both boxes and click the Save button. Once the answers are selected, click Save. You will get a confirm box:
In this case, it is telling you there are 114 grants that are going to be set to the answer. Click Yes to save them or No to cancel. In this case, click Yes. You will see:
The answers to custom fields can take some time to populate. To avoid a browser timeout it runs as a background job. When it is finished, you can look at the job and see a detail:
If there are errors, the Message field will tell you what the errors are.
The screenshot below shows a grant report with ID, Date, Amount, Grantee and UN SDG goal with a filter for grants in 2020.
Note that the grant to Sawgrass Nature Center has a value while the others are empty. You could also use the UN SDG field as “Group By” to total the grants by SDG.
When you are using a Multiselect type of field, “Group By” will work, but each combination will result in a group. For instance, using SDG as a multiselect could result in a group that is “Goal 2”, a group that is “Goal 3” and a group that is “Goal 2, Goal 3”. This is another important consideration when deciding between a Multiselect and multiple Dropdowns.
If there were multiple dropdowns for SDG, you could only group by one of them. For instance, if something meets multiple goals and you want to report them separately rather than on just one of the goals, use Multiselect. If you want to assign a primary and report everything in just that primary, use multiple Dropdowns.
Example 3: Grant Program Area Example (Custom Workflow)
The next example illustrates how to create a program area for grants used in grant processing.
Add this field in your Sandbox site like before. Go to the Grants module and click Custom Fields in the left menu. Click Create and create a field that uses what you see below.
Now, navigate into the grant Approval bucket. You’ll see several grants in this example:
You’ll note we don’t see the custom field here. When you are going to utilize a field as part of the process, this is when you will need to use filters.
Let’s say you want to work with the Panther Needs grants. First, add the field to the filter. It’s easiest by using the search. Click the Filter link (under the words Approval Grants) and type “Program” in the search area. This shows the Program Area as a result.
Click the Program Area link and you’ll see “Add Filter Program Area” like this.
The box for “Panther Needs” is already checked. Now click Apply Report Filter. The approval list just got shorter.
Integrating Custom Fields with GLM/SLM
An integrated custom field is a custom field in both systems that is connected via the platform and will update from CommunitySuite to CommunityGLM/SLM and vice versa. It is vital that your CommunitySuite administrator and GLM/SLM administrator communicate and agree on which fields will be integrated and how the information will be uses, as not all custom fields should be integrated.
For more information on integrated custom fields please check out the article below:
For additional help with custom fields, check out the resources below, or speak with your CSM:
Foundant Help Menu
- "How to Create Custom Fields" walk-thru, which can be found in the Foundant Help Menu (question mark icon) in your sandbox and live site.