Quick Start

Note:
This documentation is for the v2 development platform which is used to build apps for the new Freshdesk Mint UI. To build apps on the existing UI, use the v1 platform.


In this section, you will learn to build a simple Freshdesk app using the following steps.

Step 1: Install Node

Step 2: Install the CLI

Step 3: Create your First App

Step 4: Test your App

Step 5: Validate and Pack

Install Node

First, you need to install Node.js to use the Freshworks CLI. To install Node.js, click here (only versions 6.10.x are supported). Once installed, you can verify the version by using the following command: $ node –v
v6.10.0

For Windows, you need to install a few required tools and configurations by using the following command: $ npm install --global --production windows-build-tools


Install the CLI

Next, you need to install the Freshworks CLI on your machine to build, test, and publish apps in Freshdesk Marketplace.


Note:
By installing the CLI, you agree to these Terms and Conditions.


 

To install the CLI, run the following command:

  • For Mac/Unix -
  • Copied Copy
    1
    sudo npm install http://dl.freshdev.io/cli/fdk-4.3.8.tgz -g
  • For Windows -
  • Copied Copy
    1
    npm install http://dl.freshdev.io/cli/fdk-4.3.8.tgz -g

The -g command option ensures global installation with which you will be able to run the CLI anywhere in your machine.

Once you install the CLI, you can verify the version by using the following command:

$ fdk version
4.3.8
Create your First App

In this section, you will learn to create a simple app to display the Freshworks logo and name of the ticket requester on the Ticket Details page.

Open the terminal window, navigate to the directory (my_first_app) in which you want to create your app, and run the following command: $ fdk create --template your_first_app

Once create is successful, the app files shown below will appear in the my_first_app directory.

DIRECTORY/FILE DESCRIPTION
app/ This directory contains all the files (HTML, JS, CSS, images, library) required for the front-end component of your app. The JS files must follow the ES5 standard.
app/icon.svg This product icon file in the app directory created as part of the sample project. You can replace it with your own assets while building your app.
Note:The icon file should be of SVG type with a resolution of 64x64 pixels.
app/template.html This file contains the HTML required for the app’s UI which will be rendered in an IFrame.
config/ This directory contains installation parameters and OAuth configuration files.
config/iparams.json This file contains all the parameters which users will have to specify/set when they install the app. For more information on installation parameters and related APIs, see Installation Parameters.
config/iparam_test_data.json This file contains the parameter values which you will specify in order to test the app locally.
manifest.json This file contains details about your app and its characteristics.
README.md This file contains any additional instructions or specifications which developers might want to outline.

For a detailed walkthrough of the app, see Code Walkthrough.

Test your App

To render your app locally and test it from your machine, follow the steps given below.

  1. Open your console, navigate to your project folder, and execute the following command: $ fdk run
  2. Log in to your Freshdesk account (if you do not have a Freshdesk account, sign up here).
  3. Go to the Ticket Details page, and in the Address bar append the URL with ?dev=true. For example, the URL would look like this: https://subdomain.freshdesk.com/helpdesk/tickets/1?dev=true.
    When you test your app locally, you may see a shield icon in the Address bar of the browser. Clicking the icon will display a warning message as the Support portal runs on HTTPS while the server used for local testing runs on HTTP. Click Load unsafe scripts to continue testing.
  4. On the Home page, from the left navigation bar, select Tickets and click any ticket. The rendered app will be displayed on the right side of the page as shown below.
Validate and Pack

To check if the app is error-free and package it for submission, follow the steps below.

  1. Navigate to your project folder and validate the code by using the following command: $ fdk validate [--app-dir DIR] where DIR is the relative or absolute path to the project directory.
  2. Once validation is successful, you can pack the project by running the following command: $ fdk pack [--app-dir DIR] The pack command generates the dist/my_first_app.zip file which you need to upload in the Developer portal to be published in Freshdesk Marketplace. For information on the submission process, see the Types of Apps section in Marketplace Listing.