This is documentation for Apprenda 7 and 8.
Documentation for older versions are also available.

Custom Properties

Custom Properties are (in most cases) Platform Operator-defined tags that can be applied to Platform objects to govern behavior. They can be assigned and referenced in order to help asset management and reporting, as well as (in conjunction with Application Deployment Policies) to configure how deployment decisions are made. Custom Properties can be applied to guest applications, application components, Infrastructure servers and SQL nodes, Resource Policies, and Storage Quotas.

Viewing Custom Properties

To view, modify, or add Custom Properties, navigate to the Configuration>Custom Properties page in the SOC.

If any Custom Properties have already been created for your Platform, they will appear in the list here, along with corresponding definition info.

Create Custom Properties

To create a new Custom Property, click the New Custom Property button in the upper right. 

This will open a New Custom Property window. In the first page, you can enter General Settings for the new property.

  1. fill in a Name and Display Name for the new property. Display Name is how the property will appear on the Custom Properties settings pages of Apprenda objects. Both name and display name should be unique.

If you are creating a Custom Property that will apply Kubernetes pods, the name of the property should conform to Kubernetes naming conventions. If it does not, the Platform may change the setting name so that the pod will deploy with a valid Kubernetes label.

  1. add a Description for what the property does

  2. fill in the Allowed Value(s) for the property. Different values should be separated with a comma (,). If there is no set values for the property or additional values to what you have entered as allowed values, select Allow custom Value(s). For Custom Properties settings pages of Apprenda objects the property appears on, the values will appear in descending order based on the left-to-right order in which you enter them here

  3. check of all categories this property Applies To. Applying the Custom Property to each of these objects means that the property will appear on that object's Custom Properties settings page, and the value it's set to will be referenced by any processes that use that specific Custom Property. Specific application components aren't available to be selected at this point, but if you choose "Applications" on the Applies To list here, you will be able to apply the Custom Property to individual application components later in the property creation process

If you plan to use the Custom Property as the Source Property for an Application Deployment Policy, the property must be applied to "Servers" as well as to at least one additional object in order to allow comparison for deployment decisions.  For more information on creating Application Deployment Policies, see this documentation
  1. checking a category's Allow Multi-Select box will allow multiple values to be set for the Custom Property for that object type. In this case, check boxes will appear next to the property's allowed values instead of the values being offered in a dropdown list (and an input box for custom values will also appear if the "Allow custom Value(s)" box is checked).  Also, if both "Multi-Select" and custom values are allowed, you will be able to input multiple custom values when setting the value for this Custom Property.

Click Next. If you set allowed values, you will see the Default Value page.

On the Default Value page, you can set the default value for this property from the drop down list. If you selected "Allow Multi-Select", in the previous page you can choose multiple Default Values by checking the boxes that appear next to the allowed values in place of a dropdown list. This ensures that every Platform object that the Custom Property applies to will inherit the default value(s) as the initial setting for the Custom Property.  Selecting "No Default", means no initial value will be set.

Click Next when you have completed setting the default. If you selected "Applications" for the "Applies To" setting, you will be shown the Application Settings page (if not, you will move directly to the Custom Property summary display).

On the Application Settings page, you can choose how the Custom Property will be applied to guest applications, as well as how (or if) the setting will appear to Development Teams during the application creation and deployment process.

  1. Under the Scope heading,

    • select Application Level if you want the Custom Property to apply to applications as a whole, and therefore to each individual component associated with that application.
    • select Application Component Level if you want to choose specific application components (User Interfaces, Services, Windows Services, Java Web Applications, Databases, Pods) to apply the Custom Property.

Since an application's individual components inherit any Custom Property setting applied to the application as a whole, a Custom Property cannot be applied to both "Application Level" and "Application Component Level" at the same time.  In order to eliminate conflicts between property settings, the "Scope" levels are mutually exclusive.

Note that Custom Properties that apply to pods will be represented as Kubernetes labels when the pod is deployed. To avoid naming conflicts with other labels in the cluster, Custom Properties will be created as labels with the prefix "custom-property.apprenda.com-" on the pod.

  1. Under the Developer Visibility heading,

    • select Visible to Developers if you want the Custom Property to appear on the application or component's Custom Properties settings page in the Developer Portal. If this is not set, the setting won't be visible to Developers in the Developer Portal
    • if the setting is visible to Developers, you can choose that the property be Required for Deployment, which will mean that a value must be set for that Custom Property setting before the application or component it applies to before that application/component can be deployed.  Additionally, you can make the property setting Editable by Developers, which will allow Developers to assign a value or change it from its default. If this option is unchecked, the value will appear as a read-only property on the Custom Properties settings page.

Click Next after these final steps in the Custom Property creation process. A summary window containing an overview of the Custom Property will appear.  Click Finish to create the property. The setting will now appear on the Custom Properties list, along with its Description and a list of the Apprenda objects that the property applies to.

On this page, you can choose how the Custom Property will be applied to guest applications, as well as how (or if) the setting will appear to Development Teams during the application creation and deployment process.  Under the Scope heading, selecting Application Level will cause the Custom Property to apply to applications as a whole, and therefore to each individual component associated with that application.  Selecting Application Component Level, however, will allow you to select specific application components (User Interfaces, Services, Windows Services, Java Web Applications, Databases) to which to apply the Custom Property.

Please Note: Since an application's individual components inherit any Custom Property setting applied to the application as a whole, a Custom Property cannot be applied to both "Application Level" and "Application Component Level" at the same time.  In order to eliminate conflicts between property settings, the "Scope" levels are mutually exclusive.

Next, you can customize the Developer Visibility options relating to the property's appearance on application or application component Custom Properties settings pages.  Selecting Visible to Developers will cause the Custom Property setting to appear on the application or component's Custom Properties settings page when it's viewed through the Developer Portal; otherwise, the setting won't be visible there.  With that option enabled, you can choose that the property be Required for Deployment, which will mean that a value must be set for that Custom Property setting before the application or component it applies to before that application/component can be deployed.  Additionally, you can make the property setting Editable by Developers, which will allow Developers to assign a value or change it from its default.  If this option is unchecked, the value will appear as a read-only property on the Custom Properties settings page.

Custom Property Groups

In addition to creating individual Custom Properties, Platform Operators are able to collect these properties into Custom Property Groups so that related properties can be managed through a single workflow.  When Custom Properties are part of a Custom Property Group, they are "turned on" or "turned off" as one through a group setting, and Platform Operators have the option of allowing Development Teams to switch on or off the Custom Properties in the group in the same way.  When a Custom Property Group is "turned on" (or "Enabled") for a given Apprenda Platform object, its child Custom Properties are applied normally to that object, but when the group is "turned off" (or "Disabled"), its child properties are treated by that object as if they don't exist, and they won't affect deployments or be available to be assigned/edited.

Additionally, when creating Application Deployment Policies or Application Bootstrap Policies, Custom Property Groups can be selected for comparison logic in place of individual Custom Properties, meaning the comparison logic will use the group's Enabled/Disabled setting value for matching.

To create a new Custom Property Group, from the Custom Properties page, click the New Custom Property Group button in the upper right.  This will open a New Custom Property Group window:

Enter a Name for the new group, as well as a Display Name, which defines how the group will appear on the Custom Properties settings pages of Apprenda objects.  Optionally, add a Description

Next, choose the Default Behavior for the group by checking or un-checking the Group is Enabled by Default box.  When this box is checked, all of the group's child Custom Properties will by default be "turned on" and will be treated normally by the Platform.  When the box is not checked, the group's child properties will by default be "turned off" and treated by the Platform as if they don't exist.  Depending on which other settings are applied to the Custom Property Group, Development Teams may have the ability to change this default behavior for their guest applications or application components.

After that, select any desired objects in the Applies To list.  Choose exactly the same set of "Applies To" objects as that of the Custom Properties you want to select as part of the group; if the "Applies To" list of objects for a Custom Property is different from the list for the group you're creating, you won't be able to assign that Custom Property to the group.

When your selection has been made, click Next.  If you selected "Applications" for the "Applies To" setting, you will be shown the Application Settings window (if not, you will move directly to the Property Selection screen):

On this screen, you can choose how the Custom Property Group will be applied to guest applications, as well as how (or if) the setting will appear to Development Teams during the application creation and deployment process.  Under the Scope heading, selecting Application Level will cause the Custom Property Group to apply to applications as a whole, and therefore to each individual component associated with that application.  Selecting Application Component Level, however, will allow you to select specific application components (User Interfaces, Services, Windows Services, Java Web Applications, Databases) to which to apply the Custom Property Group.  As with the "Applies To" section in the previous screen, the selection you make in the "Scope" section must be identical to that of any Custom Properties you'd like to make a part of this group.

Next, you can customize the Developer Visibility options relating to the group's appearance on application or application component Custom Properties settings pages.  Selecting Visible to Developers will cause the Custom Property Group setting to appear on the application or component's Custom Properties settings page when it's viewed through the Developer Portal; otherwise, the setting won't be visible there.  With that option enabled, you can make the property setting Editable by Developers, which will allow Developers to change the value from its default (the only values to choose from will be "Enabled" and "Disabled").  If this option is unchecked, the value will appear as read-only on the Custom Properties settings page.  Depending on whether the Custom Property Group setting is set to "Enabled" or "Disabled" on an app/app component Custom Properties settings page, that group's child Custom Properties may or may not also become visible/editable on the settings page (depending on individual Custom Property settings).

Click Next again to be taken to the Property Selection screen:

On this screen you can choose which existing Custom Properties to add to the Custom Property Group.  Only Custom Properties that are not already part of another group and that have the same scope as what was selected for this Custom Property Group on the previous screens will appear in the list of Available Properties within Scope.  Select one or more Custom Properties, then click the right arrow button to move those properties to the Selected Properties to Group list (you can also unselect properties by highlighting them in the Selected Properties to Group list and clicking the left arrow button).

After selecting which Custom Properties to include in the group, click Next once again.  A summary window containing an overview of the Custom Property Group will appear.  Click Finish to create the group; you will now see it appear on the Custom Properties list, along with its Description and a list of the Apprenda objects that the property Applies To:

Managing Custom Properties & Custom Property Groups

A Custom Property or Custom Property Group can be updated by clicking the corresponding Edit button to the right. It can also be removed by choosing the Delete option from the dropdown menu to the right of the Edit button. 

A Custom Property or Group can't be edited while it's being referenced by an active Application Deployment Policy.  If you want to edit a Custom Property or Group that is being referenced, first set any Application Deployment Policies that reference the property as "Inactive" (see more information here). If you want to delete a Custom Property or Group, it must not be referenced by any Application Deployment Policy, active or inactive. The Custom Property or Group must be removed from all referencing Application Deployment Policies before it can be deleted.

Depending on which Platform objects your Custom Property or Group has been applied to, the property will now appear in those objects' Custom Properties settings pages.  To view the Custom Properties settings page of a server or SQL node, navigate to the Infrastructure page in the SOC via the link in the top menu bar.  Click the name of the desired server or database node to go to that target's overview page; on the upper left of the page, in the Details box, click the View Custom Properties link.  Click the Show all available custom properties link on the resulting window to expand the list of available Custom Properties and Custom Property Groups:

From this view, you can assign values for each of the listed Custom Properties/Groups to the target server or database node.  Any Custom Properties/Groups you've created that have been set to apply to servers will appear here, as well as several properties that correspond to applications' or app components' inherent properties.  For example, any application deployed on the Platform will possess a specific Application Service level, a specific Deployment Stage that it has arrived at, and a specific Development Team Alias for the Dev Team responsible for creating it.  On a per-application level, these properties are set by the state of the application itself, but the related server settings can be customized by the Platform Operator. 

Custom Properties server settings that correspond to inherent application properties can be useful when, for example, an Application Deployment Policy is set to compare an inherent property of an application to that corresponding Custom Properties server setting in order to select a target for deployment (see more about creating Application Deployment Policies). Clicking the pencil icon to the right of a property will allow you to edit it.  For the Application Service settings (Authentication, Authorization, and Multi-tenancy) you can select True or False, for Deployment Stage you can select either Sandbox, Published, or both, and for Development Team Alias you can input a name.  If any created Custom Properties/Groups appear here, their possible values will depend on the settings that each property was given.

Similar to how a server's Custom Properties settings page can be accessed, a Resource Policy or Storage Quota's Custom Properties settings page can be viewed by navigating to the Resource Policies page in the SOC (via the Configuration link in the top menu bar).  The info box for each Resource Policy and Storage Quota listed here contains a View Custom Properties link that corresponds to that Policy or Quota; click the appropriate link to view the Custom Properties settings page for the desired object.  The available settings will be identical to a server/database node's, with possible exceptions in this circumstance: any created Custom Properties/Groups that may exist on the Platform might have been applied differently to these objects, and will appear differently than on the server/database node settings pages.

Viewing Application & Component Custom Properties & Custom Property Groups Settings

Platform Operators do not have the ability to edit a guest application or application component's Custom Properties settings (only the Development Team that created the app can do that), but these Custom Properties settings can be viewed through the SOC.  Navigate to the Applications page via the top menu and click on the Version name next to the application whose settings you wish to view.  If any created Custom Properties/Groups have been applied to applications, a View Custom Properties link will appear in the Version details box on the left of the resulting page.  Click on that link to view the application's Custom Properties/Groups, including the present values for its inherent properties such as Deployment Stage and Development Team Alias.  If any created Custom Properties/Groups have been applied to specific application components, click the Components tab on the Application Version page to view all deployed components for that app.  From the dropdown menu that appears by clicking the arrow to the far right of the listed component, choose the View Custom Properties option to see a list of values for those created Custom Properties/Groups.

Custom Properties on Kubernetes Components

When a Custom Property is applied to a Kubernetes component it will be created as a Label on the Deployment, ReplicaSet, or ReplicationController. The Label will be named customproperty.acp.apprenda.com/CustomPropertyName, where apprenda.com is your Cloud URL, and CustomPropertName is the name of the property. The Namespace the Platform manages is names acp.

Custom Property names for Kubernetes components that