AEM OSGi Config Generator

What this tool does

The generator writes AEM OSGi configuration files (.cfg.json) and puts each in the right run-mode folder of your project. Start from a common configuration (logger, service user mapping, externalizer, CORS, referrer filter, default GET servlet) or your own service, fill in the form, and download every file at once. On AEM as a Cloud Service it writes $[env:…] and $[secret:…] placeholders for you and lists the variables to set in Cloud Manager.

When to use it

• Adding a configuration to a project, without looking up the PID, property names, types or folder layout.
• Setting different values per environment, such as debug logging on dev only, or a different API URL on stage.
• Moving secrets out of Git, by replacing them with secret placeholders.
• Checking an existing file: import a .cfg.json to see and fix its types, placeholders and run mode.

How to use it

1. Choose AEM as a Cloud Service or AEM 6.5, and set your app ID and module.
2. Add a configuration from the list, or import an existing .cfg.json.
3. Open it and choose where it applies: author, publish or both, and which environment. On AEM 6.5 you can add other run modes.
4. Fill in the properties. For your own service, enter the PID (usually the implementation class name) and add properties with their types.
5. On AEM as a Cloud Service, set Value from to Variable or Secret for values that differ per environment or mustn’t be in Git.
6. Press Copy on a configuration to make a version for another environment, then change its values.
7. Check the Checks tab, then Download all (.zip) and unzip it over your project root. Set the listed variables in Cloud Manager before deploying.

Run modes and precedence

Folder	Applies to
config	Every service and environment
config.author, config.publish	One service
config.dev, config.stage, config.prod	One environment
config.publish.prod	One service in one environment

When several folders configure the same PID, the folder matching the most run modes wins, and it replaces the whole configuration: properties aren’t merged across folders. On AEM as a Cloud Service, preview uses the publish configuration, and custom run modes aren’t supported.

Types in .cfg.json

Type	Written as
String	"key": "value"
String[]	"key": ["a", "b"]
Boolean	"key": true
Long	"key": 5
Integer	"key:Integer": 5
Double	"key": 2.5, or "key:Double": 2 for whole numbers

Variables and secrets

• $[env:NAME] takes the value of an environment variable; $[env:NAME;default=value] falls back to a default.
• $[secret:NAME] takes a secret. Secrets are required for passwords, private keys and tokens on AEM as a Cloud Service.
• Names are 2–100 letters, digits and _, not starting with a digit. Names starting with INTERNAL_, ADOBE_ or CONST_ are reserved by Adobe.
• Values are at most 2048 characters, and each environment holds up to 200 variables.
• Placeholders are written as strings. Most components convert them, but check yours if the property is a number or boolean.

Limits

• Factory files are named with ~ (<factoryPID>~<name>.cfg.json), the form Sling recommends; Adobe’s documentation also shows -, which works too.
• The catalogue lists the most-used properties of each configuration. Add others with + Add property; any you leave out keep their defaults.
• Variables and secrets only work on AEM as a Cloud Service. On AEM 6.5, keep secrets out of Git with the Crypto Support service.