This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Configuring an Entitlement Definition for a New Application

From the Version 1 Overview page for your application in the Additional Controls section of the Developer Portal, click on the Entitlements icon in the upper right-hand menu.  This will take you to the Entitlements page for that version of the application.

For the initial version of an application, Apprenda automatically creates one blank Entitlement Definition and names it Standard; this Entitlement Definition initially appears in the Entitlement Definition list on the right side of the page:

If the associated application has only Authorization enabled, you will only be able to edit and publish a single Entitlement Definition.  The Standard definition can be renamed here, but no other options are available.  If the application has Multi-tenancy enabled, however, multiple Entitlement Definitions can be created (although only one can be published at a time), and you can use the icons to the right of the Entitlement Definition description to copy, edit, or delete it.  For applications with Multi-tenancy, you can copy an Entitlement Definition at any time, but it is especially useful to copy a populated Entitlement Definition that you wish to use as the basis of a new  Entitlement Definition.  You can also use the New  Entitlement Definition box on the lower left side of the page to create a blank Entitlement Definition.

Please note: you cannot delete an Entitlement Definition once it has been published, even if it is later replaced with another Entitlement Definition.  This is to preserve the integrity of existing subscriptions from the retired Entitlement Definition.

To begin the process of building an Entitlement Definition, click on the name of the Entitlement Definition you would like to configure (if you have not made any changes, the Standard Entitlement Definition automatically created by Apprenda will be your only option).  This will take you to an overview page for that Entitlement Definition:

To view or edit how your  Entitlement Definition appears to your Tenants, click on the View/Edit Appearance Settings link.  This will take you to the Entitlements Appearance page, which will allow you to make changes to the Public Name and Description of your application if you would like them to appear differently in the  Entitlement Definition than they do in the Developer Portal.  From this page you can also customize the appearance of your Entitlement Definition by providing a URL to a Custom Stylesheet in the appropriate field.

In the Publication section of the overview page, you can use the Preview this Entitlement Definition link at any time to see how your Entitlement Definition will appear to your potential subscribers.  Once you have completed all required pricing definitions, a Publish this Entitlement Definition option will appear in this section.

The Entitlement Definitions section of the overview page lists all of your definition options.

To set a User-based Entitlement Definition:

Click on the corresponding link, which will take you to the User-based Subscription Entitlement Definition page.  First, you will need to create a plan:

  1. In the Create a Plan Now box, input a name for your plan in the appropriate field.
  2. Use the Description field to input a description of the plan that will appear in the Entitlement Definition. 
  3. Although it is not required that you do so, you can base your plan on an Edition by selecting one from the pull-down menu. 
  4. If you would like to limit the number of subscriptions that a Tenant can add for this Plan, check the appropriate box and enter the desired limit.
  5. Click the Create Plan button. 

Your plan will now appear in an Entitlement Definition matrix that will allow you to set an Entitlement refreshment period as well as add Features and non-application components.  You also can add additional plans:

In setting the Entitlement refreshment period, you should consider what kinds of Features (if any) are included in your plan.  If your plan includes Block Features, they can be exhausted and will need to be refreshed in order for that Feature to be accessible to a User; in this case, you should configure your Feature Quantities and refreshment period accordingly.  If you do not include Block Features, you can simply exclude a refreshment period.

To add a new plan to your User-based Subscription Entitlement Definition, click on the Add Plan button that appears in the top row to the right of your existing plans.

To delete or copy an existing plan, mouse over its name in the top row of the pricing matrix.  To delete the plan, click on the red box containing the white “X” that will appear to the right of the plan name. To make a copy of an existing plan, click on the duplicate icon that will appear to the right of the deletion icon.

To edit the name of an existing plan, click on its name in the top row of the pricing matrix.  This will open editable fields that will allow you to make and save your desired changes.

To add a Feature or non-application Component, click on the Add Component button.  This will generate an editable field that will allow you to create a display name for the Component.  To configure this Component as a Feature, select the corresponding Feature from the pull-down menu.   Otherwise, you can add a Component that is not linked to a Feature.

Once you have added your desired Components and plans, you can define which Components will be included in which plans.  To do this, right-click on the intersection of the desired plan and Component.  This will generate an editable Inclusion Options field that will allow you to mark the Component as Not Included or Included for that plan.  Please note that if you have created Editions for your application, you will only be able to Include a Component tied to a Feature if that Feature is marked as part of the Edition upon which the Plan is based; otherwise the Component will be listed as Unavailable.

The Inclusion Options field also requires you to set Quantities for Features that are Blocks, Boundaries or Limiters; Blocks will also require a Block Label.

You may also use the Footnote function on this page to include additional information about the component.

To Set Account-wide Entitlement Definition (for applications with Multi-tenancy only):

Click on the corresponding link in the Entitlement Definition Overview page, which will take you to the Account-wide Entitlement Definition page.  The procedures for creating Account-wide plans are the same as those detailed above for User-based Entitlement Definitions.

As you add plans and Components to your Entitlement Definition, Apprenda will alert you to incomplete sections (e.g., if you do not configure Inclusion Options or define necessary Feature quantities) by highlighting these sections with a red border and showing a message at the top of the page.  You must resolve all incomplete sections in an Entitlement Definition before you can publish it.

Once you have configured your Entitlement Definition, you can preview how it will appear to your Tenants by returning to the overview page for the Entitlement Definition and clicking on the Preview this Entitlement Definition link. If your pricing definitions are complete, you can publish your Entitlement Definition by clicking on the Publish this Entitlement Definition link that will appear in this section.

Please note that only limited changes are permitted to a published Entitlement Definition. Changes that affect display only, such as placement and content of footnotes, are generally permitted, and these changes are reflected immediately in how subscribers view the published Entitlement Definition. Apprenda limits changes you can make to a published Entitlement Definition in order to preserve the integrity of existing subscriptions.