1. Purpose

This document is the user guide for the Zendesk app "Strawberry Fields" provided by Lovestock & Leaf. This guide will be updated periodically as new features are added to the product.

2. Guide

2.1 Background

Ever wanted to add a date field to your tickets? Now you can, and it comes with a handy date picker calendar.

You can now also disable any field so that it is read-only.

A brief description of the Strawberry Fields app is available at the following link:

http://www.lovestockleaf.com/zendesk/zendesk-apps/strawberry-fields.html

Zendesk doesn't have a date field available for custom fields. Strawberry Fields introduces date fields to tickets and provides a popup date picker calendar for ease of use.

With Strawberry Fields you can also disable any field (system or custom), on both the Help Centre request form and/or in the agent view. This will make the field visible but read-only to the user.

2.2 Using the Strawberry Fields app

 

The Strawberry Fields app is found in the right-hand ticket sidebar for existing tickets.

The screenshot above shows the different field types which Strawberry fields provides. When there are no fields for Strawberry Fields to display, then it appears as following.

Strawberry Fields creates the following field types:

• Date
• Range slider
• Range buttons
• Convert drop-down to buttons
• Read only
• Hidden
• Multi-select for checkboxes

These are discussed in the following sections.

2.2.1 Date

When a field is configured as a date field, then the date field in the ticket form on the left is hidden and it is displayed in the right hand app panel. When you click on the date field, you see a date picker where you can easily choose a date.

When you select a date from the widget, it will populate the value into the field.

2.2.2 Read-only

The Strawberry Fields app can also disable fields as is shown below. The field is read-only or disabled in the ticket form on the left, but it is not shown in the Strawberry Fields app.

This field is not shown in the right hand side app, but is disabled in the left hand ticket form.

2.2.3 Range slider

The Range slider is a widget which converts a numeric or decimal field into a slider. The field is hidden on the left hand side ticket form, but is shown on the right in the app.

As you move the slider, the number in the slider is what is saved into the field.

2.2.4 Range buttons

The range buttons is a widget which converts a numeric field into buttons. The field is hidden on the left hand side ticket form, but is shown on the right in the app.

When you click on a value, this is what is saved into the field.

And clicking on the value again sets the value back to empty.

2.2.5 Convert drop-down to buttons

The Convert drop-downs to buttons widget converts drop-down to buttons. The field is hidden on the left hand side ticket form, but is shown on the right in the app.

When you click on an option, then that option is highlighted.

And clicking on the selected option will then set the field back to empty.

 

2.2.6 Hidden

This field type hides the field from the left hand ticket form.

2.2.7 Multi-select

The multi-select will convert multiple checkbox fields into a single widget. The checkboxes are are hidden on the left hand side of the form, with the combined checkbox widget shown on the right side of the app.

When you check or uncheck a checkbox in the multi-select widget, the corresponding custom checkbox fields are updated.

2.2.8 Searchable Drop-down

Locations: helpcenter

The drop-down fields on the Help Centre forms do not allow user to type in to quickly search for corresponding option. This plugin is to provide searchability on the dropdown field.

  - field: [23814128, 3898934890]
    fieldType: dropdown
    fieldOptions:
        searchable: true
        searchText: "Search for options"

The configuration above set the custom fields with ids of 23814128, 3898934890 to be a dropdown field with searachble feature

• searchable = this must be set to true for this feature to be enabled
• searchText = this is the text to display in the search box to the end-user (Default: empty)

Note: if set to

  - field: all

it will apply to all dropdown fields on the Help Centre

 

2.3 Where to configure the Strawberry Fields app

The preferred way to configure Strawberry Fields is using the “Lovely” Zendesk app. This will have been installed at the same time that this app was installed.

On the left sidebar of your agent screen, there should be now a cloud icon, this is Lovely (CloudMetro) app. Please click on it and select “Strawberry Fields”. This will open Strawberry configuration screen where we can define the config in YAML languange.

2.4 Configuration

Standard Config Format

Each field config should have the following standard format to be put in Strawberry Fields configuration:

 

  - field: <<field_id>>
    fieldType: <<type>>
    fieldOptions:
        <<options>>

 

• field_id: this is the field ID of the field we want to apply Strawberry on. To find out the field ID of each field, in Strawberry configuration screen, there is “ID Viewer -> Ticket Fields”. Multiple fields can also be defined. e.g. instead of
  

      field: 123456

  we could also have
  

      field: [123456, 7891230, 1234526]

• type: the enhancement that Strawberry support as mentioned in the below enhancement types list
• options: each enhancement have specific options (for example, if it’s a “Date” enhancement, we can have options to define date format, date range etc.). Please refer to each enhancement below for supported options of each enhancement type.

 

Enhancement Types

The configuration field in the settings is where the Strawberry Fields app is configured. It supports the following types and options for the fields:

• Date
• Description only
• Read-only
• Hidden
• Description
• Range slider
• Range buttons
• Convert button to drop-down

2.4.1 Date

Locations: agent, helpcenter, feedbackwidget

Strawberry Fields can designate a field as a date field. When you set up the custom field you should create it as a text field, or a regular expression field. The regular expression rule should match the date format you specify in the configuration.

  - field: [23814128, 3898934890]
    fieldType: date
    fieldOptions:
        dateFormat: "yy-mm-dd"
        changeMonth: true
        changeYear: true

The configuration above set the custom fields with ids of 23814128, 3898934890 to be a date field. Once you have set a field to be a date, you have further options to control the way it can be used.

• dateFormat = this sets the date format for how the date should be saved into the field and how it is presented to the user or agent
• changeMonth = this allows the date picker to change the month. The default is true if this option is not provided.
• changeYear = this allows the date picker to change the year. The default is true if this option is not provided.

2.4.2 Description only

Locations: helpcenter, feedbackwidget

Strawberry Fields can use a field to only show it’s description. This is only valid for the location of helpcenter and feedbackwidget. This is useful if you want to present instructions or helper text in the form for end users.

  - field: 21631754
    fieldType: descriptionOnly

The configuration above sets the field as type of description only. This means that the field is not displayed to the end user, but the description is. There is also additional options which can be set if you have the field as description only.

 

Important: if we want to show description based on field conditions, please use 2.4.5 Description with option hideLabel: true instead of using this plugin.

 

2.4.3 Read-only

Locations: agent

Strawberry Fields can also set a field as read-only or disabled. This means it will show the field, but it cannot be changed. This is only valid for forms in the “agent” location only.

- field: 21910384
  fieldType: disabled

This setting above marks the custom field 21910384 as disabled. Note that you can use the disabled field option with other options. For example you could have a date field, and disable it. If you do not provide the disabled option it is false by default.

2.4.4 Hidden

Location: agent

Strawberry Fields can also set a field as hidden. This means it will not show the field. This is valid for forms in the “agent” location only.

  - field: 21910384
    fieldType: hide

This setting above marks the custom field 21910384 as hidden. Note that you can use the hidden field option with other options. For example you could have a date field, and hide it. If you do not provide the disabled option it is false by default.

2.4.5 Description

Locations: helpcenter, feedbackwidget

Strawberry fields can move the location of the description for a field. This is only available in the form locations of helpcenter and feedbackwidget.

  - field: 22171890
    fieldType: description
    fieldOptions:
        location: above

The configuration option above marks the custom field with id of 22171890 to show the description above the field.

The valid options for the location are:

• above = The description will appear above the field
• below = The description will appear below the field
• tooltip = The description will appear as a tool tip. See the following section for the additional tool tip configuration options
• heading = The description appears at the top of the form
• default = The description is shown in the default location for the form
• placeholder = The description is shown as the placeholder for the field
• all = have the description appear in locations

Multiple locations are also supported:

  - field: 22171890
    fieldType: description
    fieldOptions:
        location: [above, below]

The description of the field must contain corresponding data for each location:

[above]

This text appears above the field

[below]

This text appears below the field

 

Strawberry Fields also allows you to show a part of a description based on some basic logic by using location:all .

 

To use this you should enter your content into the description for the field like the following with the id format is that <location>_<name>:

[below_section1]
This is content A
...
[above_section2]
This is content B
...

In the above example, it means section1 will show below the field label, while section2 will show above the field label

Then we can set the configuration option to conditionally show the sections based on the value of other fields. (remember to add location: all as below)

  - field: 21631754
    fieldType: description
    fieldOptions:
        location: all
        showParts:
            above_section2: [21224422, '==', 'no']
            below_section1: 
                - [21224423, '==', 'val1'],[21224424, '==', 'val2']
                - [21224425, '==', 'val3']

The condition has four items which must be configured. These are in order:

• The custom field ID for the field you are comparing a value to
• The comparison operator
• The value to compare against
• The section of the description to show

The valid comparisons are:

• “==” which means the value equals
• “!=” which means the value does not equal

Strawberry fields can use the description field as a tool tip. This is only available in the form locations of helpcenter and feedbackwidget.

  - field: 22171890
    fieldType: description
    fieldOptions:
        location: tooltip
        tooltip:
            "img-src": "https://cm.cloudmetro.com/tooltip.gif"
            "background": "#000"
            "border": "1px solid green"

The configuration above sets the custom field with id 22171890 to have the description used as a tool tip. The tool tip can then have options:

• img-src = The path to an image file you want to use as the icon for the tool tip
• background = The background colour for the tool tip
• border = The border colour for the tool tip

These options should be all provided.

Extra: if we don't want to show the field and the field label (i.e. only want to show description only). We can add "hideLabel: true" to the fieldOptions

 

2.4.6 Range

Locations: agent, helpcenter, feedbackwidget

Strawberry fields can have a range field type which is based on either numeric or decimal fields. The range field type can be used in all form locations.

  - field: 22171890
    fieldType: range
    fieldOptions:
        min: 0
        max: 10
        step: 1
        widget: slider

The field options for this are:

• min = The lowest value
• max = The highest value
• step = What values to have as valid. This will be discussed below
• widget = The widget to be used. Values can be either “slider” or “buttons”

The step allows you to define how many numbers you jump between each setting. As an example:

• Min = 0, Max = 10, Step = 2 results in: 0, 2, 4, 6, 8, 10 as valid values
• Min = 0, Max = 0.5, Step = 0.1 results in: 0.1, 0.2, 0.3, 0.4, 0.5 as valid values
• Min = 1, Max = 1001, Step = 200 results in: 1, 201, 401, 601, 801, 1001 as valid values

2.4.7 Convert drop-down to buttons

Locations: agent, helpcenter, feedbackwidget

Strawberry fields allows you to convert a drop-down to buttons.

  - field: 22171890
    fieldType: buttons 

This will present the drop-down as a set of buttons.

2.4.8 Multi-select

Locations: agent

The multi-select will convert one or more checkbox fields into a single widget. The most basic configuration is as follows:

  - field: 29854798
    fieldType: multi_select 

To specify which checkboxes will be included in the widget, you include their IDs in the `field` option. When selecting more than one field, you must surround the group with square brackets and separate them with commas:

  - field: [29854798,29949908,29949918]
    fieldType: multi_select

Using fieldOptions, you can control many more aspects over how the checkboxes are presented. Below is a sample configuration:

  - field: [24267373, 24267383, 24310826, 24310816]
    fieldType: multi_select
    fieldOptions:
        label: Request for Information checklist
        order: alpha
        maxHeight: 150px
        24267373:
            label: 1. Collect relevant information from requestor
        24267383:
            label: 2. Get approval from Office of RFI
        24310816:
            label: 3. Print off report and email to requestor
        24310826:
            label: 4. Close file

• label - This will allow you to set an overall label for the group. This is displayed before the checkboxes.
• order - You can specify the order that the checkboxes are displayed. Currently the only option is alpha for alphabetical.
• maxHeight - You customize the maximum height of the widget. By default it’ll be maximum 150 pixels tall. To have no maximum height, set this value to 0.
• By using the field ID in fieldOptions, you can specify options for individual checkboxes.
• label - This allows you to override the checkbox’s label

2.4.9 Filtering

Each config can also have some filters on it, to indicate that the config should only run in certain conditions.

At the moment the supported conditions are: ticket form (ticket forms are only available on Zendesk Enterprise), form location and user role.

We can apply all filters or only some. e.g. a field config with all filters applied are as below:

  - field: 123456
    ticketForm: [1234, 3223]
    formLocation: agent
    withRole: ‘end-user’

ticketForm: in the above examples the field configuration would be valid for ticket forms with id of 1234 and 3223.

formLocation: the configuration would only apply to ticket forms in the agent location. The valid option for the formLocation setting are:

• agent = New Zendesk agent view, sometime referred to as “Lotus”.
• helpcenter = The new Help Center
• feedbackwidget = The custom feedback widget which Lovestock & Leaf have created

withRole: the configuration would only apply to users with a certain role. The role can either be one of the built-in roles, or it could be a number (representing a custom role, for those on Enterprise subscription levels only). The built-in roles are: end-user, admin and agent

2.5 Configuring Strawberry Fields to work in Help Center

If you have been provided with a CloudMetro username and password, please fill it in Lovely. (Please contact us if you don’t have or not sure about this)

Lovely will then have another “Strawberry Fields” in the list, under Help Center Apps section. This is where we can configure Strawberry Fields for the Help Center.

Open that configuration screen, at the bottom there is a hash number, copy this number out.

Then modify your Zendesk Help Center theme and put the following codes in the theme Header. Remember to replace XXXXXXXXXXXXXXXX by the hash number found.

 

<!--[if lt IE 9]> <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.0.3/es5-shim.min.js"></script> <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.0.3/es5-sham.min.js"></script> <![endif]--> <script type="text/javascript" src="//cdn.cloudmetro.com/app-framework.js" data-lnl-hash="XXXXXXXXXXXXXXXXXXXXXXXXXX"></script>

 

Once done, save and publish your Zendesk theme. Strawberry Fields should now also be running on the Help Center ticket form (end user ticket form).