1 Overview & Download
Latest version can be downloaded here: lovely-2.0.13.zip
The Lovely Zendesk App is the one-stop shop for configuring Lovestock & Leaf Zendesk applications. As new applications are developed the features of the app will expand. This app does not do anything on its own, but agents with the administrator role can use it to configure other applications.
This guide was written based on version 1.0.0 of the Lovely 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:
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
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:
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.
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:
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:
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?
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 Configuring the Lovely app
You can set the configuration options for app through the application settings. It should be noted you can set the configuration settings for Lovely from within the Lovely app if you wanted to. You can access this by clicking on “Admin” (the cog icon).
Next, click on the “Manage” item in the “Apps” section of Zendesk admin.
Once you are in this section you click on the cog icon for the app and click on “Change Settings” to edit the settings.
This will take you to the following screen.
This screen has the following options:
- Title: This is the name of the app as it appears in the apps list.
- Lovely URL: This is your Lovely location. This is not yet being used and can be blank.
- Lovely API key: This is the API key you will have been provided with. This is not yet being used and can be left
- Indentation: This is the number of spaces to use in place of a tab for when you are editing configuration files.
- 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.