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

Patching Your Application

The Patch tab in the Developer Portal can be used to update/replace an application's archive when the application version is in any active Lifecycle stage (Definition, Sandbox, Published); the way the application will be affected, though, depends on the specific Lifecycle stage the application is in.  See below for more detail on patching your application while it is in each of the individual Lifecycle stages.

Patching in the Definition and Sandbox Stages

When an application version has not yet been Published, you are able to completely replace that app version's archive with a new one that you select.  From the Patch tab, select the new patching application archive you'd like to upload; you can either select an archive from the local file system or enter an Application Package URL that points to the location of the desired archive.  After selecting a valid archive, you also have the option of choosing a Target Stage to promote/demote the application to after the new archive is uploaded (Please note: if no Target Stage is selected, by default the application will be placed in the Definition stage, even if it is originally in the Sandbox stage when the new archive is uploaded):

When you are done, click the Save button in the lower right to upload the new archive, or click Cancel to clear your selections.

When the new archive is uploaded, any existing application-level or version-level settings, including any existing Entitlement Definitions, will be retained, unless these settings are explicitly changed by the new Deployment Manifest contained in the archive (including a Deployment Manifest in the new archive is optional).  However, since the new archive is not necessarily based on the one it replaced, it may contain completely new application components.  Therefore, all existing component-level settings will be discarded when the new archive is uploaded, and any of these settings that you want to retain will need to be explicitly set in the new archive's Deployment Manifest, or can be set manually through the app's Configure tab once the archive is uploaded.

Patching in the Published Stage

As with any Published application available for User access, it may be necessary to upgrade your applications to include new functionality or to patch bugs.  When your application version is in the Published stage, patching works differently than if the app was in an earlier Lifecycle stage because of the necessity of continuing to make the app available for consumption while initiating the creation and testing process with a new version.  While one version of an application is Published, an entirely new version, based on the currently-Published one but with a patched set of Runtime Binaries, can be created and tested.  Once you have Published a version of an application and have created a new version, you cannot change the Runtime Binaries of your application by uploading the entire upload archive, but must create a patch for the new version. This is because once an application is Published, scripts that control database structure and content cannot be overwritten, but must be changed manually according to the demands of the particular component.  For details on how to create an archive for patching, please see this documentation.

To patch an application in the Published stage:

  • From the Patch tab, select the patching archive you'd like to upload; you can either select an archive from the local file system or enter an Application Package URL that points to the location of the desired archive. 
  • After selecting a valid archive, you can choose whether the patching archive will be applied as a Destructive Upload by checking or unchecking the appropriate checkbox; this setting determines whether any items from the previous application version which are not included in the uploaded patching archive will be removed from the application's binaries.  If the box is left unchecked, those items not included in the uploaded archive will be kept for the new app version.
  • You also have the option of choosing a Target Stage to promote/demote the application to after the new archive is uploaded.  If no Target Stage is selected, the new application version will remain in the Definition stage.  For applications with Authorization or Multi-tenancy, if you select a more advanced (Sandbox/Published) stage, the new app version will only be able to promote to that stage if a published Entitlement Definition has been defined for the new app version through a Deployment Manifest included in the patching archive you used to create the new version.
  • Finally, you are asked to define a Version Name and Alias for the new application version, as well as optionally including a Description for the version.  When creating a new app version, the Description field can serve as a changelog that tracks the updates made to subsequent new versions of an application.

When you are done, click the Save button in the lower right to upload the new archive, or click Cancel to clear your selections.

Uploading a patching archive will result in new Runtime Binaries and, possibly, new Features. If you have not selected a Target Stage to promote the new app version to, and if you have not defined a published Entitlement Definition in the Deployment Manifest of your patching archive, any Entitlement Definitions from the original version of the application will be copied automatically and left in the “unpublished” state for the new app version.  For applications with Authorization or Multi-tenancy, it will be necessary to adjust them through the Additional Controls section in order to reference any new Features, and it will be necessary to publish an Entitlement Definition for the new app version before it can be promoted to the Sandbox and Published stages.

Notes and Considerations Regarding Patching an Application in the Published Stage:

  • A new version of an application can only be created after the application has been Published. This is because new versions of an application are created based on the version that is currently Published.
  • While you can have multiple versions of a product in the Definition, Sandbox, and Archived stages, you can only have one version of the product in the Published stage at any given time
  • Once a version is Published, a version based on an older version of the application cannot be Published. For instance, suppose that Version 1 has been Published and Versions 2 and 3 have been created based on Version 1.  Should you then Publish Version 3 (skipping Version 2), you will not be able to Publish Version 2; any future Published versions must be based on Version 3.  For this reason, the Description field is useful for keeping track of the genealogy of each version of an application.  While all versions created while Version 1 is Published will be based on Version 1 (e.g., Version 2 will be based on Version 1 if it is created while Version 1 is in Production), later versions that are created when a different version is Published will be based on that version (e.g., Version 6 will be based on Version 4 if it is created when Version 4 is Published).  The version Description, therefore, can be useful for tracking the relationship between your versions, as well as for cataloging changes made to a new version after you have created it.  For instance, your Version 6 Description might contain the following: “based on Version 4; added new Block Feature for Tenant support; fixed a bug in the database.”

Testing and Publishing Patched Applications

Managing Application Versions

If more than one version of an application exists, you are able to switch back and forth between version overviews in the Developer Portal in two ways.  First, on the Applications list, click the arrow icon next to the Lifecycle stage listed in the Stage column for the app you want to view; the resulting dropdown list will allow you to choose which version to view:

Second, while viewing a specific application version in the Developer Portal, clicking the version name of the app version you're currently viewing (located in the upper right of the screen) will cause a dropdown list containing all versions of the application to appear:

In both dropdown lists, the Lifecycle stage each version is in will be indicated by a colored dot next to the version name (Definition=red, Sandbox=yellow, Published=green, Archived=grey).  Clicking on a version name will take you to that version's overview.

If you wish to delete an application version while it's in the Definition or Sandbox stage, navigate to that application version's Dashboard tab.  Next, click on the Delete button on the bottom menu bar and select the Delete Application Version option from the menu that appears (and then affirm this decision at the confirmation prompt) in order to permanently delete the application version.

Testing a New Version in the Sandbox Stage

If your new application version has not already been promoted from the Definition stage, you may need to adjust and/or publish an Entitlement Definition through the Additional Controls section for the app version before it can move further in its Lifecycle.  Once that is done, the new version can be promoted to the Sandbox stage by clicking the Promote button on the bottom menu bar on the app version's Dashboard tab.  Once promoted to the Sandbox stage, the new version will be available for testing through the same methods outlined here.

Publishing a New Version

Please Note: During the publication process for a new application version, Users access to the application will be disabled. Should a User attempt to launch the application at this time, they will be directed to the Maintenance page. Once the new version is published (and, if the application has Authorization or Multi-tenancy, a given User's subscription has been migrated to the new version), the application will be accessible once more. For a User who has hit upon the Maintenance page, this means that the Click here to return link will direct them to the application.

Furthermore, publishing a new version that adds or removes Features or Securables will affect any existing Tenants and users who subscribe to the app; it is therefore advisable to inform any Tenants or users if they will be affected by such Feature or Securable changes.

If your application version has successfully been promoted to the Sandbox stage and you are satisfied with its performance, you can then promote it to the Published stage, again using the Promote button on the app version's Dashboard tab.  

When promoting a patched application version to the Published stage, you will be prompted to choose whether the to-be Published version should use Scaling Component settings (and maintain current component instance counts) set specifically for the version, or should inherit them from the Published version it will replace:

The version currently in the Published stage will be moved automatically to the Archived stage for future reference.  Any Entitlement Definitions associated with the new version will now be the basis for all new subscription procurements of the application, and the new version of the application will launch when new and existing Tenants access it.