Use interface methods

Interface-methods is a mechanism that the developer platform provides, to enable your app to trigger certain actions on the Freshservice UI.

Using interface methods an app can, on the Freshservice UI,

  • Display certain UI elements such as Modals, Confirmation boxes, and Notifications.
  • Mimic click actions - such as starting or stopping a timer or navigating to specific pages.
  • Show/Hide certain fields, field values, and elements (such as icons or other relevant information).
  • Enable/Disable certain buttons.
  • Set the values of certain fields.

Global interfaces

An app can display these interfaces/UI elements on any of the Freshservice pages where the app is deployed.

Display modals

  1. From your project’s root, navigate to the app directory and create a <modal or any-reasonable-name>.html file. In this file, enter the code to render the (front-end of the) Modal.

  2. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.

  3. After app initialization, to display a Modal, use the following method:

    Sample app.js
    client.interface.trigger("showModal", {
      title: "<Modal name>",
      template: "<path to the modal.html file>"
    })

showModal method

The method displays a Modal in an IFrame. Events methods and Interface methods are not supported in a Modal - your app cannot react to click, change, or update events that occur inside a Modal and your app cannot trigger actions on the product UI from the Modal.

Installation parameters, Request method, Data method, and Data storage are supported in modals. If your app uses these methods from modals, in the modal.html file (or in any other equivalent file that you have added), ensure to include the following appclient resource.

<script src="{{{appclient}}}"></script>
Modal dialog boxModal dialog box

Use the sample code shown on the right pane, to enable your app to display a Modal, as part of the app logic.

You can retrieve the contextual information pertaining to the parent location from where a modal is triggered by using Instance method - Context. You can use the Instance methods - Send and Receive to enable communication between modals and any other app instance.

Display confirmation messages

To enable your app to display standard confirmation-message boxes,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, to display a confirmation message with default buttons, use the following method:
Sample app.js
 client.interface.trigger("showConfirm", {
   title: "<Confirmation box name>",
   message: "<text message to be displayed seeking confirmation>"
 })

showConfirm method

The method displays a confirmation message box with a title, a message, and the save and cancel buttons. By default, the message box displays the SAVE and CANCEL buttons. You can customize the button names.

Time-out information:Timeout for Confirmation message box is 10 seconds.

Use the sample code shown on the right pane > Default buttons tab, to enable your app to display a Confirmation message box (with SAVE and CANCEL buttons), as part of the app logic.

Confirmation message box - Default buttonsConfirmation message box - Default buttons

Display notifications

To enable your app to display notifications,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.

  2. After app initialization, to display a notification, use the following method:

    Sample app.js
     client.interface.trigger("showNotify", {
       type:<Possible values: info, success, warning, error>,
       title: "<Display name>",
       message: "<text message to be displayed in the notification box>"
     }
    )

showNotify method

The method displays a notification box with a title and notification message (can be an info message, a success message, a cautionary note, an error message which, if ignored, can fail the system).

Use the sample code shown on the right pane, to enable your app to display various notification messages, as part of the app logic.

Info notificationNotification box with an info message

Ticket details page - possible app actions

Hide/display or enable/disable UI elements

To enable your app to hide an UI element, display a hidden element, disable an element, or enable an element,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, to a hide/display or enable/disable UI element, use the following method:
    client.interface.trigger("<method-name>", {
      id: "<element-name>"
    })
    <method-name> is the action to be performed. Possible values: hideElement, showElement, enableElement, disableElement
    <element-name> is the element to be hidden or displayed; disabled or enabled.

Enable/disable editor window element

To enable your app to disable an element or enable an element, on the reply or forward editor,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, to a enable/disable an editor window element, use the following method:
    client.interface.trigger("<method-name>", {
      id: "<window-name>",
      field: "<element-name>"
    })
    <method-name> is the action to be performed. Possible values: enableElement, disableElement
    <window-name> is the action to be performed. Possible values: reply, forward
    <element-name> is the element to be disabled or enabled. Possible value: from

Set the value of a field

To enable your app to set the value of a UI field,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, use the following method:
    client.interface.trigger("setValue", {
      id: "<element-name>",
      value: "<value to be set>"
    })
    <element-name> is the element whose value is to be set.

Set the value of an editor-window field

To enable your app to set the value of an element, on the reply or forward editor,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.

  2. After app initialization, use the following method:

    client.interface.trigger("setValue", {
      id: "<window-name>",
      field: "<element-name>",
      value: "<value to be set>"
    })

    <window-name> is the editor window name. Possible values: reply, forward

    <element-name> is the element (on the reply or forward window) on which the app acts. Possible value: from

Mimic click actions

A button click on the product UI, performs an action. For example, button clicks can start a timer, toggle a timer, expand a collapsed item, open a window, and update field values. Your app can mimic certain button clicks and perform the subsequent actions. To enable your app to do this,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, to mimic a click action, use the following method:
    client.interface.trigger("click", {
      id: "<action to be performed>"
    })
    Note: If <action to be performed> is updateProperties, all values of the Properties widget’s fields are obtained as the result of the action.
  3. To start a timer, use the following method:
    client.interface.trigger("start", {
      id: "timer",
      value: {<payload needed for the timer action, specified as an
          object of key:value pairs}})
  4. To toggle (if started stop or if stopped start) a timer, use the following method:
    client.interface.trigger("toggle", {
      id: "timer"
    })

On which UI elements can this method work?

On Ticket Details page:

On the Ticket details page > Properties widget: Update button: Submit updated ticket properties

UI elements that the app can act on

attachments

Use the sample code on the right pane, to hide attachments or display already hidden attachments.

This image highlights the element the app can act onThis image highlights the element the app can act on

ticketDelete

Use the sample code on the right pane, to hide or display the Delete menu-option from the menu shown in the following image.

This image highlights the element the app can act onThis image highlights the element the app can act on

dueDateEdit

The product UI has an edit icon that enables editing the Resolution due date associated with a ticket. The icon is highlighted in the following image. Use the sample code on the right pane, to enable your app to hide or display this link.

This image highlights the element the app can act onThis image highlights the element the app can act on

note

Use the sample code on the right pane, to hide/display the Add Note button in the bottom toolbar of the Ticket window and the Add Note drop-down option that is available on clicking the Reply button.

This image highlights the element the app can act onThis image highlights the element the app can act on

timer

An agent working on a ticket can choose to record the time spent on the ticket. The agent can use the timer available on the product UI, to do this. Your app can mimic the agent’s actions, and start or toggle a timer.

Use the sample code on the right pane, to enable your app to start or stop a timer.

This image highlights the element the app can act onThis image highlights the element the app can act on

expandConversations

In a ticket thread, if there are more than three messages, they are in collapsed format. Use the sample code on the right pane, to enable your app to expand the collapsed items and let an agent view the entire conversation.

Open the reply editor window with a text insert

Use the sample code on the right pane, to enable your app to mimic a click action on the Reply button and open the reply editor window with a text inserted in the window.

Note:If the ticket.replyClick event method is used in app.js, this interface method triggers the event method and invokes the associated callback.

This image highlights the Reply button that opens the reply editorThis image highlights the Reply button that opens the reply editor

Open the note editor window with a text insert

Use the sample code on the right pane, to enable your app to open the note editor window with a text inserted in the window.

Note:If the ticket.notesClick event method is used in app.js, this interface method triggers the event method and invokes the associated callback.

This image highlights the Add Note button that opens the note editorThis image highlights the Add Note button that opens the note editor

Open the add task window with a text insert

Use the sample code on the right pane, to enable your app to open the Add task window with a text inserted in the Note section of the window.

This image shows the Add Text window with a text insertThis image shows the Add task window with a text insert

Properties widget fields

The product UI displays all ticket properties in the Properties widget of the Ticket details page. The Properties widget is highlighted in the image.

This image highlights the Properties widgetThis image highlights the Properties widget

An app can act on the following elements (fields) of the Properties widget.

Field (default display) nameElement name to be used in app.js
Statusstatus
Prioritypriority
Sourcesource
Impactimpact
Urgencyurgency
Typetype
Agentagent
Departmentdepartment
Categorycategory
Groupgroup
Custom Fieldcustomfield name

Use the sample code on the right pane, with the appropriate element name, to hide, display, disable, or enable these fields.

setValue: Your app can set a value for a Properties widget field. Use the sample code on the right pane with the appropriate element name, to set a field’s value.

Submit updated ticket properties

You can use the sample code on the right pane to enable your app to mimic a click on the Properties widget > Update button. The values of the properties, at the time of the click, are sent to the app.

This image highlights the Properties widgetThis image highlights the Update button. Your app can mimic the act of clicking this.

Add note window

When an agent adds a note to a ticket, the Add note editor is displayed. The app can act on the following element of this window.

Use the sample code on the right pane to set the note type. If the note type is private, the Visible to the customer toggle is set to NO.

This image highlights the note type optionsThis image highlights the note type options

Editor window fields

When an agent replies to or forwards a ticket, the Reply or Forward editor is displayed. The app can act on the following element of the Editor window.

Field (default display) nameElement name to be used in app.js
Fromfrom
This image highlights the Editor window elements that the app can act onThis image highlights the Editor window elements that the app can act on

Use the sample code on the right pane, with the appropriate <window-name> to disable or enable the from field.

setValue: Your app can set a value for the Reply or Forward editor’s From field. Use the sample code on the right pane with the appropriate window name, to set the field’s value.

Change details page - possible app actions

Hide/display UI elements

To enable your app to hide an UI element or display a hidden element,

  1. Navigate to the app.js file. Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application (the product on which the app is deployed) passes a client reference to the app.
  2. After app initialization, to a hide/display a UI element, use the following method:
    client.interface.trigger("<method-name>", {
      id: "<element-name>"
    })
    <method-name> is the action to be performed.
    Possible values: hideElement, showElement
    <element-name> is the element to be hidden or displayed. Important:To hide/display status, priority, and impact as one unit, enter <element-name> as defaultFields.

UI elements that the app can act on

CHANGE PROPERTIES widget

Any org level service changes can be managed through the Freshservice - Change management. The Change details page captures all information pertaining to a change. The product UI displays all change properties in the CHANGE PROPERTIES widget of the Change details page. The CHANGE PROPERTIES widget is highlighted in the image.

This image highlights the CHANGE PROPERTIES widgetThis image highlights the CHANGE PROPERTIES widgets

An app can act on the following elements (fields) of the CHANGE PROPERTIES widget.

Field (default display) nameElement name to be used in app.js
Statusstatus
Prioritypriority
Impactimpact
Riskrisk
Typetype
Agentagent
Departmentdepartment
Categorycategory
Groupgroup
Planned Start DateplannedStartDate
Planned End DateplannedEndDate
custom fieldcustomfield

Use the sample code on the right pane, with the appropriate element name, to hide or display these fields.

setValue: Your app can set a value for a CHANGE PROPERTIES widget field. Use the sample code on the right pane with the appropriate element name, to set a field’s value.

Change view - Planning section

On the Change details page > Change view (that is, the main viewport), the Planning section contains the change roll-out plan. The Planning section is highlighted in the image.

Use the sample code on the right pane, to hide/display or enable/disable (all) Planning section fields

New ticket page - possible app actions

UI elements that the app can act on

The New incident page displays all ticket properties that are necessary for ticket creation.

This image highlights the elements that  the app can act onThis image highlights the elements that the app can act on

An app can act on the following elements (fields) of the New Incident page.

Field (default display) nameElement name to be used in app.js
Statusstatus
Prioritypriority
Impactimpact
Urgencyurgency
Agentagent
Departmentdepartment
Categorycategory
Groupgroup
Custom fieldcustomfield

Use the sample code on the right pane, with the appropriate element name, to hide, display, disable, or enable these fields.

setValue: Your app can set a value for a New Incident page field. Use the sample code on the right pane with the appropriate element name, to set a field’s value.

New change page - possible app actions

UI elements that the app can act on

The Create a New Change page displays all change properties that are necessary for a change creation.

This image highlights the elements that  the app can act onThis image highlights the elements that the app can act on

An app can act on the following elements (fields) of the Create a New Change page.

Field (default display) nameElement name to be used in app.js
Change Typetype
Statusstatus
Prioritypriority
Impactimpact
Riskrisk
Groupgroup
Agentagent
Departmentdepartment
Categorycategory
Planned Start DateplannedStartDate
Planned End DateplannedEndDate
Planning (section)planningFields
Custom fieldcustomfield

Use the sample code on the right pane, with the appropriate element name, to hide, display, disable, or enable these fields.

setValue: Your app can set a value for a Create a New Change page field. Use the sample code on the right pane with the appropriate element name, to set a field’s value.