Basic Site Settings

Configure site settings such as site URL, contact email address, and themes.

Note: this section contains information about the configuration settings defined within the Akana API Platform, which apply to the entire developer portal.

For information about the configuration settings defined in the Akana Administration Console, which apply only to the specific container, refer to Admin Console Settings.

Table of Contents

  1. How do I configure site settings?
  2. What custom date formats does the platform support?
  3. How do I specify a custom date format?
  4. How do I add a theme?
  5. How do I extend a platform theme?
  6. How do I edit a theme?
  7. How do I delete a theme?
  8. How do I configure values for a theme?
  9. How do I manage security for a developer portal theme?
  10. How do I add security to a theme?
  11. What are the valid file types for the security certificate for a theme?
  12. How do I view the security certificate for a theme?
  13. How do I update the security for a theme?
  14. How do I download an existing certificate already assigned to a theme?
  15. How do I delete the certificate assigned to a theme?
  16. Lifecycle Manager: special instructions for running with MS SQL Server

How do I configure site settings?

API Platform Version: 8.3

Key values relating to your implementation of the developer portal, such as the contact email address used in emails and notifications sent out by the system, are generally set up as part of the Jython script that's run as part of installation. However, you might want to change one or more of these values later.

Some of these settings, you can configure in the Site Settings page.

You can also add or modify platform themes on this page.

This setting... Controls this feature...
Name

A friendly name for the tenant (can be more than one word), used in emails and notifications that are sent out by the system. It should reflect the name of your site.

Corresponds to the tenantName element in the installation Jython script.

Site Contact Email

The email address used in any "contact us" context for the developer portal, including certain emails and notifications that include contact information.

Corresponds to the contactEmailAddress element in the installation Jython script.

From Email

The email address displayed in the "From" field for email notifications sent out by the platform.

Corresponds to the fromEmailAddress element in the installation Jython script.

Limit forward proxy feature to allow only these hosts

Optional security feature. Default (*) means that Test Client will forward API calls to any valid host. When you specify one or more allowable hosts, Test Client will forward API calls only to these trusted hosts.

This setting also affects file upload in the developer portal. For example, if you specify trusted hosts, an API Admin can only upload an API description document from an external URL if the host is trusted. See How do I add an API using an API description document?

You can use any of the following formats, or a combination:

  • A specific hostname (example.com).
  • Multiple specific hostnames, comma-separated (example.com,example.org).
  • Asterisk used as a wild card with a domain and sub-domain (*.example.com).
  • Asterisk used as a wild card with domain/sub-domain and prefix (*.apiportal.example.com).
  • Host name without sub-domain and domain (ubu14234-9).
  • Asterisk used as a wild card to indicate any domain address (*). This is the default value.

Note: There is a setting in the Akana Administration Console relating to forward proxy hosts, and that field takes precedence over this one. It must be set to the default, * (allow all) in order for values specified in the developer portal site settings to apply. For information on the Akana Administration Console setting, see com.soa.atmosphere.forwardproxy.

Default Console Address

The full URL that will be used in the browser when accessing the developer portal user interface. The browser then redirects to the default login page.

Corresponds to the consoleAddress element in the installation Jython script.

Google Analytics Account ID To add Google Analytics automatically to your site pages, provide your Account ID.
Extended Properties and Workflow If enabled, properties defined for assets in the developer portal, such as apps and APIs, can be extended by modifying templates in an integrated Lifecycle Manager. For more information, see Using Custom Metadata on the Developer Portal. For information about special steps to take if you're using Lifecycle Manager with a SQL Server database, see Lifecycle Manager: special instructions for running with MS SQL.
Custom Date Format (8.4.8 and later) By default, the platform uses the browser's Locale setting to determine the date format. If needed, you can use this setting to override the platform default and specify a date format to be used for dates in the developer portal; for example, on API logs. For details of the supported date formats, see What custom date formats does the platform support?
Themes

Current themes for the tenant are displayed. You can:

  • Add a theme: click Add Theme. See How do I add a theme?
  • Edit a theme: On the line for the theme you want to edit, click the Actions arrow at the right and choose Edit Theme. See How do I edit a theme?
  • Delete a theme: On the line for the theme you want to delete, click the Actions arrow at the right and choose Delete Theme. See How do I delete a theme?
To configure site settings:
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. Change the settings as needed. For explanations of your choices, refer to the table above.
  4. When done, click Save.

Back to top

What custom date formats does the platform support?

API Platform Version: 8.4.8 and later

The platform supports the date formats shown below. To enter a custom date format in the Site Settings, just type, or copy and paste, and then click Save. See How do I specify a custom date format? below.

Note: Do not specify the hours, minutes, and seconds. The platform adds those automatically. Just specify the date format.

Supported date and time patterns:

  • yy = short year
  • yyyy = long year
  • M = month (1-12)
  • MM = month (01-12)
  • MMM = month abbreviation (Jan, Feb ... Dec)
  • MMMM = long month (January, February ... December)
  • d = day (1 - 31)
  • dd = day (01 - 31)
  • ddd = day of the week in words (Monday, Tuesday ... Sunday)

Examples:

  • dd/MM/yyyy = 31/08/2017
  • M/d/yy = 8/31/17

Note: When you change the date format, browser restart is needed for the change to take effect.

Back to top

How do I specify a custom date format?

API Platform Version: 8.4.8 and later

The platform displays dates in several places; for example:

  • In the title bar under Last Logged In
  • In the Dashboard and Forum, for forum entries
  • In app and API analytics (charts and logs)

By default, the platform takes the date format based on the locale setting for the user's browser; so, for example, on 7 September 2017, with the US setting (en-us), the Last Logged In date would show as 7/9/17, and with the UK setting (en-gb) it would show as 9/7/17. The location of this setting varies by browser; for example, in Mozilla Firefox, it's in Options > Content > Languages. Generally, browser restart is needed for a change to take effect.

The platform includes a setting that allows the Site Admin to override the browser default, so that the date format displayed in the developer portal is consistent for all users.

To specify a custom date format:
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. In the Custom Date Format field, type the new format. For a list of supported formats, see What custom date formats does the platform support?
  4. When done, click Save.

Notes:

  • Do not specify the hours, minutes, and seconds. The platform adds those automatically. Just specify the date format.
  • The developer portal converts the time zone specified for the operating system into the local browser time format.
  • If the date format specified in the browser locale (language) settings doesn't match one of the date format supported ( see What custom date formats does the platform support?), the format used in the developer portal defaults to MM/dd/yy HH:mm, the standard US date format.
  • Browser restart is needed for a change in date format to take effect.

Back to top

How do I add a theme?

API Platform Version: 8.3

You can add one or more themes in the Site Settings page.

To add a theme:
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, click Add Theme.
  4. Specify settings (for help with field values, see How do I configure values for a theme? below):
    • Choose Standard Theme (hermosa, simpledev. or default), or Custom Theme (specify a custom theme name, and then specify the standard theme that it's based on).
    • Specify one or more comma-delimited virtual hosts for the theme.
    • Specify the full console address for the theme, including trailing backslash.
    • Specify the site title. This is important for SEO rankings.
    • Specify the site meta description.
  5. Click Finish.
  6. On the Site Settings page, click Save to confirm.

Back to top

How do I extend a platform theme?

API Platform Version: 8.5

The developer portal has three out-of-the-box standard themes: Default Theme, Simple Dev, and Hermosa.

You can extend a standard theme by defining one or more custom themes based on the same standard theme. By doing this, you can have two or more instances of the same platform theme, each with its own URL and potentially each with a different set of user-defined customizations. Each instance uses the same database.

You can use this to define multiple access points into the platform, each with its own set of customizations applied via the custom.less file.

Sample scenario illustrating multiple customizations of look and feel:

Tenant ACMEPayments Corp has 10 partners; each partner has a different API on the platform, and each has an API admin who accesses the platform and exports metric information for the API.

When installing, the Site Admin defines ten custom themes, each based on Hermosa theme, each named for one of the 10 partners, and each with a different URL that includes the tenant name and partner name.

After defining one or more custom themes, the Site Admin applies the customization by uploading a custom.less file for each partner with the partner's company colors and logo.

When each API Admin logs in via the URL for his company, he sees the colors and logo for his company.

Notes:

Back to top

How do I edit a theme?

API Platform Version: 8.3

You can edit a theme in the Site Settings page.

To edit a theme:
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Edit Theme.
  5. In the Edit Theme overlay, modify settings as needed. For help with field values, see How do I configure values for a theme? below.
  6. Click Finish.
  7. On the Site Settings page, click Save to confirm the change.

Back to top

How do I delete a theme?

API Platform Version: 8.3

You can delete a theme in the Site Settings page.

To delete a theme:
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Delete Theme.
  5. From the Site Settings page, click Save to confirm the deletion.

Back to top

How do I configure values for a theme?

API Platform Version: 8.3

In Site Settings, you can add, edit, or delete a theme.

The values in the Add/Edit Theme overlay are explained below.

Add/Edit Theme Settings
Field Description
Theme: Standard Standard themes are out-of-the-box themes that ship with the product; however, they must be specifically installed.
Theme Name

If you choose Standard Theme, choose a name out of the list of out-of-the-box themes available: simpledev, hermosa, or default.

Note: If the theme you want is not available for selection, ask the System Administrator to install it.

Theme: Custom

Naming a custom theme allows you to define a new theme, based on an out-of-the box theme. You can then apply customization to the custom theme without affecting the out-of-the-box theme itself. Choose a simple theme name without spaces or special characters.

Theme Name

Custom themes allow you to have a different branding on a different virtual host for the same theme. The custom theme name is used in the path of the uploaded resources for the theme. If you choose Custom Theme, specify the out-of-the-box theme it will be based on. Available choices: hermosa, simpledev, or default.

Virtual Hosts / Vanity Hostnames A comma-delimited list of all hostnames that will be used to access the site (for example, vanity.example.com,other.example.com). The system uses these hostnames to determine which theme to present. In your DNS system, make sure there is an A record or CNAME record for each virtual hostname, and that it points to your system.
Console Address The full URL for the site. As well as browser access, the console address is used in links to the site in various emails and notifications. Must be a full URL, including scheme, hostname, context path, and trailing forward slash; for example, https://vanity.example.com/site/.
Site Title The page title for the site. This is the most important on-page SEO element, and typically appears in the browser tab and search engine results. Place relevant keywords first in the title, with branded information at the end. Keywords earlier in the title are given greater importance and will positively impact your organic rankings and traffic. Page titles should ideally be no more than 60 characters long to ensure they're not truncated on desktop, mobile, and tablet searches.
Site Meta Description The meta description for the site. This is used by search engines. The description should lead with an explanation of what the site is about, followed by a call to action. It should be no more than 155 characters so that it isn't truncated in search results.

Back to top

How do I manage security for a developer portal theme?

API Platform Version: 8.5 and later

For added site security, you can upload and assign a PKCS12 security certificate and assign it to your developer portal theme. When you add your own certificate, it's presented (by SNI) to your tenant accessing the developer portal.

You can:

Note: Before uploading the security certificate and assigning it in the developer portal, you must define it in Policy Manager so that trust is established. For instructions, see Import CA Certificate (Policy Manager help).

If you get the below error message, you'll need to first set up an HTTPS listener in Policy Manager, the underlying infrastructure:

No available HTTPS listeners.

To set up the listener, see Adding a Listener (Policy Manager help).

Back to top

How do I add security to a theme?

API Platform Version: 8.5

Once you've added a site theme, you can upload a certificate to add security to the theme.

Note: The certificate must first be uploaded in Policy Manager so that it's established as a trusted certificate. For instructions, see Import CA Certificate (Policy Manager help).

In general, changes that you make to a theme aren't saved until you click Save; however, certificates are an exception. When you upload the security certificate, it's attached to the theme immediately.

Adding a certificate for a site theme

To add a certificate to a theme
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Upload Certificate. The Import Private Key + X.509 Certificate from Keystore overlay appears.
  5. Import the key/certificate file that you want presented (by SNI) to your tenant:
    • Browse to the keystore file and upload it.
    • If the keystore file is passworded, enter the password.
    • Enter the key alias.
    • Enter the key password.
  6. Click Finish. The key/certificate information is added to the theme immediately, and the Site Settings page is updated to display the security icon for the theme, as shown below.

    Site security icon

  7. In the Site Settings page, click Save.

Back to top

What are the valid file types for the security certificate for a theme?

API Platform Version: 8.5

The security certificate for a site theme must be one of these file types:

  • PKCS; for example, file extension p12.
  • JKS; for example, file extension .jks.

Note: The certificate file alone is not enough; you must upload the keystore file. Also note that the certificate must first be uploaded in Policy Manager so that it's established as a trusted certificate. For instructions, see Import CA Certificate (Policy Manager help

Back to top

How do I view the security certificate for a theme?

API Platform Version: 8.5

You can quickly review the plain-text details of the security certificate for a specific theme, in the Site Settings page.

To view the security certificate for a theme
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, find the security icon for the theme, as shown below, and click it.

    Site security icon

  5. Review the certificate. An example is shown below.

    Viewing the certificate for a theme

  6. When done, click OK to close the View Certificate page.

Back to top

How do I update the security for a theme?

API Platform Version: 8.5

Once you've uploaded the security certificate for a theme, you can edit the certificate (upload a different one), download it, or delete it.

Note: If you're updating the certificate, make sure that the new certificate has been uploaded in Policy Manager so that it's established as a trusted certificate. For instructions, see Import CA Certificate (Policy Manager help).

To update the certificate for a theme
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Edit Certificate, as shown below.

    Site security options

  5. In the Import Private Key + X.509 Certificate from Keystore overlay, import the new key/certificate file:
    • Browse to the keystore file and upload it.
    • If the keystore file is passworded, enter the password.
    • Enter the key alias.
    • Enter the key password.
  6. Click Finish. The key/certificate information is updated immediately.
  7. In the Site Settings page, click Save.

Back to top

How do I download an existing certificate already assigned to a theme?

API Platform Version: 8.5

You might need to download the certificate that's been assigned to a theme; for example, for backup. Follow the steps below.

To download the certificate for a theme
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Download Certificate.
  5. Choose whether to open or save the file, and specify application (for Open) or location (for Save). The default filename is certificate.cer.

Back to top

How do I delete the certificate assigned to a theme?

API Platform Version: 8.5

Most values associated with a site theme are updated only when you click Save on the Site Settings page. However, when you make changes to security keys/certificates, the changes are effective immediately. Deleting the security certificate for a site theme removes a layer of security; be sure that you want to perform this action. If you're planning to add a new certificate, you could leave the existing certificate in place and then just upload the new one, to ensure there is no lapse in site security; see How do I update the security for a theme?

To delete the certificate for a theme
  1. Log in as the Site Admin and go to the Admin section.
  2. Go to Site.
  3. At the bottom, in the Themes section, find the theme.
  4. To the right of the line, click the Actions icon and choose Delete Certificate.
  5. At the confirmation message, click OK. The certificate is no longer associated with the theme.
  6. In the Site Settings page, click Save.

Back to top

Lifecycle Manager: special instructions for running with MS SQL

When the API Platform is using a Microsoft SQL Server database, when you initially enable the option in the Site Settings (see Extended Properties and Workflow), this action fails to create the backing Lifecycle Manager library for the tenant.

To address this issue, you'll need to enable a setting in the Akana Administration Console for the container, before enabling the Extended Properties and Workflow site setting. Follow the steps below.

To enable synchronization of Lifecycle Manager data in the Akana Administration Console
  1. In the Akana Administration Console, on the Configuration tab, under Configuration Actions, choose Synchronize Lifecycle Manager Data. The wizard opens.
  2. Enter the name of a specific tenant, or leave empty for all tenants, and run the configuration action.
  3. When done, click Finish.

For more information on running this configuration action, see Synchronize Lifecycle Manager Data (Admin Console documentation).

Back to top