Feature flags

​

Migrate a public app to the developer projects framework

​

Prerequisites

• You have an existing public app that has not yet been converted to the developer projects framework.
• You’ve opted your developer account into the new developer overview, or you’re using a standard HubSpot account to manage your apps (which automatically uses the new developer overview).
• 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 <accountNameOrID>.

​

Migrate legacy public app to the projects framework

• Ensure you’ve installed the latest version (v7.6.0 or greater) of the HubSpot CLI by running the following command:

npm i -g @hubspot/cli@latest

• With your developer account connected to the CLI and set as the default, run the command below:

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 HubSpot 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.

hs project deploy

​

Workflow for HubSpot Marketplace apps

​

Development workflow

curl -XPUT -s --json '{"flagState": "ON"}' 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/{portalId}?hapikey={developerApiKey}'

hs project dev

hs project upload

hs project deploy

​

Rollout strategies

​

Add card update guidance

Admin view	Non-admin view

response.status(200).send({"showMigrationMessage": "true", "results": [crmCardDetails]});

• In the test account, navigate to a CRM record that contains your classic card.
• On the CRM record, locate the card, then click the Set up now 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. Alternatively, you can hide the old card from the account using the feature flag API.

​

Gradually roll out app cards

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

Roll out to new installs

• For the first request, 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}.

// Example POST to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/batch/upsert?hapikey={developerAPIKey}
{
  "portalStates": [
    {
      "portalId": 1234,
      "flagState": "OFF"
    },
    {
      "portalId": 4567,
      "flagState": "OFF"
    },
    {
      "portalId": 78910,
      "flagState": "OFF"
    }
  ]
}

• With existing app installs set to OFF, you can now 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}

// Example PUT to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}
{
  "defaultState": "ON"
}

• 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.

// Example POST to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards/portals/batch/delete?hapikey={developerAPIKey}
{
  "portalIds": [1234, 4567, 78910]
}

• 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}.

curl --request DELETE \
  --url 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}'

​

Roll out to a subset of accounts

{
  "portalStates": [
    {
      "portalId": 1234,
      "flagState": "ON"
    },
    {
      "portalId": 4567,
      "flagState": "ON"
    },
    {
      "portalId": 78910,
      "flagState": "ON"
    }
  ]
}

curl --request DELETE \
  --url 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}'

​

Roll out to all accounts simultaneously

curl --request DELETE \
  --url 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-release-app-cards?hapikey={developerAPIKey}'

​

Hiding legacy CRM cards

• Make a PUT request to set your app’s defaultState to OFF. This initializes the app flag and ensures that the app’s legacy CRM cards will be visible in every existing and new installed account.

// Example PUT to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-hide-crm-cards?hapikey={developerAPIKey}
{
    "defaultState": "OFF"
}

• Next, set the flagState to OFF for all accounts that currently have the app installed. In the request body, you’ll provide a portalId for each account.

// Example POST to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-hide-crm-cards/portals/batch/upsert?hapikey={developerAPIKey}
{
  "portalStates": [
    {
      "portalId": 1234,
      "flagState": "OFF"
    },
    {
      "portalId": 4567,
      "flagState": "OFF"
    },
    {
      "portalId": 78910,
      "flagState": "OFF"
    }
  ]
}

• With existing app installs set to OFF, make another request to set the defaultState to ON. This prevents new installs from ever seeing the app’s legacy CRM cards.

curl --request PUT \
  --url 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-hide-crm-cards?hapikey={developerAPIKey}'\
  --header 'content-type: application/json' \
  --data '{
    "defaultState": "ON"
  }'

• As you observe customers using the new app cards, such as receiving hubspot.fetch() calls from their accounts, you can remove them from the hs-hide-crm-cards flag list using the request below. Because you hid the legacy CRM cards from new installs, you’ll only need to take this step for accounts you previously set to OFF.

// Example POST to https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-hide-crm-cards/portals/batch/delete?hapikey={developerAPIKey}
{
  "portalIds": [1234, 4567, 78910]
}

• When all previously added accounts have been removed from the flag list, you can be sure that your entire install base can no longer access the old legacy CRM cards. At this point, you can navigate to the app’s settings page in your developer account and delete the legacy CRM cards.

• Finally, make a request to delete the hs-hide-crm-cards flag from the app.

curl --request DELETE \
  --url 'https://api.hubapi.com/feature-flags/v3/{appId}/flags/hs-hide-crm-cards?hapikey={developerAPIKey}'

​

Feature flag API reference

• App flag endpoints:
  • Retrieve an app’s feature flags
  • Retrieve accounts with a set flag state
  • Set an app’s feature flag
  • Delete an app’s feature flag
• Account flag state endpoints:
  • Delete an account flag state
  • Retrieve account flag state
  • Batch delete account flag state
  • Batch set account flag state
  • Set an account flag state