Basics:Custom Fields

From Cerberus Helpdesk Wiki

This is one of the few features in the Helpdesk where the name itself tells you exactly what it is. "Custom Fields" isn't like "Watchers" or "Broadcast", where the name won't make a lick of sense until you learn more about the feature. In this case, you can break the name into two parts: "custom" and "fields", and it's pretty obvious what you're getting into. "Fields" refers to data fields, or forms of input, you use every day when working with computers such as simple checkboxes or text boxes. The "custom" part of course implies you can create your own original fields beyond what the Helpdesk offers; to be clear you can't create your own types like a crazy checkbox/text hybrid, what we mean is you can make a new field similar to what we offer, and just give it your own name or label to use for whatever you want.

If you're relatively new to the Cerb system, meaning you're comfortable with all the fundamentals but as an administrator you haven't really looked into some of the advanced features, custom fields is the perfect place to start building from. Almost every major feature supports custom fields on some basic level, and custom fields are also the driving force behind many advanced workflows where a couple of different features need to work together.

Why Custom Fields?

Just about every thing in the Helpdesk has one or more stock "fields" you can set or modify as you please. Tickets have a group/bucket dropdown ("picklist" in Cerb terms), organizations have several text boxes for filling in a client's work address (street, city, state, zip code), and tasks have "due dates" and a "completed" checkbox.

All of these are standard fields the developers went out of their way to include, things that captured a certain property or idea they felt everyone would benefit from. Custom fields are so important because they give you additional fields of your choice to expand beyond what we already give you, the key being custom fields work exactly like the regular fields -- the same types (text fields, checkboxes, picklists) are available to choose from and they can be attached to the same objects (tickets, tasks, opportunities). The only real difference is that you get to give them whatever name you want to derive your own "meaning", and that's what the "custom" in custom fields represents.

How do Custom Fields work?

Custom fields can be attached to just about all the different source objects you find in Cerb. For instance you could attach your own unique fields to contact addresses, and some other user-created fields to all your tasks. As you browse around the Helpdesk, any place where our default fields are found, a custom field could be there too. Here's a handful of screenshots of different pop-up windows, tabs, and functions, where you might see custom fields in the wild. Remember even though custom fields are attached to lots of different objects, a lot of the places where they are used look identical because these objects share the same interface; for example, tickets and tasks both use an 'Edit' Properties window to set fields.

Peek

Clicking (peek) will open a pop-up window, and below the standard fields you'll see your custom fields; ticket peeks technically have two tabs, 'Message' and 'Properties', click over to 'Properties' to see the fields.

Other objects that don't technically have a (peek) button still use the same "peek"-style window; feedback has an '(edit)' link and you simply click e-mail addresses to show their respective fields.

Bulk Update

The button for "mass changes" is usually found at the bottom left of a list. Upon clicking 'Bulk Update' you will find a list of "do" actions, and below that will be your custom fields. Any values you set here will apply to all the items you checked (or the whole list if you chose that "With" option).

Worklist column

From any list, click 'customize'. The custom fields will be optional columns you can expose; each list will have its own fields (tickets, tasks, opportunities, etc.).

Edit button Properties tab

Starting in 5.1, the 'Properties' tab for an object is now inside the 'Edit' window. In the past, a ticket for example, would have its own 'Properties' section next to 'Conversation', that entire tab has been moved. Click the 'Edit' button near the top of the page and you'll see your custom fields.

Organizations (I believe) is the only object left that does not use the 'Edit' button interface, and still has the old 'Properties' tab on the page itself.

Search

Most objects in the Helpdesk can be searched through. To start searching for a specific type of thing you will usually have to visit its individual tab. Let's check out tasks as an example, since it has very few search filters to wade through. In the 'Add Filter' dropdown (right box) all the stock fields are included (Completed, Completed Date) plus any custom fields you added; unlike the 'Properties' tabs, there's a convenient "custom fields" label that separates them from the rest.

Your custom fields get the same treatment as the regular search fields. Depending on the type of field you can search based on text matches, date ranges, or status (yes/no).

Custom Field Configuration

As we've been discussing, custom fields can be attached to a variety of Helpdesk source objects -- when I say the word "sources" or "objects", in Cerb-speak I'm referring to the bigger concepts like tickets, tasks, and opportunities. Most of these are pretty self-explanatory, and a lot of the examples we just went over covered how a couple of the more prominent ones work. There are a total of 10 different sources you can take advantage of, but half of them need to be enabled ahead of time.

Click 'helpdesk setup', 'Plugins & Features' and enable each of the following:

• Community Portals
• Feedback Capture
• Knowledgebase
• Opportunity Tracking
• Time Tracking

When you're done, head on over to the 'Custom Fields' tab (also in 'helpdesk setup'). On the left sidebar you'll see all the sources we enabled plus the stock set.

Knowledgebase Articles & Community Portals

All of these sources should look familiar except for maybe these two; for those who've checked out the 'Custom Fields' tab before, these are new to the custom field scene starting in 5.0. And because they have radically different interfaces and public components, it's probably not obvious how to use their fields.

• Knowledgebase Article custom fields are applied to the articles themselves. Most importantly these are also for internal use only, any custom fields you create will not appear to your customers if you open up your Knowledgebase to the public as a Support Center module. The Knowledgebase keeps all custom fields in the 'Properties' tab of the 'Edit' window (next to 'Editor').

• Community Portals is the odd man out in this whole discussion, because technically custom fields have yet to be fully integrated into it. So for now this documentation is more of a placeholder for when it's ready. At the moment in 5.1, you can create custom fields the same way we've been recommending but you can't set the fields anywhere in 'helpdesk setup', 'Community Portals'. In other words, there's no (peek), 'Edit', or "Properties" tab where you can find the custom fields.

Creating your first Custom Fields

When it comes time to create your custom fields, you start by choosing what object you want them to work with. Here I've clicked 'Address' from the left sidebar and added a few custom fields.

You can add, delete, or change the name of an existing field; if you want to change the type (single line to checkbox), you would have to delete the field and create it again. You can also change the order the custom fields appear in the Helpdesk, *Job Title will always appear first followed by *Available between in pop-up windows like 'Edit'. You'll notice that I prefaced both custom fields with a star *, this is not necessary but used to make them stick out from regular fields in our screenshots.

No matter what source you pick the configuration works the same, but note the custom fields do not overlap. If you create a checkbox field for your addresses it won't appear in your tasks; if you need a task checkbox you need to create a second checkbox field just for tasks. Before we go over each type individually, a couple of notes:

Wait... I already have Custom Fields?

Even if this is your first time using custom fields, those of you who have upgraded from early 4.0 to 5.1 may find custom fields already in the system as you click around the different sources. The reason is, many of the stock fields we had in 4.x were moved into custom fields behind the scenes gradually as the developers grew less attached to them. The fact that their custom fields counterparts function the same way (show up in the same edit windows, accept the same data) means the transition was seamless, and you likely didn't even notice.

If you see some of these leftovers in your Helpdesk, that's what happened (you can always delete them if you don't use use them).

• Ticket: Next Action
• Address (contact): Phone Number
• Feedback: Lists

I bring this up specifically to also act as a warning, because down the road it's possible we'll continue to take this approach. By offering you an alternative that works identically to what we built, we can justify moving more and more of the defaults into custom fields -- removing the less important fields from all the new installs, and letting users that need those specific fields recreate them as they wish.

Types of Fields

Now that we've covered all the sources, we have 10 different types of fields to choose from to populate these sources. Most of the fields only ask you for a name (or label) so setup is fairly simple.

Text: Single Line

The text-based fields are ideal for any "free-form" english. Use the single line version for "short" one-word answers, single sentence responses or formatted numbers like a phone, serial, or order number -- do NOT use the number field (more on that in a second).

Text: Multi-Line

Another "free-form" field. Use the multi-line variation for longer responses or anything that needs line breaks or paragraph style formatting.

Number

Any integers, or whole numbers, that are not formatted with any symbols such as a running tally (or count). The number field will truncate numbers with hyphens, decimal points, currency symbols ($) and leading zeroes. So as counter-intuitive as it may be, make sure you use Text: Single Line for any numbers that fit this criteria, otherwise...

• Phone Numbers: 555-9999 -> 555
• Money: $78.99 -> 0
• Order Numbers: 0003672 -> 3672

Date

Date actually accounts for dates as well as time of day. Date fields produce the same "date and calendar" function you see throughout the Helpdesk, such as a Task "Due Date" or the "When would you like to resume this conversation?" inside ticket replies. To select your date a mini-calendar is available.

A text field is also included for manual data entry where all the typical Helpdesk "shorthands" are accepted (keywords are not case-sensitive).

• Dates (Relative)

• Current date, day, and time: now
• The current day, date at midnight (in the past): today
• Yesterday at midnight: yesterday
• Future day of the week [if it's today, midnight (in the past)]: wed, wednesday
• Tomorrow at midnight: tomorrow
• X number of days, weeks, or years from now (keeps time): 4 days, +4 days, 2 weeks, +2 weeks, 1 year, +1 year

• Dates (Absolute)

• Month Date (Year) [no quotes needed]: Sep 3, September 03, Sep 3 2010, September 03 2010, 3 September 2010, "September 3, 2010", "September 3rd, 2010"
• month/day(/year) [American standard only, d/m/y will not work]: 9/3, 09/03, 9/3/10, 09/03/10, 09/03/2010

• Times (Relative)

• X number of minutes or hours from now (will properly extend to the next day): 30 min, +30 min, 30 minutes, +30 minutes, 48 hours, +48 hours

• Times (Absolute)

• Standard time of day (excluding AM/PM will default to AM): 2:45, 2:45AM, 2:45PM
• Military time: 13:00, 16:30

• Date + Time combinations work too, such as tomorrow 9:30AM and Sep 03 21:30.

Because the calendar pre-fills the text field for you automatically, you can pick a date with the calendar, and then simply add your own time. By default the calendar technically sets the time to midnight, after you pick a date in the calendar notice there's no timestamp (Friday, 3 September 2010). Save changes, re-open the edit window, and you'll see 00:00:00 (midnight).

Note when you don't specify a literal date the most "natural" choice is determined automatically, usually with a lean towards the closest FUTURE match. If it was a Sunday, and you typed in "Wednesday", you'd get the upcoming Wednesday, not last Wednesday or the Wednesday two weeks from now. If you excluded the year from your date (Sep 08 or 09/08), it would translate to September 8th, 2010 -- not September 2008.

The one exception to the future date rule is when you're referring to the current date: "Wednesday" on a Wednesday, "today", or 09/08/10 on September 8th 2010, would put you at midnight that morning which is technically in the past.

Picklist

You might want to think of these as "dropdowns". You provide a handful of options, or choices, upfront during configuration, then in actual use you select one choice from the dropdown. The field options support any text, so you can pick a single word, a phrase, a sentence, or even numbers.

Multi-Picklist

Same idea as the picklist, but like the name suggests it supports multiple selections. Here a customer was reporting several issues with our product, and we've categorized the ticket as such via custom field. Use the CTRL key or CMD key (Macintosh) to select more than one choice; remember you can always select just one.

Checkbox

The most self-explanatory of the group, a simple checkbox with two states: ON/OFF or YES/NO. Here we're using a custom field to mark a primary contact for this organization.

Lisa is the primary contact for the Customer Example, LLC.

Notice how we're looking at the 'People' tab on the organization's page but still clicking into an address to use the *Primary Contact field. We've also changed the first worklist column to "*Primary Contact", so we can push him or her (Lisa White) to the top of the list.

• Unfortunately with checkboxes there is no in-between state. If you don't know who the *Primary Contact is, you could not indicate "Don't Know" by not marking the checkbox; "Don't Know" would be equivalent to "No" in the Helpdesk.

Multi-Checkbox

Again much like the relation between picklist and multi-picklist, multi-checkbox gives you the option to make more than one selection, but this time you don't need to hold CTRL or CMD down. Notice we're using the same "experiencing issues" example as multi-picklist, the difference between the two mainly comes down to the style you prefer.

Worker

Remember the old "Next Worker" concept in Cerb4? One ticket for one worker?

This is kind of like that. You get a worker dropdown of all the workers inside the Helpdesk just like the old interface; it is NOT the Owners chooser like you see in 5.1 that lets you do multiple assignments. In the past worker custom fields enabled you to simulate multiple assignments -- the ticket "Next Worker" system of previous versions would assign the ticket to one worker, and then you could use a complementary worker custom field to assign the ticket to a second worker, sort of like "Another Next Worker". For better or worse, the new Owner functionality is so strong that it limits many of the potential use cases for the worker custom field.

There is one simple use case still available that's assignment-related I can recommend. Owners does not touch the Knowledgebase yet (although it's likely only a matter of time) so you can create a worker custom field to represent ownership, maybe like a dedicated editor for the article.

• At the risk of confusing you, be aware that workers are also a source object you can attach custom fields to (see the left sidebar in helpdesk setup, Custom Fields). Which means in theory you can attach worker CUSTOM FIELDS to the workers themselves inside 'helpdesk setup', 'Workers'. A simple example is creating a worker field to assign each worker a manager, or supervisor.

URL

In this field you can input any web or internal link you see fit, it could be a company's website or an internal file you have on the network. Once you save a legit URL in the text field, the custom field label will turn into an active hyperlink for you; this way you can still freely edit the "plaintext" URL should you want to make a change.

(Group) Ticket Fields

Tickets is the oddball in the custom field space, because technically there are two "levels" of ticket custom fields -- global and group. Every ticket supports global fields, as long as a worker can "see" the ticket, he or she should be able to modify those custom field values (remember tickets are hidden from workers if they are not a member of the group).

The second ticket tier is group-level fields, the idea being you can attach ticket custom fields to the groups themselves (Dispatch, Sales, Support). Group fields are only visible when the ticket is in the corresponding group -- a Support group field would only appear when the ticket was in Support, if it moved to Sales those fields would be hidden. Under this design your group members can access their own "private" custom fields to use as they see wish.

• Here's the ticket in the Support group (see 'Bucket'), there is one global custom field and one support group custom field.

I moved our earlier multi-checkbox example "*Experiencing issues with" to a group-level custom field.

The "(Global)" and "(Support)" labels are not typical, I added those to the custom field name during setup to make the examples more clear. Normally you would not be able to distinguish between global or per-group custom fields by just eyeballing the names.

• Here's the same ticket after I moved it to the Sales group. Notice the "(Support)" custom field is gone and two "(Sales)" custom fields took over.

If a ticket is moved the fields are not permanently erased, as soon as the ticket is moved back they will show up again, values intact. When I move the ticket back to Support, I will see the *Experiencing issues with custom field as well as "Upgrading" and "Software Crashes" selected.

• Global ticket fields must be configured by a Helpdesk administrator in 'helpdesk setup' just like we've been doing thus far. Group-level fields are configured in 'group setup', 'Ticket Fields', and can be done by the group's manager or an administrator.

Custom Fields in other features

Remember what I said at the very beginning about custom fields being important building blocks for different workflows? It's time to explain what I meant with a quick overview. All of these features and ideas do have separate documentation, covering everything from start to finish, unfortunately they tend to be written in a way that glosses over the custom field aspect. Links to full documentation are included at the bottom of each section.

Snippets

Snippets are the 5.x version of e-mail templates with a little more flexibility. You can pre-compose a simple template and then use that over and over in your replies instead of typing it out every time. One of the interesting perks with snippets is that they have access to a ton of tokens, or placeholders, that swap with all the standard fields in the Helpdesk plus the custom fields you created.

To use any field, custom or standard, select it from the dropdown and the token will be added to the message box. Tokens are visually represented with a string name surrounded by curly braces; a custom field token will include the word "custom" followed by an ID number (the number used is listed in 'helpdesk setup', 'Custom Fields').

Here we're using a single line custom field on a worker to represent a phone number, {{worker_worker_custom_18}} .

The next several features: broadcast, auto-responses, and signatures, are "snippet-compatible" which means they share a similar interface and have access to the same set of tokens (custom fields). All three features, including snippets, always have access to worker, organization, and address based custom fields. Whether or not you can add ticket custom fields to that list depends on contexts: ticket-centric or worker-centric.

• Learn more about snippets and contexts?

Broadcast

Broadcast is a tool you can use to reply to multiple tickets at once, the idea being you select a handful of tickets, compose a "generic" reply, and then send that single message out to each ticket with one click. Just like snippets you can select your custom fields from the dropdown to insert placeholders in the form of tokens. Since you're replying to multiple tickets at once, the tokens will be swapped out with the corresponding custom field values for each ticket. Broadcast uses the snippet ticket context, so it supports ticket custom fields.

To determine which hosted installs are on which hardware we compare a preconfigured address (picklist) custom field: *Hosted On {{custom_26}}, where possible values include black, white, red, or yellow. A very simple IF/ELSE block automatically sends the correct maintenance window to the right contacts.

• Learn more about broadcast?

Auto-responses

Auto-responses are designed to trigger a preconfigured reply to the original sender (FROM) on a ticket. There are two auto-response actions, one for new mail and the other for when you close ("resolve") a ticket. New ticket and closed ticket auto-responses are optional settings done per-group inside 'group setup', 'Mail Preferences'. Auto-responses use the snippet ticket context, so they support ticket custom fields.

Here I'm checking for keywords inside an address (single line) custom field using IF/ELSE statements: {{initial_message_sender_custom_19}} .

• Learn more about auto-responses?

Signatures

Personalized signatures is another Helpdesk feature snippet-compatible and custom field ready. A signature in Cerb is just like a signature in your standard e-mail client, the only difference is they're organized per-group. Each group can create their own signature (otherwise they get the default) and personalize it to include the worker's contact information, so each worker's reply sounds like it's from them.

Again we're using a single line custom field to represent a phone number, {{worker_worker_custom_18}} .

The default signature is configured through 'Mail Setup' (helpdesk setup) and the group signatures in 'Mail Preferences' (group setup). Signatures use the Snippet worker context, which means you do NOT have access to ticket custom fields.

Mail Rules

At this point we're done with features that use the snippet token system, so now it's all about using custom fields the way we did before. Mail rules are for automatically "handling" incoming mail as it enters the Helpdesk; this could be anything from tossing spam, to moving mail into one of your groups, (and most importantly for us) to setting custom fields. Mail rules all use a criteria system, where you check if X matches and if it does do Y. The Y we're concerned with right now is setting a ticket custom field. In practice you could do something as simple as "If To = 911@example.com, set Priority custom field = ASAP".

Mail rules have three layers, or gates, where mail must travel through before it hits its destination but only the latter two support setting custom fields.

• Mail Filtering (helpdesk setup) is where you can stop mail from becoming tickets (or replies from being added to the ticket) by "rejecting" it. Spammy messages or vacation responders can be dropped, redirected to a different e-mail address, or bounced. At this first stage you cannot set custom fields.

• Mail Routing (helpdesk setup) is the second stop on the journey and controls what groups mail gets sent off to. Here you can start setting custom fields because mail that makes it this far (gets past mail filtering) is now part of a functional ticket. You have access to all of your global ticket custom fields.

• Inbox Routing (group setup) is the last stop and lets each group decide how it handles mail. You can push it to a specific bucket, assign it to a certain worker, or mark it resolved immediately (status = closed). Here you have access to both the global and that group's own local ticket custom fields.

On all "new orders" we use inbox routing to mark all the sales options our customers paid for.

Custom fields are a two-way street when it comes to mail rules. You can also use them as criteria in your filtering, reading the current values on new mail and taking action based on their values. The question then is how does a customer send in mail with custom fields already set? Well this is only possible with mail coming in from the Support Center*, which we'll talk about next with contact forms. (*Developer's Note: You can set custom field values based on header values, too, through use of a custom plugin. See Plugin:Header_Filters for more information.)

• Learn more about mail rules?

Contact Forms

Last, but not least, is the most complicated example of all, as there are several topics at play now. First you have to understand that, as suggested earlier, the Helpdesk can be outfitted with a complementary Support Center - the public component of Cerb - that your customers can log into. One optional module you can enable with the Support Center is a public contact form. The contact form is a second way to accept incoming requests from your customer base; instead of e-mailing you directly they can open a ticket by filling out a form.

The more advanced contact forms, in addition to the message itself, let you pitch questions for your customers to answer -- "What problem are you having?", "Do you want to be contacted by phone?", "What's your daytime telephone number?". These are called follow-up questions in Cerb lingo and are what we'll focus on here, as each question can be linked with a ticket custom field.

• What problem are you having? -> Multi-Checkbox (Can't Install, Software crashes, Slow performance)
• Do you want to be contacted by phone? -> Checkbox (yes/no)
• What's your daytime telephone number? -> Single Line

The star * in front of "What problem are you having?" makes it a required field.

The top half of the screen is part of the 'Open Ticket' module in 'helpdesk setup', 'Community Portals', the bottom half is the actual Support Center your customers would see. Each question's custom field is the customer's to fill in however they want -- your internal staff does NOT have to go find the ticket later and "copy/paste" their answers into the custom fields, the customers are literally "setting" the custom field themselves.

The beauty of this (as we talked about earlier) is that your mail rules can detect these custom fields and treat them as criteria. If someone answered "Yes" to "Do you want to be contacted by phone?", you can create a mail routing rule that pushes that ticket into a Support bucket called "Callback" and assign it to your tech guy automatically.

• Learn more about the Support Center and contact forms?