Lovely » User guide

 

1 Overview & Installation

Lovely is a Zendesk app to configure all Lovestock & Leaf Zendesk apps.This app does not do anything on its own, but agents with the administrator role can use it to configure other applications.

Download the zip file here lovely-2.0.21.zip and upload it as a private app on your Zendesk (see Uploading and installing a private app)

 

2 Using the Lovely app

The Lovely app is found in the left-hand side navigation bar (the bottom icon). This should only be available to agents with the “Administrator” role.

When you click on the icon you are taken to the following screen.

On the left hand side there are two sections. The top section contains a link to information about Lovestock & Leaf, and our Zendesk apps.

The second section is a list of all the Lovestock & Leaf apps which is installed on your Zendesk instance. It shows the icon for the app, the name of the app, and the currently installed version of the app.

There is a refresh link at the top right of the list of apps. If you click on this then it will refresh the list of apps.

In the app list, if an app is greyed out (as Strawberry Fields is above) then it means that this app is currently disabled.

When you click on one of these entries you will see the following screen:

This screen is the same as the app configuration screen you see in Zendesk. The main point of difference is that you can edit the app configuration in Yet Another Markup Language (YAML) format rather than JavaScript Object Notation (JSON) format. See the sections “What is YAML?” and “What is JSON?” below for more information about both these formats.

At the top of the screen, below the app name and the version are the following controls:

• Reload settings from
• Configuration format

At the bottom of the screen below the app settings are the following controls:

• Delete app
• Disable app
• Reset form
• Update

These controls are explained in the following sections.

2.1 Reload settings from

This drop-down allows you to re-load the settings from a different source. When you click on the drop-down you can choose the source. The available options are:

• Zendesk
• Cache

The app will always try to load the settings from the Cache in the Lovely app. If the cache is empty, then it will load the settings from Zendesk.

The Cache is used to store the YAML configuration settings (including comments). This helps with editing the settings. When the settings are saved into Zendesk (which is what happens when you click on “Update”), extra information and formatting of the YAML setting is lost as it is stored in JSON within Zendesk.

Normally you will not need to worry about using this control.

In the near future Lovestock & Leaf will be rolling out their new Lovely infrastructure which will work closely with the Lovely app. For those customers on a support plan with Lovestock & Leaf you will be able to restore previous versions of configurations.

2.2 Configuration format

The configuration for the apps can be in three different formats. The formats are only checked for the multi-line text setting fields. These formats are:

• RAW = There are no checks made and the settings are saved exactly as they are entered.
• JSON = The app checks to make sure that the setting is valid JSON and will give you an error when it is not valid. It will not allow you to save the setting until the error has been fixed. When the setting is saved it will remain in JSON format.
• YAML = The app checks to make sure the setting is valid YAML and will give you an error if it is not valid YAML. When the setting is saved it is converted to JSON format.

2.3 Delete app

When you click on this it will prompt you to make sure you really want to delete the app.

You must click on “OK” for the app to be deleted.

2.4 Disable app / Enable app

When you click on the “Disable app” link you get a prompt asking if you would really like to disable the app.

You must click on “OK” for the app to be disabled.

When you click on the “Enable app” link you get a prompt asking if you would really like to enable the app.

You must click on “OK” for the app to be enabled.

2.5 Reset form

When you click on the “Reset form” link it will reset the form back to the current settings. This is effectively changing the form back to what is currently set for the app.

2.6 Update

When you click on the “Update” button this will check to make sure that you have provided settings for mandatory fields, and that the fields are correct before it allows the settings to be saved.

If you have a field which is mandatory, but you have not provided a value you will see an error like the following:

If you have a setting which is either JSON or YAML and the format is not correct then you will see an error like the following. The first is a YAML error, and the second is a JSON error.

Once you have successfully updated your settings you will need to refresh your browser so that the apps can pick up the new settings.

3 What is YAML?

YAML is an acronym for “Yet Another Markup Language” and is a simple and easy to read and write way of setting configuration settings. You can read more about YAML at the following resources:

http://www.yaml.org/spec/1.2/spec.html

http://en.wikipedia.org/wiki/YAML

Both of these resources are very dry. We’ve found that the Wikipedia article gives you a good background about YAML with good examples, and the official specifications link gives you all the possibilities for how you can use YAML.

If you do not have the Lovely app installed, or you prefer to configure your apps in JSON, then you would need to convert YAML settings to JSON. There is an online YAML to JSON converter which will convert the YAML configuration to JSON:

http://yaml-online-parser.appspot.com

Probably the most important thing with the YAML settings is that the indentation needs to be uniform. YAML will accept either 2 spaces or 4 spaces indentation. You are free to choose how many spaces you want to use, but you need to be consistent. You cannot mix 2 space indentation and 4 space indentation in the same configuration setting.

4 What is JSON?

JSON is an acronym for “JavaScript Object Notation” and is a fairly simple way to store configuration settings. It is not as easy for humans to read this format over the YAML format above. You can read more about JSON at the following resources:

http://www.json.org/

http://en.wikipedia.org/wiki/JSON

Both of these resources are very dry. We’ve found that the Wikipedia article gives you a good background about JSON with good examples, and the official site link gives you all the possibilities for how you can use JSON.

5 (Optional) Configuring the Lovely app to show Help Centre apps

If you have Lovestock & Leaf apps on your Help Centre (for the end-users side, not for agents side), then you will need to configure Lovely itself to show these Help Centre apps. Otherwise, please skip this section.

To do so, go to Zendesk App Settings -> Lovely -> Change Settings:

This screen has the following options:

• Title: This is the name of the app as it appears in the apps list.
• CloudMetro URL: This is your Lovely location. This is not yet being used and can be left default.
• CloudMetro API key (or CloudMetro Username/Password): If you are using Lovestock&Leaf Help Centre apps (for end-users), such as Fork, FIeld Marshal, Strawberry Fields... please enter the API key (or username/password) you have been provided by us.  Otherwise, please live the fields empty.
• Indentation: This is the number of spaces to use in place of a tab for when you are editing configuration files. (Note: this option is no longer available in later version of Lovely)
• Enable role restrictions?: This field is a Zendesk supplied option which allows you to restrict only users in certain roles from using the app. Leaving this setting unticked will mean that the app is available for all agents.

The Lovely app should be set to be only be available to users with the administrator role.