Support
Submit a request

Support Centre

Automatic Fork » User guide

Updated:

Follow
Contents
  1. 1 Overview
  2. 2 Installing Lovely and Automatic Fork
    1. 2.1 Configuring Lovely
    2. 2.2 Setup Automatic Fork
    3. 2.3 Test Run
  3. 3 Configuring Fork
    1. 3.1 Text replacements
    2. 3.2 Assignee and Requester for sub tickets
    3. 3.3 Run with ALL or ANY tag conditions
  4. 4 Appendix
    1. 4.1 Data Field
    2. 4.2 Target
    3. 4.3 Trigger

1 Overview

Fork is a workflow management tool which helps agents manage tickets and workflow processes through sub-tickets.  The sub-tickets are displayed in the Escalator app in the apps panel on the ticket page. (The Lovely Views app will soon be also displaying the sub-tickets).

Fork automatically creates sub-tickets based on a specific tag being added to a ticket. Every time a ticket is created or updated, Fork is called into action to check whether the tag exists in the ticket, and if so, it creates the required sub-tickets, and then links them to the original ticket.  

The tags that trigger Fork, can be added to the ticket in many ways. It can be the result of a customer filling out a support form and selecting an option in a drop-down field or checking a checkbox field. It can be an agent adding the tag directly to a ticket, or selecting from a drop-down or checking a checkbox. It can also be added by a trigger or automation.

 

2 Installing Lovely and Automatic Fork

Lovely is an app to configure all Lovestock & Leaf's apps, including Automatic Fork.

To get started, you will need to have Lovely installed on your Zendesk, by going to our foxycart installer (docs) and fill in the following license key:

LOVELY

then follow the guide on the screen to enter your Zendesk details.

Lovely will be installed to your Zendesk upon completion.

2.1 Configuring Lovely

Once Lovely is installed, there should be a grey cloud icon on the left agent task bar, click on it to open Lovely.

  • Inside Lovely, there is a list of all Lovestock & Leaf apps (and hence Lovely is also in the list)
  • Please select "Lovely" itself from the list and fill in the Lovely username & password we provided you (do not fill in other username and password).
    Contact us     if you have not received your Lovely username and password.

 

2.2 Setup Automatic Fork

If Lovely is entered with correct Lovely username and password, Automatic Fork should appear under HELP CENTER APPS in Lovely and is ready to configure:

  • Open Automatic Fork in Lovely
  • On Automatic Fork configuration screen, please click on button Requirements -> Install . It may ask for your Lovely username and password, please enter them again.

Once done, set your Automatic Fork configuration to have your Zendesk domain, username and password/API token as below:

 

 

  • Zendesk Domain = your Zendesk domain (e.g. something.zendesk.com)
  • Zendesk Username = your Zendesk email address (or email address of an admin on your Zendesk who has ability to create tickets - subtickets will be created under this user permission)

    e.g. admin123@something.com if you are using password
    or admin123@something.com/token is you are using API token
  • Zendesk Password or Token = your Zendesk password or API token.
    (API token is highly recommended, however please remember to put /token at the end of your email address as above if you are using API token)
  • Data Field ID = the same Data Field Id used by Escalator app (should be automatically filled otherwise please enter it manually - you can use ID Viewers button near the Requirements button to find out all ticket field IDs)
  • List of fields not to inherit = Optional and can leave blank
  • Fork Config = your Automated Subtickets config, please prefer to section 2.3 and section 3 below for more details.

 

2.3 Test Run

  • Put the following config to the Fork Config section: 
    my_fork:
  title: Fork1 triggered
  subTickets:
    - subject: "Fork A"
    - subject: "Fork B"
  • Click 'Update' to save current Automatic Fork setting.
  • Create a new ticket with tag my_fork, 2 subtickets should be automatically created for it.


(How it works: when ticket is created or updated, 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 your above settings. This process adds new tickets as sub-tickets of the existing parent ticket.)

3 Configure Automatic Fork

At section 2.3 Test run above, we have entered some basic config (in YAML) to create subtickets when a tag appears on the parent ticket.

YAML config is defined with spaces and new lines, so it is important to ensure that all configs/options are indented with correct spacing to indicating the levels they are on.

For example, this is incorrect config, because the indentation of 2 subtickets are NOT the same:
(i.e. they are not vertically aligned by the look of it)

my_fork:
  title: Fork1 triggered
  subTickets:
         - subject: "Fork A"
    - subject: "Fork B"


Triggering Tag/Field Selection:

In the above example, we can change the triggering tag my_fork, to any tag, or any dropdown field option value (so that if the field is set to that option, automated subtickets are created)

e.g.

delivery_apple:
  title: Delivery Apple
  subTickets:
    - subject: "A new delivery is scheduled"

order_water_melon:
  title: Water Melon Order
  subTickets:
    - subject: "Water Melon - New invoice required"
    - subject: "Water Melon - New delivery required"


Automated subtickets per tag and options of each subticket:

In Automatic Fork configuration, each automated subticket is indicated by using a dash "-" in front.

We can add more options for each subticket as below:
(again, notice how the options are vertical aligned with other options, not with the dash "-". The dash is vertical aligned with other dash to indicate other subticket):

my_fork:
  title: My own Fork
  subTickets:
    - subject: "Fork A"
      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]
      custom_ticket_fields:
          21037428: "this is a test subticket"
          21378927: [optiontag1, optiontag2]
          25522127: optiontag
          

    - subject: "Fork B"

In the example above, having a "my_fork" tag on a ticket will result in the creation of 2 sub tickets.

The 2nd sub-ticket will only have subject set to "Fork B".

The 1st sub-ticket is far more elaborate with alot of options

Subticket options
Full options list is as below:

  • subject will set the subject of the automated subticket. This is required.
  • type will set the ticket type to this value (task, problem, incident, question). 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. This needs to be User ID of an user on your Zendesk. Defaults to the person creating the sub-ticket.
  • group will be set to this group. This needs to be Group ID of a group on your Zendesk. Defaults to nobody. Note that the assignee has to be in the group specified.
  • assignee will be set to this user. This needs to be User ID of an agent on your Zendesk. Defaults to nobody. Note that the assignee has to be in the group specified.
    Note: IDs of people and groups can easily be seen with the "ID Viewers" button on the Automatic Fork config screen.
  • 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.
  • custom_ticket_fields To set the ticket field values of the subticket, by specifying the list of field ids and their corresponding values.
    Note:
    • with dropdown fields: must be option tag of one of the option (or "" for empty)
      e.g. if an option is labeled "Test Option" with tag test_option, then your config must use test_option, instead of "Test Option"
    • with multi-option dropdown fields: must be a list of options tags
      e.g. 123456: [optiontag_1, optiontag_2, optiontag_3]
    • with checkbox fields: true is for checked, false is for unchecked.
      If false does not work on your Zendesk (rarely happens), please try null- this is because sometimes Zendesk is inconsistent in the way the checkbox gets set

 

3.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 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.

3.3 Run with ALL or ANY tag conditions

Sometimes we may want to create subtickets only when:

  • ticket has ALL of the specific tags
  • ticket has ANY of the specific tags

To do so, use all or any option as below:

my_fork1:
  title: My own Fork
  any: [tag1, tag2]
  subTickets:
    - subject: "Fork A"
      
my_fork2:
  title: My own Fork
  all: [tag1, tag2, tag3, tag4, tag5]
  subTickets:
    - subject: "Fork B"

With the above example code:

  • subticket Fork A will be created if the parent ticket has either tag1 or tag2
  • subticket Fork B will be created if the parent ticket has all 5 tags: tag1, tag2, tag3, tag4 and tag5

Note: When using all or any option, the main key (e.g. my_fork1, my_fork2...) will be ignored and will not be considered as tag to test on ticket.

4 Appendix

4.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.

4.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)

4.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.

Have more questions? Submit a request

Comments