Custom OSGi Configuration in AEM

PublishedAugust 30, 2024

Viewed184 times

OSGi Configuration allow us to configure run-mode specific properties. All the out-of-the-box OSGi configurations are available at /system/console/configMgr while custom configurations can be created as per business requirements. These configurations are typically managed within the AEM project's ui.config module in the code repository.

To create a custom OSGi configuration, you need to define an interface that determines how the fields will appear configuration console.

AppConfig.java

@ObjectClassDefinition(
  name = "AEM Demo Application Configuration")
public @interface AppConfig {
  @AttributeDefinition(name = "App Name")
  String app_name();

  @AttributeDefinition(name = "API Endpoint")
  String api_endpoint();

  @AttributeDefinition(name = "App Client ID")
  String client_id();

  @AttributeDefinition(name = "App Client Secret")
  String client_secret();
}

Next, you need to create a service to read those configuration values.

AppConfigService.java

public interface AppConfigService {
  String getAppName();
  String getAPIEndpoint();
  String getClientIds();
  String getClientSecret();
}

AppConfigServiceImpl.java

@Component(service = AppConfigService.class)
@Designate(ocd = AppConfig.class)
public class AppConfigServiceImpl implements AppConfigService {
  private AppConfig appConfig;

  @Activate
  public void activate(AppConfig appConfig) {
    this.appConfig = appConfig;
  }
  
  @Override
  public String getAppName() {
    return appConfig.app_name();
  }

  @Override
  public String getAPIEndpoint() {
    return appConfig.api_endpoint();
  }

  @Override
  public String getClientId() {
    return appConfig.client_id();
  }

  @Override
  public String getClientSecret() {
    return appConfig.client_secret();
  }
}

To add your custom-developed OSGi configuration to AEM instance, place it in the ui.config / osgiconfig folder of your project. If the configuration values differ across environments or run modes, you should add separate configurations within the respective environment or run mode-specific folders like config.publish.dev, config.publish.stage, etc.

config / com.aem.demo.core.services.impl.AppConfigServiceImpl.cfg.json

{
  "app.name": "aem-demo",
  "api.endpoint": "https://www.google.com",
  "client.id": "8TfyfkUAB481AxOfn4UrqIyWIStKrTm8Jl",
  "client.secret": "8TxmpkXAPRtLiOHIFHzjx4uKHlm1soAvO7I"
}

You can check the configuration on your instance from here /system/console/configMgr.

OSGi Installer Configuration Printer

There are scenarios when OSGi properties and their value formats may not be well understood by the developer defining OSGi configurations in the AEM project, particularly for AEM-provided OSGi components.

In such cases, you can first locate the targeted OSGi configuration in /system/console/configMgr and modify its property values. Record the Persistent Identity (PID) which will be used to generate the OSGi configuration JSON.

Navigate to OSGi Installer Configuration Printer at /system/console/osgi-installer-config-printer. Paste the PID in the PID field that was copied in the previous step, ensure the Serialization Format is set to "OSGi Configurator JSON" and Select Print. The OSGi Configuration in JSON format will display in the Serialized Configuration Properties section.

Configuring OSGi for AEMaaCS

However, if you're using AEM as a Cloud Service, you can manage environment-specific variables directly within Cloud Manager and use them like below. For more information about Environment Variables and Secrets, please visit this link.

config / com.aem.demo.core.services.impl.AppConfigServiceImpl.cfg.json

{
  "app.name": "aem-demo",
  "api.endpoint": "$[env:API_ENDPOINT]",
  "client.id": "$[secret:CLIENT_ID]",
  "client.secret": "$[secret:CLIENT_SECRET]"
}

There are three varieties of OSGi configuration values that can be used with AEM as a Cloud Service.

Inline values: which are values that are hard-coded into the OSGi configuration and stored in Git, such as app.name.
Environment-specific values: which are values that vary between Development environments, and thus cannot be accurately targeted by run mode, particularly when multiple development environments are needed and share the same run mode.
Secret values: which are values that must not be stored in Git for security reasons, such as client.id and client.secret.

Additionally, /system/console/configMgr is not accessible in AEM Cloud environment. To view configuration values, you can use Developer Console instead.

Custom OSGi Configuration in AEM

OSGi Installer Configuration Printer

Configuring OSGi for AEMaaCS

Frequently Asked Questions (FAQ)

`osgiconfig` is not visible in AEM Cloud

Custom OSGi Configuration in AEM

OSGi Installer Configuration Printer

Configuring OSGi for AEMaaCS

Frequently Asked Questions (FAQ)

osgiconfig is not visible in AEM Cloud

`osgiconfig` is not visible in AEM Cloud