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

Creating a Patch in the Additional Controls Section

Notice

Single file patching for non-database files is no longer supported. If you want to patch your application, you must do a full archive upload.

Once you have Published a version of an application and have created a new version, you must create a patch for the new version. While you can simply upload new binaries for some application tiers, if your application includes a data tier you must implement any changes through patch scripts. 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.

Patching can only be performed when a version is in the Definition stage. Before you can promote a new version of a application to the Sandbox stage, you must create a patch. This means that some change to the Runtime Binaries (such as adding or removing a file) must be made even if it is later negated (for instance, by removing or reinstating the changed file).

 

For all changes, you have the option of using the Patchbuilder utility to manually add and remove files and folders.  Because you cannot simply overwrite database scripts, you must use the Patchbuilder utility to implement any changes to a database.

For changes that do not involve changes to database scripts, you also have the choice of uploading a patching archive.

Using the Patchbuilder Utility

Single file patching for non-database files is no longer supported. If you want to patch your application, you must do a full archive upload.

To access the Patchbuilder utility, navigate to the Runtime Binaries page for the version of the application you wish to patch. This can be done by clicking on Definitions icon in the upper right of the Version Overview page, which will bring up a submenu that includes the Runtime Binaries link.

The Patchbuilder utility is located in the bottom half of the Runtime Binaries box.  The left side of the utility displays the current archive structure. 

To make changes to a particular element, click on its name (or its parent folder) in the archive structure on the left.  The file or folder will then appear in editable form on the right side of the utility, where you can expand any folders as necessary:

To remove an individual file or folder, right click on its name.  The option to Delete your selected file will appear in the resulting menu along with the option to download the file.

To add an individual file or folder, right click on the folder to which you would like to add it.  This will open a menu that will allow you to Add and then Upload a file or files, and will also let you add a New Folder.

Information on how Apprenda handles data for your application (including an explanation of Shared Tables) can be found in the Working with Data section of our documentation.

To make database changes, click on the Scripts icon in the archive structure; a current list of database scripts will then appear on the right side of the utility. Right click on the script you wish to amend (usually the Application Provisioning Script)  and then select the Patch SQL Scripts option.  This will open up the Persistence Scripts patching tool.  Use the Browse button to select an SQL script, and then designate it as a Schema or Data Script (or Shared Schema/Data Script) by marking the appropriate circle before clicking the Upload button.  You can then order them as needed by right clicking on the uploaded file names and selecting the Move Up or Move Down options.

Uploading a Patching Archive

You can implement the majority of changes to your application’s Runtime Binaries by uploading a patching archive in the form of a ZIP file.  This file must be structured in the same way as your initial Deployment Archive upload, but should not include an Application Provisioning Script.  Changes to your Application Provisioning Script must be made through patching scripts.  This can be done through the Patchbuilder (as indicated in the section above), but can also be accomplished through a patching archive as follows:

  • Database patching scripts must be included in the Scripts folder within the Persistence folder in an application archive.  
  • In order to take effect, they must be listed in the Deployment Manifest with the proper path and script type information as per the example below.
  • They should also be listed in the order in which they should be applied.

Sample DeploymentManifest.xml for DB Patching

<?xml version="1.0" encoding="utf-8"?>
<appManifest xmlns="http://schemas.apprenda.com/DeploymentManifest"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://schemas.apprenda.com/DeploymentManifest http://apprenda.com/schemas/platform/3.5/DeploymentManifest.xsd" >

  <persistencePatches>
    <persistencePatch path="\Persistence\Scripts\Schema\SchemaPatch.sql" type="SchemaScript"/>
    <persistencePatch path="\Persistence\Scripts\Data\DataPatch.sql" type="DataScript"/>
  </persistencePatches>
	
  <entitlementDefinitions>
    <entitlementDefinition name="Standard" isPublished="true" />
  </entitlementDefinitions>	
  
</appManifest>

 

An updated Tenant Provisioning script can be included in your patch archive. Please note that changes made to Tenant Provisioning scripts will automatically affect only new Tenants.  You can make changes to existing Tenant data through the Data Management section of the Cloud Control panel.

Other than patch scripts for the Application Provisioning script and an updated Tenant Provisioning script, you must omit any database scripts from your patching archive.  If you are not making either of these updates, you must remove the Scripts folder from your archive entirely.  As you will not be able to upload an archive with an empty Persistence folder, you must remove the entire Persistence folder if you have removed the Scripts folder and nothing else remains; however, you can include a Persistence folder if you are, for instance, using the archive upload to patch CLR stored procedures.

Once you have appropriately packaged your patching archive, you can upload it from the Runtime Binaries page for the version of the Application you wish to patch. You may choose to remove items not included in the patching archive by checking the appropriate box. This is useful if you have a service or interface that is no longer needed. Leave this box unchecked if you prefer not to remove any existing files.

Whether or not the box is checked, persistence scripts will remain unchanged. Existing Features and Securables will not be removed, although new ones may be added by means of an updated DeploymentManifest.xml file.

If the archive is uploaded successfully, the Patchbuilder display will update to reflect any changes. Additional changes can be made either with the Patchbuilder or by uploading an additional patching archive.

Updating Other Application Definition Components

Code-related changes made to Features and Securables through Patching will not automatically repopulate the Feature and Securable tokens that appear in the Definition page for the application version. Changes must be made by manually updating the Features and Securables sections of the version Definition.  Information on how to do this can be found in the relevant portions of the Defining a New Application section of our documentation.  It is also possible to add Features and Securables through a Deployment Manifest included with a patching archive, although removing a Feature must be done through the Developer Portal UI.