Version control your application definition

In this section, learn how to version your application definition. Versioning your application using a Version Control System (VCS) is useful if you want to:

  • Compare the content of two different application versions to see what has changed.
  • Detect any conflicting user-managed resources which would impact your application upgrade process. 
  • Manage and version key elements of your application such as your model, your mappings, and your routes. 

Initialize your VCS repository

The .appx file to manage should be a complete export of your application (i.e. no partial export)

To initialize your VCS repository:

  1. Get the DI .appx file you want to manage.
  2. Using the ZIP management tool of your choice, extract the content of the .appx file into your VCS repository.
  3. Add all files and commit them to your repository.

About the .appx file format

To open a DI .appx file, use your preferred ZIP file management tool.

Inside the .appx file, you will find many files organized based on the type of resources they manage.

Currently, only the files marked with a (star) can be manually updated. This means, once your application is in a VCS system, you can freely update and commit changes to any (star)-type file.

(warning) Do not rename or remove them, as they are referenced by the application.xml files.

However, do not manually update the unstarred files in your application. Instead, when you export a new version of your application from DI, merge this latest version of the files with their respective counterpart in your VCS.  For more information, see Version control your application definition#Merge or update your versioned application below.

File Comment

This file contains the definition of the application and its content. It contains a reference to all other files.

{spaceKey}/routes/{routeName}.xml (star)
Data integration routes
{spaceKey}/libraries/{libraryname}/{filename} (star)
Data integration library file
{spaceKey}/resources/{resourceName} (star)
Data integration resources
Data integration mapping
Data integration connector
Data integration event
Data integration query 
Data integration trigger
Data integration notifier
Notification definition

Dashboard definition.

By default, dashboard space key are a random UUID, you can update them to a more readable key using the space management tool.

Pagelet definition
templates/{templateName}_{templateUUID}.xml (star)
Indicator definition
{spaceKey}/images/{imageName} (star)
Images that are part of your application.
Icon set definition

Merge or update your versioned application

Unless you are working on a (star) file, you must never directly update the contents of your application.

Instead, here is the recommended procedure to merge or update your versioned application:

  1. Use your DEV environment to update your application.
  2. Export the application when you are done. 
  3. Extract the contents of the new application and use the diff tool of your choice to compare both the current "official" application and your new one with updates.
  4. When merging the files in your VCS repository: 
    • Files that were deleted in your new application should also be deleted from your versioned files.
    • Files that are not marked with (star) should be copied as-is from your new version to your versioned application version.
    • For files marked with a (star), you may manually make your changes and manage this type of content as you see fit
  5. Once you are done, commit your changes.

Import your versioned application

  1. Using any compression tool, create a zip or a tar.gz of the whole content of your application.
  2. Rename the file from or myApp.tar.gz to myApp.appx and import it in your DI node.

As you manually merged/updated the application, it is strongly advised to use a development node first to validate the integrity of your application.  Do not re-import to your production environment without testing on your DEV environment first. 

See also

For more information about importing and exporting a DI application, see Import and export an application.

Related Links