Table of Contents

Part 1: Integrating Custom Apps

• Overview
• Setup and configuration
• Editing custom apps
• Enabling custom apps
• Troubleshooting

Part 2: API Actions

• Overview
• Creating an API action
• Testing an API action
• Key considerations

• Dynamic parameter binding from another API action

Integrating Custom Apps

Overview

The custom apps feature lets you add external applications to your system by entering key details and settings. This guide explains how to set up, configure, and troubleshoot custom apps. It also includes supported authentication types and connection options. To add a custom app, go to Application settings > Application > Integrations > Custom apps.

Setup and Configuration

Supported Authentication Types

Custom apps support three types of authentication:

• API Token-Based Authentication
• Basic Authentication
• OAuth 2.0 Authentication (including OAuth with PKCE)

These options allow secure access to third-party services. OAuth 2.0 authentication allows more secure access, and now, users can choose between "AuthCode" and "AuthCode with PKCE" via a dropdown.

• AuthCode: Standard OAuth 2.0 flow.
• AuthCode with PKCE: A more secure OAuth 2.0 flow where users can also select between two "Code Challenge Methods":
  • Plain
  • SHA-256

Connection Types

Custom apps offer two connection types:

• App-Level Connection: A central connection for all users; individual users don’t need to connect separately.
• User-Level Connection: Each user must connect to perform operations.

OAuth 2.0 supports both app-level and user-level connections, while API Token and Basic Authentication support only app-level.

Base URL

Users must enter a base URL, which will be used for API actions.

Redirect URL

For OAuth 2.0 connections, note the redirect URL shown for the app; this is needed to set up the OAuth app on the third-party service portal.

Logo Requirements

Each custom cpp needs a logo with the following specifications:

• Size: 210x210 pixels (square shape)
• Max file size: 1 MB

Following these specs ensures proper display on the intranet.

Editing Custom Apps

After setting up a connection (app-level, user-level, or test connection), the authentication type and related settings are locked and cannot be changed. However, other fields like the app’s name and description can still be edited. If the connections are removed, these locked fields can be updated again.

Enabling Custom Apps

New custom apps are disabled by default. To enable a custom app, switch its status on so it can be used in the system.

Troubleshooting

If there are issues during setup, especially with OAuth 2.0 connections that fail due to extra query parameters in the authentication request, add |exclude:display,immediate to the auth URL. This removes unnecessary parameters that might cause conflicts, ensuring a smoother connection.

API Actions 

Overview

API actions let you run specific tasks in other applications by setting up API connections in our system. Each action is linked to a custom app, so it uses that app's login details when it runs.

How to Create an API Action

Creating an API action involves three simple steps:

1. Details
2. API Setup
3. Preview & Confirm

Note: Once you've created the API action, you can create custom app tiles using the action.

Step 1: Provide Details

• Select Custom App: Pick the custom app you want to link this action to.
• API Action Name: Give your action a clear name so it’s easy to recognize later.

Step 2: Set Up the API

Here’s where you’ll configure how your API action works.

• HTTP Method: Choose how the action will communicate with the app. You can pick from:

  • GET 
  • POST 
  • PUT 
  • PATCH 
  • DELETE 

• Endpoint Setup: This is the web address where your action will connect.

  • Endpoint URL: Start with http:// or https:// then add the domain and path.
  • Path Parameters: You can make parts of the URL flexible by using double braces. For example: https://www.example.com/users/{{userId}}/items/{{itemId}}. Just replace {{userId}} and {{itemId}} with real values when running the action.

• Other Endpoint Tips:

  • Use slashes (/) to separate parts of the URL.
  • Make sure each part is either a fixed piece or a variable, not both.
  • Avoid using the same name for different variables in the URL.

• Parameters: These are extra pieces of information your API action might need.

  • Path Parameters: Define which parts of the URL can change.
  • Query Parameters: Add any extra info that’s needed. You can decide if these are required or optional.
  • Headers: These are like extra notes sent along with the request. Again, you can choose if they are required or optional.

Parameter Details

• Key Label: This is a friendly name for the parameter that helps users know what to fill in.

• Value Type: This tells you what kind of data to expect and how to collect it. Here are some types you can use:

  • Text/Textarea: For general info like names or descriptions.
  • Number: For things like quantities or IDs.
  • Boolean: A simple yes/no option, often as a checkbox.
  • Multi-select Dropdown: Allows picking multiple choices from a list.
  • Single-select Dropdown: Choose one option from a list.
  • Date Picker: A calendar tool to pick dates.

• Default Value: You can set a starting value for inputs to help users get going faster.

Testing Your API Action

Once you’ve set everything up, it’s time to test it out!

• Connect Test Account: Make sure your test account is connected using the app’s login method.
• Configure Parameters: Fill in the required info for your action.
• Run Test: Click Run to see if your action works as expected.

Step 3: Preview and Confirm

• Preview Details: Check all your settings one last time.
• Publish: When you’re ready, publish the API action. Just remember, you can’t change anything once it’s published!

New Enhancements for API Actions

• OAuth with PKCE: When setting up OAuth 2.0, you can now choose between the traditional "AuthCode" flow and the more secure "AuthCode with PKCE" option. For "AuthCode with PKCE", you’ll also have the option to select between Plain and SHA-256 as the "Code Challenge Method."
• Headers for Token URL: You can now define additional headers for the Token URL, which are only required for OAuth 2.0 setups. A checkbox "Add Headers for Token URL" is available, which will prompt a text area where you can enter key-value pairs for the headers.

Note: Authorization and Token URLs allow query parameters to be included directly in the URL. Headers are only required for the Token URL and are displayed in a separate section for clarity.

Key Considerations

• Mandatory Parameters: Make sure to fill in all required fields, or the action won’t work.
• Optional Parameters: These can be left out if you don’t have values for them.

Dynamic parameter binding from another API action

We've now made it easier to set up dynamic app tiles by letting you pull values directly from another API. You don’t need to manually enter dropdown options or backend values anymore. With this update, things become smarter, faster, and more accurate.

Let’s break it down into two simple updates:

1. Automatically Fill Dropdown Menus Using Another API

When you add a dropdown in your tile (like a list of countries, users, or tags), you no longer have to type the options yourself. Instead, you can link it to another API that already has this information.

Why is this useful?

• Keeps the list up to date automatically

• Saves time and effort

• Reduces mistakes from manual entry

How to do it?

• When setting up your dropdown, you’ll now see an option:

  • Manually add options

  • Get options from another API

• Choose Get options from another API.

• Select the API you want to pull the data from (for example, an API that lists all users or countries).

• If the selected API needs some values first (like a filter or category), you can either:

  • Enter those values manually

  • Or reuse values already used in the current tile setup

• Run a quick test to check the data.

• Finally, choose which parts of the result will be the label (what users see in the dropdown) and the value (what gets used behind the scenes).

Example

• A tag dropdown can pull names and IDs from a ListTags API.

• A country selector can use a GetCountries API.

• A project owner list can use a ListUsers API.

2. Fill Hidden or Fixed Fields Automatically Using Another API

What’s New?

Some fields in your tile don’t show up for users and can’t be edited—like an ID or user role. These are handled behind the scenes. Now, you can automatically fill these fields using data from another API, instead of hardcoding them.

Why is this useful?

• Keeps system information accurate

• Automates backend setup

• Removes manual steps for the tile author

How to do it?

• When setting up a non-editable field, choose the option:

  • Get value from another API

• Pick the API that has the info you need.

• Provide any inputs it requires (manually or using values already in the tile).

• Run a test to see the result.

• Select the correct value from the response to fill your field.

Example

• Automatically fill organizationId using a GetCurrentOrg API

• Fill customerTier using a GetCustomerProfile API

• Fill userId using a GetCurrentUserByEmail API

Benefits

These new features help you:

• Save time by avoiding manual setup

• Ensure your dropdowns and hidden values are always accurate

• Create smarter tiles that update based on live data