Fork » User guide – Support Centre - Lovestock & Leaf

1 Overview

Fork is a workflow management tool which helps agents manage tickets and work flow processes through sub-tickets. The sub-tickets are displayed in the Fork app in the Zendesk apps panel on the ticket page.

A brief description of the Fork app is available here.

Fork consists of 2 sides:

1. Fork Agent: where Fork runs on existing ticket or new ticket allowing agents to view/create or link sub tickets.
2. Automatic Fork: (optional) where Fork automatically creates subticket without the need of agent action.

2 Installing Fork

Fork can be installed using a license key through our foxycart installer (docs).

Once Fork is installed, there are 2 apps: Fork and Lovely. Lovely is an extra handy app to configure Fork (as well as all other Lovestock&Leaf apps)

2.1 Configuring Lovely

There should be a grey cloud icon on agent task bar (left handside of agent interface), click on it to open Lovely. Inside Lovely, there is a list of all Lovestock & Leaf apps that we can configure. (and hence Lovely and Fork are also in the list)

To configure Lovely, select "Lovely" from the list, fill in the CloudMetro username & password we have provided you (Please contact us if you have not received them - do not use auto-prefill settings.)

If Lovely is setup with correct username and password, the 2nd Fork app should appear under CLOUD METRO APPS (new name: HELP CENTER APPS) section:

To configure Fork Agent, select Fork under AGENT APPS section
To configure Automatic Fork, select Fork under HELP CENTER APPS section

2.2 Fork Requirements

A. Fork Agent Requirements

From Lovely, select Fork under AGENT APPS section then click on Requirements button to install Fork Agent requirements

Set Username to the CloudMetro username we have provided to you as in section 2.1 above
Set Password to the CloudMetro password we have provided to you as in section 2.1 above
Click 'Install' (only once) and wait for it to complete

Once done, Fork settings will be automatically filled in and this is now completed. Fork Agent side is ready to use for all agents.

B. Automatic Fork requirements (optional)

If Automatic Fork is required (i.e. automatic create subticket without the need of agent action), we also need to select Fork under HELP CENTER APPS to configure it:

Zendesk Domain = your own Zendesk domain
Zendesk Username = your own Zendesk username
Zendesk Password or Token = your own Zendesk password or API token
Data Field ID = the same Data Field Id seen in the 'Fork' configuration
List of fields not to inherit = Optional. [field_id_1, field_id_2, etc]
Fork Config = your config

Set the Configuration Format to YAML (by clicking on the YAML button on top menu of the app) then enter your config as follows:
```
my_fork:
  title: Fork1 triggered
  subTickets:
    - subject: "Fork A"
    - subject: "Fork B"
```
Click 'Update'

For more extensive information on the Fork Config see "Configuring Fork".

Test Run: we can now refresh zendesk and give it a test! Open a new ticket tab, add 'my_fork' as a tag and save the new ticket. After approx. 10 seconds two sub tickets should have been automatically created!

3 Configuring Fork

3.1 Fork Agent Configuration

Fork Agent should work straight away without any further configuration.

The below info is only for when there is some advanced use case required / more details on what we can configure for Fork Agent side:

This section applies to the 'on-the-fly' sub-ticket feature of Fork, which is available via the agent side app that can be located in the Apps panel when viewing a ticket.

Data Field ID = The ID of the LL_Fork_Data field where Fork stores its data, autofilled by Lovely
Default Tags = Optional
Copy only the fields listed below = Optional
Fields to copy or exclude = Optional
Do not open app tray automatically = Optional

The Default Tags are the tags to add to the subticket it is created or linked on the fly. There are current 2 options newTicket and existingTicket available:

newTicket: [tag_1, tag_2]
existingTicket: [tag_2, tag_3]

parentNewTicket: [tag_5, tag_6]
parentExistingTicket: [tag_7, tag_8]

These settings will result in the following:

When we creates a "New ticket"/"New ticket (copy fields) in Fork, "tag_1" and "tag_2" tags will be added to the being created ticket.
When we link an "Existing ticket" to the current ticket, "tag_2" and "tag_3" will be added to the target ticket.
The parent ticket that has newly subticket added, will have tag_5 and tag_6 (only available in Fork version 2.1.20 onward)
The parent ticket that has another ticket added to it as subticket, will have tag_7 and tag_8 (only available in Fork version 2.1.20 onward)

We recommend that at least a 'sub_ticket' tag is added to sub-tickets as clients in time often want to exclude sub-ticket in reporting, triggers or views.

Fields to copy or exclude will control which fields are copied (or excluded from copying) when you add a "New ticket (copy fields)".

The list of fields is a comma separated list. A field can be the ID of the ticket field or a system field. The possible options you have are:

12345 = the ID of the custom ticket field
requester = the requester of the parent ticket
assignee = the assignee of the parent ticket
group = the group of the parent ticket
collaborators = the CCs of the parent ticket
priority = the priority of the parent ticket
sharedWith = the external sharing of the parent ticket
status = the status of the parent ticket
tags = the tags of the parent ticket
type = the type of the parent ticket
subject = the subject of the parent ticket (version 2.1.4 and later only)
description = the original description of the parent ticket
brand = the brand of the parent ticket (version 2.1.4 and later only)
problem_id = the linked problem ticket of the parent ticket (if the parent ticket is an Incident ticket)
due_date = the due date of the parent ticket (if the parent ticket is a Task ticket)

For example:

12345, assignee, tags

The Fork data field (usually called "LL_Data_Fork") is never copied to the child ticket.

3.2 Automatic Fork Configuration

The following example applies to the configuration for auto sub-ticket creation, which is the configuration in the HELP CENTER APPS section. The examples are in YAML format, which is the recommended format.

In YAML the configuration nesting levels are defined with spaces and new lines, so a new set of sub-tickets is always started off with the corresponding tag positioned at col1 of a new line in the config. Further nested settings for each level 1 tag are then each added on a new line, preceded with a set number of spaces (in multiples of 2 or 4, for example) for each nested level.

It is important to ensure that all nested levels settings of the same type are preceded with the exact same multiple of spaces, otherwise your configuration file will be invalid. (An easy way to ensure this is to copy and paste the pre-loaded example for each tag, and edit that section.)

my_fork:
  title: My own Fork
  subTickets:
    - subject: Provide new coat hanger

    - subject: Provide a new coat
      shortSubject: New coat
      type: incident
      status: open
      requester: 1234567
      assignee: 5678123
      comment: This is the config comment.
      copyExistingComments: true
      inheritParentValues: true
      inheritParentTags: true
      dynamicAssigneePrefix: fork_assignee_
      dynamicRequesterPrefix: fork_requester_
      tags: [john_coat]

In the example above, having a "my_fork" tag on a ticket will result in the creation of 2 sub tickets. The first sub-ticket will only have subject set to "Provide a new coat hanger". The seconds sub-ticket is far more elaborate. It will:

Have subject set to "Provide a new coat".
shortSubject is used by the Fork agent side app when displaying the sub-tickets. This is used in place of the actual ticket subject, and can be used when the actual subject is too long to fit into the Fork app display.
type will set the ticket type to this value. Defaults to nothing.
priority will set the ticket type to this value. Defaults to nothing. (note: when this is set to "inherit" or option inheritParentValues is true, priority will be set to same as parent ticket)
status will set the ticket status to this value. By default this is "new" if the sub-ticket is not assigned to an agent, in which case Zendesk will automatically make the status "open".
requester will be set to this user. Defaults to the person creating the sub-ticket.
group will be set to this group. Defaults to nobody. Note that the assignee has to be in the group specified.
assignee will be set to this user. Defaults to nobody. Note that the assignee has to be in the group specified.
comment is the comment of the new ticket. Defaults to to the description (the first comment) of the parent ticket.
copyExistingComments will copy all comments from the parent ticket to the child ticket. Defaults to false.
copyExistingPublicComments will copy only public comments from the parent ticket to the child ticket. Defaults to false.
copyExistingPrivateComments will copy only private comments from the parent ticket to the child ticket. Defaults to false.
copyExistingRequesterComments will copy only comments made by the requester from the parent ticket to the child ticket. Defaults to false.
copyExistingAssigneeComments will copy only comments made by the assignee from the parent ticket to the child ticket. Defaults to false.
inheritParentValues If this is set to true, Fork will copy the ticket fields from the parent ticket to the sub-ticket. Defaults to true.
inheritParentTags If this is set to true, Fork will copy the tags from the parent ticket to the sub-ticket. Defaults to false.
inheritParentCCs If this is set to true, Fork will include the same CCs as the parent ticket. Defaults to false.
inheritRequester This is a true/false setting where true means that the requester will be set to the same requester as the parent ticket. The default is false.
inheritAssignee This is a true/false setting where true means that the assignee will be set to the same assignee as the parent ticket. The default is false.
inheritGroup This is a true/false setting where true means that the group will be set to the same group as the parent ticket. The default is false.
internalNote This is a true/false setting where true means that the subticket description will be private. Default to false.
dynamicAssigneePrefix The prefix for the drop-down used to set the user ID for the assignee of the child ticket.
dynamicRequesterPrefix The prefix for the drop-down used to set the user ID for the requester of the child ticket.
submitter either "requester" or "assignee" to indicate who is the author of the first comment in the subticket. Default to "requester".
ticketForm The ID of the ticket form to use when you create the sub-ticket.
tags This is an array of tags to add to the sub-ticket in addition to the inherited values. Note that you can add tags associated with dropdown field options here in order for those dropdown options to be selected on the sub-ticket.

IDs of people and groups can easily be seen with the "ID Viewer" of Lovely.

3.2.1 Text replacements

For the Automatic Fork configuration, Fork can replace text in the subject or description to make it more appropriate or personalised. For example:

my_fork:
  title: My own Fork
  subTickets:
    - subject: "{{parentSubject}} - for {{dynamicAssignee}}"

(e.g. if the parent ticket subject was "Testing Testing" and the child ticket’s assignee was "Harry Helpdesk" then the subject on the child ticket would be: "Testing Testing - for Harry Helpdesk".)

The following tokens can be used in subject:

{{parentId}} = This will replace the token with the ticket ID of the parent ticket
{{parentSubject}} = This will replace the token with the subject from the parent ticket
{{parentRequester}} = This will replace the token with the full name of the requester of the parent ticket
{{parentRequesterFirstName}} = This will replace the token with the first name of the requester of the parent ticket
{{dynamicRequester}} = This will replace the token with the name of the requester based on the requester of the child ticket.
{{dynamicAssignee}} = This will replace the token with the name of the assignee based on the assignee of the ticket.

The following tokens can be used in comment:

{{parentId}} = This will replace the token with the ticket ID of the parent ticket
{{parentSubject}} = This will replace the token with the subject from the parent ticket
{{parentDescription}} = This will replace the token with the description from the parent ticket
{{parentRequester}} = This will replace the token with the full name of the requester of the parent ticket
{{parentRequesterFirstName}} = This will replace the token with the first name of the requester of the parent ticket

3.2.2 Assignee and Requester for sub tickets

A sub-ticket can have a static requester using the "requester" sub-ticket option, or a dynamic requester based on the value of the tag using the "dynamicRequesterPrefix" value. If, for example, and agent should be able to choose a 3rd party that the sub-ticket should be created for (e.g. a service provider) by selecting a dropdown option value for e.g. "Service Provider", Fork will add the relevant requester to the sub-ticket.

Firstly a drop-down custom field needs to be set up in Zendesk which will be used for requesters. (In this case "Service Provider".) The field can be called whatever you like, and the tag values for each of the options must start with the same prefix.

Custom field options and tags:

Sam Support : support_1234567
Harry Helpdesk : support_5678123

Fork config:

my_fork:
  title: My own Fork
  subTickets:
    - subject: Fork1 ticket A
      requester: 1231234
      dynamicRequesterPrefix: support_

Fork will search for a tag which starts with "support_", and will then set the Zendesk user with user ID 1234567 as the requester if Sam Support (support_1234567) was found. If a support_ tag is not present, it will use the static requester, being "1231234".

The same concept applies to the dynamic assignee.

4 Using the Fork Zendesk app

The Fork Zendesk app appears in the ticket sidebar apps tray. Fork works in two ways - you can add sub-tickets "on the fly", or it can add sub tickets based on tags on a ticket (which are usually based on drop-down custom ticket fields).

4.1 On the fly sub-tickets

For a new ticket, the app will appear, but you will not be given any options. For an existing ticket you will see the following screen.

When you click on the "add" button you will be given three options.

4.1.1 Add new ticket

If you click on the "New ticket" option, Fork will open up a new ticket, and pre-populate the subject of the new ticket. You are free to change the subject and add a description. Once you are finished you should save the new ticket. The new ticket will be saved as a sub-ticket of the parent ticket.

4.1.2 Add new ticket and copy fields

Similar to "Add new ticket" but it will pre-populate the subject and ticket fields on your new ticket.

There are settings in the app which allow you to define which fields are copied when you create a new sub ticket. The options are explained in the Fork configuration section.

One limitation is that if there are ticket forms, and the parent ticket is not the default ticket form, then you will see a notice in the app to ask you to change to the same form as the parent.

4.1.3 Add existing ticket

If you click on the "Existing ticket" option, a modal screen is shown. This allows you to select another existing ticket and link it as a sub-ticket of the existing ticket.

You cannot add an existing solved ticket as a sub-ticket. If you attempt this, you will be notified that the ticket is solved and cannot be added as a sub ticket.

4.2 Automatic sub-tickets

The other way that you can create sub-tickets is based on tags of the ticket.

This can be achieved through either of two ways:

Manually add a tag to a ticket
Set a ticket field, which (after ticket save) will create a tag on the ticket (automatically done by Zendesk).

A specifically configured trigger will notify the Fork service on CloudMetro that sub-tickets are required. The CloudMetro service then creates the sub-tickets based on configuration settings. See the configuration section on how to configure the Fork app.

This process adds new tickets as sub-tickets of the existing parent ticket.

4.3 Unlinking tickets

On the parent ticket, there is an "X" to the right of each of the sub-tickets. This allows you to unlink and existing ticket. When you click on the "X" it will pop up a confirmation.

Clicking on "Unlink ticket" will unlink the sub-ticket. You then need to save the "parent" ticket to complete the unlinking.

5 Appendix

5.1 Data Field

The Data Field should have been created and automatically linked to Fork.

The Data Field is a custom multi-line text field where the Fork data is saved. The ID of the field is shown in the top right corner of the screen when editing that specific field.

"Data field ID" refers to the ID of that custom field.

If this field doesn't exist, please create a new custom multi-line text field and make a note of the ID of this field.

5.2 Target

To enable the communication between Zendesk and CloudMetro for auto sub-ticket creation based on tags, Fork uses a target.

The following settings should be configured:

Title = CloudMetro Fork
Url = https://single-instance.cloudmetro.com/boxcar/fork.php?ticket_id={{ticket.id}}
Method = POST
Attribute Name is deprecated by Zendesk and not used. You can set it to anything.
Username = Username provided by us (please contact us)
Password = Password provided by us (please contact us)

5.3 Trigger

A trigger is an action which happens when a ticket is saved.

Trigger title = Create or update sub tickets with Fork
Meet all condition = Ticket: Update via is not Web service (API)
Perform these actions = Notifications: Notify target CloudMetro Fork
Message = {{ticket.id}}

New = yellow
Open = red
Pending = blue
On-hold = black
Solved = grey

As per the above example, the Fork trigger runs when the ticket was NOT updated via the API. This is the default condition added when Fork is installed, and is set so that Fork does not create loops of sub-tickets (sub-ticket of sub-ticket of sub-ticket etc).

If you have tickets that are created by API (via an external system, or another app), and you would like Fork to auto create sub-tickets for those, you would need to add a tag to all your sub-tickets (see above for configuration examples), and then modify this Fork trigger to exclude tickets where that tag was found, instead of excluding tickets that were created via the API.

What is your request regarding?

Support Centre

Contents