Leveraging NAB’s Export/Import Functionality

Posted on July 11, 2022

As your repository of data sources, widgets and apps created in Nitro App Builder grows, you’re likely to encounter situations where you need to move NAB objects from one instance to another, or even deploy entire NAB apps to another IBM i system altogether. Likewise, you may occasionally have a need to retrieve a prior version of a data source/widget/app in order to “undo” some recent changes.

All of these tasks can be achieved with NAB’s built-in import/export functionality, as well as through batch calls or scripts, which can be added to your internal change management processes to promote NAB elements from development to production instances in conjunction with back-end RPG programs.

In this tip we’ll explore how to use these various import/export features, and formally review new import/export functionality that was introduced with Valence 6.1 earlier this year.

First up, let’s cover the three ways to move a NAB object (meaning, a data source, widget or app) from one instance to another.

 

(1) Direct export to another instance

The simplest way to copy a NAB object from one Valence instance to another, provided both instances are on the same system, is by using the direct export option. Any instance defined in the Instance Manager app is eligible for this approach. It is recommended that both instances be on the same major release — ideally 6.1 — to avoid losing any functionality between instances.

To utilize this approach, simply click on the row menu selector adjacent to the NAB object you’d like to export, then select Export > Instance and click on the desired destination instance (for data sources and widgets, Export is located inside the Miscellaneous sub-menu). When exporting an app, all underlying data sources and widgets will be exported along with the app definition.

After selecting the destination instance for the export, NAB will determine which object(s) being exported already exist on the destination instance, and which are being exported to that instance for the first time. The results are listed in a confirmation window that will show you what NAB will be replacing or adding if you click the Confirm button.

Note that matching objects are determined based on the date and time the objects were initially created. You can see those creation date/time values in the main list of NAB objects by clicking on the cogwheel in the upper right and then ticking the “Created” checkbox.

 

(2) Export to a save file, then import 

When you need to send NAB objects to another system, or if you simply want to preserve the current state of NAB objects for backup purposes, you can export the objects to a save file. The save file can then be used to import the exported NAB objects to a Valence instance on any system — again, ideally running at the same major release (6.1).

To utilize this approach, you would click on the row menu selector adjacent to the NAB object you wish to export, then select Export > Save File (again, for data sources and widgets, Export is located inside the Miscellaneous sub-menu). A prompt window will appear wherein you can assign a description for the save file in a “Name” field, along with a supplemental note for the save file repository, if desired, in a “Note” field. The save file repository is new for Valence 6.1 and is described in more detail below.

Upon clicking OK, a save file encapsulating the NAB objects will be created in a special library called VVEXPORT.

If your intention is to make the NAB objects available to another IBM i system, you would then use your preferred method to transfer the save file from the originating VVEXPORT library to your destination system’s VVEXPORT library. Then log into the appropriate Valence instance on the destination system, launch Nitro App Builder and click on the Import button that appears when you hover over the Plus button in the lower right. This will bring up a list of importable save files that exist in the VVEXPORT library.

Select the desired file and, provided the “Preview first” checkbox is ticked in the upper right, you will be prompted with a confirmation window identical to the one presented when directly exporting to another instance. Click the Confirm button to proceed with adding or replacing the NAB object(s) on the instance.

 

(3) Export and Import via batch program calls

A third option for exporting NAB objects is to call specific programs to handle the export and import process, essentially mirroring the steps described in either options (1) or (2) above. 

The first step in this approach is to call VVEXPORT to export NAB objects to a specific instance (option 1) or to create a save file for later import elsewhere (option 2).  

The parameters to be passed to VVEXPORT are as follows:

type (20A): One of three values: DATA_SOURCE, WIDGET or APP
id (15P 5): The numeric NAB object ID associated with the data source, widget or app, as shown in the Id column
description override (64A): If non-blank, will be used for the save file description. Otherwise save file description will be pulled from the data source, widget or app being exported
error flag (1A): A value of “1” will be returned if an error is encountered in the process
message (256A): Pass any note for the repository in this field. If an error is encountered in the process, text detailing the exception condition will be returned in this field.
destination instance (10A): If exporting directly to another instance, the name of the instance should be specified here. Leave blank to create a save file only.
mode (1A): A hard-coded value of “3” should be passed here to indicate the program is being called outside of Valence

When VVEXPORT is directed to export to a save file for import on a separate machine or partition, your next step would be to programmatically execute a routine or script to copy the generated save file to the desired location. The name of the 10-character save file that was created is passed back in the “message” parameter, beginning at the 10th character position.

You would then need to call VVIMPORT on the destination system or partition with the following parameters:

type (20A): One of three values: DATA_SOURCE, WIDGET or APP
save file name (10A): The 10-character name of the save file created (returned from VVEXPORT in the message parameter, beginning at position 10)
save file library (10A): The library in which the save file was placed (typically VVEXPORT)
destination library (10A): The library name (Valence instance) into which the NAB objects should be placed
mode (10A): A hard-coded value of “BATCH_EXEC” should be passed here to tell the program it’s being called outside of Valence
return message (256A): If any exception occurs during the import process, a description of the problem will be returned through this parameter

These programmatic export/import steps can be incorporated into your company’s change management software to make it possible to simultaneously promote Valence NAB apps in conjunction with back-end RPG exit programs and any other IBM i objects used by the app. We are currently working with Midrange Dynamics to incorporate this logic into their MDCMS product. We’ll be announcing more details on this collaboration in a future newsletter.

 

The new NAB save file repository and purge logic in Valence 6.1

To make it easier to manage what can quickly become a daunting number of NAB save files in the VVEXPORT library, a new save file “repository” concept was introduced in Valence 6.1, along with logic for NAB to automatically discard save files that are no longer needed.

The repository is essentially an extension file containing additional information for every save file created in VVEXPORT. The details are stored in a file called VVEXPORTS and includes information such as the specific Valence instance and version from which the save file was created, who created it, when and where it was imported, and additional notes relating to the save file contents, provided the save file was created in an instance running Valence 6.1 or higher. This extension information is displayed in the import list alongside every save file in VVEXPORT. Click on the “View last imported” checkbox to see when the listed save files were last imported.

Once a save file has been imported, it becomes eligible for automatic purging once the number of days specified in Portal Admin > Setting > Nitro App Builder > “Export save file retention period” since the import date has passed (default is 14 days). This automatic purge feature can be effectively disabled by setting the value to a huge number, like 9999.

Note that any save files sitting in VVEXPORT that have not yet been imported will never be deleted automatically, so you may occasionally want to do some manual housekeeping on the library by deleting unneeded save files.  Once a save file is deleted, the corresponding record in the repository will be deleted the next time any user goes to do an import in NAB.