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 by hand-written code or with App Builder (code and Variables, with Developer Helper or the App Builder drag-and-drop tool).
  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 and edit access for Users and Groups, optional Public App access for external audiences without an MI login) 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 to creating Apps in Metric Insights:

Templates are recommended, since they allow defining common structure and logic while offering flexibility with the displayed content. You can later diversify the populated Apps using the specifically designed Metric Insights features. This approach is especially recommended for use-cases where you plan to create multiple Apps from one blueprint Template. This phase covers only whether to start from a Template or a standalone App; Phase 3 covers the other build decision, whether to build with App Builder or by hand.

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 decided on the App's Layout, build its structure using one of two co-equal paths: App Builder or hand-written code.

  1. Path B: Hand-written code: Build the App structure directly in code.
    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.
  2. Path A: Build with App Builder: Assemble the App visually, without hand-written code.
    1. Open App Builder: On the App or Template, enable the "Use App Builder" toggle. See App Builder Overview.
    2. Assemble the layout: Add built-in components. See App Builder Built-In Components.
    3. Apply styling: Set the appearance through the Styles tab (v7.2.1+). See Configure Styles for App Builder Elements And Components.
    4. Extend when needed: Add custom components or libraries if built-in components do not cover your use case. See Custom Components for App Builder and Add Library with Custom Components to App Builder.

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).
  • For the App Builder path, styling is applied through the Styles tab.

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 development workflow is defined, choose and implement the method for data interaction. Several approaches can be used simultaneously depending on the goal:

  • Embedding Metric Insights content: When you're primarily presenting Metric Insights content in a custom layout.
  • Using App Entities: When you want managed, app-scoped integration points into Metric Insights.
  • Using Metric Insights 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 that lets you generate embed codes for selected Elements and paste them directly into 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, and Custom Scripts.

  1. Create Entities for your App.
  2. Interact with the created Entities using Portal Page Entities API.
  3. Use App Dataset Entities for in-App reporting with read and write access over REST, without SQL access. Supported methods: GET, POST, PUT, and DELETE. See Track Element Clicks on a Page Using an App Dataset.
    • v7.2.2+: Unauthenticated visitors to a Public App can read and write an App Dataset anonymously when the Entity's Access Type is "Public". All other access types require an authenticated session.

4C Use Metric Insights API to Interact with Elements Directly

Metric Insights API allows you to interact with a broad variety of system objects, Elements, and permissions, and to create, categorize, and distribute different types of content.

There are two approaches to granting API access:

  • External Application-related tokens: The older approach allows you to generate tokens directly via API.
    1. Set up API Access
    2. Get Token
  • Personal Access Tokens: These can be generated only via the UI, support granular permissions for Users, and have a 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 intended non-Admin 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 establish an update mechanism: either uploading a ZIP of Assets manually or syncing 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).

This final step configures access to the App and permissions for Users and Groups; this determines who can see the App and who can 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
  3. To open the App to an external audience, make it a Public App, accessible without an MI login: Configure Public App

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

  • Admin;
  • Intended user (Power User or Regular User);
  • Unauthenticated user (for Public Apps);
  • Restricted user.

Phase 8: Advanced Usage Examples

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

Once you have completed the full process of creating, setting 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).