In the Freshworks Marketplace, some of the common use cases and third-party integration apps are available. But, most businesses cannot only run with these apps. They would need some customised integration and workflow customisation to work in their own process. With this, I introduce you to Custom apps. There's no difference in building a custom app and a Marketplace app for Freshworks.

Custom apps are private to a particular account and gets published and installed only in the same account. Marketplace apps are published by a developer and can be used by any Freshworks customers can install this app from the Marketplace.

Usually, the custom apps are solved to address a problem in hand rather than exploring the problem. So, let's skip the planning exercise and jump to requirements gather exercise.

Requirements gathering

Starting the development with the complete requirement reduces the need for changes in the design during the development that could lead to inefficiency or drag the timeline further.

Collect the complete requirements from the customer or business analysts beforehand. Get the gaps clarified with the domain experts and add definition in your own words.

If still there are assumptions and word "depends" in the require, clearly capture them.

If some cases are clearly unachievable, capture the alternatives.

Get the expected the usage pattern and traffic for the app. Get the expected growth in the traffic for the app in the next few years (recommended - at least 2 years).

Design and UI/UX considerations

Setting up the local development environment

Node.js and Node Version Manager (NVM)

Node.js is the runtime required to run the Freshworks CLI that helps develop, test, and publish the Freshworks app.

NVM enables you to install multiple node versions. Freshworks CLI depends on a particular Node.js version and it might vary with your other Node.js projects. Also, NVM helps to easily change from one Node.js version to another which helps upgrades smooth.

Refer to the documentation for installation steps for NVM and Node.js.

Freshworks CLI (FDK)

Freshworks CLI is also called as FDK because it uses the keyword fdk for all of it's commands.

Refer to the documentation for installation steps for the Freshworks CLI.

Freshworks product account

Sign up for a Freshworks developer account.

Freshworks has a suite for products to which the Freshworks apps can be created as custom app. Create a trial account with the product that you wish to build the custom app for. Extend the trial by creating a ticket in the Dev-Assist portal. This step is required when the product trial ends.

Version Control System (optional)

A version control system (VCS) that helps to track different versions of the app. It enables you to keep the app in cloud, publish your development version separately from a completed production version of the app, and to see the difference between them before and after merging them. A version control system is more powerful than what is mentioned above and is a useful tool for app development process.

Git is a widely used vcs these days.

FDK templates

The Freshworks apps can be started development with the boilerplate templates provided by teh Freshworks CLI.

The fdk create command will let you use one of the pre-built templates.

Usually starting an app from scratch with a template is easier. Follow the Quick Start steps from the reference documentation when lost.

Sample apps repository

There are sample applications available showcasing the Freshworks developer platform features and use cases. If partial requirement of the app can be made simple with some of these sample apps, feel free to copy the code from them.

All the sample apps are also in a runnable state. So, they can be tested to see how these features work if needed.

Documentation and code snippets

When referring to the documentation for each platform features, it's easier to copy the relevant code snippets available for them.

Whenever they are required again, it's always easier to copy from them than writing manually which is error-prone that could lead to losing time and braindrain for troubleshooting.

Crayons UI components

We all might agree that we hate to write CSS. It's hard to get the UI of the app right and beautiful.

Freshworks has an open-source UI components library, Crayons. It has a lot of useful styled UI components that can be readily used in the Freshworks apps.

Plus, Crayons follows the Freshworks design system. So, they will match the design of the Freshworks products and align with the product effortlessly and the users won't feel any difference. Since it's an open-source library, you can also share feedback in the public repository and work on them if you want to. Freshworks actively maintains this repository and keeps releasing new updates and addresses the feedback.

FDK run

If you have followed the Quick start steps in the reference documentation, you would have run the application at least once.

If not, we will see here how to run the Freshworks app. Open the terminal or command prompt in the app folder that you have created.

  1. Execute fdk run command, and it will run your app in your local computer.
  2. Open the Freshworks product in your preferred web browser. We recommend to use Google Chrome for local development as all the features will work reliably.
  3. For each app placeholder, the app can be opened in a specific page of the Freshworks product. If we use "your_first_app" template for Freshdesk, the app can be viewed in the Ticket Details page of your Freshdesk account. Open details page for one of the tickets. Append ?dev=true query parameter to the URL after opening the page.
  4. Now, the app should be rendered in the right side-bar in the ticket details page in the collapsed accordion. Open the accordion with the app name and the app content will be visible.

Note: Making changes to the app code would require a page refresh to see the changes. In some cases where there's no configuration and manifest changes, the app would refresh without requiring a page refresh.

Production

In production, the app can be debugged with frontend logs in the browser developer tools and Serverless logs from the Marketplace apps gallery page in the product.

FDK logs and Serverless app logs

The Freshworks CLI stores the debugging logs. They can be checked for any troubleshooting at ./log/app.log file. After the app is deployed to production, the Serverless app logs are available on-demand in the App gallery where the app is installed.

fdk debug mode

If you would want to see verbose debugging logs in the terminal during the development, you can activate the debugging more by running the app with the command, NODE_DEBUG=fdk fdk run. It will print the same logs that are stored in the app log file. Refer to the demo for the usage.

Freshworks Developer Community

When you cannot solve some issues, you may need others' help. We all do. Freshworks Developer Community has a lot of active developers and platform experts to help. Search or post your query to get help.

Code coverage ensures the code that is written is thoroughly tested and is free of bugs. Code coverage is an automated process that tracks the code covered when you test the app manually. The Freshworks CLI measures the percentage of code that has been tested and also provide information on which part of the code has not been tested. This helps to write more comprehensive tests for the app and improve the code coverage percentage.

The code coverage setup for Freshworks apps consists of the following steps:

  1. Running the app with Freshworks CLI
  2. Manually testing the app through Freshworks product in the web browser
  3. Stop and look at the code covered compared to the overall app code
  4. View the coverage files to find which parts of the code are not covered
  5. Achieving minimum of 80% code coverage to submit the app to the Freshworks marketplace

However, the code coverage is not a requirement for the Custom apps. It's a better practice to keep the complete app code covered by testing the app for bug-free app.

Preparing the app for submission

FDK validate

The app source code can be validated if the configurations and the code is syntax error-free by running the command fdk validate. It will show the validation errors and warning with the source code line and the issue can be fixed for an error-free app. Fix the warnings as well to publish a better version of the app.

FDK pack

When the app development completes, the app is ready to be published. To publish, the app has to be validated first with no errors. Pack the app to publish it by running the command, fdk pack. It will generate the app distribution as a zip file.

AMP form checklist

  1. Navigate to the Freshworks app management portal by logging in at developers.freshworks.com with your account domain or from your Freshworks product.
  2. Create a new app and choose "Custom app" as the type of the app.
  3. Upload the app zip file generated in the previous step.

Submitting the app to Freshworks

Mandatory form fields in AMP

Fill the required details to publish the app.

  1. App nameThe app name is unique in your account and it should not have any special characters apart from _ (underscore) and - (hyphen).
  2. support email addressThis is mandatory field to let the customers know who is supporting the app. If the app developer is different from the customer, it would help the customer about the app developer.

Time it takes for the app deployment

The custom apps would take time up to 30 minutes for the deployment. But, it gets deployed within 2 minutes.

Custom app installation

After the app is deployed and available to install, navigate to the Marketplace apps gallery in the product to install.

While installing the app, the configuration will be filled by the admin user.

If the app requires, the admin user has to provide authentication credentials or authenticate via OAuth to the third-party and Freshworks products.

The custom apps can be updated in the same screen when the app is updated again in the App Management Portal.

Also, the app uninstallation available through the same App Gallery.

Summary of key steps

Let's recap what we have shared so far in this tutorial.

  1. Plan and design your custom app
  2. Developer the custom app
  3. Test your app
  4. Prepare for the app submission
  5. Submit and install the app

Resources and further reading

For further learning, use the following materials to reference during your Freshworks app development journey.