Accepting Custom Options on Provision
Last updated August 23, 2024
Table of Contents
This article describes how add-on partners can access command-line parameters sent by a user as part of add-on provisioning.
When provisioning at the command-line, customers have the option of specifying additional options which we pass along to you. You can use these to provide additional functionality to your install that cannot be determined simply by plan or by accessing additional customer information through the Unified API. For example, Heroku PostgreSQL uses customer options to support creating database forks and followers.
Command-line parameter format
The command-line accepts parameters in standard Unix-style switch format, with or without an equals sign.
Single parameters are interpreted as boolean switches and will have the string 'true' as their value.
For example, the following command line:
$ heroku addons:create youraddon -- --foo=bar --bar foo --baz
Will be interpreted as:
{ "foo" : "bar", "bar" : "foo", "baz" : "true" }
Accessing parameters
Heroku passes command-line parameters given to the addons:create action during add-on provisioning to the add-on partner.
Heroku performs no validation of these parameters before passing them along, so you will receive all parameters that the customer has specified. We strongly recommend ignoring any options you do not recognize instead of failing in these cases.
These options are passed in the JSON body of the provision request via the “options” key.
Consider this example:
$ heroku addons:create youraddon -- --foo=bar --bar foo --baz
The options are included as part of the JSON in the provision request:
POST /heroku/resources HTTP/1.0
Content-Type: application/json
{
"options": {"foo":"bar","bar":"foo","baz":"true"},
"heroku_id": "app12345@heroku.com",
"plan": "test",
"callback_url": "http://localhost:7779/callback/999"
}