Migrating Classic UI properties to the New Edge UI

In Apigee Edge for Private Cloud 4.54.00, the Classic UI (the edge-ui component) is removed and no longer available. The New Edge UI (the edge-management-ui component) is the only UI for Edge for Private Cloud.

You cannot use edge-ui in Edge for Private Cloud 4.54.00. If you customized the Classic UI by setting properties in /opt/apigee/customer/application/ui.properties, the New Edge UI doesn't read that file. After you update to 4.54.00, you must set the equivalent properties in /opt/apigee/customer/application/management-ui.properties.

This page lists the Classic UI properties documented for ui.properties, the equivalent properties for the New Edge UI, and the Classic UI properties that aren't supported in the New Edge UI.

The New Edge UI uses the same code with config (CwC) mechanism as other Edge components. For more information, see How to configure Edge.

Compare Classic UI and New Edge UI configurations

The New Edge UI replaces the Classic UI component, properties file, service name, default port, and TLS certificate format. Review the following table to update your automation scripts, firewall rules, and TLS files before migrating your properties:

Setting Classic UI (4.53.01 and earlier) New Edge UI (4.54.00)
Component name edge-ui edge-management-ui
Properties file /opt/apigee/customer/application/ui.properties /opt/apigee/customer/application/management-ui.properties
Restart command apigee-service edge-ui restart apigee-service edge-management-ui restart
Default port 9000 3001
TLS configuration Java keystore (JKS) file PEM certificate and key files. See Configure TLS for the New Edge UI.

Set properties for the New Edge UI

Set New Edge UI configuration properties in /opt/apigee/customer/application/management-ui.properties and restart the edge-management-ui service so your changes take effect.

To set a property for the New Edge UI:

  1. Open the management-ui.properties file in an editor. If the file doesn't exist, create it: 
    vi /opt/apigee/customer/application/management-ui.properties
  2. Set the property. For example: 
    conf_uebe_disableGeoMap=true
  3. Save your changes.
  4. Make sure the file is owned by the apigee user: 
    chown apigee:apigee /opt/apigee/customer/application/management-ui.properties
  5. Restart the New Edge UI: 
    /opt/apigee/apigee-service/bin/apigee-service edge-management-ui restart

Follow these formatting rules when you set properties for the New Edge UI:

  • Property names are case-sensitive. For example, conf_uebe_disableGeoMap is valid, but conf_uebe_disablegeomap isn't.
  • Enclose string values in double quotation marks, for example conf_uebe_branding_companyNameShort="My Company".
  • Don't enclose boolean values (true or false) or numeric values in quotation marks. If a boolean or numeric value is enclosed in quotation marks, the New Edge UI doesn't start.

To check the current value of a property, use the -search option. For example:

/opt/apigee/apigee-service/bin/apigee-service edge-management-ui \
  configure -search conf_uebe_disableGeoMap

Map Classic UI properties to the New Edge UI

The following tables map each supported Classic UI property in ui.properties to its equivalent New Edge UI property in management-ui.properties. The Default column shows the default value in the New Edge UI.

Configure feature properties

Map Classic UI feature flags to the corresponding conf_uebe_* properties in management-ui.properties:

Classic UI property New Edge UI property Default Notes
conf_apigee_apigee.feature.disablegeomap conf_uebe_disableGeoMap false Set to true to hide Geo Maps. In the Classic UI for Edge for Private Cloud, Geo Maps were disabled by default. If you haven't enabled geo aggregation, set this property to true. See Enabling geo aggregation and geo maps.
conf_apigee_apigee.feature.disablepasswordreset conf_uebe_disablePasswordReset false Set to true to hide the Reset password link on the login page.
conf_apigee-base_apigee.feature.enableforcerangelimit conf_uebe_enableForceRangeLimit true Set to false to allow custom reports for a date range of more than 14 days.
conf_apigee-base_apigee.feature.enabletraceforinternaladdresses conf_uebe_trace_for_internal_addresses false Set to true to allow the Trace tool to send requests to local or internal IP addresses.
conf_apigee-base_apigee.feature.enableopenapiforinternaladdresses conf_uebe_openapi_for_internal_addresses false Set to true to allow OpenAPI specifications to be imported from local or internal IP addresses.
conf_apigee-base_apigee.feature.enablewsdlforinternaladdresses conf_uebe_wsdl_for_internal_addresses false Set to true to allow WSDL files to be imported from local or internal IP addresses.

Configure session and TLS properties

Map Classic UI session timeout and TLS properties to their New Edge UI equivalents in management-ui.properties:

Classic UI property New Edge UI property Default Notes
conf_application_session.maxage conf_uebe_authsessiontimeout 12 (hours) Time after which a user session expires after login. Specify a number of hours (for example, 12 or 0.5) or a duration with the h (hours) or m (minutes) unit (for example, 24h or 90m). The values 12 and 12h are equivalent. The d (days) unit isn't supported; for example, replace 1d with 24h. If the value isn't valid, the default of 12 hours is used and no error is reported. Applies to sessions that use basic authentication.
conf_application_session.secure None required Not applicable The New Edge UI sets the Secure flag on session cookies automatically when TLS is enabled (conf_uebe_usehttps=true) or when TLS terminates on a load balancer (conf_uebe_tlsoffload=true).
conf/application.conf+trustxforwarded conf_uebe_usehttps=true and conf_uebe_tlsoffload=true false Set both properties when TLS terminates on a load balancer. The load balancer must forward requests to the New Edge UI over HTTP and set the X-Forwarded-Proto header. The configure-ssl command sets these properties when MANAGEMENT_UI_SCHEME=https and MANAGEMENT_UI_TLS_OFFLOAD=y. See Configure TLS for the New Edge UI.
conf/application.conf+play.ws.ssl.loose.acceptAnyCertificate conf_uebe_skipverify false Set to true only if the Management Server uses a self-signed certificate. See Configuring TLS for the management API.

Configure email properties and templates

Map Classic UI email sender, subject, branding, host URL, and link expiration properties to the New Edge UI:

Classic UI property New Edge UI property Default Notes
conf_apigee_apigee.mgmt.mailfrom conf_apigee_apigee.mgmt.mailfrom Apigee <sales@apigee.com>, or the value of SMTPMAILFROM specified at install time Unchanged.
conf_apigee-base_apigee.emails.passwordreset.subject conf_apigee_apigee.emails.passwordReset.subject Password Reset Request Note the camelCase passwordReset property segment.
conf_apigee-base_apigee.emails.useraddedexisting.subject conf_apigee_apigee.emails.userAddedExisting.subject You Have Been Added to an Organization {organization} Note the camelCase userAddedExisting property segment.
conf_apigee-base_apigee.emails.useraddednew.subject conf_apigee_apigee.emails.userAddedNew.subject An Account Has been Created for You at {companyNameShort} Note the camelCase userAddedNew property segment.
conf_apigee_apigee.branding.companynameshort conf_uebe_branding_companyNameShort Apigee Sets the value of the {companyNameShort} placeholder in email subjects and templates.
conf_apigee_apigee.emails.hosturl conf_apigee_apigee.emails.hosturl None Unchanged. If not set, password reset links use the URL of the New Edge UI that was specified at install time, and user invitation links use the host name of the request. Set this property if users access the New Edge UI through a load balancer or a DNS name, for example conf_apigee_apigee.emails.hosturl="https://ui.mycompany.com".
conf_apigee_apigee.forgotpassword.emaillinkexpiryseconds conf_apigee_apigee.forgotPassword.EmailLinkExpirySeconds 600 Applies to password reset links and user invitation links.

The New Edge UI uses built-in email templates. To use the templates that you customized for the Classic UI:

  1. Create the /opt/apigee/edge-management-ui/email-templates directory.
  2. Copy your customized password-reset.html, user-added-existing.html, and user-added-new.html files from the backup directory you created before updating (for example, /opt/apigee/customer/backup/) to /opt/apigee/edge-management-ui/email-templates. The template file names and placeholders are the same as in the Classic UI.
  3. Make sure the directory and files are owned by the apigee user.
  4. Restart the New Edge UI.

For more information, see Customizing Edge email templates.

Configure auto-generated password properties

Map Classic UI auto-generated password properties to the New Edge UI:

Classic UI property New Edge UI property Default
conf_apigee-base_apigee.forgotPassword.underscore.minimum conf_apigee_apigee.forgotPassword.underscore.minimum 0
conf_apigee-base_apigee.forgotPassword.specialchars.minimum conf_apigee_apigee.forgotPassword.specialchars.minimum 0
conf_apigee-base_apigee.forgotPassword.lowecase.minimum conf_apigee_apigee.forgotPassword.lowecase.minimum 0
conf_apigee-base_apigee.forgotPassword.uppercase.minimum conf_apigee_apigee.forgotPassword.uppercase.minimum 0

Configure Management Server connection and shared secret properties

Map Classic UI Management Server connection, credential, and application secret properties to the New Edge UI:

Classic UI property New Edge UI property Notes
conf_apigee_apigee.mgmt.baseurl mgmt_baseurl URL of the management API, for example https://FQ_domain_name:port/v1. This property name doesn't start with conf_. If the Management Server uses a self-signed certificate, also set conf_uebe_skipverify=true.
conf_apigee_apigee.mgmt.credential conf_uebe_mgmtCredential Encrypted sysadmin credentials. You must encrypt the credentials again for the New Edge UI using ./bin/management-ui --encrypt; see Configuration required for different sysadmin credentials.
conf_apigee_mail.smtp.credential conf_apigee_mail.smtp.credential Encrypted SMTP credentials.
conf_application_application.secret conf_uebe_applicationsecret Secret used to encrypt credentials and session cookies. Generated at install time.

Remove Classic UI properties that require no action

The following Classic UI properties have no equivalent in the New Edge UI because the behavior is always enabled. Don't include these properties in management-ui.properties (and remove them from any automated configuration scripts):

Classic UI property Behavior in the New Edge UI
conf_apigee_apigee.feature.expireSessionCookiesInternally Session expiry is always validated on the server.
conf_apigee_apigee.feature.trackSessionCookies Session information is always stored in server memory. If you use multiple instances of the New Edge UI behind a load balancer, configure the load balancer to use sticky sessions.

Remove unsupported Classic UI properties

The following Classic UI properties aren't supported and have no equivalent in the New Edge UI. Don't include these properties in management-ui.properties (and remove them from any automated configuration scripts):

Classic UI property Description
conf_apigee_apigee.feature.apitimeout, conf_apigee_play.ws.timeout.idle, conf_apigee_play.ws.timeout.connection The timeout for management API calls isn't configurable in the New Edge UI.
conf_application_http.proxyhost, conf_application_http.proxyport, conf_application_http.proxyuser, conf_application_http.proxypassword The New Edge UI doesn't support a forward proxy for Trace tool requests.
conf_apigee-base_apigee.feature.enableconsentbanner, conf_apigee-base_apigee.consentbanner.buttoncaption, conf_apigee-base_apigee.consentbanner.body The consent banner isn't supported in the New Edge UI.
conf_apigee-base_apigee.feature.apiproxypaginationenabled, conf_apigee-base_apigee.pagination.apiproxypaginationbatchsize In the New Edge UI, the API proxy list is always loaded in pages. The page size isn't configurable.
conf_logger_settings_application_log_level, conf_logger_settings_play_log_level, conf_application_logger.application The log level isn't configurable in the New Edge UI. Log files are written to /opt/apigee/var/log/edge-management-ui.
bin_setenv_min_mem, bin_setenv_max_mem, bin_setenv_meta_space_size, bin_setenv_ext_jvm_opts The New Edge UI doesn't run in a Java virtual machine. Java memory settings don't apply.

Review a migration example

The following example compares a Classic UI ui.properties file with the equivalent management-ui.properties file for the New Edge UI.

Classic UI, /opt/apigee/customer/application/ui.properties:

conf_apigee_apigee.feature.disablegeomap=false
conf_apigee-base_apigee.feature.enabletraceforinternaladdresses="true"
conf_application_session.maxage="1d"
conf_apigee-base_apigee.emails.passwordreset.subject="Reset your My Company password"
conf_apigee_apigee.branding.companynameshort="My Company"
conf_apigee_apigee.emails.hosturl="https://ui.mycompany.com"

New Edge UI, /opt/apigee/customer/application/management-ui.properties:

conf_uebe_disableGeoMap=false
conf_uebe_trace_for_internal_addresses=true
conf_uebe_authsessiontimeout=24
conf_apigee_apigee.emails.passwordReset.subject="Reset your My Company password"
conf_uebe_branding_companyNameShort="My Company"
conf_apigee_apigee.emails.hosturl="https://ui.mycompany.com"

Note that the boolean value true isn't enclosed in quotation marks, and that the session timeout 1d is replaced with 24.

After you save the file, restart the New Edge UI:

/opt/apigee/apigee-service/bin/apigee-service edge-management-ui restart

Summary checklist

Use the following checklist to complete your migration to the New Edge UI in Apigee Edge for Private Cloud 4.54.00:

  1. Back up /opt/apigee/customer/application/ui.properties and any customized email templates from /opt/apigee/edge-ui/email-templates before upgrading.
  2. Add mapped properties to /opt/apigee/customer/application/management-ui.properties without quoting boolean or numeric values, and omit unsupported Classic UI properties.
  3. Copy customized email templates from your backup directory to /opt/apigee/edge-management-ui/email-templates.
  4. Re-encrypt sysadmin credentials with ./bin/management-ui --encrypt if you set conf_uebe_mgmtCredential.
  5. Set file ownership to apigee:apigee and restart edge-management-ui.