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
• Component validations
• 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

Note:

We strongly recommend enlisting an IT resource to help in configuring your own apps. Although the feature is entirely self-service, it involves an understanding of APIs and 3rd party integration connections, and you'll likely need your admin user for approval on many applications.

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.

Note:

The API Action's response must be within 10 seconds for the app tile to load or function properly.

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.

Component Validations

Some new validation checks are now in place:

Container:

• Appearance Tab: If custom size is selected, the height and width must not exceed 100%, and both must be numeric.
• Data Tab:
  • If Loop Data is enabled, an Array Object field must be present.
  • If Link to external URL is selected, the External URL button text and External URL field must be provided.

Text:

• Data Tab: The text field should not exceed 512 characters, though an empty value is acceptable.

Link:

• Data Tab:
  • Both Link Text and URL fields are mandatory.
  • Link Text must be under 512 characters.
  • URL should be a valid URL.

Image:

• Appearance Tab:
  • If the Image size is set to custom, height and width must be either 100% or less if using percentages, or less than 1024px width and 768px height if using pixels. Both fields must contain numeric values.
• Data Tab:
  • Image Source is required and must be a valid URL.
  • Target URL must be a valid URL.
    • Alt Text should not exceed 512 characters.

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!

---