Migrate a public app to the developer projects framework (BETA)

Using the CLI, you'll migrate an existing production public app to the projects framework. App features that are supported by projects, such as auth configuration and webhooks, will be included automatically in the migration. Features not supported by projects, such as custom workflow actions and timeline events, can be configured through the app settings UI or API as before.

In this guide:

• Prerequisites
• Migrate to the projects framework
• Add app cards
• Development workflows
  • Workflow for unlisted apps
  • Workflow for App Marketplace apps
• Rolling out updates to the App Marketplace
• Feature flag API reference

This guide assumes that you meet the following criteria:

• You have an existing public app that has not yet been converted to the developer projects framework.
• You are ready to migrate your public app to the developer projects framework, enabling the creation of UI extensions for your app. If you want to start with a dry run of the migration, you can instead make a copy of your app in a project by running hs project clone-app.
• You have set up your local environment for project development and set your developer account as the default in the CLI. 
  • To view your connected accounts, run hs accounts list in the terminal. The terminal will list all currently connected accounts, along with the default.
    
  • If your developer account is connected but not the default, run hs accounts use <accountName>.
  • If you haven't connected your developer account to the CLI yet, revisit the setup guide.

To begin migration, you'll switch your public app to be configured using projects. This process will preserve the original auth credentials, and all other existing app features, App Marketplace listings, and app installs. No changes are required in your app backend, and customers will not experience any interruptions in service.

• Ensure you've installed the latest version (v6.1.0 or greater) of the HubSpot CLI by running npm i -g @hubspot/cli@latest.

• With your developer account connected to the CLI and set as the default, run hs project migrate-app.

• Select the public app that you'd like to migrate. This will create a new project containing a single public app component that represents the current state of your app.
  
• Enter a name and local path for your project, then press Enter. The terminal will then display a message to outline the migration process and confirm your intention to convert the app. 

• Press Enter to confirm that you're ready to proceed with migration.
• The migration process will then begin, and the terminal will display the migration status. The migration includes:
  • Creating the project in your app developer account.
  • Converting the project-supported features of the app to source code files, which you can use int he future to update feature configuration.
  • Building and deploying the new project (Build #1), which completes the association between the public app and its project. This will preserve the original auth credentials, all app features, App Marketplace listing, and installs.
  • Downloading the new project source files to the specified local directory.

With build #1 succeeded, you'll now have captured your original app's configuration state. As you continue to build your app and UI extensions, you can always safely revert to this state by redeploying build #1 by running the hs project deploy --buildId=1 command.

Before you can begin UI extension development and run a local development server, deploy the successful build by running hs project deploy.

With the app successfully migrated, you can now update the public app with app cards.

After the migration is complete, you can add UI extensions to it to customize the HubSpot UI with app cards, along with any other required app feature definition changes from your local development project to the new project-based public app. For guidance around building UI extensions, you can:

• Follow the public app quickstart guide to see HubSpot's boilerplate project template, which includes a simple app card.
• Check out HubSpot's sample UI extensions.
• Review the utilities available in the UI extensions SDK.
• Browse the available UI components for building the UI of your cards.

While developing a UI extension, you can start a local development server to see your changes in the browser in real-time without needing to upload. To enable local development:

• Install dependencies by running npm i in the src/app/extensions directory. 
• Add the card to the UI location through the account's settings. For apps that are currently listed on the App Marketplace, you'll need to complete this step after setting the test account feature flag.

Your development workflow for building out your app will depend on whether it's currently listed in the App Marketplace:

• Migrated apps that are listed in the App Marketplace will automatically be set with a feature flag to prevent your deployed changes from rolling out to active installs. You will need to selectively enable accounts for development and testing using the feature flag API. Learn more about the development workflow for listed apps.
• Migrated apps that are not listed in the App Marketplace will not be set with feature flags by default, so your deployed changes will be available in the accounts where the app is currently installed. However, you can enable feature flagging for your app with the feature flag API if you would like to selectively limit access during the development phase. Learn more about the development workflow for unlisted apps.

If your app is listed in the App Marketplace, your migrated app will automatically have a feature flag enabled that controls access to app cards in the accounts where the app is installed. You'll need to use the feature flag API to selectively enable accounts to use the new app cards. By default, app cards for listed public apps are restricted to a maximum of five accounts. 

To start developing new app cards without impacting production accounts, first create a test account within your developer account if you haven't done so yet. Then, using your developer account's developer API key, set your test account's feature flag to ON by making a request to the feature flag API.

With your test account feature flag configured, you'll be able to view new app cards in HubSpot as you develop your UI extensions.

• Enable local development, then start the local development server by running hs project dev in the terminal.

• When the build succeeds, deploy your changes by running hs project deploy.

You can continue testing your app and its new cards in additional accounts by using the feature flag API to set the flagState to ON, as shown in the first step above. You can enable this flag for up to five accounts, including beta customers.

Once you've sufficiently tested your updated app, you'll need to submit it for review by emailing details to [email protected].

After receiving approval for unlimited distribution from the App Card marketplace review process, your app will be ready for distribution. Before proceeding with app distribution, it's recommended to consider the following:

• If your app previously included a classic CRM card in the sidebar, consider adding card update guidance so that users can seamlessly add your new cards and remove the old ones.
• It’s recommended to gradually roll out your app card updates to catch any issues before distributing to the full install base. You can also roll out to all installed accounts at the same time.

To help users migrate to your new cards, HubSpot includes a default update state that you can apply to your classic cards. This update includes messaging to indicate that the card should be updated, along with a link to the record customization settings page where they can then add the app’s new cards. 

The state will only display to super admins, so non-admin users will not see any disruption.

To add this state to your classic cards, include "showMigrationMessage": "true" in the card's JSON response. This should be included at the top-level of the response.

Alternatively, you can build your own custom update state by manually updating the card's JSON response directly, or even using the feature flag API for conditional responses.

With the default update state enabled for your classic cards, their content will be replaced, and you can walk through what the end-user experience will be for super admins who want to upgrade to your new cards:

• In the test account, navigate to a CRM record that contains your classic card.
• On the CRM record, locate the card, then click the Update card link to navigate to the app settings page.
  
• The app settings page will display all available cards. Click the link provided for each card to navigate to the customization page for that object.

• Users can then proceed to customize their record pages as needed. They can find your new cards within the Apps section of the customization sidebar.
• After adding the new card, the old card can be removed by locating it in the view editor then clicking Remove.
  

Learn more about the card updating user experience on HubSpot's Knowledge Base.

Using the feature flag API, you can gradually roll out your app in two ways:

• Roll out app cards to new installs
• Roll out app cards to a subset of accounts

To roll out your app cards to new installs only, you'll use the feature flag API to turn off the feature flag for all existing installs. Then, you'll turn on the default flag state so that new installs have the flag enabled by default.

• For the first request, you'll set the flagState to OFF for all accounts that currently have the app installed. You'll need to gather the portalId for all existing installed accounts, then make a POST request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/batch/upsert?hapikey={developerAPIKey}.

• With existing app installs set to OFF, you can now use the feature flag API to set the defaultState to ON. To do so, make a PUT request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}

• Once you feel confident in new customer adoption, you can begin to remove customer portalIds that you switched to the OFF state by making a POST request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/batch/delete?hapikey={developerAPIKey} with the account IDs you want to remove from the OFF list.

• When all previously added accounts have been deleted using the above endpoint, you''ll have successfully completed the rollout and finished migration. At this point, you can safely delete your feature flag by making a DELETE request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}.

Alternatively, rather than starting with new installs, you can selectively enable your app cards for a subset of accounts that have your app installed. To do so, you'll need to have a list of the account IDs for all existing public app installs. With that list, you can make a POST request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/batch/upsert?hapikey={developerAPIKey} and set their flagState to ON.

You can continue making this request for subsets of accounts until all accounts have been migrated. Then, you can delete your feature flag by making a DELETE request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}.

To release your app cards to all installed accounts simultaneously, delete the app's feature flag by making a DELETE request to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}.

Use the feature flag API to control availability of your app cards in customer accounts. All endpoints are under the https://api.hubapi.com/feature-flags/v3/{appId} root path.

This API has two resources: App Flags and Portal Flag States.

The API currently supports a single App Flag: hs-release-app-cards. All example URLs are given with this flag name already specified. Attempts to specify other App Flags will receive an error.

Flag endpoints can be used to retrieve and update an app's feature flags.

GET /flags/hs-release-app-cards?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Retrieve an app's hs-release-app-cards feature flag. No request body is included.

PUT /flags/hs-release-app-cards/?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Update an app's feature flags.

Portal Flag State endpoints can be used to retrieve and update feature flags at the account-level.

GET /flags/hs-release-app-cards/portals/{portalId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY


Retrieve a single account's App Card Release flag state setting.

GET /flags/hs-release-app-cards/portals/?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY


Retrieve a list of HubSpot accounts with an account-specific flag setting. No request body is included.

Accepts the following query parameters:

• limit: maximum number of results to return in a single request.
• startPortalId: the initial account ID for listing, enabling pagination.

PUT /flags/hs-release-app-cards/portals/{portalId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Specify a Portal Flag State for a specific HubSpot account and the hs-release-app-cards flag.

DELETE /flags/hs-release-app-cards/portals/{portalId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Delete a Portal Flag State for a specific HubSpot account. No request body is included.

POST /flags/hs-release-app-cards/portals/batch/upsert?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Set hs-release-app-cards portal flag state for multiple HubSpot accounts at once. Use this endpoint to manage flag exposure for groups of HubSpot accounts

POST /flags/hs-release-app-cards/portals/batch/delete?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY

Delete hs-release-app-cards portal flag state for multiple HubSpot accounts at once. Use this endpoint to manage flag exposure for groups of HubSpot accounts.