Add-ons CLI

The @planningcenter/add-ons-cli tool helps you generate a skeleton add-on and is what you will use to configure and upload your code to Planning Center.

Once installed with npm, the subcommands are to be used like this:

• planningcenter-add-ons -V: Show the current version of the tool installed.
• planningcenter-add-ons create <name>: Creates a new directory with sample code for your new Add-on.
• planningcenter-add-ons update: Bundles and uploads add-on code to Planning Center.
• planningcenter-add-ons watch: Watches the files in the add-on directory and runs update when they change.
• planningcenter-add-ons promote <from-env> <to-env>: Copies bundled JavaScript from one environment to the next, e.g. from testing to beta, or from beta to production.

config.yaml

Your add-on directory generated by the CLI tool contains a config.yaml file that looks like this:

testing_oauth_config: &testing_oauth_config
  authorize_url: http://myapp.local/oauth/authorize
  token_url: http://myapp.local/oauth/token
  redirect_url: http://myapp.local/oauth/complete
  identifier: "{{ TESTING_INTEGRATOR_OAUTH_IDENTIFIER }}"
  secret: "{{ TESTING_INTEGRATOR_OAUTH_SECRET }}"
  scopes: []

production_oauth_config: &production_oauth_config
  authorize_url: https://example.com/oauth/authorize
  token_url: https://example.com/oauth/token
  redirect_url: https://example.com/oauth/complete
  identifier: "{{ PRODUCTION_INTEGRATOR_OAUTH_IDENTIFIER }}"
  secret: "{{ PRODUCTION_INTEGRATOR_OAUTH_SECRET }}"
  scopes: []

add_on:
  oauth_application_id: "300"
  environments:
    testing:
      integrator_oauth: *testing_oauth_config
    beta:
      integrator_oauth: *production_oauth_config
      ui_extensions:
        - people.list.send_message
      organization_ids: []
    production:
      integrator_oauth: *production_oauth_config
      ui_extensions:
        - people.list.send_message
  scopes:
    - people
  ui_extensions:
    people.list.send_message:
      title: Send text with Foo
      icon_url: data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMjAgMjAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iMTAiIGN5PSIxMCIgcj0iOCIgc3Ryb2tlPSJoc2woMjY4LCA3MSUsIDI3JSkiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSIvPjwvc3ZnPg==
      icon_dark_url: data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMjAgMjAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iMTAiIGN5PSIxMCIgcj0iOCIgc3Ryb2tlPSJoc2woMjY4LCA3MCUsIDg4JSkiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSIvPjwvc3ZnPg==
      component_version: "6"

The meaning of each key is described below:

• oauth_application_id: This is the ID of the OAuth application record in Planning Center that houses your application configuration. You can manage this record here: https://api.planningcenteronline.com/oauth/applications. The value of this field should be the application ID you see in the URL when viewing your application. For example, if clicking "edit" on your OAuth application takes you to https://api.planningcenteronline.com/oauth/applications/42/edit, then the application ID is 42.

• environments

  • testing, beta, and production

    • integrator_oauth: This section contains settings so Planning Center can get an OAuth token from your (the Integrator's) API. The authenticatedIntegratorFetch() function utilizes the the OAuth token obtained with this configuration.

      • authorize_url: OAuth will be initiated at this URL where the user will click "Allow" or similar. This is a URL on your server that gives the user the chance to see that Planning Center will be accessing the data on your server on their behalf.
      • token_url: The OAuth token will be obtained from this URL
      • redirect_url: The URL where Planning Center will redirect after the user authorizes your add-on to access Planning Center data. (This must match one of the "Authorization callback URLs" on the OAuth Application configuration here.)
      • identifier: This is the OAuth application identifier
      • secret: This is the OAuth application secret
      • scopes: This is the list of scopes Planning Center will request from your OAuth server, as a YAML array

    • ui_extensions: This is a YAML array of UI Extension names, e.g. people.list.send_message. The configuration for these UI Extensions is later in the config file. This is just a list of the names. This would allow you to hide new UI Extension from your production or beta environment while it is in early development.

  • beta-only config

    • organization_ids: This is a YAML array of Organization IDs that control which organizations see your "beta" add-on. You can put up to 20 IDs in this list.

• scopes: This is a list of OAuth scopes for your add-on. The API token generated for your add-on automatically by authenticatedFetch() will have these scopes. Only use the OAuth scopes you absolutely need. These are Planning Center scopes, e.g. people, services, registrations, etc.

• ui_extensions

  • insertion point: This is the name of an insertion point where your UI Extension will appear. This name must exactly match the filename of your UI Extension, e.g. for the insertion point people.list.send_message, the filename must be people.list.send_message.jsx.

    • title: This text will appear at the insertion point and be an actionable link, button, or tab for your user to choose.
    • icon_url: This is an icon that may or may not appear next to the title. This depends on how the insertion point is designed in the UI and will vary.
    • icon_dark_url: If the user prefers dark mode, we'll use this icon instead.
    • component_version: Specifies the component version your UI Extension uses, allowing you to opt-in to breaking component changes once your extension has been updated. Default: "5"