Will this provide the ability to stage a component into a ChangeMan ZMF package from scripting?  I am looking at using a groovy script to stage a component from the USS file system or PDS into an existing ZMF package.  The package ID would come from a member.cmn file in the repository.  We are using Bitbucket (x86) -> GitLab (z) -> USS zFS (z) -> PDS (z) using the DBB Groovy library. 

Basic ask is for the ability to Stage a component (program, JCL, bundle, aar, ara, etc.) into a package triggering any required compiles from an API or groovy scripting.  This would eliminate the developer needing to manually stage the components after the commit into Bitbucket.

Hello Christopher,

I’m afraid that I am not familiar with the use of BitBucket and so I can’t be definite about whether the Git/ZMF protocol helper will be of use to you.

In order to use the protocol helper you need to be able to issue standard git commands clone/push/fetch/pull to a remote repo with the repo url formatted as    ZMF://<zowe-zmf-profile-name>/<zmf-package-id>.  

If you can do that from your script then it may be of use.

However, the basic premise is that ZMF is the central repository and the local Git workspace is subservient to ZMF, which may not work with your configuration (though I’m not sure about that).

Your basic ask should be possible without using git commands.

If you just have a component in a workspace that can be addressed via the file system then you can make use of either the zowe zmf cli’s or the underlying ZMF REST API calls.

The cli’s can be issued from anywhere you can issue a command, the REST API calls need to be coded but they will work in the same way that any REST API call works.

To use The REST API calls you need to have installed the zmfrest web app which runs under Tomcat on z/OS.

The zowe zmf cli’s require zowe to be installed on your workstation along with the zowe zmf cli plugin.

I can produce some zowe zmf cli and/or ZMF REST API samples if you like but please comment on the above before I go any further.

Thanks.

Thanks for the additional information.

Lets ignore Bitbucket for now.  We are using Jenkins and EGIT to replicate the BB repo into USS on z.

Given that I have the files on z in the zFS file system can I stage a component into an existing package?

Can I stage all of the copybooks into a package and promote and then stage the COBOL modules triggering compiles?

I think the directions of data travel are opposite between our solutions.  In mine I am trying to push components from Git into ZMF and you are pulling components from ZMF into Git.

In my design I would have two components:

1. program.cbl          contains cobol program

2. program.cmn        contains an xml or yaml structure with ZMF information like package ID, component type, compile and link options

The script (running on z) would identify the components from a git diff and using the *.cmn member identify the package for this component and stage the cobol member to that package.

I have not located any examples where this is possible. Is there a ZMF CLI command for Stage from PDS?

The developers currently manually stage the components from a PDS into ZMF after updating in git. 

Thanks

Chris

 There are a number of things to say in relation to your questions.

 You have been able to stage zFS components into ZMF packages since version 7 (released about 10 years ago).

Originally you could use SOAP based web services or the zmf4eclipse plugin to do this.

More recently, a full set of ZMF REST api calls have been made available. These are serviced via Apache Tomcat running on z, the Tomcat stc passes the request/response onto/from the target ZMF subsystem.

If your script can make a REST api call then it can do what you want directly.

We have also exposed a (growing) subset of the ZMF REST api calls as ZOWE plugin cli commands. This subset includes the ability to stage a component from an external file into a ZMF package. These can be issued anywhere you can issue a command line command but require ZOWE to be implemented.    

So you can probably do what you want to do without anything more than this ?

Here is a sample REST api call to stage a component from a PDS to a ZMF package, first using URI parameters, then using a JSON request body.

The Apache Tomcat stc is at <url> and listening on port 9996.

The webapp which is connected to my target ZMF subsystem is called u820all

The component/checkin designation identifies the ZMF service to be executed.

The api parameters appear after the ?

Target package is STEV001611

The component is being staged from a PDS (or PDSE) called USERID.PROGRAMS.SRC

The incoming member name is INBOUND (this is usually the same as the target component name but, as in this case, it doesn’t have to be)

The target component name is CPYREST1

The target component library type is CPY

<url>:9996/u820all/component/checkin?package=STEV001611&component=INBOUND&componentType=CPY&chkInSourceLocation=1&sourceStorageMeans=9&sourceLib=USERID.PROGRAMS.SRC&targetComponent=CPYREST1&bypassLockCheck=N

The same thing can be presented as a JSON body on the REST call (instead of using URI parms):

{

    "componentType":"CPY",

    "component":"INBOUND",

    "package":"STEV001611",

    "chkInSourceLocation":1,

    "sourceStorageMeans":9,

    "targetComponent":"CPYREST1",

    "listCount":1,

    "sourceLib":"USERID.PROGRAMS.SRC"

}

And here is the same process as a command issued via the zowe zmf cli plugin.

zowe zmf checkin comp --zmf-p U820ALL --chkInsourcelocation 1 --componenttype CPY --package STEV001611 --sourcelib USERID.PROGRAMS.SRC --component INBOUND --targetcomponent CPYREST1 --sourcestoragemeans 9      

or, in abbreviated form

zowe zmf checkin comp --zmf-p U820ALL --csl 1 -t CPY -p STEV001611 --sl USERID.PROGRAMS.SRC -c INBOUND --tc CPYREST1 --ssm 9

Although these show a stage from a PDS you can also stage from zFS files (or, indeed, any local file system should be running off z) directly should you wish to do so.

And, of course, if the component you have just staged needs to be compiled then there is both a REST api call and a zowe zmf cli command which can request the build job be submitted.

The full range of ZMF actions have been exposed as REST api calls, we have also tried to anticipate all those calls that may be required as line commands and generated those into the zowe zmf cli plugin.

However, if you (or anybody) finds something that is missing we will remedy that.

The Git/ZMF interface is aimed at developers who are used to working directly with git and who wish to stage components directly from their local repo.

Traffic is both ways.

You can stage components from your local repo into a target ZMF package.

You can also pull changes from a target ZMF package into your local repo.

The Git/ZMF interface is built using the zowe zmf cli as its method of communicating with the target ZMF subsystem.

However, unless I have misread what you are trying to do, you don’t actually need to use this Git/ZMF interface. You just need to make either the relevant REST api call from your script, or issue the equivalent zowe zmf cli line command ??

Thanks for the excellent answer.

I think the reason I was not finding what I expected is that I was searching for STAGE and not CHECKIN/CHECKOUT.  We do not normally use the CHECKIN/CHECKOUT process and just STAGE components and overlay the package member.

How would I best follow the documentation?  Is all functionality in the ZMF XML Services Guide and translate that into JSON and REST?

Is the only security interface basic auth and the passing of userid and password in the clear?

Thanks

Yes, that’s right, the REST api calls mostly expose exactly the same set of services as you can find in the XML services guide.

There is a relatively recent pdf manual (so you may have to get hold of the most recent documentation bundle) called “Changeman ZMF REST Services Getting Started Guide” which contains lots of information about how to install the feature and it provides a (starter) list of available api calls.

Once you have the feature installed there is a prototyping tool (equivalent to xmlserv) which runs in a browser and allows you to further explore the available REST api calls (which, as is usual with hard copy, may be a superset of those described in the pdf manual).

Be aware that the manual will talk about REST services and ZMF event emission. The latter (implemented via the ZMF REST service architecture) is a mechanism for getting ZMF to notify external processes (e.g. Jenkins) when things happen (i.e. this is outbound from ZMF).

The REST api calls themselves are for traffic going the other way (i.e. requests inbound to ZMF).

The REST api call authentication is basic but that means passing userid and password encrypted in base64. They are not ‘clear text’.

Using the zowe zmf cli makes use of profiles (which include userid and password) which are stored securely on your local machine – all authentication is based on encrypted information passed by zowe driven by these local profiles.

I hope this helps.

If you need further information about where to find all this good stuff then please contact support for the official channel.  

Note that you will need at least ZMF 8.2patch4 to use the REST api calls and ZMF 8.2patch5 to use the zowe zmf cli. Preferably you should be on the latest supported release of ZMF (if only in a test subsystem to start with) to make use of these facilities.