Skip to Content

How to Build a Release Package

This article will provide a general overview of how to build a Release Package in Vinyl, also referred to as an "LP". A Release is a collection of Applications and Data Sources, which are packaged together for deployment. This process is used when moving an application from one environment to another, for example when moving an application from Development to QA, and ultimately to Production.

Build a Release

Building a Release into a Package and then Installing a Package in a new environment all takes place in the Deploy your application area, accessed from the Vinyl IDE. During this process you will move from the left side of the Release Template (Builder) screen to the right side, as you step through all of the steps described here:

  1. From the Vinyl application, click the Action Drawer and select Vinyl IDE
  2. Select Deploy your application from the Build menu

  3. From the Create a Release area, you'll use the Release Template (Builder) panel to create the Release build package.

    Releaseprocess

    Release Template Builder

  4. To start a Build, you can either select an existing Template (if you're updating an existing App upgrade) or click Create to create a new Template for usage

  5. If using an existing Template, click on the Template button for the existing Template record
  6. Update the Name, Version and Developer fields on the Release Details screen to reflect the Build you're creating
  7. Click the Next tab to continue
  8. The Solution Applications screen provides information about what specific Applications will be part of the build. A Release can contain one or more Applications. Make sure this screen contains all of the Applications required for your release, if it does not click the Create button and add Application(s) as appropriate.
  9. Click the Next tab to continue

  10. The Solution Data Sources screen lists all Data Sources relevant to the release build. If your build requires a Data Source not already listed, click the Create button and add it. For each Data Source listed, check the Include column and make sure it is set as you want it for the Build (Logical Model Only, Logical Model and Physical Tables, or Do Not Include). The different settings for each Data Source to Include are:

    • Logical Model Only should be used when you want to package only the data that was created and exists in Vinyl itself. Examples: Data and Business Objects, Subqueries, CRUDs, Workflow, Bridges. This option is generally used for data sources we do not own and/or are not maintained via Vinyl (external data sources, API data sources, etc.).
    • Logical Model and Physical Tables should be used when you want to bring along all data existing in Vinyl itself as well as the underlying Data Source Tables and Columns structures. Here, Physical refers to Vinyl maintaining or making updates to the actual database layer. If you move a Physical model, that means any changes made in dev to the database will also be made in the QA/Prod database upon moving the LP. This option is generally used for data sources we manage.
    • Do Not Include should be used if you do not wish to include this Data Source in this Release

    Solutiondatasources

    Solution Data Sources Screen

  11. Click the Next tab to continue

  12. The Solution Bundles screen is for translations. If you have built your app and added translations to it, you'll need to manually go and add in your application Solution Bundle to this screen. If you have not done any translations with your app, no information needs to exist on this screen.
  13. Click the Next tab to continue

  14. The Release Notes screen contains overview information about the Release package, including:

    • Name = the name of your application
    • Version = the version number of package being created
    • Release Date = the date you want the release to appear as (this is a soft date and can be different from the actual release date)
    • Build Date = actual date you committed the package
    • Release Date = actual date you released the package
    • Template Description = a text description of what your app or suite does

  15. The Publish screen lets you review information entered. When ready, click the Ready for Release button, and the Proceed button which moves you to the next step. You should now be back at the Release Template (Builder) screen with the Ready column containing a green checkmark.

  16. Click on the Db Changes button, and you'll know you have unconfirmed changes to review and commit if you see a red checkmark appear in the Db column on the Release Template (Builder) screen. The Change Management Requests screen lists out all of the data source related changes that will be part of the package. If you see any changes listed with a red checkmark for Status, that requires you to manually click into it to review and approve.

    Clicking into review brings you to the Change Management Request screen. Here, the Patch Number field auto populates with a value and indicates what iteration this package update reflects. Be sure to review all entries listed in the Changes panel to ensure this information is what you expect will move with the package. On this screen you need to enter:

    • Reference Number – this can mirror the Patch Number value, be a JIRA or AHA ticket reference, or use a client numbering value
    • Short Description – provide a text description about the package. If desired, enter additional information in the Comments field.

  17. Click the Save button, and if ready to proceed click the Close this Request button

  18. Close out remaining screens so you're looking at the Release Template (Builder) screen. You'll now see a green check appear in the Db column.

  19. The Data Config is optional and only used if you're moving Logical and Physical Data with the package. From the Data Configuration screen you'll line items of all the datasource, tables for the data source, along with what Owner Type has been assigned along with the corresponding action that happens when the table is moved to that environment. The different Owner Types are

    • User Data = will not transfer any of the data. The Users in each environment are responsible for populating that Table. For example: Customers or Orders, which are transactional Tables
    • Share Data = inserts the new records only into the next environment. For example: Email Templates, which is a table you want the User to customize changes to
    • Developer Data = truncates the Table in QA and inserts all the records from the package. This is typically used any time you have lookup Tables or Tables that are part of Configuration. For example: CustomerType, EmployeeType

  20. Information can be manually overridden for Owner Types, and set for the specific package, or you can simply click Confirm Config. This marks this process as complete and returns to the Release Template (Builder) page. Note that Jitterbit methodology Best practice is to always set the Install Option value at the Table level, which maps to Owner Type in the Release Template (Builder). Install Options are User Data, Share Data and Developer Data. If the values are set at the Table level, these settings will transfer over to the Release package. Setting this information at the Table level is helpful for projects with multiple team members.

  21. The SQL Config area allows you to pick the data base and see if there are any Objects (views or stored procedures) stored on the database at the native SQL layer. This will allow you to move views or stored procedures. This information will not automatically populate on the resultant Code screen, you will need to manually click on the Create button and add them in. This step is typically only used in advanced situations, and is not a required step.

  22. The Build step will show the version for this Release, and allow you to add Notes specific to this release. When you structure your Release Notes, we recommend using a format like the following screenshot. Following a consistent process for naming your Release Notes over time is important, especially if your project is one that has multiple people working on them. This becomes a running log of the app Release Notes.

    Releasenotesforbuild

    Release Notes Example

  23. Click on the Build Package button, which kicks off a background job that builds the package. There is no notification that happens to let you know when the package is finished and/or fails. In order to check on the process status, you need to go to Vinyl IDE, Manage Servers and Schedules and check the Instance Running Jobs panel.

  24. The Reset button would clear out all information associated with the Package Template, and allow you to start from a clean slate for your package build.
  25. Click the Packages icon (Packages) which brings you to Solution Releases screen, which has the downloadable LP file created for the next environment. This is the file you'll take to install in the next environment. From this screen, download the Package file and store it locally on your computer.
  26. With the LP file available, go to your next environment where you will install it (QA or Prod). From there, go to Deploy your Application from the Vinyl IDE and click on the Install Release button.

  27. Click the Create button and Browse to locate the Package file and click Save. Upon Saving you will see the Solution panel on the right display the package information about Name, Version, Developer, Release Date, Description and Release Notes.

    Solutionscreeninstall

    Example Solution Panel View

  28. Click the Install button after confirming this is the package you wish to install. This process runs in the foreground. If it succeeds you'll get a success message. If it fails go to Logs > App Server Fast Logs and you'll see specific error information as to why the install failed.

Information Included in a Build Package

Releasecontents

Information included in a Vinyl Release

  • Data - includes Data Model, Views and Stored Procedures
  • Data Sources - includes Data Objects and Roles
  • File System Paths
  • Bridges
  • Applications
  • Collections – includes Themes, HTML Templates, Formats, Widgets and Images
  • User Functions – if being used in the app
  • Schedules - these will come over unless you specifically delete or remove prior to building the package
  • Bundles
  • Assemblies and Plugins

Schedules and Release Packages

Schedules will be included in a Release Package (or LP) unless they are manually removed when building the Package. By design, Schedules that have been deployed in a Production environment are "sealed" or prevented from making certain edits to the Schedule information. This prevents someone from accidentally making development changes in a downstream environment, which could lead to various issues when trying to deploy the app in the future. Schedules are part of an application, so they are "sealed" in these downstream environments. You can turn Schedules on or off or adjust the time, but you are not able to change the execution type of a Schedule.

There are some scenarios where you might set up a Schedule in Dev but once in Production the Dev Schedule gets turned off. For example, interacting with an API. You may only want to interact with an API from the Production environment, so once the Dev is complete you can turn off the Schedule in the Development environment.

Once a Schedule has been added to an LP, note that not all Schedule changes will get pushed in future Builds of a package. If you add or remove Events associated with a Schedule, these changes will get reflected in a new Build. Other changes to a Schedule definition will not get pushed to future Builds.

In order to make changes to a Production Schedule that is sealed, you can create a new Schedule that will then get included in the next LP. This process will ensure the Schedule is created correctly with any new settings reflected in the downstream environments.

Information Not Included in a Build Package

  • Vinyl Instance Groups
  • Vinyl Instance Security Providers
  • Server Credentials

Warning about Database Changes

If you have database changes that need to be committed you should move Logical and Physical for that database. The Release Management process does support importing Tables. If you import Tables into a data source, those imported Tables will be created in the target system if they are a part of the first Physical change set.

Troubleshooting

Release Template Cheat Sheet

The following Cheat Sheet diagram helps Vinyl users understand which area of the Release Template Builder map to what component(s) in an application:

Cheatsheet

Cheat Sheet for Building a Release in Vinyl

Note

If you do not see a "Build" button available on the Release Template Builder screen, that indicates you have to confirm the data config option.