Exporting and importing from a ZAPP file

What is a ZAPP file?

A ZAPP file is a .yaml or .json file that specifies options for a Z APPlication (ZAPP) development environment. ZAPP files have several uses and functions, one of which is to define property group options in an IBM® Developer for z/OS® or IBM Developer for z/OS on VS Code development environment. For a full description of ZAPP files and how to define property group options in them, see Configure your applications with ZAPP files in the IBM Developer for z/OS on VS Code documentation.

Before Developer for z/OS can make use of the options in a ZAPP file, it must import them into a property group. The import operation occurs automatically when you load a z/OS project that contains a ZAPP file into the workspace. You can also export property groups into ZAPP files. This topic explains how the product imports ZAPP files, and how to export property groups to ZAPP files.

How ZAPP files are imported into the workspace

A ZAPP file that is in a local or remote z/OS project generates a property group automatically. A common use case illustrates this process:

1. Add a Git repository that contains a ZAPP file to the Git Repositories view. For instructions, see Adding a Repository.
2. Use the Create a z/OS Project menu action to add the repository to the z/OS Projects view. For instructions, see Creating a z/OS project from a Git repository.
   Important: The project must have only one ZAPP file in the root folder of the project.
3. A read-only local property group is generated and added to the Property Group Manager.

Exporting to a ZAPP file

1. In the Property Group Manager, right-click a local or remote property group and select Generate ZAPP.
   
2. In the Generate ZAPP file from Property Groups window, click Browse to navigate to a project to save the ZAPP file in. Select the project that you want to apply the property group options to.
3. From the file extension list, choose .yaml or .json. The file name must be zapp and cannot be altered.
4. Click OK. The ZAPP file is generated and added to the project. The product also generates a copy of the property group and adds it to the Property Group Manager.
   
   Note:

   • For HLASM property groups that are exported to a ZAPP file, Remote Macro Libraries and Remote Copy Libraries in the local HLASM property group are processed differently. Only entries with the library name MACLIB from the Remote Macro Libraries table are exported as macro libraries. Entries with the library name MACLIB in the Remote Copy Libraries table are ignored during export. All other entries in the Remote Copy Libraries table are exported and are available as copy libraries when a property group is generated from the ZAPP file.
   • If a Property Group uses the value <HLQ> to reference the High Level Qualifier (HLQ) of an MVS Data set, the HLQ variable must be defined in the ZAPP User Variables with HLQ as the Variable name and High-Level-Qualifier-Username as the Value.

     For more information, see Passing User Variables to a ZAPP file.

   Tip: In the generated property group, all fields that were displayed from the ZAPP file are read-only. If you need to update any of the read-only fields, you must update them in the ZAPP file. The product keeps the ZAPP file and the generated property group in sync. All other property group options can be changed in the property group editor.

Supported and unsupported ZAPP conversions

When a ZAPP file is imported into the workspace, the product generates a property group based on the options defined in the ZAPP file. The conversion supports a defined set of options.