update documentation

src/site/markdown/index.md

@@ -9,6 +9,7 @@ wcm.io DevOps CONGA Plugin for [Apache Sling][sling].
 
 * [Usage][usage]
 * [CONGA Extensions][extensions]
+* [Combined JSON file for defining OSGi Configurations][osgi-config-combined-json]
 * [API documentation][apidocs]
 * [Changelog][changelog]
 
@@ -17,8 +18,8 @@ wcm.io DevOps CONGA Plugin for [Apache Sling][sling].
 
 This plugin extends [CONGA][conga] with:
 
-* Manage OSGi configuration templates in [Apache Sling Provisioning][sling-provisioning] file format
-* Generate OSGi configurations in [Apache Felix Config Admin][felix-configadmin] file format
+* Manage OSGi configuration templates in [Combined JSON files][osgi-config-combined-json] or [Apache Sling Provisioning][sling-provisioning] file format
+* Generate OSGi configurations in `.cfg.json` files (as used by [Apache Sling Configuration Installer Factory][sling-configuration-installer-factory-cfg-json])
 
 
 ### Further Resources
@@ -31,9 +32,10 @@ This plugin extends [CONGA][conga] with:
 
 [usage]: usage.html
 [extensions]: extensions.html
+[osgi-config-combined-json]: osgi-config-combined-json.html
 [apidocs]: conga-sling-plugin/apidocs/
 [changelog]: changes-report.html
 [conga]: https://devops.wcm.io/conga/
 [sling]: http://sling.apache.org/
 [sling-provisioning]: https://sling.apache.org/documentation/development/slingstart.html
-[felix-configadmin]: http://felix.apache.org/documentation/subprojects/apache-felix-config-admin.html
+[sling-configuration-installer-factory-cfg-json]: https://sling.apache.org/documentation/bundles/configuration-installer-factory.html#configuration-files-cfgjson

src/site/markdown/osgi-config-combined-json.md

@@ -0,0 +1,54 @@
+## Combined JSON file for defining OSGi Configurations
+
+Similar to the (deprecated) [Apache Sling Provisioning File Format][sling-provisioning] it is possible to define a set of OSGi configurations using a CONGA template in a single JSON file which contains a set of OSGi configurations and [repoinit][sling-repoinit] statements, optionally mapped to run modes.
+
+From this combined JSON file, CONGA generates individually `.cfg.json` files as used by [Apache Sling Configuration Installer Factory][sling-configuration-installer-factory-cfg-json]. With this approach it is easy to define all configurations in one file, and add/remove configurations based on CONGA environment variables using Handlebars logic.
+
+### JSON file example
+
+```json
+{
+  "configurations": {
+    "my.pid": {
+      "prop1": "value1",
+      "prop2": [1,2,3],
+      "prop3": true
+    }
+  },
+
+  "configurations:dev": {
+    "my.pid2": {
+      "prop1": "value-for-dev"
+    }
+  },
+
+  "configurations:publish,prod": {
+    "my.pid2": {
+      "prop1": "value-for-publish-prod"
+    }
+  }
+
+  "repoinit": [
+    "create path /repoinit/test1",
+    "create path /repoinit/test2"
+  ],
+  "repoinit:dev": [
+    "create service user dev-user"
+  ]
+}
+```
+
+The following keys are allowed on toplevel of the JSON file:
+
+* `configurations` - Configurations that are always active
+* `configurations:runmode` - Configurations that are active only for the given run mode.
+* `repoinit` - List of repoinit statements to be always applied
+* `repoinit:runmode` - List of repoinit statements to be applied for the given run mode.
+
+`runmode` can be a comma-separate strings, e.g. `prod,publish`. In this case all given run modes have to be active. On AEM as a Cloud Service, only the [officially supported run modes][aemaacs-runmodes] are allowed.
+
+
+[sling-provisioning]: https://sling.apache.org/documentation/development/slingstart.html
+[sling-repoinit]: https://sling.apache.org/documentation/bundles/repository-initialization.html
+[sling-configuration-installer-factory-cfg-json]: https://sling.apache.org/documentation/bundles/configuration-installer-factory.html#configuration-files-cfgjson
+[aemaacs-runmodes]: https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/implementing/deploying/overview.html?lang=en#runmodes