ssossossosso
Media library

How to Create A Custom Field

by Brandon Kim

OroCRM allows users to create custom fields in order to collect additional details that are not included out of the box. For example, the contacts entity has fields of information such name, address, phone number and so on. But suppose you wanted to capture additional details, such as their tumblr handle, so that you can target this user for various promotions.

While many social media ID fields are provided on the contact record out of the box, a new field is required. A custom field added to the contact entity allows you to capture this information.

To create a custom field:

  1. Navigate to the main system menu and select Entities and then Entity Management
  2. Select the contacts entity.
    1. The Contacts Entity record displays.
  3. Click the  Create Field button in the top right hand corner of the screen.
    1. A blank General Information Entity form displays. This grid contains all the existing fields related to this entity.
  4. Define the Field Name. For this example we’ll use TumblrID
  5. Select a storage type.

Serialized field allows admins to create simple custom fields that keep information for a single entity without a schema update. This means that there is no need to shut down/restart the system in order for these fields to display.

      1. Serialized fields cannot be used for grid filters, for reporting, chart generation, data audit or creation of segments and relations.
      2. Serialized fields cannot be used for files, multi-selects or option sets.
    1. Table Column store field values to a database table. A schema update is necessary for this field to be available.
  1. Chose a field Type.  For this example we can choose a string value for our Tumblr ID. Other values such as date and time, currency, integers and images are just a few of the pre-formatted fields available.
  2. Click the Continue Button in the top right hand corner of the screen.
  3. Depending on what has been selected for the field Type, additional fields are displayed.

General Information

  1. Enter a label for the field. The label is the name displayed for the field in the user interface and does not need to match the field name. For example, the field might be called “Tumblr” but the label might say “Tumblr Handle”. By default, the name of the field is automatically listed as the label, but you can change this value.
  2. Fill out the description. The information detailed in the description field displays on the user interface when hovering over the information tooltip icon on the left of the field when entering data. This field is not required, but is highly recommended to help guide users who may need a better understanding of the the information required for that specific field.

Click the Import and Export Link. This section details name and placement of the custom field for importing and exporting only.

  1. Define Column Name. If no name is used here, then the default Label will be used. This will be the name/column in the CSV file.
  2. Type Column Position. Type a number that corresponds to the position of this field in the .csv file that contains entity records.
  3. The use as Identity field defines if this field will be added to record identification. An example of a field used as an identification field is contact name. Additionally this field is used to determine unique values in the CSV file.
  4. In the Exclude Column? Field, select NO if you want this field available for Export or Yes if you wish to exclude the column. This means this field will not be included in the csv export file or any Other.
  5. In the Available in Email Templates field select Yes if you’d like this field to be available for use in templates.
  6. The contact information field has 3 possible values:
    1. If you leave this field empty, this custom field will not be treated as contact information.
    2. Selecting email in this field means that the values of the field are treated by marketing lists as email addresses.
    3. If Phone is selected, the values of the field are treated by marketing lists as a phone number. For our example, I’ll leave this field blank, as the information in this custom field is not contact information.
  7. The Add to Grid Settings options controls the availability and display of a field in the Grid. By default “Yes and Display” are selected by default and makes the field available for use in the grid. Yes and do not display means the field is hidden by default and Yes as Mandatory adds it permanently to all grid views.
  8. Show Grid Filter – Select Yes if you wish to have the new field’s filter displayed on the user interface by default. Select No, and it will not be displayed by default, but you can add it as a filter if needed.
  9. In the Show on Form field, select Yes if you wish to have this field displayed and editable on record and page edits. The ability to edit depends on the permissions of the logged in user.
  10. In the Show on View field, select yes if you would like the field displayed on record view pages.
  11. Priority defines an order of custom fields on entity record view, edit, create pages, and on the respective grid.
    1. Custom fields are always displayed one after another, usually below the system fields. If no priority is defined or the defined priority is 0, the fields will be displayed in the order in which they have been added to the system. The fields with a higher priority (a bigger value) will be displayed before the fields with a lower priority.
  12. If the searchable field is set to yes, this field will be indexed and returned in search results.
  13. Select if the field is an auditable field. If set to Yes, the system will log changes made to this field values when users edit entity records. Not available for serialized fields.
  14. Applicable Organizations check box determines if you want this field to be available throughout all organizations.
  15. When you are finished configuring your new custom field, click the save and close button in the top right hand corner of the screen.
  16. Please note that before any field is viewable on a form or a vew page, users must first update the schema. Serialized data fields do not require a schema update. Once you have finished configuring your field, click the red “update schema” button in the top right hand corner of the screen.
  17. Return to the customer contact grid and create a new contact.  You will notice that our new field has been created under the additional link.

Example 2 Selector

Another example of custom field creation allows you to select one of a number of options. We can demonstrate this by navigating back to the entities grid and selecting the contacts entity.

  1. Click the Create Field button in the top right hand corner of the screen.
    1. A blank General Information Entity form displays.
  2. Define the Field Name. For this example I’ll use Location to demonstrate multiple choice selection.
  3. Select Table Column for Storage type. This type of custom field saves this information the database and requires a schema update.
  4. Chose a field Type.  For this example we can choose select, to give the user the option to use a drop down menu to select one of a several possible choices.
  5. Click the continue button.
  6. On the right of the screen  you will see a field to add available options for your new selection field.
    1. Enter West Coast (click the add button)
    2. Enter East Coast (click the Add Button)
    3. Enter Remote Office
    4. Click the checkbox next to one of the choices if you would like one of these options to be set as default.
    5. You can drag and drop these options in the desired order by clicking on the option using the (up/down) arrow to move the options into the correct position.
  1. Fill out the rest of the form according to the instructions in the previous step.
  2. When you are finished creating the custom field, click the Save and Close button in the top right hand corner of the screen.
  3. When you return to the view page of the contact entity, you will see a red update schema button in the top right hand corner of the screen. Click on the red button to update the schema. Please note that if you do not complete this step, your field will not be visible in the user interface.

After the schema has been updated, navigate to the customer contacts option and click the Create Contact button. Now when creating or editing a contact record, you can see the new custom select field.

custom fields

ssossossosso