Your First App

The goal of this tutorial is to help you understand the basics of app development. Here, you will build an app using the Freshworks platform.

For this tutorial, choose the your_first_app template. This app will be visible on the Ticket Details page and will display the Freshservice logo along with the name of the ticket requester as shown below.


Create

Note:
Before proceeding, ensure that you have installed Node.js and the Freshworks CLI.

To get started, open the terminal window, navigate to the directory under which you want to create your app, and type the following command. Note that this directory must be empty. $ fdk create --products freshservice --template your_first_app The app is created with the following directories and files.

Code Walkthrough

Let’s take a closer look at the files that were created in the app.

README.md

Developers need to maintain a proper README file so when there is a change in ownership of the code base, a new developer can easily understand the various nuances of the code.

manifest.json

The manifest file is used to store configuration information for the app.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
{ "platform-version": "2.0", "product": { "freshservice": { "location": { "ticket_sidebar": { "url": "template.html", "icon": "icon.svg" } } } } }
EXPAND ↓

The platform-version key is automatically generated and used to infer the platform version that your app uses. This will be used to ensure backward compatibility when a new version of the framework is released.

The productkey is used to specify the product and location in which the app is rendered. This app is to be rendered in the ticket_sidebar location in the Ticket Details page. url and icon specify the path (from the /app directory) to the template and icon files rendered in that location.

You can view the complete list of where apps can be rendered in the App Locations section.

app/icon.svg

This is the app icon specified in the manifest file. It is displayed at the right-hand side of the Ticket Details page. The app icon file is of SVG type with a resolution of 64 x 64 pixels.

app/freshservice_logo.png

This is the Freshservice logo displayed by the app.

app/template.html

Apps in the new Freshservice UI are rendered inside an IFrame. This file contains the HTML markup for the app. It is a simple template that displays an image along with text which is dynamically generated in the app.js file.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
<html> <head> <script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.0/jquery.min.js"></script> <script src="app.js"></script> <link rel="stylesheet" type="text/css" href="https://static.freshdev.io/fdk/2.0/assets/freshservice.css"> <link rel="stylesheet" type="text/css" href="style.css"> </head> <body> <div class="logo"></div> <p id="apptext"></p> </body> </html>
EXPAND ↓

The template.html file includes the following:

  • fresh_client.js - This JS library enables the app to communicate with the parent page. The file is mandatory as the app runs in an IFrame and needs to communicate with the parent page in order to access data, listen to events, and trigger interface actions.
  • jquery - This is used by app.js in line 9 where it adds text to the #apptext element.
  • app.js - Establishes connection with the parent page to retrieve information about the ticket requester.
  • freshservice.css - Importing this css file ensures that the app maintains a UI that is consistent with the parent page. Anytime the parent page is redesigned, we update this stylesheet so that the app remains consistent.
  • style.css - App specific stylesheet that contains style information for various UI components of the app.

app/app.js

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$(document).ready( function() { app.initialized() .then(function(_client) { var client = _client; client.events.on("app.activated", function() { client.data.get("requester") .then(function(data) { $("#apptext").text("Ticket created by " + data.requester.name); }) .catch(function(e) { console.log("Exception - ", e); }); }); }); });
EXPAND ↓

To enable the app to refresh itself at the right time, the ticket page triggers an app.activated() event. Apps in the ticket_sidebar location are initially in a minimized state. When the agent expands the app for the first time on the page, the app receives the app.activated() event. If the agent navigates to another ticket and then expands the app (for the first time on that page), the app.activated() event is triggered again.

When the ticket page is loaded for the first time, the app.js file registers for the app.initialized() event. In the callback, it receives a client object and registers for the app.activated() event. The core logic of the app, which is to retrieve the ticket requester’s name and append it to a string, is contained in this callback.

As apps are rendered in an IFrame, the app and underlying page communicate through APIs by using the client object. The client.data.get('requester') method uses a Data API to retrieve the ticket requester details and parses it to get the requester’s name.

app/style.scss

The app specific stylesheet which contains style information for various UI components of the app. For this app, the file contains style information for the Freshservice logo which is part of the app as well as the div block that contains the image and accompanying text.

Copied Copy
1
2
3
4
5
6
7
.logo { background: url("freshservice_logo.png"); background-repeat: no-repeat; background-size: contain; height: 25px; margin-top: 25px; }
Next Steps

Now that you understand the basic components of an app, why not build your own?

If you run into any issues, you can reach out to us at support@Freshservice.com or via the chat icon at the bottom-right corner of the screen.

Log in with your Freshservice account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.