Skip to Content

Release management in Jitterbit App Builder

This article walks through best practices, prerequisites to building a Release, and steps to follow for general Release Management in App Builder. For detailed instructions on how to build the App Builder Release within App Builder itself, see the Build a release article.

Best practices

The Development environment is not a sandbox. App Builder is capturing each database change, tracking them, and will replay them in QA when the database is shipped. As such, the developer should apply changes to the development environment in the same way they would expect the changes to be applied in QA and Prod. There are two types of changes that App Builder captures in development and applies during an upgrade of QA and PROD:

Schema Changes

  1. Renaming a table
  2. Adding/Modifying/Deleting a column
  3. Modifying a primary key
  4. Adding/Modifying/Deleting a foreign key
  5. Adding/Modifying/Deleting a unique constraint

Migration Rules - Migration rules are defined similarly to an Create/Update/Delete rule and run in the development environment. App Builder records the rule and runs it during an upgrade.

Transport all dependent applications and data sources

Shipping just an application or just a data source

While it is possible to ship a single application or a single data source from Dev to QA, it should only be done by advanced administrators with detailed knowledge of the changes that are being shipped with the object. In general, it is best to include all dependent objects when shipping a solution from Dev to QA and Prod. Following are some scenarios to consider when not including all dependent objects:

A designer adds a column to a data object in Data Source A. They then add a control to to a panel in Application X that is bound to the new column. If the developer attempts to ship Data Source A to QA, the upgrade will succeed. The data object will have a new column, though it is not used by the application. However, if the developer shipped Application X to QA, not including Data Source A in their solution, then the upgrade will fail. While upgrading the application, App Builder wlll attempt to add the new control, but the column it is bound to does not exist in the current data source in QA and therefore it fails to be added.

Multiple applications using the same data source

Assume Application X and Application Y both reference Data Source A. One team is working on Application X and another team is working on Application Y. Both teams have added a columns to a data objects in Data Source A, and both teams have added controls to Applications X and Y that are bound to those columns. One of the teams also removed a control from Application X and removed the column, Column Z, which the control was bound to. If a developer attempts to ship Application Y and Data Source A to QA, the upgrade will fail. App Builder will attempt to remove Column Z from Data Source A, but the column is still referenced by Application X in QA and therefore the upgrade will fail to remove the column. It is best to include any applications and data sources that are referenced in the solution to ensure that the upgrade will be successful.

Adding a non-null column

Take advantage of migration rules. Assume a table "Employee" has been shipped to QA and PROD and has been populated with production data. A developer then removes all of the rows from that table to add a NON NULL Column (Active Boolean Allow Nulls = False). This operation will succeed in the development environment because there are no employee records. When this changeset is applied in QA or PROD however, it will fail. An RDMBs database will not allow a non-null column to be added to a table that contains rows.

Instead, in the development environment, do not delete the employee records. Leave them so that the environment is representative of the QA and PROD target environments. Add the new column to the Employee table, but allow null values (Active Boolean Allow Nulls = True). Create a migration rule that updates the value of Employee.Active to true/false for all employees. Run the rule. Change the new column to be Allow Nulls = False. This operation will succeed in development, and will succeed when shipped to QA and PROD. App Builder will perform the following steps during the upgrade:

  1. Add Active to Employee table Allow Nulls = True
  2. Update all Employee rows to have Active = true/false
  3. Modify the Active column to be Allow Nulls = False

Note

Use supported Expressions to set the Active bit to true/false based on practical conditions. Typically, when adding a column to a table, all rows aren't expected to have the same value for that column. In this scenario, the migration rule might set Active to False for contract employees who have not been contracted in the past year, while setting all other employee rows to have Active = true.

Modifying the primary key of a table

Take precaution when modifying a primary key on a table that has already been shipped to QA and contains data. Again, it is best to ensure that the development environment has data in the table, so it best represents the QA and Prod environments. There are several ways a primary key might change. Following is one example:

Assume Employee has a column EmployeeId Integer Primary Key. Also assume that EmployeeAccrual has a column EmployeeId Integer (foreign key references Employee.EmployeeId). The Employee table also has a column SocialSecurity (String Unique Allow Nulls = False).

The developer has decided to change the primary key of Employee from EmployeeId to SocialSecurity. These are the recommended steps:

  1. Add SocialSecurity String Allow Null = True to EmployeeAccrual.
  2. Create a migration rule that updates EmployeeAccrual.SocialSecurity to be Employee.SocialSecurity joining to the two tables together on EmployeeId. Run the migration rule.
  3. Change SocialSecurity in EmployeeAccrual to be Allow Nulls = False
  4. Drop the relationship between Employee and EmployeeAccrual on EmployeeId
  5. Drop the column EmployeeId from EmployeeAccrual
  6. Change primary key of Employee to SocialSecurity
  7. Drop the column EmployeeId from Employee table
  8. Create relationship between Employee and EmployeeAccrual on SocialSecurity

App Builder will record these steps, and successfully execute them while upgrading QA and Prod.

Note

While performing steps 1 through 8, it is expected that the developer will be making changes to Data Objects, Actions, Panels, Controls, and so on. Feel free to make these changes at any time. In the example above, it is possible that the 8 steps listed are performed over a period of 8 hours during which several pages, data objects, and controls are also changed at various stages. The important point is to perform the steps listed in the correct order, so they are performed in the correct order during an upgrade. It is expected and fine to perform any number of changes to the logical data source or application while performing these steps.

Avoid importing schema

If the intention is to move a physical a database from Dev to Qa to Prod, and to further modify that physical database through the App Builder UI and ship those changes to QA and Prod, then do not use the import feature for App Builder Data Sources. To push changes made in development, App Builder captures those changes as they are made through its UI. Importing a data source bypasses the App Builder UI, synching the App Builder logical model to match the imported data source's physical model. Therefore, no changes in the imported data source would be propagated during an upgrade. There are situations where importing is supported with release management:

  1. If the physical database is maintained and modified outside of App Builder in all environments, then importing the data source throughout the development life cycle is supported.
  2. If the physical database is shared by Dev/Qa/Prod, then importing the data source throughout the development life cycle is supported.

Prerequisites to building a release

The following items should be considered and completed prior to building an App Builder Release:

  1. Ensure that the App Builder db User has Table and database Create permissions in the environment you are installing into.
  2. Ensure that a Database Administrator completes a database backup of both the App Builder database and any database undergoing physical and/or schema changes.
  3. Ensure the environment package that will be installed is running on the same Version of App Builder that the source environment is running on.

Steps to follow for release management

  1. Using your company standards for testing, verify the functionality of the App Builder application.
  2. Create a list of all attached Data Sources for the application you're building a release for. This information is available from the App Builder IDE, Build your application, click on your application and review the resultant Data Sources Panel.
  3. Create an application Release Template, and ensure all applications that should be promoted are included.
  4. Ensure that all linked Data Sources identified in step 2 are included in the Template.
  5. Verify the Template configuration for Data Sources. Only set Logical and Physical for data sources that you will manage schema changes for with App Builder.
  6. Review and commit any open database change management steps for databases that are marked as Logical and Physical Install.
  7. Configure the Data Config for tables in databases that have been marked for Logical and Physical Install.
  8. Once Data Config is complete, confirm Data Config.
  9. Build the release. For detailed instructions on building a Release within App Builder itself, see the Build a release article.