Making Your Add-on Shareable
Last updated 06 December 2017
Table of Contents
To minimize integration churn in the context of other features coming in the next year, the first version of Shareable Add-ons makes minimal changes to the current add-on partner integration.
In this guide, we will take you step by step through the process of making your existing Heroku Add-on “Shareable.”
Your staging add-on
If you have a staging environment and corresponding Heroku Add-on that differ from your publicly-available Heroku add-on, we highly recommend testing these changes extensively there before promoting these changes to your main offering.
Supporting multi-app attachment
To make an add-on shareable between apps, add the
attachable flag to the
requires array in your manifest. No further changes should be necessary for
Supporting multiple installs per app
To allow an add-on service to be installable to the same application multiple times:
- Add the
many_per_appflag to the
requiresarray in your manifest.
- Be sure to remove any uniqueness constraint on the
heroku_idfield in provision requests.
- Use the new provision-time
uuidfield for Heroku-side uniqueness, if desired
- This field will only be present for add-ons flagged into the new runtime or for provisions from users or applications that are flagged in.
- Return your own provision response
idthat is unique per installation, not app (i.e. not a derivative of
- Optionally back-fill the
uuidfield from the App Info API as needed. The field may be null for some installations, until migration and roll-out is complete.
many_per_app flag is enabled, users will be able to override the
“attachment name” which is used as the prefix to env vars.
For an add-on named
foo-bar which sets
FOO_BAR_B, we will
treat this as setting
B instead by stripping out a normalized variant
of the add-on service slug from the beginning of the string. (In a future
integration version, the service-prefix won’t be necessary but is necessary
today for backwards compatibility)
- A and B are prefixed by the attachment name from the perspective of the
application. For an attachment named
BALLOON, this will result in
BALLOON_Bvars being exposed.
- Attachment names are chosen with the following heuristic
- Customer-provided name (e.g.
WORKER; if conflict, error)
- Partner-recommended name (e.g.
REDIS; if conflict, next)
- Normalized add-on service slug (e.g.
REDISGREEN; if conflict, next)
- Normalized add-on service slug + random color (e.g.
REDISGREEN_CYAN; if conflict, pick new random color; if color pool exhausted, error)
- Customer-provided name (e.g.
- Custom names may be allowed even without
many_per_appenabled in the future.
- To provide a recommended attachment name return a root-level key named
recommended_prefixin the provision response. Based on partner feedback, this recommendation may move to the manifest
What to test
Exercise every aspect of your add-on to be sure the above changes did not have a negative impact on functionality; also test the following behaviors specific to Heroku integration, where they apply to your add-on:
- Provisioning for the same app multiple times (if you chose to support many-per-app)
- Multiple attachments of one installation to the same app
- SSO in the context of multiple installations on a single app, and with attachments to multiple apps
- Custom attachment naming
- Updating configuration variables and checking that they propagate to all attached applications
- Plan upgrades and downgrades