Adding your applications to z/OSMF

To add your application to z/OSMF, create a property file that defines the parameters required for z/OSMF to configure your application, and use the z/OSMF Import Manager task to import the property file.

To use a property file to add a new plug-in to z/OSMF, complete the steps that follow:

1. Create a property file in the z/OS® UNIX System Services (z/OS UNIX) file system, and set 644 as its permissions. For example, you can create a text file called plugin.properties.
2. Type importType=plugin at the beginning of the file. Doing so informs z/OSMF that the property file contains a plug-in definition. You cannot define other types of objects, such as event types or handlers, in a property file for a plug-in.
3. Define only one plug-in to be added to z/OSMF. To do so, specify the following properties for the new plug-in:

   izu.externalapp.file.version=plugin-version
   izu.externalapp.local.context.root=plugin-context-root
   izu.externalapp.code.root=plugin-code-root
   
   pluginId=plugin-Id
   pluginDefaultName=plugin-name
   pluginDescription=plugin-description
   aboutPanelPath=about-panel-path
   
   izu.externalapp.help.root=help-root
   izu.externalapp.helpdoc=help-plugin-name

   plugin-version

   Specify the version of the plug-in.

   plugin-context-root

   Specify the name of the symbolic link directory under the USERDIR/data/externalapps directory to use for your applications. The USERDIR setting, which identifies the mount point of the z/OSMF user file system, is set when your installation configures z/OSMF. By default, the mount point is /var/zosmf/.

   If you specify myapp as the plug-in context root, a symbolic link named myapp will be created in the path of USERDIR/data/externalapps/myapp, and it will point to the source code path /usr/lpp/myapp/ui.

   z/OSMF uses the context root to build the navigation URL and the bundle URL.

   The plug-in context root is required, and the directory name must comply with the z/OS UNIX naming guidelines.

   plugin-code-root

   Specify the path to the z/OS UNIX directory that contains the source code for the tasks included in the plug-in. If the plug-in property file and the source code directory reside in the same directory, you can specify a relative path, for example, ui. Otherwise, you must specify the absolute path, for example, /usr/lpp/myapp/ui. The plug-in code root is required.

   plugin-ID

   Specify a unique identifier for the plug-in. The ID is required, must be unique, and can contain a maximum of 64 characters.

   plugin-name

   Specify the name of the plug-in. The plug-in name is required, and can contain a maximum of 64 characters.

   plugin-description

   Provide a description of the plug-in. The description is required, and can contain a maximum of 256 characters.

   about-panel-path

   Specify the absolute path of the flat file that contains the plug-in version information to display on the z/OSMF About page. For example, /zosmf/IzuUICommon/externalfiles/myapp/myappVersion.txt. The path is required.

   Tip: If the file resides in the same directory as the plug-in property file, you can specify the filename with no path information. For example, myappVersion.txt.

   help-root

   Specify the path to the z/OS UNIX directory that contains the help files for the tasks included in the plug-in. If the plug-in property file and the help root directory reside in the same directory, you can specify a relative path, for example, helps. Otherwise, you must specify the absolute path, for example, /usr/lpp/myapp/helps. The plug-in help root is optional.

   help-plugin-name

   Specify the name of the directory that contains the help files for the tasks in your application. For example, com.ibm.zosmfmyapp.task1.help.doc. The directory name is required only if you are including help files in your plug-in. The directory name must comply with the z/OS UNIX naming guidelines.

   Each help plug-in must be enumerated and must be listed in numeric order because z/OSMF expects the first help plug-in to be enumerated as izu.externalapp.help.root.1, the second as izu.externalapp.help.root.2, and so on. The first time the enumeration does not match the position of the help plug-in in the file, z/OSMF stops looking for help plug-ins.

4. Include one to 32 task definitions in the plug-in property file. Each task definition must be enumerated and must be listed in numeric order because z/OSMF expects the first task definition to be enumerated as one, the second definition as two, and so on. The first time the enumeration does not match the position of the task definition in the file, z/OSMF stops reading the file. That is, the remaining task definitions will not processed.
   The following attributes are supported for tasks:

   taskId=task-ID
   taskVersion=task-version
   taskCategoryId=category-ID
   taskDispName=task-name
   taskDispDesc=task-description
   taskSAFResourceName=task-SAF-resource-name
   taskMultiSysplexScope=task-multi-sysplex-scope
   taskHandlerEligible=task-handler-eligible
   taskAuthenticatedGuestEligible=task-authenticated-guest-eligible
   taskNavigationURL=task-navigation-URL
   taskBundleUrl=bundle-URL
   taskBundleFileName=bundle-file-name
   taskMinZOS=minimum-z/OS-level
   taskMinZOSMF=minimum-z/OSMF-level

   task-ID

   Specify a unique identifier for the task. The ID is required, must be unique, and can contain a maximum of 64 characters.

   task-version

   Specify the version of the task.

   category-ID

   Specify where the task is to be displayed in the z/OSMF navigation area. You can assign the task to any valid category, or you can opt not to categorize the task. If assigned to a category, the task is sorted alphabetically with the other tasks and links in that category. Otherwise, the task is placed after the Welcome task in the navigation area, sorted alphabetically with any other uncategorized tasks and links.

   To indicate the placement of the task, specify one of the following values:

   • 1 - z/OSMF Administration
   • 2 - Problem Determination
   • 3 - Links
   • 4 - Configuration
   • 5 - Software
   • 7 - z/OS Classic Interfaces
   • 9 - Performance
   • 10 - z/OSMF Settings
   • 11 - Uncategorized
   • 12 - Commands and Logs
   • 13 - Jobs and Resources

   The category ID is required.

   task-name

   Specify the task name to be displayed in the z/OSMF navigation area. The task name is required, and can contain a maximum of 30 characters.

   task-description

   Provide a description of the task. The description is required, and can contain a maximum of 200 characters.

   task-SAF-resource-name

   Specify a unique SAF resource name to be used for managing user authorizations to the task. The resource name must start with ZOSMF, and must conform to the following structure to ensure uniqueness:

   ZOSMF.<vendor>_<plugin-ID>.<task-ID>.<task-name>

   where:

   vendor

   Name of your company.

   plugin-ID

   Unique identifier you assigned to the plug-in.

   task-ID

   Unique identifier you assigned to the task.

   task-name

   Name you assigned to the task.

   For example, ZOSMF.IBM_TESTPLUGIN.COMMANDS.Commands.

   If the SAF resource name does not begin with ZOSMF, z/OSMF will add prefix ZOSMF.IMPORT to the SAF resource name.

   The resource name is required, and can contain up to 231 alphanumeric characters (A-Z a-z 0-9) and the following special characters: underscore (_), dash (-), period (.). The use of a period in a resource name is treated as a qualifier. As such, the first character after a period must be A-Z or a-z.

   task-multi-sysplex-scope

   z/OSMF provides a multi-sysplex capability, which allows you to manage multiple z/OS sysplexes from a single z/OSMF instance. To do so, a z/OSMF instance must be running in each sysplex to be managed.

   Set the task-multi-sysplex-scope property to true to indicate that this task can be used to manage or display data for multiple z/OS sysplexes. Otherwise, omit this property or set it to false.

   task-handler-eligible

   z/OSMF provides the application linking capability, which allows you to create context-sensitive launch points between tasks or applications. The task or application that initiates the launch request is referred to as the event requestor, and the task or application that processes the request and displays the appropriate context is referred to as the event handler.

   Set the task-handler-eligible property to true to indicate that the task is eligible to be an event handler in the application linking process. Doing so allows users to define the task as a handler for one or more event types. To disallow the task to participate in the application linking process as an event handler, omit this property or set it to false.

   task-authenticated-guest-eligible

   Set this property to true to extend task authorization to users who are logged into z/OSMF, but are not defined to a z/OSMF SAF security group. Otherwise, omit this property or set it to false. Extending task authorization to users who are not logged into z/OSMF is not supported.

   task-navigation-URL

   Specify the relative or absolute path of the home page for the task. For example, if the home page is named index.html and resides in the myapp directory (context root), you can specify index.html or /zosmf/IzuUICommon/externalfiles/myapp/index.html.

   If the plug-in contains more than one task, append the following to the path: ?task=contextRoot.taskName, where contextRoot and taskName are the values you specified for the izu.externalapp.local.context.root property and the taskDispName property. For example, /zosmf/IzuUICommon/externalfiles/myapp/index.html?myapp.settings.task.

   The path can contain a maximum of 4000 characters, including alphanumeric characters (A-Z a-z 0-9), blanks, mathematical symbols (+ - = | ~ ( ) { } \), punctuation marks (? , . ! ; : ' " / [ ]), and the following special characters: %, $, #, @, ^, *, and _. Any leading or trailing white space is ignored.

   The navigation URL is required if the bundle URL is specified. Otherwise, omit the navigation URL.

   bundle-URL

   Specify the relative or absolute path of the language resource bundle for the task. For example, if the bundle file resides in the /myapp/js directory, you can specify /js or /zosmf/IzuUICommon/externalfiles/myapp/js.

   The path can contain a maximum of 256 characters, including alphanumeric characters (A-Z a-z 0-9), blanks, mathematical symbols (+ - = | ~ ( ) { } \), punctuation marks (? , . ! ; : ' " / [ ]), and the following special characters: %, $, #, @, ^, *, and _. Any leading or trailing white space is ignored.

   The bundle URL is required if the navigation URL is specified. Otherwise, omit the bundle URL.

   bundle-file-name

   Specify the name of the language resource bundle file. The file name can contain a maximum of 256 characters. For example, bundle.js. The file name is required if the bundle URL is specified.

   minimum-z/OS-level

   Specify the minimum z/OS operating system level that the task requires. You can specify one of the following values:

   • 04.24.00: Indicates that the minimum z/OS level is V2R1.
   • 03.23.00: Indicates that the minimum z/OS level is V1R13.

   minimum-z/OSMF-level

   Specify the minimum z/OSMF level that the task requires. You can specify one of the following values:

   • 04.24.00: Indicates that the minimum z/OSMF level is V2R1.
   • 03.23.00: Indicates that the minimum z/OSMF level is V1R13.

   Figure 1 provides a sample property file that defines the myapp plug-in, which contains a Commands task and a Settings task.

   Figure 1. Sample plug-in property file

   importType=plugin
   
   izu.externalapp.file.version=1.0.0
   izu.externalapp.local.context.root=myapp
   izu.externalapp.code.root=ui
   pluginId=com.ibm.zoszmf.myapp
   pluginDefaultName=myapp
   pluginDescription=Operate myapp.
   aboutPanelPath=/zosmf/IzuUICommon/externalfiles/myapp/myappVersion.txt 
   
   izu.externalapp.help.root=helps
   izu.externalapp.helpdoc.1=com.ibm.zosmfmyapp.commands.help.doc
   izu.externalapp.helpdoc.2=com.ibm.zosmfmyapp.settings.help.doc
   
   taskId1=COMMANDS 
   taskVersion1=1.0 
   taskCategoryId1=12 
   taskDispName1=Commands
   taskDispDesc1=The Commands task lets you enter z/OS commands. 
   taskSAFResourceName1=ZOSMF.IBM_COMMANDS.COMMANDS.Commands 
   taskMultiSysplexScope1=true
   taskHandlerEligible1=true
   taskAuthenticatedGuestEligible1=true
   taskNavigationURL1=/zosmf/IzuUICommon/externalfiles/myapp/index.html?task=myapp.commands
   taskBundleUrl1=/zosmf/IzuUICommon/externalfiles/myapp/js/nls 
   taskBundleFileName1=bundle.js  
   taskMinZOS1=04.24.00
   taskMinZOSMF1=04.24.00
   
   taskId2=SETTINGS 
   taskVersion2=1.0 
   taskCategoryId2=10 
   taskDispName2=Settings 
   taskDispDesc2=The Settings task allows you to define task-specific settings.  
   taskSAFResourceName2=ZOSMF.IBM_SETTINGS.SETTINGS.Settings 
   taskHandlerEligible2=true
   taskAuthenticatedGuestEligible2=true
   taskNavigationURL2=/zosmf/IzuUICommon/externalfiles/myapp/index.html?task=myapp.settings 
   taskBundleUrl2=/zosmf/IzuUICommon/externalfiles/myapp/js/nls 
   taskBundleFileName2=bundle.js  
   taskMinZOS2=04.24.00
   taskMinZOSMF2=04.24.00

   Tip: To remove a plug-in and all of its tasks from z/OSMF, type deletePlugin=true at the end of the property file. Otherwise, omit this property.
5. Save the property file.
6. Import the property file. To do so, complete the following steps:
   1. In the z/OSMF navigation area, expand the z/OSMF Administration category and select Import Manager.
   2. On the Import tab on the Import Manager page, specify the full path and name of the property file you created, and click Import.