Help & Documentation
Open Support Ticket

Custom Apps Workflow Playbook

Target Personas

NOTE: One person can hold multiple roles. The workflow still works as long as each responsibility is explicitly assigned.

  • Metric Insights Admin: Enables the feature set, controls governance, and manages sharing and permissions.
  • App Developer: Builds UI/logic, manages assets, and implements integrations and error handling.
  • App Owner: Defines goals and acceptance criteria; approves UX/layout and go-live readiness.
  • Security/IAM (as needed): Reviews secure handling of sensitive values and validates authorization boundaries.
  • Validator (often the App Owner): Runs persona testing and confirms rollback readiness.

Workflow Overview (What Happens in This Process)

A Custom App implementation typically follows these phases:

  1. Create a new App (with/without App Template) and capture the IDs needed for development.
  2. Define the App layout (with MI navigation bar vs custom layout).
  3. Build the App UI (code + variables + optional tooling such as Developer Helper / App Builder).
  4. Connect the App to content and data (embedding, entities, and/or MI API).
  5. Add and manage App assets (ZIP upload or VCS sync) and validate the update loop.
  6. Apply optional customizations (caching, custom domain, feedback prompt, React nav bar, legacy compatibility).
  7. Share the App (visibility + edit access) and validate behavior across personas.
  8. Implement advanced patterns (secure external APIs, Snowflake OAuth examples).

Pre-Work

Complete the Decision Gates section in Best Practices & First Principles: Custom Apps before starting Phase 1.

Phase 1: Create a New App

Who: MI Admin or App Developer.

There are two approaches of creating Apps in Metric Insights:

  • Create a Template from which you will populate future Apps,
  • Create a standalone App.

We recommend using Templates, since it allows defining common structure and logic, while offering flexibility with the displayed content. You can later diversify the populated Apps using the specifically designed MI features. This approach is especially recommended for use-cases where you plan to create multiple Apps from one blueprint Template.

  1. Create an App Template (recommended).
  2. Create an App (alternatively, skip to this step, if you don't plan populating more similar Apps).

IMPORTANT: Note the App Template ID (if used) and the App ID, these values are required for App development.

Phase 2: Define Layout for Your App

Who: MI Admin + App Owner + App Developer.

Choose whether your App will be displayed with Metric Insights navigation bar, or will have its own Layout.

  1. If the App uses a custom Layout, you can select an existing one, or create a new Layout. Otherwise, proceed with the standard Layout containing the MI navigation bar.

Phase 3: Write Code for Your App

Who: App Developer.

Once you have made a decision regarding the App's Layout, you can proceed with creating its structure.

  1. Start with known patterns and common FAQs: Use snippets and official guidance for core behavior.
  2. Set up an efficient workflow: Use the Developer Helper for faster develop/test loops.
  3. Parametrize with Variables: Use Template Variables to avoid hardcoding environment-specific configuration.
  4. Optional Path: App Builder: Use App Builder when it fits your use case, and extend it via custom component libraries if needed.

Checklist for Phase 3 completion:

  • Core UI renders and navigation works.
  • Variable strategy is in place (no hardcoded environment values).
  • Dev workflow is defined (manual updates vs helper/Next.js workflow).

Phase 4: Interacting with Data from App

Who: App Developer + MI Admin (and Security/IAM if sensitive/external).

Once the core UI is rendered and the dev workflow is defined, it's time to choose and implement the method for data interaction. There are several approaches which can be used simultaneously depending on the goal:

  • Embedding Metric Insights content: When you’re primarily presenting MI content in a custom layout.
  • Using App Entities: When you want managed, app-scoped integration points into MI.
  • Using MI API: When you need broad programmatic control and are prepared to manage authentication and failure handling.

4A Embedding Element from MI

Metric Insights provides built-in embedding functionality which allows to simply generate embed codes for the selected elements and copy/paste it right to the App:

4B Use Entities to Interact with MI Data

Entities provide a structured and managed way to connect Apps to Metric Insights objects, such as Datasets, Data Sources, Custom Scripts.

  1. Create Entities for your App.
  2. Interact with the created Entities using Portal Page Entities API.

4C Use Metric Insights API to Interact with Elements Directly

Metric Insights API allows interacting with a broad variety of system objects, elements, permissions, create, categorize, distribute different types of content.

There are two approaches in granting API access:

  • External Application-related tokens: The older approach, allows to generate tokens directly via API.
    1. Set up API Access
    2. Get Token
  • Personal Access Tokens: Can be generated only via the UI, support granular permissions for users, configurable lifetime.
    1. Generate personal API Token

Once you have enabled API access with either of the token types, see the documentation on available API endpoints.

Checklist for Phase 4 completion:

  • Works for non-admin intended users (not only for admins).
  • Failure states are visible (not silent).
  • If using API tokens, token acquisition and a simple test call succeed.

Phase 5: Add Assets to Your App Template

Who: App Developer + MI Admin.

App Assets allow you to upload the code, including HTML/CSS/JS files and images for your App. This also helps establishing an update mechanism: either uploading ZIP with aasets manually, or sync with a version control system.

  1. Learn what filetypes are supported for Assets and how to use them in your App: Understanding App (Portal Page) Assets
  2. Choose the Asset distribution method:

NOTE: If the changes are not showing up, confirm caching (see Phase 6).

Phase 6: Customization

Who: App Developer + MI Admin.

Once the main App functionality is established, you can proceed customizing it.

  1. Fine-tune App performance by setting up cache lifetime: App (Portal Page) Asset Caching for Improved Performance
  2. If you want to set a custom domain for your App: Configuring a Custom Domain for an App (Portal Page)
  3. If you want to enable a Feedback Prompt on your App: How Do I Enable Feedback Prompt on an App (Portal Page)?
  4. If you want to enable MI navigation bar for a React App: Enable MI Navigation Bar in React-Based App
  5. If you are using legacy Apps from v6: Legacy Scripts for Apps (Portal Pages) Compatibility in v7.0.1+

Phase 7: Share App With Users and Groups

Who: MI Admin + App Owner (signoff).

The last but not the least step is configuring access to the App and permissions for Users and Groups. This means configuring who will see the App and who will be able to make changes to it:

  1. Configure App visibility for Users and Groups: Start Page Priority Rules
  2. Configure edit access: Sharing Apps, Displaying in Navigation Bar and As Start Page

Once you have configured App access, validate the behavior for different user types:

  • Admin
  • Intended user (Power User or Regular User)
  • Restricted user

Phase 8: Advanced Usage Examples

Who: App Developer + Security/IAM + MI Admin.

Once you have completed the full process of creating, settings up, and sharing the App, proceed with implementing more advanced functionality. Examples below demonstrate secure integration patterns and specialized auth flows:

  1. Secure Interaction with External APIs in an App (Portal Page)
  2. Configure Snowflake OAuth via an App

Checklist for Phase 8 completion:

  • Secrets/sensitive values are not stored in front-end assets.
  • Failure modes are user-visible and actionable (no silent break).