Settings allow Deskpro admins to configure your app during installation. You can describe settings in the manifest.json file in the root of your app package, and Deskpro uses this to build a settings form in the apps admin section. This is useful for configuring things like API keys or arbitrary options of your app.

Setting Properties

Each setting has the following properties, where the key of each setting is it's name.

• title - friendly name of the setting, used in the apps admin section of Deskpro (required)

• description - brief description, shown below the setting field in apps admin (optional)

• type - the type of setting, current available options are string

• isRequired - is this setting required for the app to be installed or updated (rewuired)

• validationPattern - an optional regular expression that describes a valid value

• isBackendOnly - is this setting backend only, i.e. is it only used via the apps proxy

• default - value to use as a default when first installing the app (pre-fills app settings form)

Adding and using a simple setting

In this example we're going to add a setting that holds a website URL. Let's start by adding the setting to our manifest:

# /manifest.json

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "settings": {
    "website_url": {
      "title": "Company Homepage URL",
      "description": "The URL of our company homepage",
      "type": "string",
      "isRequired": true,
      "isBackendOnly": false,
      "default": "https://example.com/"
    }
  }
}
 copy

This manifest configuration will build a settings form like this in the apps admin section of Deskpro:

Ok, now that we've defined our setting, we can then use it in our app. Settings are passed along with app events, so we'll need to listen to one of those to get access to it. In this case we're going to listen to the READY event, which gives us access to the setting as soon as the app is loaded.

import { useState } from "react";
import { 
  useDeskproAppEvents, 
  Context,
} from "@deskpro/app-sdk";

export const MyComponent = () => {
  const [url, setUrl] = useState(null);

  useDeskproAppEvents({
    onReady(context: Context) {
      setUrl(context.settings.website_url);
    },
  });

  return (
    <>
      {url && Our Company Homepage}
    
  );
};
 copy

Adding and using a backend only setting

Backend only settings are settings that cannot be accessed from your app (using the method in the previous example), instead they're used by the apps proxy to replace values in outgoing requests. This is so we can securly transmit parameters like API keys. In the next example we'll add a backend only setting to store an API key, then use it in an outbound request from the app.

Ok, so let's add the api_key setting to our manifest, notice that the isBackendOnly is set to "true" and we have a proxy entry configured for our API enpoint URL:

# /manifest.json

{
  "name": "my_app",
  "title": "My App",
  "description": "Brief description of my app",
  "version": "1.0.0",
  "scope": "agent",
  "isSingleInstall": true,
  "targets": [{
    "target": "ticket_sidebar",
    "entrypoint": "index.html"
    }
  }],
  "settings": {
    "api_key": {
      "title": "API Key",
      "description": "Our API key",
      "type": "string",
      "isRequired": true,
      "isBackendOnly": true
    }
  },
  "proxy": {
    "whitelist": [{
      "url": "https://example.com/api/.*",
      "methods": ["GET"],
      "timeout": 10
    }]
  }
}
 copy

Our app code is a little different this time as we cannot "see" backend only setting by listening to app events and extracting them from the context, as we did before. Instead, backend only settings are passed as "placeholders" that are then used by the app proxy.

import { useEffect, useState } from "react";
import {
  useDeskproAppClient,
  proxyFetch,
  Fetch,
} from "@deskpro/app-sdk";

export const MyComponent = () => {
  const [users, setUsers] = useState([]);
  const { client } = useDeskproAppClient();

  useEffect(() => {
    // Is the Deskpro app client initialised?
    if (!client) {
      return;
    }

    // First, we need to get a special version of fetch() that is authorised to use the apps proxy
    proxyFetch(client).then((fetch: Fetch) => {

      // Perform GET request against the API, replacing __api_key__ with the associated setting value
      fetch("https://example.com/api/users?key=__api_key__").then((res: Response) => {

        // Get data from the API and set state
        res.json().then((data) => {
          setUsers(data);
        });

      });

    });

  }, [client]);

  return (
    <>
      {users.map((user: string, idx: number) => (
        
{user}
      ))}
    
  );
};
 copy

The important part of this example is the use of a placeholder that represents the value of a backend only setting, api_key. All setting placeholders are wrapped in double underscore delimiters, "__", so the placeholder for this particular setting is "__api_key__".

Settings placeholders may be used in the following parts of a fetch() request:

• URL

• Headers (both single and multiple values)

• Request Body

Running the app as a setting

Sometimes it's necessary to actually run the app in order to successfully install or update it. For example, you may want to validate API credentails by actually using them to ping the third party service. Or you need to implement an authorization flow, like OAuth. For this we provide two special settings types; app_embedded and app_modal -- both of which wrap a simple "string" field, and can be used to set it.

Using app_embedded as a setting type will embed an iframe containg your app within the settings form itself.

    "sample_field": {
      "title": "My Sample Field",
      "type": "app_embedded",
      "options": {
        "entrypoint": "index.html?abc=123"
      },
      "isRequired": true,
      "isBackendOnly": true
    },
 copy

Using app_modal as a setting type will embed a button to open a modal containing your app iframe, with the setting title being the label of the button.

    "sample_field": {
      "title": "My Sample Field",
      "type": "app_modal",
      "options": {
        "entrypoint": "index.html?abc=123"
      },
      "isRequired": true,
      "isBackendOnly": true
    },
 copy

When the app is run in either of these contexts we provide some new methods that you can run from the Deskpro client (within your app), these are:

useInitializedDeskproAppClient((client) => {

  // Set the value of the setting field to "hello world"
  client.setAdminSetting("hello world");

 // This will invalidate the setting field, setting the validation message to "Setting is invalid"
 client.setAdminSettingInvalid("Setting is invalid");

});
 copy