Fields Director FREE - How to use

Settings & configuration

Use this section to understand app settings and app configuration. Settings grouped according by app features.

• Settings & Configuration
  • TICKET: Required Fields (Optional)
    • TICKET: Fields Reference
  • TICKET: Hide / Disable / Show / Enable Fields (Optional)
    • TICKET: Fields Reference
    • TICKET: Field Value Reference
      • Assignee Field
      • Status Field
      • Type Field
      • Priority Field
      • Ticket Form
      • Ticket Sharing
      • Custom Fields
  • Error Message When Required Fields Are Missing Values (Optional)
  • Optional Delay in Milliseconds (Optional)
• Use Cases
  • Require User Information for New Tickets
  • Private Comment Only for New Starters
  • Unwanted Values in System Type Field
  • Ticket Fields That Controlled by a Macro
  • Show Time Tracking Fields on a Ticket

TICKET: Required fields (optional)

Required fields feature allows listing ticket fields that should have any value at every ticket submission. Fields validation happen when Agent press Submit button. If any of visible required fields are missing value the ticket submission will be interrupted, Agent will be informed about ticket fields missing value in form of pop-up.

• Required fields feature only available on ticket screen (new and existing ticket)
• Only currently visible fields will be validated
• Required fields listed in the app will not have any visual signs. If required fields need to have an asterisk in field label use field setting to rename the field accordingly
• Attachments, Macros, Post Save Action are not supported by Required fields feature

TICKET: Fields reference

Use the following ticket fields reference in App setting page to configure required fields. Although, other field references may work, the app was only tested with the following references.

• requester  - validates the presence any a value in system Requester field. Requester without email address or phone number will be considered as valid. Values like requester.email , requester.id  will not be accepted.
• assignee  - validates the presence of Group or Agent in Assignee field.
• assignee.user  - validates the presence of Agent in Assignee field. Tickets assigned to a group will fail validation.
• assignee.group  - validates the presence of Group in Assignee field. Tickets not assigned to any group will fail validation.
• type  - validates the presence any a value in system Type field.
• priority  - validates the presence any a value in system Priority field.
• tags  - validates the presence of any value in system Tags field.
• collaborator  - validates the presence of any value in system CCs field. Value like collaborators  (plural) will not be accepted.
• brand  - validates the presence of any value in system Brand field. (This field will always have a value)
• form  - validates the presence of any value in system Ticket Form field. (This field will always have a value) (This field only available on Enterprise Zendesk plans and higher)
• subject  - validates the presence of any value in system Subject field. Ticket Subject 'mandatory' status can be changed in field settings.
• comment  - validates the presence of any value in system Comment field. Spaces, line breaks, attached files will be ignored. Inline images will pass the validation. Comment field known as 'Description' and always required by Zendesk.
• internalNote  - validates the fact of using Internal Note mode for ticket comment.
• publicReply  - validates the fact of using Public Comment mode for ticket comment.
• organization  - validates the presence of any value in system Ticket Organization field.
• sharedWith  - validates the presence of any value in system Sharing field. This field is only visible when Ticket Sharing agreement is established with other Zendesk accounts. If Zendesk account has no Ticket Sharing agreements validation of this field will be ignored.
• due_date  - validates the presence of any value in system Due Date field. This field will only be visible when System Field Type is set to Task. In all other cases this field will be ignored.
• problem  - validates the presence of any value in system Linked problem field. This field will only be visible when System Field Type is set to Incident. In all other cases this field will be ignored. Value like problem_id  will not be accepted.
• custom_field_{TICKET FIELD ID}  - validates the presence of any value in custom ticket fields of the following types: drop-down, text, date, number, decimal, regular expression, checkbox and multi line. Example of value: custom_field_1122334455 . Where 1122334455  is Zendesk field ID

TICKET: hide / disable / show / enable fields (optional)

This app feature allows to hide / disable / show / enable fields and field values on new and existing ticket screen.

• TICKET: hide fields (optional) feature allows hiding pre-configured ticket fields and/or ticket field values. This feature is designed to hide unwanted ticket fields from the Agents. For example, some system fields or fields that intended to be used internally or by someone else.
• TICKET: disable fields (optional) feature allows disabling (making visible, but read-only) pre-configured ticket fields and/or ticket field values. This feature is designed to make fields visible, but not editable for Agents. For example, allow Agent to see Internal Status, but without ability to change it manually.
• TICKET: show fields (optional) feature allows showing pre-configured ticket fields and/or ticket field values. This feature is designed to show fields hidden by other apps. If using this feature make sure Optional delay is increased so this app will run after other apps have finished their actions.
• TICKET: enable field (optional) feature allows enabling (making editable) pre-configured ticket fields and/or ticket field values. This feature is designed to enable fields which were disabled by other apps. If using this feature make sure Optional delay is increased so this app will run after other apps have finished their actions.

All these functions utilising the same Zendesk Apps framework (ZAF) API. Hence the same fields reference structure cam be applied to all of them.

TICKET: Fields reference

Use ticket fields reference below to hide / disable / show / enable ticket fields.

Subject, Description, Attachments, Macros, Apps tray, Post Save Action can not be hidden.

At the moment of publishing this app the tests with Credit Card field type revealed that ticket fields of this type can not be disabled. This may be fixed by Zendesk later.

• requester  - Ticket Requester
• assignee  - Ticket Assignee
• collaborator  - Ticket CCs
• sharedWith  - Ticket Sharing field (This field is only visible when Ticket Sharing agreement is established with other Zendesk accounts)
• tags  - Ticket tags field
• priority  - Ticket Priority field
• ticket_form_id  - Ticket Form field (This field only available on Enterprise Zendesk plans and higher)
• due_date  - Ticket Due Date field (This field only available When Ticket Type is set to Task)
• problem  - Ticket Linked problem field (This field only available When Ticket Type is set to Incident)
• type  - Ticket Type field
• brand  - Ticket Brand field
• status  - Ticket Submit button
• custom_field_{TICKET FIELD ID}  - Custom ticket fields of the following types: drop-down, text, date, number, decimal, regular expression, checkbox and multi line. Value example: custom_field_1122334455 . Where 1122334455  is Zendesk field ID

TICKET: Field value reference

There are two possible ways to refer to a field value:

1. By value identifier. For example, status.optionValues:new  will only refer to the record in status  field which has value new .
2. By value zero based index. For example, status.optionValues.0  will only refer to the very first value in status  field. On new ticket screen the very first record in status  field is 'new', so "Submit as New" option will be referred. On existing and assigned tickets, the very first record in status  field is 'open', so "Submit as Open" option will be referred.

Note the difference in syntax:

1. {FIELD IDENTIFIER}.optionValues:{VALUE}  - optionValues-colon-value
2. {FIELD IDENTIFIER}.optionValues.{INDEX}  - optionValues-dot-index

Drop-down fields mat have optional default values. If default value will be hidden the field will default to "-".

If using{FIELD IDENTIFIER}.optionValues.{INDEX}  to hide all options under expandable drop-down option (e.g. drop-down titles that using "::" separator) the parent level option will still be visible, but not selectable. To hide the parent level including all sub-levels use custom_field_{TICKET FIELD ID}.optionGroups.0  to refer such records by index.

Assignee field

Assignee field is listing Groups and Agents where ticket can be assigned to.

• assignee.optionValues:{GROUP ID}  - Group in Ticket Assignee field. This only refer to assignable Group option. {GROUP ID} is referring to Zendesk Group ID which can be seen in the URL when opened a group. If hiding the Group name will be visible in Assignee field when first clicked, but it will be impossible to assign ticket to the group as this option will be hidden. Value example: assignee.optionValues:111222
• assignee.optionValues:{GROUP ID}:{AGENT ID}  - Agent in specific Group in Ticket Assignee field. {GROUP ID} is referring to Zendesk Group ID which can be seen in the URL when opened a group. {AGENT ID} is referring to Zendesk Agent user ID which can be seen in the URL when user profile is opened. For fully hiding Agent from Assignee field it requires listing all combinations of {GROUP ID}:{AGENT ID} in app configuration. Value example: assignee.optionValues:111222:333444

Index based reference is possible assignee.optionValues.{GROUP ZERO BASED INDEX}

Status field

Status field is Submit button in Zendesk Agent UI

• status.optionValues:new  - Status New from Submit button
• status.optionValues:open  - Status Open from Submit button
• status.optionValues:pending  - Status Pending from Submit button
• status.optionValues:hold  - Status Hold from Submit button
• status.optionValues:solved  - Status Solved from Submit button

Index based reference is possible status.optionValues.0

Status Closed is not presented in Submit button. Hence can not be referred.

Hiding all available options for status will keep Submit button visible and active, but none of the status will be displayed. The text of Submit button will also be hidden.

Type field

System field Type with possible values: Questions, Incidents, Problems, or Tasks

• type.optionValues:ticket  - Type "-". Used as default/empty value.
• type.optionValues:question  - Type "Question"
• type.optionValues:incident  - Type "Incident"
• type.optionValues:problem  - Type "Problem"
• type.optionValues:task  - Type "Task"

Index based reference is possible type.optionValues.0

Priority field

System field Priority with 2 possible set of values configurable in field settings: "Low, Normal, High, or Urgent" or "Normal or High".

• priority.optionValues:-  - Priority "-". Used as default/empty value.
• priority.optionValues:low  - Priority "low".
• priority.optionValues:normal  - Priority "normal".
• priority.optionValues:high  - Priority "high".
• priority.optionValues:urgent  - Priority "urgent".

Index based reference is possible priority.optionValues.0

Ticket form

Ticket Form is Zendesk feature available on Enterprise and above Zendesk plans. Ticket Forms referred by form id. Which can be seen as a number in URL on Ticket Form configuration page.

• ticket_form_id.optionValues:{FORM ID}  - Where {FORM ID} is numeric Ticket Form ID. Value example: ticket_form_id.optionValues:11223344

Index based reference is possible ticket_form_id.optionValues.0

Attempt to hide default Ticket Form will result in the following behaviour. When new ticket screen is opened the default form will be visible in Ticket Form selector. As soon the ticket form has changed the default value will disappear from the form selector.

Ticket Sharing

Sharing is system ticket drop-down listing available sharing agreement with other Zendesk instances. This field is only visible when Zendesk account has at least one active accepted ticket sharing agreement. Ticket sharing records referred by sharing agreement id. Which can be found in the link for agreement 'view' or via API.

• sharedWith.optionValues:{SHARING AGREEMENT ID}  - Where {SHARING AGREEMENT ID}  is numeric Ticket Sharing Agreement ID. Value example: sharedWith.optionValues:11223344

Index based reference is possible sharedWith.optionValues.0

For referring to the very first value in Sharing field (e.g. "-") use index based reference: sharedWith.optionValues.0

Custom fields

Any custom ticket field which has options. At this moment only ticket Drop-down list (tagger) was tested with the following reference.

Custom fields referred by Zendesk field ID. Which can be found in ticket field settings page.

Custom field value is the tag associated with the value. Tags and values can be found in ticket field settings page.

• custom_field_{TICKET FIELD ID}.optionValues:{VALUE}  - Where {TICKET FIELD ID} is numeric Zendesk ticket field ID and {VALUE} is the actual tag associated with this value. Value example: custom_field_1122334455.optionValues:rma_return

Index based reference is possible custom_field_{TICKET FIELD ID}.optionValues.0

For referring to the very first value in custom drop-down (e.g. "-") use index based reference: custom_field_{TICKET FIELD ID}.optionValues.0

Error message when required fields are missing values (optional)

Error message is the text displayed when ticket submission is interrupted due to required fields missing values. Default value is The following fields/settings are marked as required for submitting this ticket:.

If error messaged is not provided the app will default to localised version of the message.

If error message is provided the app will use this message.

Optional delay in milliseconds (optional)

Optional delay is intended to solve possible conflicts between several installations of this app or between this and other apps that handling fields. Optional delay will pause execution of the code for N milliseconds allowing other apps to complete their actions first. For example, if optional delay will be set to 1000 it will delay the code execution for 1 second.

Optional delay field is expecting numeric value from 0 to infinity. Value example: 2000  Where 2000 stays for 2000 milliseconds or 2 seconds delay. Default value is 0. Means nothing will delay the code execution.

Optional delay is recommended to be set to 1000 when used together with show or enable features of this app.

Optional delay is not applied to Required ticket fields feature.

Use cases

These are some app use cases overview.

Require user information for new tickets

When creating a ticket Agent should always provide client ID into appropriate ticket text field.

To make this happening add ticket field ID custom_field_{TICKET FIELD ID}  into TICKET: Required fields (optional) setting of the app and make sure app runs for desired Agent category.

• TICKET: Required fields (optional) = custom_field_{TICKET FIELD ID}

Private comment only for new starters

Often newly started agents are not allowed to communicate with customers from day one. New agents are welcomed to pick (or get assigned to them) some tickets where they allowed to leave private comments only. So more experienced colleagues can review those comments. To make sure new starters never send public reply by accident the app can be configured in the following way:

Unwanted values in System Type field

System Type field can only have these 4 values Questions, Incidents, Problems, or Tasks. Some values may not be relevant to the business and should never be used. For example, "Incidents" and "Problems" are 2 unwanted values which should be hidden.

• TICKET: hide fields (optional) = type.optionValues:incident,type.optionValues:problem

Ticket fields that controlled by a macro

Some business would like to have "Internal status" drop-down to be set only by a macro and never manually. To make this field visible and editable only by business rules the app can be configured as follows.

• TICKET: disable fields (optional) = custom_field_{TICKET FIELD ID OF "Internal status" drop-down}

Show time tracking fields on a ticket

If you use Time Tracking app and would like to show to your Admins 2 hidden ticket fields that this app silently use on every ticket consider the following configuration:

• TICKET: show fields (optional) = custom_field_{TICKET FIELD ID OF 1ST TIME TRACKING FIELD},custom_field_{TICKET FIELD ID OF 2ND TIME TRACKING FIELD}
• Optional delay in milliseconds (optional) = 800
• On App screen open "General Settings" tab. Where under role "Role restrictions" section select "Administrator" and save settings.