Bring Your Own Integration (BYOI): Custom Apps and Custom API Actions Setup

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
• Save your work
• Final thoughts

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 Manage > 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

These options allow secure access to third-party services.

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!

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.

Saving Your Work

You can save your progress at any point, so you don’t have to finish everything at once!

Final Thoughts

Double-check that everything is set up correctly before you publish. Once it’s live, your API action is good to go for integration into your custom apps or other features in the intranet, but you cannot make any changes to the API!