Configure Custom Data

Prior Documentation Revision This section contains a prior version of CiviCRM Documentation. Go to Documentation Home for all current topics.

What is Custom Data?

CiviCRM comes with a standard set of fields for storing, searching, and displaying contact name, address, phone, email... information. However, many organizations need to record and retrieve additional information about their constituents. Use Custom Data to:

• Define additional data fields
• Specify the exact type of data to be stored (i.e. regular text vs. dates vs. numbers...)
• Organize these fields into sets of logically related elements for input and display
• Use this information to search for and segment contacts into groups
• Specify the style and placement of input fields used in CiviCRM forms
• Configure multiple choice options and default values

Planning Your Custom Data Requirements You will probably need to spend some time evaluating your requirements prior to configuring custom data in CiviCRM: If you are moving existing data (paper-based OR stored in another application) - review the CiviCRM fields available 'out of the box' (you can browse to the New Individual and New Organization input forms) and map them to the columns (fields) which you currently store and use. Survey the people who will be using CiviCRM as to any additional information which would enhance effectiveness or efficiency. Determine the type of data currently stored in fields which do NOT map to standard CiviCRM fields. If fields are currently implemented as multiple choice options - determine the list of values currently offered (and check whether the list of options needs modifications). More planning resources...

Do not use Custom Data to Record Interactions or Transactional Info Custom Data fields are best used to store characteristics of contacts. Good examples might be Voting Precinct or Annual Income. Transactional data such as donations, meetings or events attended, etc. are best stored as Activities and/or Activity History - as there will typically be multiple instances or occurences. See Configure Custom Activity Types and the specification for our upcoming CiviDonate module for more info.

Implementing Too Many Custom Fields May Cause Problems The number of custom fields CiviCRM can support will vary depending on your server capacity, MySQL version and other environmental factors. Too many custom fields can cause performance degradation, and may result in fatal errors from MySQL during search operations due to limits on the number of tables that an be "joined" in a query. We recommend keeping the total number of custom fields to 20 or less. If you must use more - be sure and test your setup thoroughly before putting it into production.

Custom Data Types and Input Field Styles

Selecting the appropriate data type for each custom field will help ensure that the information collected is valid and useful. The Alphanumeric and Note types are the least restrictive, but you will want to consider more specific types (Date, Money...) when applicable to your usage. Each data type is associated with one or more input field styles (e.g. Checkbox, Text field...).

Available CiviCRM data types - and the corresponding choices for input field style are:

Checkbox, Radio and Select field types are multiple choice - and allow you to customize any number of value options.

Configuring Custom Data - Step by Step

Create a Custom Data Group

Custom data is organized into groups (sets) of related fields. For example, you might create a custom data group for Volunteer Information - and then add fields for Skills, Preferred Volunteer Days, etc. A set of custom fields may be used for contacts of any type, OR may be applicable only to one type of contact (e.g. used for Individuals but NOT for Organizations).

• CiviCRM » Administer CiviCRM » Custom Data
• Click » New Custom Data Group
• Enter a Name for this set of fields. The name will be displayed to users as a fieldset legend, and as a navigation tab title for the Tab* display style.
• Select the type of contacts these fields will be used for.
• Change the Weight value if needed. If you have more than one custom data group, they will be arranged by weight on view and edit pages.
• Choose a Display Style. Select Inline to include this group of fields in the main contact Add/Edit form and Contact Summary screens. Select 'Tab' to create a separate navigation tab for display and editing these values (generally for less frequently accessed and/or larger sets of fields).
• Check Collapse this group on initial display if you want only the title for this fieldset to be displayed when the page is initially loaded (fields are hidden). Otherwise, the full group of fields will be shown when the form or page is loaded.
• Enter explanatory/help text to be displayed above the fields in edit mode using the Pre-form Help box. You can also include text below the fields (Post-form Help).
• Click Save
  • You should see a status message that your group has been added. Click the add custom fields link in this message to continue.

Create Custom Fields

You can now add one or more fields to the group.

• If you're not already looking at the Add Custom Field screen, click CiviCRM » Administer CiviCRM » Custom Data » View and Edit Custom Fields » New Custom Field
• Enter a Field Label - which will be displayed to users when editing and viewing this field.
• Select the Data Type and Input Field Type. The field (HTML) type choices are dictated by the data type. Refer to the examples in the table above if needed.
  • A section to enter Multiple Choice Options appears if you choose Checkbox, Radio (Button). or Select (drop-down menu) as your field type.
  • Enter up to ten (10) multiple choice options in this table (click 'another choice' for each additional choice). If you need more than ten options, you can create an unlimited number of additional choices using the Edit Multiple Choice Options link after saving this new field. If desired, you can mark one of the choices as the default choice. The option 'label' is displayed on the form, while the option 'value' is stored in the contact record. The label and value may be the same or different. Use the Weight column values to control the order in which the options are displayed.

    You Can Add and Change Multiple Options Later Don't worry if you're not sure about all the choices you want to offer for this field. You can go back and add, edit or remove multiple choice options at any time. From Administer CiviCRM » Custom Data » View and Edit Custom Fields, click the Edit Multiple Choice Options link. Use the same link if you need more options than the initial ten that can be defined when creating a new custom field.

• The field-level Weight value controls the order in which fields are displayed in a group. Enter a positive or negative integer - lower numbers are displayed ahead of higher numbers. CiviCRM will pre-populate this with the next available value as you add fields to a group - so you can leave it as is unless you want to alter the display order.
• For non-multiple choice fields, you may provide a Default value. Be sure and enter a value that matches the type of data for the field (e.g. don't enter text if the data type is Numeric). For date fields, use the following format: YYYY-MM-DD (e.g. 2005-01-01 )
• Enter any help text you want to provide for the field (Field Help box).
• Indicate whether you want to use values in this field to find contacts by checking Is this Field Searchable. Only check this box for fields that you determine are useful for finding and/or segmenting contacts, so as not to clutter up the Search forms. If you aren't sure, leave it unchecked - you can always go back and change it later.
• Click Save.
  • You should now see a listing of the configured custom field(s) for this group.
  • Click » New Custom Field to add another field, OR Administer CiviCRM » Custom Data in the navigation breadcrumb to move back up to the Custom Data Group level.

Previewing Custom Fields and Custom Field Groups You can preview the input form display for any of your custom fields by clicking the Preview action on the right side of the Custom Fields listings page. This allows you to quickly see your field help text, labels, and multiple choice options as they will be shown when editing contact info. CiviCRM » Administer CiviCRM » Custom Data » View and Edit Custom Fields You can also preview the entire fieldset, including custom group level help, using the Preview action on the main Custom Data listings page. CiviCRM » Administer CiviCRM » Custom Data » View and Edit Custom Fields It is also a good idea to review your custom data fields within the actual contact editing and display workflows. For example, if you've added custom fields for Individual contacts, click New Individual from the CiviCRM Shortcuts block. Inline style custom data group(s) should be included in this form. Complete the form and save the test contact. Then review the display of the custom values on the Contact Summary screen. For Tab style custom data groups, you should see a new navigation tab on the Contact Summary screen. Click this tab to view and edit the new fields.

Edit Multiple Choice Options

You can modify multiple choice options for custom checkbox, radio button and select type fields at any time. You can create additional choices, change the order in which they are displayed, edit the display labels, as well as disable or delete an option.

• CiviCRM » Administer CiviCRM » Custom Data » View and Edit Custom Fields
• Multiple choice style fields will include an action link to Edit Multiple Choice Options. Click this link to display existing choices.
• To add an option:
  • Click » New Option for ... below the option listings.
  • Enter the Option Label and Option Value (the label is what is displayed on the form and screen, the value is what is stored in the database).
  • The next available Weight is automatically provided, but you can modify this if you don't want the new choice to appear last.
  • Check Default if this choice should be selected or checked by default.
  • Click Save
• To edit an existing option:
  • Click Edit Option and modify settings as needed and click Save when you are done.

What Happens When I Modify Multiple Choice Labels and Values? Changing the Option Label for a multiple choice option does not affect the data actually stored for the field - it only affects the text that is displayed to the user on the input and view screens - effective immediately after you save the changed label. Modifying an Option Value will cause newly entered records to store the new value. It does not affect existing stored data values - until such time as that field is edited/updated for an existing contact. It also hides the fact that the prior values are stored - since they will no longer map to the available option values for the field. Hence, modifying option values should be avoided whenever possible.

Disable or Delete Custom Data Groups or Fields

CiviCRM allows you to either Disable or Delete custom data groups and/or fields. When you disable a group or field, you are simply hiding it - the fieldset or field will no longer appear on the input forms and existing data for these fields is no longer displayed. However, any data that was entered for these fields is still stored in your database and will reappear if you re-enable the field(s).

Deleting Destroys Data If you choose to delete a custom field or custom data group, any data that has been entered into these field(s) is destroyed and can not be recovered except by restoring a backup of your database. Only delete custom data groups and/or fields if you are sure that you will not never need the associated contact data in the future.