diff --git a/api_definitions/datasets.json b/api_definitions/datasets.json deleted file mode 100644 index 9adc7ff153..0000000000 --- a/api_definitions/datasets.json +++ /dev/null @@ -1 +0,0 @@ -{"swagger":"2.0","info":{"description":"REST API for the Data sets and z/OS Unix Files Services","version":"1.0","title":"Files API"},"host":"zzow01.zowe.marist.cloud:7559","basePath":"/","tags":[{"name":"Data Sets V1 APIs","description":"Data Sets Controller V 1"},{"name":"Data Sets V2 APIs","description":"Data Sets Controller V 2"},{"name":"Unix Files APIs V1","description":"Unix Files Controller V 1"},{"name":"Unix Files APIs V2","description":"Unix Files Controller V 2"}],"paths":{"/api/v1/datasets":{"post":{"tags":["Data Sets V1 APIs"],"summary":"Create a data set","description":"This creates a data set based on the attributes passed in","operationId":"createDataSetUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetCreateRequest"}}],"responses":{"201":{"description":"Data set successfully created","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/username":{"get":{"tags":["System APIs","Data Sets V1 APIs"],"summary":"Get current userid","description":"This API returns the callers current TSO userid.","operationId":"getCurrentUserName","produces":["application/json"],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/Username"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/{dataSetName}":{"delete":{"tags":["Data Sets V1 APIs"],"summary":"Delete a data set or member","description":"This API deletes a data set or data set member.","operationId":"deleteDatasetMemberUsingDELETE","produces":["*/*"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name","required":true,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"204":{"description":"Data set or member successfully deleted","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v1/datasets/{dataSetName}/content":{"get":{"tags":["Data Sets V1 APIs"],"summary":"Get the content of a sequential data set, or PDS member","description":"This API reads content from a sequential data set or member of a partitioned data set.","operationId":"getContent","produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/DataSetContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["Data Sets V1 APIs"],"summary":"Sets the content of a sequential data set, or PDS member","description":"This API writes content to a sequential data set or partitioned data set member.","operationId":"putContent","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetContent"}},{"name":"If-Match","in":"header","description":"If-Match","required":false,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"object"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/{dataSetName}/members":{"get":{"tags":["Data Sets V1 APIs"],"summary":"Get a list of members for a partitioned data set","description":"This API returns a list of members for a given partitioned data set.","operationId":"getMembers","produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Partitioned data set name","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«string»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/{filter}":{"get":{"tags":["Data Sets V1 APIs"],"summary":"Get a list of data sets matching the filter","description":"This API returns the attributes of data sets matching the filter","operationId":"getDataSetAttributes","produces":["application/json"],"parameters":[{"name":"filter","in":"path","description":"Dataset filter string, e.g. HLQ.**, **.SUF, etc.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«DataSetAttributes»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/{filter}/list":{"get":{"tags":["Data Sets V1 APIs"],"summary":"Get a list of data sets without attributes matching the filter","description":"This API returns the list of data sets matching the filter","operationId":"getDataSets","produces":["application/json"],"parameters":[{"name":"filter","in":"path","description":"Dataset filter string, e.g. HLQ.**, **.SUF, etc.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«DataSet»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/datasets/{oldDataSetName}/rename":{"put":{"tags":["Data Sets V1 APIs"],"summary":"Rename of a sequential data set, or PDS member","description":"This API renames data set or partitioned data set member.","operationId":"renameContent","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"oldDataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetRenameRequest"}}],"responses":{"200":{"description":"Ok"},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/unixfiles":{"get":{"tags":["Unix Files APIs V1"],"summary":"Get a list of a directories contents","description":"This API gets a list of files and directories for a given path","operationId":"getDirectoryListing","produces":["application/json"],"parameters":[{"name":"path","in":"query","description":"Path of Directory to be listed","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/UnixDirectoryAttributesWithChildren"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/unixfiles/{path}/**":{"get":{"tags":["Unix Files APIs V1"],"summary":"Get the contents of a Unix file","description":"This API gets a the contetns of a Unix file. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes and not include wild card characters","operationId":"getUnixFileContents","produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"name":"Convert","in":"header","description":"Convert","required":false,"type":"boolean"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/UnixFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"post":{"tags":["Unix Files APIs V1"],"summary":"Create a new Unix File or Diretory","description":"This API will create a new UnixFile or Directory. Try it out function not functional due to encoding of slashes and auto insertion of wildcard characters, an example request path would be /api/v1/unixFiles/u/ibmuser/newDirectory","operationId":"postUnixFileOrDirectory","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/UnixCreateAssetRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Created","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["Unix Files APIs V1"],"summary":"Update the contents of a Unix file","description":"This API will update the contents of a Unix file. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes and not include wild card characters","operationId":"putUnixFileContents","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/UnixFileContent"}},{"name":"If-Match","in":"header","description":"If-Match","required":false,"type":"string"},{"name":"Convert","in":"header","description":"Convert","required":false,"type":"boolean"}],"responses":{"200":{"description":"Ok","schema":{"type":"object"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["Unix Files APIs V1"],"summary":"Delete a Unix file","description":"This API deletes a Unix file or directory. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes","operationId":"deleteUnixFile","produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"name":"recursive","in":"header","description":"recursive","required":false,"type":"boolean","default":false}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"204":{"description":"Unix file successfully deleted","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v2/datasets":{"post":{"tags":["Data Sets V2 APIs"],"summary":"Create a data set","description":"This creates a data set based on the attributes passed in","operationId":"createDataSetUsingPOST_1","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetCreateRequest"}}],"responses":{"201":{"description":"Data set successfully created","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/datasets/{dataSetName}":{"delete":{"tags":["Data Sets V2 APIs"],"summary":"Delete a data set or member","description":"This API deletes a data set or data set member.","operationId":"deleteDatasetMemberUsingDELETE_1","produces":["*/*"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name","required":true,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"204":{"description":"Data set or member successfully deleted","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v2/datasets/{dataSetName}/content":{"get":{"tags":["Data Sets V2 APIs"],"summary":"Get the content of a sequential data set, or PDS member","description":"This API reads content from a sequential data set or member of a partitioned data set.","operationId":"getContent_1","produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/DataSetContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["Data Sets V2 APIs"],"summary":"Sets the content of a sequential data set, or PDS member","description":"This API writes content to a sequential data set or partitioned data set member.","operationId":"putContent_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetContent"}},{"name":"If-Match","in":"header","description":"If-Match","required":false,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"object"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/datasets/{dataSetName}/members":{"get":{"tags":["Data Sets V2 APIs"],"summary":"Get a list of members for a partitioned data set","description":"This API returns a list of members for a given partitioned data set.","operationId":"getMembers_1","produces":["application/json"],"parameters":[{"name":"dataSetName","in":"path","description":"Partitioned data set name","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«string»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/datasets/{filter}":{"get":{"tags":["Data Sets V2 APIs"],"summary":"Get a list of data sets matching the filter","description":"This API returns the attributes of data sets matching the filter","operationId":"getDataSetAttributes_1","produces":["application/json"],"parameters":[{"name":"filter","in":"path","description":"Dataset filter string, e.g. HLQ.**, **.SUF, etc.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«DataSetAttributes»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/datasets/{filter}/list":{"get":{"tags":["Data Sets V2 APIs"],"summary":"Get a list of data sets without attributes matching the filter","description":"This API returns the list of data sets matching the filter","operationId":"getDataSets_1","produces":["application/json"],"parameters":[{"name":"filter","in":"path","description":"Dataset filter string, e.g. HLQ.**, **.SUF, etc.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/ItemsWrapper«DataSet»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/datasets/{oldDataSetName}/rename":{"put":{"tags":["Data Sets V2 APIs"],"summary":"Rename of a sequential data set, or PDS member","description":"This API renames data set or partitioned data set member.","operationId":"renameContent_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"oldDataSetName","in":"path","description":"Data set name, e.g. HLQ.PS or HLQ.PO(MEMBER)","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/DataSetRenameRequest"}}],"responses":{"200":{"description":"Ok"},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/unixfiles":{"get":{"tags":["Unix Files APIs V2"],"summary":"Get a list of a directories contents","description":"This API gets a list of files and directories for a given path","operationId":"getDirectoryListing_1","produces":["application/json"],"parameters":[{"name":"path","in":"query","description":"Path of Directory to be listed","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/UnixDirectoryAttributesWithChildren"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/unixfiles/{path}/**":{"get":{"tags":["Unix Files APIs V2"],"summary":"Get the contents of a Unix file","description":"This API gets a the contetns of a Unix file. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes and not include wild card characters","operationId":"getUnixFileContents_1","produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"name":"Convert","in":"header","description":"Convert","required":false,"type":"boolean"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/UnixFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"post":{"tags":["Unix Files APIs V2"],"summary":"Create a new Unix File or Diretory","description":"This API will create a new UnixFile or Directory. Try it out function not functional due to encoding of slashes and auto insertion of wildcard characters, an example request path would be /api/v1/unixFiles/u/ibmuser/newDirectory","operationId":"postUnixFileOrDirectory_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/UnixCreateAssetRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Created","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["Unix Files APIs V2"],"summary":"Update the contents of a Unix file","description":"This API will update the contents of a Unix file. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes and not include wild card characters","operationId":"putUnixFileContents_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"in":"body","name":"input","description":"input","required":true,"schema":{"$ref":"#/definitions/UnixFileContent"}},{"name":"If-Match","in":"header","description":"If-Match","required":false,"type":"string"},{"name":"Convert","in":"header","description":"Convert","required":false,"type":"boolean"}],"responses":{"200":{"description":"Ok","schema":{"type":"object"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["Unix Files APIs V2"],"summary":"Delete a Unix file","description":"This API deletes a Unix file or directory. Try it out function will not work due to the encoding of forward slashes, it should be noted that requests to this endpoint should only contain unencoded slashes","operationId":"deleteUnixFile_1","produces":["application/json"],"parameters":[{"name":"path","in":"path","description":"path","required":true,"type":"string"},{"name":"recursive","in":"header","description":"recursive","required":false,"type":"boolean","default":false}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"204":{"description":"Unix file successfully deleted","schema":{"type":"object"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}},"definitions":{"DataSet":{"type":"object","required":["name"],"properties":{"migrated":{"type":"boolean","example":false,"description":"Whether the data set is migrated","allowEmptyValue":false},"name":{"type":"string","description":"Data set name","allowEmptyValue":false}},"title":"DataSet","description":"List of data set"},"DataSetAttributes":{"type":"object","required":["name","recordFormat","recordLength"],"properties":{"allocatedSize":{"type":"integer","format":"int32","description":"Allocate size, sizex","allowEmptyValue":false},"allocationUnit":{"type":"string","description":"Unit of space allocation, alcunit, spaceu","allowEmptyValue":false,"enum":["TRACK","CYLINDER","BLOCK","BYTE","KILOBYTE","MEGABYTE","RECORD"]},"averageBlock":{"type":"integer","format":"int32","description":"Average block","allowEmptyValue":false},"blockSize":{"type":"integer","format":"int32","description":"Block size, blksize","allowEmptyValue":false},"catalogName":{"type":"string","description":"Catalog name, catnm","allowEmptyValue":false},"creationDate":{"type":"string","description":"Creation date, cdate","allowEmptyValue":false},"dataSetOrganization":{"type":"string","description":"Data set organization","allowEmptyValue":false,"enum":["PO","POU","PO_E","PS","PS_E","PS_L","PSU","VSAM","VSAM_E","HFS","ZFS","DA","DAU"]},"deviceType":{"type":"string","description":"Device type","allowEmptyValue":false},"directoryBlocks":{"type":"integer","format":"int32","description":"Number of directory blocks, dirblk","allowEmptyValue":false},"expirationDate":{"type":"string","description":"Expiration date, edate","allowEmptyValue":false},"migrated":{"type":"boolean","example":false,"description":"Whether the data set is migrated","allowEmptyValue":false},"name":{"type":"string","description":"Data set name","allowEmptyValue":false},"primary":{"type":"integer","format":"int32","description":"Primary space allocation","allowEmptyValue":false},"recordFormat":{"type":"string","description":"Record format, recfm","allowEmptyValue":false},"recordLength":{"type":"integer","format":"int32","description":"Record length, lrecl","allowEmptyValue":false},"secondary":{"type":"integer","format":"int32","description":"Secondary space allocation","allowEmptyValue":false},"used":{"type":"integer","format":"int32","description":"Percentage of allocation used","allowEmptyValue":false},"volumeSerial":{"type":"string","description":"Volume serial","allowEmptyValue":false}},"title":"DataSetAttributes","description":"Attributes of a data set"},"DataSetContent":{"type":"object","required":["records"],"properties":{"records":{"type":"string","example":"//TESTJOBX JOB (),MSGCLASS=Hn// EXEC PGM=IEFBR14","description":"The content of the data set, with \n for new lines","allowEmptyValue":false}},"title":"DataSetContent","description":"Data Set file content"},"DataSetCreateRequest":{"type":"object","required":["allocationUnit","dataSetOrganization","name","primary","recordFormat","recordLength","secondary"],"properties":{"allocationUnit":{"type":"string","example":"TRACK","description":"Unit of space allocation, alcunit, spaceu","allowEmptyValue":false,"enum":["TRACK","CYLINDER","BLOCK","BYTE","KILOBYTE","MEGABYTE","RECORD"]},"averageBlock":{"type":"integer","format":"int32","example":500,"description":"Average block","allowEmptyValue":false},"blockSize":{"type":"integer","format":"int32","example":400,"description":"Block size, blksize","allowEmptyValue":false},"dataSetOrganization":{"type":"string","example":"PO","description":"Data set organization","allowEmptyValue":false,"enum":["PO","POU","PO_E","PS","PS_E","PS_L","PSU","VSAM","VSAM_E","HFS","ZFS","DA","DAU"]},"deviceType":{"type":"string","example":3390,"description":"Device type, unit","allowEmptyValue":false},"directoryBlocks":{"type":"integer","format":"int32","example":5,"description":"Number of directory blocks, dirblk. Only valid for partitioned data sets","allowEmptyValue":false},"name":{"type":"string","example":"HLQ.ZOWE","description":"Data set name","allowEmptyValue":false},"primary":{"type":"integer","format":"int32","example":10,"description":"Primary space allocation","allowEmptyValue":false},"recordFormat":{"type":"string","example":"FB","description":"Record format, recfm","allowEmptyValue":false},"recordLength":{"type":"integer","format":"int32","example":80,"description":"Record length, lrecl","allowEmptyValue":false},"secondary":{"type":"integer","format":"int32","example":5,"description":"Secondary space allocation","allowEmptyValue":false},"volumeSerial":{"type":"string","example":"zmf046","description":"Volume serial","allowEmptyValue":false}},"title":"DataSetCreateRequest","description":"Attributes of a data set to be created"},"DataSetRenameRequest":{"type":"object","required":["newName"],"properties":{"newName":{"type":"string","example":"HLQ.ZOWE or HLQ.ZOWE(mem1)","description":"new dataset name","allowEmptyValue":false}},"title":"DataSetRenameRequest","description":"Reaname data set request payload with attributes from-dataset to-dataset"},"ItemsWrapper«DataSetAttributes»":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/DataSetAttributes"}}},"title":"ItemsWrapper«DataSetAttributes»"},"ItemsWrapper«DataSet»":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/DataSet"}}},"title":"ItemsWrapper«DataSet»"},"ItemsWrapper«string»":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"title":"ItemsWrapper«string»"},"UnixCreateAssetRequest":{"type":"object","required":["type"],"properties":{"permissions":{"type":"string","example":"rwxrw-r--","description":"Access Mode for new asset","allowEmptyValue":false},"type":{"type":"string","example":"FILE","description":"Unix Entity type, File or Directory","allowEmptyValue":false,"enum":["FILE","DIRECTORY"]}},"title":"UnixCreateAssetRequest","description":"Unix File or Directory attributes for creation"},"UnixDirectoryAttributesWithChildren":{"type":"object","required":["children","group","lastModified","owner","permissionsSymbolic","size","type"],"properties":{"children":{"type":"array","description":"Children","allowEmptyValue":false,"items":{"$ref":"#/definitions/UnixDirectoryChild"}},"group":{"type":"string","description":"Group","allowEmptyValue":false},"lastModified":{"type":"string","description":"Last Modified","allowEmptyValue":false},"owner":{"type":"string","description":"Owner","allowEmptyValue":false},"permissionsSymbolic":{"type":"string","description":"Symbolic permissions","allowEmptyValue":false},"size":{"type":"integer","format":"int32","description":"Size on disk","allowEmptyValue":false},"type":{"type":"string","description":"Type","allowEmptyValue":false,"enum":["FILE","DIRECTORY"]}},"title":"UnixDirectoryAttributesWithChildren","description":"Attributes of a Unix Directory with its children"},"UnixDirectoryChild":{"type":"object","required":["lastModified","link","name","size","type"],"properties":{"lastModified":{"type":"string","description":"lastModified","allowEmptyValue":false},"link":{"type":"string","description":"Link","allowEmptyValue":false},"name":{"type":"string","description":"Path","allowEmptyValue":false},"size":{"type":"integer","format":"int32","description":"size","allowEmptyValue":false},"type":{"type":"string","description":"type","allowEmptyValue":false,"enum":["FILE","DIRECTORY"]}},"title":"UnixDirectoryChild","description":"Child of a unix directory"},"UnixFileContent":{"type":"object","required":["content"],"properties":{"content":{"type":"string","example":"Hello World","description":"The content of the unix file","allowEmptyValue":false}},"title":"UnixFileContent","description":"Unix file content"},"Username":{"type":"object","properties":{"username":{"type":"string"}},"title":"Username"}}} diff --git a/api_definitions/jobs.json b/api_definitions/jobs.json deleted file mode 100644 index 6f32493481..0000000000 --- a/api_definitions/jobs.json +++ /dev/null @@ -1,2 +0,0 @@ -{"swagger":"2.0","info":{"description":"REST API for the JES Jobs Service","version":"1.0","title":"JES Jobs API"},"host":"zzow01.zowe.marist.cloud:7600","basePath":"/","tags":[{"name":"JES job APIs V1","description":"Jobs Controller V 1"},{"name":"JES job APIs V2","description":"Jobs Controller V 2"}],"paths":{"/api/v1/jobs":{"get":{"tags":["JES job APIs V1"],"summary":"Get a list of jobs","description":"This API returns the a list of jobs for a given prefix and owner.","operationId":"getJobs","produces":["application/json"],"parameters":[{"name":"prefix","in":"query","description":"Job name prefix. If omitted, defaults to *.","required":false,"type":"string","default":"*"},{"name":"owner","in":"query","description":"Job owner. Defaults to requesters userid.","required":false,"type":"string"},{"name":"status","in":"query","description":"Job status to filter on, defaults to ALL.","required":false,"type":"string","enum":["ACTIVE","OUTPUT","INPUT","ALL"]}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/Job"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["JES job APIs V1"],"summary":"Given a list of jobs issue a Modify command for each","description":"This API modifies all jobs provided","operationId":"modifyJobs","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/ModifyMultipleJobsRequest"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"202":{"description":"Job modifies requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["JES job APIs V1"],"summary":"Given a list of jobs Cancel and Purge them all","description":"This API purges all jobs provided","operationId":"purgeJobs","produces":["application/json"],"parameters":[{"in":"body","name":"jobList","description":"jobList","required":true,"schema":{"type":"array","items":{"$ref":"#/definitions/SimpleJob"}}}],"responses":{"200":{"description":"OK"},"204":{"description":"Job purges succesfully requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v1/jobs/dataset":{"post":{"tags":["JES job APIs V1"],"summary":"Submit a job given a data set","description":"This API submits a partitioned data set member or Unix file. For fully qualified data set members use MYJOBS.TEST.CNTL(TESTJOBX). For Unix files use /u/myjobs/job1.","operationId":"submitJob","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/SubmitJobFileRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Job successfully created","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/string":{"post":{"tags":["JES job APIs V1"],"summary":"Submit a job given a string of JCL","description":"This API submits a job given jcl as a string","operationId":"submitJob_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/SubmitJobStringRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Job successfully created","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/username":{"get":{"tags":["System APIs","JES job APIs V1"],"summary":"Get current userid","description":"This API returns the callers current TSO userid.","operationId":"getCurrentUserName","produces":["application/json"],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/Username"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/{jobName}/{jobId}":{"get":{"tags":["JES job APIs V1"],"summary":"Get the details of a job for a given job name and identifier","description":"This API returns the details of a job for a given job name and identifier.","operationId":"getJobByNameAndId","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["JES job APIs V1"],"summary":"Modify a job","description":"This API modifies a job (cancel, hold, release)","operationId":"modifyJob","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier","required":true,"type":"string"},{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/ModifyJobRequest"}}],"responses":{"200":{"description":"Job modified"},"201":{"description":"Created"},"202":{"description":"Job modify requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["JES job APIs V1"],"summary":"Cancel a Job and Purge its associated files","description":"This API purges a Job","operationId":"purgeJob","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier","required":true,"type":"string"}],"responses":{"200":{"description":"OK"},"204":{"description":"Job purge succesfully requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v1/jobs/{jobName}/{jobId}/files":{"get":{"tags":["JES job APIs V1"],"summary":"Get a list of output file names for a job","description":"This API returns the output file names for a given job.","operationId":"getJobOutputFiles","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/JobFile"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/{jobName}/{jobId}/files/content":{"get":{"tags":["JES job APIs V1"],"summary":"Get the contents of all job output files for a given job","description":"This API reads the contents of all job files of a given job.","operationId":"getConcatenatedJobOutputFiles","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/JobFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/{jobName}/{jobId}/files/{fileId}/content":{"get":{"tags":["JES job APIs V1"],"summary":"Get content from a specific job output file","description":"This API reads content from a specific job output file. The API can read all output, or a relative record range.","operationId":"getJobOutputFile","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"},{"name":"fileId","in":"path","description":"Job file id.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/JobFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v1/jobs/{jobName}/{jobId}/steps":{"get":{"tags":["JES job APIs V1"],"summary":"Get job steps for a given job","description":"This API returns the step name and executed program for each job step for a given job name and identifier.","operationId":"getJobSteps","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/JobStep"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs":{"get":{"tags":["JES job APIs V2"],"summary":"Get a list of jobs","description":"This API returns the a list of jobs for a given prefix and owner.","operationId":"getJobs_1","produces":["application/json"],"parameters":[{"name":"prefix","in":"query","description":"Job name prefix. If omitted, defaults to *.","required":false,"type":"string","default":"*"},{"name":"owner","in":"query","description":"Job owner. Defaults to requesters userid.","required":false,"type":"string"},{"name":"status","in":"query","description":"Job status to filter on, defaults to ALL.","required":false,"type":"string","enum":["ACTIVE","OUTPUT","INPUT","ALL"]}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/Job"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["JES job APIs V2"],"summary":"Given a list of jobs issue a Modify command for each","description":"This API modifies all jobs provided","operationId":"modifyJobs_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/ModifyMultipleJobsRequest"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"202":{"description":"Job modifies requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["JES job APIs V2"],"summary":"Given a list of jobs Cancel and Purge them all","description":"This API purges all jobs provided","operationId":"purgeJobs_1","produces":["application/json"],"parameters":[{"in":"body","name":"jobList","description":"jobList","required":true,"schema":{"type":"array","items":{"$ref":"#/definitions/SimpleJob"}}}],"responses":{"200":{"description":"OK"},"204":{"description":"Job purges succesfully requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v2/jobs/dataset":{"post":{"tags":["JES job APIs V2"],"summary":"Submit a job given a data set","description":"This API submits a partitioned data set member or Unix file. For fully qualified data set members use MYJOBS.TEST.CNTL(TESTJOBX). For Unix files use /u/myjobs/job1.","operationId":"submitJob_2","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/SubmitJobFileRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Job successfully created","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs/string":{"post":{"tags":["JES job APIs V2"],"summary":"Submit a job given a string of JCL","description":"This API submits a job given jcl as a string","operationId":"submitJob_3","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/SubmitJobStringRequest"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Job successfully created","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs/{jobName}/{jobId}":{"get":{"tags":["JES job APIs V2"],"summary":"Get the details of a job for a given job name and identifier","description":"This API returns the details of a job for a given job name and identifier.","operationId":"getJobByNameAndId_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/Job"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"put":{"tags":["JES job APIs V2"],"summary":"Modify a job","description":"This API modifies a job (cancel, hold, release)","operationId":"modifyJob_1","consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier","required":true,"type":"string"},{"in":"body","name":"request","description":"request","required":true,"schema":{"$ref":"#/definitions/ModifyJobRequest"}}],"responses":{"200":{"description":"Job modified"},"201":{"description":"Created"},"202":{"description":"Job modify requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}},"delete":{"tags":["JES job APIs V2"],"summary":"Cancel a Job and Purge its associated files","description":"This API purges a Job","operationId":"purgeJob_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier","required":true,"type":"string"}],"responses":{"200":{"description":"OK"},"204":{"description":"Job purge succesfully requested"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}},"/api/v2/jobs/{jobName}/{jobId}/files":{"get":{"tags":["JES job APIs V2"],"summary":"Get a list of output file names for a job","description":"This API returns the output file names for a given job.","operationId":"getJobOutputFiles_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/JobFile"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs/{jobName}/{jobId}/files/content":{"get":{"tags":["JES job APIs V2"],"summary":"Get the contents of all job output files for a given job","description":"This API reads the contents of all job files of a given job.","operationId":"getConcatenatedJobOutputFiles_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/JobFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs/{jobName}/{jobId}/files/{fileId}/content":{"get":{"tags":["JES job APIs V2"],"summary":"Get content from a specific job output file","description":"This API reads content from a specific job output file. The API can read all output, or a relative record range.","operationId":"getJobOutputFile_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"},{"name":"fileId","in":"path","description":"Job file id.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/JobFileContent"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/v2/jobs/{jobName}/{jobId}/steps":{"get":{"tags":["JES job APIs V2"],"summary":"Get job steps for a given job","description":"This API returns the step name and executed program for each job step for a given job name and identifier.","operationId":"getJobSteps_1","produces":["application/json"],"parameters":[{"name":"jobName","in":"path","description":"Job name.","required":true,"type":"string"},{"name":"jobId","in":"path","description":"Job identifier.","required":true,"type":"string"}],"responses":{"200":{"description":"Ok","schema":{"type":"array","items":{"$ref":"#/definitions/JobStep"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}},"definitions":{"ItemsWrapper«JobFile»":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/JobFile"}}},"title":"ItemsWrapper«JobFile»"},"ItemsWrapper«Job»":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/Job"}}},"title":"ItemsWrapper«Job»"},"Job":{"type":"object","properties":{"executionClass":{"type":"string"},"jobId":{"type":"string"},"jobName":{"type":"string"},"owner":{"type":"string"},"phaseName":{"type":"string"},"returnCode":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","OUTPUT","INPUT","ALL"]},"subsystem":{"type":"string"},"type":{"type":"string"}},"title":"Job"},"JobFile":{"type":"object","properties":{"byteCount":{"type":"integer","format":"int64"},"ddName":{"type":"string"},"id":{"type":"integer","format":"int64"},"recordCount":{"type":"integer","format":"int64"},"recordFormat":{"type":"string"},"recordLength":{"type":"integer","format":"int64"}},"title":"JobFile"},"JobFileContent":{"type":"object","properties":{"content":{"type":"string"}},"title":"JobFileContent"},"JobStep":{"type":"object","properties":{"name":{"type":"string"},"program":{"type":"string"},"step":{"type":"integer","format":"int32"}},"title":"JobStep"},"ModifyJobRequest":{"type":"object","required":["command"],"properties":{"command":{"type":"string","example":"cancel","description":"The modify command, e.g. cancel, hold, release","allowEmptyValue":false}},"title":"ModifyJobRequest"},"ModifyMultipleJobsRequest":{"type":"object","required":["command","jobs"],"properties":{"command":{"type":"string","example":"cancel","description":"The modify command, e.g. cancel, hold, release","allowEmptyValue":false},"jobs":{"type":"array","example":[{"jobId":"job1234", "jobName":"TestJob"}],"description":"The list of jobs to receive the modify command","allowEmptyValue":false,"items":{"$ref":"#/definitions/SimpleJob"}}},"title":"ModifyMultipleJobsRequest"},"SimpleJob":{"type":"object","required":["jobId","jobName"],"properties":{"jobId":{"type":"string","example":"JOB00001","description":"The id of a job","allowEmptyValue":false},"jobName":{"type":"string","example":"TESTJOB","description":"The name of a job","allowEmptyValue":false}},"title":"SimpleJob"},"SubmitJobFileRequest":{"type":"object","required":["file"],"properties":{"file":{"type":"string","example":"ATLAS.TEST.JCL(TSTJ0001)","description":"The data set, or z/OS unix file to submit in form: in the form: ATLAS.TEST.JCL(TSTJ0001) for a data set, or /u/myjobs/job1 for z/OS unix file","allowEmptyValue":false}},"title":"SubmitJobFileRequest"},"SubmitJobStringRequest":{"type":"object","required":["jcl"],"properties":{"jcl":{"type":"string","example":"//TESTJOBX JOB (),MSGCLASS=H -// EXEC PGM=IEFBR14","description":"The jcl to be submitted, with n for new lines","allowEmptyValue":false}},"title":"SubmitJobStringRequest"},"Username":{"type":"object","properties":{"username":{"type":"string"}},"title":"Username"}}} diff --git a/docs/appendix/zowe-api-reference.md b/docs/appendix/zowe-api-reference.md index 87c4296cdf..79054bb92a 100644 --- a/docs/appendix/zowe-api-reference.md +++ b/docs/appendix/zowe-api-reference.md @@ -2,12 +2,8 @@ Find and learn about the Zowe APIs that you can use. -- **[REST API for the Data sets and z/OS Unix Files Services](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/datasets.json)** - - **[REST API for the API Gateway service](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/gateway.json)** -- **[REST API for the JES Jobs Service](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/jobs.json)** - - **[REST API for ZLUX Plug-in](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/zlux-plugin.json)** -- **[REST API for ZSS](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/swagger-zss.json)** +- **[REST API for ZLUX Plug-in](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/zlux-plugin.json)** diff --git a/docs/appendix/zowe-cli-command-reference.md b/docs/appendix/zowe-cli-command-reference.md index 87de1b1582..55a1537658 100644 --- a/docs/appendix/zowe-cli-command-reference.md +++ b/docs/appendix/zowe-cli-command-reference.md @@ -2,9 +2,10 @@ View detailed documentation on commands, actions, and options in Zowe CLI. You can read an interactive online version, download a PDF document, or download a ZIP file containing the HTML for the online version. -Currently, this reference documentation only contains the web help for -the Zowe CLI core component and CLI plug-ins maintained by Zowe. As third-party plug-ins are approved under the Zowe V2 LTS Conformance Program and contribute their web help to Zowe, we will update the documentation accordingly. To view the web help for V1 conformant plug-ins, click the version drop-menu on the top right corner of this page and click the link to any previous v1.xx.x version of this page. +This reference documentation is organized to contain the web help for Zowe CLI, CLI plug-ins maintained by Zowe, and Zowe V3 LTS-conformant third-party CLI plug-ins. As third-party plug-ins are approved under the Zowe V3 LTS Conformance Program and contribute their web help to Zowe, we update the documentation accordingly. -- Browse online -- Download CLI reference in PDF format -- Download CLI reference in ZIP format +To view the web help for V2 conformant plug-ins, click the version drop-menu on the top right corner of this page and click the link to any previous v2.xx.x version of this page. + +- Browse the interactive online version +- Download the CLI reference guide in PDF format +- Download the CLI reference guide in ZIP format diff --git a/docs/appendix/zowe-glossary.md b/docs/appendix/zowe-glossary.md index 234080b73b..1f4bc18337 100644 --- a/docs/appendix/zowe-glossary.md +++ b/docs/appendix/zowe-glossary.md @@ -10,7 +10,7 @@ Security is central to a wide range of functionalities in Zowe and includes nume For an overview of security in Zowe, see [the Zowe Security policy](https://www.zowe.org/security) on zowe.org. ::: -## Core Zowe Projects +## All Core Zowe Projects ### Zowe API Mediation Layer (API ML) @@ -47,11 +47,13 @@ Provides a command-line interface that lets you interact with the mainframe remo ### Zowe client projects -Includes all the Zowe projects that are installed on the user's PC. Also known as *Zowe client-side projects*. +Includes all the Zowe projects, or components, that are installed on the user's PC. Also known as *Zowe client-side projects* or *Zowe client-side components*. + +Examples include Zowe CLI, Zowe Explorer for Visual Studio Code, Zowe Explorer for IntelliJ IDEA, and Zowe Client SDKs. ### Zowe Client SDKs -Allow extenders to build applications on top of existing programmatic APIs such as z/OSMF. Currently supported client SDKs include Node.js (core), Kotlin/z/OSMF, Python, Swift, and Java. +Allow extenders to build applications on top of existing programmatic APIs such as z/OSMF. Currently supported client SDKs include Node.js (core), Kotlin, Python, Swift, and Java. ### Zowe Explorer @@ -169,9 +171,9 @@ Provides re-usable and industry-compliant JSON-formatted RMF/SMF data records so The set of programs (for example, `zwe` command) and utilities (for example, JCL, scripts) which manage the Zowe server configuration and components. The infrastructure standardizes the packaging of components and controls how they are started, stopped, and how configuration is provided to them. -#### Zowe IntelliJ Plug-in +#### Zowe Explorer plug-in for IntelliJ IDEA -Uses the IntelliJ IDE to provide the ability to work with z/OS data sets and USS files, and to explore and manage JES jobs. +Uses the IntelliJ IDEA platform IDEs to provide the ability to work with z/OS data sets, USS files, to explore and manage JES jobs and to work with TSO Console. #### Zowe Launcher @@ -201,7 +203,7 @@ The Zowe Support Provider Conformance Program gives vendors the ability to showc #### Base profile -A type of team configuration profile that stores connection information for use with one or more services. Your service profiles can pull information from base profiles as needed, to specify a common username and password only once. +An object in a team configuration file that stores connection information for use with one or more services. Depending on your configuration file type, the base profile can be either a `global_base` or `project_base` profile. Your service profiles can pull information from base profiles as needed, to specify a common username and password only once, for example. The base profile can optionally store tokens to connect to Zowe API Mediation Layer, which improves security by enabling Multi-Factor Authentication (MFA) and Single Sign-on (SSO). @@ -225,13 +227,17 @@ The standard z/OS Unix directory where Zowe logs are stored. It is specified in Use of z/OS UNIX services requires a z/OS UNIX security context, referred to as an OMVS segment, for the user ID associated with any unit of work requesting these services. To learn more consult [IBM Documentation](https://www.ibm.com/docs/en/zos/2.5.0?topic=profiles-omvs-segment-in-user). +#### Parent profile + +An object in a team configuration file that groups service profiles together that share the same properties and values (for example, hostname or credentials). A parent profile makes it possible to define properties for its group of service profiles in one place rather than duplicating values throughout a configuration. + #### Runtime directory The z/OS Unix directory for the [Zowe runtime](#zowe-runtime), specified in the Zowe configuration file via `zowe.runtimeDirectory`. Also the parent directory of the `zwe` command. #### Service profile -A type of team configuration profile that stores connection information for a specific mainframe service, such as IBM z/OSMF. Plug-ins can introduce other service profile types, such as the CICS profile to connect to IBM CICS. +An object in a team configuration file that stores connection information for a specific mainframe service, such as IBM z/OSMF. Plug-ins can introduce other service profile types, such as the CICS profile to connect to IBM CICS. #### SMP/E diff --git a/docs/appendix/zowe-yaml-configuration.md b/docs/appendix/zowe-yaml-configuration.md index 00f638a9be..cf356e0bba 100644 --- a/docs/appendix/zowe-yaml-configuration.md +++ b/docs/appendix/zowe-yaml-configuration.md @@ -1,13 +1,13 @@ # Zowe YAML server configuration file reference -Zowe v2 uses a YAML configuration file for server installation, configuration, and runtime. This file is usually referred to as the Zowe configuration YAML file or the `zowe.yaml` file. YAML is a human-friendly data serialization language for all programming languages. To learn more about YAML specifications, see [https://yaml.org/](https://yaml.org/). For a free, offline YAML validator to help validate your syntax, download the [Red Hat's VS Code YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). +Zowe v3 uses a YAML configuration file for server installation, configuration, and runtime. This file is usually referred to as the Zowe configuration YAML file or the `zowe.yaml` file. YAML is a human-friendly data serialization language for all programming languages. To learn more about YAML specifications, see [https://yaml.org/](https://yaml.org/). For a free, offline YAML validator to help validate your syntax, download the [Red Hat's VS Code YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). Content within the YAML file is documented by and validated against schema files which are shipped within Zowe and extended by Zowe extensions. For details on the schema technology and where to find the schema files within our source code, see [Using the Configuration Manager](../user-guide/configmgr-using.md#json-schema-validation). :::note -In the following sections, we refer to configuration keys by using the concatenation of key names and dots. For example, if you want to update the configuration key `zowe.certificate.keystore.type` with value `PKCS12`, you should set value for this entry in the `zowe.yaml`: +In the following sections, we refer to configuration keys by using the concatenation of key names and dots. For example, if you want to update the configuration key `zowe.certificate.keystore.type` with the value `PKCS12`, you should set the value for this entry in the `zowe.yaml`: ```yaml zowe: @@ -18,30 +18,6 @@ zowe: ::: -**Table of Contents** - -- [High-level overview of YAML configuration file](#high-level-overview-of-yaml-configuration-file) -- [Extract sharable configuration out of zowe.yaml](#extract-sharable-configuration-out-of-zoweyaml) -- [Configuration override](#configuration-override) -- [YAML configurations - certificate](#yaml-configurations---certificate) -- [YAML configurations - zowe](#yaml-configurations---zowe) -- [YAML configurations - java](#yaml-configurations---java) -- [YAML configurations - node](#yaml-configurations---node) -- [YAML configurations - zOSMF](#yaml-configurations---zosmf) -- [YAML configurations - components](#yaml-configurations---components) - - [Configure component gateway](#configure-component-gateway) - - [Configure component discovery](#configure-component-discovery) - - [Configure component api-catalog](#configure-component-api-catalog) - - [Configure component caching-service](#configure-component-caching-service) - - [Configure component app-server](#configure-component-app-server) - - [Configure component zss](#configure-component-zss) - - [Configure component jobs-api](#configure-component-jobs-api) - - [Configure component files-api](#configure-component-files-api) - - [Configure external extension](#configure-external-extension) -- [YAML configurations - haInstances](#yaml-configurations---hainstances) -- [Auto-generated environment variables](#auto-generated-environment-variables) -- [Troubleshooting your YAML with the Red Hat VSCode extension](#troubleshooting-your-yaml-with-the-red-hat-vs-code-extension) - ### High-level overview of YAML configuration file The YAML configuration file has few high-level sections: @@ -61,14 +37,13 @@ The YAML configuration file has few high-level sections: ### Extract sharable configuration out of zowe.yaml -The Zowe YAML configuration file supports splitting into several files or PARMLIB members when "zowe.useConfigmgr" is set to true. This can help simplify grouping configuration changes by type or owner. +The Zowe YAML configuration file supports splitting into several files or PARMLIB members. This can help simplify grouping configuration changes by type or owner. More details can be found [in the configmgr documentation.](../user-guide/configmgr-using.md#splitting-configuration-into-multiple-storage-types) - ### Creating portable references The Zowe YAML configuration file has template logic for relating one value to another, a system environment variable or symbol, or even to add conditional behavior. -This feature is available when "zowe.useConfigmgr" is set to true, and it can help to make your configuration portable between systems that need slightly different behavior while retaining the same configuration file. +It can help to make your configuration portable between systems that need slightly different behavior while retaining the same configuration file. More details can be found [in the configmgr documentation.](../user-guide/configmgr-using.md#configuration-templates) ### Configuration override @@ -129,7 +104,7 @@ Inside `zowe.yaml`, you can define default values and they may be overridden in ### YAML configurations - certificate -In Zowe YAML configuration, certificate definition shares the same format and this format can be used in several configuration entries. For example, `zowe.certificate`, `components..certificate`, and `haInstances..components..certificate`. The certificate definition may include the following entries: +In Zowe YAML configuration, the certificate definition shares the same format which can be used in several configuration entries. For example, `zowe.certificate`, `components..certificate`, and `haInstances..components..certificate`. The certificate definition may include the following entries: - **`keystore.type`** Defines the type of the keystore. If you are using keystore, this value usually should be `PKCS12`. If you are using keyring, this value should be `JCERACFKS`. @@ -329,7 +304,7 @@ zowe: - `zowe.setup.certificate.san` is the `Subject Alternative Name`(s) of the certificate if they are different from `zowe.externalDomains`. Note that for `JCERACFKS` type, with limitation of RACDCERT command, this should contain exact one hostname (domain) and one IP address. - `zowe.setup.certificate.importCertificateAuthorities` is the list of certificate authorities will be imported to Zowe `PKCS12` keystore or `JCERACFKS` keyring. Please note, for JCERACFKS type, only maximum 2 CAs is supported. If you are using `PKCS12` certificate, this should be USS files in PEM format. If you are using `JCERACFKS` certificate, this should be certificate labels on the z/OS system. -**For `PKCS12` certificate users,** +**For `PKCS12` certificate users** - `zowe.setup.certificate.pkcs12.directory` is the directory where you plan to store the PKCS12 keystore and truststore. This is required if `zowe.setup.certificate.type` is `PKCS12`. - `zowe.setup.certificate.pkcs12.lock` is a boolean configuration to tell if we should lock the PKCS12 keystore directory only for Zowe runtime user and group. The default value is true. @@ -338,7 +313,7 @@ zowe: - `zowe.setup.certificate.pkcs12.import.password` is the password for keystore defined in `zowe.setup.certificate.pkcs12.import.keystore`. - `zowe.setup.certificate.pkcs12.import.alias` is the original certificate alias defined in `zowe.setup.certificate.pkcs12.import.keystore`. After imported, the certificate will be saved as alias specified in `zowe.setup.certificate.pkcs12.name`. -**For `JCERACFKS` certificate (z/OS keyring) users,** +**For `JCERACFKS` certificate (z/OS keyring) users** - `zowe.setup.certificate.keyring.owner` is the keyring owner. It's optional and default value is `zowe.setup.security.users.zowe`. If it's also not defined, the default value is `ZWESVUSR`. - `zowe.setup.certificate.keyring.name` is the keyring name will be created on z/OS. This is required if `zowe.setup.certificate.type` is `JCERACFKS`. @@ -367,8 +342,15 @@ The high-level configuration `java` supports these definitions: - **`home`** Defines the path to the Java runtime directory. +### YAML configurations - node + +The high-level configuration `node` supports these definitions: + +- **`home`** + Defines the path to the Node.js runtime directory. + :::tip -Ensure the value of `node.home` in the `zowe.yaml` is visible to the Zowe STC users, and contains `bin/node`. +Ensure the value of `node.home` in the `zowe.yaml` is visible to the Zowe STC users, and contains `bin/node`. **Example:** ``` node: @@ -377,15 +359,6 @@ node: The above value is valid only when the path `/usrlppSysplex/nodejs/node-v12.16.1/bin/node` exists. If you observe output of `node:...FSUM7351 not found`, check to ensure that the value contains `bin/node`. ::: - - -### YAML configurations - node - -The high-level configuration `node` supports these definitions: - -- **`home`** - Defines the path to the Node.js runtime directory. - ### YAML configurations - zOSMF The high-level configuration `zOSMF` supports these definitions: @@ -418,36 +391,84 @@ These configurations can be used under the `components.gateway` section: Defines the port which the gateway should be started on. This must be a valid port number. - **`debug`** Defines whether to enable debug mode for the Gateway. -- **`apiml.service.allowEncodedSlashes`** - When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. -- **`apiml.service.corsEnabled`** - When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `gateway/api/v1/**`. -- **`apiml.service.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - - ::: +- **`apiml.connectionTimeout`** + Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used. +- **`apiml.connection.idleConnectionTimeoutSeconds`** + Specifies how long will the connection to southbound remains open without communication. The default value is 5 seconds. Unit is second. +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. - **`apiml.gateway.timeoutMillis`** Specifies the timeout for connection to the services in milliseconds. - **`apiml.security.x509.enabled`** Set this parameter to `true` to enable the client certificate authentication functionality through ZSS. - **`apiml.security.x509.externalMapperUrl`** Defines the URL where Gateway can query the mapping of client certificates. +- **`apiml.security.auth.jwt.customAuthHeader`** + Returns valid JWT header also in another header +- **`apiml.security.auth.passticket.customAuthHeader`** + Provides passtickets for the southbound service in the custom header +- **`apiml.security.auth.passticket.customUserHeader`** + Provides User Info when Passticket is provided in the custom header - **`apiml.security.auth.provider`** Defines the authentication provider used by the API Gateway. - **`apiml.security.authorization.endpoint.url`** - Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to the `APIML.SERVICES` profile of `ZOWE` class. -- **`apiml.security.ssl.verifySslCertificatesOfServices`** - Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. + Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to the `APIML.SERVICES` profile of `ZOWE` class. +- **`apiml.security.personalAccessToken.enabled`** + Enable Personal Access Tokens +- **`apiml.security.useInternalMapper`** + This property is the global feature toggle. Set the value to true to enable Internal Mapper +- **`apiml.security.oidc.enabled`** + Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality. + +- **`apiml.security.oidc.registry`** + Specifies the SAF registry used to group the identities recognized as having an OIDC identity mapping. The registry name is the string used during the creation of the mapping between the distributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration). + +- **`apiml.security.oidc.jwks.uri`** + Specifies the URI obtained from the authorization server's metadata where the Gateway will query for the JWK used to sign and verify the access tokens. + +- **`apiml.security.oidc.jwks.refreshInternalHours`** + Specifies the frequency in hours to refresh the JWK keys from the OIDC provider. Defaults to one hour. + +- **`apiml.security.oidc.identityMapperUser`** + (Optional) If the userId is different from the default Zowe runtime userId (`ZWESVUSR`), specify the `identityMapperUser` userId to configure API ML access to the external user identity mapper. + +:::note + +User authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. + +::: + +- **`apiml.security.oidc.identityMapperUrl`** + Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID. + This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe, but if you are using Zowe release 2.14 or a later version, we recommend you use the [API ML internal mapper](../../user-guide/authenticating-with-client-certificates.md#enabling-the-internal-api-ml-mapper). You can provide your own API to perform the mapping. In this case, it is necessary to customize this value. + + The following URL is the default value for Zowe and ZSS: + + ``` + https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/certificate/dn + ```- **`apiml.security.ssl.verifySslCertificatesOfServices`** + Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate if the certificate is trusted in truststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. - **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** - Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in turststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. -- **`apiml.server.maxConnectionsPerRoute`** - Specifies the maximum connections for each service. -- **`apiml.server.maxTotalConnections`** - Specifies the total connections for all services registered under API Mediation Layer. + Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in truststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. +- **`apiml.service.allowEncodedSlashes`** + When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. +- **`apiml.service.corsEnabled`** + When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `gateway/api/v1/**`. +- **`server.maxConnectionsPerRoute`** + Specifies the maximum connections for each service. +- **`server.maxTotalConnections`** + Specifies the total connections for all services registered under API Mediation Layer. +- **`server.ssl.enabled`** + This handles whether TLS is used +- **`server.webSocket.maxIdleTimeout`** + This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). +- **`server.webSocket.connectTimeout`** + This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). +- **`server.webSocket.asyncWriteTimeout`** + This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). +- **`server.webSocket.requestBufferSize`** + This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. + #### Configure component discovery @@ -457,14 +478,9 @@ These configurations can be used under the `components.discovery` section: Defines the port which discovery should be started on. This may be defined as a valid port number or as an offset from the Gateway component's port. To define an offset enter `"+{offset}"` or `"-{offset}"` as a string. The offset must start with `+` or `-`. - **`debug`** Defines whether to enable debug mode for the Discovery Service. -- **`apiml.service.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. The Zowe start script will ignore this value and always set it to `false`. - - ::: + +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. - **`apiml.security.ssl.verifySslCertificatesOfServices`** Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. - **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** @@ -476,7 +492,8 @@ These configurations can be used under the `components.discovery` section: - **`apiml.discovery.serviceIdPrefixReplacer`** Modifies the service ID of a service instance before it registers to API Mediation Layer. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with v2, based on Zowe v2 conformance. - +- **`server.ssl.enabled`** + This handles whether TLS is used #### Configure component api-catalog @@ -486,14 +503,27 @@ These configurations can be used under the `components.api-catalog` section: Defines the port which API Catalog should be started on. - **`debug`** Defines if we want to enable debug mode for the API Catalog. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable but with better granular level. -- **`environment.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - ::: +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. +- **`apiml.security.authorization.provider`** + Provider used for SAF resource check +- **`apiml.security.authorization.endpoint.url`** + Base path of endpoint's URL (`{base path}/{userId}/{class}/{entity}/{level}`) +- **`apiml.catalog.customStyle.logo`** + Specifies the location of the logo that will replace the default Zowe logo in the API Catalog header. The supported image formats are: `svg`, `png` and `jpg/jpeg`. +- **`apiml.catalog.customStyle.fontFamily`** + Specifies the font family to use across the API Catalog. +- **`apiml.catalog.customStyle.backgroundColor`** + Specifies the HTML color of the main background across the API Catalog +- **`apiml.catalog.customStyle.titlesColor`** + Specifies the title color. +- **`apiml.catalog.customStyle.headerColor`** + Specifies the HTML color of the header element in the API Catalog home page +- **`apiml.catalog.customStyle.textColor`** + Specifies the HTML color of the main text across the API Catalog +- **`apiml.catalog.customStyle.docLink`** + Specifies a custom link to be displayed in the header. Use this property to refer to applicable documentation. The format is `|` #### Configure component caching-service @@ -511,6 +541,18 @@ These configurations can be used under the `components.caching-service` section: Specifies eviction strategy to be used when the storage size is achieved. - **`storage.vsam.name`** Specifies the data set name of the caching service VSAM data set. +- **`storage.infinispan.initialHosts`** + + This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. + +- **`storage.infinispan.persistence.dataLocation`** + + The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store. + The default value is `data`. If you run the Caching Service in Highly Available mode and the instances use the same filesystem, you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). + +- **`storage.infinispan.jgroups.port`** + + The port number used by Infinispan to synchronise data among caching-service instances. - **`storage.redis.masterNodeUri`** Specifies the URI used to connect to the Redis master instance in the form `username:password@host:port`. - **`storage.redis.timeout`** @@ -528,15 +570,6 @@ These configurations can be used under the `components.caching-service` section: Specifies the truststore file used to keep other parties public keys and certificates. - **`storage.redis.ssl.truststorePassword`** Specifies the password used to unlock the truststore. -- **`environment.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - - ::: - - **`apiml.security.ssl.verifySslCertificatesOfServices`** Specifies whether APIML should verify certificates of services in strict mode. Set to `true` will enable `strict` mode that APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) match the service hostname. - **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** @@ -556,26 +589,6 @@ These configurations can be used under the `components.zss` section: - **`port`** Defines the port which ZSS should be started on. This may be defined as a valid port number or as an offset from the Gateway component's port. To define an offset enter `"+{offset}"` or `"-{offset}"` as a string. The offset must start with `+` or `-`. -#### Configure component jobs-api - -These configurations can be used under the `components.jobs-api` section: - -- **`port`** - Defines the port which Jobs API should be started on. This may be defined as a valid port number or as an offset from the Gateway component's port. To define an offset enter `"+{offset}"` or `"-{offset}"` as a string. The offset must start with `+` or `-`. - - - **`debug`** - Defines whether to enable debug logging for the Jobs API. - -#### Configure component files-api - -These configurations can be used under the `components.files-api` section: - -- **`port`** - Defines the port which Files API should be started on. This may be defined as a valid port number or as an offset from the Gateway component's port. To define an offset enter `"+{offset}"` or `"-{offset}"` as a string. The offset must start with `+` or `-`. - - - **`debug`** - Defines whether to enable debug logging for the Files API. - #### Configure external extension You can define a `components.` section and use common component configuration entries. @@ -619,10 +632,10 @@ Each line of Zowe YAML configuration will have a matching environment variable d * any non-alphabetic-numeric characters will be converted to underscore `_`, * and no double underscores like `__`. -For examples: +**Examples:** -- `ZWE_zowe_runtimeDirectory`, parent directory of where `zwe` server command is located. -- `ZWE_zowe_workspaceDirectory` is the path of user customized workspace directory. +- `ZWE_zowe_runtimeDirectory` is parent directory where `zwe` server command is located. +- `ZWE_zowe_workspaceDirectory` is the path of the user customized workspace directory. - `ZWE_zowe_setup_dataset_prefix` is the high-level qualifier where Zowe MVS data sets are installed. - `ZWE_zowe_setup_dataset_parmlib` is the data set configured to store customized version of parameter library members. - `ZWE_zowe_setup_dataset_authPluginLib` is the data set configured to store APF authorized ZIS plug-ins load library. diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md index 1ced6a027f..fc431b7ff5 100644 --- a/docs/contribute/contributing.md +++ b/docs/contribute/contributing.md @@ -10,7 +10,7 @@ Before contributing a documentation change to the repository, you should be fami * Slack: The Zowe Documentation team communicates using the Slack application. To learn about Slack, refer to the [Slack Help Center](https://slack.com/help). The Zowe team is part of the [Open Mainframe Project](https://openmainframeproject.slack.com) channel. * Markdown Language: The Zowe documentation is written in Markdown language. To learn about Markdown, refer to [The Markdown Guide](https://www.markdownguide.org/). -In addition to being familiar with the Zowe community and how we work together, you will need to sign the CNCF Contributor License Agreement. The Contributor License Agreement defines the terms under which you contribute to Zowe documentation. Contributions to Zowe documentation are reviewed before being committed to the repository. Committing changes to the Zowe repository requires additional access rights. See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe Documentation for more details about roles and permissions. +Contributions to Zowe documentation are reviewed before being committed to the repository. Commits needs to have Developer Certificate of Origin (DCO). Committing changes to the Zowe repository requires additional access rights. See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe Documentation for more details about roles and permissions. ## Getting started checklist diff --git a/docs/contribute/guidelines-code/categories.md b/docs/contribute/guidelines-code/categories.md index 30a534e380..bce5a942f8 100644 --- a/docs/contribute/guidelines-code/categories.md +++ b/docs/contribute/guidelines-code/categories.md @@ -17,9 +17,13 @@ For each area of the codebase, there are established and favored programming lan - **CLI** - Node.js, TypeScript - **Desktop UI** - Node.js, JavaScript - **APIs** - C, Assembler, Java, Spring -- **API Mediation Layer** - Java, Spring +- **API Mediation Layer** - Java, Spring, JavaScript -**Note:** JavaScript is not recommended and should be avoided in favor of Typescript to utilize typing. +:::note + +JavaScript is not recommended and should be avoided in favor of Typescript to utilize typing. + +::: ## Component-specific guidelines and tutorials diff --git a/docs/contribute/roadmap-contribute.md b/docs/contribute/roadmap-contribute.md index fdce094b8b..dcbbcbf6fb 100644 --- a/docs/contribute/roadmap-contribute.md +++ b/docs/contribute/roadmap-contribute.md @@ -52,7 +52,7 @@ Check out the contribution guidelines for different components and squads to lea - [Zowe Application Framework](https://github.com/zowe/zlux) - [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/blob/master/CONTRIBUTING.md) - [Zowe Client SDKs](https://github.com/zowe/zowe-cli/blob/master/docs/SDKGuidelines.md) - - [Zowe IntelliJ plug-in](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md) + - [Zowe Explorer plug-in for IntelliJ IDEA](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md) - [Zowe Docs](./contributing) ## Promote Zowe diff --git a/docs/extend/dynamic-static-registration-overview.md b/docs/extend/dynamic-static-registration-overview.md deleted file mode 100644 index 272a5f6fa1..0000000000 --- a/docs/extend/dynamic-static-registration-overview.md +++ /dev/null @@ -1,21 +0,0 @@ -# Dynamic and static registrtion overview - -Zowe API Mediation Layer extenders can build and onboard additional API services to the API ML microservices ecosystem. REST APIs can register with the API Mediation Layer, which makes them available in the API Catalog and for routing through the API Gateway. - -To register a z/OS service with the API Mediation Layer, there are two approaches: -- [Dynamic API registration](#dynamic-api-registration) -- [Static API registration](#static-api-registration) - -For information about how to onboard REST APIs, see the [Onboarding Overview](extend-apiml/onboard-overview.md). - -To streamline the process of onboarding new REST API services to the API Mediation Layer, see [Onboarding a REST API service with the YAML Wizard](../user-guide/onboard-wizard.md). - -### Dynamic API registration - -Registration of a REST API service to the API ML is performed through a call to the Discovery Service by sending registration data and metadata for the service being registered. Registration requires that the z/OS service must know the web address of the API ML Discovery Service. When Dynamic registration is performed, the service that performs the registration must periodically send heartbeat requests to the Discovery Service for each registered service instance. These heartbeat requests serve to renew the corresponding service instance registration with API ML. These requests enable the Discovery Service to monitor the availability of registered service instances. Services that are registered dynamically display the status of the service in the API Catalog after initial service registration. - -For more information about how to build a service which is able to register, see the [Onboarding Overview](extend-apiml/onboard-overview.md). - -### Static API registration - -For services that cannot be modified to be dynamically discoverable, it is possible onboard them to the API ML by providing the API ML a static definition file with API service details. This registration method does not require modifications to the existing API service code. For more information, see [Onboard a REST API without code changes required](extend-apiml/onboard-static-definition.md). Unlike services that use Dynamic API registration, the status of services onboarded through Static API registration is not displayed in the API Catalog. diff --git a/docs/extend/extend-api/ReactJSUI.md b/docs/extend/extend-api/ReactJSUI.md deleted file mode 100644 index cc66b211b4..0000000000 --- a/docs/extend/extend-api/ReactJSUI.md +++ /dev/null @@ -1,192 +0,0 @@ -# Creating a Zowe integrated ReactJS UI - -One of the great things about working with Zowe is that you can include any UI's that you have already developed in your Zowe Virtual Desktop. In this blog we look at how we do this and also show how to take advantage of a Restful API created on a JEE server within the Zowe environment. - -![](../../images/samples/reactjs/overview.png) - -Take a look at the [Creating a RestAPI with Swagger documentation using Liberty](./libertyAPI) tutorial for the background to the Restful API with Swagger documentation we will be using. - -## Prerequisite skills - -Knowledge of the following development technologies is beneficial: - -- React -- Redux -- Consuming Rest API's - -## Examining the App Structure - -First download the sample app found [here](https://github.com/zowe/webui-scenarios/tree/master/basic-react). We will not be examining the entire sample, but it is included as an example and boilerplate that can be built off of. - -Looking at the sample app their are 2 main sections that are important to us: - -- Constants.js -- actions/actions.js. - -### Constants.js - -Lets first examine Constants.js. - -```javascript -let host = ':' -if (typeof location !== 'undefined') { - const hostname = location.hostname - if (hostname !== 'localhost') { - host = location.host - } -} - -export const BASE_SERVER_URL = host -export const BASE_URL = `https://${host}` -export const BASE_WS_URL = `wss://${host}` -``` - -Notice that here we are setting our 'host' for the app. We are connecting to hypothetical server and the default port for the MVD 7445. This host then gets wrapped in a 'BASE_URL' constant that we can use in other sections of our app. Change this line to connect to your own server and port. - -### Actions.js - -Next lets look at calling our API created in the [creating a RestAPI with Swagger documentation using Liberty](./libertyAPI) tutorial. Following Redux structure, this call will be in our action.js file. We won't be looking at the entire file, but instead the relevant fetch request. - -```javascript -function fetchPosts(subreddit) { - return dispatch => { - dispatch(requestPosts(subreddit)) - let header = new Headers({ - 'Access-Control-Allow-Origin': '*', - 'Content-Type': 'multipart/form-data' - }) - return fetch(`${BASE_URL}/jzos/environmentVariable`, { - header: header, - credentials: 'include' - }) - .then(response => response.json()) - .then(json => dispatch(receivePosts(subreddit, json))) - .catch(error => console.log(error)) - } -} -``` - -Note that we are using the [fetch api](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to the grab the `environmentVariable` from the host that we defined before. We then make the rest of our app aware of the response using Redux's 'dispatch' method. - -## Adding your App to the MVD - -While the zlux environment comes with predefined "apps" and explorers, you also have the ability to extend the system and add your own apps. - -### Building your App for the MVD. - -Before we can place our app on the MVD, we need to first 'build' a production version of it and place it in a folder where Zowe can read it. -Zowe looks in a folder called 'web' when looking for an entry point to new apps. - -In order to build and prepare your app: - -1. Run the `build` script in `package.json` using: - - - `npm run build` - -2. Create a folder for your project and a new `web` folder inside it. - - - EX: `/Desktop/` and `Desktop//web` - -3. Copy built project into `Desktop//web` - - If using the sample, copy `app.min.js` , `index.html` , `icon.png` and `css` into to `/Desktop//web/` - -### Configuring your app for Zowe - -In order for Zowe to be aware of an app, a pluginDefintion.json file must be included in the root of the project. This file lets Zowe know information about the framework used, reference files, and basic configuration for the app. Lets take a look at our pluginDefinition: - -```json -{ - "identifier": "com.rs.basic-react", - "apiVersion": "1.0", - "pluginVersion": "1.0", - "pluginType": "application", - "webContent": { - "framework": "iframe", - "launchDefinition": { - "pluginShortNameKey": "basic-react", - "pluginShortNameDefault": "IFrame", - "imageSrc": "icon.png" - }, - "descriptionKey": "Sample App Showcasing IFrame Adapter", - "descriptionDefault": "Sample App Showcasing IFrame Adapter", - "startingPage": "index.html", - "isSingleWindowApp": true, - "defaultWindowStyle": { - "width": 800, - "height": 420, - "x": 200, - "y": 50 - } - }, - "dataServices": [] -} -``` - -Next add this pluginDefinition to the root of your project: - -- EX: `Desktop//` - -### Explaining the Plugin file system - -To add new apps, files must be added in two locations. - -- Zowe root (`/zaas1/zowe/`) -- Plugins Folder (`/zaas1/zowe//zlux-example-server/plugins`) - -Inside the 'Plugins Folder' we will add our identifier named `com.basic-react.json`. Inside this json file the **plugin location** and the **identifier name** are specified. Our identifier will look like this: - -```json -{ - "identifier": "com.rs.basic-react", - "pluginLocation": "../../" -} -``` - -To add our app to the file system: - -1. Copy project from `/Desktop` to `/` on your server - - - Use `scp @ /Users/path/to/files /` - - Alternatively this can be done using SFTP or the ZOS Explorer in binary mode. - -2. Create our identifier within the plugins folder (`/zlux-example-server/plugins`): - - - `touch com.basic-react.json` - -3. Edit file with vi to read: - -```json -{ - "identifier": "com.", - "pluginLocation": "../../" -} -``` - -### Deploying your App - -In order to deploy our newly added app, - -1. Run `./deploy.sh` found in `/zaas1/zowe//zlux-build` -2. Run `./zowe-stop.sh` found in `/zaas1/zowe//scripts` -3. Run `./zowe-start.sh` found in `/zaas1/zowe//scripts` - -## Setting up the server for Development - -:::warning -This next section should only be changed for development purposes. -::: - -While not necessary depending on your system configuration, often will need to allow our server to accept incoming connections and avoid CORS errors. - -In order to update the server to accept all connections: - -- Navigate to `/explorer-server/wlp/usr/servers/Atlas/server.xml` -- Open the file with vi and paste the following code in. - -```javascript - - - -``` - -After adding this section, navigate to `https://:/ZLUX/plugins/com.rs.mvd/web/` and you should see your new app added to the MVD! diff --git a/docs/extend/extend-api/api-intro.md b/docs/extend/extend-api/api-intro.md deleted file mode 100644 index a8cf14ddf8..0000000000 --- a/docs/extend/extend-api/api-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# API Extension Samples - -These samples show users how to create their own API's using a Node or Liberty Server. diff --git a/docs/extend/extend-api/existingAPI.md b/docs/extend/extend-api/existingAPI.md deleted file mode 100644 index 9507e3a311..0000000000 --- a/docs/extend/extend-api/existingAPI.md +++ /dev/null @@ -1,128 +0,0 @@ -# Onboarding existing Rest API Script - -(WORK IN PROGRESS) - -In this tutorial we consider how an organization with a product or tool with an existing Rest API can be rapidly Onboarded to Zowe™ by getting that product or tool registered with the API Gateway. This would then allow the product to be available from a central location and benefit from other Zowe API Mediation layer functionality. To do this we need a method for defining the service to the gateway - -As the example product we are using a simple Spring Boot sample app that can be downloaded here: [spring-boot-jzos-sample](https://github.com/zowe/spring-boot-jzos-sample). If you have your own example skip the "Get your app running" section we can adapt your script for that. - -## Overview -Apart from accessing your API's centrally through the Gateway, the Gateway provides manifest information about all accessible API's in it's catalog. For our static definition this information is retrieved from api definitions stored in yaml files. Although these files are simple in structure they would add more complexity for your customers when it comes to installing your product. Therefore we have developed a script that you can include with your product to simplify the process. - -### The Api definition file - -Key to registering your product to the gateway is the following file structure which is installed in the API mediation layer. It's not critical to understand everything here but provided for anyone who wishes to grasp every detail. - -```yaml -services: - - serviceId: jzos # internal id for the service - title: IBM z/OS jzos # Title as used in the Catalog information tiles - description: IBM z/OS jzos REST API service # Title as used in the Catalog information tiles - catalogUiTileId: jzos # internal id Catalog information tiles - instanceBaseUrls: - - https://host.my.com:2956/ # location of service - homePageRelativeUrl: # home page, leave blank if instanceBaseUrls is the same - routedServices: - - gatewayUrl: api/v1 # [api/ui/ws]/v{majorVersion} convention - serviceRelativeUrl: jzos # added to location - apiInfo: - - apiId: com.ibm.jzos # internal id - gatewayUrl: api/v1 # main reference - version: 1.0.0 # version of API on Gateway - documentationUrl: https://host.my.com:2956/swagger-ui.html # Applies if no swagger ui - swaggerUrl: https://host.my.com:2956/v2/api-docs # provides a link and generates swagger info - -catalogUiTiles: - jzos: # as per serviceId - internal id for the service - title: z/OS jzos services # tile label - description: IBM z/OS jzos REST services # tile description -``` - -This information together creates the catalog tile information -![](../../images/extender/tile.png) - - -By clicking on the tile the following information is presented. Note the swagger is generated from the swaggerUrl link which needs to be v2 swagger -![](../../images/extender/service.png) - -Although the most critical information, the redirection of the urls is under routed services along with the service id. -``` -routedServices.gatewayUrl+serviceId will point at instanceBaseUrls+serviceRelativeUrl -/jzos/api/v1 ==> https://host.my.com:2956/jzos -``` -## Getting the sample app running - -If you are using the sample follow the instructions in the readme to get it up and running on your z/OS machine. If using your own go to section 2. The sample generates swagger 2 documentation. - -## Modifying the Gateway script - -As described earlier we are registering our application with the API Catalog by way of a file that is read by the Gateway when it's started. We think of this as a static definition as the details of the service won't change whilst the gateway is running. To achieve a more dynamic relationship between the application and registry, one that can respond to changes in one or the other e.g. for load balancing purposes we need to construct the product differently. See [Onboarding from scratch](./existingApp). - -The information contained in the yaml definitions file abover requires input from both the onboarding organization (you) and the end user. Therefore the intent is to provide as much of the onboarder information into the script template so the end user has fewer choices to make. Therefore the script should be updated. - -[Onboard-to-gateway](https://github.com/zowe/Onboarding-scripts) - -The following fields need to be set - -````properties -################################################################################ -# The following fields to be filled in by implementing extenders team -################################################################################ -defaultServiceId="xtdrsvcid" # lowercase only -defaultTitle="Product name" -defaultDescription="Product description" -defaultCatalogUiTileId="xtdrCatalogUiTileId" -defaultHomePageRelativeUrl="" # Usually home page is the same as the base URL - -defaultGatewayUrl1="api/v1" -defaultServiceUrl1="api/v1/xtdrServiceId" -defaultGatewayUrl2="ui/v1" -defaultServiceUrl2="ui/v1/xtdrServiceId" -# Additional gateway and services will require further changes to script later - -defaultApiId="no.id.ea" -defaultGatewayUrl=$defaultGatewayUrl1 -defaultApiVersion="1.0.0" - -defaultCatalogTileTitle="My Product in catalog" -defaultCatalogTileDescription="My Product description in catalog" -```` - -##### defaultServiceId -This field is an internal identifier that needs to be unique across product instances. Therefore if you install multiple instances of your product this will also need to be incremented. Note it must be lowercase and is also used as part of the gateway uri -##### defaultTitle - -##### defaultDescription - -##### defaultCatalogUiTileId -This is the name that appears on the tab of the opened service - -##### defaultHomePageRelativeUrl -If the home page is not same as the base url add it in here - -##### defaultGatewayUrl(n) -This is the the gateway url that you want your redirect to work from. -You can create several defaultGatewayUrl/defaultServiceUrl pairings. Normally this would cater for api, web socket (ws) and ui. - -##### defaultServiceUrl(n) -The target url of the service - -##### defaultApiId -An internally used id. Suggest using com.co.yourprod etc. - -##### defaultGatewayUrl -Main url redirection for documentation - -##### defaultApiVersion -Version number of API if you wish to use it - -##### defaultCatalogTileTitle -The title that is displayed in the catalog pages - -##### defaultCatalogTileDescription -The description that is displayed in the catalog pages - -## How the Script works -Your updated shell script can now be run. This is how the process will appear to the end user. - - diff --git a/docs/extend/extend-api/existingApp.md b/docs/extend/extend-api/existingApp.md deleted file mode 100644 index 986062f158..0000000000 --- a/docs/extend/extend-api/existingApp.md +++ /dev/null @@ -1,7 +0,0 @@ -# Onboarding from scratch - -In this tutorial we consider how an organization with a product existing or under development with no pre-existing Rest API can be Onboarded to Zowe™. This would then allow the product to be available from a central location and benefit from other Zowe API Mediation layer functionality. - -At this stage of your development you have more options and can design with Zowe in mind. - -As the example product we are using a simple Spring Boot sample app that can be downloaded here: [spring-boot-jzos-sample](https://github.com/zowe/spring-boot-jzos-sample) \ No newline at end of file diff --git a/docs/extend/extend-api/liberty-api-sample.md b/docs/extend/extend-api/liberty-api-sample.md deleted file mode 100644 index 72c6fc520a..0000000000 --- a/docs/extend/extend-api/liberty-api-sample.md +++ /dev/null @@ -1,44 +0,0 @@ -# Provide Liberty API Sample - -:::tip Github Sample Repo: -[rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample) -::: - -This sample is a boilerplate for creating Rest API's using a liberty. For more information, visit [Creating a RestAPI with Swagger documentation using Liberty](./libertyAPI). - -## To Install - -After creating or obtaining the REST API war file: - -1. Stop the Zowe server. - - - Navigate to `/scripts/` - - Run `./zowe-stop.sh` - -2. Push the war file up to the dropins folder using SCP, SFTP, or on Windows with Putty SCP (PSCP). - - _EX_: - `scp /path/to/warfile @:/explorer-server/wlp/usr/servers/Atlas/dropins/` - -:::tip -Use the USS, IDZ, or IBM Explorer for z/OS to confirm that your files have transferred. -::: - -3. Restart the Zowe server. - - - Navigate to `/scripts/` - - Run `./zowe-start.sh` - -## Verify Install - -1. Check the Browser to see if the REST APIs have been added. - - _EX_: `:/ibm/api/explorer/#/` - -view - -:::tip -Make sure to set file transfer mode to binary before the transfer. -After transferring the WAR file, check the permission on the file by running -ls -la -If the read permission is not set, turn on the read permission by running, -chmod +r javazos-sample.war -::: diff --git a/docs/extend/extend-api/libertyAPI.md b/docs/extend/extend-api/libertyAPI.md deleted file mode 100644 index 0837ca9525..0000000000 --- a/docs/extend/extend-api/libertyAPI.md +++ /dev/null @@ -1,127 +0,0 @@ -# Creating a RestAPI with Swagger documentation using Liberty - -This tutorial will show you how to develop your own Zowe API's with Swagger notation. Although the resulting War file is "dropped into" a Liberty server, the same principles can be applied for other JEE servers. - -The source repo for the project can be found at the [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample). -This document describes how we can add new function and UI's to run alongside Zowe. - -So for example, as a team with an established z/OS application we may want to provide wider access to that functionality so that it can be exploited by different applications and organizations. This can include making functionality available to company DevOps processes or for inclusion in UI's. - -## Prerequisite skills - -Developers should be familiar with the following technologies: - -- Java -- Git and GitHub -- Maven - -Knowledge of the following development technologies is beneficial: - -- J2E -- Liberty or WebSphere Application Server -- Eclipse/z/OS Explorer -- RestAPI's -- zSystems development - -## Zowe API Architecture Overview - -Much of the Zowe infrastructure builds upon functionality provided by different applications and systems in z/OS some of which are microservices deployed on a Liberty server running on the Z system. As an example Zowe can access z/OSMF services that are aggregated with other functionality that provides new or more comprehensive functionality that allows new services to be created that also benefit from single-sign using **Lightweight Third Party** Authentication (LTPA) keys and centralized logging functions. - -The API for Zowe is written in Java utilizing JAX-RS: Java API for RESTful Web Services (JAX-RS). JAX-RS uses Java annotations to simplify the development and deployment of web service clients and endpoints and ultimately become rendered into swagger interfaces. - -## Building your own Microservice - -There are many publications and blogs regarding Microservice design -available and it's beyond our scope to attempt to cover here. Fundamentally, however you have most likely already performed an analysis of your product and have identified several notional business -areas or components that you are most interested in. One of the recommendations in developing Microservices is not to have one massive service but several services that represent component areas. One reason -would be Microservices that are not used or function is considered restricted can be excluded without affecting other function. - -Once you have identified areas of the functionality Microservices for the API's can be designed. Once again there are an -enormous amount of guidelines, Best practices, strict rules and design guides out there and I won't be prescriptive how you do this except to -say that you will spend a lot of time teasing out your API object names and considering how the REST functions (GET, PUT, POST and DELETE) apply -to these objects. Once ready or as long as we have the most basic Get Object API defined we can make a start at coding. - -An example below is intended to show how we apply the definitions of -the Rest API as Java Annotations around a Java method. - -```java - @PUT - @Path(value = "{attribute}") - @Produces(MediaType.APPLICATION_JSON) - @ApiOperation(value = "Updates the value of an existing environment variable", - notes = "This API uses JZOS to perform the process.") - @ApiResponses({ - @ApiResponse(code = 200, message = "Updated the environment variable")}) - public Response update( - @ApiParam(value = "Environment variable name", required = true) @PathParam("attribute") String attribute, - @ApiParam(value = "Value of an environmental variable") ValueParameter parameter) - { - jzosService.updateProperty(attribute, parameter) ; - return Response.status(Status.OK).build(); - } -``` - -Within the Liberty server we have configured a function "APIDiscovery" which at run time converts this into swagger format. - -![](../../images/guides/libertyAPI/swag.png) - -## Anatomy of a project - -Using [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample) as a guide. Create a Dynamic web project (don't specify it as part of an EAR if using the wizard), or if using a -Maven archetype choose one containing a simplified sample J2EE application. - -_Alternatively, use the project as a template. Download the code, rename it and use as the basis of your new project._ - -The image below indicates the type of structure you should be seeing although this contains more files and folders than you will have -initially it should give you the general idea. Don't worry about git or target at this stage they will appear later as you develop your project. - -![](../../images/guides/libertyAPI/struct1.png) - -Your project should be developed as a standalone war file and deployed either to a local server if you have no z dependencies (Hint: good to -start with). If using Eclipse and not yet using z/OS specific functionality consider setting up a test server within Eclipse and -automatically deploying your war to it. Fantastic for debugging. - -The alternative is to drop the war into the Dropins folder of an existing Zowe installation. - -It is possible to debug remotely using Eclipse but personally I have found this can lead to issues such as corrupt process locks in z/OS -requiring SysProg intervention. If you have quick access to SysProg rights you may be comfortable with this but often good old sysout is the -best debug support - -The example project uses Maven for its build process which will run locally or as part of a Jenkins build process. - -Further examples of implementations can be found looking at the code for the Zowe microservice. - -### Eclipse hint.. - -Using Maven to build in an Eclipse environment can leave your files full of red x's. Generally this is caused because the Eclipse compiler -mechanism has no visibility of dependencies described in the pom.xml file. There is a magic function to help with this. Right click on your -project and select the Maven Update option. This will allow the Eclipse project to be updated and get rid of many of the x's. - -![](../../images/guides/libertyAPI/menu1.png) - -### Generic jar files - -It is likely that the Zowe team will provide utility jar files that will either be present on the server or require specific inclusion as -described in 'Additional Jars'. Currently generic jar files such as Zowe utilities should be included in your war file. This may be revised -later based upon future requirements. - -## Unit Testing - -Aim for 100% coverage. In many cases it may be impossible or impractical to achieve either because code is auto-generated or covered in other -tests. Use Jacoco to highlight where there are gaps. - -Note the references to Jacoco in the atlas-jzos-sample pom.xml file. Remember it operates in two phases, initializing before the unit tests -are run and reporting afterwards. - -Examples of unit testing, the use of Mockito and PowerMock are in the src/test/java folder for the jzos sample. - -### FV testing - -For the purpose of testing applications in a live fully configured environment scenario it is necessary to create another testing specific -project. You will notice that only the src/main/tests folder is populated. When running a Maven build the tests contained here are -exercised. - -- Using the maven-archetype-quickstart as your Maven template or by creating a new Java project and adding the pom.xml file in Eclipse, - create a project to contain FV and/or Integration tests. - -- Alternatively, you can always download the code, rename it and use as the basis of your new project. diff --git a/docs/extend/extend-apiml/api-mediation-components-of-URL.md b/docs/extend/extend-apiml/api-mediation-components-of-URL.md deleted file mode 100644 index e4f3d9c7d1..0000000000 --- a/docs/extend/extend-apiml/api-mediation-components-of-URL.md +++ /dev/null @@ -1,100 +0,0 @@ -# Components of a URL - -This page provides definitions and a diagram to make sure everyone is using the same terms. To maintain consistency of the structure of URLs, Zowe seeks to establish standards around URLs and the elements that make up a URL. This article presents the standard terminology used in Swagger documentation. - -## Definitions - -REST APIs have a _baseUrl_ to which the endpoint paths are appended. The base URL is defined by _scheme_, _host_, _port_ and _basePath_ - -where: - -- **`baseUrl`** -Specifies an absolute URL prefix that is different for each instance of the service, or when the service is accessed via the API Gateway. - -The endpoint paths are relative paths that follow the documentation of the REST API. - -- **`scheme`** -Specifies the transfer protocols used by the API. API ML supports the `http`, `https`, and WebSocket schemes - `ws` and `wss`. - -- **`host`** -Specifies the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without a scheme or sub-paths. - -- **`basePath`** -Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`. If basePath is not specified then all endpoint paths start at the host root. - -When a service is accessed without the API Gateway then the format the `basePath` depends on the service. It can be empty or have several parts (e.g. `/fileMasterPlus/api/v1`). - -When a service is accessed via the API Gateway, the format of the URL is standardized in one of the following formats: - -- Using `serviceId`, service type (`t`) and major version (`v`) -- Using `serviceId` and service type (`t`) - -where: - -- **`serviceId`** -Specifies a unique name of the service that is set during the installation of the service. - -- **`t`** -Specifies the type of the service. It can be `api`, `ui`, or `ws` - -- **`v`** -Specifies the major version the REST API. - - **Example:** `v1`, `v2`. It is optional since some existing services can have versioning in the endpoint path. - -The fundamental principle is that by changing the base URL you can access different services with the same API because the structure after the base URL is the same. - -The base URL is the parameter the can be set in Zowe CLI in order to access the service. The endpoint path is prepared by the Zowe CLI plug-in but the base URL needs to be provided by the user based on installation of the REST API service. - -## Examples - -### URL to a service endpoint without API gateway - -```markup -http://ca11.ca.com:19876/fileMasterPlus/api/v1/mvs/dataSets/test/ping -\_____/\_______________/\____________________/\_____________________/ -scheme host basePath endpointPath -\____________________________________________/ - baseUrl -``` - -### URL with empty basePath - -```markup -https://ca32.ca.com:1443/zosmf/info -\_____/\_______________/\_________/ -scheme host endpointPath -\______________________/ - baseUrl -``` - -### URL to a service endpoint via API gateway - -```markup -https://ca3x.ca.com:10310/cafilemasterplus/api/v1/mvs/dataSets/test/ping -\______/\_______________/\______________________/\_____________________/ -scheme host basePath endpointPath - \______________/\__/\/ - serviceId t v - -\_______________________________________________/ - baseUrl - -``` - -### URL to a service endpoint via API gateway without version - -```markup -https://ca3x.ca.com:10310/zosmfca32/api/zosmf/info -\_____/\________________/\____________/\_________/ -scheme host basePath endpointPath - \________/\_/ - serviceId t - -\______________________/ - baseUrl -``` - -### Resources - -- For more information, see the documentation for [swagger specifications](https://swagger.io/docs/specification/2-0/api-host-and-base-path/) in the Swagger product documentation. diff --git a/docs/extend/extend-apiml/api-mediation-infinispan.md b/docs/extend/extend-apiml/api-mediation-infinispan.md index 763c882af0..8fef33ed2f 100644 --- a/docs/extend/extend-apiml/api-mediation-infinispan.md +++ b/docs/extend/extend-apiml/api-mediation-infinispan.md @@ -1,7 +1,9 @@ # Using Infinispan as a storage solution through the Caching service -As an API developer, you can configure Infinispan as a storage solution through the Caching service. This article describes how to configure your storage solution for Infinispan. -You can configure Infinispan for high availability as well as to replicate data to provide data durability and availability. +:::info Required roles: system administrator, security administrator +::: + +You can configure Infinispan as a storage solution through the Caching service, as well as configure Infinispan for high availability to replicate data to provide data durability and availability. - [Using Infinispan as a storage solution through the Caching service](#using-infinispan-as-a-storage-solution-through-the-caching-service) - [Understanding Infinispan](#understanding-infinispan) @@ -31,17 +33,30 @@ Configure Infinispan as a storage solution through the Caching service by settin This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. - either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. - * **`zowe.components.caching-service.storage.infinispan.persistence.dataLocation`** - The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store. - The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). + The path where the service keeps its data files for the Infinispan Soft-Index Cache Store. + The default value is `data`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the data property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). + + +* **`zowe.components.caching-service.storage.infinispan.persistence.indexLocation`** + + The path where the service keeps its index data for the Infinispan Soft-Index Cache Store. + The default value is `index`. If you run the Caching Service in HA and the instances use the same filesystem, you have to specify a different value of the index property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). * **`zowe.components.caching-service.storage.infinispan.jgroups.port`** - The port number used by Infinispan to synchronise data among cahing-service instances. + (OPTIONAL)The default value is `7600`. The port number used by Infinispan to synchronise data among cahing-service instances. + +* **`zowe.components.caching-service.storage.infinispan.jgroups.host`** + + (OPTIONAL)The default value is taken from zowe hostname. The hostname used by Infinispan to synchronise data among cahing-service instances. + + +* **`zowe.components.caching-service.storage.infinispan.keyExchange.port`** + + (OPTIONAL)The default value is `7601`. The port number used by Infinispan to exchange encryption key among cahing-service instances. **Example of Caching service HA configuration using Infinispan:** @@ -60,6 +75,7 @@ Configure Infinispan as a storage solution through the Caching service by settin port: 7098 persistence: dataLocation: /global/zowe/workspace/caching-service/data01 + indexLocation: global/zowe/workspace/caching-service/index01 lpar2: components: caching-service: @@ -71,4 +87,5 @@ Configure Infinispan as a storage solution through the Caching service by settin port: 7099 persistence: dataLocation: /global/zowe/workspace/caching-service/data02 + indexLocation: global/zowe/workspace/caching-service/index02 ``` \ No newline at end of file diff --git a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md index 9d2761772f..d637198844 100644 --- a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md +++ b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md @@ -10,5 +10,5 @@ The `Dummy Authentication Provider` implements simple authentication for develop Use the following property of the API Gateway to enable the `Dummy Authentication Provider`: ``` -components.gateway.security.auth.provider: dummy +components.gateway.apiml.security.auth.provider: dummy ``` diff --git a/docs/extend/extend-apiml/api-mediation-passtickets.md b/docs/extend/extend-apiml/api-mediation-passtickets.md index bf06738235..36369e33f9 100644 --- a/docs/extend/extend-apiml/api-mediation-passtickets.md +++ b/docs/extend/extend-apiml/api-mediation-passtickets.md @@ -1,6 +1,6 @@ # This article was changed and moved -The information that used to be in the article **Configuring Zowe to use PassTickets** has been reorganized and is available in following articles: +The information that used to be in the article **Configuring Zowe to use PassTickets** has been reorganized and is available in following articles: - For detailed information about configuring Zowe to use PassTickets, and to enable Zowe to use PassTickets to authenticate towards specific extending services, see [Enabling single sign on for extending services via PassTicket configuration](https://docs.zowe.org/stable/user-guide/api-mediation/configuration-extender-passtickets). diff --git a/docs/extend/extend-apiml/api-mediation-redis.md b/docs/extend/extend-apiml/api-mediation-redis.md index 2bf851af6e..61ce46b797 100644 --- a/docs/extend/extend-apiml/api-mediation-redis.md +++ b/docs/extend/extend-apiml/api-mediation-redis.md @@ -1,7 +1,9 @@ # Using Redis as a storage solution through the Caching service -As an API developer, you can configure Redis as a storage solution through the Caching service. This article describes how to configure your storage solution for Redis. -You can configure Redis for high availability as well as to replicate data to provide data durability and availability. +:::info Required roles: system administrator, security administrator +::: + +You can configure Redis as a storage solution through the Caching service, as well as configure Redis for high availability to replicate data to provide data durability and availability. - [Understanding Redis](#understanding-redis) - [Redis configuration](#redis-configuration) diff --git a/docs/extend/extend-apiml/api-mediation-vsam.md b/docs/extend/extend-apiml/api-mediation-vsam.md index 837de1e7ab..60cdafa621 100644 --- a/docs/extend/extend-apiml/api-mediation-vsam.md +++ b/docs/extend/extend-apiml/api-mediation-vsam.md @@ -1,7 +1,13 @@ -# Using VSAM as a storage solution through the Caching service +# Using VSAM as a storage solution through the Caching service **Deprecated** -As an API developer, you can configure VSAM as a storage solution through the Caching service. The procedure in this article -describes how to configure your storage solution for VSAM. Configuring VSAM ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage multiple caching services concurrently, whereby clients can retreive data through VSAM. +:::info Required roles: system administrator, security administrator +::: + +:::caution Important +VSAM as a storage solution is deprecated in Zowe V3, please use [Infinispan](./api-mediation-infinispan), which is packaged as part of the Caching Service. +::: + +In Zowe v2 or previous versions, it is possible to configure VSAM as a storage solution through the Caching service. Configuring VSAM ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage multiple caching services concurrently, whereby clients can retreive data through VSAM. - [Understanding VSAM](#understanding-vsam) - [VSAM configuration](#vsam-configuration) diff --git a/docs/extend/extend-apiml/onboard-plain-java-enabler.md b/docs/extend/extend-apiml/onboard-plain-java-enabler.md index 30995dd652..b5506293fc 100644 --- a/docs/extend/extend-apiml/onboard-plain-java-enabler.md +++ b/docs/extend/extend-apiml/onboard-plain-java-enabler.md @@ -1,6 +1,6 @@ -# Onboarding a REST API service with the Plain Java Enabler (PJE) +# Onboarding a REST or GraphQL API service with the Plain Java Enabler (PJE) -This article is part of a series of onboarding guides, which outline the process of onboarding REST API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built without a dependency on Spring Cloud, Spring Boot, or SpringFramework. +This article is part of a series of onboarding guides, which outline the process of onboarding REST or GraphQL API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a service with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built without a dependency on Spring Cloud, Spring Boot, or SpringFramework. :::tip For more information about onboarding API services with the API ML, see the [Onboarding Overview](onboard-overview.md). @@ -14,12 +14,12 @@ Zowe API ML is a lightweight API management system based on the following Netfli * Zuul - reverse proxy / API Gateway * Ribbon - load balancer -The API ML Discovery Service component uses Netflix/Eureka as a REST services registry. +The API ML Discovery Service component uses Netflix/Eureka as a services` registry. Eureka endpoints are used to register a service with the API ML Discovery Service. -The API ML provides onboarding enabler libraries. The libraries are JAR artifacts available through an artifactory. Using these libraries is the recommended approach to onboard a REST service with the API ML. +The API ML provides onboarding enabler libraries. The libraries are JAR artifacts available through an artifactory. Using these libraries is the recommended approach to onboard a REST or GraphQL service with the API ML. -The PJE library serves the needs of Java developers who are not using either [Spring Boot](https://spring.io/projects/spring-boot) or the [Spring Framework](https://spring.io/). If Spring Boot or the Spring framework are used in the project you would like to onboard, see the [Onboarding Overview](onboard-overview.md) for the corresponding enablers. +The PJE library serves the needs of Java developers who are not using either [Spring Boot](https://spring.io/projects/spring-boot) or the [Spring Framework](https://spring.io/). If Spring Boot or the Spring framework are used in the project you would like to onboard, see the [Onboarding Overview](onboard-overview.md) for the corresponding enablers. Additionally, this enabler is not intended for use in projects that depend on [Spring Cloud Netflix](https://spring.io/projects/spring-cloud-netflix) components. Configuration settings in the PJE and Spring Cloud Netflix Eureka Client are different. Using the two configuration settings in combination makes the result state of the discovery registry unpredictable. @@ -28,9 +28,9 @@ For more information about how to utilize another API ML enablers, see the docum the [Onboarding Overview](onboard-overview.md). ::: -## Onboarding your REST service with API ML +## Onboarding your REST or GraphQL service with API ML -The following steps outline the overall process to onboard a REST service with the API ML using the PJE. Each step is described in further detail in this article. +The following steps outline the overall process to onboard a service with the API ML using the PJE. Each step is described in further detail in this article. 1. [Prerequisites](#prerequisites) @@ -40,7 +40,7 @@ The following steps outline the overall process to onboard a REST service with t * [Maven build automation system](#maven-build-automation-system) 3. [Configuring your service](#configuring-your-service) - * [REST service identification](#rest-service-identification) + * [Service identification](#rest-service-identification) * [Administrative endpoints](#administrative-endpoints) * [API info](#api-info) * [API routing information](#api-routing-information) @@ -61,17 +61,17 @@ The following steps outline the overall process to onboard a REST service with t Ensure that the prerequisites from the [Onboarding Overview](onboard-overview.md) are met. -* The REST API service to onboard is written in Java +* The REST or GraphQL API service to onboard is written in Java * The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured connection :::noteNotes: * This documentation is valid for API ML version `ZoweApimlVersion 1.3.0` and higher. We recommend that you check the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for the latest stable versions. -* Following this guide enables REST services to be deployed on a z/OS environment. Deployment to a z/OS environment, however, is not required. As such, you can first develop on a local machine before you deploy on z/OS. + * Following this guide enables REST or GraphQL services to be deployed on a z/OS environment. Deployment to a z/OS environment, however, is not required. As such, you can first develop on a local machine before you deploy on z/OS. * The API Mediation Layer provides the sample application using the Plain Java Enabler in the [api-layer repository](https://github.com/zowe/api-layer/tree/v2.x.x/onboarding-enabler-java-sample-app) -::: + ::: ## Configuring your project @@ -112,7 +112,7 @@ Use the following procedure to use _Gradle_ as your build automation system. implementation "org.zowe.apiml.sdk:onboarding-enabler-java:$zoweApimlVersion" implementation "org.zowe.apiml.sdk:common-service-core:$zoweApimlVersion" ``` - The published artifact from the Zowe Artifactory also contains the enabler dependencies from other software packages. If you are using an artifactory other than Zowe, add also the following dependencies in your service `build.gradle` script: + The published artifact from the Zowe Artifactory also contains the enabler dependencies from other software packages. If you are using an artifactory other than Zowe, add also the following dependencies in your service `build.gradle` script: ```gradle implementation "com.netflix.eureka:eureka-client:1.10.15" @@ -124,7 +124,7 @@ Use the following procedure to use _Gradle_ as your build automation system. compileOnly "org.projectlombok:lombok:1.18.20" ``` - **Notes:** + **Notes:** * You may need to add more dependencies as required by your service implementation. * The information provided in this file is valid for `ZoweApimlVersion 1.3.0` and higher. @@ -149,7 +149,7 @@ Use the following procedure if you use _Maven_ as your build automation system. ``` - **Tip:** If you want to use snapshot version, replace `libs-release` with `libs-snapshot` in the repository url and change snapshots->enabled to `true`. + **Tip:** If you want to use snapshot version, replace `libs-release` with `libs-snapshot` in the repository url and change snapshots->enabled to `true`. 2. Add the proper dependencies: ```xml @@ -181,6 +181,8 @@ are in `${parameterValue}` format. For your service configuration file, provide **Example:** +**REST API** + ```yaml serviceId: sampleservice title: Hello API ML @@ -205,7 +207,7 @@ authentication: scheme: httpBasicPassTicket applid: ZOWEAPPL - apiInfo: +apiInfo: - apiId: zowe.apiml.sampleservice version: 1.0.0 gatewayUrl: api/v1 @@ -217,14 +219,71 @@ authentication: swaggerUrl: http://${sampleServiceSwaggerHost}:${sampleServiceSwaggerPort}/sampleservice/api-doc?group=api-v2 documentationUrl: http:// defaultApi: true - catalog: +catalog: tile: id: sampleservice title: Hello API ML description: Sample application to demonstrate exposing a REST API in the ZOWE API ML version: 1.0.0 - ssl: +ssl: + enabled: true + verifySslCertificatesOfServices: true + protocol: TLSv1.2 + keyAlias: localhost + keyPassword: password + keyStore: keystore/localhost.keystore.p12 + keyStoreType: PKCS12 + keyStorePassword: password + trustStore: keystore/localhost.truststore.p12 + trustStoreType: PKCS12 + trustStorePassword: password + ``` + +**GraphQL API** + +```yaml + serviceId: sampleservice + title: Hello API ML + description: Sample API ML GraphQL Service + baseUrl: https://${samplehost}:${sampleport}/${sampleservice} + serviceIpAddress: ${sampleHostIpAddress} + preferIpAddress: false + + homePageRelativeUrl: /application/home + statusPageRelativeUrl: /application/info + healthCheckRelativeUrl: /application/health + + discoveryServiceUrls: + - https://${discoveryServiceHost1}:${discoveryServicePort1}/eureka + - https://${discoveryServiceHost2}:${discoveryServicePort2}/eureka + + routes: + - gatewayUrl: api/v1 + serviceUrl: /sampleservice/api/v1 + +authentication: + scheme: httpBasicPassTicket + applid: ZOWEAPPL + +apiInfo: + - apiId: zowe.apiml.sampleservice + version: 1.0.0 + gatewayUrl: api/v1 + graphqlUrl: http://${sampleServiceGraphQLHost}:${sampleServiceGraphQLPort}/sampleservice/graphql + - apiId: zowe.apiml.sampleservice + version: 2.0.0 + gatewayUrl: api/v2 + graphqlUrl: http://${sampleServiceGraphQLHost}:${sampleServiceGraphQLPort}/sampleservice/graphql + +catalog: + tile: + id: sampleservice + title: Hello API ML + description: Sample application to demonstrate exposing a GraphQL API in the ZOWE API ML + version: 1.0.0 + +ssl: enabled: true verifySslCertificatesOfServices: true protocol: TLSv1.2 @@ -238,6 +297,7 @@ authentication: trustStorePassword: password ``` + **Optional metadata section** The following snippet presents additional optional metadata that can be added. @@ -252,7 +312,7 @@ customMetadata: ``` The onboarding configuration parameters are broken down into the following groups: -- [REST service identification](#rest-service-identification) +- [Service identification](#rest-service-identification) - [Administrative endpoints](#administrative-endpoints) - [API info](#api-info) - [API routing information](#api-routing-information) @@ -263,22 +323,22 @@ The onboarding configuration parameters are broken down into the following group - [Eureka Discovery Service](#eureka-discovery-service) - [Custom Metadata](#custom-metadata) -### REST service identification +### Service identification * **serviceId** - The `serviceId` uniquely identifies one or more instance of a microservice in the API ML and is used as part of the service URL path in the API ML Gateway address space. - Additionally, the API ML Gateway uses the `serviceId` for routing to the API service instances. - When two API services use the same `serviceId`, the API Gateway considers the services as clones of each other. - An incoming API request can be routed to either of them through utilized load balancing mechanism. + The `serviceId` uniquely identifies one or more instance of a microservice in the API ML and is used as part of the service URL path in the API ML Gateway address space. + Additionally, the API ML Gateway uses the `serviceId` for routing to the API service instances. + When two API services use the same `serviceId`, the API Gateway considers the services as clones of each other. + An incoming API request can be routed to either of them through utilized load balancing mechanism. - **Important!** Ensure that the `serviceId` is set properly with the following considerations: + **Important!** Ensure that the `serviceId` is set properly with the following considerations: * The same `servicedId` should only be set for multiple API service instances for API scalability. * The `servicedId` value must only contain lowercase alphanumeric characters. * The `servicedId` cannot contain more than 40 characters. - **Example:** + **Example:** * If the `serviceId` is `sampleservice`, the service URL in the API ML Gateway address space appears as the following path: ``` @@ -294,36 +354,36 @@ The onboarding configuration parameters are broken down into the following group * **description** - This parameter is a short description of the API service. This value is displayed in the API Catalog when a specific API service instance is selected. This parameter can be externalized and set by the customer system administrator. + This parameter is a short description of the API service. This value is displayed in the API Catalog when a specific API service instance is selected. This parameter can be externalized and set by the customer system administrator. **Tip:** Describe the service so that the end user understands the function of the service. * **baseUrl** - This parameter specifies the base URL for the following administrative endpoints: + This parameter specifies the base URL for the following administrative endpoints: * **homePageRelativeUrl** * **statusPageRelativeUrl** * **healthCheckRelativeUrl** - Use the following format to include your service name in the URL path: + Use the following format to include your service name in the URL path: - `protocol://host:port/servicename` + `protocol://host:port/servicename` - **Note:** Ensure that the `baseUrl` does not end with a trailing `/`. Inclusion of `/` causes a malformed URL if any of the above administrative endpoints begin with a `/`. It is expected that each administrative endpoint begins with a `/`. Warnings will be logged if this recommendation is not followed. + **Note:** Ensure that the `baseUrl` does not end with a trailing `/`. Inclusion of `/` causes a malformed URL if any of the above administrative endpoints begin with a `/`. It is expected that each administrative endpoint begins with a `/`. Warnings will be logged if this recommendation is not followed. * **serviceIpAddress** (Optional) - This parameter specifies the service IP address and can be provided by a system administrator in the externalized service configuration. - If this parameter is not present in the configuration file or is not set as a service context parameter, it is resolved from the hostname part of the `baseUrl`. + This parameter specifies the service IP address and can be provided by a system administrator in the externalized service configuration. + If this parameter is not present in the configuration file or is not set as a service context parameter, it is resolved from the hostname part of the `baseUrl`. * **preferIpAddress** (Optional) - Set the value of this parameter to `true` to advertise a service IP address instead of its hostname. + Set the value of this parameter to `true` to advertise a service IP address instead of its hostname. ### Administrative endpoints - The following snippet presents the format of the administrative endpoint properties: +The following snippet presents the format of the administrative endpoint properties: ```yaml homePageRelativeUrl: @@ -333,47 +393,49 @@ healthCheckRelativeUrl: /application/health * **homePageRelativeUrl** - Specifies the relative path to the home page of your service. - - Start this path with `/`. If your service has no home page, leave this parameter blank. + Specifies the relative path to the home page of your service. + + Start this path with `/`. If your service has no home page, leave this parameter blank. - **Examples:** + **Examples:** * `homePageRelativeUrl: ` This service has no home page * `homePageRelativeUrl: /` This service has a home page with URL `${baseUrl}/` * **statusPageRelativeUrl** - Specifies the relative path to the status page of your service. + Specifies the relative path to the status page of your service. - Start this path with `/`. + Start this path with `/`. - **Example:** + **Example:** - `statusPageRelativeUrl: /application/info` + `statusPageRelativeUrl: /application/info` - This results in the URL: - `${baseUrl}/application/info` + This results in the URL: + `${baseUrl}/application/info` * **healthCheckRelativeUrl** - Specifies the relative path to the health check endpoint of your service. + Specifies the relative path to the health check endpoint of your service. - Start this path with `/`. + Start this path with `/`. - **Example:** + **Example:** - `healthCheckRelativeUrl: /application/health` + `healthCheckRelativeUrl: /application/health` - This results in the URL: - `${baseUrl}/application/health` + This results in the URL: + `${baseUrl}/application/health` ### API info -REST services can provide multiple APIs. Add API info parameters for each API that your service wants to expose on the API ML. +Services can provide multiple APIs. Add API info parameters for each API that your service wants to expose on the API ML. The following snippet presents the information properties of a single API: +**REST API** + ``` apiInfo: - apiId: zowe.apiml.sampleservice @@ -392,36 +454,52 @@ apiInfo: codeBlock: | console.log('hello'); ``` +**GraphQL API** + +``` +apiInfo: + - apiId: zowe.apiml.sampleservice + version: 1.0.0 + gatewayUrl: api/v1 + graphqlUrl: http://localhost:10021/sampleservice/graphql +``` + * **apiInfo.apiId** - Specifies the API identifier that is registered in the API ML installation. - The API ID uniquely identifies the API in the API ML. - The `apiId` can be used to locate the same APIs that are provided by different service instances. The API developer defines this ID. - The `apiId` must be a string of up to 64 characters - that uses lowercase alphanumeric characters and a dot: `.` . + Specifies the API identifier that is registered in the API ML installation. + The API ID uniquely identifies the API in the API ML. + The `apiId` can be used to locate the same APIs that are provided by different service instances. The API developer defines this ID. + The `apiId` must be a string of up to 64 characters + that uses lowercase alphanumeric characters and a dot: `.` . * **apiInfo.version** - Specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API. + Specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API. * **apiInfo.gatewayUrl** - specifies the base path at the API Gateway where the API is available. - Ensure that this value is the same path as the `gatewayUrl` value in the `routes` sections that apply to this API. + specifies the base path at the API Gateway where the API is available. + Ensure that this value is the same path as the `gatewayUrl` value in the `routes` sections that apply to this API. * **apiInfo.swaggerUrl** (Optional) - Specifies the Http or Https address where the Swagger JSON document is available. + Specifies the Http or Https address where the Swagger JSON document is available. + +* **apiInfo.graphqlUrl** (Optional) + + Specifies the Http or Https address where the GraphQL server is available. + +_Specific for REST API_ * **apiInfo.documentationUrl** (Optional) - Specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation. + Specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation. * **apiInfo.defaultApi** (Optional) - Specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one - with the highest API `version`. + Specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one + with the highest API `version`. * **apiInfo.codeSnippet** (Optional) @@ -429,16 +507,16 @@ apiInfo: the request using the *Try it out* functionality. When specifying this configuration, you need to provide the following parameters: * **`endpoint`** - The endpoint that represents the API operation of the customized snippet + The endpoint that represents the API operation of the customized snippet * **`language`** - The language of the snippet + The language of the snippet * **`codeBlock`** - The content of the snippet to be displayed in the API Catalog + The content of the snippet to be displayed in the API Catalog ### API routing information -The API routing group provides the required routing information used by the API ML Gateway when routing incoming requests to the corresponding REST API service. -A single route can be used to direct REST calls to multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to rewrite the URL +The API routing group provides the required routing information used by the API ML Gateway when routing incoming requests to the corresponding API service. +A single route can be used to direct calls to multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to rewrite the URL in the Gateway address space. Currently, the routing information consists of two parameters per route: The `gatewayUrl` and `serviceUrl`. These two parameters together specify a rule for how the API service endpoints are mapped to the API Gateway endpoints. The following snippet is an example of the API routing information properties. @@ -457,21 +535,21 @@ routes: * **routes** - Specifies the container element for the route. + Specifies the container element for the route. * **routes.gatewayUrl** - The `gatewayUrl` parameter specifies the portion of the gateway URL which is replaced by the `serviceUrl` path part. + The `gatewayUrl` parameter specifies the portion of the gateway URL which is replaced by the `serviceUrl` path part. * **routes.serviceUrl** - The `serviceUrl` parameter provides a portion of the service instance URL path which replaces the `gatewayUrl` part. + The `serviceUrl` parameter provides a portion of the service instance URL path which replaces the `gatewayUrl` part. -**Examples:** +**Examples:** * ``` https://gateway:10010/sampleservice/api ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api ``` @@ -479,7 +557,7 @@ routes: ``` https://gateway:10010/sampleservice/api/v1 ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api/ver1 ``` @@ -487,17 +565,17 @@ routes: ``` https://gateway:10010/sampleservice/api/v1/api-doc ``` - is routed to: + is routed to: ``` https://service:10015/sampleservice-api/api-doc ``` ### API Catalog information -The API ML Catalog UI displays information about discoverable REST services registered with the API ML Discovery Service. +The API ML Catalog UI displays information about discoverable services registered with the API ML Discovery Service. Information displayed in the Catalog is defined by the metadata provided by your service during registration. The following image is an example of a tile in the API Catalog: - - ![Tile](../../images/api-mediation/API-Catalog-Tile.png "Tile of a sample service in API Catalog") + +![Tile](../../images/api-mediation/API-Catalog-Tile.png "Tile of a sample service in API Catalog") The Catalog groups correlated services in the same tile if these services are configured with the same `catalog.tile.id` metadata parameter. @@ -516,34 +594,34 @@ The following code block is an example of configuration of a service tile in the * **catalog.tile.id** - Specifies the unique identifier for the product family of API services. - This is a value used by the API ML to group multiple API services into a single tile. - Each unique identifier represents a single API dashboard tile in the Catalog. + Specifies the unique identifier for the product family of API services. + This is a value used by the API ML to group multiple API services into a single tile. + Each unique identifier represents a single API dashboard tile in the Catalog. - **Tip:** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID. + **Tip:** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID. * **catalog.tile.title** - Specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title. + Specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title. * **catalog.tile.description** - The detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description. + The detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description. * **catalog.tile.version** - specifies the semantic version of this API Catalog tile. + specifies the semantic version of this API Catalog tile. - **Note:** Ensure that you increase the version number when you introduce changes to the API service product family details. + **Note:** Ensure that you increase the version number when you introduce changes to the API service product family details. ### Authentication parameters These parameters are not required. Default values are used when parameters are not specified. For more information, see [Authentication Parameters for Onboarding REST API Services](./authentication-for-apiml-services.md#authentication-parameters). - + ### API Security -REST services onboarded with the API ML act as both a client and a server. When communicating to API ML Discovery service, a REST service acts as a client. When the API ML Gateway is routing requests to a service, the REST service acts as a server. +Services onboarded with the API ML act as both a client and a server. When communicating to API ML Discovery service, a service acts as a client. When the API ML Gateway is routing requests to a service, the service acts as a server. These two roles have different requirements. The Zowe API ML Discovery Service communicates with its clients in secure Https mode. As such, TLS/SSL configuration setup is required when a service is acting as a server. In this case, the system administrator decides if the service will communicate with its clients securely or not. @@ -562,9 +640,9 @@ TLS/SSL configuration consists of the following parameters: * **protocol** - This parameter specifies the TLS protocol version currently used by Zowe API ML Discovery Service. + This parameter specifies the TLS protocol version currently used by Zowe API ML Discovery Service. - **Tip:** We recommend you use `TLSv1.2` as your security protocol + **Tip:** We recommend you use `TLSv1.2` as your security protocol * **keyAlias** @@ -577,9 +655,9 @@ TLS/SSL configuration consists of the following parameters: * **keyStore** This parameter specifies the keystore file used to store the private key. When using keyring, the value should be set to the SAF keyring location. For information about required certificates, see [Zowe API ML TLS requirements](https://github.com/zowe/api-layer/blob/v3.x.x/docs/api-ml-security-overview.md#zowe-api-ml-tls-requirements). - - If you have an issue with loading the keystore file in your environment, try to provide the absolute path to the keystore file. The sample keystore file for local deployment is in [api-layer repository](https://github.com/zowe/api-layer/tree/master/keystore/localhost) + +If you have an issue with loading the keystore file in your environment, try to provide the absolute path to the keystore file. The sample keystore file for local deployment is in [api-layer repository](https://github.com/zowe/api-layer/tree/master/keystore/localhost) * **keyStorePassword** @@ -637,22 +715,22 @@ An example is presented in the following snippet: ```yaml discoveryServiceUrls: -- https://localhost:10011/eureka -- http://...... + - https://localhost:10011/eureka + - http://...... ``` * **discoveryServiceUrls** - Specifies the public URL of the Discovery Service. The system administrator at the customer site defines this parameter. - It is possible to provide multiple values in order to utilize fail over and/or load balancing mechanisms. + Specifies the public URL of the Discovery Service. The system administrator at the customer site defines this parameter. + It is possible to provide multiple values in order to utilize fail over and/or load balancing mechanisms. ### Custom Metadata For information about custom metadata, see the topic [Custom Metadata](./custom-metadata.md). - + ## Registering your service with API ML -The following steps outline the process of registering your service with API ML. Each step is described in detail in this article. The process describes the integration with the usage of the Java application server. The guideline is tested with the Tomcat application server. The specific steps that apply for other application servers may differ. +The following steps outline the process of registering your service with API ML. Each step is described in detail in this article. The process describes the integration with the usage of the Java application server. The guideline is tested with the Tomcat application server. The specific steps that apply for other application servers may differ. 1. Add a web application context listener class 2. Register a web application context listener @@ -662,19 +740,19 @@ The following steps outline the process of registering your service with API ML. **Follow these steps:** -1. Implement and add a web application context listener class: +1. Implement and add a web application context listener class: - ```implements javax.servlet.ServletContextListener``` + ```implements javax.servlet.ServletContextListener``` - The web application context listener implements two methods to perform necessary actions at application start-up time as well as when the application context is destroyed: + The web application context listener implements two methods to perform necessary actions at application start-up time as well as when the application context is destroyed: - - The `contextInitialized` method invokes the `apiMediationClient.register(config)` method to register the application with API Mediation Layer when the application starts. - - The `contextDestroyed` method invokes the `apiMediationClient.unregister()` method when the application shuts down. This unregisters the application from the API Mediation Layer. + - The `contextInitialized` method invokes the `apiMediationClient.register(config)` method to register the application with API Mediation Layer when the application starts. + - The `contextDestroyed` method invokes the `apiMediationClient.unregister()` method when the application shuts down. This unregisters the application from the API Mediation Layer. 2. Register a web application context listener. - Add the following code block to the deployment descriptor `web.xml` to register a context listener: - + Add the following code block to the deployment descriptor `web.xml` to register a context listener: + ```xml com.your.package.ApiDiscoveryListener @@ -683,13 +761,13 @@ The following steps outline the process of registering your service with API ML. 3. Load the service configuration. - Load your service configuration from a file `service-configuration.yml` file. - The configuration parameters are described in the preceding section, [Configuring your service](#configuring-your-service). + Load your service configuration from a file `service-configuration.yml` file. + The configuration parameters are described in the preceding section, [Configuring your service](#configuring-your-service). + + Use the following code as an example of how to load the service configuration. - Use the following code as an example of how to load the service configuration. + **Example:** - **Example:** - ```java @Override public void contextInitialized(ServletContextEvent sce) { @@ -698,14 +776,14 @@ The following steps outline the process of registering your service with API ML. ApiMediationServiceConfig config = new ApiMediationServiceConfigReader().loadConfiguration(configurationFile); ... ``` - - **Note:** The `ApiMediationServiceConfigReader` class also provides other methods for loading the configuration from two files, `java.util.Map` instances, or directly from a string. Check the `ApiMediationServiceConfigReader` class JavaDoc for details. + + **Note:** The `ApiMediationServiceConfigReader` class also provides other methods for loading the configuration from two files, `java.util.Map` instances, or directly from a string. Check the `ApiMediationServiceConfigReader` class JavaDoc for details. 4. Register with Eureka Discovery Service. - Use the following call to register your service instance with Eureka Discovery Service: + Use the following call to register your service instance with Eureka Discovery Service: - **Example:** + **Example:** ```java try { @@ -718,9 +796,9 @@ The following steps outline the process of registering your service with API ML. 5. Unregister your service. - Use the `contextDestroyed` method to unregister your service instance from Eureka Discovery Service in the following format: - - **Example:** + Use the `contextDestroyed` method to unregister your service instance from Eureka Discovery Service in the following format: + + **Example:** ```java @Override @@ -732,7 +810,7 @@ The following steps outline the process of registering your service with API ML. apiMediationClient = null; } ``` - + The following code block is a full example of a context listener class implementation. **Example:** @@ -818,11 +896,11 @@ public class ApiDiscoveryListener implements ServletContextListener { Once you are able to build and start your service successfully, you can use the option of validating that your service is registered correctly with the API ML Discovery Service. **Follow these steps:** - 1. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml). - - 2. Check that you can access your API service endpoints through the Gateway. +1. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml). - 3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway. +2. Check that you can access your API service endpoints through the Gateway. + +3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway. Specific addresses and user credentials for the individual API ML components depend on your target runtime environment. @@ -840,18 +918,18 @@ Wait for the Discovery Service to discover your service. This process may take a #### Log messages during registration problems -When an Enabler connects to the Discovery service and fails, an error message prints to the Enabler log. The default setting does not suppress these messages as they are useful to resolve problems during the Enabler registration. Possible reasons for failure include the location of Discovery service is not correct, the Discovery Service is down, or the TLS certificate is invalid. +When an Enabler connects to the Discovery service and fails, an error message prints to the Enabler log. The default setting does not suppress these messages as they are useful to resolve problems during the Enabler registration. Possible reasons for failure include the location of Discovery service is not correct, the Discovery Service is down, or the TLS certificate is invalid. -These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery Service. +These messages continue to print to the Enabler log, while the Enabler retries to connect to the Discovery Service. To fully suppress these messages in your logging framework, set the log levels to `OFF` on the following loggers: com.netflix.discovery.DiscoveryClient, com.netflix.discovery.shared.transport.decorator.RedirectingEurekaHttpClient Some logging frameworks provide other tools to suppress repeated messages. Consult the documentation of the logging framework you use to find out what tools are available. The following example demonstrates how the Logback framework can be used to suppress repeated messages. -**Example:** +**Example:** -Add the following code to your configuration file if you use XML configuration: +Add the following code to your configuration file if you use XML configuration: ``` 0 @@ -859,5 +937,5 @@ Add the following code to your configuration file if you use XML configuration: ``` :::note -For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub. +For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub. ::: diff --git a/docs/extend/extend-apiml/onboard-static-definition.md b/docs/extend/extend-apiml/onboard-static-definition.md index 55e7f98c29..7f2fb4e780 100644 --- a/docs/extend/extend-apiml/onboard-static-definition.md +++ b/docs/extend/extend-apiml/onboard-static-definition.md @@ -1,9 +1,9 @@ -# Onboarding a REST API without code changes required +# Onboarding a REST or GraphQL API without code changes required -As a user of Zowe™, onboard an existing REST API service to the Zowe™ API Mediation Layer without changing the code of the API service. This form of onboarding is also refered to as, "static onboarding". +As a user of Zowe™, onboard an existing REST or GraphQL API service to the Zowe™ API Mediation Layer without changing the code of the API service. This form of onboarding is also refered to as, "static onboarding". :::note -When developing a new service, it is not recommended to onboard a REST service using this method, as this method is non-native to the API Mediation Layer. For a complete list of methods to onboard a REST service natively to the API Mediation Layer, see the [Onboarding Overview](onboard-overview.md#service-onboarding-guides). +When developing a new service, it is not recommended to onboard a service using this method, as this method is non-native to the API Mediation Layer. For a complete list of methods to onboard a service natively to the API Mediation Layer, see the [Onboarding Overview](onboard-overview.md#service-onboarding-guides). ::: The following procedure outlines the steps to onboard an API service through the API Gateway in the API Mediation Layer without requiring code changes. @@ -31,31 +31,31 @@ The first step in API service onboarding is to identify the APIs that you want t * Hostname * Port * (Optional) base path where the service is available. - This URL is called the base URL of the service. + This URL is called the base URL of the service. - **Example:** + **Example:** - In the sample service described in the [Onboarding Overview](onboard-overview.md#sample-rest-api-service), the URL of the service is: `http://localhost:8080`. + In the sample service described in the [Onboarding Overview](onboard-overview.md#sample-rest-api-service), the URL of the service is: `http://localhost:8080`. 2. Identify the API of the service that you want to expose through the API Gateway. - **Example:** + **Example:** - The API provided by the sample service is a second version of the Pet Store API. All the endpoints to be onboarded are available - through `http://localhost:8080/v2/` URL. This REST API is therefore available at the path `/v2` relative to base URL of the service. - There is no version 1 in this case. + The API provided by the sample service is a second version of the Pet Store API. All the endpoints to be onboarded are available + through `http://localhost:8080/v2/` URL. This API is therefore available at the path `/v2` relative to base URL of the service. + There is no version 1 in this case. 3. Choose the `service ID` of your service. The `service ID` identifies the service uniquely in the API Gateway. The `service ID` is an alphanumeric string in lowercase ASCII. - **Example:** + **Example:** - In the sample service, the `service ID` is `petstore`. + In the sample service, the `service ID` is `petstore`. 4. Decide which URL to use to make this API available in the API Gateway. This URL is referred to as the gateway URL and is composed of the API type and the major version. The usually used types are: `api`, `ui` and `ws` but you can use any valid URL element you want. - **Example:** + **Example:** - In the sample service, we provide a REST API. The first segment is `/api` as the service provides only one REST API. To indicate that this is version 2, the second segment is `/v2`. This version is required by the Gateway. If your service does not have a version, use `v1` on the Gateway. + In the sample service, we provide a REST API. The first segment is `/api` as the service provides only one REST API. To indicate that this is version 2, the second segment is `/v2`. This version is required by the Gateway. If your service does not have a version, use `v1` on the Gateway. ## Define your service and API in YAML format @@ -107,7 +107,7 @@ In this example, a suitable name for the file is `petstore.yml`. * There are more examples of API definitions at this [link](https://github.com/zowe/api-layer/tree/master/config/local/api-defs). * For more details about how to use YAML format, see this [link](https://learnxinyminutes.com/docs/yaml/). -::: + ::: ## Route your API @@ -145,7 +145,7 @@ To access resource `pets` of the `petstore` version 2 API, gateway URL will be: ``` https://gateway:port/petstore/api/v2/pets ``` -It will be routed to: +It will be routed to: ``` https://localhost:8080/v2/pets ``` @@ -158,6 +158,7 @@ This method enables you to access the service through a stable URL, and move the This part contains a more complex example of the configuration and an explanation of all the possible parameters: +**REST API** ```yaml services: - serviceId: petstore @@ -192,6 +193,45 @@ catalogUiTiles: title: Static API services description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions +additionalServiceMetadata: + - serviceId: petstore + mode: UPDATE # How to update UPDATE=only missing, FORCE_UPDATE=update all set values + authentication: + scheme: bypass +``` +**GraphQL API** + +```yaml +services: + - serviceId: petstore + catalogUiTileId: static + title: Petstore Sample Service + description: This is a sample server Petstore service + instanceBaseUrls: + - http://localhost:8080 + homePageRelativeUrl: /home # Normally used for informational purposes for other services to use it as a landing page + statusPageRelativeUrl: /application/info # Appended to the instanceBaseUrl + healthCheckRelativeUrl: /application/health # Appended to the instanceBaseUrl + routes: + - gatewayUrl: api/v2 + serviceRelativeUrl: /v2 + authentication: + scheme: httpBasicPassTicket + applid: ZOWEAPPL + apiInfo: + - apiId: io.swagger.petstore + gatewayUrl: api/v2 + graphqlUrl: http://localhost:8080/v2/graphql + customMetadata: + yourqualifier: + key1: value1 + key2: value2 + +catalogUiTiles: + static: + title: Static API services + description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions + additionalServiceMetadata: - serviceId: petstore mode: UPDATE # How to update UPDATE=only missing, FORCE_UPDATE=update all set values @@ -201,14 +241,14 @@ additionalServiceMetadata: * **serviceId** - This parameter specifies the service instance identifier that is registered in the API Mediation Layer installation. - The service ID is used in the URL for routing to the API service through the Gateway. - The service ID uniquely identifies the service in the API Mediation Layer. - The system administrator at the customer site defines this parameter. + This parameter specifies the service instance identifier that is registered in the API Mediation Layer installation. + The service ID is used in the URL for routing to the API service through the Gateway. + The service ID uniquely identifies the service in the API Mediation Layer. + The system administrator at the customer site defines this parameter. - :::caution - Ensure that the service ID is set properly with the following considerations: - ::: + :::caution + Ensure that the service ID is set properly with the following considerations: + ::: * When two API services use the same service ID, the API Gateway considers the services to be clones (i.e. two instances for the same service). An incoming API request can be routed to either of them. * The same service ID should be set only for multiple API service instances for API scalability. @@ -216,138 +256,138 @@ additionalServiceMetadata: * The service ID cannot contain more than 40 characters. * The service ID is linked to security resources. Changes to the service ID require an update of security resources. - **Examples:** + **Examples:** * If the customer system administrator sets the service ID to `monitoringpr1`, - the API URL in the API Gateway appears as the following URL: + the API URL in the API Gateway appears as the following URL: - `https://gateway:port/monitoringpr1/api/v1/...` + `https://gateway:port/monitoringpr1/api/v1/...` * If customer system administrator sets the service ID to `authenticationprod1`, - the API URL in the API Gateway appears as the following URL: + the API URL in the API Gateway appears as the following URL: + + `http://gateway:port/authenticationprod1/api/v1/...` - `http://gateway:port/authenticationprod1/api/v1/...` +* **title** - * **title** + This parameter specifies the human readable name of the API service instance (for example, `Monitoring Prod` or `systemInfo LPAR1`). This value is displayed in the API catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator. - This parameter specifies the human readable name of the API service instance (for example, `Monitoring Prod` or `systemInfo LPAR1`). This value is displayed in the API catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator. + **Tip:** We recommend that you provide a specific default value of the `title`. + Use a title that describes the service instance so that the end user knows the specific purpose of the service instance. - **Tip:** We recommend that you provide a specific default value of the `title`. - Use a title that describes the service instance so that the end user knows the specific purpose of the service instance. +* **description** - * **description** + This parameter specifies a short description of the API service. - This parameter specifies a short description of the API service. + **Examples:** - **Examples:** - - - `Monitoring Service - Production Instance` - - `System Info Service running on LPAR1` + - `Monitoring Service - Production Instance` + - `System Info Service running on LPAR1` - This value is displayed in the API Catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator. + This value is displayed in the API Catalog when a specific API service instance is selected. This parameter is externalized and set by the customer system administrator. - :::tip - Describe the service so that the end user knows the function of the service. - ::: + :::tip + Describe the service so that the end user knows the function of the service. + ::: * **instanceBaseUrls** - This parameter specifies a list of base URLs to your service's REST resource. It will be the prefix for the following URLs: + This parameter specifies a list of base URLs to your service's resource. It will be the prefix for the following URLs: * **homePageRelativeUrl** * **statusPageRelativeUrl** * **healthCheckRelativeUrl** - **Examples:** + **Examples:** * `- http://host:port/ftpservice` for an HTTP service * `- https://host:port/source-code-mngmnt` for an HTTPS service - You can provide one URL if your service has one instance. If your service provides multiple instances for the high-availability then you can provide URLs to these instances. + You can provide one URL if your service has one instance. If your service provides multiple instances for the high-availability then you can provide URLs to these instances. - **Examples:** + **Examples:** * `- https://host1:port1/source-code-mngmnt` * `- https://host2:port2/source-code-mngmnt` - + * **homePageRelativeUrl** - This parameter specifies the relative path to the homepage of your service. The path should start with `/`. - If your service has no homepage, omit this parameter. The path is relative to the instanceBaseUrls. + This parameter specifies the relative path to the homepage of your service. The path should start with `/`. + If your service has no homepage, omit this parameter. The path is relative to the instanceBaseUrls. - **Examples:** + **Examples:** * `homePageRelativeUrl: /` The service has homepage with URL `${baseUrl}/` * `homePageRelativeUrl: /ui/` The service has homepage with URL `${baseUrl}/ui/` * `homePageRelativeUrl: ` The service has homepage with URL `${baseUrl}` * **statusPageRelativeUrl** - This parameter specifies the relative path to the status page of your service. - Start this path with `/`. If you service doesn't have a status page, omit this parameter. - The path is relative to the instanceBaseUrls. + This parameter specifies the relative path to the status page of your service. + Start this path with `/`. If you service doesn't have a status page, omit this parameter. + The path is relative to the instanceBaseUrls. + + **Example:** + + `statusPageRelativeUrl: /application/info` - **Example:** + the result URL will be: - `statusPageRelativeUrl: /application/info` - - the result URL will be: - - `${baseUrl}/application/info` + `${baseUrl}/application/info` * **healthCheckRelativeUrl** - This parameter specifies the relative path to the health check endpoint of your service. - Start this URL with `/`. If your service does not have a health check endpoint, omit this parameter. - The path is relative to the instanceBaseUrls. + This parameter specifies the relative path to the health check endpoint of your service. + Start this URL with `/`. If your service does not have a health check endpoint, omit this parameter. + The path is relative to the instanceBaseUrls. - **Example:** + **Example:** - `healthCheckRelativeUrl: /application/health` - - This results in the URL: + `healthCheckRelativeUrl: /application/health` - `${baseUrl}/application/health` + This results in the URL: + + `${baseUrl}/application/health` * **routes** - The following parameters specify the routing rules between the Gateway service and your service. Both specify how the API endpoints are mapped to the API Gateway endpoints. + The following parameters specify the routing rules between the Gateway service and your service. Both specify how the API endpoints are mapped to the API Gateway endpoints. * **routes.gatewayUrl** - The _gatewayUrl_ parameter sets the target endpoint on the Gateway. This is the portion of the final URL that is Gateway specific. - - **Example:** - - For the petstore example, the full Gateway URL would be: + The _gatewayUrl_ parameter sets the target endpoint on the Gateway. This is the portion of the final URL that is Gateway specific. + + **Example:** + + For the petstore example, the full Gateway URL would be: - `https://gatewayUrl:1345/petstore/api/v2/pets/1` - - In this case, the URL that will be called on the service is: + `https://gatewayUrl:1345/petstore/api/v2/pets/1` - `http://localhost:8080/v2/pets/1` + In this case, the URL that will be called on the service is: + + `http://localhost:8080/v2/pets/1` * **routes.serviceRelativeUrl** - The _serviceRelativeUrl_ parameter points to the target endpoint on the service. This is the base path on the service called through the Gateway. - + The _serviceRelativeUrl_ parameter points to the target endpoint on the service. This is the base path on the service called through the Gateway. + * **authentication** - The information about the possible ways to integrate authentication are available in [Single Sign On Integration for Extenders](./api-medation-sso-integration-extenders.md) article. + The information about the possible ways to integrate authentication are available in [Single Sign On Integration for Extenders](./api-medation-sso-integration-extenders.md) article. * **apiInfo** - This section defines APIs that are provided by the service. Currently, only one API is supported. + This section defines APIs that are provided by the service. Currently, only one API is supported. * **apiInfo.apiId** - This parameter specifies the API identifier that is registered in the API Mediation Layer installation. The API ID uniquely identifies the API in the API Mediation Layer. - The same API can be provided by multiple services. The API ID can be used to locate the same APIs that are provided by different services. - - The creator of the API defines this ID. - The API ID needs to be a string of up to 64 characters - that uses lowercase alphanumeric characters and a dot: `.`. - - **Tip:** We recommend that you use your organization as the prefix. + This parameter specifies the API identifier that is registered in the API Mediation Layer installation. The API ID uniquely identifies the API in the API Mediation Layer. + The same API can be provided by multiple services. The API ID can be used to locate the same APIs that are provided by different services. - **Examples:** + The creator of the API defines this ID. + The API ID needs to be a string of up to 64 characters + that uses lowercase alphanumeric characters and a dot: `.`. + + **Tip:** We recommend that you use your organization as the prefix. + + **Examples:** - `zowe.file` - `ca.sysview` @@ -355,55 +395,61 @@ additionalServiceMetadata: * **apiInfo.gatewayUrl** - This parameter specifies the base path at the API Gateway where the API is available. Ensure that this path is the same as the _gatewayUrl_ value in the _routes_ sections. + This parameter specifies the base path at the API Gateway where the API is available. Ensure that this path is the same as the _gatewayUrl_ value in the _routes_ sections. * **apiInfo.swaggerUrl** - (Optional) This parameter specifies the HTTP or HTTPS address where the Swagger JSON document is available. + (Optional) This parameter specifies the HTTP or HTTPS address where the Swagger JSON document is available. + + * **apiInfo.graphqlUrl** + + (Optional) This parameter specifies the HTTP or HTTPS address where GraphQL server is available. + + _Specific for REST API_ * **apiInfo.documentationUrl** - (Optional) This parameter specifies a URL to a website where external documentation is provided. - This can be used when _swaggerUrl_ is not provided. + (Optional) This parameter specifies a URL to a website where external documentation is provided. + This can be used when neither _swaggerUrl_ not _graphqlUrl_ are provided. * **apiInfo.version** - (Optional) This parameter specifies the actual version of the API in [semantic versioning](https://semver.org/) format. This can be used when _swaggerUrl_ is not provided. + (Optional) This parameter specifies the actual version of the API in [semantic versioning](https://semver.org/) format. This can be used when _swaggerUrl_ is not provided. * **apiInfo.defaultApi** - - (Optional) This parameter specifics that the API is the default one to show in the API Catalog. If this not set to true for any API, or multiple APIs have it set to true, - then the default API becomes the API with the highest major version as seen in `apiInfo.version`. - + + (Optional) This parameter specifics that the API is the default one to show in the API Catalog. If this not set to true for any API, or multiple APIs have it set to true, + then the default API becomes the API with the highest major version as seen in `apiInfo.version`. + * **apiInfo.codeSnippet** (Optional) - specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing - the request using the *Try it out* functionality. - When specifying this configuration, you need to provide the following parameters: + specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing + the request using the *Try it out* functionality. This can be used when swaggerUrl is not provided. + When specifying this configuration, you need to provide the following parameters: * **`endpoint`** - The endpoint that represents the API operation of the customized snippet + The endpoint that represents the API operation of the customized snippet * **`language`** - The language of the snippet + The language of the snippet * **`codeBlock`** - The content of the snippet to be displayed in the API Catalog + The content of the snippet to be displayed in the API Catalog * **customMetadata** - Custom metadata are described [here](custom-metadata.md). - + Custom metadata are described [here](custom-metadata.md). + * **catalogUiTileId** - This parameter specifies the unique identifier for the API services group. - This is the grouping value used by the API Mediation Layer to group multiple API services - together into "tiles". - Each unique identifier represents a single API Catalog UI dashboard tile. - Specify the value based on the ID of the defined tile. + This parameter specifies the unique identifier for the API services group. + This is the grouping value used by the API Mediation Layer to group multiple API services + together into "tiles". + Each unique identifier represents a single API Catalog UI dashboard tile. + Specify the value based on the ID of the defined tile. * **catalogUiTile** - This section contains definitions of tiles. Each tile is defined in a section that has its tile ID as a key. - A tile can be used by multiple services. + This section contains definitions of tiles. Each tile is defined in a section that has its tile ID as a key. + A tile can be used by multiple services. ```yaml catalogUiTiles: @@ -416,42 +462,42 @@ additionalServiceMetadata: ``` * **catalogUiTile.\{tileId\}.title** - - This parameter specifies the title of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile title. - + + This parameter specifies the title of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile title. + * **catalogUiTile.\{tileId\}.description** - - This parameter specifies the detailed description of the API Catalog UI dashboard tile. This value is displayed in the API Catalog UI dashboard as the tile description. + + This parameter specifies the detailed description of the API Catalog UI dashboard tile. This value is displayed in the API Catalog UI dashboard as the tile description. * **additionalServiceMetadata** - This section contains a list of changes that allows adding or modifying metadata parameters for the corresponding service. - + This section contains a list of changes that allows adding or modifying metadata parameters for the corresponding service. + * **additionalServiceMetadata.serviceId** - - This parameter specifies the service identifier for which metadata is updated. - + + This parameter specifies the service identifier for which metadata is updated. + * **additionalServiceMetadata.mode** - - This parameter specifies how the metadata are updated. The following modes are available: - - **UPDATE** - - Only missing parameters are added. Already existing parameters are ignored. - - **FORCE_UPDATE** - - All changes are applied. Existing parameters are overwritten. - + + This parameter specifies how the metadata are updated. The following modes are available: + + **UPDATE** + + Only missing parameters are added. Already existing parameters are ignored. + + **FORCE_UPDATE** + + All changes are applied. Existing parameters are overwritten. + * **additionalServiceMetadata.\{updatedParameter\}** - - This parameter specifies any metadata parameters that are updated. + + This parameter specifies any metadata parameters that are updated. ## Add and validate the definition in the API Mediation Layer running on your machine After you define the service in YAML format, you are ready to add your service definition to the API Mediation Layer ecosystem. -The following procedure describes how to add your service to the API Mediation Layer on your local machine. +The following procedure describes how to add your service to the API Mediation Layer on your local machine. **Follow these steps:** @@ -474,7 +520,7 @@ The following procedure describes how to add your service to the API Mediation L ## Add a definition in the API Mediation Layer in the Zowe runtime -After you define and validate the service in YAML format, you are ready to add your service definition to the API Mediation Layer running as part of the Zowe runtime installation on z/OS. +After you define and validate the service in YAML format, you are ready to add your service definition to the API Mediation Layer running as part of the Zowe runtime installation on z/OS. **Follow these steps:** @@ -487,17 +533,17 @@ The `${zoweInstanceDir}` symbol is used in following instructions. 2. Add the fully qualified zFS path of your YAML file to `ZWE_STATIC_DEFINITIONS_DIR` in `zowe.yaml`. - To hold your YAML file outside of the instance directory, add `ZWE_STATIC_DEFINITIONS_DIR` variable to the `zowe.environments` section of `zowe.yaml`. Append the fully qualified zFS path of the YAML file to the `ZWE_STATIC_DEFINITIONS_DIR` variable. You may specify multiple zFS paths, separating each path by a semicolon. - - - To place your YAML file within the instance directory, copy your YAML file to the `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory. - :::note Notes: + - To place your YAML file within the instance directory, copy your YAML file to the `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory. + + :::note Notes: - The `${zoweInstanceDir}/workspace/api-mediation/api-defs` directory is created the first time that Zowe starts. If you have not yet started Zowe, this directory might be missing. - The user ID `ZWESVUSR` that runs the Zowe started task must have permission to read the YAML file. - ::: + ::: 3. Ensure that your application that provides the endpoints described in the YAML file is running. -4. Restart Zowe runtime or follow steps in section [(Optional) Reload the services definition after the update when the API Mediation Layer is already started](#optional-reload-the-services-definition-after-the-update-when-the-api-mediation-layer-is-already-started) which allows you to add your static API service to an already running Zowe. +4. Restart Zowe runtime or follow steps in section [(Optional) Reload the services definition after the update when the API Mediation Layer is already started](#optional-reload-the-services-definition-after-the-update-when-the-api-mediation-layer-is-already-started) which allows you to add your static API service to an already running Zowe. 5. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml) @@ -516,9 +562,9 @@ Static API definition file: /Users/user/workspace/api-layer/config/local/api-def Adding static instance STATIC-localhost:petstore:8080 for service ID petstore mapped to URL http://localhost:8080 ``` - :::note - If these messages are not displayed in the log, ensure that the [API ML debug mode](https://docs.zowe.org/stable/troubleshoot/troubleshoot-apiml#enable-api-ml-debug-mode) is active. - ::: +:::note +If these messages are not displayed in the log, ensure that the [API ML debug mode](https://docs.zowe.org/stable/troubleshoot/troubleshoot-apiml#enable-api-ml-debug-mode) is active. +::: ## (Optional) Reload the services definition after the update when the API Mediation Layer is already started @@ -528,24 +574,24 @@ The following procedure enables you to refresh the API definitions after you cha 1. Use a REST API client to issue a `POST` request to the Discovery Service (port 10011): - `http://localhost:10011/discovery/api/v1/staticApi` + `http://localhost:10011/discovery/api/v1/staticApi` - The Discovery Service requires authentication by a client certificate. If the API Mediation Layer is running on your local machine, the certificate is stored at `keystore/localhost/localhost.pem`. + The Discovery Service requires authentication by a client certificate. If the API Mediation Layer is running on your local machine, the certificate is stored at `keystore/localhost/localhost.pem`. - This example uses the [HTTPie command-line HTTP client](https://httpie.org) and is run with Python 3 installed: + This example uses the [HTTPie command-line HTTP client](https://httpie.org) and is run with Python 3 installed: ``` httpie --cert=keystore/localhost/localhost.pem --verify=keystore/local_ca/localca.cer -j POST https://localhost:10011/discovery/api/v1/staticApi ``` - - Alternatively, it is possible to use curl to issue the POST call if it is installed on your system: - + + Alternatively, it is possible to use curl to issue the POST call if it is installed on your system: + ``` curl -X POST --cert keystore/localhost/localhost.pem --cacert keystore/localhost/localhost.keystore.cer https://localhost:10011/discovery/api/v1/staticApi ``` 2. Check if your updated definition is effective. - :::note - It can take up to 30 seconds for the API Gateway to pick up the new routing. - ::: + :::note + It can take up to 30 seconds for the API Gateway to pick up the new routing. + ::: \ No newline at end of file diff --git a/docs/extend/extend-apiml/websocket.md b/docs/extend/extend-apiml/websocket.md deleted file mode 100644 index 7139fcd47b..0000000000 --- a/docs/extend/extend-apiml/websocket.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Using WebSocket support in API Gateway - -The API Gateway includes a basic WebSocket proxy which enables the Gateway to access applications that use the WebSocket protocol together with a web UI and a REST API. - -The service defines which WebSocket endpoints are exposed by using Eureka metadata. - -**Example:** -``` -eureka: - instance: - metadata-map: - apiml: - routes: - ws_v1: - gatewayUrl: "ws/v1" - serviceUrl: /${serviceId}/ws -``` - -These metadata make it possible for requests from `wss://gatewayHost:gatewayPort/${serviceId}/ws/v1/path` to map to `wss://serviceHost:servicePort/${serviceId}/ws/v1/path`. - -* **`serviceId`** - Specifies the service ID of the service. - -* **`path`** - Specifies the remaining path segment in the URL. - diff --git a/docs/extend/extend-cli/cli-authentication-mechanisms.md b/docs/extend/extend-cli/cli-authentication-mechanisms.md new file mode 100644 index 0000000000..274d9e7b2a --- /dev/null +++ b/docs/extend/extend-cli/cli-authentication-mechanisms.md @@ -0,0 +1,16 @@ +# Authentication mechanisms + +As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe. + +Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with. + +However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in. + +To learn the authentication methods used for different services and their order of precedence, refer to the following table. + +Service | Order of precedence +|:--- |:--- | +API ML | 1. username, password
2. API ML token
3. PEM certificate | +Db2,
FTP,
most other services | username, password +SSH | 1. SSH key
2. username, password + ZOSMF
direct connection | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md index 548a47f470..b93e3be1a8 100644 --- a/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md +++ b/docs/extend/extend-cli/cli-creating-plug-in-lifecycle-actions.md @@ -1,40 +1,42 @@ # Creating plug-in lifecycle actions -As a developer, you may want your plug-in to perform certain tasks immediately after install and just before uninstall. +As a developer, you might want your plug-in to perform certain tasks immediately after install and just before uninstall. Many different types of tasks can make up these *plug-in lifecycle actions*, including the following examples: - Post-install actions: - - A sanity check + - An initial check - Additional setup - - Adding the plug-in as an override of Zowe CLI Credential Manager + - Adding the plug-in as an override of Zowe CLI's built-in credential manager - Pre-uninstall actions: - Revert specialized setup - - Removing the plug-in as an override of Zowe CLI Credential Manager + - Removing the plug-in as an override of Zowe CLI's built-in credential manager Creating and using lifecycle actions is optional, but they can be useful tools. Lifecycle actions can automate a manual process intended for the plug-in user to carry out. They can also avoid the need to create commands with uses limited to post-install and pre-uninstall tasks. -**Note:** When creating a plug-in to override Zowe CLI Credential Manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +:::note +When creating a plug-in to override Zowe CLI's built-in credential manager, it is necessary to implement a post-install action to configure your plug-in as the credential manager. +::: -## Implenting lifeycyle actions +## Implementing lifecyle actions -Add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions. - -Follow these steps: +To add the `pluginLifeCycle` property to your plug-in definition file and include a plug-in class to implement lifecycle functions: 1. Navigate to the plug-in definition file. - This file is the value for the `configurationModule` property in the plug-in `package.json` file. - - See this [`IImperativeConfig.ts` file](https://github.com/zowe/imperative/blob/master/packages/imperative/src/doc/IImperativeConfig.ts) to view an example of the detailed format used in the plug-in definition file. + The path to this file is the value for the `configurationModule` property in the plug-in `package.json` file. 2. In the plug-in definition file, use the `pluginLifeCycle` property to add the path to the javascript file the plug-in uses to implement the class containing lifecycle functions. - This plug-in lifecycle functions class extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/imperative/blob/master/packages/imperative/src/plugins/AbstractPluginLifeCycle.ts). + The `pluginLifeCycle` property is defined in [this file](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/doc/IImperativeConfig.ts). + + The class defined by this property extends the `AbstractPluginLifeCycle` class [found in the Imperative package of utility functions](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/imperative/src/plugins/AbstractPluginLifeCycle.ts). 3. In the plug-in lifecycle functions class you created, add instructions for both the `postInstall` and `preUninstall` functions. If implemented correctly, Zowe CLI calls the `postInstall` function of the plug-in immediately after the plug-in has been installed. Similarly, the `preUninstall` function is called immediately before the Zowe CLI uninstalls the plug-in. -**Note:** If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +:::note +If your plug-in needs to perform an operation at only post-install or pre-uninstall, implement the other action to simply return to Zowe CLI without taking any action. +::: diff --git a/docs/extend/extend-cli/cli-devTutorials.md b/docs/extend/extend-cli/cli-devTutorials.md index f253652c41..bc41efbd1c 100644 --- a/docs/extend/extend-cli/cli-devTutorials.md +++ b/docs/extend/extend-cli/cli-devTutorials.md @@ -1,74 +1,50 @@ # Developing for Zowe CLI -You can extend Zowe™ CLI by developing plug-ins and contributing code to the base Zowe CLI or existing plug-ins. +Extend Zowe™ CLI by developing plug-ins and contributing code to Zowe CLI core or existing plug-ins. ## How to contribute -You can contribute to Zowe CLI in the following ways: -- Add new commands, options, or other improvements to the base CLI. + +Contribute to Zowe CLI in the following ways: +- Add new commands, options, or other improvements to the core CLI. - Develop a Zowe CLI plug-in. You might want to contribute to Zowe CLI to accomplish the following objectives: - Provide new scriptable functionality for yourself, your organization, or to a broader community. -- Make use of Zowe CLI infrastructure (profiles and programmatic APIs). +- Make use of Zowe CLI infrastructure (such as profiles and programmatic APIs). - Participate in the Zowe CLI community space. ## Getting started -If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). The [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in) is a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects. + +If you want to start working with the code immediately, review the Readme file in the [Zowe CLI core repository](https://github.com/zowe/zowe-cli#zowe-cli--) and the Zowe [contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md#contribution-guidelines). To review a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects, see the [zowe-cli-sample-plugin GitHub repository](https://github.com/zowe/zowe-cli-sample-plugin#zowe-cli-sample-plug-in). ### Contribution guidelines + The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins. -The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly: +The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. | For more information about ... | See: | | ------------------------------ | ----- | -| General guidelines that apply to contributing to Zowe CLI and Plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | -| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| -| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | -| Guidelines for running tests on the plug-ins that you build| [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | -Versioning conventions for Zowe CLI and Plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | - - -### Tutorials -Follow these tutorials to get started working with the sample plug-in: -1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment. -2. [Installing a plug-in:](cli-installing-sample-plugin.md) Install the sample plug-in to Zowe CLI and run as-is. -3. [Extending a plug-in:](cli-extending-a-plugin.md) Extend the sample plug-in with a new by creating a programmatic API, definition, and handler. -4. [Creating a new plug-in:](cli-developing-a-plugin.md) Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets. -5. [Implementing user profiles:](cli-implement-profiles.md) Implement user profiles with the plug-in. +| General guidelines that apply to contributing to Zowe CLI and plug-ins | [Contribution guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) | +| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and plug-in guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)| +| Guidelines for running tests on Zowe CLI | [Testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) | +| Guidelines for running tests on the plug-ins that you build| [Plug-in testing guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) | +Versioning conventions for Zowe CLI and plug-ins| [Versioning guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) | ### Plug-in development overview -At a high level, a plug-in must have `imperative-framework` configuration [(sample here)](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. -A Zowe CLI plug-in will minimally contain the following: +At a high level, a plug-in must have `imperative-framework` configuration (see a [sample here](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/pluginDef.ts)). This configuration is discovered by `imperative-framework` through the [package.json](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/package.json) `imperative` key. + +A Zowe CLI plug-in minimally contains the following: 1. Programmatic API: Node.js programmatic APIs to be called by your handler or other Node.js applications. 2. Command definition: The syntax definition for your command. 3. Handler implementation: To invoke your programmatic API to display information in the format that you defined in the definition. -The following guidelines and documentation will assist you during development: - -### Imperative CLI Framework documentation -[Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these supplementary documents during development to learn about specific features such as: +#### Imperative CLI Framework documentation +[Imperative CLI Framework documentation](https://github.com/zowe/zowe-cli/wiki) is a key source of information to learn about the features of Imperative CLI Framework, the code framework that you use to build plug-ins for Zowe CLI. Refer to these supplementary documents during development to learn about specific features such as: - Auto-generated help - JSON responses - User profiles -- Logging, progress bars, experimental commands, and more! +- Logging, progress bars, experimental commands, and more - Authentication mechanisms - -### Authentication mechanisms - -As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe. - -Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with. - -However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. Extenders can modify this order for their plug-in. - -To learn the authentication methods used for different services and their order of precedence, refer to the following table: - -service | Zowe V1 order of precedence | Zowe V2 order of precedence -|:--- |:--- |:--- | -API ML | 1. username, password
2. API ML token | 1. username, password
2. API ML token
3. PEM certificate | -Db2,
FTP,
most other services | username, password | username, password -SSH | 1. SSH key
2. username, password | 1. SSH key
2. username, password - ZOSMF
direct connection | username, password | 1. username, password
2. PEM certificate diff --git a/docs/extend/extend-cli/cli-developing-a-plugin.md b/docs/extend/extend-cli/cli-developing-a-plugin.md index 290b098d52..0e635f74e7 100644 --- a/docs/extend/extend-cli/cli-developing-a-plugin.md +++ b/docs/extend/extend-cli/cli-developing-a-plugin.md @@ -1,21 +1,22 @@ # Developing a new Zowe CLI plug-in -Before you begin this tutorial, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. + +Before you begin, complete the [Extending an existing plug-in](cli-extending-a-plugin.md) tutorial. ## Overview + The advantage of Zowe CLI and of the CLI approach in mainframe development is that it allows for combining different developer tools for new and interesting uses. This tutorial demonstrates how to create a brand new Zowe CLI plug-in that uses Node.js to create a client-side API. -After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial will also show you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). +After following all the steps, you will have created a data set diff utility plug-in called **Files Util Plug-in**. This plug-in takes in any two data sets, or files, and returns a plain text output in the terminal showing how they differ. This tutorial also shows you how you can integrate your new plug-in with a third-party utility to make your output colorful and easier to read, as shown in the image at the [bottom of this page](../extend-cli/cli-developing-a-plugin#bringing-together-new-tools). If you are ready to create your own unique Zowe CLI plug-in, refer to the notes at the end of each tutorial step for guidance. If you are interested in creating a credential manager plug-in, see the [Zowe CLI secrets for kubernetes plug-in](https://github.com/zowe/zowe-cli-secrets-for-kubernetes) repository. ## Setting up the new sample plug-in project - Download the sample plug-in source and delete the irrelevant content to set up your plug-in project. - - Follow these steps: + + Download the sample plug-in source and delete the irrelevant content to set up your plug-in project: 1. Open a terminal and run the command `mkdir zowe-tutorial`. @@ -49,7 +50,11 @@ If you are interested in creating a credential manager plug-in, see the [Zowe CL If vulnerabilities are found in any of the installed dependencies, refer to [npm Docs](https://docs.npmjs.com/cli/v9/commands/npm-audit) for how to fix them. ::: -**To create a unique plug-in:** Change the `files-util` directory to a name applicable for your project. +:::tip To create a unique plug-in + +Change the `files-util` directory to a name applicable for your project. + +::: ## Updating `package.json` @@ -63,7 +68,11 @@ Open the `package.json` file in a text editor and replace the name field with th This tutorial uses `@zowe/files-util` as the tutorial plug-in name. -**To create a unique plug-in:** Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). +:::tip To create a unique plug-in + +Replace `@zowe/files-util` with a unique plug-in name. This allows you to publish the plug-in under that name to the `npm` registry in the future. For information regarding npm scoping, see the [npm documentation](https://docs.npmjs.com/cli/v9/using-npm/scope). + +::: ## Adjusting Imperative CLI Framework configuration @@ -86,13 +95,15 @@ export = config; When successful, the `src/pluginDef.ts` file contains the new configurations. -**To create a unique plug-in:** Change the plug-in name, display name, and description according to your project. +:::tip To create a unique plug-in -## Adding third-party packages +Change the plug-in name, display name, and description according to your project. -Install third-party packages as dependencies for the plug-in's client-side API. +::: - Follow these steps: +## Adding third-party packages + +Install third-party packages as dependencies for the plug-in's client-side API: 1. Run `npm install --save-exact diff` to install the diff package (which includes methods for comparing text). @@ -100,12 +111,15 @@ Install third-party packages as dependencies for the plug-in's client-side API. When successful, the `diff` and `@types/diff` packages are added to the dependency list in the `package.json` file. -**To create a unique plug-in:** Instead of the `diff` package, install the package(s) that are required for your API, if any. +:::tip To create a unique plug-in + +Instead of the `diff` package, install the package(s) that are required for your API, if any. + +::: ## Creating a Node.js client-side API -Create a client-side API that compares the contents of two data sets on the mainframe. -Follow these steps: +Create a client-side API that compares the contents of two data sets on the mainframe: 1. In the `src/api` directory, create a file named `DataSetDiff.ts`. @@ -170,11 +184,15 @@ Follow these steps: When successful, the `index.ts` file contains the new code. -**To create a unique plug-in:** The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. +:::tip To create a unique plug-in + +The file name and code in Step 2 may be entirely different if you want to implement an API to do something else. + +::: ## Building your plug-in source -To confirm that your project builds successfully: +Confirm that your project builds successfully: 1. Due to missing license headers, you will come across linting errors. Run `npm run lint:fix` to resolve the errors automatically. @@ -186,7 +204,11 @@ To confirm that your project builds successfully: The `lib` directory is configurable by modifying [this value](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/tsconfig.json#L12) in the `tsconfig.json` file. -**To create a unique plug-in:** Follow these same steps. +:::tip To create a unique plug-in + +Follow these same steps. + +::: ## Creating a Zowe CLI command @@ -275,17 +297,19 @@ If you are adding multiple commands to your CLI plug-in, consider moving the cod ::: -**To create a unique plug-in:** Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. +:::tip To create a unique plug-in + +Refer to file names specific to your project. Your code likely follows the same structure, but command name, handler, definition, and other information would differ. + +::: ## Trying your command Before you test your new command, confirm that you are able to connect to the mainframe. -In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Using profiles](../../user-guide/cli-using-using-team-profiles/) for information. +In order for the client-side API to reach the mainframe (to fetch data sets), Zowe CLI needs a z/OSMF profile for access. See [Team configurations](../../user-guide/cli-using-using-team-profiles/) for information. -Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time. - -Follow these steps: +Once the connection between Zowe CLI and z/OSMF is confirmed, build and install the plug-in before running it for the first time: 1. Repeat the steps in [Building your plug-in source](../extend-cli/cli-developing-a-plugin#building-your-plug-in-source). @@ -329,9 +353,13 @@ Follow these steps: When successful, the output displays plain text diffs of the entered data sets. -**To create a unique plug-in:** Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. +:::tip To create a unique plug-in -## Bringing together new tools! +Use Step 3 to run your new command. Note that the command is different based on the plug-in name in the `src/pluginDef.ts` file. + +::: + +## Bringing together new tools You have created a simple CLI plug-in that provides plain text diffs of two data sets. But you may not want to end there. @@ -343,8 +371,6 @@ To help fix this, you can extend **Files Util Plug-in** to create a more visual |:--:| | Diff to HTML by [rtfpessoa](https://github.com/rtfpessoa)| -Follow these steps: - 1. Run `npm install --global diff2html-cli` to install `diff2html`. :::note diff --git a/docs/extend/extend-cli/cli-extending-a-plugin.md b/docs/extend/extend-cli/cli-extending-a-plugin.md index 9aad0e9832..bf2a8a7c65 100644 --- a/docs/extend/extend-cli/cli-extending-a-plugin.md +++ b/docs/extend/extend-cli/cli-extending-a-plugin.md @@ -1,86 +1,88 @@ # Extending a plug-in + Before you begin, be sure to complete the [Installing the sample plug-in](cli-installing-sample-plugin.md) tutorial. ## Overview -This tutorial demonstrates how to extend the plug-in that is bundled with this sample by: - -1. Creating a Typescript interface for the Typicode response data -2. Creating a programmatic API -3. Creating a command definition -4. Creating a command handler - -We'll do this by using `@zowe/imperative` infrastructure to surface REST API data on our Zowe™ CLI plug-in. +This tutorial uses the Typicode REST API as a guide for how to build a Zowe CLI plug-in that interacts with REST APIs on the mainframe. -Specifically, we're going to show data from [this URI](https://jsonplaceholder.typicode.com/todos) by [Typicode](https://jsonplaceholder.typicode.com/). -Typicode serves sample REST JSON data for testing purposes. +At the end of this tutorial, you are able to use the following new command from the Zowe CLI interface: -At the end of this tutorial, you will be able to use a new command from the Zowe CLI interface: `zowe zowe-cli-sample list typicode-todos` +``` +zowe zowe-cli-sample list typicode-todos +``` -Completed source for this tutorial can be found on the `typicode-todos` branch of the zowe-cli-sample-plugin repository. +The completed source for this tutorial can be found on the `typicode-todos` branch of the [`zowe-cli-sample-plugin`](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) repository. ### Creating a Typescript interface for the Typicode response data -First, we'll create a Typescript interface to map the response data from a server. +First, create a Typescript interface to map the response data from a server: -Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain our interface (sometimes referred to as a "document" or "doc"). Within the doc folder, create a file named `ITodo.ts`. +1. Within `zowe-cli-sample-plugin/src/api`, create a folder named `doc` to contain the interface. The interface specifies the properties that we expect from the JSON response. -The `ITodo.ts` file will contain the following: +2. In the `doc` folder, create a file named `ITodo.ts`. -```typescript -export interface ITodo { - userId: number; - id: number; - title: string; - completed: boolean; -} -``` +3. Edit the `ITodo.ts` file to contain the following code: + + ```typescript + export interface ITodo { + userId: number; + id: number; + title: string; + completed: boolean; + } + ``` ### Creating a programmatic API -Next, we'll create a Node.js API that our command handler uses. This API can also be used in any Node.js application, because these Node.js APIs make use of REST APIs, Node.js APIs, other NPM packages, or custom logic to provide higher level functions than are served by any single API. +Next, create a Node.js API for the command handler to use. -Adjacent to the existing file named `zowe-cli-sample-plugin/src/api/Files.ts`, create a file `Typicode.ts`. +This API can also be used in any Node.js application. -`Typicode.ts`should contain the following: +1. Create a file named `Typicode.ts` in the `zowe-cli-sample-plugin/src/api` directory. -```typescript -import { ITodo } from "./doc/ITodo"; -import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; +2. Edit the `Typicode.ts` file to contain the following code: -export class Typicode { + ```typescript + import { ITodo } from "./doc/ITodo"; + import { RestClient, AbstractSession, ImperativeExpect, Logger } from "@zowe/imperative"; - public static readonly TODO_URI = "/todos"; + export class Typicode { - public static getTodos(session: AbstractSession): Promise { - Logger.getAppLogger().trace("Typicode.getTodos() called"); - return RestClient.getExpectJSON(session, Typicode.TODO_URI); - } + public static readonly TODO_URI = "/todos"; + + public static getTodos(session: AbstractSession): Promise { + Logger.getAppLogger().trace("Typicode.getTodos() called"); + return RestClient.getExpectJSON(session, Typicode.TODO_URI); + } - public static getTodo(session: AbstractSession, id: number): Promise { - Logger.getAppLogger().trace("Typicode.getTodos() called with id " + id); - ImperativeExpect.toNotBeNullOrUndefined(id, "id must be provided"); - const resource = Typicode.TODO_URI + "/" + id; - return RestClient.getExpectJSON(session, resource); + public static getTodo(session: AbstractSession, id: number): Promise { + Logger.getAppLogger().trace("Typicode.getTodos() called with id " + id); + ImperativeExpect.toNotBeNullOrUndefined(id, "id must be provided"); + const resource = Typicode.TODO_URI + "/" + id; + return RestClient.getExpectJSON(session, resource); + } } -} -``` + ``` -The `Typicode` class provides two programmatic APIs, `getTodos` and `getTodo`, to get an array of `ITodo` objects or a specific -`ITodo` respectively. The Node.js APIs use `@zowe/imperative` infrastructure to provide logging, parameter validation, -and to call a REST API. See the [Imperative CLI Framework documentation](https://github.com/zowe/imperative/wiki) for more information. + The `Typicode` class provides two programmatic APIs, `getTodos` and `getTodo`, to get an array of `ITodo` objects or a specific `ITodo`, respectively. -#### Exporting interface and programmatic API for other Node.js applications + The Node.js APIs use `@zowe/imperative` infrastructure to provide logging, parameter validation, and to call a REST API. See the [Imperative CLI Framework documentation](https://github.com/zowe/zowe-cli/wiki) for more information. -Update [zowe-cli-sample-plugin/src/index.ts](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/index.ts) to contain the following: +#### Exporting the interface and programmatic API for other Node.js applications + +Edit the [zowe-cli-sample-plugin/src/index.ts](https://github.com/zowe/zowe-cli-sample-plugin/blob/master/src/index.ts) file to contain the following code: ```typescript export * from "./api/doc/ITodo"; export * from "./api/Typicode"; ``` -A sample invocation of your API might look similar to the following, if it were used by a separate, standalone Node.js application: +This allows a separate, standalone Node.js application to use APIs from the sample Typicode plug-in to get data from the REST API at jsonplaceholder.typicode.com. + +The following code is an example of how a Node.js application could import classes from your API to interact with the Typicode REST API: + ```typescript import { Typicode } from "@zowe/zowe-cli-sample-plugin"; import { Session, Imperative } from "@zowe/imperative"; @@ -93,91 +95,116 @@ const session = new Session({ hostname: "jsonplaceholder.typicode.com"}); })(); ``` -### Checkpoint one +### Verify that you can build the programmatic API -Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present. At this point in this tutorial, you have a programmatic API -that will be used by your handler or another Node.js application. Next you'll define the command syntax for the command that will use your programmatic Node.js APIs. +In your terminal, issue `npm run build` in your terminal to verify a clean compilation and confirm that no lint errors are present. + +At this point, you have a programmatic API that can be used by your handler or another Node.js application. Next, define the command syntax for the command that uses your programmatic Node.js APIs. ### Creating a command definition -Within Zowe CLI, the full command that we want to create is `zowe zowe-cli-sample list typicode-todos`. Navigate to `zowe-cli-sample-plugin/src/cli/list` and create a folder -`typicode-todos`. Within this folder, create `TypicodeTodos.definition.ts`. Its content should be as follows: -```typescript -import { ICommandDefinition } from "@zowe/imperative"; -export const TypicodeTodosDefinition: ICommandDefinition = { - name: "typicode-todos", - aliases: ["td"], - summary: "Lists typicode todos", - description: "List typicode REST sample data", - type: "command", - handler: __dirname + "/TypicodeTodos.handler", - options: [ - { - name: "id", - description: "The todo to list", - type: "number" - } - ] -}; +This tutorial creates the following command in Zowe CLI: + +``` +zowe zowe-cli-sample list typicode-todos` ``` -This describes the syntax of your command. -#### Defining command to list group +#### Defining the syntax of your command -Within the file `zowe-cli-sample-plugin/src/cli/list/List.definition.ts`, add the following code below other `import` statements near the top of the file: -```typescript -import { TypicodeTodosDefinition } from "./typicode-todos/TypicodeTodos.definition"; -``` +1. Navigate to `zowe-cli-sample-plugin/src/cli/list` and create a folder titled `typicode-todos`. -Then add `TypicodeTodosDefinition` to the children array. For example: -``` -children: [DirectoryContentsDefinition, TypicodeTodosDefinition] -``` +2. In this folder, create a file named `TypicodeTodos.definition.ts`. + + Edit the `TypicodeTodos.definition.ts` file to contain the following code: + + ```typescript + import { ICommandDefinition } from "@zowe/imperative"; + export const TypicodeTodosDefinition: ICommandDefinition = { + name: "typicode-todos", + aliases: ["td"], + summary: "Lists typicode todos", + description: "List typicode REST sample data", + type: "command", + handler: __dirname + "/TypicodeTodos.handler", + options: [ + { + name: "id", + description: "The todo to list", + type: "number" + } + ] + }; + ``` + + The `TypicodeTodos.definition.ts` file describes the syntax of your command. + +#### Adding a command to a command group + +Add the newly created `TypicodeTodosDefinition` to the `list` command group to enable users to list to-dos by running the `zowe zowe-cli-sample list typicode-todos` command. + +1. In `zowe-cli-sample-plugin/src/cli/list/List.definition.ts`, add the following code below other `import` statements near the top of the file: + ```typescript + import { TypicodeTodosDefinition } from "./typicode-todos/TypicodeTodos.definition"; + ``` + +2. To the children array, add `TypicodeTodosDefinition`. + + For example: + ``` + children: [DirectoryContentsDefinition, TypicodeTodosDefinition] + ``` + The command is added to the `list` command group. ### Creating a command handler -Also within the `typicode-todos` folder, create `TypicodeTodos.handler.ts`. Add the following code to the new file: -```typescript -import { ICommandHandler, IHandlerParameters, TextUtils, Session } from "@zowe/imperative"; -import { Typicode } from "../../../api/Typicode"; -export default class TypicodeTodosHandler implements ICommandHandler { - - public static readonly TYPICODE_HOST = "jsonplaceholder.typicode.com"; - public async process(params: IHandlerParameters): Promise { - - const session = new Session({ hostname: TypicodeTodosHandler.TYPICODE_HOST}); - if (params.arguments.id) { - const todo = await Typicode.getTodo(session, params.arguments.id); - params.response.data.setObj(todo); - params.response.console.log(TextUtils.prettyJson(todo)); - } else { - const todos = await Typicode.getTodos(session); - params.response.data.setObj(todos); - params.response.console.log(TextUtils.prettyJson(todos)); +1. In the `typicode-todos` folder, create the file `TypicodeTodos.handler.ts`. + +2. Add the following code to the `TypicodeTodos.handler.ts` file: + ```typescript + import { ICommandHandler, IHandlerParameters, TextUtils, Session } from "@zowe/imperative"; + import { Typicode } from "../../../api/Typicode"; + export default class TypicodeTodosHandler implements ICommandHandler { + + public static readonly TYPICODE_HOST = "jsonplaceholder.typicode.com"; + public async process(params: IHandlerParameters): Promise { + + const session = new Session({ hostname: TypicodeTodosHandler.TYPICODE_HOST}); + if (params.arguments.id) { + const todo = await Typicode.getTodo(session, params.arguments.id); + params.response.data.setObj(todo); + params.response.console.log(TextUtils.prettyJson(todo)); + } else { + const todos = await Typicode.getTodos(session); + params.response.data.setObj(todos); + params.response.console.log(TextUtils.prettyJson(todos)); + } } } -} -``` -The `if` statement checks if a user provides an `--id` flag. If yes, we call `getTodo`. Otherwise, we call `getTodos`. If the -Typicode API throws an error, the `@zowe/imperative` infrastructure will automatically surface this. + ``` + + The `if` statement checks if a user provides an `--id` flag. If yes, the command handler calls `getTodo`. Otherwise, the command handler calls `getTodos`. + + If the Typicoce API throws an error, the error is forwarded to `@zowe/imperative` to log the error and display an error message in the terminal. -### Checkpoint two +### Verify that you can build your plug-in -Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present. You now have a handler, definition, and your command has been defined to the `list` group of the command. +Issue `npm run build` to verify a clean compilation and confirm that no lint errors are present. + +You now have a command definition, the command has been added to the `list` command group, and you have a handler. ## Using the installed plug-in -Issue the command: `zowe zowe-cli-sample list typicode-todos` +Issue the command `zowe zowe-cli-sample list typicode-todos`. -Refer to `zowe zowe-cli-sample list typicode-todos --help` for more information about your command and to see how text in the command definition -is presented to the end user. You can also see how to use your optional `--id` flag: +Refer to `zowe zowe-cli-sample list typicode-todos --help` for more information about your command and to see how text in the command definition is presented to the end user. You can also see how to use your optional `--id` flag: ![output](../../images/guides/CLI/completedSample.png) ## Summary You extended an existing Zowe CLI plug-in by introducing a Node.js programmatic API, and you created a command definition with a handler. -For an official plugin, you would also add [JSDoc](https://jsdoc.app/) to your code and create automated tests. + +For an official Zowe CLI plug-in, you would also add [JSDoc](https://jsdoc.app/) to your code and create automated tests. ## Next steps diff --git a/docs/extend/extend-cli/cli-implement-profiles.md b/docs/extend/extend-cli/cli-implement-profiles.md index 973becca3e..16e707a4fc 100644 --- a/docs/extend/extend-cli/cli-implement-profiles.md +++ b/docs/extend/extend-cli/cli-implement-profiles.md @@ -1,74 +1,106 @@ # Implementing profiles in a plug-in -You can use this profile template to create a profile for your product. - -The profile definition is placed in the `imperative.ts` file. - -The `type: "someproduct"` property represents the profile name that you might require on various commands to have credentials loaded -from a secure credential manager and retain the host/port information, so that you can easily swap to different servers from the CLI. - - By default, if your plug-in that is installed into Zowe™ CLI contains a profile definition that is similar to the following example, a profile template is added automatically to team config JSON when you run the `zowe config init` command. Any properties for which `includeInTemplate` is true are included in the template. Additionally, commands that manage V1 profiles are created automatically under `zowe profiles`. For example, `create`, `validate`, `set-default`, `list`, and so on. - - -```typescript -profiles: [ - { - type: "someproduct", - schema: { - type: "object", - title: "Configuration profile for SOME PRODUCT", - description: "Configuration profile for SOME PRODUCT ", - properties: { - host: { - type: "string", - optionDefinition: { - type: "string", - name: "host", - alias:["H"], - description: "Host name of your SOME PRODUCT REST API server" - } - }, - port: { - type: "number", - optionDefinition: { - type: "number", - name: "port", - alias:["P"], - includeInTemplate: true, - description: "Port number of your SOME PRODUCT REST API server" - } - }, - user: { - type: "string", - optionDefinition: { - type: "string", - name: "user", - alias:["u"], - description: "User name to authenticate to your SOME PRODUCT REST API server" - }, - secure: true - }, - password: { - type: "string", - optionDefinition: { - type: "string", - name: "password", - alias:["p"], - description: "Password to authenticate to your SOME PRODUCT REST API server" + +Users of your plug-in communicate with the mainframe by specifying connection information in a configuration profile. + +For profiles to work with services other than z/OSMF, SSH, and TSO, developers must define profile types and the profile structure for their plug-in in a special file. This plug-in definition file ultimately allows an end user to add the plug-in profile — and its connection details — to their team configuration. + +When creating profile types for a plug-in, apply the following code as a template to the plug-in definition file. Modify the template as necessary by changing values and/or adding more properties. + +## Editing the plug-in definition file + +You can specify the plug-in definition file name and location in your plug-in's `package.json` file. For example: + +``` +"imperative": { + "configurationModule": "lib/pluginDef.js" + }, +``` + + - `pluginDef.js` + + The runtime file + + - `src/pluginDef.ts` + + Location of your definition source + +Edit the `pluginDef.ts` file (or your equivalent) to define profile types for your plug-in: + +1. Use a text editor to open the `pluginDef.ts` file. + +2. In the `pluginDef.ts` file, add the following profile definition: + + ```typescript + profiles: [ + { + type: "someproduct", + schema: { + type: "object", + title: "Configuration profile for SOME PRODUCT", + description: "Configuration profile for SOME PRODUCT ", + properties: { + host: { + type: "string", + optionDefinition: { + type: "string", + name: "host", + alias:["H"], + description: "Host name of your SOME PRODUCT REST API server" + } + }, + port: { + type: "number", + optionDefinition: { + type: "number", + name: "port", + alias:["P"], + includeInTemplate: true, + description: "Port number of your SOME PRODUCT REST API server" + } + }, + user: { + type: "string", + optionDefinition: { + type: "string", + name: "user", + alias:["u"], + description: "User name to authenticate to your SOME PRODUCT REST API server" + }, + secure: true + }, + password: { + type: "string", + optionDefinition: { + type: "string", + name: "password", + alias:["p"], + description: "Password to authenticate to your SOME PRODUCT REST API server" + }, + secure: true + }, }, - secure: true }, - }, - }, - createProfileExamples: [ - { - options: "spprofile --host zos123 --port 1234 --user ibmuser --password myp4ss", - description: "Create a SOME PRODUCT profile named 'spprofile' to connect to SOME PRODUCT at host zos123 and port 1234" } - ] - } -] -``` + ] + ``` +3. Replace `someproduct` in `type: "someproduct"` with your plug-in profile name. + + This property represents the name of the profile type option that might be required on commands that allow users to select a profile from their team configuration. (Zowe CLI has profile types for z/OSMF, SSH, and TSO.) + + - For example, the `zowe zosmf check status --zosmf-profile` command includes an option that specifies a z/OSMF profile from the user's team configuration. For your plug-in, the profile type that you define can be used in a commands to specify a profile for your plug-in. + + This value is used in team configuration to create a plug-in profile to connect to the mainframe. + +4. Update the title and description for your plug-in. + +5. Add any needed properties to allow users to configure plug-in settings. + + Each option property in the template includes an `optionDefinition`. For a reference of `optionDefinition` attributes, see the [`ICommandOptionDefinition` interface](https://github.com/zowe/zowe-cli/blob/master/packages/imperative/src/cmd/src/doc/option/ICommandOptionDefinition.ts). + +6. Set the `includeInTemplate` property to `true` to dictate that this property is included in any generated team configuration. + + If set to `false` or not included, end users will have to add the property themselves when editing their team configuration. -**Next steps** +7. Set the `secure` property to `true` to ensure that any value the end user specifies for this property is stored by default in their secure credential store. Otherwise the value is stored as plain text. -If you completed all previous tutorials, you now understand the basics of extending and developing plug-ins for Zowe CLI. Next, we recommend reviewing the project [contribution guidelines](cli-devTutorials.md#contribution-guidelines) and [Imperative CLI Framework documentation](cli-devTutorials.md#imperative-cli-framework-documentation) to learn more. \ No newline at end of file + The profile has been defined as needed. diff --git a/docs/extend/extend-cli/cli-installing-sample-plugin.md b/docs/extend/extend-cli/cli-installing-sample-plugin.md index 8f7ec4f5fb..203f5b45e3 100644 --- a/docs/extend/extend-cli/cli-installing-sample-plugin.md +++ b/docs/extend/extend-cli/cli-installing-sample-plugin.md @@ -1,36 +1,48 @@ # Installing the sample plug-in -Before you begin, [set up](cli-setting-up.md) your local environment to install a plug-in. +This tutorial covers installing and running the [Zowe™ CLI sample plug-in](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in), which adds a command to the CLI to list the contents of a directory on your computer. -## Overview -This tutorial covers installing and running this bundled Zowe™ CLI plugin as-is (without modification), which adds a command to the CLI that lists the contents of a directory on your computer. +Before you begin, [set up](cli-setting-up.md) your local environment to install a plug-in. ## Installing the sample plug-in to Zowe CLI -To begin, `cd` into your `zowe-tutorial` folder. (See [Initial setup](cli-setting-up.md#initial-setup) for instructions on creating the `zowe-tutorial` folder.) +To install the Zowe CLI sample plug-in: + +1. Open a terminal and enter `cd zowe-tutorial` to change directory into your `zowe-tutorial` folder. + + See [Initial setup](cli-setting-up.md#initial-setup) for instructions on creating the `zowe-tutorial` folder. + +2. Issue the following command to install the sample plug-in to Zowe CLI: -Issue the following commands to install the sample plug-in to Zowe CLI: + ``` + zowe plugins install ./zowe-cli-sample-plugin + ``` -`zowe plugins install ./zowe-cli-sample-plugin` + The Zowe CLI Sample Plug-in is installed. ## Viewing the installed plug-in -Issue `zowe --help` in the command line to return information for the installed `zowe-cli-sample` command group: + +Open a terminal and issue the `zowe --help`command to return information for the installed `zowe-cli-sample` command group: ![Installed](../../images/guides/CLI/InstalledSample.png "Installed Sample Plugin") ## Using the installed plug-in -To use the plug-in functionality, issue: `zowe zowe-cli-sample list directory-contents`: + +Open a terminal and issue the `zowe zowe-cli-sample list directory-contents` command: ![Output](../../images/guides/CLI/SampleOutput.png "Sample Plugin Output") ## Testing the installed plug-in -To run automated tests against the plug-in, `cd` into your `zowe-tutorial/zowe-cli-sample-plugin` folder. -Issue the following command: +1. Open a terminal and enter `cd zowe-tutorial/zowe-cli-sample-plugin` to run automated tests against the plug-in. -``` -npm run test -``` +2. Issue the following command: + + ``` + npm run test + ``` + The command runs the automated unit and system tests defined in the `__tests__` folder. Test results are displayed in the terminal with the count of passed and failed tests. Failed tests are identified in the results. ## Next steps -You successfully installed a plug-in to Zowe CLI! Next, try the [Extending a plug-in](cli-extending-a-plugin.md) tutorial to learn about developing new commands for this plug-in. \ No newline at end of file + +You successfully installed a plug-in to Zowe CLI! Next, try the [Extending a plug-in](cli-extending-a-plugin.md) tutorial to learn about developing new commands for this plug-in. diff --git a/docs/extend/extend-cli/cli-setting-up.md b/docs/extend/extend-cli/cli-setting-up.md index e3fc70ec16..fd6e1e74d0 100644 --- a/docs/extend/extend-cli/cli-setting-up.md +++ b/docs/extend/extend-cli/cli-setting-up.md @@ -5,43 +5,36 @@ Before you follow the development tutorials for creating a Zowe™ CLI plug- [Install Zowe CLI](../../user-guide/cli-installcli#methods-to-install-zowe-cli). ## Initial setup -To create your development space, clone and build [zowe-cli-sample-plugin](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) from source. -Before you clone the repository, create a local development folder named `zowe-tutorial`. You will clone and build all projects in this folder. +### Clone and build your project -## Branches +1. Create a local development folder named `zowe-tutorial` to clone and build all projects in this folder. -There are two branches in the repository that correspond to different Zowe CLI versions. You can develop two branches of your plug-in so that users can install your plug-in into `@latest` or `@zowe-v2-lts` CLI. Developing for both versions will let you take advantage of new core features quickly and expose your plug-in to a wider range of users. +2. Clone [`zowe-cli-sample-plugin`](https://github.com/zowe/zowe-cli-sample-plugin/#zowe-cli-sample-plug-in) and build from source. -The `master` branch of Sample Plug-in is compatible with the `@zowe-v2-lts` version of core CLI (Zowe LTS release). + Clone the repository into your development folder to match the following structure: + ``` + zowe-tutorial + └── zowe-cli-sample-plugin + ``` -The `master` branch of Sample Plug-in is also compatible with the `@latest` version of core CLI (Zowe Active Development release) at this time. + 1. Open a terminal and enter `cd zowe-tutorial` to change directory into your `zowe-tutorial` folder. + 2. Enter `git clone https://github.com/zowe/zowe-cli-sample-plugin` to clone the `zowe-cli-sample-plugin` repository. + 3. Enter `cd zowe-cli-sample-plugin` to change directory into your `zowe-cli-sample-plugin` folder. + 4. Enter `npm install` to install all dependencies and modules for the project. + 5. Enter `npm run build` to create a production build. -For more information about the versioning scheme, see [Maintainer Versioning](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) in the Zowe CLI repository. +### Optional step: Run automated tests -### Clone zowe-cli-sample-plugin and build from source -Clone the repository into your development folder to match the following structure: -``` -zowe-tutorial -└── zowe-cli-sample-plugin -``` -**Follow these steps:** +We recommend running automated tests on all code changes. -1. `cd` to your `zowe-tutorial` folder. -2. `git clone https://github.com/zowe/zowe-cli-sample-plugin` -3. `cd` to your `zowe-cli-sample-plugin` folder. -4. `git checkout master` -5. `npm install` -6. `npm run build` +To run automated tests: -### (Optional) Run the automated tests -We recommend running automated tests on all code changes. Follow these steps: - -1. `cd` to the `__tests__/__resources__/properties` folder. -2. Copy `example_properties.yaml` to `custom_properties.yaml`. -3. Edit the properties within `custom_properties.yaml` to contain valid system information for your site. -4. `cd` to your `zowe-cli-sample-plugin` folder -5. `npm run test` +1. Use Visual Studio Code or your file explorer to copy the content in the `example_properties.yaml` file to the `custom_properties.yaml` file. +2. Use a text editor to edit the properties within `custom_properties.yaml` to contain valid system information for your site. +3. In a terminal, enter `cd zowe-cli-sample-plugin` to change directory into your `zowe-cli-sample-plugin` folder. +4. Enter `npm run test` to run the automated test. ## Next steps + After you complete your setup, follow the [Installing the sample plug-in](cli-installing-sample-plugin.md) tutorial to install this sample plug-in to Zowe CLI. diff --git a/docs/extend/extend-cli/cli-tutorials.md b/docs/extend/extend-cli/cli-tutorials.md new file mode 100644 index 0000000000..fede8c1302 --- /dev/null +++ b/docs/extend/extend-cli/cli-tutorials.md @@ -0,0 +1,11 @@ +# Tutorials + +To better understand how to extend Zowe CLI and Zowe CLI plug-ins, read through the Extend tutorials. + +The following topics are covered in the tutorials: + +1. [Setting up:](cli-setting-up.md) Clone the project and prepare your local environment. +2. [Installing a plug-in:](cli-installing-sample-plugin.md) Install the sample plug-in to Zowe CLI and run as-is. +3. [Extending a plug-in:](cli-extending-a-plugin.md) Extend the sample plug-in with a new command by creating a programmatic API, definition, and handler. +4. [Creating a new plug-in:](cli-developing-a-plugin.md) Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets. +5. [Implementing user profiles:](cli-implement-profiles.md) Implement user profiles with the plug-in. \ No newline at end of file diff --git a/docs/extend/extend-desktop/mvd-conda.md b/docs/extend/extend-desktop/mvd-conda.md index b884107b38..34431b99b9 100644 --- a/docs/extend/extend-desktop/mvd-conda.md +++ b/docs/extend/extend-desktop/mvd-conda.md @@ -4,8 +4,8 @@ As Zowe is composed of components which can be extended by Plugins, a standardized and simple way to find, install, upgrade, and list Plugins in your Zowe environment is important to make it easy to get the most out of Zowe. -Package management as a concept generally provides a way to find packages such as plug-ins, check and possibly co-install dependencies the package has, and ultimately install the desired package. - +Package management as a concept generally provides a way to find packages such as plugins, +check and possibly co-install dependencies the package has, and ultimately install the desired package. Post-install, management tasks such as upgrading and uninstalling are common. Conda is one such package manager, and if you are familiar with apt, yum, or npm, you will find diff --git a/docs/extend/extend-desktop/mvd-configdataservice.md b/docs/extend/extend-desktop/mvd-configdataservice.md index 02da7ce37c..d3995fa1e9 100644 --- a/docs/extend/extend-desktop/mvd-configdataservice.md +++ b/docs/extend/extend-desktop/mvd-configdataservice.md @@ -306,5 +306,5 @@ The following policies are currently implemented: ## Examples - [zlux-app-manager](https://github.com/zowe/zlux-app-manager/tree/v2.x/master/bootstrap/src/uri/mvd-uri.ts) - [VT Terminal App](https://github.com/zowe/vt-ng2/blob/v2.x/master/webClient/src/app/app.component.ts) + [zlux-app-manager](https://github.com/zowe/zlux-app-manager/tree/v3.x/master/bootstrap/src/uri/mvd-uri.ts) + [VT Terminal App](https://github.com/zowe/vt-ng2/blob/v3.x/master/webClient/src/app/app.component.ts) diff --git a/docs/extend/extend-desktop/mvd-externals.md b/docs/extend/extend-desktop/mvd-externals.md index f672df67d5..420175de42 100644 --- a/docs/extend/extend-desktop/mvd-externals.md +++ b/docs/extend/extend-desktop/mvd-externals.md @@ -1,27 +1,26 @@ -In the Zowe Desktop, multiple Apps can coexist but such Apps are treated as independent entities, and may be independently developed. To keep resources in check while allowing for Apps to depend on rich libraries, common libraries are deduplicated by having Apps refer to a collection of these libraries, considered the "Externals" bundle. This bundle is loaded on page load from `/ZLUX/plugins/org.zowe.zlux.ng2desktop/web/externals.js`. The current list of libraries that are present in this bundle is: +In the Zowe Desktop, multiple Apps can coexist but such Apps are treated as independent entities, and may be independently developed. To keep resources in check while allowing for Apps to depend on rich libraries, common libraries are deduplicated by having Apps refer to a collection of these libraries, considered the "Externals" bundle. This bundle is loaded on page load from `/ZLUX/plugins/org.zowe.zlux.ng2desktop/web/main.js`. The current list of libraries that are present in this bundle is: | Library | Version | |---------|---------| -| '@angular/animations' | 12.0.0 | -| '@angular/cdk' | 12.0.0 | -| '@angular/core' | 12.0.0 | -| '@angular/common' | 12.0.0 | -| '@angular/common/http' | 12.0.0 | -| '@angular/forms' | 12.0.0 | -| '@angular/platform-browser' | 12.0.0 | -| '@angular/cdk/portal' | 12.0.0 | -| '@angular/material' | 12.0.0 | -| '@angular/router' | 12.0.0 | -| 'angular-l10n' | 12.0.0 | -| 'bootstrap' | 4.3.1 | -| 'corejs' | 3.19.2 | -| 'jquery' | 3.6.0 | +| '@angular/animations' | 18.0.0 | +| '@angular/cdk' | 18.0.0 | +| '@angular/core' | 18.0.0 | +| '@angular/common' | 18.0.0 | +| '@angular/common/http' | 18.0.0 | +| '@angular/forms' | 18.0.0 | +| '@angular/platform-browser' | 18.0.0 | +| '@angular/cdk/portal' | 18.0.0 | +| '@angular/material' | 18.0.0 | +| '@angular/router' | 18.0.0 | +| 'angular-l10n' | 18.0.0 | +| 'bootstrap' | 5.3.2 | +| 'corejs' | 3.38.1 | | 'popper.js' | 1.14.7 | -| 'rxjs' | 6.6.0 | +| 'rxjs' | 7.8.1 | The above list is derived from 3 source files. Please consult them for up-to-date information: -1) [package-lock.json](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/package-lock.json) for version information -2) [externals.ts](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/src/externals.ts) which loads the libraries into the browser at page load -3) [externals-main.ts](https://github.com/zowe/zlux-app-manager/blob/v2.x/master/virtual-desktop/src/externals-main.ts) which imports libraries that were not loadable with the technique in #2 +1) [package-lock.json](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/package-lock.json) for version information +2) [desktop.ts](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/src/desktop.ts) which loads the libraries into the browser at page load +3) [webpack5.base.js](https://github.com/zowe/zlux-app-manager/blob/v3.x/staging/virtual-desktop/plugin-config/webpack5.base.js) which is an example of how a plugin may depend upon these libraries without including them, via the "externals" configuration object. Apps that are not of type "iframe" should not use any other versions of these libraries, due to the chance for conflict to occur at runtime. diff --git a/docs/extend/extend-desktop/mvd-iframecomm.md b/docs/extend/extend-desktop/mvd-iframecomm.md index fba0d54281..ead4de3299 100644 --- a/docs/extend/extend-desktop/mvd-iframecomm.md +++ b/docs/extend/extend-desktop/mvd-iframecomm.md @@ -1,5 +1,5 @@ # Configuring IFrame communication -The Zowe Application Framework provides the following shared resource functions through a [ZoweZLUX object](https://github.com/zowe/zlux-platform/blob/v2.x/master/interface/src/index.d.ts#L720): `pluginManager`, `uriBroker`, `dispatcher`, `logger`, `registry`, `notificationManager`, and `globalization` +The Zowe Application Framework provides the following shared resource functions through a [ZoweZLUX object](https://github.com/zowe/zlux-platform/blob/v3.x/master/interface/src/index.d.ts#L720): `pluginManager`, `uriBroker`, `dispatcher`, `logger`, `registry`, `notificationManager`, and `globalization` Like REACT and Angular apps, IFrame apps can use the ZoweZLUX object to communicate with the framework and other apps. To enable communication in an IFrame app, you must add the following javascript to your app, for example in your `index.html` file: diff --git a/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md b/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md index 8405259e6d..f3a7d7c8c8 100644 --- a/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md +++ b/docs/extend/extend-desktop/mvd-mvdandwindowmgt.md @@ -55,7 +55,9 @@ Every instance of an application's web content within Zowe is given context and When the Window is created, the application's web content is encapsulated dependent upon its framework type. The following are valid framework types: -- "angular2": The web content is written in Angular, and packaged with Webpack. Application framework objects are given through @injectables and imports. +- "angular": The web content is written in Angular, and packaged with Webpack. Application framework objects are given through @injectables and imports. + +- "react": The web content is written in React, and packaged with Webpack. Application framework objects are given through `this.props`. - "iframe": The web content can be written using any framework, but is included through an iframe tag. Applications within an iframe can access framework objects through `parent.ZoweZLUX` and callbacks. diff --git a/docs/extend/extend-desktop/mvd-server-config.md b/docs/extend/extend-desktop/mvd-server-config.md index 76d46c0390..ffb574f0dd 100644 --- a/docs/extend/extend-desktop/mvd-server-config.md +++ b/docs/extend/extend-desktop/mvd-server-config.md @@ -1,16 +1,22 @@ +# Advanced Server Configuration + The Zowe's App Server and ZSS rely on many required or optional parameters to run, which includes setting up networking, deployment directories, plugin locations, and more. -These parameters can be specified in multiple ways: configuration files, CLI arguments, or environment variables. +These parameters can be specified in two ways: configuration files, or environment variables. + +Every configuration option and requirement is documented within the application framework [json-schema file](https://github.com/zowe/zlux/blob/v3.x/staging/schemas/zlux-config-schema.json) + +## Configuration file -Every configuration option and requirement is documented within the application framework [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zlux-config-schema.json) +In Zowe's server configuration file, app-server parameters can be specified within `components.app-server` as shown in the component [json-schema file](https://github.com/zowe/zlux/blob/v3.x/staging/schemas/zowe-schema.json), or `components.zss` for ZSS. -# Configuration file -In Zowe's server configuration file, app-server parameters can be specified within `components.app-server` as shown in the component [json-schema file](https://github.com/zowe/zlux/blob/v2.x/staging/schemas/zowe-schema.json), or `components.zss` for ZSS. +## Environment variables + +The format is `ZWED_key=value`, where `ZWED_` is a prefix for any configuration object. -# Environment variables -CLI arguments take precedence over the configuration file, but are overridden by the CLI arguments. -The format is `ZWED_key=value`, where "ZWED_" is a prefix for any configuration object. The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple values. + For example: + ``` node: https: @@ -26,7 +32,9 @@ logLevels: org.zowe.terminal.tn3270.*: 5 ``` + In Environment variable format, this is specified as + ``` ZWED_node_https_ipAddresses=0.0.0.0 ZWED_node_https_port=8554 @@ -54,52 +62,11 @@ ZWED_logLevels_org____zowe____terminal____tn3270_x2e_x2a:5 * strings can have quotes, but otherwise everything that isnt an array, boolean, or number is a string * objects are never values. They are the keys. -## Friendly names for environment variables -Some common configuration options have names that do not follow the above special syntax. These options get mapped to the special syntax when the server runs, so the same behavior can be configured in more than one way. Many of these values are listed here https://docs.zowe.org/stable/user-guide/configure-zowe-zosmf-workflow/#configure-the-zowe-instance-directory. - - -Although overridden by both environment variables and CLI arguments, for convenience the App server and ZSS read from a configuration file with a common structure. ZSS reads this directly as a startup argument, while the App Server as defined in the [zlux-server-framework](https://github.com/zowe/zlux-server-framework) repository accepts several parameters which are intended to be read from a YAML file through an implementer of the server, such the default provided in the [zlux-app-server](https://github.com/zowe/zlux-app-server) repository, namely the [lib/zluxServer.js](https://github.com/zowe/zlux-app-server/blob/v2.x/master/lib/zluxServer.js) file. This file accepts a YAML file that specifies most if not all parameters needed, but some other parameters can be provided via flags if desired. - - -# CLI arguments (app-server only) -CLI arguments take precedence over environment variable and configuration files. -The format is `--key=value` -The key maps to a YAML object attribute, so to set the value of a nested object, such as the https configuration, you need multiple period-separated values. -For example: -``` -node: - https: - ipAddresses: 0.0.0.0 - port: 7556 - //pfx (string), keys, certificates, certificateAuthorities, and certificateRevocationLists are all valid here. - keys: "../defaults/serverConfig/server.key" - certificates: "../defaults/serverConfig/server.cert" - -``` -In CLI argument format, this is specified as -``` -node.https.ipAddresses=0.0.0.0 -node.https.port=8554 -node.https.keys="../defaults/serverConfig/server.key" -node.https.certificates="../defaults/serverConfig/server.cert" -``` - -**NOTE: ZSS does not support CLI arguments** - -**The key name is case-sensitive.** - -**The types of the values are syntax-sensitive.** -* Numbers are treated as numbers, not strings. -* false & true are treated as boolean. -* commas are for arrays. An array of length 1 has a comma at the end -* strings can have quotes, but otherwise everything that isn't an array, boolean, or number is a string -* objects are never values. They are the keys. - - -# Parameter Details +# Parameter details Below is some more detail on certain parameters than can be covered within the json-schema. -## Configuration Directories +### Configuration directories + When running, the App Server will access the server's settings and read/modify the contents of its resource storage. All of this data is stored within a hierarchy of a few folders, which is correspond to scopes: - Product: The contents of this folder are not meant to be modified, but used as defaults for a product. @@ -110,7 +77,8 @@ All of this data is stored within a hierarchy of a few folders, which is corresp These directories dictate where the [Configuration Dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) will store content. -### Directories example +#### Directories example + ``` "productDir":"../defaults", "siteDir":"/home/myuser/.zowe/workspace/app-server/site", @@ -120,16 +88,21 @@ These directories dictate where the [Configuration Dataservice](https://github.c ``` +### App configuration -## App configuration This section does not cover any dynamic runtime inclusion of Apps, but rather Apps defined in advance. In the configuration file, a directory can be specified which contains JSON files which tell the server what App is to be included and where to find it on disk. The backend of these Apps use the Server's Plugin structure, so much of the server-side references to Apps use the term Plugin. To include Apps, be sure to define the location of the Plugins directory in the configuration file, via the top-level attribute *pluginsDir* -**NOTE: In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v2.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is ~/.zowe/workspace/app-server. So, the example configuration file uses the latter directory.** +:::note + +In this example, the directory for these JSON files is [/defaults/plugins](https://github.com/zowe/zlux-app-server/tree/v3.x/master/defaults/plugins). Yet, in order to separate configuration files from runtime files, the App Server will initialize by copying the contents of this folder into the defined instance directory, of which the default is `~/.zowe/workspace/app-server`. So, the example configuration file uses the latter directory. + +::: + +#### Plug-ins directory example -### Plugins directory example ``` // All paths relative to zlux-app-server/lib // In real installations, these values will be configured during the install. @@ -137,23 +110,24 @@ To include Apps, be sure to define the location of the Plugins directory in the "pluginsDir":"../defaults/plugins", ``` -## Logging configuration +### Logging configuration For more information, see [Logging Utility](mvd-logutility.md). -## ZSS Configuration +### ZSS Configuration + When running ZSS, it will require a configuration file similar or the same as the one used for the App Server. The attributes that are needed for ZSS, at minimum, are: *productDir*, *siteDir*, *instanceDir*, *groupsDir*, *usersDir*, *pluginsDir* and **agent**. All of these attributes have the same meaning as described above for the App server, but if the App server and ZSS are not run from the same location, then these directories may be different if desired. -### ZSS Networking +#### ZSS Networking -The attributes that control ZSS exclusively are within the **agent** object. ZSS uses HTTPS by default, but for those who wish to use AT-TLS instead of the built-in HTTPS support, ZSS can use HTTP as well. HTTP should never be used without [AT-TLS](../../user-guide/mvd-configuration#defining-the-at-tls-rule), as this is a security risk. The values `agent.https.port`, `agent.http.port` tell ZSS which ports to bind to, but also where the app-server can find ZSS. The values `agent.host` is used to tell app-server where to find ZSS as well, though `agent.https.ipAddresses` and `agent.http.ipAddresses` tell ZSS which addresses to bind to. For addresses, at this time only the first value of that array is used, and it may either be a hostname or an ipv4 address. +The attributes that control ZSS exclusively are within the **agent** object. ZSS uses HTTPS by default, but AT-TLS can also be used by setting `zowe.network.server.tls.attls` or `components.zss.zowe.network.server.tls.attls` to `true`. The value `agent.https.port` tells ZSS which ports to bind to and where the app-server can find ZSS. The values `agent.host` is used to tell app-server where to find ZSS as well, though `zowe.network.server.listenAddresses` or `components.zss.zowe.network.server.listenAddresses` tell ZSS which addresses to bind to. For addresses, at this time only the first value of that array is used, and it may either be a hostname or an ipv4 address. Example of the agent body: + ``` agent: host: localhost https: - ipAddresses: 0.0.0.0 port: 7557 ``` diff --git a/docs/extend/extend-sdks.md b/docs/extend/extend-sdks.md index 686f7a15b3..65017fb5d7 100644 --- a/docs/extend/extend-sdks.md +++ b/docs/extend/extend-sdks.md @@ -2,8 +2,18 @@ The Zowe SDKs are open source. You can contribute to add features, enhancements, and bug fixes to the source code. -The functionality is currently limited to the interfaces provided by IBM z/OSMF. As a plug-in developer, you can enhance the SDK by creating a packages that exposes programmatic APIs for your service. +The functionality is currently limited to the interfaces provided by IBM z/OSMF. As a plug-in developer, you can enhance the SDK by creating a package that exposes programmatic APIs for your service. + +## Contributing to Zowe Client SDKs For detailed contribution guidelines, see the following documents: - [Node.js SDK guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/SDKGuidelines.md) +- [Kotlin SDK guidelines](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md) - **Coming soon! Python SDK guidelines** + +## Community resources + +- Join the [#zowe-cli Slack channel](https://openmainframeproject.slack.com/) to ask questions about Zowe CLI and Zowe SDKs, propose new ideas, and interact with the Zowe community. +- You can join one of the [Zowe CLI squad meetings](https://lists.openmainframeproject.org/g/zowe-dev/calendar) to discuss Zowe SDKs issues and contibute to Zowe SDKs. +- Read a series of [blogs about Zowe](https://medium.com/zowe) on Medium to explore use cases, best practices, and more. +- Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe). diff --git a/docs/extend/extend-zowe-overview.md b/docs/extend/extend-zowe-overview.md index 9dbb2adfd7..5942fa34e7 100644 --- a/docs/extend/extend-zowe-overview.md +++ b/docs/extend/extend-zowe-overview.md @@ -36,7 +36,7 @@ For more information about developing for Zowe Application Framework, see [Zowe ### Extend Zowe CLI -Zowe CLI extenders can build plug-ins that provide new commands. Zowe CLI is built using Node.js and is typically run on a machine other than z/OS, such as a PC, where the CLI can be driven through a terminal or command prompt, or on an automation machine such as a DevOps pipeline orchestrator. +Zowe CLI extenders can build plug-ins that provide new commands. Zowe CLI is built using Node.js and is typically run on a machine other than a mainframe, such as a PC, where the CLI can be driven through a terminal or command prompt, or on an automation machine such as a DevOps pipeline orchestrator. For more information about extending the Zowe CLI, see [Developing a new plug-in](extend-cli/cli-developing-a-plugin.md). This article includes a sample plug-in that is provided with the tutorial; see [Installing the sample plug-in](extend-cli/cli-installing-sample-plugin.md). diff --git a/docs/extend/k8s-extend.md b/docs/extend/k8s-extend.md index d8a2232772..9fe2ef4153 100644 --- a/docs/extend/k8s-extend.md +++ b/docs/extend/k8s-extend.md @@ -18,8 +18,7 @@ An extension must have a container image to run in a Zowe container environment. The core components define component Dockerfiles and use GitHub Actions to build images. For example, -- `jobs-api` is a component which has built-in web service. To build the images, this component defines a Dockerfile at https://github.com/zowe/jobs/blob/v2.x/master/container/Dockerfile and defines a GitHub Actions workflow at https://github.com/zowe/jobs/tree/v2.x/master/.github/workflows. -- `explorer-jes` is a Zowe App Server Framework plug-in but does not have a built-in web service. It follows Zowe's [container conformance criteria](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/containers/conformance.md). It defines a Dockerfile at https://github.com/zowe/explorer-jes/blob/v2.x/master/container/Dockerfile. Similar to `jobs-api`, it also defines a GitHub Actions workflow at https://github.com/zowe/explorer-jes/blob/v2.x/master/.github/workflows/build_test.yml to build the images. +- `explorer-jes` is a Zowe App Server Framework plug-in but does not have a built-in web service. It follows Zowe's [container conformance criteria](https://github.com/zowe/zowe-install-packaging/blob/v2.x/staging/containers/conformance.md). It defines a Dockerfile at https://github.com/zowe/explorer-jes/blob/v2.x/master/container/Dockerfile. It also defines a GitHub Actions workflow at https://github.com/zowe/explorer-jes/blob/v2.x/master/.github/workflows/build_test.yml to build the images. The following GitHub Actions are used by the core components to build conformant images. They might not be completely reusable for you, but are provided as an example. diff --git a/docs/extend/migrate-extensions.md b/docs/extend/migrate-extensions.md index 7d3876ff85..d6cadbc1bb 100644 --- a/docs/extend/migrate-extensions.md +++ b/docs/extend/migrate-extensions.md @@ -31,7 +31,7 @@ Review the following table for a detailed mapping of Zowe v1 and v2 variables. | --- | --- | --- | --- | | `APIML_ALLOW_ENCODED_SLASHES` | `components.gateway.apiml.service.allowEncodedSlashes` | `ZWE_components_gateway_apiml_service_allowEncodedSlashes` | | | `APIML_CORS_ENABLED` | `components.gateway.apiml.service.corsEnabled` | `ZWE_components_gateway_apiml_service_corsEnabled` | | -| `APIML_DEBUG_MODE_ENABLED` | `components.gateway.debug`, etc | `ZWE_components_gateway_debug`, etc | In v2, you can enable debug mode for APIML components separately. The `gateway` placeholder can be `discovery`, `api-catalog`, or `metrics-service`, and so on. | +| `APIML_DEBUG_MODE_ENABLED` | `components.gateway.debug`, etc | `ZWE_components_gateway_debug`, etc | In v2, you can enable debug mode for APIML components separately. The `gateway` placeholder can be `discovery`, `api-catalog`, and so on. | | `APIML_ENABLE_SSO` | Removed in v2 | Removed in v2 | | | `APIML_GATEWAY_EXTERNAL_MAPPER` | `components.gateway.apiml.security.x509.externalMapperUrl` | `ZWE_components_gateway_apiml_security_x509_externalMapperUrl` | | | `APIML_GATEWAY_INTERNAL_HOST` | Not configurable in v2 | Not configurable in v2 | | @@ -48,12 +48,10 @@ Review the following table for a detailed mapping of Zowe v1 and v2 variables. | `DISCOVERY_PORT` | `components.discovery.port` | `ZWE_components_discovery_port` | | | `EXTERNAL_CERTIFICATE_AUTHORITIES` | `zowe.certificate.pem.certificateAuthorities` | `ZWE_zowe_certificate_pem_certificateAuthorities` | | | `EXTERNAL_COMPONENTS` | Removed in v2 | Removed in v2 | Zowe v2 configuration does not distinguish core components and extensions on how to enable them. They use the same `components..enabled` configuration. | -| `FILES_API_PORT` | `components.files-api.port` | `ZWE_components_files_api_port` | | | `GATEWAY_PORT` | `components.gateway.port` | `ZWE_components_gateway_port` | | | `INSTANCE_DIR` | Removed in v2 | `ZWE_zowe_workspaceDirectory` or `ZWE_zowe_logDirectory` | The instance directory is split into workspace and logs directory in v2. | | `JAVA_HOME` | `java.home` | `JAVA_HOME` | | | `JES_EXPLORER_UI_PORT` | Removed in v2 | Removed in v2 | In v2, explorer-jes reuses the web server provided by App Server. It does not start independent web server. | -| `JOBS_API_PORT` | `components.jobs-api.port` | `ZWE_components_jobs_api_port` | | | `KEY_ALIAS` | `zowe.certificate.keystore.alias` | `ZWE_zowe_certificate_keystore_alias` | | | `KEYSTORE_CERTIFICATE_AUTHORITY` | `zowe.certificate.pem.certificateAuthorities` | `ZWE_zowe_certificate_pem_certificateAuthorities` | | | `KEYSTORE_CERTIFICATE` | `zowe.certificate.pem.certificate` | `ZWE_zowe_certificate_pem_certificate` | | diff --git a/docs/extend/packaging-zos-extensions.md b/docs/extend/packaging-zos-extensions.md index b180f78d18..78a85168c8 100644 --- a/docs/extend/packaging-zos-extensions.md +++ b/docs/extend/packaging-zos-extensions.md @@ -4,7 +4,7 @@ You can extend Zowe in multiple ways. You may extend Zowe with microservices, wh Before you start, review the following terms: -- **component**: +- **component** Component refers to the most generic way to describe a program which can work within Zowe. It can be a microservice, a Zowe App Framework plug-in, or even just a shared program to be used by other Zowe components. This is also the generic word when referring to both Zowe core components and extensions. In most of the cases described in this topic, this terminology does not include programs running on the client side, like Zowe CLI plug-in or Zowe Explorer (VSCode extension). - **extension** @@ -15,7 +15,7 @@ Before you start, review the following terms: You can package Zowe components (extensions) into various formats. You can package them as a stand-alone PAX, ZIP, or TAR file. You can also bundle and ship your Zowe extension(s) within another product. -A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists of the following files and directories: +A typical component package consists of the following files and directories: ``` +-- manifest.yaml @@ -23,7 +23,7 @@ A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists |-- schema.json |-- bin/ |-- configure.sh - |-- jobs-api-server-1.0.4-boot.jar + |-- component-1.0.0-boot.jar |-- start.sh |-- validate.sh ``` @@ -39,7 +39,8 @@ A typical component package, for example, `jobs-api-package-1.0.4.zip`, consists - `apiml-static-registration.yaml.template` - Refers to a supporting file that instructs the Zowe launch script how to register this extension service to the API Mediation Layer Discovery service. In this case, this file is referred in the `manifest.yaml` `apimlServices.static[0].file` field. This file is optional depending on the function of the component and you can change and customize the file name in the manifest file. + Refers to a supporting file that instructs the Zowe launch script how to register this extension service to the API Mediation Layer Discovery service. In this case, this file is referred in the `manifest.yaml` `apimlServices.static[0].file` field. This file is optional depending on the function of the component. You can change and customize the file name in the manifest file. + - `bin/(configure|start|validate).sh` This file contains the Zowe component lifecycle scripts. You may not need these files depending on the function of the component. You can find detailed definition of lifecycle scripts in [Zowe component runtime lifecycle](lifecycling-with-zwesvstc.md#zowe-component-runtime-lifecycle). @@ -49,6 +50,7 @@ It is also suggested that you put the following files into the package: - `README.md` This file is a brief introduction to your extension in Markdown format, including how it should be installed, configured, verified, and so on. + - `LICENSE` This is the full license text file. @@ -77,6 +79,5 @@ Zowe extensions, as well as core components, can use a manifest file to describe For examples of manifests thoughout Zowe GitHub repositories, see the following links: - [API Catalog manifest.yaml](https://github.com/zowe/api-layer/blob/v2.x.x/api-catalog-package/src/main/resources/manifest.yaml) -- [Jobs API manifest.yaml](https://github.com/zowe/jobs/blob/v2.x/master/jobs-zowe-server-package/src/main/resources/manifest.yaml) - [Sample Node API and API Catalog extension manifest.yaml](https://github.com/zowe/sample-node-api/blob/master/manifest.yaml) - [Sample Zowe App Framework extension manifest.yaml](https://github.com/zowe/sample-trial-app/blob/master/manifest.yaml) diff --git a/docs/extend/server-schemas.md b/docs/extend/server-schemas.md index eee8d60312..c455b041c6 100644 --- a/docs/extend/server-schemas.md +++ b/docs/extend/server-schemas.md @@ -1,6 +1,6 @@ # Server component schemas -Starting with Zowe v2.0, each Component in Zowe must contain a [json schema](https://json-schema.org/) describing the configuration parameters that are valid for its component section in Zowe's server configuration. If a component does not have anything that can be configured, this file can just be boilerplate specifying that it fully inherits generic Component parameters and nothing more. +Each Component in Zowe must contain a [json schema](https://json-schema.org/) describing the configuration parameters that are valid for its component section in Zowe's server configuration. If a component does not have anything that can be configured, this file can just be boilerplate specifying that it fully inherits generic Component parameters and nothing more. The server infrastructure will utilize each components' schema files to validate a Zowe instance configuration every startup, so this requirement is enforced by code. diff --git a/docs/extend/zowe-conformance-program.md b/docs/extend/zowe-conformance-program.md index 03d7610916..4dadd9da08 100644 --- a/docs/extend/zowe-conformance-program.md +++ b/docs/extend/zowe-conformance-program.md @@ -8,6 +8,13 @@ Conformance provides Independent Software Vendors (ISVs), System Integrators (SI As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe, you are encouraged to get certified today. + +:::info find out more + +The [Zowe Conformance Program Explained](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) blog on Medium.com describes the conformance program in more detail. + +::: + ## How to participate To participate in the Zowe Conformance Program, follow the process on the [Zowe Conformance Program website](https://openmainframeproject.org/our-projects/zowe-conformance-program/). You can also find a list of products that have earned Zowe Conformant status. diff --git a/docs/getting-started/ZE-system-reqs.md b/docs/getting-started/ZE-system-reqs.md index d78c252936..a84c4c054d 100644 --- a/docs/getting-started/ZE-system-reqs.md +++ b/docs/getting-started/ZE-system-reqs.md @@ -1,33 +1,42 @@ -# Zowe Explorer System Requirements +# Zowe Explorer system requirements Before installing Zowe Explorer, make sure that you meet the following requirements. +:::info Required roles: systems administrator, devops architect +::: + ## Client side requirements ### Operating systems +- macOS + + :::note + + Only Mac operating system versions supported by Apple. -- MacOS 10.15 (Catalina), 11 (Big Sur), 12 (Monterey) + ::: - Unix-like: - [CentOS](https://www.centos.org/) 8+ - [RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 8+ - [Ubuntu](https://ubuntu.com/) 20.04+ - Windows 10+ -### Integrated development environments: +### Integrated development environments: + +- [Red Hat CodeReady Workspaces](https://www.redhat.com/en/technologies/jboss-middleware/codeready-workspaces) + + :::note -- [VS Code](https://code.visualstudio.com/) 1.53.2+ -- [Eclipse Che](https://www.eclipse.org/che/) -- [Red Hat CodeReady Workspaces](https://www.redhat.com/en/technologies/jboss-middleware/codeready-workspaces) -- [Theia](https://theia-ide.org/) 1.18+ + Secure credentials are not supported in Red Hat CodeReady Workspaces as the keyring is not unlocked by default. However, you can use the [Kubernetes Secrets plug-in for Zowe CLI and Zowe Explorer](https://github.com/zowe/zowe-cli-secrets-for-kubernetes/blob/main/README.md) as an alternative, or you can create your own [Custom Credential Managers in Zowe Explorer and Zowe CLI](https://medium.com/zowe/custom-credential-managers-in-zowe-explorer-b37faeee4c29). - - Zowe Explorer is compatible with Theia 1.18.0 or higher. However, we recommend using a [Theia community release](https://theia-ide.org/releases/) as Zowe Explorer could experience possible unexpected behaviors with the latest Theia releases. + ::: +- [VS Code](https://code.visualstudio.com/) 1.79.0+ ## Server side requirements - IBM z/OSMF is configured and running. - - Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can run Zowe Explorer successfully. - - z/OSMF enables the core capabilities, such as retrieving data sets, executing TSO commands, submitting jobs, and more. + - See [z/OSMF REST services for Zowe clients](/user-guide/systemrequirements-zosmf/#zosmf-rest-services-for-the-zowe-cli) for a list of services that need configuration. - Applicable plug-in services are configured and running on the mainframe. - Plug-ins communicate with various mainframe services. The services must be configured and running on the mainframe before issuing plug-in commands. diff --git a/docs/getting-started/cli-getting-started.md b/docs/getting-started/cli-getting-started.md index 55d60e748a..6cd4d64b49 100644 --- a/docs/getting-started/cli-getting-started.md +++ b/docs/getting-started/cli-getting-started.md @@ -25,7 +25,7 @@ npm install -g @zowe/cli@zowe-v2-lts ### Installing CLI plug-ins ``` -zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/ims-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts +zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts ``` The command installs most open-source plug-ins, but the IBM Db2 plug-in requires [additional configuration to install](../user-guide/cli-db2plugin.md#installing). diff --git a/docs/getting-started/install-ze-extensions.md b/docs/getting-started/install-ze-extensions.md new file mode 100644 index 0000000000..542c6b19d7 --- /dev/null +++ b/docs/getting-started/install-ze-extensions.md @@ -0,0 +1,34 @@ +# Installing Zowe Explorer extensions + +To successfully install Zowe Explorer extensions, meet the following system requirements. + +## Zowe Explorer CICS Extension system requirements + +### Client side requirements + +- [Visual Studio Code](https://code.visualstudio.com/download) +- [Zowe Explorer V3](../user-guide/ze-install#installing-zowe-explorer) + +### Server side requirements + +The following services must be installed, configured, and running on the mainframe: + +- CICS Management Client Interface (CMCI) APIs +- z/OSMF (optional but recommended) + +## Zowe Explorer FTP Extension system requirements + +### Client side requirements + +- [Visual Studio Code](https://code.visualstudio.com/download) +- [Zowe Explorer V3](../user-guide/ze-install#installing-zowe-explorer) + +### Server side requirements + +- Ensure that you can obtain remote access to a z/OS FTP service before using the extension. + +- Some functionality within the FTP extension requires the FTP server on the mainframe to be configured with the `JESINTERFACELevel` parameter set to `2`. For more information, see the [JESINTERFACELEVEL (FTP server) statement](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-jesinterfacelevel-ftp-server-statement). + + The `JESINTERFACELevel` parameter can be found in multiple locations within the mainframe, depending on your site's security policies. + + Contact your system administrator to determine if your FTP server is configured with the correct `JESINTERFACELevel`. For more information, see [FTP configuration statements in FTP.DATA](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-ftp-configuration-statements-in-ftpdata). \ No newline at end of file diff --git a/docs/getting-started/install-zowe-sdks.md b/docs/getting-started/install-zowe-sdks.md new file mode 100644 index 0000000000..120b53e2ef --- /dev/null +++ b/docs/getting-started/install-zowe-sdks.md @@ -0,0 +1,140 @@ +# Zowe SDKs installation + +Leverage the Zowe Client Software Development Kits (SDKs) to build client applications and scripts that interface with the mainframe. + +The SDKs include programmatic APIs, each of which performs a particular mainframe task. For example, one API package provides the ability to upload and download z/OS data sets. You can leverage that package to rapidly build a client application that interacts with data sets. + +The following SDKs are available. +- Zowe Client Java SDK +- Zowe Client Kotlin SDK +- Zowe Client Node.js SDK +- Zowe Client Python SDK *technical preview* + +## Fundamentals + +- New to Zowe Client SDKs? This [Zowe Client SDK overview](overview.md#zowe-client-software-development-kits-sdks) briefly introduces the SDKs. + +- The blog [Zowe SDKs - Build z/OS Connected Applications Faster](https://medium.com/zowe/zowe-sdks-build-z-os-connected-applications-faster-b786ba7bb0d9) introduces Zowe SDKs and their benefits. + +## SDK documentation + +For detailed SDK documentation, see the following: +- [Zowe Client Java SDK](https://github.com/Zowe-Java-SDK) +- [Zowe Client Kotlin SDK](https://zowe.github.io/zowe-client-kotlin-sdk/) +- [Zowe Client Node.js SDK](https://docs.zowe.org/stable/typedoc/index.html) +- [Zowe Client Python SDK](https://zowe-client-python-sdk.readthedocs.io/en/latest/) *technical preview* +- [Zowe SDK Sample Scripts](https://github.com/zowe/zowe-sdk-sample-scripts/) + +## SDK software requirements and dependencies + +### Java SDK + +Requires Java Runtime Environment (JRE) 17. + +To install this library in your project, use a build tool such as Maven, Gradle, or Ant. Get the necessary artifacts from the [Java SDK repository](https://mvnrepository.com/artifact/org.zowe.client.java.sdk/zowe-client-java-sdk). + +If you add the Java SDK as a dependency to your project, Maven or Gradle automatically downloads any additional dependencies needed to use the SDK. + +For a Maven project, add the SDK as a dependency by updating the `pom.xml` file: + +``` + + org.zowe.client.java.sdk + zowe-client-java-sdk + 2.2.0 + +``` + +For a Gradle project, add the SDK as a dependency by updating the `build.gradle` file: + +``` +implementation group: 'org.zowe.client.java.sdk', name: 'zowe-client-java-sdk', version: '2.2.0' +``` + +### Kotlin SDK + +Requires Java Runtime Environment (JRE) 17. + +For detailed information about how to install the library, refer to [the official installation guide for Zowe Client Kotlin SDK](https://zowe.github.io/zowe-client-kotlin-sdk/#installation) + +### Node.js + +If you install Node SDK packages from the [online registry](#installing-an-sdk-from-an-online-registry), the required dependencies are installed automatically. + +If you download Node SDK packages from Zowe.org, the downloaded folder contains dependencies that you must install manually. Extract the `TGZ` files from the folder, copy the files to your project, and issue the following commands to install the dependencies: + +``` +npm install imperative.tgz +``` + +``` +npm install core-for-zowe-sdk.tgz +``` + +### Python SDK *technical preview* + +If you install Python SDK packages from the [online registry](#installing-an-sdk-from-an-online-registry), the required dependencies are installed automatically. + +If you download the Python SDK packages from Zowe.org, the downloaded folder contains dependencies that you must install manually. Extract the `WHL` files from the folder, copy the files to your project, and issue the following command for each dependency: + +``` +pip install .whl +``` + +## Installing a Zowe Client SDK + +To get started, import the SDK package to your project. You can pull the packages from an online registry, or download the packages from Zowe.org to install locally. + +### Installing an SDK from an online registry + +Pull the packages from an online registry such as npm or PyPi: + +1. In command-line window, navigate to your project directory. Issue the following command to install a package from the registry: + + - To import a Node.js package: `npm install ` + - To import a Python package: `pip install ` + + - `` + The name of the SDK package that you want to install, such as `zos-files-for-zowe-sdk`. + + The package is installed. + + - Node packages are defined in `package.json` in your project. + - Python packages are installed by default to `$PYTHONPATH/Lib/site-packages` (Linux) or to the Python folder in your local `/AppData` folder (Windows). + - For the Java and Kotlin SDKs, Maven puts libraries in the `~/.m2/repository` directory and Gradle puts libraries in the `~/.gradle/caches/modules-2/files-2.1` directory, where `~` represents the path to the user's home directory. + +2. **(Optional)** You might want to automatically update the SDK version when updates become available, or you might want to prevent automatic updates. + + - To define the versioning scheme for Node packages, use [semantic versioning](https://docs.npmjs.com/about-semantic-versioning). + + - To define versioning for Python packages, specify versions or version ranges in a `requirements.txt` file checked-in to your project. For more information, see [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) in the pip documentation. + + - To define versioning for Python packages, specify versions or version ranges in the `pom.xml` or `build.gradle` files checked-in to your project. + + - In Maven, versioning ranges can be [specified in the `pom.xml` file](https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution#DependencyMediationandConflictResolution-DependencyVersionRanges). + + - In Gradle, versioning ranges can be [specified in the `build.gradle` file](https://docs.gradle.org/current/userguide/single_versions.html). + +### Installing an SDK from a local package + +Download and install the packages: + +1. Navigate to [Zowe.org Downloads](https://www.zowe.org/download.html). Select your desired programming language in the **Zowe Client SDKs** section. + + The SDK is downloaded to your computer. + +2. Unzip the SDK folder, which contains the packages for each set of functionality (such as z/OS Jobs). Copy each file that you want to install and paste them into your project directory. + +3. Install required dependencies, which are included in the bundle. See [Software requirements and dependencies](#software-requirements-and-dependencies) for more information. + +3. In a command-line window, navigate to your project directory. Issue *one* of the following commands. + + - To install a Node.js package: `npm install .tgz` + - To install a Python package: `pip install .whl` + + -`` + The name of the package that you want to install, such as `zos-files-for-zowe-sdk`. + +4. Repeat the command for each package that you need. + + Packages are now installed. diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 16312abb8e..baaec03aaa 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -51,11 +51,7 @@ API ML consists of these core components: the API Gateway, the Discovery Service - The API Gateway provides secure routing of API requests from clients to registered API services. - The Discovery Service allows dynamic registration of microservices and enables their discoverability and status updates. - The API Catalog provides a user-friendly interface to view and try out all registered services, read their associated APIs documentation in OpenAPI/Swagger format. -- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data in-memory or using Redis, or VSAM storage. - -Core Zowe also provides out of the box services for working with MVS Data Sets, JES, as well as working with z/OSMF REST APIs. - -**Note:** The MVS datasets and JES services are deprecated and will not be available in Zowe V3. +- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data using various backends. Recommended is usage of Inifinispan packaged with the Caching Service. The API Mediation Layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and API documentation. @@ -68,7 +64,7 @@ The API Mediation Layer offers enterprise, cloud-like features such as high-avai * High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind. * Caching Service: This feature is designed for Zowe components in a high availability configuration, and supports high availability of all components within Zowe. As such, components can remain stateless whereby the state of the component is offloaded to a location accessible by all instances of the service, including those which just started. * Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration. -* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility. +* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. * Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services. #### API Mediation Layer structural architecture @@ -79,37 +75,39 @@ The following diagram illustrates the single point of access through the Gateway #### Components The API Layer consists of the following key components: -**API Gateway** +**Gateway Service** -Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL. Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway is built using Netflix Zuul and Spring Boot technologies. +Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API +client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL. +Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances +can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway Service is built on Spring +Cloud Gateway and Spring Boot technology. **Discovery Service** -The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. - -**Discovery Service TLS/SSL** - -HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables heightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered. +The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service +continuously collects and aggregates service information and serves as a repository of active services. When a service is +started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. +Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are +available to help with service on-boarding of various application architectures including plain Java applications and +Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. **API Catalog** -The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability. - -**Catalog Security** - -Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the z/OSMF API. +The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both +the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component +to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service +instances, which provide exactly the same service for high-availability or scalability. API Catalog requires authentication +from the accessing user. **Caching Service** -An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated with keys. The service can only be used by internal Zowe services and is not exposed to the internet. - -**Metrics Service (Technical Preview)** - -The Metrics Service provides a web user interface to visualize requests to API Mediation Layer services. HTTP metrics such as number of requests and error rates are displayed for -each API Mediation Layer service. This service is currently in technical preview and is not ready for production. +An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated +with keys. #### Onboarding APIs -Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics to discover more about adding new APIs to the API Mediation Layer and using the API Catalog: +Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics +to learn more about adding new APIs to the API Mediation Layer and using the API Catalog: * [Onboarding Overview](../extend/extend-apiml/onboard-overview.md) * [Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer](../extend/extend-apiml/onboard-spring-boot-enabler.md) @@ -216,6 +214,7 @@ The Zowe Client SDKs consist of programmatic APIs that you can use to build clie - Zowe Node.js Client SDK - Zowe Java Client SDK +- Zowe Kotlin Client SDK - Zowe Python Client SDK For more information, see [Using the Zowe SDKs](../user-guide/sdks-using.md). @@ -270,21 +269,21 @@ ZEBRA Provides re-usable and industry compliant JSON formatted RMF/SMF data reco For more information, see the [ZEBRA documentation](https://github.com/zowe/zebra/tree/main/Documentation). -### Zowe IntelliJ Plug-in +### Zowe Explorer plug-in for IntelliJ IDEA -Zowe IntelliJ plug-in for Intellij-based IDEs is a smart and interactive mainframe code editing tool that allows you to browse, edit, and create data on z/OS via z/OSMF REST API. +Zowe Explorer plug-in for IntelliJ IDEA is a smart and interactive mainframe code editing tool that allows you to browse, edit, and create data on z/OS via z/OSMF REST API. -Zowe IntelliJ plug-in helps you to: -- Start working with z/OS easily with no complex configurations. -- Organize datasets on z/OS, files on USS into working sets. -- Allocate datasets, create members, files and directories with different permissions. -- Perform operations like renaming, copying and moving data in a modern way. -- Edit datasets, files and members. Smart auto-save keeps your content both in the editor and on the mainframe in-sync. -- Create multiple connections to different z/OS systems. -- Perform all available operations with jobs. -- Highlight all IntelliJ supported languages automatically and recognize them once opened from the mainframe. +The plug-in helps to: +- Start working with z/OS easily with no complex configurations +- Organize data sets on z/OS, files on USS into working sets +- Allocate data sets, create members, files and directories with different permissions +- Perform operations like renaming, copying and moving data in a modern way +- Edit data sets, files and members. Smart auto-save keeps your content both in the editor and on the mainframe in sync +- Create multiple connections to different z/OS systems +- Perform all available operations with jobs +- Work with TSO Console directly in the IDE -For more information, see [Using Zowe IntelliJ plug-in](../user-guide/intellij-using.md). +To learn more about the plug-in, you can start with [Zowe Explorer plug-in for IntelliJ IDEA use cases](../user-guide/intellij-use-cases.md). ## Zowe Bill of Materials diff --git a/docs/getting-started/user-roadmap-apiml.md b/docs/getting-started/user-roadmap-apiml.md index e61b37c5cc..54e19c4bb6 100644 --- a/docs/getting-started/user-roadmap-apiml.md +++ b/docs/getting-started/user-roadmap-apiml.md @@ -42,13 +42,9 @@ The following definition of skill levels about Zowe assist you with gathering th - **Configuring API Mediation Layer** - - [Configuring the Zowe APIs](../user-guide/configure-data-sets-jobs-api.md) - - This article explains how to configure security for the Zowe API Mediation Layer. - - - [Advanced Gateway features configuration](../user-guide/advanced-apiml-configuration.md) + - [Advanced API Mediation Layer features configuration](../user-guide/advanced-apiml-configuration.md) - This article is for system programmers who want to configure advanced Gateway features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced Gateway features. + This article is for system programmers who want to configure advanced features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced features. ## Using Zowe API Mediation Layer @@ -102,7 +98,8 @@ The following definition of skill levels about Zowe assist you with gathering th This blog takes a deeper dive into the SSO feature of API ML. -- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579) +- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579) +- [**Blog: CLI and Client Certificates](https://medium.com/zowe/zowe-cli-and-client-certificates-dae341f8f52a) ## Contributing to Zowe API Mediation Layer diff --git a/docs/getting-started/user-roadmap-client-sdk.md b/docs/getting-started/user-roadmap-client-sdk.md index 505e3458de..fe4711512a 100644 --- a/docs/getting-started/user-roadmap-client-sdk.md +++ b/docs/getting-started/user-roadmap-client-sdk.md @@ -2,84 +2,12 @@ This roadmap outlines information resources that are applicable to the various user roles who are interested in Zowe Client Software Development Kits (SDKs) which is a Zowe component still under development. These resources provide information about various subject areas, such as learning basic skills, installation, developing, and troubleshooting for Zowe Client SDKs. -The following definition of skill levels about Zowe will help you gather most relevant resources for you. - -* Beginner: You are starting out and want to learn the fundamentals. -* Intermediate: You have some experience but want to learn more in-depth skills. -* Advanced: You have lots of experience and are looking to learn about specialized topics. - -## Fundamentals - -> Zowe skill level: Beginner - -- [**Zowe Client SDK overview**](overview.md#zowe-client-software-development-kits-sdks) - - New to Zowe Client SDKs? This overview topic briefly introduces what the SDK is. - -- [**Blog: Zowe SDKs - Build z/OS Connected Applications Faster**](https://medium.com/zowe/zowe-sdks-build-z-os-connected-applications-faster-b786ba7bb0d9) - - This blog introduces Zowe SDKs and their benefits. - -## Installing - -> Zowe skill level: Beginner - -- [**System requirements**](../user-guide/sdks-using.md#software-requirements) - - Review this topic to ensure that your system meets the requirements for installing Zowe Client SDKs. - -- [**Installing Zowe SDK**](../user-guide/sdks-using.md#getting-started) - - Follow the steps to install Zowe SDKs. You can pull the packages from an online registry, or download the packages from Zowe.org to install locally. - -## Using Zowe Client SDKs - -> Zowe skill level: Intermediate - -### Zowe Node.js SDK - -- [**Using Zowe Node.js SDKs**](../user-guide/sdks-using.md#using---nodejs) - - This information provides links to different pakcage Readmes that describes how to use the Zowe Node SDK. - -- **Docs: Node.js SDK reference guide** - - Refer to the following Zowe Client SDK reference guides for information about the API endpoints: - - **[Browse Node SDK reference guide online](https://docs.zowe.org/stable/typedoc/index.html)** - - **[Download SDK reference guide in ZIP format](https://docs.zowe.org/stable/zowe-nodejs-sdk-typedoc.zip)** - -- [**Zowe SDK Sample Scripts**](https://github.com/zowe/zowe-sdk-sample-scripts/) - - This repository contains some sample scripts that utilize various components of the Zowe SDKs organized by use cases. - -### Zowe Python SDK - -- [**Using Zowe Python SDKs**](https://zowe-client-python-sdk.readthedocs.io/en/latest/) - - This information provides links to different pakcage Readmes that describes how to use the Zowe Python SDK. - -- **Docs: Python SDK reference guide** - - Refer to the following Zowe Client SDK reference guides for information about the API endpoints: - - **[Browse Python SDK reference guide online](https://zowe-client-python-sdk.readthedocs.io/en/latest/index.html)** - - **[Download SDK reference guide in PDF format](https://zowe-client-python-sdk.readthedocs.io/_/downloads/en/latest/pdf/)** - - -## Contributing to Zowe Client SDKs - -> Zowe skill level: Advanced - -- [**Contributing guidelines**](https://github.com/zowe/zowe-cli/blob/master/docs/SDKGuidelines.md) - - This document is a summary of guidelines for development within Zowe SDKs. You can contribute to add features, enhancements, and bug fixes to the source code. - ## Troubleshooting and support - [**Sumit an issue**](https://github.com/zowe/zowe-cli/issues/new) If you have an issue that is specific to Zowe SDKs, you can submit an issue against the `zowe-cli` repo. - ## Community resources - [**Slack channel**](https://openmainframeproject.slack.com/) diff --git a/docs/getting-started/user-roadmap-zowe-explorer.md b/docs/getting-started/user-roadmap-zowe-explorer.md index 881262c106..10563478e4 100644 --- a/docs/getting-started/user-roadmap-zowe-explorer.md +++ b/docs/getting-started/user-roadmap-zowe-explorer.md @@ -1,121 +1,59 @@ -# Zowe Explorer +# Installing Zowe Explorer -The resources here provide information about various Zowe Explorer subject areas, such as learning basic skills, installation, developing, and troubleshooting. +The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs. -:::tip +For a better understanding of Zowe Explorer, review the various reference materials that document the VS Code extension. -To identify the resources most relevant for you, use the following definitions of Zowe Explorer skill levels. +## About Zowe Explorer -* Beginner: You're starting out and want to learn the fundamentals. -* Intermediate: You have some experience but want to learn more in-depth skills. -* Advanced: You have lots of experience and are looking to learn about specialized topics. -::: +- Check out [**Zowe release notes**](../whats-new/release-notes/release-notes-overview.md) to learn about the latest Zowe Explorer updates. -## Fundamentals - -> Zowe skill level: Beginner - -* [**Zowe Explorer overview**](../user-guide/ze-install.md) - - New to Zowe Explorer? This overview topic introduces the key features, main components, and benefits of Zowe Explorer. - -* [**Zowe Explorer FAQs**](../getting-started/zowe_faq.md#zowe-explorer-faq) - - If you have a question, review the FAQ, which answers the most commonly asked questions about Zowe Explorer. - -* [**Blog: Visual Studio Code for Mainframe Via the Zowe Explorer Extension**](https://medium.com/zowe/visual-studio-code-for-mainframe-via-the-zowe-explorer-extension-b679054ffaf7) - - This Medium article outlines the basics of Zowe Explorer, including Getting Started videos. +- If you have a question, review the [**Zowe Explorer FAQs**](../getting-started/zowe_faq.md#zowe-explorer-faq), which answer the most commonly asked questions about Zowe Explorer. ## Installing and configuring -> Zowe skill level: Beginner - -* [**Installing Zowe Explorer**](../user-guide/ze-install.md#installing-zowe-explorer) - - This page includes the system requirements and steps for installing the Zowe Explorer. - -* [**Video: Getting started with Zowe Explorer (Part 1)**](https://youtu.be/G_WCsFZIWt4) -* [**Video: Getting started with Zowe Explorer (Part 2)**](https://youtu.be/X4oSHrI4oN4) - - These videos help you to get started with Zowe Explorer and show the basic data set use cases. - -* [**Zowe Explorer Profiles**](../user-guide/ze-profiles.md) - - This page describes how to create and work with Zowe Explorer profiles. Having a profile enables you to use all functions of the extension, activate the Secure Credential Store plug-in to securely store credentials, and more. - -## Using Zowe Explorer - -> Zowe skill level: Intermediate +- Review the system requirements and steps for installing the Zowe Explorer in [**Installing Zowe Explorer**](../user-guide/ze-install.md). -* [**Using Zowe Explorer**](../user-guide/ze-usage.md) +- Learn how to create and work with [**Zowe Explorer profiles**](../user-guide/ze-profiles.md). A profile enables you to connect to services running on a mainframe, integrate with the API Mediation Layer, and more. - This page includes usage tips and sample use cases for data sets, USS files, JOBs, and TSO commands. Familiarize yourself with the extension and make the best use of available options and features. +## Getting the most out of Zowe Explorer -## Extending Zowe Explorer +- Review [**Using Zowe Explorer**](../user-guide/ze-usage.md) to go over how to use Zowe Explorer in a remote environment and managing credentials. -> Zowe skill level: Advanced +* Learn how to [**extend Zowe Explorer**](https://github.com/zowe/vscode-extension-for-zowe/wiki/Extending-Zowe-Explorer) to introduce new functionalities. -* [**Extend Zowe Explorer**](https://github.com/zowe/zowe-explorer-vscode/wiki/Extending-Zowe-Explorer) +- Add CICS functionality and the FTP protocol to the Zowe Explorer VS Code extension with the [**Zowe Explorer CICS Extension**](../user-guide/ze-using-zowe-explorer-cics-ext.md) and the [**Zowe Explorer FTP Extension**](../user-guide/ze-ftp-install-ze-ftp-ext.md). - Learn how to create extensions for Zowe Explorer to introduce new functionalities. +- Check out the [**Zowe Explorer GitHub repository**](https://github.com/zowe/vscode-extension-for-zowe#readme) to view the source code for Zowe Explorer and other Zowe Explorer-related extensions. -- [**Zowe Explorer CICS Extension**](../user-guide/ze-using-zowe-explorer-cics-ext.md) +- Watch the following videos to learn how to get started with Zowe Explorer, and work with data sets: - Learn how to install the CICS extension. The extension adds CICS functionality to the Visual Studio Code extension, which lets you interact with CICS regions and programs. + -* [**Zowe Explorer FTP Extension**](../user-guide/ze-ftp.md) - - Learn how to install and use the FTP extension. The extension adds the FTP protocol to the Zowe Explorer VS Code extension, which lets use z/OS FTP Plug-in for Zowe CLI profiles to connect and interact with z/OS USS. - -* [**Zowe Explorer repository**](https://github.com/zowe/zowe-explorer-vscode) - - The GitHub repository of contains the source code of Zowe Explorer and other Zowe Explorer-related extensions. Check out the landing page README in the repository to find out how to contribute to the extension. - -* [**Developing for Eclipse Theia**](https://github.com/zowe/zowe-explorer-vscode/wiki/Developing-for-Theia) - - This article contains information on how to develop for Eclipse Theia. + ## Contributing to Zowe Explorer -> Zowe skill level: Advanced - -* [**Contributing guidelines**](https://github.com/zowe/zowe-explorer-vscode/blob/master/CONTRIBUTING.md) - - This document is intended to be a living summary of conventions & best practices for development of the Visual Studio Code Extension for Zowe. - -* [**Conformance Program**](../extend/zowe-conformance-program.md) - - This topic introduces the Zowe Conformance Program. Conformance provides Independent Software Vendors (ISVs), System Integrators (SIs), and end users greater confidence that their software will behave as expected. As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe CLI, you are encouraged to get certified today. - -* [**Blog: Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) - - This Medium article provide more details about the Conformance Program, including useful references. - -## Troubleshooting and support - -* [**Troubleshooting Zowe Explorer**](../troubleshoot/ze/troubleshoot-ze.md) - - Learn about the tools and techniques that are available to help you troubleshoot and resolve problems. You can also find the list of Zowe Explorer issues. +- Review the [**Contribution Guidelines**](https://github.com/zowe/vscode-extension-for-zowe/blob/master/CONTRIBUTING.md) for a summary of conventions and best practices for development of the Visual Studio Code Extension for Zowe. -* [**Submit an issue**](https://github.com/zowe/zowe-explorer-vscode/issues) +## Zowe Explorer community resources - If you have an issue that is specific to Zowe Explorer, you can submit an issue against the `vscode-extension-for-zowe` repository. +The Zowe ecosystem is more than a collection of applications and extensions. An entire community exists to work on enhancements, help answer questions, and discuss plans for the future of the open source project. -## Community resources +- Join the [**#zowe-explorer-vscode**](https://app.slack.com/client/T1BAJVCTY/CUVE37Z5F) Slack channel to ask questions, propose new ideas, and interact with the Zowe community. -* [**Slack channel**](https://openmainframeproject.slack.com/) +- You can join **Zowe Explorer squad meetings** to get involved. The meeting schedule is posted in the [Zowe calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe). - Join the `# zowe-explorer` Slack channel to ask questions, propose new ideas, and interact with the Zowe community. +- Read informative [**blog posts about Zowe**](https://medium.com/zowe) on Medium to explore use cases, best practices, and more. -* [**Zowe Explorer squad meetings**](https://lists.openmainframeproject.org/g/zowe-dev/calendar) +- **Discuss Zowe topics** in the [Open Mainframe Project community forums](https://community.openmainframeproject.org/c/zowe). - You can join one of the Zowe Explorer squad meetings to get involved. +- If you have an issue that is specific to Zowe Explorer, you can [**submit an issue**](https://github.com/zowe/zowe-explorer-vscode/issues/new/choose) in the `zowe-explorer-vscode` repository on GitHub. -* [**Zowe Blogs on Medium**](https://medium.com/zowe) +## Zowe Conformance Program - Read a series of blog articles about Zowe on Medium to explore use cases, best practices, and more. +Administered by the Open Mainframe Project, the [Zowe Conformance Program](../extend/zowe-conformance-program.md) aims to give users the confidence that when they use a product, app, or distribution that leverages Zowe, they can **expect a high level of common functionality**, **interoperability**, and **user experience**. -* **Community Forums** +As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe Explorer, you are encouraged to get certified today. - Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe). +Read the blog post [**Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) for more details about the Conformance Program, including useful references. diff --git a/docs/getting-started/zowe-architecture.md b/docs/getting-started/zowe-architecture.md index 499269c73f..107e5bb266 100644 --- a/docs/getting-started/zowe-architecture.md +++ b/docs/getting-started/zowe-architecture.md @@ -31,10 +31,6 @@ The configuration entries of each LPAR in the `zowe.yaml` file control which com The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex, are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so that each instance behaves similarly to the user irrespective of where their request is routed. -For simplification of the preceding diagram, the Jobs and Files API servers are not shown as being started. If the user defines Jobs and Files API servers to be started in the `zowe.yaml` configuration file, these servers behave the same as the servers illustrated. In other words, these services register to their API discovery server which then communicates with other discovery servers on other Zowe instances on either the same or other LPARs. The API traffic received by any API Gateway on any Zowe instance is routed to any of the Jobs or Files API components that are available. - -To learn more about Zowe with high availability enablement, see [Configuring Sysplex for high availability](../user-guide/configure-sysplex.md). - ## Zowe architecture when running in Kubernetes cluster The following diagram illustrates the difference in locations of Zowe components when deploying Zowe into a Kubernetes cluster as opposed to running all components on a single z/OS system. @@ -77,7 +73,17 @@ ZIS is a z/OS native, authorized cross-memory server that allows a secure and co Unlike all of the servers described above which run under the `ZWESLSTC` started task as address spaces for USS processes, the Cross Memory server has its own separate started task `ZWESISTC` and its own user ID `ZWESIUSR` that runs the program `ZWESIS01`. -## API Gateway +## API Mediation Layer + +The API Mediation Layer is a collection of services for management and administration of APIs, and is comprised of the following components that are described in detail below: + +* API Gateway +* API Catalog +* API Discovery +* Caching service +* ZAAS + +### API Gateway The API Gateway is a proxy server that routes requests from clients on its northbound or upstream edge, such as web browsers or the Zowe command line interface, to servers on its southbound (downstream) edge that are able to provide data to serve the request. The API Gateway is also responsible for generating the authentication token used to provide single sign-on (SSO) functionality. The API Gateway homepage is `https://:7554`. Following authentication, this URL enables users to navigate to the API Catalog. @@ -86,17 +92,17 @@ The API Gateway is a proxy server that routes requests from clients on its north When the API Gateway is running, this server is accessible at `https://:7554/`. When running on z/OS, the server uses the jobname suffix of AG. -## API Catalog +### API Catalog The API Catalog provides a list of the API services that have registered themselves as catalog tiles. These tiles make it possible to view the available APIs from Zowe's southbound (downstream) servers, as well as test REST API calls. ![Zowe API Catalog](../images/api-mediation/api-catalog.png) When the API Gateway is running, this server is accessible at `https://:7554/apicatalog/ui/v1`. -When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog` +When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog` When running on z/OS, the server uses the jobname suffix of AC. -## API Discovery +### API Discovery The API Discovery server acts as the registration service broker between the API Gateway and its southbound (downstream) servers. This server can be accessed through the URL `https://:7552` making it possible to view a list of registered API services on the API discovery homepage. @@ -104,13 +110,13 @@ The API Discovery server acts as the registration service broker between the API When running on z/OS, the server uses the jobname suffix of AD. -## Caching service +### Caching service The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The Caching service URL is `https://:7555`. For more information about the Caching service, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). When the API Gateway is running, this server is accessible at `https://:7554/cachingservice/api/v1`. -When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`. +When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`. When running on z/OS, the server uses the jobname suffix of CS. ## Desktop Apps @@ -118,13 +124,3 @@ When running on z/OS, the server uses the jobname suffix of CS. Zowe provides a number of rich GUI web applications for working with z/OS. Such applications include the Editor for files and datasets, the JES Explorer for jobs, and the IP Explorer for the TCPIP stack. You can access them through the Zowe desktop. ![Zowe Desktop Explorers](../images/mvd/desktop-explorers.png) - -### File API and JES API - -The File API server provides a set of REST APIs for working with z/OS data sets and Unix files. These APIs can be enabled in Zowe server configuration. - -The JES API server provides a set of REST APIs for working with JES. These APIs can be enabled in Zowe server configuration. - -Both the File API and JES API servers are registered as tiles in the API Catalog, so users can view the Swagger definition and test API requests and responses. - - diff --git a/docs/getting-started/zowe-high-availability.md b/docs/getting-started/zowe-high-availability.md index e90cdaa827..dbc37749d0 100644 --- a/docs/getting-started/zowe-high-availability.md +++ b/docs/getting-started/zowe-high-availability.md @@ -30,7 +30,7 @@ If you are running the Caching Service on z/OS, there are three storage methods - Part of the Caching service - Does not need separate processes - Highly performant -- [VSAM](../user-guide/configure-caching-service-ha.md#vsam) +- [VSAM (*deprecated*)](../user-guide/configure-caching-service-ha.md#vsam) - Familiar to z/OS engineers - Slow - [Redis](../extend/extend-apiml/api-mediation-redis.md#redis-configuration) diff --git a/docs/getting-started/zowe-resources.md b/docs/getting-started/zowe-resources.md index a6ab87911c..96792fec47 100644 --- a/docs/getting-started/zowe-resources.md +++ b/docs/getting-started/zowe-resources.md @@ -22,6 +22,8 @@ As well as [Zowe videos](https://www.youtube.com/embed?listType=playlist&list=PL Find out what is happening with Zowe in the Zowe Quarterly Update Webinar Series. +- [Zowe Quarterly Update Webinar: May 2024](https://youtu.be/57IKsRfM_F0) +- [Zowe Quarterly Update Webinar: February 2024](https://youtu.be/d9eA9eZRREI) - [Zowe Quarterly Update Webinar: October 2021](https://youtu.be/b0Xo6WIy3vc) - [Zowe Quarterly Update Webinar: July 2021](https://youtu.be/T3Z4hMwElII) - [Zowe Quarterly Update Webinar: April 2021](https://youtu.be/9rQCcZGVDzQ) diff --git a/docs/getting-started/zowe-security-authentication.md b/docs/getting-started/zowe-security-authentication.md index eb0b1eef33..05e0eb23a9 100644 --- a/docs/getting-started/zowe-security-authentication.md +++ b/docs/getting-started/zowe-security-authentication.md @@ -4,7 +4,6 @@ The API Mediation Layer provides multiple methods which clients can use to authe * [Authentication with JSON Web Tokens (JWT)](#authentication-with-json-web-tokensjwt) * [Authentication with client certificates](#authentication-with-client-certificates) * [Authentication with Personal Access Token (PAT)](#authentication-with-personal-access-token-pat) -* [Authentication with SAF Identity Tokens](#authentication-with-saf-identity-tokens) * [Multi-factor authentication (MFA)](#multi-factor-authentication-mfa) * [Advanced Authentication Mainframe (AAM)](#advanced-authentication-mainframe-aam) @@ -32,11 +31,6 @@ A Personal Access Token (PAT) is a specific scoped JWT with a configurable valid For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token.md). -## Authentication with SAF Identity Tokens -The SAF Authentication Provider allows the API Gateway to authenticate the user directly with the z/OS SAF provider that is installed on the system. - -For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system.md#configure-signed-saf-identity-tokens-idt). - ## Multi-factor authentication (MFA) Multi-factor authentication is provided by third-party products which Zowe is compatible with. The following are known to work with Zowe: diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md index e0ead2e71c..5adacfcde8 100644 --- a/docs/getting-started/zowe-security-overview.md +++ b/docs/getting-started/zowe-security-overview.md @@ -3,7 +3,7 @@ Zowe implements comprehensive measures to secure mainframe services and data resources in transition and in rest: - Digital certificates are used by Zowe to facilitate secure electronic communication and data exchange between people, systems, and devices online. -- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, Multi-Factor Authentication (MFA), JWT, or Personal Access Token (PAT). +- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, JWT, or Personal Access Token (PAT). Potentially with added Multi-Factor Authentication (MFA). - User access is authorized by System Authorization Facility (SAF) / External Security Manager (ESM). Before installation and use of Zowe server-side components, it is practical to first learn about the core security features built into the Zowe architecture. @@ -28,11 +28,18 @@ A certificate contains an identity (a hostname, or an organization, or an indivi A certificate can be self-signed or issued by a Certificate Authority (CA). A CA is a trusted organization which provides infrastructure for creation, validation and revocation of the certificates according to the contemporary security standards. -**Note:** -For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local CA, or even self-signed certificates issued by Zowe security tools specific for the target technology platform. -Use of self-signed certificates, however, is not recommended for production environments. +:::note -**Tip:** Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates. +For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local Certificate Authority (CA), or even certificates issued by Zowe security tools and signed by generated CA specific for the target technology platform. +Use of certificates signed by generated CA, however, is not recommended for production environments. + +::: + +:::tip + +Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates. + +::: ### Digital certificates usage Zowe uses digital certificates to secure the communication channel between Zowe components as well as between Zowe clients and Zowe services. Digital client certificates can also be used to validate that a client-user (the service user) identity is known to the mainframe security facility. @@ -44,9 +51,9 @@ Zowe uses digital certificates to secure the communication channel between Zowe ## User Authentication Zowe always authenticates the users accessing its interfaces and services. -Zowe API ML implements a Singls-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid. +Zowe API ML implements a Single-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid. -API ML uses multiple authentication methods - from Basic Auth (username-password), to external Multi-Factor Authentication providers, and modern authentication protocols, such as OIDC/OAuth2. +API ML uses multiple authentication methods - Basic Auth (username-password), OIDC/OAuth2, Client certificates and Personal Access Tokens with possibility of strengthening of the security by adding external Multi-Factor Authentication provider. **Next steps:** - For more details on the authentication methods used by Zowe, see the dedicated [API ML User Authentication](./zowe-security-authentication) article. @@ -68,7 +75,7 @@ Access to a SAF resource is checked with the installed z/OS External Security Ma For detailed information, see the [SAF resource checking documentation](../user-guide/api-mediation/configuration-saf-resource-checking). ## Additional resources -For more information about getting started with certificates including dertermining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources: +For more information about getting started with certificates including determining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources: - [Use-case based certificates configuration scenarios](../user-guide/certificate-configuration-scenarios.md) - [Generate certificates for Zowe servers](../user-guide/generate-certificates.md) diff --git a/docs/getting-started/zowe_faq.md b/docs/getting-started/zowe_faq.md index b881f4576c..9ce6862d63 100644 --- a/docs/getting-started/zowe_faq.md +++ b/docs/getting-started/zowe_faq.md @@ -34,7 +34,7 @@ Zowe technology can be used by a variety of mainframe IT and non-IT professional -Zowe consists of several components. The primary languages are Java and JavaScript. Zowe CLI and Desktop are written in TypeScript. ZSS is written in C, while the cross memory server is written in metal C. +Zowe consists of several components. The primary languages for API Mediation Layer are Java and JavaScript. Zowe CLI, Explorer for VSCode, and Desktop are written in TypeScript. Zowe Explorer plug-in for IntelliJ IDEA is written in Kotlin, ZSS is written in C, while the cross memory server is written in metal C. @@ -499,19 +499,19 @@ As a developer, you may contribute to Zowe Explorer in the following ways: -## Zowe IntelliJ plug-in FAQ +## Zowe Explorer plug-in for IntelliJ IDEA FAQ -### Why might I use Zowe IntelliJ plug-in versus a traditional ISPF interface to perform mainframe tasks? +### Why would I use the plug-in versus a traditional ISPF interface to perform mainframe tasks?
-Zowe IntelliJ plug-in allows you to access and work with data sets, members and jobs directly from your IntelliJ-based IDE. +Zowe Explorer plug-in for IntelliJ IDEA allows you to access and work with data sets, members and jobs directly from your IntelliJ-based IDE, such as IntelliJ IDEA, PyCharm, Android Studio, etc.
-### How can I get started with Zowe IntelliJ plug-in? +### How can I get started with Zowe Explorer plug-in for IntelliJ IDEA?
@@ -521,42 +521,32 @@ Install the plug-in in your IntelliJ-based IDE directly from marketplace or down
-### Where can I use Zowe IntelliJ plug-in? +### Where can I use Zowe Explorer plug-in for IntelliJ IDEA?
-You can use it in any IntelliJ-based IDE. +You can use it in any IntelliJ-based IDE, such as IntelliJ IDEA, PyCharm, Android Studio, etc.
-### How do I get help with using Zowe IntelliJ plug-in? +### How do I get help with using Zowe Explorer plug-in for IntelliJ IDEA?
-You can read detailed user guide and find any information you need [here](https://plugins.jetbrains.com/plugin/18688-zowe-explorer/user-guide). Also, you can ask any questions in the Zowe Slack channel [#zowe-explorer-intellij](https://openmainframeproject.slack.com/archives/C020BGPSU0M). +You can start with the [Use cases](../user-guide/intellij-use-cases.md) section to learn about use cases and how to install and use the plug-in. Also, you can ask any questions in our [Zowe Slack channel (#zowe-explorer-intellij)](https://openmainframeproject.slack.com/archives/C020BGPSU0M).
-### How can I create, edit and delete z/OSMF connection? +### How can I contribute to Zowe Explorer plug-in for IntelliJ IDEA?
-To create a connection, expand plug-in panel on an IDE sidebar (on the right side of your screen) and press the "wrench" pictogram, or go to **File** -> **Settings** (CTRL+ALT+S), select **Zowe Explorer (Zowe IntelliJ plugin)** and then switch to the **z/OSMF connection** tab. Press the “+” button and fill inn all necessary fields. - -
- -### How can I contribute to Zowe IntelliJ plug-in? - -
- - - -If you have something to introduce but there is no related issue in the project repo, then you can either create the issue by yourself or contact us to help you with it. See more information in the [CONTRIBUTION.md](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md) file. +If you have ideas on how to improve the plug-in, or have an issue/bug fix in mind, visit the [contribution guide](https://github.com/zowe/zowe-explorer-intellij/blob/main/CONTRIBUTING.md). Also, you can ask for help in our [Zowe Slack channel (#zowe-explorer-intellij)](https://openmainframeproject.slack.com/archives/C020BGPSU0M).
diff --git a/docs/getting-started/zowe_v2_faq.md b/docs/getting-started/zowe_v2_faq.md index 938d31523d..5970d3c32e 100644 --- a/docs/getting-started/zowe_v2_faq.md +++ b/docs/getting-started/zowe_v2_faq.md @@ -2,7 +2,7 @@ ## Where can I find the V1 and V2 LTS conformance criteria? -The Zowe Squads have prepared XLS spreadsheets with conformance criteria for all Zowe extensions including: CLI, APIs, App Framework, and Explorer for VS Code. The spreadsheets clearly show the prior / V1 criteria alongside the new / V2 criteria. Please be aware, there are additions, deletions, and CHANGES to the criteria. In some cases the change is simply that a BEST PRACTICE has been deemed REQUIRED. Use the included fill color key to identify new changes for V2, reworded changes, or changes from V1 removed in V2. See the Changes to the [Conformance Criteria](https://www.zowe.org/vnext#conformance-changes) section at Zowe.org/vNext. +The Zowe Squads have prepared XLS spreadsheets with conformance criteria for all Zowe extensions including: CLI, APIs, App Framework, and Explorer for VS Code. The spreadsheets clearly show the prior / V1 criteria alongside the new / V2 criteria. Please be aware, there are additions, deletions, and CHANGES to the criteria. In some cases, the change is simply that a BEST PRACTICE has been deemed REQUIRED. Use the included fill color key to identify new changes for V2, reworded changes, or changes from V1 removed in V2. See the Changes to the [Conformance Criteria](https://www.zowe.org/vnext#conformance-changes) section at Zowe.org/vNext. ## Whats the difference between "server.json" and "example-zowe.yaml"? @@ -16,7 +16,7 @@ For more information on Zowe setup and the yaml configuration, run the following ## What are the new default ports? -Four of the default Zowe ports have changed: the app server, zss, the jobs API, and the files API. The new default app server port is 7556 (previously 8544) and the new zss port is 7557 (previously 8542). The new jobs API port is 7558 (previously 8545) and the new files API is 7559 (previously 8547). The JES/USS/MVS Explorer UI servers have been removed and thus no longer require port configurations. +Four of the default Zowe ports have changed for the app server, and ZSS. The new default app server port is 7556 (previously 8544) and the new ZSS port is 7557 (previously 8542). The JES/USS/MVS Explorer UI servers have been removed, and thus no longer require port configurations. ## How do I access Zowe through the API Mediation Layer in V2? diff --git a/docs/images/api-mediation/api-catalog.png b/docs/images/api-mediation/api-catalog.png index 68032a4c36..8a75cb1ba1 100644 Binary files a/docs/images/api-mediation/api-catalog.png and b/docs/images/api-mediation/api-catalog.png differ diff --git a/docs/images/common/Zowe-HA-Architecture-View.pptx b/docs/images/common/Zowe-HA-Architecture-View.pptx index 7ebf17304a..9db8061e33 100644 Binary files a/docs/images/common/Zowe-HA-Architecture-View.pptx and b/docs/images/common/Zowe-HA-Architecture-View.pptx differ diff --git a/docs/images/common/zowe-architecture-docker.png b/docs/images/common/zowe-architecture-docker.png index 05079762d5..0e4cf0b842 100644 Binary files a/docs/images/common/zowe-architecture-docker.png and b/docs/images/common/zowe-architecture-docker.png differ diff --git a/docs/images/common/zowe-architecture-ha copy.png b/docs/images/common/zowe-architecture-ha copy.png new file mode 100644 index 0000000000..07a4d8085c Binary files /dev/null and b/docs/images/common/zowe-architecture-ha copy.png differ diff --git a/docs/images/common/zowe-architecture-ha.png b/docs/images/common/zowe-architecture-ha.png index 05ebdd4bd0..1ba43768a9 100644 Binary files a/docs/images/common/zowe-architecture-ha.png and b/docs/images/common/zowe-architecture-ha.png differ diff --git a/docs/images/common/zowe-architecture-k8s.png b/docs/images/common/zowe-architecture-k8s.png index 7a7ae39ce4..478d1de95d 100644 Binary files a/docs/images/common/zowe-architecture-k8s.png and b/docs/images/common/zowe-architecture-k8s.png differ diff --git a/docs/images/common/zowe-architecture.png b/docs/images/common/zowe-architecture.png index 5f11f0b012..555d0df35d 100644 Binary files a/docs/images/common/zowe-architecture.png and b/docs/images/common/zowe-architecture.png differ diff --git a/docs/images/common/zowe-architecture.pptx b/docs/images/common/zowe-architecture.pptx index 1378135378..36b3c897dc 100644 Binary files a/docs/images/common/zowe-architecture.pptx and b/docs/images/common/zowe-architecture.pptx differ diff --git a/docs/images/intellij/actions_download_artifact.png b/docs/images/intellij/actions_download_artifact.png new file mode 100644 index 0000000000..bf531808ab Binary files /dev/null and b/docs/images/intellij/actions_download_artifact.png differ diff --git a/docs/images/intellij/actions_select_build.png b/docs/images/intellij/actions_select_build.png new file mode 100644 index 0000000000..3eaa68a3f8 Binary files /dev/null and b/docs/images/intellij/actions_select_build.png differ diff --git a/docs/images/intellij/actions_select_workflow.png b/docs/images/intellij/actions_select_workflow.png new file mode 100644 index 0000000000..fb9b5f7d63 Binary files /dev/null and b/docs/images/intellij/actions_select_workflow.png differ diff --git a/docs/images/intellij/connection_create.gif b/docs/images/intellij/connection_create.gif index 2ce0944f5d..d0d3f4a972 100644 Binary files a/docs/images/intellij/connection_create.gif and b/docs/images/intellij/connection_create.gif differ diff --git a/docs/images/intellij/connection_zowe_config_v2.gif b/docs/images/intellij/connection_zowe_config_v2.gif deleted file mode 100644 index 999a7445e5..0000000000 Binary files a/docs/images/intellij/connection_zowe_config_v2.gif and /dev/null differ diff --git a/docs/images/intellij/copy_cut_member_copy.png b/docs/images/intellij/copy_cut_member_copy.png new file mode 100644 index 0000000000..324e80469a Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy.png differ diff --git a/docs/images/intellij/copy_cut_member_copy_dialog.png b/docs/images/intellij/copy_cut_member_copy_dialog.png new file mode 100644 index 0000000000..91ccea06f9 Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_dialog.png differ diff --git a/docs/images/intellij/copy_cut_member_copy_result.png b/docs/images/intellij/copy_cut_member_copy_result.png new file mode 100644 index 0000000000..42ab971e12 Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_result.png differ diff --git a/docs/images/intellij/copy_cut_member_copy_select_paste.png b/docs/images/intellij/copy_cut_member_copy_select_paste.png new file mode 100644 index 0000000000..1d484a1b31 Binary files /dev/null and b/docs/images/intellij/copy_cut_member_copy_select_paste.png differ diff --git a/docs/images/intellij/copy_cut_member_cut.png b/docs/images/intellij/copy_cut_member_cut.png new file mode 100644 index 0000000000..6321619672 Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut.png differ diff --git a/docs/images/intellij/copy_cut_member_cut_dialog.png b/docs/images/intellij/copy_cut_member_cut_dialog.png new file mode 100644 index 0000000000..dcdef7913c Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_dialog.png differ diff --git a/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png b/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png new file mode 100644 index 0000000000..76264f5fee Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_moving_confirmation.png differ diff --git a/docs/images/intellij/copy_cut_member_cut_result_source.png b/docs/images/intellij/copy_cut_member_cut_result_source.png new file mode 100644 index 0000000000..b3fabea85f Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_result_source.png differ diff --git a/docs/images/intellij/copy_cut_member_cut_select_paste.png b/docs/images/intellij/copy_cut_member_cut_select_paste.png new file mode 100644 index 0000000000..f1a8e2f4be Binary files /dev/null and b/docs/images/intellij/copy_cut_member_cut_select_paste.png differ diff --git a/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png b/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png new file mode 100644 index 0000000000..f1db0ecdae Binary files /dev/null and b/docs/images/intellij/copy_cut_member_to_uss_copy_dialog.png differ diff --git a/docs/images/intellij/copy_cut_member_to_uss_copy_result.png b/docs/images/intellij/copy_cut_member_to_uss_copy_result.png new file mode 100644 index 0000000000..729b5044b0 Binary files /dev/null and b/docs/images/intellij/copy_cut_member_to_uss_copy_result.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png new file mode 100644 index 0000000000..9e5060b46e Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png new file mode 100644 index 0000000000..905148130e Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png new file mode 100644 index 0000000000..c0cac766b1 Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png new file mode 100644 index 0000000000..07e1334649 Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cross_copy_result.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut.png b/docs/images/intellij/copy_cut_pds_to_uss_cut.png new file mode 100644 index 0000000000..8018c7e0bf Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png b/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png new file mode 100644 index 0000000000..39e7c995ef Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut_paste.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png b/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png new file mode 100644 index 0000000000..336a4776ff Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_cut_result.png differ diff --git a/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png b/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png new file mode 100644 index 0000000000..cb4973c54b Binary files /dev/null and b/docs/images/intellij/copy_cut_pds_to_uss_moving_dialog.png differ diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy.png b/docs/images/intellij/copy_cut_ps_to_pds_copy.png new file mode 100644 index 0000000000..f1461fbef1 Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy.png differ diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png new file mode 100644 index 0000000000..15491181ff Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_conflicts.png differ diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png new file mode 100644 index 0000000000..880fd44c6d Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_dialog.png differ diff --git a/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png b/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png new file mode 100644 index 0000000000..68bf2f662f Binary files /dev/null and b/docs/images/intellij/copy_cut_ps_to_pds_copy_result.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut.png b/docs/images/intellij/copy_cut_uss_to_pds_cut.png new file mode 100644 index 0000000000..8701ef2de2 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png new file mode 100644 index 0000000000..c50cc946f5 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_content_before.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png new file mode 100644 index 0000000000..cb7962a590 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_paste.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png new file mode 100644 index 0000000000..d4f0bd1f87 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png b/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png new file mode 100644 index 0000000000..65fd5560d0 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_cut_result.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png b/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png new file mode 100644 index 0000000000..235e62cc36 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_pds_moving_dialog.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png b/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png new file mode 100644 index 0000000000..ff35dccdaa Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_copy_select_paste.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut.png b/docs/images/intellij/copy_cut_uss_to_uss_cut.png new file mode 100644 index 0000000000..ee9dfae668 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png b/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png new file mode 100644 index 0000000000..3b970b3e81 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut_result.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png b/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png new file mode 100644 index 0000000000..a811ef2936 Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_cut_select_paste.png differ diff --git a/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png b/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png new file mode 100644 index 0000000000..2e8a64b9bc Binary files /dev/null and b/docs/images/intellij/copy_cut_uss_to_uss_moving_dialog.png differ diff --git a/docs/images/intellij/copy_mem_to_uss.gif b/docs/images/intellij/copy_mem_to_uss.gif deleted file mode 100644 index 6fbfd5ff88..0000000000 Binary files a/docs/images/intellij/copy_mem_to_uss.gif and /dev/null differ diff --git a/docs/images/intellij/create_connection_plus.png b/docs/images/intellij/create_connection_plus.png new file mode 100644 index 0000000000..840180d026 Binary files /dev/null and b/docs/images/intellij/create_connection_plus.png differ diff --git a/docs/images/intellij/create_connection_settings.png b/docs/images/intellij/create_connection_settings.png new file mode 100644 index 0000000000..9cb325af0f Binary files /dev/null and b/docs/images/intellij/create_connection_settings.png differ diff --git a/docs/images/intellij/create_connection_zowe_config_file.gif b/docs/images/intellij/create_connection_zowe_config_file.gif new file mode 100644 index 0000000000..3b0d6dbb1a Binary files /dev/null and b/docs/images/intellij/create_connection_zowe_config_file.gif differ diff --git a/docs/images/intellij/create_connection_zowe_config_plus.gif b/docs/images/intellij/create_connection_zowe_config_plus.gif new file mode 100644 index 0000000000..587ddca3d2 Binary files /dev/null and b/docs/images/intellij/create_connection_zowe_config_plus.gif differ diff --git a/docs/images/intellij/create_plugins_connection_or_zowe_config.png b/docs/images/intellij/create_plugins_connection_or_zowe_config.png new file mode 100644 index 0000000000..0a035a61af Binary files /dev/null and b/docs/images/intellij/create_plugins_connection_or_zowe_config.png differ diff --git a/docs/images/intellij/cross_system_copy.gif b/docs/images/intellij/cross_system_copy.gif deleted file mode 100644 index 156b4233ed..0000000000 Binary files a/docs/images/intellij/cross_system_copy.gif and /dev/null differ diff --git a/docs/images/intellij/datasets_sort.png b/docs/images/intellij/datasets_sort.png new file mode 100644 index 0000000000..8e11b57e76 Binary files /dev/null and b/docs/images/intellij/datasets_sort.png differ diff --git a/docs/images/intellij/datasets_sort_result.png b/docs/images/intellij/datasets_sort_result.png new file mode 100644 index 0000000000..857bbdfe79 Binary files /dev/null and b/docs/images/intellij/datasets_sort_result.png differ diff --git a/docs/images/intellij/download_intellij.png b/docs/images/intellij/download_intellij.png new file mode 100644 index 0000000000..c4bb2094c3 Binary files /dev/null and b/docs/images/intellij/download_intellij.png differ diff --git a/docs/images/intellij/download_plugin_marketplace.png b/docs/images/intellij/download_plugin_marketplace.png new file mode 100644 index 0000000000..67e3fa3343 Binary files /dev/null and b/docs/images/intellij/download_plugin_marketplace.png differ diff --git a/docs/images/intellij/download_plugin_releases.png b/docs/images/intellij/download_plugin_releases.png new file mode 100644 index 0000000000..469c24d4a4 Binary files /dev/null and b/docs/images/intellij/download_plugin_releases.png differ diff --git a/docs/images/intellij/download_uss_copy.png b/docs/images/intellij/download_uss_copy.png new file mode 100644 index 0000000000..b0a45906fd Binary files /dev/null and b/docs/images/intellij/download_uss_copy.png differ diff --git a/docs/images/intellij/download_uss_copy_final_dialog.png b/docs/images/intellij/download_uss_copy_final_dialog.png new file mode 100644 index 0000000000..9e3ddc6597 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_final_dialog.png differ diff --git a/docs/images/intellij/download_uss_copy_name_conflicts.png b/docs/images/intellij/download_uss_copy_name_conflicts.png new file mode 100644 index 0000000000..f0a0ca03a1 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_name_conflicts.png differ diff --git a/docs/images/intellij/download_uss_copy_paste.png b/docs/images/intellij/download_uss_copy_paste.png new file mode 100644 index 0000000000..083dca4bd4 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_paste.png differ diff --git a/docs/images/intellij/download_uss_copy_result.png b/docs/images/intellij/download_uss_copy_result.png new file mode 100644 index 0000000000..d65071f499 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_result.png differ diff --git a/docs/images/intellij/download_uss_copy_security_warning.png b/docs/images/intellij/download_uss_copy_security_warning.png new file mode 100644 index 0000000000..fbe90227b9 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_security_warning.png differ diff --git a/docs/images/intellij/download_uss_copy_single_conflict.png b/docs/images/intellij/download_uss_copy_single_conflict.png new file mode 100644 index 0000000000..a94c4b7244 Binary files /dev/null and b/docs/images/intellij/download_uss_copy_single_conflict.png differ diff --git a/docs/images/intellij/get_plugin.png b/docs/images/intellij/get_plugin.png new file mode 100644 index 0000000000..92a415066b Binary files /dev/null and b/docs/images/intellij/get_plugin.png differ diff --git a/docs/images/intellij/install_from_bin_from_disk.png b/docs/images/intellij/install_from_bin_from_disk.png new file mode 100644 index 0000000000..236f3e6bce Binary files /dev/null and b/docs/images/intellij/install_from_bin_from_disk.png differ diff --git a/docs/images/intellij/install_from_bin_restart.png b/docs/images/intellij/install_from_bin_restart.png new file mode 100644 index 0000000000..55e43c3757 Binary files /dev/null and b/docs/images/intellij/install_from_bin_restart.png differ diff --git a/docs/images/intellij/install_from_bin_search_for_zip.png b/docs/images/intellij/install_from_bin_search_for_zip.png new file mode 100644 index 0000000000..9df91c8b38 Binary files /dev/null and b/docs/images/intellij/install_from_bin_search_for_zip.png differ diff --git a/docs/images/intellij/install_in_intellij_after_install.png b/docs/images/intellij/install_in_intellij_after_install.png new file mode 100644 index 0000000000..a5747d96e2 Binary files /dev/null and b/docs/images/intellij/install_in_intellij_after_install.png differ diff --git a/docs/images/intellij/install_in_intellij_corner_change.png b/docs/images/intellij/install_in_intellij_corner_change.png new file mode 100644 index 0000000000..fad743bb00 Binary files /dev/null and b/docs/images/intellij/install_in_intellij_corner_change.png differ diff --git a/docs/images/intellij/install_in_intellij_marketplace.png b/docs/images/intellij/install_in_intellij_marketplace.png new file mode 100644 index 0000000000..5c30f5da81 Binary files /dev/null and b/docs/images/intellij/install_in_intellij_marketplace.png differ diff --git a/docs/images/intellij/install_in_intellij_plugins.png b/docs/images/intellij/install_in_intellij_plugins.png new file mode 100644 index 0000000000..facba91f00 Binary files /dev/null and b/docs/images/intellij/install_in_intellij_plugins.png differ diff --git a/docs/images/intellij/install_in_intellij_restart.png b/docs/images/intellij/install_in_intellij_restart.png new file mode 100644 index 0000000000..c7d8190aec Binary files /dev/null and b/docs/images/intellij/install_in_intellij_restart.png differ diff --git a/docs/images/intellij/install_in_intellij_search_and_install.png b/docs/images/intellij/install_in_intellij_search_and_install.png new file mode 100644 index 0000000000..8f0d0a0f4c Binary files /dev/null and b/docs/images/intellij/install_in_intellij_search_and_install.png differ diff --git a/docs/images/intellij/intellij-install.gif b/docs/images/intellij/intellij-install.gif deleted file mode 100644 index 10c06fb377..0000000000 Binary files a/docs/images/intellij/intellij-install.gif and /dev/null differ diff --git a/docs/images/intellij/intellij_open_uss_file.png b/docs/images/intellij/intellij_open_uss_file.png new file mode 100644 index 0000000000..0b32036819 Binary files /dev/null and b/docs/images/intellij/intellij_open_uss_file.png differ diff --git a/docs/images/intellij/jes_jcl_edit.png b/docs/images/intellij/jes_jcl_edit.png new file mode 100644 index 0000000000..f0a923106b Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit.png differ diff --git a/docs/images/intellij/jes_jcl_edit_after_refresh.png b/docs/images/intellij/jes_jcl_edit_after_refresh.png new file mode 100644 index 0000000000..569a63f0b8 Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_after_refresh.png differ diff --git a/docs/images/intellij/jes_jcl_edit_console.png b/docs/images/intellij/jes_jcl_edit_console.png new file mode 100644 index 0000000000..e12ea9e9ba Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_console.png differ diff --git a/docs/images/intellij/jes_jcl_edit_refresh.png b/docs/images/intellij/jes_jcl_edit_refresh.png new file mode 100644 index 0000000000..29e267c385 Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_refresh.png differ diff --git a/docs/images/intellij/jes_jcl_edit_run_button.png b/docs/images/intellij/jes_jcl_edit_run_button.png new file mode 100644 index 0000000000..34134795f7 Binary files /dev/null and b/docs/images/intellij/jes_jcl_edit_run_button.png differ diff --git a/docs/images/intellij/jes_purge_click_purge.png b/docs/images/intellij/jes_purge_click_purge.png new file mode 100644 index 0000000000..ac0a9b30db Binary files /dev/null and b/docs/images/intellij/jes_purge_click_purge.png differ diff --git a/docs/images/intellij/jes_purge_dialog.png b/docs/images/intellij/jes_purge_dialog.png new file mode 100644 index 0000000000..41986de1e6 Binary files /dev/null and b/docs/images/intellij/jes_purge_dialog.png differ diff --git a/docs/images/intellij/jes_purge_job_create_filter.png b/docs/images/intellij/jes_purge_job_create_filter.png new file mode 100644 index 0000000000..499faf1924 Binary files /dev/null and b/docs/images/intellij/jes_purge_job_create_filter.png differ diff --git a/docs/images/intellij/jes_purge_job_filter_dialog.png b/docs/images/intellij/jes_purge_job_filter_dialog.png new file mode 100644 index 0000000000..1e5956cd88 Binary files /dev/null and b/docs/images/intellij/jes_purge_job_filter_dialog.png differ diff --git a/docs/images/intellij/jes_purge_success_notification.png b/docs/images/intellij/jes_purge_success_notification.png new file mode 100644 index 0000000000..23cc7cdba8 Binary files /dev/null and b/docs/images/intellij/jes_purge_success_notification.png differ diff --git a/docs/images/intellij/jes_sort.png b/docs/images/intellij/jes_sort.png new file mode 100644 index 0000000000..f14fbd4724 Binary files /dev/null and b/docs/images/intellij/jes_sort.png differ diff --git a/docs/images/intellij/jes_sort_sorted.png b/docs/images/intellij/jes_sort_sorted.png new file mode 100644 index 0000000000..4877f9db80 Binary files /dev/null and b/docs/images/intellij/jes_sort_sorted.png differ diff --git a/docs/images/intellij/jes_spool_console.png b/docs/images/intellij/jes_spool_console.png new file mode 100644 index 0000000000..6b0091b4fe Binary files /dev/null and b/docs/images/intellij/jes_spool_console.png differ diff --git a/docs/images/intellij/jes_spool_console_shown.png b/docs/images/intellij/jes_spool_console_shown.png new file mode 100644 index 0000000000..56dab8b1d9 Binary files /dev/null and b/docs/images/intellij/jes_spool_console_shown.png differ diff --git a/docs/images/intellij/jes_spool_view.png b/docs/images/intellij/jes_spool_view.png new file mode 100644 index 0000000000..220a12ec28 Binary files /dev/null and b/docs/images/intellij/jes_spool_view.png differ diff --git a/docs/images/intellij/jes_spool_view_editor.png b/docs/images/intellij/jes_spool_view_editor.png new file mode 100644 index 0000000000..e85b47b21d Binary files /dev/null and b/docs/images/intellij/jes_spool_view_editor.png differ diff --git a/docs/images/intellij/jes_spool_view_reveal.png b/docs/images/intellij/jes_spool_view_reveal.png new file mode 100644 index 0000000000..07c7f56706 Binary files /dev/null and b/docs/images/intellij/jes_spool_view_reveal.png differ diff --git a/docs/images/intellij/jes_status.png b/docs/images/intellij/jes_status.png new file mode 100644 index 0000000000..93eb89afb5 Binary files /dev/null and b/docs/images/intellij/jes_status.png differ diff --git a/docs/images/intellij/move_mem_to_ds.gif b/docs/images/intellij/move_mem_to_ds.gif deleted file mode 100644 index 5814436b3d..0000000000 Binary files a/docs/images/intellij/move_mem_to_ds.gif and /dev/null differ diff --git a/docs/images/intellij/move_uss_folder_to_uss_folder.gif b/docs/images/intellij/move_uss_folder_to_uss_folder.gif deleted file mode 100644 index cfe62346bf..0000000000 Binary files a/docs/images/intellij/move_uss_folder_to_uss_folder.gif and /dev/null differ diff --git a/docs/images/intellij/move_uss_to_pds.gif b/docs/images/intellij/move_uss_to_pds.gif deleted file mode 100644 index 0633c186f8..0000000000 Binary files a/docs/images/intellij/move_uss_to_pds.gif and /dev/null differ diff --git a/docs/images/intellij/pds_copy_move_ds.gif b/docs/images/intellij/pds_copy_move_ds.gif deleted file mode 100644 index 26d42b7d3c..0000000000 Binary files a/docs/images/intellij/pds_copy_move_ds.gif and /dev/null differ diff --git a/docs/images/intellij/pds_move_zos_to_uss.gif b/docs/images/intellij/pds_move_zos_to_uss.gif deleted file mode 100644 index 6cfedd82fd..0000000000 Binary files a/docs/images/intellij/pds_move_zos_to_uss.gif and /dev/null differ diff --git a/docs/images/intellij/plugin_all_configurations.png b/docs/images/intellij/plugin_all_configurations.png new file mode 100644 index 0000000000..4c3cd38e26 Binary files /dev/null and b/docs/images/intellij/plugin_all_configurations.png differ diff --git a/docs/images/intellij/plugin_create_dataset.png b/docs/images/intellij/plugin_create_dataset.png new file mode 100644 index 0000000000..831b9100d0 Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset.png differ diff --git a/docs/images/intellij/plugin_create_dataset_fields.png b/docs/images/intellij/plugin_create_dataset_fields.png new file mode 100644 index 0000000000..072797d042 Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset_fields.png differ diff --git a/docs/images/intellij/plugin_create_dataset_ok.png b/docs/images/intellij/plugin_create_dataset_ok.png new file mode 100644 index 0000000000..5d71cfcd35 Binary files /dev/null and b/docs/images/intellij/plugin_create_dataset_ok.png differ diff --git a/docs/images/intellij/plugin_create_mask_or_skip.png b/docs/images/intellij/plugin_create_mask_or_skip.png new file mode 100644 index 0000000000..6e4721fc62 Binary files /dev/null and b/docs/images/intellij/plugin_create_mask_or_skip.png differ diff --git a/docs/images/intellij/plugin_dataset_presets.png b/docs/images/intellij/plugin_dataset_presets.png new file mode 100644 index 0000000000..ce73928c44 Binary files /dev/null and b/docs/images/intellij/plugin_dataset_presets.png differ diff --git a/docs/images/intellij/plugin_open_settings.png b/docs/images/intellij/plugin_open_settings.png new file mode 100644 index 0000000000..7088ae4f0c Binary files /dev/null and b/docs/images/intellij/plugin_open_settings.png differ diff --git a/docs/images/intellij/plugin_other_settings.png b/docs/images/intellij/plugin_other_settings.png new file mode 100644 index 0000000000..baded2dec6 Binary files /dev/null and b/docs/images/intellij/plugin_other_settings.png differ diff --git a/docs/images/intellij/plugin_save_before_close.png b/docs/images/intellij/plugin_save_before_close.png new file mode 100644 index 0000000000..1f017dfd30 Binary files /dev/null and b/docs/images/intellij/plugin_save_before_close.png differ diff --git a/docs/images/intellij/plugin_sync_button.png b/docs/images/intellij/plugin_sync_button.png new file mode 100644 index 0000000000..db9bd7d4a7 Binary files /dev/null and b/docs/images/intellij/plugin_sync_button.png differ diff --git a/docs/images/intellij/select_compatibility_and_channel.png b/docs/images/intellij/select_compatibility_and_channel.png new file mode 100644 index 0000000000..7c5c32556d Binary files /dev/null and b/docs/images/intellij/select_compatibility_and_channel.png differ diff --git a/docs/images/intellij/tso_cli.gif b/docs/images/intellij/tso_cli.gif deleted file mode 100644 index c7171ca53c..0000000000 Binary files a/docs/images/intellij/tso_cli.gif and /dev/null differ diff --git a/docs/images/intellij/tso_console_create.png b/docs/images/intellij/tso_console_create.png new file mode 100644 index 0000000000..1daa4c9aa7 Binary files /dev/null and b/docs/images/intellij/tso_console_create.png differ diff --git a/docs/images/intellij/tso_console_created_console.png b/docs/images/intellij/tso_console_created_console.png new file mode 100644 index 0000000000..1c8c6268af Binary files /dev/null and b/docs/images/intellij/tso_console_created_console.png differ diff --git a/docs/images/intellij/tso_console_dialog.png b/docs/images/intellij/tso_console_dialog.png new file mode 100644 index 0000000000..1525860666 Binary files /dev/null and b/docs/images/intellij/tso_console_dialog.png differ diff --git a/docs/images/intellij/tso_sessions_add.png b/docs/images/intellij/tso_sessions_add.png new file mode 100644 index 0000000000..15fb226403 Binary files /dev/null and b/docs/images/intellij/tso_sessions_add.png differ diff --git a/docs/images/intellij/tso_sessions_add_dialog.png b/docs/images/intellij/tso_sessions_add_dialog.png new file mode 100644 index 0000000000..ffe0ab737f Binary files /dev/null and b/docs/images/intellij/tso_sessions_add_dialog.png differ diff --git a/docs/images/intellij/tso_sessions_created.png b/docs/images/intellij/tso_sessions_created.png new file mode 100644 index 0000000000..71e8006fd6 Binary files /dev/null and b/docs/images/intellij/tso_sessions_created.png differ diff --git a/docs/images/intellij/tso_sessions_go_to_sessions.png b/docs/images/intellij/tso_sessions_go_to_sessions.png new file mode 100644 index 0000000000..7873e766da Binary files /dev/null and b/docs/images/intellij/tso_sessions_go_to_sessions.png differ diff --git a/docs/images/intellij/tso_sessions_wrench.png b/docs/images/intellij/tso_sessions_wrench.png new file mode 100644 index 0000000000..f5173631b6 Binary files /dev/null and b/docs/images/intellij/tso_sessions_wrench.png differ diff --git a/docs/images/intellij/upload_file_to_pds_copy.png b/docs/images/intellij/upload_file_to_pds_copy.png new file mode 100644 index 0000000000..637f6747cb Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy.png differ diff --git a/docs/images/intellij/upload_file_to_pds_copy_dialog.png b/docs/images/intellij/upload_file_to_pds_copy_dialog.png new file mode 100644 index 0000000000..fa1970f16c Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_dialog.png differ diff --git a/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png b/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png new file mode 100644 index 0000000000..c9eb8b1281 Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_member_truncation.png differ diff --git a/docs/images/intellij/upload_file_to_pds_copy_paste.png b/docs/images/intellij/upload_file_to_pds_copy_paste.png new file mode 100644 index 0000000000..0bba9a2a97 Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_paste.png differ diff --git a/docs/images/intellij/upload_file_to_pds_copy_result.png b/docs/images/intellij/upload_file_to_pds_copy_result.png new file mode 100644 index 0000000000..61dc37c715 Binary files /dev/null and b/docs/images/intellij/upload_file_to_pds_copy_result.png differ diff --git a/docs/images/intellij/uss_click_properties.png b/docs/images/intellij/uss_click_properties.png new file mode 100644 index 0000000000..cbd70c1830 Binary files /dev/null and b/docs/images/intellij/uss_click_properties.png differ diff --git a/docs/images/intellij/uss_encoding_dialog.png b/docs/images/intellij/uss_encoding_dialog.png new file mode 100644 index 0000000000..bc92d23e74 Binary files /dev/null and b/docs/images/intellij/uss_encoding_dialog.png differ diff --git a/docs/images/intellij/uss_encoding_select_option.png b/docs/images/intellij/uss_encoding_select_option.png new file mode 100644 index 0000000000..ac0bdc918c Binary files /dev/null and b/docs/images/intellij/uss_encoding_select_option.png differ diff --git a/docs/images/intellij/uss_encoding_warning_dialog.png b/docs/images/intellij/uss_encoding_warning_dialog.png new file mode 100644 index 0000000000..453900ad42 Binary files /dev/null and b/docs/images/intellij/uss_encoding_warning_dialog.png differ diff --git a/docs/images/intellij/uss_properties_change_owner_perms.png b/docs/images/intellij/uss_properties_change_owner_perms.png new file mode 100644 index 0000000000..7ec4383c90 Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms.png differ diff --git a/docs/images/intellij/uss_properties_change_owner_perms_ok.png b/docs/images/intellij/uss_properties_change_owner_perms_ok.png new file mode 100644 index 0000000000..2666ab3239 Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms_ok.png differ diff --git a/docs/images/intellij/uss_properties_change_owner_perms_select.png b/docs/images/intellij/uss_properties_change_owner_perms_select.png new file mode 100644 index 0000000000..6b80e9fdc2 Binary files /dev/null and b/docs/images/intellij/uss_properties_change_owner_perms_select.png differ diff --git a/docs/images/intellij/uss_properties_possible_changes.png b/docs/images/intellij/uss_properties_possible_changes.png new file mode 100644 index 0000000000..5f7c490d37 Binary files /dev/null and b/docs/images/intellij/uss_properties_possible_changes.png differ diff --git a/docs/images/intellij/uss_props_general_tab.png b/docs/images/intellij/uss_props_general_tab.png new file mode 100644 index 0000000000..175dc06985 Binary files /dev/null and b/docs/images/intellij/uss_props_general_tab.png differ diff --git a/docs/images/intellij/uss_sort.png b/docs/images/intellij/uss_sort.png new file mode 100644 index 0000000000..63fd7c2190 Binary files /dev/null and b/docs/images/intellij/uss_sort.png differ diff --git a/docs/images/intellij/uss_sort_result.png b/docs/images/intellij/uss_sort_result.png new file mode 100644 index 0000000000..0efca33b57 Binary files /dev/null and b/docs/images/intellij/uss_sort_result.png differ diff --git a/docs/images/intellij/work_with_jes_jobs.gif b/docs/images/intellij/work_with_jes_jobs.gif deleted file mode 100644 index 74aa2f535a..0000000000 Binary files a/docs/images/intellij/work_with_jes_jobs.gif and /dev/null differ diff --git a/docs/images/troubleshoot/cli/home_struc.png b/docs/images/troubleshoot/cli/home_struc.png index cb1a774e24..0582982585 100644 Binary files a/docs/images/troubleshoot/cli/home_struc.png and b/docs/images/troubleshoot/cli/home_struc.png differ diff --git a/docs/images/troubleshoot/cli/home_struc_2.png b/docs/images/troubleshoot/cli/home_struc_2.png new file mode 100644 index 0000000000..0582982585 Binary files /dev/null and b/docs/images/troubleshoot/cli/home_struc_2.png differ diff --git a/docs/images/troubleshoot/intellij/intellij-find-plugin.png b/docs/images/troubleshoot/intellij/intellij-find-plugin.png new file mode 100644 index 0000000000..7724b4354c Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-find-plugin.png differ diff --git a/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png b/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png new file mode 100644 index 0000000000..6aaee8b312 Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-go-to-plugins.png differ diff --git a/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png new file mode 100644 index 0000000000..bccadf7661 Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about.png differ diff --git a/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png new file mode 100644 index 0000000000..7bad12896b Binary files /dev/null and b/docs/images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png differ diff --git a/docs/images/ze/ZE-uss-drag-drop.gif b/docs/images/ze/ZE-uss-drag-drop.gif new file mode 100644 index 0000000000..6a2ff711f3 Binary files /dev/null and b/docs/images/ze/ZE-uss-drag-drop.gif differ diff --git a/docs/troubleshoot/cli/cli-issue.md b/docs/troubleshoot/cli/cli-issue.md index 557988016e..789a3d5888 100644 --- a/docs/troubleshoot/cli/cli-issue.md +++ b/docs/troubleshoot/cli/cli-issue.md @@ -1,6 +1,6 @@ # Raising a CLI issue on GitHub -When necessary, you can raise GitHub issues against the Zowe™ CLI repository [here](https://github.com/zowe/zowe-cli/issues). It is suggested that you use either the bug or enhancement template. +When necessary, raise a GitHub issue in the [Zowe™ CLI repository](https://github.com/zowe/zowe-cli/issues). It is suggested that you use either the bug or enhancement template. ## Raising a bug report diff --git a/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md b/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md index 8fdf6175a7..b1e1b6ad46 100644 --- a/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md +++ b/docs/troubleshoot/cli/cli-use-curl-to-troubleshoot.md @@ -19,7 +19,11 @@ Add cURL options to establish communication between Zowe CLI and z/OSMF, as in t ``` curl --location --request "https://:/" --header "X-CSRF-ZOSMF-HEADER;" --insecure --user ":" ``` -**NOTE:** Some terminals may require single quotes rather than double quotes. +:::note + +Some terminals might require single quotes rather than double quotes. + +::: ### `--location` @@ -32,21 +36,31 @@ When the server attempts to redirect and `--location` is not included in the com Use `--request` to identify the API method (such as `POST`, `GET`, `PUT`, `DELETE`). Not necessary when the API method is `GET`. -- ``: Specifies the API method used in the request. +- `` + + Specifies the API method used in the request. ### `"https://:/"` Indicates the protocol and URL. -- ``: Specifies the host name where the z/OSMF services are running. -- ``: Specifies the REST port number. If not specified, defaults to 443 for HTTPS. -- ``: Specifies the API endpoint used in the request. +- `` + + Specifies the host name where the z/OSMF services are running. +- `` + + Specifies the REST port number. If not specified, defaults to 443 for HTTPS. +- `` + + Specifies the API endpoint used in the request. ### `--header "X-CSRF-ZOSMF-HEADER;"` Required to establish communication with z/OSMF. Specifies that the client is sending a cross-site request to the REST interface. -- `;`: Indicates that the header has no value. (Not all commands require a value.) +- `;` + + Indicates that the header has no value. (Not all headers require a value.) To pass an additional header with a value, use a colon to separate the key and value. For example: `--header "X-IBM-Data-Type: binary"`. @@ -60,10 +74,18 @@ For example, this bypasses SSL certificate verification for servers with self-si Required and displays as plain text. Also possible to [use an environment variable](../../user-guide/cli-using-using-environment-variables.md). -- ``: Specifies the z/OSMF user identification. -- ``: Specifies the user password for z/OSMF. +- `` + + Specifies the z/OSMF user identification. +- `` + + Specifies the user password for z/OSMF. + +:::note + +To be prompted for a password instead of displaying it in plain text, omit the password from the command and enter `--user ""`. -**NOTE:** To be prompted for a password instead of displaying it in plain text, omit the password from the command and enter `--user ""`. +::: ## Comparing commands diff --git a/docs/troubleshoot/cli/known-cli.md b/docs/troubleshoot/cli/known-cli.md index bd913e1565..705dfc7a37 100644 --- a/docs/troubleshoot/cli/known-cli.md +++ b/docs/troubleshoot/cli/known-cli.md @@ -12,7 +12,6 @@ After you install Zowe CLI, and the installation appears to complete successfull - `zowe config init` - `zowe config secure` -- `zowe profiles create` - Most Zowe commands that access your mainframe environment This behavior occurs under the following conditions: @@ -25,14 +24,14 @@ This behavior occurs under the following conditions: 1. Define the `npm_config_global` environment variable. Issue the command that corresponds with your operating system: - - **Windows Command Prompt:** `set npm_config_global=true` - - **Windows PowerShell:** `$env:npm_config_global="true"` - - **macOS/Linux Bash:** `export npm_config_global=true` + - Windows Command Prompt: `set npm_config_global=true` + - Windows PowerShell: `$env:npm_config_global="true"` + - macOS/Linux Bash: `export npm_config_global=true` 2. Install or reinstall Zowe CLI using your preferred installation method. 3. After the Zowe CLI installation completes, reset the `npm_config_global` environment variable. Issue the command that corresponds with your operating system: - - **Windows Command Prompt:** `set npm_config_global=` - - **Windows PowerShell:** `$env:npm_config_global=""` - - **macOS/Linux Bash:** `export npm_config_global=` + - Windows Command Prompt: `set npm_config_global=` + - Windows PowerShell: `$env:npm_config_global=""` + - macOS/Linux Bash: `export npm_config_global=` 4. Continue configuring Zowe CLI. Or, reissue a Zowe command that returned an error message. You should no longer get an error message. ## Chain commands fail in a batch script @@ -81,9 +80,9 @@ To correct this behavior, verify the following: - Node.js and NPM are installed. - PATH contains the correct path to the NodeJS folder. -**More Information:** [System requirements for Zowe CLI](../../user-guide/systemrequirements-cli.md) +For more information, see [System requirements for Zowe CLI](../../user-guide/systemrequirements-cli.md). -## EACCESS error when issing `npm install` command +## EACCESS error when issuing `npm install` command **Valid on Windows, Mac, or Linux** @@ -137,28 +136,10 @@ report success using the following workarounds: - Issue the `npm cache clean` command. - - Uninstall and reinstall Zowe CLI. For more information, - see [Install Zowe CLI](../../user-guide/cli-installcli.md). + - Uninstall and reinstall Zowe CLI. For instructions, + see the [Zowe CLI installation checklist](../../user-guide/cli-install-cli-checklist.md). - - `Add the --no-optional` flag to the end of the `npm install` command. - -## `npm install -g` command fails due to `npm ERR! Cannot read property 'pause' of undefined` error - -**Valid on Windows or Linux** - -**Symptom:** - -You receive the error message `npm ERR! Cannot read property 'pause' of undefined` when you attempt to install the product. - -**Solution:** - -This behavior is due to a problem with Node Package Manager (npm). If -you encounter this problem, revert to a previous version of npm that -does not contain this defect. To revert to a previous version of npm, -issue the following command: -``` -npm install npm@5.3.0 -g -``` + - Add the `--no-optional` flag to the end of the `npm install` command. ## Paths converting in Git Bash @@ -178,7 +159,11 @@ If a command includes a path similar to the following example: ``` A:/ibmuser/my_dir ``` - **Note:** Depending on the root directory, the Git Bash conversion can add other directories it assumes to be included in the path. + :::note + + Depending on the root directory, the Git Bash conversion can add other directories it assumes to be included in the path. + + ::: **Solutions:** @@ -214,3 +199,15 @@ The installation fails on Linux or macOS. **Solution:** Depending on how you configured Node.js on Linux or macOS, you might need to add the prefix `sudo` before the `npm install -g` command or the `npm uninstall -g` command. This step gives Node.js write access to the installation directory. + +## Missing data set search results with `--mainframe-search` option + +**Valid on Windows, Mac, or Linux** + +**Symptom:** + +When the `zowe zos-files search data-sets` command is issued with the `--mainframe-search` option, results can omit data sets that are in binary format. + +**Solution:** + +Issue the `zowe files search ds` command without the `--mainframe-search` option. This returns results that include data sets in binary format. diff --git a/docs/troubleshoot/cli/mustgather-cli.md b/docs/troubleshoot/cli/mustgather-cli.md index 64bb039a42..c381f90512 100644 --- a/docs/troubleshoot/cli/mustgather-cli.md +++ b/docs/troubleshoot/cli/mustgather-cli.md @@ -40,7 +40,6 @@ zowe config list --locations The output provides a brief overview with the following information: - Configuration file locations - - Profile names and types - Profile type defaults - All property values (host, port, etc.) @@ -61,7 +60,7 @@ The output provides a list of configuration files that affect your Zowe commands Add the `--show-inputs-only` option to any Zowe command. -For example, if you want to check the command to list a data set, you add the option to the following command: +For example, if you want to check the command to list a data set, add the option to the following command: ``` zowe zos-files list data-set "SYS1.PARMLIB*" --show-inputs-only diff --git a/docs/troubleshoot/cli/troubleshoot-cli-credentials.md b/docs/troubleshoot/cli/troubleshoot-cli-credentials.md index 76e45c09e9..f00dc844a5 100644 --- a/docs/troubleshoot/cli/troubleshoot-cli-credentials.md +++ b/docs/troubleshoot/cli/troubleshoot-cli-credentials.md @@ -12,7 +12,7 @@ You can troubleshoot a failed log-in to a mainframe service by reviewing the aut Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with. -However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. +However, some services can accept multiple methods of authentication. When multiple methods are provided (in a configuration profile or command) for a service, the CLI follows an *order of precedence* to determine which method to apply. To find the authentication methods used for different services and their order of precedence, see the table in [Authentication mechanisms](../../extend/extend-cli/cli-devTutorials.md#authentication-mechanisms). @@ -20,7 +20,7 @@ To find the authentication methods used for different services and their order o PEM certificate files are used by Zowe CLI to authenticate to the API Mediation Layer. To be accepted, these certificate files must first be recorded in the service's keyring/trust-store on the mainframe before they are used by Zowe CLI. -Some users choose to secure PEM certificates by placing them in a password protected container, such as a PGP file, a ZIP file, or a password protected PKCS12 file (a.k.a. a PFX file). However, Zowe CLI does not currently support any certificate files that require a password for use. +Some users choose to secure PEM certificates by placing them in a password protected container, such as a PGP file, a ZIP file, or a password protected PKCS12 file (or a PFX file). However, Zowe CLI does not currently support any certificate files that require a password for use. :::note diff --git a/docs/troubleshoot/cli/troubleshoot-cli.md b/docs/troubleshoot/cli/troubleshoot-cli.md index 5170eea053..ed5a507712 100644 --- a/docs/troubleshoot/cli/troubleshoot-cli.md +++ b/docs/troubleshoot/cli/troubleshoot-cli.md @@ -19,8 +19,11 @@ These instructions apply to Zowe CLI installed on Windows, Mac OS X, and Linux s Collect the following information to help diagnose the issue: - Zowe CLI version installed. + - Issue the [Zowe CLI](../troubleshoot-check-your-zowe-version.md#zowe-cli) command to get the version number. - List of plug-ins installed and their version numbers. + - Issue the [Zowe CLI plug-ins](../troubleshoot-check-your-zowe-version.md#zowe-cli-plug-ins) command to get the version number(s). - Node.js and NPM versions installed. + - Issue the [Node.js and npm](../../troubleshoot/cli/use-individual-troubleshoot-commands.md#nodejs-and-npm) commands to get the version numbers. - List of environment variables in use. For instructions on using commands to collect this information, see [Gathering information to troubleshoot Zowe CLI](mustgather-cli.md) or [Using individual commands for troubleshooting](use-individual-troubleshoot-commands). diff --git a/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md b/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md index 920107d837..1c886af030 100644 --- a/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md +++ b/docs/troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md @@ -2,7 +2,7 @@ As part of the IBM Db2 Database Plug-in installation, the ODBC driver is automatically installed. The driver is required to connect to Db2, but installation can fail due to security restrictions. -When the ODBC driver installation fails, Zowe CLI displays an error message. To resolve this, the user can manually download and install the driver. +When the ODBC driver installation fails, Zowe CLI displays an error message. To resolve the error, the user can manually download and install the driver. **Symptom:** diff --git a/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md b/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md index 33462543fe..817e34f2ba 100644 --- a/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md +++ b/docs/troubleshoot/cli/use-individual-troubleshoot-commands.md @@ -10,15 +10,15 @@ Issue the following command: zowe -V ``` -The exact Zowe CLI version may vary depending upon if the `@latest` or `@zowe-v1-lts`, or `@zowe-v2-lts` version is installed. +The exact Zowe CLI version may vary depending upon if the `@latest`, `@zowe-v1-lts`, `@zowe-v2-lts`, or `@zowe-v3-lts` version is installed. -You can also display the version of your globally-installed Zowe CLI through the following NPM command: +Display the version of your globally-installed Zowe CLI through the following NPM command: ``` npm list -g @zowe/cli ``` -More information regarding versioning conventions for Zowe CLI and plug-ins is located in [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md). +More information regarding versioning conventions for Zowe CLI and plug-ins is located in [Zowe CLI Releases](https://github.com/zowe/zowe-cli/blob/master/RELEASE_HISTORY.md#zowe-v3x-lts-releases). ## Identify the currently installed versions of plug-ins @@ -28,24 +28,29 @@ Issue the following command: zowe plugins list ``` -The output describes version and the registry information. +The output includes the plug-in version number and registry information. ## Environment variables -The following settings are configurable via environment variables: +The following settings are configurable with environment variables: ### Log levels Environment variables are available to specify logging level and the CLI home directory. -**Important\!** Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For example, command line arguments will be logged when TRACE is set. +:::warning + +Setting the log level to `TRACE` or `ALL` might result in sensitive data being logged. For example, command line arguments will be logged when `TRACE` is set. + +::: For more information about logging and environment variables, see [Setting CLI log levels](../../user-guide/cli-configuringcli-ev.md#setting-cli-log-levels). ### CLI daemon mode -By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home directory resides on a network drive and has poor file performance. For information about how to change the location that the daemon uses, see [Setting CLI daemon mode properties](../../user-guide/cli-configuringcli-ev#setting-cli-daemon-mode-properties). +By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. One example of this would be when the home directory resides on a network drive and has poor file performance. In this case, changing the file location would improve performance time. +For information about how to change the location that the daemon uses, see [Setting CLI daemon mode properties](../../user-guide/cli-configuringcli-ev#setting-cli-daemon-mode-properties). ### Home directory @@ -59,26 +64,19 @@ The values for these variables can be **echo**ed. ## Home directory structure -![Home Directory](../../images/troubleshoot/cli/home_struc.png) +![Home Directory](../../images/troubleshoot/cli/home_struc_2.png) -### Location of logs +### Location and types of logs -There are two sets of logs to be aware of: +Zowe client logs are located in the `~/.zowe/logs` directory: -- Imperative CLI Framework log, which generally contains installation and configuration information. - -- Zowe CLI log, which contains information about interaction between CLI and the server endpoints. +- **Imperative CLI Framework log**, `imperative.log` + - Generally contains installation and configuration information +- **Zowe CLI log**, `zowe.log` + - Contains information about interaction between the CLI and the server endpoints Analyze these logs for any information relevant to your issue. -### Profile configuration - -The `profiles` folder stores connection information. - -**Important\!** The profile directory might contain "sensitive" information, such as your mainframe password. You should obfuscate any sensitive references before providing configuration files. - -**Note:** While the profile directory can still be used in Zowe CLI v2, it has been deprecated in favor of v2 [team configuration](https://docs.zowe.org/stable/user-guide/cli-using-using-team-profiles) files. - ## Node.js and npm Zowe CLI is compatible with the currently supported Node.js LTS versions. For an up-to-date list of supported LTS versions, see [Node.js.org](https://nodejs.org/en/download/releases/). @@ -90,28 +88,28 @@ npm --version ``` ### npm configuration -If you are having trouble installing Zowe CLI from an npm registry, gather your npm configuration to help identify issues with registry settings, global install paths, proxy settings, etc... +If you are having trouble installing Zowe CLI from an npm registry, gather your npm configuration to help identify issues with registry settings, global install paths, proxy settings, etc.: ``` npm config ls -l ``` ### npm log files -In case of errors, npm creates log files in the `npm_cache\_logs` location. To get the `npm_cache` location for a specific OS, run the following command: +In case of errors, npm creates log files in the `npm_cache\_logs` location. To get the `npm_cache` location for a specific OS: ``` npm config get cache ``` -By default, npm keeps only 10 log files, but sometimes more are needed. Increase the log count by issuing the following command: +By default, npm keeps only 10 log files, but sometimes more are needed. To increase the log count: ``` npm config set logs-max 50 ``` -This command increases the log count to 50, so that more log files will be stored on the system. Now you can run tests multiple times and not lose the log files. The logs can be passed to Support for analysis. + - This command increases the log count to 50, so that more log files will be stored on the system. Now you can run tests multiple times and not lose the log files. The logs can be passed to Support for analysis. -As the log files are created only when an npm command fails, but you are interested to see what is executed, you can increase the log level of npm. Issue the following command: +By default, log files are created only when an npm command fails. To see what is executed, increase the log level of npm: ``` npm config set loglevel verbose @@ -120,7 +118,16 @@ npm config set loglevel verbose - With this change, you can see all actions taken by npm on the stdout. If the command is successful, it still does not generate a log file. - The available log levels are: -"silent", "error", "warn", "notice", "http", "timing", "info", "verbose", "silly", and "notice". "Notice" is the default. + - `silent` + - `error` + - `warn` + - `notice` + - `http` + - `timing` + - `info` + - `verbose` + - `silly` + - `notice` -- Alternatively, you can pass `--loglevel verbose` on the command line, but this only works with npm related commands. By setting log level in the config, it also works when you issue some `zowe` commands that use npm (for example, `zowe plugins install @zowe/cics`). +- Alternatively, pass `--loglevel verbose` on the command line. This only works with npm related commands. By setting log level in the config, it also works when you issue some `zowe` commands that use npm (for example, `zowe plugins install @zowe/cics`). diff --git a/docs/troubleshoot/cli/zosmf-cli.md b/docs/troubleshoot/cli/zosmf-cli.md index 16c699ca7d..e016e4e660 100644 --- a/docs/troubleshoot/cli/zosmf-cli.md +++ b/docs/troubleshoot/cli/zosmf-cli.md @@ -1,14 +1,16 @@ # z/OSMF troubleshooting -The core command groups use the z/OSMF REST APIs which can experience any number of problems. + +The core command groups use the z/OSMF REST APIs, which can experience any number of problems. If you encounter HTTP 500 errors with the CLI, consider gathering the following information: -1. The IZU* (IZUSVR and IZUANG) joblogs (z/OSMF server) -2. z/OSMF USS logs (default location: /global/zosmf/data/logs - but may change depending on installation) +- The IZU* (IZUSVR and IZUANG) joblogs (z/OSMF server) +- z/OSMF USS logs (default location: /global/zosmf/data/logs, but may change depending on installation) If you encounter HTTP 401 errors with the CLI, consider gathering the following information: -1. Any security violations for the TSO user in SYSLOG +- Any security violations for the TSO user in SYSLOG + +## Alternate methods -## Alternative methods At times, it may be beneficial to test z/OSMF outside of the CLI. You can use the CLI tool `curl` or a REST tool such as "Postman" to isolate areas where the problem might be occurring (CLI configuration, server-side, etc.). Example `curl` command to `GET /zosmf/info`: diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md index 7e2a282a76..e2ad67a54c 100644 --- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md +++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md @@ -1,7 +1,7 @@ # Error Message Codes -The following error message codes may appear on logs or API responses. Use the following message code references and the corresponding reasons and actions to help troubleshoot issues. +The following error message codes may appear on logs or API responses. Use the following message code references and the corresponding reasons and actions to help troubleshoot issues. ## API mediation utility messages @@ -79,6 +79,18 @@ The following error message codes may appear on logs or API responses. Use the f Further connections will be queued until there is room in the connection pool. You may also increase the total connection limit via the gateway start-up script by setting the Gateway configuration for maxTotalConnections. +### ZWEAO400E + + The structure of the request is invalid: %s + + **Reason:** + + A value in the request is missing or contains an invalid value. + + **Action:** + + Fix the request and try again. + ### ZWEAO401E Unknown error in HTTPS configuration: '%s' @@ -91,6 +103,62 @@ The following error message codes may appear on logs or API responses. Use the f Start the service again in debug mode to get a more descriptive message. This error indicates it is not a configuration issue. +### ZWEAO402E + + The request has not been applied because it lacks valid authentication credentials. + + **Reason:** + + The accessed resource requires authentication. The request is missing valid authentication credentials or the token expired. + + **Action:** + + Review the product documentation for more details about acceptable authentication. Verify that your credentials are valid and contact security administrator to obtain valid credentials. + +### ZWEAO404E + + The service can not find the requested resource. + + **Reason:** + + **Action:** + +### ZWEAO405E + + The request method has been disabled and cannot be used for the requested resource. + + **Reason:** + + **Action:** + +### ZWEAO415E + + The media format of the requested data is not supported by the service, so the service has rejected the request. + + **Reason:** + + **Action:** + +### ZWEAO500E + + The service has encountered a situation it doesn't know how to handle. Please contact support for further assistance. More details are available in the log under the provided message instance ID + + **Reason:** + + **Action:** + +### ZWEAO503E + + The server is not ready to handle the request: %s + + **Reason:** + + The service is not ready to handle the request, it is being initialized or waiting for another service to start. + + **Action:** + + Repeat the request later. Please contact support for further assistance. + ## Common service core messages ### ZWEAM100E @@ -535,70 +603,70 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The string sent by the central Gateway was not recognized as a valid DER-encoded certificate in the Base64 printable form. + The string sent by the central Gateway was not recognized as valid DER-encoded certificate in the Base64 printable form. **Action:** - Ensure that forwarding of the client certificate is also enabled in the central Gateway. Check for any error messages from the central Gateway. + Ensure that the forwarding of client certificate is enabled also in the central Gateway. Check for any error messages from the central Gateway. ### ZWEAT501E Failed to get trusted certificates from the central Gateway. Unexpected response from %s endpoint. Status code: %s. Response body: %s **Reason:** - - The response status code is different from the expected 200 OK. - + + The response status code is different from expected 200 OK. + **Action:** - + Ensure that the parameter apiml.security.x509.certificatesUrl is correctly configured with the complete URL to the central Gateway certificates endpoint. Test the URL manually. ### ZWEAT502E Invalid URL specified to get trusted certificates from the central Gateway. Error message: %s - + **Reason:** - + The parameter apiml.security.x509.certificatesUrl is not correctly configured with the complete URL to the central Gateway certificates endpoint. - + **Action:** - + Ensure that the parameter apiml.security.x509.certificatesUrl is correctly configured. ### ZWEAT503E An error occurred during retrieval of trusted certificates from the central Gateway. Error message: %s - + **Reason:** - - The communication with the cloud gateway got interrupted or an error occurred while processing the response. - + + The communication with the gateway got interrupted or an error occurred during processing the response. + **Action:** - + Check the provided error message. Contact the support. ### ZWEAT504E Failed to parse the trusted certificates provided by the central Gateway. Error message %s - + **Reason:** - + The string sent by the central Gateway was not recognized as valid DER-encoded certificates in the Base64 printable form. - + **Action:** - + Check that the URL configured in apiml.security.x509.certificatesUrl responds with valid DER-encoded certificates in the Base64 printable form. ### ZWEAT505E Incoming request certificate is not one of the trusted certificates provided by the central Gateway. - + **Reason:** - - The Gateway performs an additional check of request certificates when the central Gateway forwards the incoming client certificate to the domain Gateway. This check may fail when the certificatesUrl parameter does not point to the proper central Gateway certificates endpoint. - + + The Gateway performs additional check of request certificates when the central Gateway forwards incoming client certificate to the domain Gateway. This check may fail when the certificatesUrl parameter does not point to proper central Gateway certificates endpoint. + **Action:** - + Check that the URL configured in apiml.security.x509.certificatesUrl points to the central Gateway and it responds with valid DER-encoded certificates in the Base64 printable form. ### ZWEAT601E @@ -673,40 +741,40 @@ The following error message codes may appear on logs or API responses. Use the f Provide a list of services for which this token will be valid -### ZWEAT607E +### ZWEAT608E - Body in the revoke request is not valid. + Error mapping between distributed and mainframe identity. Reason: %s %s **Reason:** - The request body is not valid + Unexpected error occurred when mapping between distributed and mainframe identity **Action:** - Use a valid body in the request. Format of a message: `{userId: string, (optional)timestamp: long}` or `{serviceId: string, (optional)timestamp: long}`. + Contact Broadcom support. -### ZWEAT608E +### ZWEAT609W - Error mapping between distributed and mainframe identity. Reason: %s %s + Mapping between distributed and mainframe identity failed. Reason: %s **Reason:** - Unexpected error occurred when mapping between distributed and mainframe identity + Mapping between distributed and mainframe identity failed. **Action:** - Contact Broadcom support. - -### ZWEAT609W +### ZWEAT610E - Mapping between distributed and mainframe identity failed. Reason: %s + Missing registry name configuration. **Reason:** - Mapping between distributed and mainframe identity failed. + The registry name configuration is required to correctly map distributed user name from the OIDC access token. **Action:** + Make sure that 'components.gateway.apiml.security.oidc.registry' is correctly set in 'zowe.yaml'. + ## Security client messages ### ZWEAS100E @@ -841,7 +909,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - When this error occurs it is necessary to get a new JWT token. + When this error occurs it is necessary to get a new JWT token. ### ZWEAS120E @@ -889,7 +957,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Log the message from the exception and then handle the exception based on the information provided there. + Log the message from the exception and then handle the exception based on the information provided there. ### ZWEAS400E @@ -1011,7 +1079,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support. + Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support. ### ZWEAD401E @@ -1023,7 +1091,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support. + Ensure that there are no network issues and that the Gateway was not restarted. If the problem reoccurs, contact Broadcom support. ### ZWEAD700W @@ -1061,7 +1129,7 @@ The following error message codes may appear on logs or API responses. Use the f Review the mentioned static API definition file for errors. Refer to the specific log message to determine the exact cause of the problem: - + - ServiceId is not defined in the file '%s'. The instance will not be created. Make sure to specify the ServiceId. - The `instanceBaseUrls` parameter of %s is not defined. The instance will not be created. Make sure to specify the `InstanceBaseUrl` property. - The API Catalog UI tile ID %s is invalid. The service %s will not have an API Catalog UI tile. Specify the correct catalog title ID. @@ -1103,29 +1171,25 @@ The following error message codes may appear on logs or API responses. Use the f ## Gateway service messages -### ZWEAG500E +### ZWEAG111E - Client certificate is missing in request. + The service has encountered a situation it doesn't know how to handle. Please contact support for further assistance. More details are available in the log under the provided message instance ID **Reason:** - No client certificate is present in the HTTPS request. - **Action:** - Properly configure client to send client certificate. +### ZWEAG501E -### ZWEAG700E - - No instance of the service '%s' found. Routing will not be available. + The connection is not secure. **Reason:** - The Gateway could not find an instance of the service from the Discovery Service. + AT-TLS is not properly configured. **Action:** - Check that the service was successfully registered to the Discovery Service and wait for Spring Cloud to refresh the routes definitions. + Review AT-TLS documentation and make sure your configuration is correct for this service. ### ZWEAG701E @@ -1329,7 +1393,7 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - The provided id is not valid under the conformance criteria. + The provided id is not valid under conformance criteria. **Action:** @@ -1341,15 +1405,15 @@ The following error message codes may appear on logs or API responses. Use the f **Reason:** - Metadata are not accessible. + Metadata aren't accessible **Action:** - Verify that the metadata are accessible and not empty. + Verify that the metadata are accessible and not empty ### ZWEAG719I - The service id provided is invalid: '%s' + The service is not conformant: %s **Reason:** @@ -1357,19 +1421,7 @@ The following error message codes may appear on logs or API responses. Use the f **Action:** - Verify the conformance criteria, provide valid service id. - -### ZWEAG100E - - Authentication exception: '%s' for URL '%s' - - **Reason:** - - A generic failure occurred during authentication. - - **Action:** - - Refer to the specific authentication exception details for troubleshooting. + Verify the conformance criteria. ### ZWEAG101E @@ -1383,42 +1435,6 @@ The following error message codes may appear on logs or API responses. Use the f Use the correct HTTP request method supported by the URL. -### ZWEAG102E - - Token is not valid - - **Reason:** - - The JWT token is not valid. - - **Action:** - - Provide a valid token. - -### ZWEAG103E - - The token has expired - - **Reason:** - - The JWT token has expired. - - **Action:** - - Obtain a new token by performing an authentication request. - -### ZWEAG104E - - Authentication service is not available at URL '%s'. Error returned: '%s' - - **Reason:** - - The authentication service is not available. - - **Action:** - - Make sure that the authentication service is running and is accessible by the URL provided in the message. - ### ZWEAG105E Authentication is required for URL '%s' @@ -1431,234 +1447,6 @@ The following error message codes may appear on logs or API responses. Use the f Provide valid authentication. -### ZWEAG106W - - Login endpoint is running in dummy mode. Use credentials '%s'/'%s' to log in. Do not use this option in the production environment. - - **Reason:** - - The authentication is running in dummy mode. - - **Action:** - - Ensure that this option is not being used in a production environment. - -### ZWEAG107W - - Incorrect value: apiml.security.auth.provider = '%s'. The authentication provider is not set correctly. The default 'zosmf' authentication provider is being used. - - **Reason:** - - An incorrect value of the apiml.security.auth.provider parameter is set in the configuration. - - **Action:** - - Ensure that the value of apiml.security.auth.provider is set either to 'dummy' if you want to use dummy mode, or to 'zosmf' if you want to use the z/OSMF authentication provider. - -### ZWEAG108E - - z/OSMF instance '%s' not found or incorrectly configured. Gateway is shutting down. - - **Reason:** - - The Gateway could not find the z/OSMF instance from the Discovery Service or it could not communicate with the provided z/OSMF instance. - - **Action:** - - Ensure that the z/OSMF instance is configured correctly and that it is successfully registered to the Discovery Service and that the API Mediation Layer can communicate with the provided z/OSMF instance. The default timeout is 5 minutes. On a slower system, add the variable components.gateway.apiml.security.jwtInitializerTimeout:... and the value in minutes into Zowe's configuration to override this value. - -### ZWEAG109E - - z/OSMF response does not contain field '%s'. - - **Reason:** - - The z/OSMF domain cannot be read. - - **Action:** - - Review the z/OSMF domain value contained in the response received from the 'zosmf/info' REST endpoint. - -### ZWEAG110E - - Error parsing z/OSMF response. Error returned: '%s - - **Reason:** - - An error occurred while parsing the z/OSMF JSON response. - - **Action:** - - Check the JSON response received from the 'zosmf/info' REST endpoint. - -### ZWEAG120E - - Invalid username or password for URL '%s' - - **Reason:** - - The username and/or password are invalid. - - **Action:** - - Provide a valid username and password. - -### ZWEAG121E - - Authorization header is missing, or the request body is missing or invalid for URL '%s' - - **Reason:** - - The authorization header is missing, or the request body is missing or invalid. - - **Action:** - - Provide valid authentication. - -### ZWEAS123E - - Invalid token type in response from Authentication service. - - **Reason:** - - Could not retrieve the proper authentication token from the Authentication service response. - - **Action:** - - Review your APIML authentication provider configuration and ensure your Authentication service is working. - -### ZWEAG130E - - Token is not valid for URL '%s' - - **Reason:** - - The token is not valid. - - **Action:** - - Provide a valid token. - -### ZWEAG131E - - No authorization token provided for URL '%s' - - **Reason:** - - No authorization token is provided. - - **Action:** - - Provide a valid authorization token. - -### ZWEAG150E - - SAF IDT generation failed. Reason: %s - - **Reason:** - - An error occurred during SAF verification. Review the reason in the error message. - - **Action:** - - Verify the Identity Token configuration. - -### ZWEAG151E - - SAF IDT is not generated because authentication or authorization failed. Reason: %s - - **Reason:** - - The user credentials were rejected during SAF verification. Review the reason in the error message. - - **Action:** - - Provide a valid username and password. - -### ZWEAG160E - - No authentication provided in the request - - **Reason:** - - The JWT token or client certificate was not provided with the request - - **Action:** - - Configure your client to provide valid authentication. - -### ZWEAG161E - - No user was found - - **Reason:** - - It was not possible to map provided token or certificate to the mainframe identity. - - **Action:** - - Ask your security administrator to connect your token or client certificate with your mainframe user. - -### ZWEAG162E - - Gateway service failed to obtain token. - - **Reason:** - - Authentication request to get token failed. - - **Action:** - - Contact your administrator. - -### ZWEAG163E - - Error occurred while parsing X509 certificate. - - **Reason:** - - %s - - **Action:** - - Configure your client to provide valid x509 certificate. - -### ZWEAG164E - - Error occurred while validating X509 certificate. %s - - **Reason:** - - X509 certificate cannot be validated or the certificate cannot be used for client authentication. - - **Action:** - - Configure your client to provide valid x509 certificate. - -### ZWEAG165E - - X509 certificate is missing the client certificate extended usage definition - - **Reason:** - - X509 certificate cannot be used for client authentication. - - **Action:** - - Configure your client to provide valid x509 certificate. - -### ZWEAG166E - - ZOSMF authentication scheme is not supported for this API ML instance. - - **Reason:** - - z/OSMF is not used as security provider for API ML. - - **Action:** - - Contact your administrator. - ### ZWEAG167E No client certificate provided in the request @@ -1671,180 +1459,57 @@ The following error message codes may appear on logs or API responses. Use the f Configure your client to provide valid certificate. -### ZWEAG168E - - Invalid authentication provided in request - - **Reason:** - - The JWT token or client certificate is not valid - - **Action:** - - Configure your client to provide valid authentication. - -### ZWEAG169E - - Unexpected response from the external identity mapper. Status: %s body: %s - - **Reason:** - - The external identity mapper request failed with Internal Error - - **Action:** - - Verify that ZSS is responding. - -### ZWEAG170E - - Error occurred while trying to parse the response from the external identity mapper. Reason: %s - - **Reason:** - - The external identity mapper failed when trying to parse the response - - **Action:** - - Verify that the response is valid. - -### ZWEAG171E - - Configuration error. Failed to construct the external identity mapper URI. Reason: %s - - **Reason:** - - Failed to construct the external identity mapper URI - - **Action:** - - Verify that the external identity mapper URL specified in the configuration is valid. - -### ZWEAT607E - - Body in the revoke request is not valid. - - **Reason:** - - The request body is not valid - - **Action:** - - Use a valid body in the request. Format of a message: `{userId: string, (optional)timestamp: long}` or `{serviceId: string, (optional)timestamp: long}`. - -### ZWEAG180E - - There was an error while reading webfinger configuration - - **Reason:** - - Webfinger provider contains incorrect configuration. - - **Action:** - - Contact the administrator to validate webfinger configuration in gateway service. - -### ZWEAG181W - - z/OSMF service '%s' is either not registered or not online yet. - - **Reason:** - - z/OSMF service may not be properly onboarded to API ML. - - **Action:** - - Verify if z/OSMF is up and registered to Discovery Service. - -### ZWEAG182E - - SSL Misconfiguration, z/OSMF is not accessible. - Message: %s - Please verify the following: - - CN (Common Name) and z/OSMF hostname match. - - The certificate is valid - - TLS version matches - - z/OSMF server certificate is trusted in Zowe's truststore - Enable debugging to see further details in stack trace. - - **Reason:** - - The z/OSMF connection is incorrectly configured. - - **Action:** - - Verify z/OSMF connection details. Verify z/OSMF can be accessed with HTTPS. Configure sslDebug to see SSL debugging messages. - -### ZWEAG183E - - z/OSMF internal error - - **Reason:** - - z/OSMF returned HTTP Status %s. - - **Action:** - - Review z/OSMF status and availability. - -### ZWEAG184E - - Could not connect to z/OSMF: %s - - **Reason:** - - There was a connection issue between the API Mediation Layer instance and z/OSMF. - - **Action:** - - Verify z/OSMF is running. Verify connectivity to z/OSMF from this instance. - -### ZWEAG185W +### ZWEAM400E - The change password endpoint has failed with code %s + Error initializing SSL Context: '%s' **Reason:** - The change password endpoint was not found. + An error occurred while initializing the SSL Context. **Action:** - Ensure PTF for APAR PH34912 is applied. (https://www.ibm.com/support/pages/apar/PH34912) + Refer to the specific message to identify the exact problem. + Possible causes include: + - Incorrect security algorithm + - The keystore is invalid or corrupted + - The certificate is invalid or corrupted -### ZWEAG186E +### ZWEAT403E - z/OSMF internal error attempting password change: %s + The user is not authorized to the target resource: %s **Reason:** - z/OSMF informed of an internal error. + The service has accepted the authentication of the user but the user does not have access rights to the resource. **Action:** - Verify z/OSMF error log. + Contact your security administrator to give you access. -### ZWEAG187W +### ZWEAG510E - The check of z/OSMF JWT authentication endpoint has failed. Using z/OSMF info endpoint as backup. + Request to the resource ended with unexpected status code. **Reason:** - z/OSMF JWT endpoint was not found. + The service did not respond properly. **Action:** - Ensure APAR PH12143 (https://www.ibm.com/support/pages/apar/PH12143) fix has been applied. + Verify that the target service is healthy. -### ZWEAG188W +### ZWESG100W - z/OSMF JWT builder endpoint call (%s) failed with %s + Cannot receive information about services on API Gateway with apimlId '%s' because: %s **Reason:** - z/OSMF returned an error code when calling JWT endpoint. + Cannot connect to the Gateway service. **Action:** - Review z/OSMF status. Contact your system administrator. + Make sure that the external Gateway service is running and the truststore of the both Gateways contain the corresponding certificate. ## API Catalog messages @@ -1908,6 +1573,18 @@ The following error message codes may appear on logs or API responses. Use the f Check the status of the message for more information and the health of the Discovery Service. +### ZWEAC105W + + API Documentation not retrieved for service '%s' due to communication error, %s + + **Reason:** + + Unable to fetch API documentation. + + **Action:** + + Make sure the service documentation url or server transport encoding is configured correctly. + ### ZWEAC700E Failed to update cache with discovered services: '%s' @@ -1983,7 +1660,7 @@ The following error message codes may appear on logs or API responses. Use the f - The URI is not valid. Ensure the service is providing a valid URL. - Not able to select a route for the URL of the specific service. The original URL is used. If necessary, check the routing metadata of the service. - The path of the service URL is not valid. Ensure the service is providing the correct path. - + ### ZWEAC706E @@ -2023,7 +1700,7 @@ The following error message codes may appear on logs or API responses. Use the f - The URI is not valid. Ensure the service is providing a valid URL. - Not able to select a route for the URL of the specific service. The original URL is used. If necessary, check the routing metadata of the service. - The path of the service URL is not valid. Ensure the service is providing the correct path. - + ### ZWEAC709E diff --git a/docs/troubleshoot/troubleshoot-apiml.md b/docs/troubleshoot/troubleshoot-apiml.md index b1279b8d7f..10f5303728 100644 --- a/docs/troubleshoot/troubleshoot-apiml.md +++ b/docs/troubleshoot/troubleshoot-apiml.md @@ -381,7 +381,7 @@ The API ML services are running but they are in the DOWN state and not working p See the following message for full exceptions. ``` -org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://USILCA32.lvn.broadcom.net:7553/eureka/apps/apicatalog": USILCA32.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net +org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://system.lvn.broadcom.net:7553/eureka/apps/apicatalog": system.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net .at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:732) ~Ýspring-web-5.0.8.RELEASE.jar!/:5.0.8.RELEASE¨ @@ -406,7 +406,7 @@ main¨ o.a.http.impl.client.DefaultHttpClient : Retrying connect to {s}->https The Zowe started task needs to run under a user with sufficient privileges. As a workaround, you can try to run the started task under the same user ID as z/OSMF (typically IZUSVR). -The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping USILCA32.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed to do network access. +The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping system.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed network access. You can fix it by setting up the security environment as described in the [Zowe documentation](../user-guide/configure-zos-system#configure-security-environment-switching). diff --git a/docs/troubleshoot/troubleshoot-check-your-zowe-version.md b/docs/troubleshoot/troubleshoot-check-your-zowe-version.md index c1bdb2b8b5..cd9c52015f 100644 --- a/docs/troubleshoot/troubleshoot-check-your-zowe-version.md +++ b/docs/troubleshoot/troubleshoot-check-your-zowe-version.md @@ -99,14 +99,6 @@ Find the version number of your Zowe release in the `manifest.json` file. An **Editor** tab displays the Zowe Explorer extension's marketplace details. The version number is located next to the Zowe Explorer extension's name. -### Zowe IntelliJ Plug-in +### Zowe Explorer plug-in for IntelliJ IDEA -1. Open the **File** menu and click **Settings**. - - The **Settings** window opens. -2. Click **Plugins**, then click **Installed** tab. - - A list of the installed extensions displays. -3. Search for, and select, `Zowe Explorer`. - - The Zowe Explorer marketplace details display on the right side of the window. The version number is located adjacent to the Zowe Explorer name. +See the [guide](./troubleshoot-intellij) for instructions. diff --git a/docs/troubleshoot/troubleshoot-intellij.md b/docs/troubleshoot/troubleshoot-intellij.md index 59f7107f2a..11ee63b389 100644 --- a/docs/troubleshoot/troubleshoot-intellij.md +++ b/docs/troubleshoot/troubleshoot-intellij.md @@ -1,10 +1,39 @@ -# Troubleshooting Zowe IntelliJ plug-in +# Troubleshooting Zowe Explorer plug-in for IntelliJ IDEA -As a Zowe IntelliJ plug-in user, you may encounter problems with how the plug-in functions. +As a Zowe Explorer plug-in for IntelliJ IDEA user, you may encounter problems both with the plug-in and the IntelliJ IDEA platform. Our support is open for any type of issues, related to this client-side component. See the next sections as an example of how to react on these problems. -Before reaching out for support, +## Troubleshooting IntelliJ IDEA platform issues -1. Is there already a GitHub issue (open or closed) that covers the problem? Check [Zowe IntelliJ plug-in Issues](https://github.com/zowe/zowe-explorer-intellij/issues). -2. Try searching using the Zowe Docs search bar. +Sometimes there could be inconveniences in how your IDE works. Before trying to fix any problem: +1. Go to **Help** > **About** -When necessary, you can use [the Slack channel](https://openmainframeproject.slack.com/archives/C020BGPSU0M) to reach the Zowe IntelliJ squad for assistance. +![Open About](../images/troubleshoot/intellij/intellij-troubleshoot-about.png) + +2. Click **Copy and Close** button and save this information somewhere for later + +![About dialog](../images/troubleshoot/intellij/intellij-troubleshoot-about_dialog.png) + +After that, there are a few steps that could be possibly done to fix the issue: +- **If the issue details are clear and IDE says, which component it is** - copy all the related information and send it to the component's developer +- **If the issue is unclear** - try to reload IDE / your computer. If the problem persists, try to reinstall the IDE or install the newest one supported LTS version of the IDE you are using +- **Ask for help or search for the related issue** - there is [an issue tracker](https://youtrack.jetbrains.com/issues/IDEA), related to the IntelliJ IDEA issues. Try to find something related or create a new one + +## Troubleshooting the plug-in + +If you have an issue with the plug-in: +1. Click the **gear** button, select **Plugins...** + +![Select plugins](../images/troubleshoot/intellij/intellij-go-to-plugins.png) + +2. Go to **Installed** tab, locate the plug-in, save **the exact version number** + +![Locate the plugin](../images/troubleshoot/intellij/intellij-find-plugin.png) + +After these actions, you have some options to try: +- **If the problem occurs for the plug-in in editor** - try to close the file you are editing, refresh the path and open it again +- **If the problem occurs with displaying a mask or a filter** - try to hit refresh on a working set or try to recreate a connection and a working set +- **If the problem occurs for some other issues related to Files Explorer or JES Explorer** - try to recreate a new connection, and a new working set for it +- **If the problem occurs for TSO Console** - try to reopen the session, try to recreate a session entirely +- **Other non-related issues, e.g. if the problem occurs for encoding or permissions or "Internal IDE error" notification appears constantly** - copy all the necessary information about the IDE you use and the plug-in's version, [create a new issue](https://github.com/zowe/zowe-explorer-intellij/issues) listing all the necessary information (like the steps to recreate the issue) as well as the versions, or search for the related issue in the repository and put a thumb-up for it, so we know that it should have a higher priority + +If you want a direct consulting, don't hesitate to visit our [Slack channel](https://openmainframeproject.slack.com/archives/C020BGPSU0M) and leave a message. Our team is always willing to help with any issues related to the platform or the plug-in, no matter the size of an issue or a question. diff --git a/docs/troubleshoot/troubleshoot-zowe-release.md b/docs/troubleshoot/troubleshoot-zowe-release.md index 65d73f72ad..ce99279140 100644 --- a/docs/troubleshoot/troubleshoot-zowe-release.md +++ b/docs/troubleshoot/troubleshoot-zowe-release.md @@ -1,29 +1,37 @@ # Understanding Zowe release versions ## Zowe releases -Zowe uses semantic versioning for its releases, also known as SemVer. Each release has a unique ID made up of three numbers that are separated by periods. +Zowe uses *semantic versioning* for its releases, also known as SemVer. In semantic versioning, each release has a unique ID made up of three numbers that are separated by periods: ``` .. ``` Each time a new release is created, the release ID is incremented. Each number represents the content change since the previous release. For example: + - `2.5.0` represents the fifth minor release since the first major release. - `2.5.1` represents the first patch to the `2.5.0` release. - `2.6.0` is the first minor release to be created after `2.5.1`. +To see the Zowe release schedule, see [Zowe PI Schedule and Releases](https://github.com/zowe/community/blob/master/Project%20Management/Schedule/Zowe%20PI%20%26%20Sprint%20Cadence.md). + ### Major release -A major release is required if changes are made to the public API and the code is no longer compatible with an earlier version. -When Zowe is version one, it is associated with the Zowe v1 [conformance program](../extend/zowe-conformance-program.md). Offerings that extend Zowe and achieve the Zowe v1 conformance badge will remain compatible with Zowe throughout its version 1 lifetime. A major release increment because of incompatibility is sometimes referred to as a "breaking" change. +Major releases are required for a *"breaking" change*, or a modification that requires updates to avoid disruptions in your applications. Major releases also can be used to indicate to the community a significant content update over and above what would be included in a minor release. + +#### Conformance programs -The first SMP/E build for Zowe v2 has a Functional Module ID (FMID) of AZWE002, which was created with content from the 2.0.0 release. Each major release will be its own SMP/E FMID where the last digit is updated, for example AZWE00V where V represents the major version. +Zowe V1 is associated with the Zowe V1 [conformance program](../extend/zowe-conformance-program.md). Offerings that extend Zowe and achieve the Zowe V1 conformance badge remain compatible with Zowe throughout its Version 1 lifetime. A major release increment because of incompatibility is sometimes referred to as a "breaking" change. -Subsequent minor and patch releases to V2 are delivered as SMP/E PTF SYSMODs. Because of the size of the content, two co-requisite PTFs are created for each Zowe release. +#### SMP/E builds -While Major releases are required for a "breaking" change, they also can be used to indicate to the community a significant content update over and above what would be included in a minor release. +Each major release has its own SMP/E Functional Module ID (FMID) in the format `AZWE00V`, where `V` represents the major version. The first SMP/E build for Zowe V3 has a Functional Module ID (FMID) of `AZWE003`, which was created with content from the 3.0.0 release. + +Subsequent minor and patch releases to V3 are delivered as SMP/E PTF SYSMODs. Because of the size of the content, two co-requisite PTFs are created for each Zowe release. ### Minor release -A minor release indicates that new functionality is added but the code is compatible with an earlier version. The Zowe community works on two-week sprints and creates a minor release at the end of these, typically once per month although the frequency might vary. + +A minor release indicates that new functionality is added but the code is compatible with an earlier version. ### Patch + A patch is usually reserved for a bug fix to a minor release. diff --git a/docs/troubleshoot/troubleshooting.md b/docs/troubleshoot/troubleshooting.md index 51b79229f5..c68c8995cb 100644 --- a/docs/troubleshoot/troubleshooting.md +++ b/docs/troubleshoot/troubleshooting.md @@ -8,28 +8,29 @@ When you run into some issues and are looking for troubleshooting tips, the foll 1. Search the error message or error code in your error log by using the Search bar in the [Zowe Docs site](https://docs.zowe.org/). If there is an existing solution, follow the instructions to troubleshoot. -![A screenshot to show how to search in github repo](../images/troubleshoot/search-bar-2.png) + ![A screenshot to show how to search in github repo](../images/troubleshoot/search-bar-2.png) 2. If no solution is available or the existing solutions cannot apply to your problem, you could search the keywords, error messages, or error code in the [Zowe GitHub repository](https://github.com/zowe). If you find a closed issue or pull request, try troubleshooting by using the information shared in the item's Conversation section. If the issue is still open, post your question or comment to prompt a discussion on your problem. -![A gif to show how to search in github repo](../images/troubleshoot/how-to-troubleshooting.gif) + ![A gif to show how to search in github repo](../images/troubleshoot/how-to-troubleshooting.gif) 3. If your problem is not solved, try the following options: -* Create an issue in the [Zowe GitHub repository](https://github.com/zowe) with a detailed description of the problem you have encountered. + * Create an issue in the [Zowe GitHub repository](https://github.com/zowe) with a detailed description of the problem you have encountered. -* Bring up your questions to the corresponding channels as shown below: + * Bring up your questions to the corresponding channels as shown below: - - [Zowe CLI Slack channel](https://openmainframeproject.slack.com/archives/CC8AALGN6) - - [Zowe API ML Slack channel](https://openmainframeproject.slack.com/archives/CC5UUL005) - - [Zowe Chat Slack channel](https://openmainframeproject.slack.com/archives/C03NNABMN0J) - - [Zowe Documentation Slack channel](https://openmainframeproject.slack.com/archives/CC961JYMQ) + - [Zowe API ML Slack channel](https://openmainframeproject.slack.com/archives/CC5UUL005) + - [Zowe Chat Slack channel](https://openmainframeproject.slack.com/archives/C03NNABMN0J) + - [Zowe CLI Slack channel](https://openmainframeproject.slack.com/archives/CC8AALGN6) + - [Zowe Documentation Slack channel](https://openmainframeproject.slack.com/archives/CC961JYMQ) + - [Zowe Explorer for VS Code channel](https://openmainframeproject.slack.com/archives/CUVE37Z5F) -* Reach out to your available Zowe support team for assistance. + * Reach out to your available Zowe support team for assistance. ## Known problems and solutions -Some common problems with Zowe are documented, along with their solutions or workarounds. If you have a problem with Zowe installation and components, review the problem-solution topics to determine whether a solution is available to the problem that you are experiencing. +Some common problems with Zowe are documented in the Zowe Docs **Troubleshoot** section, along with their solutions or workarounds. If you have a problem with Zowe installation and components, review the problem-solution topics to determine whether a solution is available to the problem that you are experiencing. You can also find error messages and codes, must-gathers, and information about how to get community support in these topics. @@ -40,19 +41,17 @@ You can also find error messages and codes, must-gathers, and information about - [Troubleshooting API Mediation Layer](troubleshoot-apiml.md) - [Troubleshooting Zowe Application Framework](./app-framework/app-troubleshoot.md) - ### Troubleshooting Zowe client-side components - [Troubleshooting Zowe CLI](./cli/troubleshoot-cli.md) - [Troubleshooting Zowe Explorer](./ze/troubleshoot-ze.md) - [Troubleshooting Zowe Chat](./zowe-chat-troubleshoot/troubleshooting.md) -- [Troubleshooting Zowe IntelliJ plug-in](troubleshoot-intellij.md) +- [Troubleshooting Zowe Explorer plug-in for IntelliJ IDEA](troubleshoot-intellij.md) ## Verifying a Zowe release's integrity -Following a successful install of a Zowe release, the Zowe runtime directory should contain the code needed to launch and run Zowe. If the contents of the Zowe runtime directory have been modified then this may result in unpredictable behavior. To assist with this Zowe provides the ability to validate the integrity of a Zowe runtime directory, see [Verify Zowe runtime directory](./verify-fingerprint.md) +Following a successful install of a Zowe release, the Zowe runtime directory should contain the code needed to launch and run Zowe. If the contents of the Zowe runtime directory have been modified, this may result in unpredictable behavior. To assist with this, Zowe provides the ability to validate the integrity of a Zowe runtime directory. See [Verify Zowe runtime directory](./verify-fingerprint.md) for more information. ## Understanding the Zowe release -Knowing which version of Zowe you are running might help you isolate the problem. Also, the Zowe community who helps you will need to know this information. For more information, see [Understanding the Zowe release](troubleshoot-zowe-release.md). - +Knowing which version of Zowe you are running might help you isolate the problem. Also, the Zowe version number is needed by the Zowe community enlisted to help you. To learn how to find the version number, see [Understanding the Zowe release](troubleshoot-zowe-release.md). diff --git a/docs/troubleshoot/ze/known-ze.md b/docs/troubleshoot/ze/known-ze.md index 6c8554de48..d810d41a92 100644 --- a/docs/troubleshoot/ze/known-ze.md +++ b/docs/troubleshoot/ze/known-ze.md @@ -87,7 +87,7 @@ Detail: File seems to be binary and cannot be opened as text. This is likely cau There is no solution or workaround at this time. -## Theia mainframe connection error +## Visual Studio Code mainframe connection error **Symptom:** @@ -101,6 +101,6 @@ When performing an action that requires a mainframe connection (such as searchin **Solution:** -In Theia settings, search for `proxy` and change the http.proxySupport setting to `off`, as in the following image: +In VS Code settings, search for `proxy` and change the http.proxySupport setting to `off`, as in the following image: ![Proxy Support set to off](../../images/ze/ZE-proxy-support-off.png) diff --git a/docs/troubleshoot/ze/troubleshoot-ze.md b/docs/troubleshoot/ze/troubleshoot-ze.md index 78153daf1a..3fb4d4fba2 100644 --- a/docs/troubleshoot/ze/troubleshoot-ze.md +++ b/docs/troubleshoot/ze/troubleshoot-ze.md @@ -10,12 +10,6 @@ As a Zowe Explorer user, you may encounter problems when using Visual Studio Cod - The Zowe Explorer and Visual Studio Code versions installed - See [Checking your Zowe version release number](../troubleshoot-check-your-zowe-version/#zowe-explorer-for-visual-studio-code) for information. - Node.js and NPM versions installed - - Whether you have Zowe CLI and the Secure Credential Store (SCS) Zowe CLI plug-in installed - - :::note - Zowe CLI V2 does not require the SCS plug-in to manage security. Security is now managed by Zowe CLI core functionality. - ::: - - Your operating system - Zowe Logs, which usually can be found in `C:\Users\userID\.vscode\extensions\zowe.vscode-extension-for-zowe-X.Y.Z\logs` @@ -27,7 +21,7 @@ Use [the Slack channel](https://app.slack.com/client/T1BAJVCTY/CUVE37Z5F) to rea ## Connection issues with Zowe Explorer -If you’re using Zowe Explorer at a site that uses an Internet proxy but cannot connect to a mainframe, ensure that the **Proxy Support** setting in Visual Studio Code is properly configured. Your system administrator can provide information on which option works best for your network environment. +If you are using Zowe Explorer at a site that uses an Internet proxy but cannot connect to a mainframe, ensure that the **Proxy Support** setting in Visual Studio Code is properly configured. Your system administrator can provide information on which option works best for your network environment. Note that Zowe Explorer cannot bypass this setting as it would circumvent the VS Code setting applied to all other extensions. @@ -46,10 +40,7 @@ System administrators can also add IP addresses, IP ranges, or DNS hostnames for A problem with a configuration file can make Zowe Explorer unable to read your configurations. -Zowe Explorer displays an error message advising it cannot read the configuration file when either: - -- A Zowe v1 profile is invalid. -- A Zowe v2 configuration file fails to load. +Zowe Explorer displays an error message advising it cannot read the configuration file when a Zowe V3 configuration file fails to load. Possible problems in the file could include a syntax error, or an invalid keyword or symbol. diff --git a/docs/troubleshoot/ze/ze-issues.md b/docs/troubleshoot/ze/ze-issues.md index 064ef9cd2b..912456edb4 100644 --- a/docs/troubleshoot/ze/ze-issues.md +++ b/docs/troubleshoot/ze/ze-issues.md @@ -1,6 +1,6 @@ # Raising a Zowe Explorer issue on GitHub -You can raise GitHub issues against [the Zowe Explorer repository](https://github.com/zowe/zowe-explorer-vscode/issues). It is suggested that you use either the bug or feature request. +When necessary, raise a GitHub issue in the [Zowe Explorer for Visual Studio Code repository](https://github.com/zowe/zowe-explorer-vscode/issues). It is suggested that you use either the bug or feature request. ## Raising a bug report diff --git a/docs/troubleshoot/ze/ze-known-limits.md b/docs/troubleshoot/ze/ze-known-limits.md index e9e6fbd16b..2bdd5f15e0 100644 --- a/docs/troubleshoot/ze/ze-known-limits.md +++ b/docs/troubleshoot/ze/ze-known-limits.md @@ -1,24 +1,24 @@ # Known Zowe Explorer limitations -### Mismatched credentials when using Zowe Explorer and Zowe CLI +## Mismatched credentials when using Zowe Explorer and Zowe CLI -#### **Limitation** +### Limitation Mismatching credentials can potentially lock you out from using Zowe CLI and Zowe Explorer in Visual Studio Code with either Windows Subsystem for Linux (WSL) or Remote Secure Shell (SSH). -WSL allows developers to run a Linux environment on Windows without the need for a separate virtual machine or dual booting. When using Zowe Explorer with WSL, two parallel processes take place: VS Code runs on the Windows operating system, while code execution and tooling happen within the Linux environment. +WSL allows developers to run a Linux environment on Windows without the need for a separate virtual machine or dual booting. When using Zowe Explorer with WSL, two parallel processes take place: VS Code runs on the Windows operating system, while code execution and tooling happen within the Linux environment. -With Remote SSH, the network protocol provides users with a secure connection to a remote computer. When using this protocol with Zowe Explorer, you can securely connect to a remote machine or a remote development environment. +With Remote SSH, the network protocol provides users with a secure connection to a remote computer. When using this protocol with Zowe Explorer, you can securely connect to a remote machine or a remote development environment. Both WSL and Remote SSH provide more tools for mainframe developers, but they also have limitations when it comes to credentials. -Authentication information used in Zowe Explorer — such as usernames and passwords, SSH keys, API Mediation Layer tokens — resides on the developer’s local machine, not the Linux environment or the remote server or virtual machine. This is because credential storage is managed by VS Code, which stores them using the host's operating system credential manager. +Authentication information used in Zowe Explorer — such as usernames and passwords, SSH keys, and API Mediation Layer tokens — resides on the developer’s local machine, provided the developer is not connected to a remote environment through VS Code. If you are connected to a remote environment through VS Code, your secure credentials are stored on the remote system. Using the VS Code integrated terminal with virtual machines does not include access to the credentials stored by Zowe Explorer in the local machine. Zowe CLI, for example, is not able to retrieve credentials saved on a developer’s PC when accessing the mainframe. Instead, Zowe CLI attempts to use any credentials stored in the virtual machine. This can lead to confusion and inconsistencies when authenticating and accessing resources. -#### **Workaround** +### Workaround It is crucial to ensure that credentials are carefully managed between the local machine and the remote server to maintain proper authentication. diff --git a/docs/user-guide/ZE-install-checklist.md b/docs/user-guide/ZE-install-checklist.md new file mode 100644 index 0000000000..5f0a4e74f8 --- /dev/null +++ b/docs/user-guide/ZE-install-checklist.md @@ -0,0 +1,34 @@ +# Zowe Explorer installation checklist + +This checklist outlines the required steps for a first-time installation of Zowe Explorer. + +:::info Required roles: systems administrator, devops architect, security administrator, systems programmer +::: + +The checklist includes a brief description of the steps required for installation of Zowe Explorer. The checklist also identifies the roles that are typically required to complete the step, which enables the pre-installation planning team to focus on the tasks for which they are responsible. + +For a printable version of this checklist, click here. + +## Preparing for installation + +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +|[Addressing Zowe Explorer system requirements](../getting-started/ZE-system-reqs.md) | Check the following items:
  • your operating system
  • development environments
| Systems administrator | 15 min. | +| (Optional) [Configuring z/OSMF](../user-guide/cli-install-configure-zosmf.md) | Confirm that z/OS components, region sizes, and user IDs meet Zowe Explorer requirements.
Required step when using a z/OSMF profile connection. | Systems programmer | 40 min. | +| (Optional) [Configuring z/OSMF security](../user-guide/cli-install-configure-zosmf-security.md) | Configure security for:
  • SAF access to REST endpoints
  • z/OS console REST interface
  • z/OS data set and file REST services
Required step when using a z/OSMF profile connection.| Security administrator| 50 min. | +| (Optional) [Installing Zowe CLI](../user-guide/cli-install-cli-checklist) | Set up team configuration with Zowe CLI to communicate with the mainframe. | Systems administrator | 60 min. | + +## Installing Zowe Explorer + +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +| [Installing Zowe Explorer](../user-guide/ze-install#installing-zowe-explorer) and [Zowe Explorer extensions](../user-guide/ze-install.md#installing-zowe-explorer-extensions) | Install Zowe Explorer and Zowe Explorer extensions from the Visual Studio Marketplace or with a `VSIX` file. | Systems administrator and/or developer | 10 min. | +| [Updating Zowe Explorer and Zowe Explorer extensions](../user-guide/ze-install.md#updating-zowe-explorer-and-zowe-explorer-extensions) | Updates are done automatically unless otherwise specified. | Systems administrator and/or developer | 10 min. | + +## Configuring Zowe Explorer + +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +| [Creating Zowe Explorer profiles](../user-guide/ze-profiles.md) | Connect to the mainframe with a Zowe Explorer profile. | Systems administrator | 30 min. | +| [Configuring Zowe Explorer](../user-guide/ze-install-configuring-ze) | Save your preferences as settings. | Developer | 30 min. | +| [Verifying your Zowe Explorer installation](../user-guide/ze-install-verify-your-installation.md) | Confirm the connection to z/OSMF. | Systems administrator and/or DevOps architect | 15 min. | diff --git a/docs/user-guide/cli-using-team-configuration-application-developers.md b/docs/user-guide/_cli-using-team-configuration-application-developers.md similarity index 53% rename from docs/user-guide/cli-using-team-configuration-application-developers.md rename to docs/user-guide/_cli-using-team-configuration-application-developers.md index 670a4718e9..e5fa266ed4 100644 --- a/docs/user-guide/cli-using-team-configuration-application-developers.md +++ b/docs/user-guide/_cli-using-team-configuration-application-developers.md @@ -1,4 +1,4 @@ -# Team configuration for application developers +# Configuration for application developers As an application developer or Zowe CLI user, you want to manage your connection details efficiently and in one location. @@ -6,25 +6,35 @@ That could mean relying on a team configuration file, or creating your own *user To create your own user configuration, start with a global team configuration file that you have created or was provided to you. In this way, a single global configuration can become the basis for multiple user-specific configurations that are created with modifications tailored to particular requirements. +You can also edit an existing team configuration for additional mainframe services and other profiles. + ## Initializing user configuration -As an application developer, you can optionally generate a *user* configuration file that overrides the values defined in the global `zowe.config.json` file. (See [How Zowe CLI uses configurations](../user-guide/cli-using-understand-profiles-configs.md) for more information.) +As an application developer, you can choose to generate a *user* configuration file that overrides the values defined in the global `zowe.config.json` file. (See [How Zowe CLI uses configurations](../user-guide/cli-using-understand-profiles-configs.md) for more information.) -Follow these steps: +To generate a user configuration file: -1. To generate a team configuration file (`zowe.config.json`) that you can use globally, issue the following command: +1. Open a command line prompt and issue the following command to generate a global team configuration file: ``` zowe config init --global-config ``` -2. To generate the global user profile configuration file `zowe.config.user.json`, issue the following command: + The configuration file `zowe.config.json` is created in the `ZOWE_CLI_HOME` directory. + +2. Respond to subsequent prompts to create connection profiles for mainframe services. **[correct?]** + +3. Generate the global user configuration file: ``` zowe config init --global-config --user-config ``` - In your *user* file (`zowe.config.user.json`), observe that the profiles do not have properties and the "defaults" object is empty, as illustrated in the following example. Use a text editor or IDE (such as Visual Studio Code) to add your connection details as properties here to override properties in `zowe.config.json`, or to add new connections. + The configuration file `zowe.config.user.json` is created in the `ZOWE_CLI_HOME` directory. **[are there any prompts the user needs to answer? or if the config file created immeately after the command?]** + +4. Use a text editor or IDE (such as Visual Studio Code) to add your connection details as properties in the `zowe.config.user.json` file to either override the same properties in `zowe.config.json`, or to add new connection details. + + When created initially, the *user* configuration file contains profiles (copied from the global team configuration file) **[is the paranthetical correct?]** with no properties and the `defaults` object is empty. Refer to the following example. ```{ "$schema": "./zowe.schema.json", @@ -58,15 +68,13 @@ Follow these steps: ## Editing team configurations -After creating a team configuration file, you can define additional mainframe services, and other profiles, to the configuration. - -Follow these steps: +To define additional mainframe services and other profiles in an existing team configuration file: -1. Open the `~/.zowe/zowe.config.json` file in a text editor or an IDE (such as Visual Studio Code) on your computer. +1. Open the `~/.zowe/zowe.config.json` file in a text editor or an IDE (such as Visual Studio Code) on your computer. -2. Edit the file by adding or modifying the profiles stored there. +2. Edit the file by adding to or modifying the profiles stored there. - The profiles object contains connection and other frequently needed information for accessing various services, as in the following example: + The profiles object contains connection and other frequently needed information for accessing various mainframe services **[is "mainframe" correct?]**, as in the following example: ``` { diff --git a/docs/user-guide/cli-using-team-configuration-team-leaders.md b/docs/user-guide/_cli-using-team-configuration-team-leaders.md similarity index 79% rename from docs/user-guide/cli-using-team-configuration-team-leaders.md rename to docs/user-guide/_cli-using-team-configuration-team-leaders.md index c275d23cbc..7a45d35663 100644 --- a/docs/user-guide/cli-using-team-configuration-team-leaders.md +++ b/docs/user-guide/_cli-using-team-configuration-team-leaders.md @@ -1,23 +1,24 @@ -# Team configuration for team leaders +# Configuration for team leaders -As a Dev-Ops advocate or team leader, you can share team profiles with your team members so that they can easily access mainframe services. +As a team leader or Dev-Ops advocate, you can share the profiles stored in a team configuration file with your team members so that they can easily access mainframe services. -## Sharing team configuration files +## Reasons to share team configuration files -As a DevOps advocate or team leader, you might want to share a team configuration *globally* in the following scenarios: +Consider sharing a team configuration *globally* in the following scenarios: - You want to share profiles with application developers so that they can work with a defined set of mainframe services. The recipient of the file places it in their local `~/.zowe` folder manually before issuing CLI commands. - You want to add the profiles to your project directory in a software change management (SCM) tool, such as GitHub. When you store the profiles in an SCM, application developers can pull the project to their local computer and use the defined configuration. Zowe CLI commands that you issue from within the project directory use the configuration scheme for the project automatically. - You want to enable test automation in a CI/CD pipeline, which lets your pipelines make use of the project configuration. For information about how to share team configuration files, see [Sharing team configuration files](../user-guide/cli-using-sharing-team-config-files.md). -## Profile scenarios -The following topics describe various profile scenarios that DevOps advocates (team leaders) can share with their teams, and application developers that function as DevOps advocates can create. +## Profile use cases -### Access to one or more LPARs that contain services that share the same credentials +The following topics describe various profile scenarios that team leaders can share with their teams, and application developers that function as DevOps advocates can create. -The following example illustrates that the settings are using nested profiles to access multiple services directly on one or more LPARs that share the same username and password. +### Accessing LPARs that contain services that share the same credentials + +In the following configuration, nested profiles use the credentials from the same base profile to access services directly on multiple LPARs: **[is this explanation correct?]** ``` { @@ -83,9 +84,9 @@ The following example illustrates that the settings are using nested profiles to "autoStore": true } ``` -### Access to one or more LPARs contain services that do not share the same credentials +### Accessing LPARs that contain services that do not share the same credentials -The following example illustrates that the settings are using nested profiles to access multiple services directly on one or more LPARs that do not share (different) user names and passwords. +In the following configuration, nested profiles use the credentials from different service profiles to access services directly on multiple LPARs. ``` { @@ -156,9 +157,9 @@ The following example illustrates that the settings are using nested profiles to } ``` -### Access to LPARs that access services through one API Mediation Layer +### Accessing LPARs that access services through one API Mediation Layer -The following example illustrates that the settings access multiple services using the API ML where multi-factor authentication (MFA) or single sign-on (SSO) is achievable using token-based authorization. +In the following configuration, services are accessed through the API ML (where multi-factor authentication (MFA) or single sign-on (SSO) is achievable) using token-based authorization stored in a base profile. ``` { @@ -205,9 +206,9 @@ The following example illustrates that the settings access multiple services usi } ``` -### Access to LPARs that access services through one API Mediation Layer using certificate authentication +### Accessing LPARs that access services through one API Mediation Layer using certificate authentication -Access LPARs containing multiple services through API Mediation Layer with certificate authentication +In the following configuration, services are accessed through the API ML using certificate authentication stored in a base profile. ``` { diff --git a/docs/user-guide/cli-using-test-zosmf-connection.md b/docs/user-guide/_cli-using-test-zosmf-connection.md similarity index 100% rename from docs/user-guide/cli-using-test-zosmf-connection.md rename to docs/user-guide/_cli-using-test-zosmf-connection.md diff --git a/docs/user-guide/install-cli-via-proxy.md b/docs/user-guide/_install-cli-via-proxy.md similarity index 95% rename from docs/user-guide/install-cli-via-proxy.md rename to docs/user-guide/_install-cli-via-proxy.md index d7631c6ff1..bc5e9fe017 100644 --- a/docs/user-guide/install-cli-via-proxy.md +++ b/docs/user-guide/_install-cli-via-proxy.md @@ -2,6 +2,9 @@ ​ This topic describes how to install Zowe CLI using the NPM install command when you are working behind a proxy server. Use this installation method when your site blocks access to public npm. +:::info**Required role:** systems administrator +::: + You can install Zowe CLI from an online registry via proxy on Windows, macOS, or Linux operating systems: * This method requires access to an internal server that will allow you to connect to the appropriate registries. For other installation methods, see Installing CLI. @@ -48,7 +51,7 @@ You can install Zowe CLI from an online registry via proxy on Windows, macOS, or b. Issue the following command to install all of the plug-ins: ``` - zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/ims-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts + zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts ``` Zowe CLI is installed. diff --git a/docs/user-guide/_ze-install copy.md b/docs/user-guide/_ze-install copy.md new file mode 100644 index 0000000000..26bc3ee2bd --- /dev/null +++ b/docs/user-guide/_ze-install copy.md @@ -0,0 +1,139 @@ +# Visual Studio Code (VS Code) Extension for Zowe + +codecov +slack + +The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs. + +Install the extension directly to [VSCode](https://code.visualstudio.com/) to enable the extension within the GUI. Working with data sets and USS files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI experience. The extension provides the following benefits: + +- Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe. +- Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe. +- Provides a more streamlined way to access data sets, USS files, and jobs. +- Lets you create, edit, and delete Zowe CLI `zosmf` compatible profiles. + +**Note:** Zowe Explorer is a subcomponent of [Zowe](https://zowe.org/home/). The extension demonstrates the potential for plug-ins powered by Zowe. + +## Software Requirements + +Ensure that you meet the following prerequisites before you use the extension: + +- Get access to z/OSMF. +- Install [Visual Studio Code](https://code.visualstudio.com/). +- Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](https://docs.zowe.org/stable/user-guide/systemrequirements-zosmf#z-os-requirements). +- Create a Zowe CLI `zosmf` profile so that the extension can communicate with the mainframe. +- For development, install [Node.js](https://nodejs.org/en/download/) v14.0 or later. + +### Profile notes: + +- You can use existing Zowe CLI `zosmf` profiles created with Zowe CLI v.2.0.0 or later. + +- Zowe CLI `zosmf` profiles that are created in Zowe Explorer can be interchangeably used in Zowe CLI. + +- *Optionally*, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see [Working with Zowe Explorer profiles](https://docs.zowe.org/stable/user-guide/ze-profiles#working-with-zowe-explorer-profiles). + +## Installing Zowe Explorer + +Use the following steps to install Zowe Explorer: + +1. Address [the software requirements](#software-requirements). +2. Open Visual Studio Code, and navigate to the **Extensions** tab on the **Activity Bar**. +3. Type `Zowe Explorer` in the **Search** field. + + Zowe Explorer appears in the list of extensions in the **Side Bar**. + +4. Click the green **Install** button to install the extension. +5. Restart Visual Studio Code. + +The extension is now installed and available for use. + +* **Note:** For information about how to install the extension from a `VSIX` file and run system tests on the extension, see the [Developer README](https://github.com/zowe/vscode-extension-for-zowe#build-locally). + +You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data sets. + + + + + +## Configuring Zowe Explorer + +Configure Zowe Explorer in the settings file of the extension. + +To access the extension settings, follow these steps: + +1. Click the **Settings** icon at the bottom of the **Activity Bar**. + +2. Select the **Settings** option. +3. Open the **Extension** option listed in the **Commonly Used** menu. +4. Select **Zowe Explorer** to access its settings. +5. Scroll the list to find the setting that needs modification. + +### Modifying creation settings for data sets, USS files, and jobs + +Follow these steps: + +1. In Zowe Explorer settings, scroll to a data set, USS file, or job setting type. +2. Click the setting's corresponding **Edit in settings.json** link. + + This opens the `settings.json` file in an **Editor** tab. (The suggestions widget also opens if the functionality is enabled.) + +3. Edit the settings in the file as needed. +4. Save the file to keep changes. + + ![Configure Zowe settings](../images/ze/ZE-Configuration2.gif) + +### Modifying temporary file location settings + +Change the default folder location where temporary files are stored with the following steps: + + 1. Navigate to Zowe Explorer settings. + 2. Under the data set, USS, or jobs settings that you want to edit, click the **Edit in settings.json** link. + 3. Modify the following definition in the file: + + ```json + "zowe.files.temporaryDownloadsFolder": { + "folderPath": "/path/to/directory" + } + ``` + + Replace **/path/to/directory** with the new folder location. + +4. Save the file to keep the change. + +### Modifying the `Secure Credentials Enabled` setting + +When environment conditions do not support the Zowe CLI built-in Credential Manager, change the `Secure Credentials Enabled` setting with the following steps: + + 1. Navigate to Zowe Explorer settings. + 2. Scroll to **Security: Secure Credentials Enabled**. + 3. Deselect the checkbox to disable secure credentials. + + When disabled, if the `autoStore` setting in the `zowe.config.json` file is set to *true*, z/OS credentials are stored as text in the file. + + If the `autoStore` setting is set to *false*, you are prompted for the missing credentials in Visual Studio Code. These are stored and used for the duration of the session. + +### Setting confirmation requirements for submitting jobs + +Submitting the wrong job can risk potential problems on your server. This can happen when the user enters the wrong job or inadvertently selects the **Submit Jobs** option. + +To help prevent this, enable the option to require confirmation before submitting a job. Once enabled, a dialog window asking for user confirmation displays when **Submit Jobs** is selected. + +![Confirm Submit Job](../images/ze/ZE-SubmitJobConfirm.gif) + +To configure confirmation settings for submitting a job, follow these steps: + +1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. + +2. Select the **User** or **Workspace** tab, depending on the settings you want to update. +3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**. +4. In the **Jobs: Confirm Submission** section, open the drop-down menu to select a different confirmation setting. + - If enabled, a confirmation dialog displays when a job matching the selected option is submitted. + +## Relevant Information + +In this section you can find useful links and other information relevant to Zowe Explorer that can improve your experience with the extension. + +- For information about how to develop for Eclipse Theia, see [Theia README](https://github.com/zowe/vscode-extension-for-zowe/wiki/Developing-for-Theia). +- For information about how to create a VSCode extension for Zowe Explorer, see [VSCode extensions for Zowe Explorer](https://github.com/zowe/vscode-extension-for-zowe/wiki/Extending-Zowe-Explorer). + +- Visit the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) for questions and general guidance. diff --git a/docs/user-guide/address-network-requirements.md b/docs/user-guide/address-network-requirements.md index 7ea8cd452a..55d7060aed 100644 --- a/docs/user-guide/address-network-requirements.md +++ b/docs/user-guide/address-network-requirements.md @@ -18,8 +18,7 @@ For more information about variable names in the following table, see the [Zowe | 7555 | zowe.components.caching-service.port | Port of the caching service that is used to share state between different Zowe instances in a high availability topology. | 7556 | zowe.components.app-server.port | The Zowe Desktop (also known as ZLUX) port used to log in through web browsers. | 7557 | zowe.components.zss.port | Z Secure Services (ZSS) provides REST API services to ZLUX, used by the File Editor application and other ZLUX applications in the Zowe Desktop. -| 7558 | zowe.components.jobs-api.port | Port of the service that provides REST APIs to z/OS jobs used by the JES Explorer. -| 7559 | zowe.components.files-api.port | Port of the service that provides REST APIs to MVS and USS file systems. +| 7558 | zowe.components.zaas.port | | N/A | zowe.components.explorer-jes | Port of the JES Explorer GUI for viewing and working with jobs in the Zowe Desktop. | N/A | zowe.components.explorer-mvs | Port of the MVS Explorer GUI for working with data sets in the Zowe Desktop. | N/A | zowe.components.explorer-uss | Port of the USS Explorer GUI for working with USS in the Zowe Desktop. diff --git a/docs/user-guide/address-storage-requirements.md b/docs/user-guide/address-storage-requirements.md index 52b4b2e062..136537681b 100644 --- a/docs/user-guide/address-storage-requirements.md +++ b/docs/user-guide/address-storage-requirements.md @@ -22,6 +22,5 @@ Component name | Memory usage Gateway service | 256MB Discovery service | 256MB API Catalog | 512MB -Metrics service | 512MB Caching service | 512MB diff --git a/docs/user-guide/api-mediation-change-password-via-catalog.md b/docs/user-guide/api-mediation-change-password-via-catalog.md index c05cf3b24a..1d8ab29056 100644 --- a/docs/user-guide/api-mediation-change-password-via-catalog.md +++ b/docs/user-guide/api-mediation-change-password-via-catalog.md @@ -1,6 +1,6 @@ # Changing an expired password via API Catalog -In case of expiration of a mainframe password, the API Catalog offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message: +In case of expiration of a mainframe password, the API Catalog, when using SAF as authentication provider offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message: api refresh error diff --git a/docs/user-guide/api-mediation-metrics-service.md b/docs/user-guide/api-mediation-metrics-service.md deleted file mode 100644 index 2dc6f192c0..0000000000 --- a/docs/user-guide/api-mediation-metrics-service.md +++ /dev/null @@ -1,30 +0,0 @@ -# Using Metrics Service (Technical Preview) - -As a system administrator, use the Metrics Service to view information about the acitivty of services running in the API Mediation Layer. -Currently, only HTTP metrics are displayed for core API Mediation Layer services. - -In order for the Metrics Service to run, you must set `components.metrics-service.enabled` in `zowe.yaml` to `true`. Additionally, for each APIML service you want to have metrics collected for, you must set `components..apiml.metrics.enabled` set to `true` in `zowe.yaml`, or `configs.apiml.metrics.enabled` set to `true` in the service's manifest. When metrics are enabled for the API Gateway, the Gateway homepage displays a link to the Metrics Service dashboard. The dashboard is available at `https://{gateway_host}:{gateway_port}/metrics-service/ui/v1`.` - -## API Mediation Layer Metrics Service Demo Video - -Watch this [video](https://youtu.be/KkuE6xADxPk) to see a demo of the Metrics Service. - - - -## View HTTP Metrics in the Metrics Service Dashboard - -Use the Metrics Service to view HTTP metrics such as number of requests, response times, and error rates. The below image describes the information provided in the Metrics Service dashboard. - -discoverable client api v1 - -To view the HTTP metrics for a service, select the corresponding tab in the Metrics Service dashboard. Metrics are displayed for each endpoint of a service, aggregated from all service instances. - -**Example:** - -discoverable client api v1 - -Metrics are provided on a near real-time basis, so the display shows the current activity of the selected service. At this time there is no persistence for this information. - -Service instances expose their HTTP metrics at `https://:/application/hystrix.stream` using the Server-Sent-Events protocol. The Metrics Service collects these streams and aggregates them across service instances before displaying. - -**Note:** At this time, the `/application/hystrix.stream` endpoint for a service does not require authentication if metrics are enabled for that service. If metrics for that service are not enabled, `/application/hystrix.stream` is protected by authentication. diff --git a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md b/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md deleted file mode 100644 index 97d9256a24..0000000000 --- a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md +++ /dev/null @@ -1,7 +0,0 @@ -# API Gateway REST APIs - -The API Gateway provides different functionalities and implements several REST APIs to leverage these functionalities: - -* [Update User Password](api-mediation-update-password.md) -* [JWT token refresh endpoint](api-mediation-jwt-token-refresh.md) -* [Personal Access Tokens](../api-mediation/authenticating-with-personal-access-token) diff --git a/docs/user-guide/api-mediation/api-mediation-caching-service.md b/docs/user-guide/api-mediation/api-mediation-caching-service.md index 6078edb29d..448dc205f7 100644 --- a/docs/user-guide/api-mediation/api-mediation-caching-service.md +++ b/docs/user-guide/api-mediation/api-mediation-caching-service.md @@ -1,13 +1,14 @@ # Using the Caching Service -As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless in two ways: +As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless by using following backends: -- Using VSAM to store key/value pairs for production - -- Using InMemory +- Using Infinispan that is part of Caching Service +- Using Redis running off-platform +- \{Deprecated\} Using VSAM +- \{Development Use Only\} Using InMemory :::note -In the current implementation of the Caching Service, VSAM is required for the storage of key/value pairs for production, as VSAM is a native z/OS solution for storing key/value pairs. +In the current implementation of the Caching Service, Infinispan is recommended for the storage of key/value pairs for production, as it has the best performance characteristics without additional services. ::: The Caching Service is available only for internal Zowe applications, and is not exposed to the internet. The Caching service supports a hot-reload scenario in which a client service requests all available service data. @@ -48,7 +49,7 @@ Infinispan is a storage solution that can also run on the z/OS platform. It can For more information about the Infinispan storage access method, see [Using Infinispan as a storage solution through the Caching service](../../extend/extend-apiml/api-mediation-infinispan.md). -### VSAM +### VSAM (deprecated) VSAM can be used to organize records into four types of data sets: key-sequenced, entry-sequenced, linear, or relative record. Use VSAM as the storage solution for production. VSAM is used primarily for applications and is not used for source programs, JCL, or executable modules. ISPF cannot be used to display or edit VSAM files. @@ -60,7 +61,6 @@ Redis is a common storage solution that runs outside of the z/OS platform. It ca For more information about the Redis storage access method, see [Using Redis as a storage solution through the Caching Service](../../extend/extend-apiml/api-mediation-redis.md). - ### InMemory The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production. diff --git a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md index 8b19c9c82d..9e51f00d83 100644 --- a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md +++ b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md @@ -4,17 +4,17 @@ Zowe supports management of multiple tenants, whereby different tenants can serv * [Overview of Central and Domain API MLs](#overview-of-central-and-domain-api-mls) * [Multitenancy component enablement settings](#multitenancy-component-enablement-settings) -* [Onboarding Domain Gateways to the central Cloud Gateway](#onboarding-domain-gateways-to-the-central-cloud-gateway) +* [Onboarding Domain Gateways to the central Gateway](#onboarding-domain-gateways-to-the-central-gateway) * [Dynamic Onboarding (recommended) for Domain Gateways](#dynamic-onboarding-recommended-for-domain-gateways) * [Static Onboarding for Domain Gateways (deprecated)](#static-onboarding-for-domain-gateways-deprecated) -* [Onboarding a Domain Cloud-Gateway service to Central Discovery service](#onboarding-a-domain-cloud-gateway-service-to-the-central-discovery-service) +* [Onboarding a Domain Gateway service to Central Discovery service](#onboarding-a-domain-gateway-service-to-the-central-discovery-service) * [Dynamic Configurations to the Central Discovery Service](#dynamic-configurations-to-the-central-discovery-service) * [Dynamic configuration: YML](#dynamic-configuration-yml) * [Dynamic configuration: Environment variables](#dynamic-configuration-environment-variables) * [Validating successful configuration](#validating-successful-configuration) * [Establishing a trust relationship between Domain API ML and Central API ML](#establishing-a-trust-relationship-between-domain-api-ml-and-central-api-ml) * [Commands to establish trust between Domain and Central API MLs](#commands-to-establish-trust-between-domain-and-central-api-mls) -* [Using the `/registry` endpoint in Cloud Gateway](#using-the-registry-endpoint-in-the-central-cloud-gateway) +* [Using the `/registry` endpoint in Cloud Gateway](#using-the-registry-endpoint-in-the-central-gateway) * [Configuration for `/registry`](#configuration-for-registry) * [Authentication for `/registry`](#authentication-for-registry) * [Authorization for `/registry`](#authorization-with-registry) @@ -51,7 +51,7 @@ When using a multitenancy environment, ensure that the following Zowe components - Cloud Gateway and Discovery Service: **enabled** - Gateway: **disabled** -## Onboarding Domain Gateways to the Central Cloud Gateway +## Onboarding Domain Gateways to the Central Gateway The Central Cloud Gateway must onboard all Domain Gateways. This can be done dynamically or by static definition. We strongly recommend using dynamic onboarding as this onboarding method adapts better to the potentially changing environments of the customer. Static onboarding does not provide the functionality to actively monitor the health of specific services (e.g. domain gateways). @@ -98,7 +98,7 @@ For static onboarding, make sure that the following parameters are correctly spe For static onboarding, use the [Gateway static definition example (deprecated)](#gateway-static-definition-example-deprecated) presented later in this article. -## Onboarding a Domain Cloud Gateway service to the Central Discovery service +## Onboarding a Domain Gateway service to the Central Discovery service The Central Cloud Gateway can onboard Cloud Gateways of all domains. This service onboarding can be achieved similar to additional registrations of the Gateway. This section describes the dynamic configuration of the yaml file and environment variables, and how to validate successful configuration. @@ -111,13 +111,13 @@ The Central Cloud Gateway can onboard Cloud Gateways of all domains. This servic Users must set the following property for the Domain Cloud Gateway to dynamically onboard to the Central Discovery service. -`components.cloud-gateway.apiml.service.additionalRegistration` +`components.gateway.apiml.service.additionalRegistration` Use the following example as a template for how to set the value of this property in zowe.yml. **Example:** ``` -components.cloud-gateway.apiml.service.additionalRegistration: +components.gateway.apiml.service.additionalRegistration: # central API ML (in HA, for non-HA mode use only 1 hostname) - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/ routes: @@ -143,7 +143,7 @@ This Zowe configuration transforms the zowe.yaml configuration file into the env The corresponding Cloud Gateway service should appear in the Eureka console of the Central Discovery service. -To see details of all instances of the ‘CLOUD-GATEWAY’ application, perform a **GET** call on the following endpoint of the Central Discovery service: +To see details of all instances of the ‘GATEWAY’ application, perform a **GET** call on the following endpoint of the Central Discovery service: ``` /eureka/apps @@ -303,7 +303,7 @@ The following commands are examples of establishing a trust relationship between You completed certificates setup for multitenancy configuration, whereby Domain API MLs can trust the Central API ML and vice versa. -## Using the `/registry` endpoint in the Central Cloud Gateway +## Using the `/registry` endpoint in the Central Gateway The `/registry` endpoint provides information about services onboarded to all Domain Gateways and the Central Cloud Gateway. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint. @@ -333,13 +333,13 @@ Unsuccessful authorization returns a 403 error code. There are two endpoints that provide information about services registered to the API ML. One endpoint is for all domains, and the other endpoint is for the specific domain. Choose from the following **GET** calls: -* `GET /cloud-gateway/api/v1/registry` +* `GET /gateway/api/v1/registry` This request lists services in all domains. -* `GET /cloud-gateway/api/v1/registry/{apimlId}` +* `GET /gateway/api/v1/registry/{apimlId}` This request lists services in the apimlId domain. -* `GET /cloud-gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` +* `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` This request gets the specific service in the specific apimlId domain. ### Response with `/registry` @@ -398,7 +398,7 @@ Should contain information about all services in a specific domain **Example:** -* `GET /cloud-gateway/api/v1/registry/apiml2` +* `GET /gateway/api/v1/registry/apiml2` ``` [ @@ -431,13 +431,13 @@ Should contain information about all services in a specific domain ] ``` -### Response with `GET /cloud-gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` +### Response with `GET /gateway/api/v1/registry/{apimlId}?apiId={apiId}&serviceId={serviceId}` Should contain information about a specific service in a specific domain **Example:** -* `GET /cloud-gateway/api/v1/registry/apiml2?apiId=zowe.apiml.gateway&serviceId=catalog` +* `GET /gateway/api/v1/registry/apiml2?apiId=zowe.apiml.gateway&serviceId=catalog` ``` [ diff --git a/docs/user-guide/api-mediation/api-mediation-overview.md b/docs/user-guide/api-mediation/api-mediation-overview.md index 5857138d42..0b12957d25 100644 --- a/docs/user-guide/api-mediation/api-mediation-overview.md +++ b/docs/user-guide/api-mediation/api-mediation-overview.md @@ -1,14 +1,14 @@ # API Mediation Layer -The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates secure communication across loosely coupled microservices through the API Gateway. The API Mediation Layer consists of three components: the Gateway, the Discovery Service, and the Catalog. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner. +The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates secure communication across loosely coupled microservices through the API Gateway. The API Mediation Layer consists of four components: the Gateway, the Discovery Service, the Catalog and the Caching Service. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner. The Caching Service provides stateful storage of key/value pairs. ## Key features * Consistent Access: API routing and standardization of API service URLs through the Gateway component provides users with a consistent way to access mainframe APIs at a predefined address. -* Dynamic Discovery: The Discovery Service automatically determines the location and status of API services. * High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind. * Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration. * Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility. * Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services. +* Service registry: Registry of available services with the status of the services. ## API Mediation Layer architecture The following diagram illustrates the single point of access through the Gateway, and the interactions between API ML components and services: @@ -24,27 +24,21 @@ Services that comprise the API ML service ecosystem are located behind a gateway ### Discovery Service -The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. - -#### Discovery Service TLS/SSL - -HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables hightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered. +The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. ### API Catalog -The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability. +The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. -#### Catalog Security - Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the zOSMF API. -## Onboarding APIs -The most important part of the ecosystem are the real API services that provide useful APIs. Use the following topics to understand what options you have for adding new APIs to the Mediation Layer: +### Caching service -* [Onboarding Overview](../../extend/extend-apiml/onboard-overview.md) +The Caching service aims to provide an API which offers the possibility to store, retrieve and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The URL of the Caching service is `https://:7555`. +For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service). -## Caching service +## Extending API ML by Onboarding new APIs +The most important part of the ecosystem are the real API services that provide useful APIs. Use the following topics to understand what options you have for adding new APIs to the Mediation Layer: -The Caching service aims to provide an API which offers the possibility to store, retrieve and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The URL of the Caching service is `https://:7555`. -For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service). +* [Onboarding Overview](../../extend/extend-apiml/onboard-overview.md) diff --git a/docs/user-guide/api-mediation/api-mediation-update-password.md b/docs/user-guide/api-mediation/api-mediation-update-password.md index 441ba50a9a..eb514234d2 100644 --- a/docs/user-guide/api-mediation/api-mediation-update-password.md +++ b/docs/user-guide/api-mediation/api-mediation-update-password.md @@ -51,8 +51,4 @@ Use the following request body format in the `POST` REST call against the URL `/ "password" : "", "newPassword" : "" } -``` - -:::note -In order to use the password change functionality via z/OSMF, it is necessary to install the PTF for APAR PH34912. -::: \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md index 8826744317..42663d6946 100644 --- a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md +++ b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md @@ -6,6 +6,8 @@ You can use API Mediation Layer to generate, validate, and invalidate a **Personal Access Token (PAT)** that can enable access to tools such as VCS without having to use credentials of a specific person. The use of PAT does not require storing mainframe credentials as part of the automation configuration on a server during application development on z/OS. Additionally, using a PAT makes it possible to limit access to specific services and users by means of token revocation when using a token. +To enable the Personal Access Token functionality read: [Enable Personal Access Token](./configuration-personal-access-token.md) + Gateway APIs are available to both users as well as security administrators. APIs for users can accomplish the following functions: diff --git a/docs/user-guide/api-mediation/configuration-at-tls.md b/docs/user-guide/api-mediation/configuration-at-tls.md index 48131622ac..5972dfcdde 100644 --- a/docs/user-guide/api-mediation/configuration-at-tls.md +++ b/docs/user-guide/api-mediation/configuration-at-tls.md @@ -18,14 +18,11 @@ Review this article for descriptions of the configuration parameters required to ## AT-TLS configuration for Zowe -:::tip -Support for AT-TLS was introduced in Zowe v1.24. In this early version, startup was not possible in some versions of Zowe. For full support, we recommend that you upgrade to v2.13 or a later version of Zowe. -::: - Follow these steps to configure Zowe to support AT-TLS: 1. Enable the AT-TLS profile and disable the TLS application in API ML. -Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `metrics-service` in the `zowe.components` section. + +Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `zaas` in the `zowe.components` section. **Example:** @@ -63,7 +60,7 @@ zowe: server: ssl: enabled: false - metrics-service: + zaas: spring: profiles: active: attls @@ -77,8 +74,6 @@ While API ML does not handle TLS on its own with AT-TLS enabled, API ML requires If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. :::note Notes -* AT-TLS is supported in the API Cloud Gateway Mediation Layer component beginning with version 2.17. - * As the Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. ::: @@ -135,13 +130,13 @@ TTLSConnectionAction ApimlServerConnectionAction The `PortRange` of this inbound rule is taken from the list of API Mediation Layer components in the `zowe.yaml` file. The `PortRange` should cover the following components: -| Component | Port | -|----|-----------------------| -| Gateway | default port 7554 | -| Discovery | default port 7553 | -|Caching Service | 7555 | -|API Catalog | default port 7552 | -| Metrics Service | default port 7551 | +| Component | Port | +|-----------------|-------------------| +| Gateway | default port 7554 | +| Discovery | default port 7553 | +| Caching Service | default port 7555 | +| API Catalog | default port 7552 | +| ZAAS | default port | **Follow this step:** diff --git a/docs/user-guide/api-mediation/configuration-client-certificates.md b/docs/user-guide/api-mediation/configuration-client-certificates.md index d3fc86a751..fa5ec70a03 100644 --- a/docs/user-guide/api-mediation/configuration-client-certificates.md +++ b/docs/user-guide/api-mediation/configuration-client-certificates.md @@ -6,9 +6,9 @@ You can authenticate against API ML onboarded APIs. This functionality is disabled by default. Follow the steps in this article to enable authentication against API ML onboarded APIs. There are two methods to enable client certificate functionality: -* The original and default method via ZSS -* The newer and recommended method via the internal mapper component of API Mediation Layer +* The default and recommended method via the internal mapper component of API Mediation Layer The internal API ML mapper is simpler to configure and provides more functionality than ZSS. +* The older and deprecated method via ZSS Review this article to learn about the required configuration to authenticate with either method. @@ -64,7 +64,7 @@ Ensure that you have the Issuer certificate imported in the truststore or in the ::: :::tip -There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, and are using Zowe v2.14 or a later version, use the recommended internal API ML mapper. +There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, use the recommended internal API ML mapper. ::: ### Enabling zowe.yaml to use a client certificate diff --git a/docs/user-guide/api-mediation/configuration-connection-limits.md b/docs/user-guide/api-mediation/configuration-connection-limits.md index 93083dd415..b80a941b9c 100644 --- a/docs/user-guide/api-mediation/configuration-connection-limits.md +++ b/docs/user-guide/api-mediation/configuration-connection-limits.md @@ -33,8 +33,7 @@ zowe: Use the following procedure to change the limits: 1. Open the file `zowe.yaml`. -2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). -3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway will wait for the graceful stopping of the WebSocket connection. The default is 30 seconds (30000 milliseconds). -4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). -5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). -6. Find or add the property `zowe.components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. +2. Find or add the property `components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). +3. Find or add the property `components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). +4. Find or add the property `components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). +5. Find or add the property `components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. diff --git a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md index 1f167ab8c5..84591b468b 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md +++ b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md @@ -17,6 +17,7 @@ Specifies one of the following services: - `discovery` - `caching-service` - `api-catalog` + - `zaas` **Example with Gateway Service:** diff --git a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md index a2808c0e6a..a58d091713 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md +++ b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md @@ -9,7 +9,3 @@ As a system programmer, you can customize your configuration for how API ML mana * To change the global Gateway timeout value for the API ML instance, see [Customizing Gateway timeouts](./configuration-gateway-timeouts.md). - * Also see the following properties in API Gateway configuration parameters: - * `server.maxTotalConnections` - * `server.maxConnectionsPerRoute` - diff --git a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md index e411f822ce..7658e54c8e 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md +++ b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md @@ -13,7 +13,7 @@ As a system administrator, you can customize the API Catalog UI to have a simila It is possible to customize the logotype and selected style options directly in `zowe.yaml`. 1. Open the file `zowe.yaml`. -2. Configure the following properties by setting them under `ZWE_configs_apiml_catalog_customStyles`: +2. Configure the following properties by setting them under `configs.apiml.catalog.customStyles`: - **logo** Specifies the location of the logo that will replace the default Zowe logo in the API Catalog header. The supported image formats are: `svg`, `png` and `jpg/jpeg`. @@ -68,9 +68,6 @@ Nothing is displayed on the Gateway home page and the Catalog is removed from `/ - **alternative-catalog** An alternative to the API Catalog is displayed -- **metrics-dashboard** - A possible dashboard that could appear in place of the API Catalog - :::note Notes: - If the application contains the `homePageUrl` and `statusPageRelativeUrl`, then the full set of information is displayed. - If the application contains the `homePageUrl` the link is displayed without the `UP` information. diff --git a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md index 1a19517c58..fcd62fb230 100644 --- a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md +++ b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md @@ -3,7 +3,7 @@ :::info Role: system programmer ::: -You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are reuqired to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups. +You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are required to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups. Use the following procedure to distribute the load balancer cache between instances of the API Gateway. diff --git a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md index 593ffb6cdf..0601201083 100644 --- a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md +++ b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md @@ -8,35 +8,22 @@ Use the following procedure to change the global timeout value for an API Mediat 1. Open the file `zowe.yaml`. 2. Configure the following properties: - * **components.gateway.apiml.gateway.timeoutmillis** - This property defines the global value for http/ws client timeout. - - :::note - Ribbon configures the client that connects to the routed services. - ::: - * **components.gateway.ribbon.connectTimeout** + * **components.gateway.apiml.connectTimeout** Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used. + * **components.gateway.apiml.connection.idleConnectionTimeoutSeconds** - * **components.gateway.ribbon.readTimeout** - Specifies the time in milliseconds of inactivity between two packets in response from this service to API ML. If omitted, the default value specified in the API ML Gateway service configuration is used. - - * **components.gateway.ribbon.connectionManagerTimeout** - The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP connection manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to persistent connections. Internally, the connections that are managed serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period during which managed connections with API ML should be established. The value is in milliseconds. If omitted, the default value specified in the API ML Gateway service configuration is used. - - * **components.gateway.httpclient.requestConnectionTimeout** - Specifies the HTTP Client Request Connection Timeout for southbound services from the API Gateway. This setting defines the period that the API Gateway waits for a response from the southbound server before issuing a connection refused response. The value is in milliseconds. An example value of a 30 second connection timeout would be 30000. + * **components.gateway.apiml.connection.timeToLive** **Example:** ```yaml components: gateway: - ribbon: + apiml: connectTimeout: 30000 - readTimeout: 60000 - connectionManagerTimeout: 45000 - httpclient: - requestConnectionTimeout: 60000 + connection: + idleConnectionTimeoutSeconds: + timeToLive: ``` 3. Restart Zowe. diff --git a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md index 2e0c05e4ae..c1a7032f22 100644 --- a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md +++ b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md @@ -1,43 +1,48 @@ -# Configuring API Gateway Health Check Protection +# Configuring Health Check Protection :::info Role: system programmer ::: -As a system programmer, you can configure the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. Enabling protection for the health check endpoint can enhance the security of the API Gateway by restricting access to sensitive status information about the Gateway. +As a system programmer, you can disable the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. In Zowe V2, authentication was not required. Disabling protection for the health check endpoint can limit the security of the API Gateway by allowing access to sensitive status information about the Gateway. Use the following procedure to set the value of the health check endpoint of the API Gateway: 1. Open the file `zowe.yaml`. 2. Configure the following property: -* `components.gateway.apiml.gateway.health.protected` +* `components.gateway.apiml.health.protected` This property defines whether the health check endpoint is accessible with or without authentication. :::note -The default value of this parameter is `false`. We recommend setting this parameter to `true` for production environments. +The default value of this parameter is `true`. ::: **Example:** ```yaml -zowe: - components: +components: gateway: - apiml: - gateway: - health: - protected: true + apiml: + gateway: + health: + protected: true ``` -In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. This ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users. +In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. Requiring authentication ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users. To allow open access to the health check endpoint, set the parameter to `false`. Setting this parameter to `false` permits access to this endpoint without authentication. In this case, anyone can access the health check endpoint and obtain information about the status of the Gateway. +* `components.discovery.apiml.health.protected` + This property defines whether the health check endpoint on Discovery service is accessible with or without authentication. +* `components.apiCatalog.apiml.health.protected` + This property defines whether the health check endpoint on API Catalog is accessible with or without authentication. + + ## Environment Recommendations When setting this parameter, we recommend applying the following values according to your environment: * **In Production Environments** -It is recommended to set `apiml.gateway.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. +It is recommended to set `components.*.apiml.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. This is the default. * **In Development/Testing Environments** - setting `apiml.gateway.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging. + setting `components.*.apiml.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging. diff --git a/docs/user-guide/api-mediation/configuration-jwt.md b/docs/user-guide/api-mediation/configuration-jwt.md index 02caa0cc4d..4ddea8ac3a 100644 --- a/docs/user-guide/api-mediation/configuration-jwt.md +++ b/docs/user-guide/api-mediation/configuration-jwt.md @@ -74,7 +74,7 @@ An authentication token is used as proof of valid authentication. The authorizat You can also customize the following properties when authenticating with a JWT token: * **components.gateway.apiml.security.auth.zosmf.ServiceId** - This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `zosmf`. + This parameter specifies the z/OSMF service id used as authentication provider. The service id is defined in the static definition of z/OSMF. The default value is `ibmzosmf`. * **components.gateway.apiml.security.auth.tokenProperties.expirationInSeconds** This property is relevant only when the JWT is generated by the API Mediation Layer and specifies to the time before expiration. diff --git a/docs/user-guide/api-mediation/configuration-logging.md b/docs/user-guide/api-mediation/configuration-logging.md index 51c11f3b37..04c384e529 100644 --- a/docs/user-guide/api-mediation/configuration-logging.md +++ b/docs/user-guide/api-mediation/configuration-logging.md @@ -10,8 +10,7 @@ To change the default logback configuration file, set `components..lo - `discovery` - `api-catalog` - `caching-service` - - `cloud-gateway` - - `metrics-service` + - `zaas` **Example with Gateway Service:** diff --git a/docs/user-guide/api-mediation/configuration-personal-access-token.md b/docs/user-guide/api-mediation/configuration-personal-access-token.md index afe3a147da..890a9d7a71 100644 --- a/docs/user-guide/api-mediation/configuration-personal-access-token.md +++ b/docs/user-guide/api-mediation/configuration-personal-access-token.md @@ -10,18 +10,17 @@ Review this article for steps that enable single sign on via Personal Access Tok To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution. -To enable this storage method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section. For more information on these properties and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). +To enable this storage method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. For more information on other properties for infinispan and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). ``` yaml - zowe - components: - caching-service: - storage: - mode: infinispan - infinispan: - jgroups: - port: 7098 + components: + caching-service: + storage: + mode: infinispan + infinispan: + jgroups: + port: 7098 ``` ## Enabling Personal Access Tokens diff --git a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md index 59f962b5ac..0331445d2a 100644 --- a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md +++ b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md @@ -3,9 +3,9 @@ :::info Role: API service extender ::: -As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix with Zowe v2. +As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix. For more information, see the following parameter in the article Discovery Service configuration parameters: * **components.discovery.apiml.discovery.serviceIdPrefixReplacer** - This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with v2, based on Zowe v2 conformance. \ No newline at end of file + This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with. \ No newline at end of file diff --git a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png index ddf6741773..65886a4144 100644 Binary files a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png and b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png differ diff --git a/docs/user-guide/api-mediation/discovery-service-configuration.md b/docs/user-guide/api-mediation/discovery-service-configuration.md index e5b50218e9..2b38398331 100644 --- a/docs/user-guide/api-mediation/discovery-service-configuration.md +++ b/docs/user-guide/api-mediation/discovery-service-configuration.md @@ -2,7 +2,7 @@ ## Zowe runtime configuration parameters -As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `/components/discovery/bin/start.sh` file: +As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `zowe.yaml` file: * **[API ML configuration](#api-ml-configuration)** @@ -13,24 +13,24 @@ As an application developer who wants to run Zowe, set the following parameters 1. Open the file `zowe.yaml`. 2. Configure the following properties: -* **apiml.service.hostname** +* **haInstance.hostname** - This property is used to set the Discovery Service hostname. The value can be set by defining the `ZWE_haInstance_hostname` property in the `zowe.yaml` file. + This property is used to set the Discovery Service hostname. The value can be set by defining the `haInstance.hostname` property in the `zowe.yaml` file. -* **apiml.service.port** +* **components.discovery.port** - This property is used to set the Discovery Service port. The value can be set by defining the `ZWE_configs_port` property in the `zowe.yaml` file. + This property is used to set the Discovery Service port. The value can be set by defining the `components.discovery.port` property in the `zowe.yaml` file. -* **apiml.discovery.staticApiDefinitionsDirectories** +* **environments.ZWE_STATIC_DEFINITIONS_DIR** - The value of `apiml.discovery.staticApiDefinitionsDirectories` can be set by defining the `ZWE_STATIC_DEFINITIONS_DIR` property in `zowe.yaml`. The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services. + The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services. **Example:** ```yaml - ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs + environments: + ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs ``` -* **apiml.discovery.allPeersUrls** +* **environments.ZWE_DISCOVERY_SERVICES_LIST** - The value of `apiml.discovery.allPeersUrls` can be set by defining the `ZWE_DISCOVERY_SERVICES_LIST` property in `zowe.yaml`. This parameter contains the list of URLs of the Discovery Service in case of multiple instances of the service on different host. **Example:** ```yaml diff --git a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md index a9bcb49c03..79d97e32f8 100644 --- a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md +++ b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md @@ -84,8 +84,6 @@ The configuration entries of each LPAR in the `zowe.yaml` file control which com The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex, are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so that each instance behaves similarly to the user irrespective of where their request is routed. -For simplification of the preceding diagram, the Jobs and Files API servers are not shown as being started. If the user defines Jobs and Files API servers to be started in the `zowe.yaml` configuration file, these servers behave the same as the servers that are illustrated. In other words, these services register to their API discovery server which then communicates with other discovery servers on other Zowe instances on either the same or other LPARs. The API traffic received by any API Gateway on any Zowe instance is routed to any of the Jobs or Files API components that are available. - To learn more about Zowe with high availability enablement, see [Configuring Sysplex for high availability](../configure-sysplex). ## API Versioning diff --git a/docs/user-guide/api-mediation/using-api-mediation-layer.md b/docs/user-guide/api-mediation/using-api-mediation-layer.md index 7109547051..c96d2c5f9b 100644 --- a/docs/user-guide/api-mediation/using-api-mediation-layer.md +++ b/docs/user-guide/api-mediation/using-api-mediation-layer.md @@ -68,6 +68,5 @@ There are various options for using the API Catalog: ### Additional use case when usig API Mediation Layer -* [Using Metrics Service (Technical Preview)](../api-mediation-metrics-service) * [SMF records](./api-mediation-smf) diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md index b1a1d5d2bd..178ec7f93c 100644 --- a/docs/user-guide/authenticating-with-client-certificates.md +++ b/docs/user-guide/authenticating-with-client-certificates.md @@ -19,7 +19,7 @@ When sending a request to a service with a client certificate, the Gateway perfo 1. The client calls the service endpoint through the API ML Gateway with the client certificate. 2. The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway. -3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper. +3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. The API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper. 4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service. :::note Notes: @@ -31,7 +31,7 @@ When sending a request to the login endpoint with a client certificate, the Gate 1. The client calls the API ML Gateway login endpoint with the client certificate. 2. The client certificate is verified to ensure this is a valid TLS client certificate against the trusted CAs of the Gateway. -3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe release 2.14, the internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2. +3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. The internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2. 4. The Gateway then performs the login of the mapped user and returns a valid JWT token. :::note diff --git a/docs/user-guide/authentication-providers-for-apiml.md b/docs/user-guide/authentication-providers-for-apiml.md index b1c4dc2012..e6d918731c 100644 --- a/docs/user-guide/authentication-providers-for-apiml.md +++ b/docs/user-guide/authentication-providers-for-apiml.md @@ -24,7 +24,7 @@ The `z/OSMF Authentication Provider` allows the API Gateway to authenticate with Use the following properties of the API Gateway to enable the `z/OSMF Authentication Provider`: ``` components.gateway.security.auth.provider: zosmf -components.gateway.security.auth.zosmfServiceId: zosmf # Replace me with the correct z/OSMF service id +components.gateway.security.auth.zosmfServiceId: ibmzosmf # Replace me with the correct z/OSMF service id ``` ## SAF Authentication Provider diff --git a/docs/user-guide/cli-cicsplugin.md b/docs/user-guide/cli-cicsplugin.md index 8516ebb8fa..19194e79f8 100644 --- a/docs/user-guide/cli-cicsplugin.md +++ b/docs/user-guide/cli-cicsplugin.md @@ -2,13 +2,6 @@ The IBM® CICS® Plug-in for Zowe™ CLI lets you extend Zowe CLI to interact with CICS programs and transactions. The plug-in uses the IBM CICS® Management Client Interface (CMCI) API to achieve the interaction with CICS. For more information, see [CICS management client interface](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.3.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) on the IBM Knowledge Center. - - [Use Cases](#use-cases) - - [Commands](#commands) - - [Software requirements](#software-requirements) - - [Installing](#installing) - - [Creating a user profile](#creating-a-user-profile) - - ## Use cases As an application developer, you can use the plug-in to perform the following tasks: @@ -21,11 +14,13 @@ As an application developer, you can use the plug-in to perform the following ta ## Commands -For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help. It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file containing the HTML for the online version. +For detailed documentation on commands, actions, and options available in this plug-in, see our web help. + +There are several methods to view Zowe CLI web help: -- Browse Online -- Download (ZIP) -- Download (PDF) +- Use a web browser +- Extract from a ZIP file +- Download a PDF file ## Software requirements @@ -41,27 +36,54 @@ Use one of the following methods to install or update the plug-in: ## Creating a user profile -You create a cics profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile: -- **Create plug-in profiles using a configuration file:** Specify your profile and connection details in the `zowe.config.json` configuration file. -- **Create plug-in profiles using a command:** Issue the `zowe profiles create` command to create the profile. -We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing them from a future major release. +After you install the plug-in, create a CICS profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. + +Specify your plug-in profile and connection details in the `zowe.config.json` configuration file. ### Creating plug-in profiles using a configuration file -When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the CICS plug-in, the commands create an entry for a cics profile in your `zowe.config.json` file. +If you have the CICS plug-in installed and issue the `zowe config init`, `zowe config auto-init`, or `zowe config convert-profiles` command, the command creates an entry for a CICS profile in your `zowe.config.json file`. Alternatively, you can create a CICS profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file. -1. Browse to the following directory `C:\Users\\.zowe` +#### Creating a CICS profile with a command + +1. Install the CICS Plug-in for Zowe CLI. +2. Create a CICS profile: + + ``` + zowe config init + ``` +3. Set the port number to the port configured for a CICS connection on your mainframe. + + ``` + zowe config set profiles.cics.properties.port + ``` + + - `` + + Specifies the port number for the instance. + + You can now use your profile when you issue commands in the cics command group. -2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ. +#### Creating a CICS profile manually - **NOTE:** If the file does not exist, issue the following command to create the configuration file: +1. Install the CICS Plug-in for Zowe CLI. + +2. Browse to the directory `C:\Users\\.zowe`. + +3. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ IDEA. + + :::note + + If the file does not exist, issue the following command to create the configuration file: ``` zowe config init --gc ``` + + ::: -3. Add code to the "profiles" section as shown in the following example: : +4. Add code to the "profiles" section as shown in the following example: ``` "Your_cics_profile": { @@ -78,47 +100,6 @@ Alternatively, you can create a CICS profile manually by adding a section that c } ``` +5. Save the file. -4. Save the file. - -You can now use your profile when you issue commands in the cics command group. - -### Creating plug-in profiles using a command - -The following steps describe how to create a profile using the `zowe profiles create` command. - -1. Open a terminal window and issue the following command: - - ``` - zowe profiles create cics –-host --port --user --password --region-name - ``` - -- **`profile_name`:** - - Specifies a name for your profile. -- **`host`:** - - Specifies the host name for the instance. -- **`user`**: - - Specifies your user name to log in to the instance. -- **`password`**: - - Specifies your password to log in to the instance. -- **`port`**: - - Specifies the port number to connect to the instance. -- **`region`**: - - Specifies the region to use on the instance. - - **Example:** - ``` - zowe profiles create cics-profile REGION1 --host mylpar.zowe.org --port 1443 --user zowe --password zowepass --region-name CICCMCI - ``` - -2. Press Enter. The result of the command displays as a success or failure message. - -You can now use your profile when you issue commands in the cics command group. - -The plug-in uses HTTPS by default. Use the optional flag `--protocol http` to override the default with HTTP. \ No newline at end of file + You can now use your profile when you issue commands in the zftp command group. diff --git a/docs/user-guide/cli-configure-cli-on-os-where-scs-unavailable.md b/docs/user-guide/cli-configure-cli-on-os-where-scs-unavailable.md index a7c9a466fb..d058b7d25f 100644 --- a/docs/user-guide/cli-configure-cli-on-os-where-scs-unavailable.md +++ b/docs/user-guide/cli-configure-cli-on-os-where-scs-unavailable.md @@ -1,28 +1,35 @@ -# Configure Zowe CLI on operating systems where the Secure Credential Store is not available +# Configuring Zowe CLI where secure credential storage is not available -By default, Zowe CLI attempts to store sensitive information and credentials in the operating system’s credential manager. When the information cannot be stored securely, Zowe CLI displays an error when you attempt to create V1 style profiles or a V2 configuration. The actions that are required to disable secure credential management differ depending on the type of configuration being used. +By default, Zowe CLI attempts to store sensitive information and credentials in the operating system’s credential storage. If the information cannot be stored securely, Zowe CLI displays an error when you attempt to initiate [team configuration](../appendix/zowe-glossary#team-configuration). -## V1 profiles +:::info Required role: systems administrator +::: -Existing V1 profiles will continue to function properly. However, it will not be possible to create new profiles without disabling secure credential management. To disable secure credential management for V1 profiles: +## Team configuration -1. Navigate to the `.zowe/settings` directory. -2. Modify the `imperative.json` file by replacing the Credential Manager override value to the following: - ``` - "CredentialManager": false - ``` -3. Save the changes. +In team configuration, team profiles are stored in the `zowe.config.json` file and user profiles are saved in `zowe.config.user.json`. -## Team configuration +By default, every configuration file includes an `autoStore` property that is set to automatically store values that are prompted from the user. The value that you enter when prompted is stored for future commands to use to avoid re-entering information repeatedly. + +This can cause potential problems when secure credential storage is not available. + +If Zowe CLI cannot find the value for a user ID or password, for example, it prompts the user for that information and then stores the information securely when secure storage is available. -Team configuration is stored in `zowe.config.json`. +In cases where secure storage is not possible, and the `autoStore` property is set to `true`, the credentials are saved as text in the applicable configuration file. -Team configuration can be created without access to the Secure Credential Store. However, team configuration does not store sensitive user information on the system. Subsequent commands prompt for the user’s sensitive information when it not provided on the command line, and will attempt to save it with the new Auto Store functionality. Users may experience errors when Auto Store cannot save sensitive information securely. To mitigate this error, disable the Auto Store functionality by changing the value of the autoStore property from `true` to `false` in the `zowe.config.json` or `zowe.config.user.json` file. +## Stopping automatic storage of prompted values -**Example:** +To stop storing information prompted by Zowe CLI: -``` - }, - "autoStore": false -} -``` \ No newline at end of file +1. Use a text editor to open the configuration file used by your commands. + + For project configuration, locate the file in your project directory. For global configuration, the file is found in the `ZOWE_CLI_HOME` directory. + +2. Navigate to the `autoStore` property and set the value to `false`: + + ``` + }, + "autoStore": false + } + ``` + Zowe CLI is configured to prompt for all missing values on all commands that you issue. \ No newline at end of file diff --git a/docs/user-guide/cli-configure-daemon-on-zlinux-os.md b/docs/user-guide/cli-configure-daemon-on-zlinux-os.md index dfb1cff4b8..7b5ae82d82 100644 --- a/docs/user-guide/cli-configure-daemon-on-zlinux-os.md +++ b/docs/user-guide/cli-configure-daemon-on-zlinux-os.md @@ -1,8 +1,11 @@ -# Configure daemon mode on z/Linux operating systems +# Configuring daemon mode on z/Linux operating systems -Currently, Zowe does not offer a prebuilt daemon that can run on z/Linux operating systems. However, developers can build the daemon binary from source. +Currently, Zowe CLI does not offer a prebuilt daemon that can run on z/Linux operating systems. However, developers can build the daemon binary from source. -The following steps describe how to install and build the daemon binary on z/Linux systems and the technical limitations. +:::info Required roles: Security administrator, DevOps architect +::: + +To install and build the daemon binary on z/Linux systems: 1. Ensure that the z/Linux system can communicate using the Internet. 2. Install Zowe CLI on the z/Linux system. @@ -14,7 +17,7 @@ The following steps describe how to install and build the daemon binary on z/Lin - Rust For information about how to install Rust, see the [Rust documentation](https://forge.rust-lang.org/infra/other-installation-methods.html). -4. Shallow clone the Zowe CLI Git repository for the version of CLI that you installed. Issue the following command: +4. Shallow clone the Zowe CLI Git repository for the version of CLI that you installed. Open a command line window and issue the following command: ``` git clone https://github.com/zowe/zowe-cli –depth 1 –branch v$(zowe –version) @@ -34,18 +37,22 @@ The following steps describe how to install and build the daemon binary on z/Lin After the command completes successfully, the Zowe daemon binary is a file named `zowe` that can be found in the `target/release` directory. -7. Copy the binary to another location on the system and add it to your PATH. -8. (Optional) Modify the file permissions to allow others to use the same binary: +7. Copy the binary to another location on the system and add that location to your PATH. +8. To allow others to use the same binary, modify the file permissions in the binary: ``` chmod zowe chown : zowe ``` - **Example:** The following example illustrates the command to allow all users to run the Zowe binary. However, only the user that created the binary can overwrite the binary. + The following example illustrates the command to allow all users to run the Zowe binary. However, only the user that created the binary can overwrite the binary. ``` chmod 755 zowe ``` - **Note:** You can delete the `.zowe-cli` folder that was created in **Step 4** after the binary builds successfully. The Zowe daemon commands will not function, and the daemon will need to be rebuilt for all new versions of Zowe CLI. \ No newline at end of file + :::note + + You can delete the `.zowe-cli` folder that was created in Step 4 after the binary builds successfully. The Zowe daemon commands will not function, and the daemon will need to be rebuilt for all new versions of Zowe CLI. + + ::: diff --git a/docs/user-guide/cli-configure-scs-on-headless-linux-os.md b/docs/user-guide/cli-configure-scs-on-headless-linux-os.md index e1af4ca279..a995eb74d0 100644 --- a/docs/user-guide/cli-configure-scs-on-headless-linux-os.md +++ b/docs/user-guide/cli-configure-scs-on-headless-linux-os.md @@ -1,6 +1,9 @@ -# Configuring Secure Credential Store on headless Linux operating systems +# Configuring secure credential storage on headless Linux operating systems -Perform the following configurations on headless and z/Linux operating systems. +Perform the following configurations on headless Linux or z/Linux operating systems. + +:::info Required role: systems administrator +::: :::note @@ -8,20 +11,18 @@ For CI/CD pipelines, we recommend using the credential management provided by th ::: -## Headless Linux requirements +## Headless Linux operating systems -- Ensure that you installed the Secure Credential Store requirements that are described in [System Requirements](../user-guide/systemrequirements-cli.md). -- Unlock the Gnome keyring to allow you to load and store credentials on headless Linux operating systems. You can unlock the keyring manually or automatically. +### Requirements for headless Linux operating systems -:::note - -On z/Linux operating systems, complete the steps in [Configuring z/Linux](#configuring-zlinux) before you continue. - -::: +- Ensure that you installed the secure credential storage requirements that are described in [Zowe CLI software requirements](../user-guide/systemrequirements-cli.md#secure-credential-storage). +- Unlock the Gnome keyring to allow you to load and store credentials on headless Linux operating systems. You can unlock the keyring manually or automatically, see the following instructions. ### Unlocking the keyring manually -Issue the following commands to unlock the keyring manually. You must unlock the keyring in each user session. +You must unlock the keyring in each user session. + +To unlock the keyring manually, open the command prompt and issue the following command: ```bash export $(dbus-launch) @@ -30,7 +31,7 @@ gnome-keyring-daemon -r --unlock --components=secrets :::note -The `gnome-keyring-daemon -r --unlock --components=secrets` prompts you to specify a password. Press `Ctrl+D` twice after you specify the password. +The `gnome-keyring-daemon -r --unlock --components=secrets` command prompts you to specify a password. After you enter the password, press `Ctrl` + `D` twice to continue the terminal session. ::: @@ -44,14 +45,14 @@ The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. T ::: -**Follow these steps:** +To unlock the Gnome keyring automatically when you log in: -1. Install the PAM module for Gnome keyring. The package name depends on your distribution: +1. Follow instructions for your Linux distribution on installing the PAM module for Gnome keyring. The package name depends on your distribution: - `gnome-keyring-pam`: CentOS, Fedora, SUSE - `libpam-gnome-keyring`: Debian, Ubuntu -2. Apply the following edits to the files `/etc/pam.d/login` (for TTY login), and `/etc/pam.d/sshd` if it exists (for SSH login). +2. Use a text editor or the applicable command to edit the files `/etc/pam.d/login` (for TTY login) and `/etc/pam.d/sshd`, if it exists (for SSH login). - Add the following statement to the end of the `auth` section: @@ -65,7 +66,8 @@ The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. T session optional pam_gnome_keyring.so auto_start ``` -3. Add the following commands to `~/.bashrc`. The first command will launch DBus, which the Gnome keyring requires. The second command starts the keyring daemon so that it is ready to be used by Zowe CLI commands. +3. Use a text editor or the applicable command to add the following commands to the `~/.bashrc` file: + ```bash if [[ $- == *i* ]]; then # Only run in interactive mode if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then @@ -76,46 +78,85 @@ The following steps were tested on CentOS, SUSE, and Ubuntu operating systems. T fi ``` + The first command launches DBus, which the Gnome keyring requires. The second command starts the keyring daemon so that it is ready to be used by Zowe CLI commands. + 4. Restart your computer. - Issue a Zowe CLI command that uses secure credentials to test that automatic unlock of the keyring works. + You have successfully completed the configuration to unlock the Gnome keyring automatically. -## Configuring z/Linux +5. Issue a Zowe CLI command that uses secure credentials to validate the automatic keyring unlock. -The Secure Credential Store (SCS) does not contain the native, pre-built binaries that are required to access the credential vault on z/Linux operating systems. +## z/Linux operating systems -Because the credential manager is now a built-in function of Zowe CLI, developers must build the credential mananger binaries on z/Linux systems during the Zowe CLI installation process. +### Configuring z/Linux -The following steps describe how to install and build the credential store binaries on z/Linux (Red Hat Enterprise Linux (RHEL) and Ubuntu) systems. +Zowe CLI does not contain the native, pre-built binaries that are required to access the credential vault on z/Linux operating systems. Developers must build the credential manager binaries on z/Linux systems during the Zowe CLI installation process. -1. Install the following Linux packages on the z/Linux system: - - make - - gcc-c++ (sometimes available as g++) - - gnome-keyring - - libsecret (sometimes available as libsecret-1-0) - - libsecret-devel (sometimes available as libsecret-1-dev) +For instructions to set up the credential manager binaries for Red Hat Enterprise Linux (RHEL) V8.X and Ubuntu z/Linux systems, refer to this section. For instructions specific to RHEL V7.X, see [Configuring RHEL V7.X](#configuring-rhel-v7x). + +To install and build the credential storage binaries on z/Linux RHEL V8.X and Ubuntu systems: + +1. Use the command prompt to install the following Linux packages on the z/Linux system: + - `make` + - `gcc-c++` (sometimes available as `g++`) + - `gnome-keyring` + - `libsecret` (sometimes available as `libsecret-1-0`) + - `libsecret-devel` (sometimes available as `libsecret-1-dev`) - Python 3.6 or later :::note - If you are installing the Linux packages on a z/Linux system, the system where you are configuring SCS might require Internet access. When a site hosts its own package repositories, the repositories might not contain all of the packages that are required to configure the SCS. In this scenario, the z/Linux system requires Internet access to install the required packages. + If you are installing the Linux packages on a z/Linux system, the system where you are configuring secure credential storage might require Internet access. When a site hosts its own package repositories, the repositories might not contain all of the packages that are required to configure the secure credential storage. In this scenario, the z/Linux system requires Internet access to install the required packages. ::: -2. If you are configuring SCS on a Ubuntu z/Linux operating system, no further action is required. You can now install Zowe CLI. For all other platforms (RHEL), continue to the next step. +2. If you are configuring secure credential storage on a Ubuntu z/Linux operating system, install Zowe CLI. + + For all other platforms (RHEL), continue to the next step. 3. Enable the `rhel-#-for-system-z-optional-rpms` repository to download libsecret-devel. - Replace ***#*** with the major version of RHEL that is running on the z/Linux system. + If your license entitles you to this repository, open the command prompt and issue the following command to enable it: + + ``` + subscription-manager repos —-enable rhel-#-for-system-z-optional-rpms + ``` + + Replace `#` with the major version of RHEL that is running on the z/Linux system. + +4. [Unlock the keyring manually](#unlocking-the-keyring-manually) or [unlock the keyring automatically](#unlocking-the-keyring-automatically) to load and store credentials. - If your license entitles you to this repository, issue the following command to enable it: +5. If you are configuring secure credential storage to run on RHEL V8.x or later, install Zowe CLI. + +## Configuring RHEL V7.X + +To install and build the credential storage binaries on z/Linux RHEL V7.X: + +1. Use the command prompt to install the following Linux packages on the z/Linux system: + - `make` + - `gcc-c++` (sometimes available as `g++`) + - `gnome-keyring` + - `libsecret` (sometimes available as `libsecret-1-0`) + - `libsecret-devel` (sometimes available as `libsecret-1-dev`) + - Python 3.6 or later + + :::note + + If you are installing the Linux packages on a z/Linux system, the system where you are configuring secure credential storage might require Internet access. When a site hosts its own package repositories, the repositories might not contain all of the packages that are required to configure the secure credential storage. In this scenario, the z/Linux system requires Internet access to install the required packages. + + ::: + +2. Enable the `rhel-#-for-system-z-optional-rpms` repository to download libsecret-devel. + + If your license entitles you to this repository, open the command prompt and issue the following command to enable it: ``` subscription-manager repos —-enable rhel-#-for-system-z-optional-rpms ``` -4. If you are configuring SCS to run on RHEL V8.x or later, no further action is required. You can now install Zowe CLI. For RHEL V7.x, continue to the next step. -5. Install the Red Hat Developer Toolset to ensure that you are running a version of the gcc-c++ compiler that can build the SCS native binaries. + Replace `#` with the major version of RHEL that is running on the z/Linux system. + +3. Install the Red Hat Developer Toolset to ensure that you are running a version of the gcc-c++ compiler that can build the secure credential storage native binaries. Issue the following commands to enable the repositories that are required to install the toolset: ``` @@ -125,15 +166,22 @@ The following steps describe how to install and build the credential store binar subscription-manager repos --enable rhel-7-for-system-z-optional-source-rpms subscription-manager repos --enable rhel-7-for-system-z-optional-debug-rpms ``` -6. Install the toolset: +6. Install the toolset by issuing the following command: ``` yum install devtoolset-11 ``` -7. After you install the toolset on RHEL V7.x, you can install Zowe CLI. +7. Install Zowe CLI. + +8. [Unlock the keyring manually](#unlocking-the-keyring-manually) or [unlock the keyring automatically](#unlocking-the-keyring-automatically)to load and store credentials. - **Important:** The SCS is installed every time that you install or update Zowe CLI. On RHEL V7.x, ensure that the Red Hat Developer Toolset is enabled every time you install or update Zowe CLI. When you do not enable the toolset, secure credential management is not available on the system. To ensure that the toolset is enabled when you install Zowe CLI, issue the following commands instead of the standard NPM install commands. For example: + :::info important + + The secure credential storage capability is installed every time that you install or update Zowe CLI. On RHEL V7.x, ensure that the Red Hat Developer Toolset is enabled every time you install or update Zowe CLI. When you do not enable the toolset, secure credential management is not available on the system. To ensure that the toolset is enabled when you install Zowe CLI, issue the following commands instead of the standard `npm install` commands. + ``` scl enable devtoolset-11 ‘npm install -g @zowe/cli@next’ scl enable devtoolset-11 ‘npm install -g zowe-cli.tgz’ ``` - When you run these commands, Zowe CLI is installed globally and the system will use the latest version of the C++ compiler to build the native components. Refer back to the instructions to set up the Secure Credential Storage component of the Zowe CLI. + When you run these commands, Zowe CLI installs globally and the system uses the latest version of the C++ compiler to build the native components. Refer back to the keyring unlocking instructions to set up the the Zowe CLI secure credential storage. + + ::: diff --git a/docs/user-guide/cli-configuringcli-ev.md b/docs/user-guide/cli-configuringcli-ev.md index 1496bc2d83..d221ba1f4c 100644 --- a/docs/user-guide/cli-configuringcli-ev.md +++ b/docs/user-guide/cli-configuringcli-ev.md @@ -2,17 +2,20 @@ This section explains how to configure Zowe CLI using environment variables. -By default, Zowe CLI configuration is stored on your computer in the `C:\Users\user01\.zowe` directory. The directory includes log files, profile information, and installed CLI plug-ins. When troubleshooting, refer to the logs in the `imperative` and `zowe` folders. +:::info Required roles: Security administrator, DevOps architect +::: + +By default, Zowe CLI configuration is stored on your computer in the `C:\Users\user01\.zowe` directory. The directory includes log files, profile information, and installed Zowe CLI plug-ins. When troubleshooting, refer to the logs in the `imperative` and `zowe` folders. :::note -For information on how to use environment variables to execute commands more efficiently, see [Using environment variables](cli-using-using-environment-variables.md). +For information on how to define Zowe CLI environment variables to execute commands more efficiently, see [Using environment variables](cli-using-using-environment-variables.md). ::: ## Setting the CLI home directory -You can set the location on your computer where Zowe CLI creates the *.zowe* directory, which contains log files, profiles, and plug-ins for the product: +You can set the location on your computer where Zowe CLI creates the `.zowe` directory, which contains log files, profiles, and plug-ins for the product. | Environment variable | Description | Values | Default | | ---------------------- | ----------- | ------ | ------- | @@ -26,7 +29,7 @@ A project administrator can pre-install, and update, a plug-in stored in the sha The plug-in directory must be defined before any Zowe CLI plug-ins are installed. -:::infoIMPORTANT +:::info Important Any plug-in installed before specifying the environment variable cannot be managed with Zowe CLI. To resolve this, re-install the plug-in after the environment variable is set. @@ -38,9 +41,9 @@ Any plug-in installed before specifying the environment variable cannot be manag ## Setting CLI log levels -You can set the log level to adjust the level of detail that is written to log files: +You can set the log level to adjust the level of detail that is written to log files. -:::infoIMPORTANT +:::warning Setting the log level to `TRACE` or `ALL` might result in sensitive data being logged. For example, command line arguments are logged when `TRACE` is set. @@ -53,23 +56,11 @@ Setting the log level to `TRACE` or `ALL` might result in sensitive data being l ## Setting CLI daemon mode properties -By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, the home directory resides on a network drive and has poor file performance. To change the location that the daemon uses, set the environment variables that are described in the following table: - -| Platform | Environment variable | Description | Values | Default | -| ---------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- | -| All | `ZOWE_DAEMON_DIR` | Lets you override the complete path to the directory that will hold daemon files related to this user. The directory can contain the following files:
  • `daemon.lock`
  • `daemon.sock`
  • `daemon_pid.json`
| Any valid path on your computer | `/.zowe/daemon`

**Examples:**

  • **Windows:** `%HOMEPATH%\.zowe\daemon`
  • **Linux:** `$HOME/.zowe/daemon`
| -| Windows (only) | `ZOWE_DAEMON_PIPE` | Lets you override the last two segments of the name of the communication pipe between the daemon executable (.exe) and the daemon. | Any valid path on your computer | `\\.\pipe\%USERNAME%\ZoweDaemon +By default, the CLI daemon mode binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. For example, when the home directory resides on a network drive and has poor file performance. -## Setting other environment variables +To change the location that the daemon uses, set the environment variables that are described in the following table. | Platform | Environment variable | Description | Values | Default | | ---------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- | -| All | `ZOWE_V3_ERR_FORMAT` | For Zowe V2, reformats the message displayed in REST request errors so problem details, and service response and diagnostic information, display in a reader friendly manner. In Zowe V3, this will be the only error format used and this environment variable will not be available.| `TRUE`, `FALSE`, blank | blank | -| All | `CI` | Set by most Continuous Integration environments automatically. Set to any value, disables progress bars in Zowe CLI. | Any
(CI environment name, typically) | blank | -| All | `FORCE_COLOR` | For most CLI tools, sets the color depth to be used by the CLI on the terminal. Set to `0`, disables color and progress bars in Zowe CLI. Set to any other valid, non-blank value, enables color and progress bars in Zowe CLI.

See the subsequent Note regarding Zowe CLI daemon configuration. | `0`, `1`, `2`, `3`, `TRUE`, blank | blank | - -:::note - -When a user does not set `FORCE_COLOR` and uses the Zowe CLI daemon, the daemon determines if the terminal running the daemon supports colors and progress bars. If it does, the daemon automatically sets `FORCE_COLOR` to a supported setting in all requests sent to the Zowe CLI daemon server component. - -::: +| All | `ZOWE_DAEMON_DIR` | Lets you override the complete path to the directory that will hold daemon files related to this user. The directory can contain the following files:
  • `daemon.lock`
  • `daemon.sock`
  • `daemon_pid.json`
| Any valid path on your computer | `/.zowe/daemon`

Examples:

Windows: `%HOMEPATH%\.zowe\daemon`
Linux: `$HOME/.zowe/daemon` | +| Windows (only) | `ZOWE_DAEMON_PIPE` | Lets you override the last two segments of the name of the communication pipe between the daemon executable (.exe) and the daemon. | Any valid path on your computer | `\\.\pipe\%USERNAME%\ZoweDaemon` diff --git a/docs/user-guide/cli-configuringcli-evfile.md b/docs/user-guide/cli-configuringcli-evfile.md index 86ce0ded33..3a7e2a9db4 100644 --- a/docs/user-guide/cli-configuringcli-evfile.md +++ b/docs/user-guide/cli-configuringcli-evfile.md @@ -2,11 +2,18 @@ If it is not possible to configure your own system environment variables, create a special configuration file to set these variables for Zowe CLI commands. +:::info Required roles: Security administrator, DevOps architect +::: + Although not common, there are cases where users do not have the ability to configure their own system environment variables. This can happen when users are working on hosted integrated development environments (IDEs), or in a highly locked down environment. When working under these kinds of restrictions, you can set environment variables that apply to CLI commands. To do this, create a `.zowe.env.json` file storing key-value pairs that specify your configurations. -**Note:** Use a `.zowe.env.json` file *only* when it is not possible to set your own system environment variables. If you are able to configure environment variables in your system, continue to do so. +:::note + +Use a `.zowe.env.json` file *only* when it is not possible to set your own system environment variables. If you are able to configure environment variables in your system, continue to do so. + +::: ## How `.zowe.env.json` works @@ -20,15 +27,13 @@ If an existing environment variable is set in your system and the variable is al ## Creating the configuration file -Create a dedicated JSON file to store settings for environment variables. - -Follow these steps: +Create a dedicated JSON file to store settings for environment variables: -1. In your Files Explorer, go to the home directory (%HOMEPATH% for Windows, $HOME for Linux and Mac) or the path set in the `ZOWE_CLI_HOME` environment variable. +1. In your Files Explorer, go to the home directory (`%HOMEPATH%` for Windows, `$HOME` for Linux and Mac) or the path set in the `ZOWE_CLI_HOME` environment variable. 2. Create a JSON file titled `.zowe.env.json`. -3. Use an IDE to open `.zowe.env.json` and enter environment variables, as in the following example: +3. Use a text editor to open `.zowe.env.json` and enter environment variables, as in the following example: ``` { @@ -43,7 +48,11 @@ Follow these steps: } ``` - **NOTE:** If you have the `ZOWE_CLI_HOME` environment variable set in your system, do not include it in the `.zowe.env.json` file. Otherwise, unexpected behavior can occur. + :::note + + If you have the `ZOWE_CLI_HOME` environment variable set in your system, do not include it in the `.zowe.env.json` file. Otherwise, unexpected behavior can occur. + + ::: ## Using daemon mode diff --git a/docs/user-guide/cli-db2-install-m1.md b/docs/user-guide/cli-db2-install-m1.md index 9dc060b1f5..aeb222c9f7 100644 --- a/docs/user-guide/cli-db2-install-m1.md +++ b/docs/user-guide/cli-db2-install-m1.md @@ -1,4 +1,4 @@ -# M1 processor installation +# Apple Silicon processor installation for IBM Db2 Database Plug-in The IBM ODBC DB2 driver functions only on MacOS x86_64 architecture. @@ -31,8 +31,12 @@ Use the following steps to configure an M1 (or later architecture) processor to 5. Reinstall Zowe CLI. 6. After you complete these steps, do one of the following: - - If you are installing the plug-in from an online registry, continue with Step 2 in [Install from an online registry](.//cli-db2plugin.md#installing-from-an-online-registry). + - If you are installing the plug-in from an online registry, continue with Step 2 in [Installing from an online registry](.//cli-db2plugin.md#installing-from-an-online-registry). - If you are installing the plug-in from a local package, continue with Step 2 in [Installing from a local package](../user-guide/cli-db2plugin.md#installing-from-a-local-package). -**Important!** You must issue the `intel` command **every time** that you open a new terminal window to help ensure that Zowe CLI, Secure Credential Storage and the DB2 plug-in function properly on x86_64 architecture. Also, issue the command **before** you issue Zowe CLI commands. \ No newline at end of file +:::warning Important + +You must issue the `intel` command every time that you open a new terminal window to ensure that the DB2 plug-in functions properly on x86_64 architecture. + +::: diff --git a/docs/user-guide/cli-db2plugin.md b/docs/user-guide/cli-db2plugin.md index a41dd9c179..1e8c66fdb9 100644 --- a/docs/user-guide/cli-db2plugin.md +++ b/docs/user-guide/cli-db2plugin.md @@ -13,13 +13,15 @@ As an application developer, you can use Zowe CLI Plug-in for IBM Db2 Database t - Export tables to a local file on your computer in SQL format. - Call a stored procedure and pass parameters. -## Commands +## Using commands -For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help. It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file containing the HTML for the online version. +For detailed documentation on commands, actions, and options available in this plug-in, see our web help. -- Browse Online -- Download (ZIP) -- Download (PDF) +There are several methods to view Zowe CLI web help: + +- Use a web browser +- Extract from a ZIP file +- Download a PDF file ## Software requirements @@ -36,15 +38,15 @@ Use one of the following methods to install the the Zowe CLI Plug-in for IBM Db2 Complete the following steps if you installed Zowe CLI from **online registry**: -1. If you are installing the plug-in on an Apple computer that contains an M1 (or later architecture) processor, complete the steps in [M1 processor installation](../user-guide/cli-db2-install-m1.md). If not, continue to Step 2. +1. If you are installing the plug-in on an Apple computer that contains an M1 (or later architecture) processor, complete the steps in [Apple Silicon processor installation](../user-guide/cli-db2-install-m1.md). If not, continue to Step 2. 2. Open a command line window and issue the following command: ``` - zowe plugins install @zowe/db2-for-zowe-cli@zowe-v2-lts + zowe plugins install @zowe/db2-for-zowe-cli@zowe-v3-lts ``` -2. [Address the license requirements](#addressing-the-license-requirement) to begin using the plug-in. +3. [Address the license requirements](#addressing-the-license-requirement) to begin using the plug-in. ### Installing from a local package @@ -54,11 +56,11 @@ Follow these procedures if you downloaded the Zowe installation package: Download the ODBC driver before you install the Db2 plug-in: -1. If you are installing the plug-in on a Apple computer that contains an M1 (or later architecture) processor, complete the steps in [M1 processor installation](../user-guide/cli-db2-install-m1.md). If not, continue to Step 2. +1. If you are installing the plug-in on an Apple computer that contains an M1 (or later architecture) processor, complete the steps in [Apple Silicon processor installation](../user-guide/cli-db2-install-m1.md). If not, continue to Step 2. 2. [Download the ODBC CLI Driver](https://github.com/ibmdb/node-ibm_db#-download-clidriver-based-on-your-platform--architecture-from-the-below-ibm-hosted-url). Use the table within the download URL to select the correct CLI Driver for your platform and architecture. -3. Create a new directory named `odbc_cli` on your computer. Remember the path to the new directory. You will need to provide the full path to this directory immediately before you install the Db2 plug-in. +3. Create a new directory named `odbc_cli` on your computer. Remember the path to the new directory. You need to provide the full path to this directory immediately before you install the Db2 plug-in. 4. Place the ODBC driver in the `odbc_cli` folder. **Do not extract the ODBC driver**. @@ -66,7 +68,7 @@ Download the ODBC driver before you install the Db2 plug-in: #### Installing Xcode on MacOS -To install the Db2 CLI plug-in on MacOS, you need the command line tools, which can be obtained by installing Xcode from the [App Store](https://medium.com/r/?url=https%3A%2F%2Fapps.apple.com%2Fus%2Fapp%2Fxcode%2Fid497799835%3Fmt%3D12). +To install the Db2 CLI plug-in on MacOS, you need the command line tools, which can be obtained by installing Xcode from the [App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12). :::note @@ -88,7 +90,7 @@ sudo xcode-select --install With the Db2 ODBC CLI driver downloaded, set the `IBM_DB_INSTALLER_URL` environment variable and install the Db2 plug-in to Zowe CLI: -1. Open a command line window and change the directory to the location where you extracted the `zowe-cli-bundle.zip` file. If you do not have the `zowe-cli-bundle.zip` file, see the topic **Install Zowe CLI from local package** in [Installing Zowe CLI](cli-installcli.md) for information about how to obtain and extract it. +1. Open a command line window and change the directory to the location where you extracted the `zowe-cli-plugins-.zip` file. If you do not have the `zowe-cli-bundle.zip` file, see [Installing Zowe CLI and Zowe CLI plug-ins from a local package](../user-guide/cli-installcli.md#installing-zowe-cli-and-zowe-cli-plug-ins-from-a-local-package) for information about how to obtain and extract it. 2. From a command line window, set the `IBM_DB_INSTALLER_URL` environment variable: @@ -115,13 +117,13 @@ With the Db2 ODBC CLI driver downloaded, set the `IBM_DB_INSTALLER_URL` environm zowe plugins install db2-for-zowe-cli.tgz ``` -4. [Address the license requirements](#addressing-the-license-requirement) to begin using the plug-in. +4. See [Addressing the license requirement](#addressing-the-license-requirement) to begin using the plug-in. You have installed the IBM Db2 Database Plug-in successfully. ## Addressing the license requirement -To successfully connect the Db2 CLI plug-in to a database on z/OS, a license needs to be present either on the client where the Zowe CLI is executed from, or else on z/OS. If you do not have a license configured when you execute Db2 CLI commands, you receive an error `SQL1598N`: +To successfully connect the Db2 CLI plug-in to a database on z/OS, a license needs to be present either on the client where the Zowe CLI is executed from, or on z/OS. If you do not have a license configured when you execute Db2 CLI commands, you receive the following error `SQL1598N`: ``` Db2 ODBC Driver Error: [node-ibm_db] SQL_ERROR @@ -160,87 +162,74 @@ If the utility `db2connectactivate` has not been executed against the Db2 databa ## Creating a user profile -You create a Db2 profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile: - -- Create plug-in profiles using a configuration file: Specify your profile and connection details in the `zowe.config.json` configuration file. +After you install the plug-in, create a Db2 profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. -- Create plug-in profiles using a command: Issue the `zowe profiles create` command to create the profile. - -We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing them in a future major release. +Specify your plug-in profile and connection details in the `zowe.config.json` configuration file. ### Creating plug-in profiles using a configuration file -When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the Db2 plug-in, the commands create an entry for a `db2 profile` in your `zowe.config.json` file. +When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the Db2 plug-in and then issue a command, the command creates an entry for a `db2 profile` in your `zowe.config.json` file. Alternatively, you can create a Db2 profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file: -1. Browse to the following directory: `C:\Users\\.zowe` - -2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ. - - :::note - - If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc` +#### Creating a Db2 profile with a command - ::: +1. Install the IBM Db2 Database Plug-in for Zowe CLI. +2. Create a Db2 profile: -3. Add code to the "profiles" section as shown in the following example: ``` - "Your_db2_profile": { - "type": "db2", - "properties": { - "host": "Your_host_name", - "port": Your_port_number, - "database": “Your_database” - }, - "secure": [ - "user", - "password" - ] - } + zowe config init ``` +3. Set the port number to the port configured for a Db2 connection on your mainframe. -4. Save the file. - - You can now use your profile when you issue commands in the `zowe db2` command group. - -### Creating plug-in profiles using a command - -Create a profile using the `zowe profiles create` command: - -1. Open a terminal window and issue the following command: ``` - zowe profiles create db2 –-host --port --user --password --region-name + zowe config set profiles.db2.properties.port ``` - **`profile_name`** + - `` - Specifies a name for your profile. + Specifies the port number for the instance. +4. If an SSL file is available, set the `sslFile` value to SSL file path: - **`host`** - - Specifies the host name for the instance. - - **`user`** - - Specifies your user name to log in to the instance. + ``` + zowe config set profiles.db2.properties.sslFile + ``` + You can now use your profile when you issue commands in the Db2 command group. - **`password`** +#### Creating a Db2 profile manually - Specifies your password to log in to the instance. +1. Install the Db2 Plug-in for Zowe CLI. - **`port`** +2. Browse to the directory `C:\Users\\.zowe`. - Specifies the port number to connect to the instance. +3. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ IDEA. - **`database`** + :::note + + If the file does not exist, issue the following command to create the configuration file: + ``` + zowe config init --gc + ``` + + ::: - Specifies the database to use on the instance. +4. Add code to the "profiles" section as shown in the following example: - **Example:** ``` - zowe profiles create db2-profile database1 --host db2.zowe.org --port 25000 --user zowe --password zowepass --database zowedb + "Your_db2_profile": { + "type": "db2", + "properties": { + "host": "Your_host_name", + "port": Your_port_number, + "database": “Your_database” + }, + "secure": [ + "user", + "password" + ] + } ``` -2. Press `Enter`. The result of the command displays as a success or failure message. - You can now use your profile when you issue commands in the `zowe db2` command group. +5. Save the file. + + You can now use your profile when you issue commands in the Db2 command group. diff --git a/docs/user-guide/cli-extending.md b/docs/user-guide/cli-extending.md index b36b135102..95de753200 100644 --- a/docs/user-guide/cli-extending.md +++ b/docs/user-guide/cli-extending.md @@ -1,27 +1,11 @@ # Zowe CLI plug-ins -You can install plug-ins to extend the capabilities of Zowe™ CLI. Plug-ins CLI to third-party applications are also available, such as Visual Studio Code Extension for Zowe (powered by Zowe CLI). Plug-ins add functionality to the product in the form of new command groups, actions, objects, and options. +You can install plug-ins to extend the capabilities of Zowe™ CLI. CLI Plug-ins for third-party applications are also available. + +Plug-ins add functionality to the product in the form of new command groups, actions, objects, and options. :::info Important Plug-ins can gain control of Zowe CLI legitimately during the execution of every command. Install third-party plug-ins at your own risk. ::: - -- [Installing Zowe CLI plug-ins](cli-installplugins.md) -- [IBM® CICS Plug-in for Zowe CLI](cli-cicsplugin.md) -- [IBM® Db2® Database Plug-in for Zowe CLI](cli-db2plugin.md) -- [IBM® z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) -- [IBM® MQ Plug-in for Zowe CLI](cli-mqplugin.md) -- [IDF Plug-in for Zowe CLI](cli-idfplugin.md) -- [Visual Studio Code (VSCode) Extension for Zowe](ze-install.md) - -- [IBM® IMS™ Plug-in for Zowe CLI](cli-imsplugin.md) - - :::warning - - As of Zowe v2.15, the **IBM IMS Plug-in** has been deprecated. - - No additional security updates, bug fixes, or enhancements for the plug-in are expected. - - ::: diff --git a/docs/user-guide/cli-ftpplugin.md b/docs/user-guide/cli-ftpplugin.md index 1d21c5e68d..8f4e4821ce 100644 --- a/docs/user-guide/cli-ftpplugin.md +++ b/docs/user-guide/cli-ftpplugin.md @@ -1,29 +1,31 @@ # IBM® z/OS FTP Plug-in for Zowe CLI -The IBM® z/OS FTP Plug-in for Zowe™ CLI lets you extend Zowe CLI to access z/OS datasets, USS files, and submit JCL. The plug-in uses the z/OS FTP service to achieve the interaction with z/OS. +The IBM® z/OS FTP Plug-in for Zowe™ CLI lets you extend Zowe CLI to access z/OS data sets, USS files, and submit JCL. The plug-in uses the z/OS FTP service to achieve the interaction with z/OS. ## Use cases As a z/OS user, you can use the plug-in to perform the following tasks: - - List, view, rename, and download z/OS datasets or USS files. - - Upload local files or `stdin` to z/OS datasets or USS files. + - List, view, rename, and download z/OS data sets or USS files. + - Upload local files or `stdin` to z/OS data sets or USS files. - List, view, and download job status or job spool files. - - Delete a z/OS dataset, USS file, or job. + - Delete a z/OS data set, USS file, or job. -## Commands +## Using commands -::: +:::caution important When transferring files, data sets, or data set members, use only ASCII characters. If a file contains non-ASCII characters (such as glyphs or mathematical symbols), a translation error can happen when the file is downloaded from, or uploaded to, the mainframe. This error can result in data loss. ::: -For detailed documentation on commands, actions, and options available in this plug-in, see the Web Help. It is available for download in the following formats: +For detailed documentation on commands, actions, and options available in this plug-in, see our web help. + +There are several methods to view Zowe CLI web help: -- Browse the online Web Help -- Download the ZIP file -- Download the PDF document +- Use a web browser +- Extract from a ZIP file +- Download a PDF file ## Software requirements @@ -34,96 +36,83 @@ Before you install the plug-in, meet the [Software requirements for Zowe CLI plu Use one of the following methods to install or update the plug-in: - [Installing plug-ins from an online registry](cli-installplugins.md#installing-plug-ins-from-an-online-registry) - - [Installing plug-ins from a local package](cli-installplugins.md#installing-plug-ins-from-a-local-package) ## Creating a user profile -You create a zftp profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile: +After you install the plug-in, create an FTP profile. An FTP profile is recommended to issue commands via FTP. FTP profiles contain your host, port, user name, and password to connect to z/OS using FTP. You can create multiple profiles and switch between them as needed. -- **Create plug-in profiles using a configuration file:** Specify your profile and connection details in the `zowe.config.json` configuration file. +### Creating plug-in profiles using a configuration file -- **Create plug-in profiles using a command:** Issue the `zowe profiles create` command to create the profile. +If you have the IBM® z/OS FTP plug-in installed and issue the `zowe config init`, `zowe config auto-init`, or `zowe config convert-profiles` command, the command creates an entry for a FTP profile in your `zowe.config.json file`. -We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing them in a future major release. +Alternatively, you can create an FTP profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file. -### Creating plug-in profiles using a configuration file +#### Creating an FTP profile with a command -When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the z/OS FTP plug-in, the commands create an entry for a `zftp profile` in your `zowe.config.json` file. +1. Install the z/OS FTP Plug-in for Zowe CLI. +2. Create an FTP profile: -Alternatively, you can create a zftp profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file. + ``` + zowe config init + ``` +3. If using a non-standard port, set the port number to your FTP connection: -1. Browse to the following directory: `C:\Users\\.zowe` + ``` + zowe config set profiles.zftp.properties.port + ``` -2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ. + - `` - NOTE: If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc` + Specifies the port number for the instance. +4. If using an insecure connection, set the `secureFtp` value to `false`: -3. Add code to the "profiles" section as shown in the following example: - ``` - "Your_zftp_profile": { - "type": "zftp", - "properties": { - "host": "Your_host_name", - "port": Your_port_number, - "secureFtp": true - }, - "secure": [ - "user", - "password" - ] - } + zowe config set profiles.zftp.properties.secureFtp false ``` - **Note:** The value of the “`secureftp`" option is defined as true by default. We recommend that you specify this value when FTPS (FTP over SSL) is enabled in the z/OS FTP service. FTPS is not equivalent to SFTP (FTP over SSH). SFTP is not currently supported. + You can now use your profile when you issue commands in the zftp command group. -4. Save the file +#### Creating an FTP profile manually -You can now use your profile when you issue commands in the zftp command group. +1. Install the z/OS FTP Plug-in for Zowe CLI. -### Creating plug-in profiles using a command +2. Browse to the directory `C:\Users\\.zowe`. -The following steps describe how to create a profile using the `zowe profiles create` command. +3. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ IDEA. -1. Open a terminal window and issue the following command: + :::note + + If the file does not exist, issue the following command to create the configuration file: ``` - zowe profiles create zftp --host --port --user --password + zowe config init --gc ``` + + ::: + +4. Add code to the "profiles" section as shown in the following example: **[is this code correct? should this code include a `secureFtp` value?]** - **`profile_name`:** - - Specifies a name for your profile. - - **`host`:** - - Specifies the host name for the instance. - - **`user`:** - - Specifies your user name to log in to the instance. - - **`password`:** - - Specifies your password to log in to the instance. - - **`port`:** - - Specifies the port number to connect to the instance. - - **Example:** ``` - zowe profiles create zftp-profile LPAR1 --host ftp.zowe.org --port 21 --user zowe --password zowepass --secure-ftp + "Your_ftp_profile": { + "type": "ftp", + "properties": { + "host": "Your_host_name", + "port": Your_port_number, + "secureFtp": true + }, + "secure": [ + "user", + "password" + ] + } ``` -2. Press Enter. The result of the command displays as a success or failure message. - - **Note:** The command contains an option named `--secure-ftp` that is defined as true by default. We recommend that you specify this value when FTPS (FTP over SSL) is enabled in the z/OS FTP service. FTPS is not equivalent to SFTP (FTP over SSH). +5. Save the file. -You can now use your profile when you issue commands in the zftp command group. + You can now use your profile when you issue commands in the zftp command group. ### Issuing test commands -After installing the plugin successfully, you can issue commands to test basic Zowe CLI functionality. +After installing the plug-in successfully, you can issue commands to test basic Zowe CLI functionality. For example, you can use one of the following methods to download a data set: @@ -133,5 +122,17 @@ For example, you can use one of the following methods to download a data set: ``` - Download a data set without using a default profile: ``` - zowe zftp download data-set USERHLQ.DATASET.NAME --host --port 21 --user --password --secure-ftp false - ``` \ No newline at end of file + zowe zftp download data-set USERHLQ.DATASET.NAME --host --port 21 --user --password --secure-ftp false + ``` + + - `` + + Specifies the host name for the instance. + + - `` + + Specifies your user name to log in to the instance. + + - `` + + Specifies your password to log in to the instance. diff --git a/docs/user-guide/cli-imsplugin.md b/docs/user-guide/cli-imsplugin.md deleted file mode 100644 index f080089017..0000000000 --- a/docs/user-guide/cli-imsplugin.md +++ /dev/null @@ -1,135 +0,0 @@ -# IBM® IMS™ Plug-in for Zowe CLI - -:::warning - -As of Zowe v2.15, the IBM **IMS Plug-in** has been deprecated. - -No additional security updates, bug fixes, or enhancements for the plug-in are expected. - -::: - -The IBM IMS Plug-in for Zowe CLI lets you extend Zowe CLI such that it can interact with IMS resources (regions, programs and transactions). You can use the plug-in to start, stop, and query regions and start, stop, query, and update programs and transactions. - -:::note - -For more information about IMS, see [IBM Information Management System (IMS)](https://www.ibm.com/it-infrastructure/z/ims) on the IBM Knowledge Center. - -::: - -## Use cases - -As an application developer or DevOps administrator, you can use IBM IMS Plug-in for Zowe CLI to perform the following tasks: - -- Refresh IMS transactions, programs, and dependent IMS regions. -- Deploy application code into IMS production or test systems. -- Write scripts to automate IMS actions that you traditionally perform using ISPF editors, TSO, and SPOC. - -## Commands - -For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help. It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file containing the HTML for the online version. - -- Browse Online -- Download (ZIP) -- Download (PDF) - -## Software requirements - -Before you install the plug-in, meet the software requirements in [Software requirements for Zowe CLI plug-ins](cli-swreqplugins.md). - -## Installing - -Use one of the following methods to install or update the plug-in: - -- [Installing plug-ins from an online registry](cli-installplugins.md#installing-plug-ins-from-an-online-registry) - -- [Installing plug-ins from a local package](cli-installplugins.md#installing-plug-ins-from-a-local-package) - -## Creating user profiles - -You create an IMS profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile: - -- **Create plug-in profiles using a configuration file:** Specify your profile and connection details in the `zowe.config.json` configuration file. - -- **Create plug-in profiles using a command:** Issue the `zowe profiles create` command to create the profile. - -We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing them in a future major release. - -### Creating plug-in profiles using a configuration file - -When you issue various `zowe config` commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the z/OS IMS plug-in, the commands create an entry for an `ims profile` in your `zowe.config.json` file. - -Alternatively, you can create an ims profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file. - -1. Browse to the following directory: `C:\Users\\.zowe` - -2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ. - - :::note - - If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc` - - ::: - -3. Add code to the "profiles" section as shown in the following example: - ``` - "Your_ims_profile": { - "type": "ims", - "properties": { - "host": "Your_host_name", - "port": Your_port_number, - "imsConnectHost": “Your_ims_connect_host_name”, - “imsConnectPort”: Your_ims_connect_port_number - }, - "secure": [ - "user", - "password" - ] - } -4. Save the file - -You can now use your profile when you issue commands in the ims command group. - -### Creating plug-in profiles using a command - -The following steps describe how to create a profile using the `zowe profiles create` command. - -1. Open a terminal window and issue the following command: - ``` - zowe profiles create ims --host --port --user --password --ims-connect-port --ims-connect-host - ``` -- **`profile_name`:** - - Specifies a name for your profile. -- **`host`:** - - - Specifies the host name for the instance. -- **`user`:** - - - Specifies your user name to log in to the instance. -- **`password`:** - - - Specifies your password to log in to the instance. -- **`port`:** - - - Specifies the port number to connect to the instance. -- **`ims_host`:** - - - Specifies the host name to connect to the IMS Connect instance. -- **`ims_port`:** - - - Specifies the port number to connect to the IMS Connect instance. - - **Example:** - ``` - zowe profiles create ims-profile imsplex1 --host ims.zowe.org –-port 1443 --user zowe --password zowepass --ims-connect-host imsconnect.zowe.org --ims-connect-port 1444 - ``` - -2. Press `Enter`. The result of the command displays as a success or failure message. - -You can now use your profile when you issue commands in the ims command group. \ No newline at end of file diff --git a/docs/user-guide/cli-install-cli-checklist.md b/docs/user-guide/cli-install-cli-checklist.md index 13b7a2df36..a4cff40ade 100644 --- a/docs/user-guide/cli-install-cli-checklist.md +++ b/docs/user-guide/cli-install-cli-checklist.md @@ -1,48 +1,35 @@ -# Zowe CLI Installation checklist +# Zowe CLI installation checklist -The following checklists summarize the required steps for a base installation (_first-time installation_) in the order you should perform them. +This checklist outlines the required steps for a first-time installation of Zowe CLI. -The checklist includes a brief description of the steps, with links to the comprehensive information required for the installation. The checklist also identifies the roles that are typically required to complete the step, which enables the pre-installation planning team (systems administrator, DevOps architect, application developer, and so on) to focus on the tasks for which they are responsible. +:::info Required roles: systems administrator, devops architect, security administrator, systems programmer +::: -Use the Status column to track your progress. +The checklist includes a brief description of the steps required for installation of Zowe CLI. The checklist also identifies the roles that are typically required to complete the step, which enables the pre-installation planning team to focus on the tasks for which they are responsible. For a printable version of this checklist, click here. -## Addressing the prerequisites +## Preparing for installation -To plan your Zowe CLI installation, review the following checklist. +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +| Addressing [Zowe CLI software requirements](../user-guide/systemrequirements-cli.md) and [Zowe CLI plug-ins software requirements](../user-guide/cli-swreqplugins.md) | Check the following items:
  • Node.js
  • Node Package Manager (npm)
  • Disk space
  • Plug-in configuration
| Systems administrator | 15 min. | +| [Configuring your PC to install from an online registry by proxy](../user-guide/cli-install-configure-install-online-registry-proxy.md) | Configure log-in credential requirements in the NPM configuration file to use a proxy server to download Zowe CLI.| Systems administrator | 15 min. | +| [Configuring z/OSMF](../user-guide/cli-install-configure-zosmf.md) | Confirm that z/OS components, region sizes, and user IDs meet Zowe CLI requirements. | Systems programmer | 40 min. | +| [Configuring z/OSMF security](../user-guide/cli-install-configure-zosmf-security.md) | Configure security for:
  • SAF access to REST endpoints
  • z/OS console REST interface
  • z/OS data set and file REST services
| Security administrator| 50 min.| -| Step | Description | Role | Time Estimate | Status | -| ----------- | ----------- | ---------- | ------------- | ---------- | -| [Review the Zowe CLI information roadmap](../user-guide/user-roadmap-zowe-cli.md) | Learn about various Zowe CLI topics | Systems administrator, application developer, systems programmer, DevOps architect | **.25** hrs | | -| [Review the release notes](../whats-new/release-notes/release-notes-overview.md) | Read about new features and enhancements included with this release of Zowe CLI | Systems administrator, DevOps architect | **.25** hours | || Review the Zowe CLI installation methods | [Determine the installation package to use to install CLI](cli-installcli.md) | Systems administrator | **.25**hrs | | -| [Address the requirements](../user-guide/systemrequirements-cli.md) | Install the client-side and host-side software, and ensure that there is sufficient free disk space | Systems administrator | **See Note-1** | | -| [(Optional) Install API Mediation Layer](../user-guide/install-zos.md) | Install the Zowe Runtime, which includes API Mediation Layer | Systems administrator | **8** hrs | | -| [Install z/OSMF](https://www.ibm.com/docs/en/zos/2.3.0?topic=configuration-setting-up-zosmf-first-time) | Follow the steps to install z/OSMF | Systems administrator | **See Note-2** | | -| [Determine the profile types that you want to use](../user-guide/cli-using-using-team-profiles) | Learn about configuration and how to use team profiles | Systems administrator, DevOps architect | **.25** hrs | | +## Installing Zowe CLI and Zowe CLI plug-ins -**Note-1:** Allow **.25** hours to install the client-side software. The amount of time to install the host-side software depends upon your site's implementation. For example, do you require z/OSMF, REST APIs, or both, to support the Mediation Layer? See the information for the specific server-side software that you require to determine how much time to allow for complete server-side installation and configuration. +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +| Installing Zowe CLI and Zowe CLI plug-ins from [a local package](../user-guide/cli-installcli.md#installing-zowe-cli-and-zowe-cli-plug-ins-from-a-local-package) or
[an NPM public online registry](../user-guide/cli-installcli.md#installing-zowe-cli-and-zowe-cli-plug-ins-from-an-npm-online-registry) | Install Zowe CLI from an online registry or a local package.| Systems administrator | 30 min. | +| [Updating Zowe CLI and Zowe CLI plug-ins](../user-guide/cli-updatingcli.md) | Identify the currently installed version of Zowe CLI and update to the most recent version. Or, revert to a specific previous release of Zowe CLI. | Systems administrator | 30 min. | -**Note-2:** Allow **15** to **25** hours to install and configure z/OSMF. The length of time varies depending on the External Security Manager (ESM) that you are running in your site. - -You are now ready to install Zowe CLI! -## Installing Zowe CLI - -To install Zowe CLI, review the following checklist. - -| Step | Description | Role | Time Estimate | Status | -| ----------- | ----------- | ---------- | ------------- | ---------- | -| [Install Zowe CLI](../user-guide/cli-installcli.md) | Install Zowe CLI from an online registry or a local package | Systems administrator | **.5** hrs | | -| [Install Zowe CLI (quick start)](../getting-started/cli-getting-started.md) | Use the Quick Start method if you possess prerequisite knowledge of command line tools and writing scripts, and you want to get started with Zowe CLI quickly and easily. | Systems administrator | **.25** hrs | | -| [(Optional) Install Zowe CLI plug-ins](../user-guide/cli-installplugins.md) | Install Zowe CLI plug-ins from an online registry or a local package. | Systems administrator | **.25** hrs | | - -You are now ready to configure Zowe CLI! ## Configuring Zowe CLI -To configure Zowe CLI, review the following checklist. - -| Step | Description | Role | Time Estimate | Status | -| ----------- | ----------- | ---------- | ------------- | ---------- | -| [Configure environment variables](../user-guide/cli-configuringcli-ev.md) | Learn how to store configuration options that are common to your environment. | Systems administrator, DevOps architect, application developer | **.25** hrs | | -| [Configure Zowe profiles](../user-guide/cli-using-initializing-team-configuration.md) | Learn how to configure Zowe team profiles and user profiles. | Systems administrator, DevOps architect, application developer | **.25** hrs | | -| [Configure daemon mode](../user-guide/cli-using-using-daemon-mode.md) | Learn how to configure Zowe CLI to run as persistent background process (daemon). | Systems administrator, DevOps architect, application developer | **.25** hrs | | +| Step | Description | Role | Time Estimate | +| ----------- | ----------- | ---------- | ------------- | +| [Configuring Zowe CLI environment variables](../user-guide/cli-configuringcli-ev.md) | Set the location of the CLI home directory to contain log files, profiles, and other files.

Set log levels to adjust the detail included in log files.

Set CLI daemon mode properties. | Security administrator and/or
DevOps architect | 15 min. | +| [Initializing team configuration](../user-guide/cli-using-initializing-team-configuration.md) | Create team profiles to streamline profile management in one location:

  • Create service profiles to store connection information for a specific mainframe service.
  • Create base profiles to store connection information used with one or more services.
| Security administrator and/or
DevOps architect | 15 min. | +| [Configuring daemon mode](../user-guide/cli-using-using-daemon-mode.md) | Enable daemon mode and configure daemon mode properties to run Zowe CLI commands significantly faster. | Security administrator and/or
DevOps architect | 15 min | +| [Verifying your Zowe CLI installation](../user-guide/cli-install-verify-your-installation) | Confirm the connection to z/OSMF.
Access the product help. | Systems administrator and/or
DevOps architect| 15 min. | diff --git a/docs/user-guide/cli-install-cli-nodejs-windows.md b/docs/user-guide/cli-install-cli-nodejs-windows.md deleted file mode 100644 index a9e2c5454f..0000000000 --- a/docs/user-guide/cli-install-cli-nodejs-windows.md +++ /dev/null @@ -1,20 +0,0 @@ -# Installing Zowe CLI with Node.js 16 on Windows - -There are several preferred installation workarounds when you encounter the following scenarios: - -- Using Node.js version 16 with npm version 8 on Windows, want to install from the TGZ, and have restricted Internet access -- Unable to install Zowe CLI while offline using the TGZ bundle - -The workaround installation options are, in order of preference: - -- Configure NPM proxy to access the public NPM registry (npmjs.org) so that the install from TGZ can succeed. To configure an NPM proxy: - - If your proxy is HTTP: `npm config set proxy ` - - If your proxy is HTTPS: `npm config set https-proxy ` -- Install CLI from an online registry instead of TGZ. This may also require configuring an NPM proxy. See [Install Zowe CLI from online registry via proxy](install-cli-via-proxy.md). -- Downgrade NPM to version 6. To downgrade from a newer version of NPM, issue the command: `npm install -g npm@6.x` - -## Additional Considerations - -There are issues with Node 16 and bundled optional dependencies in offline node installs. Because of the issues, the optional `cpu-features` package was removed from the offline .tgz file that is available from zowe.org and Broadcom. The installation process attempts to reach a configured registry and to use any NPM proxy configured on the system. If the attempt fails, the installation process completes normally. - -`cpu-features` changes the SSH cipher order that is used on the `zowe uss issue ssh` commands, favoring `chacha20-poly1305` cipher in cases where CPUs do not have built in AES instructions. This should not affect performance. diff --git a/docs/user-guide/cli-install-configure-install-online-registry-proxy.md b/docs/user-guide/cli-install-configure-install-online-registry-proxy.md new file mode 100644 index 0000000000..b059d87019 --- /dev/null +++ b/docs/user-guide/cli-install-configure-install-online-registry-proxy.md @@ -0,0 +1,85 @@ +# Configuring your PC to install from an online registry by proxy + +You can install Zowe CLI and Zowe CLI plug-ins from an online registry using a proxy server on Windows, macOS, or Linux operating systems. + +:::info Required role: systems administrator +::: + +If your site functions behind a proxy server and blocks access to public registries, complete the following steps before you install Zowe CLI core and Zowe CLI plug-ins from your desired online registry. + +1. Contact your site administrator and obtain the IP address and port number to your proxy server. + +2. Configure your NPM configuration file using one of the following methods: + + - If your proxy server **does not require** login credentials: + + Issue one of the following commands to add to the URL for the proxy server to your NPM configuration file. + + For `HTTPS` protocol: + + ``` + npm config set https-proxy http://proxy.[proxy_name].com:[port_number] + ``` + + For `HTTP` protocol: + + ``` + npm config set proxy http://proxy.[proxy_name].com:[port_number] + ``` + + - `https-proxy` + + Specifies to communicate with the proxy server using https communication. + + - `proxy` + + Specifies to communicate with the proxy server using http communication. + + - `[proxy_name]` + + Specifies the IP address or the host name of the proxy server. + + - `[port_number]` + + Specifies the port number of the proxy server. + + - If your proxy server **requires** login credentials: + + Issue one of the following commands to add the URL for the proxy server and your login credentials to your NPM configuration file. + + For `HTTPS` protocol: + + ``` + npm config set https-proxy https://[username]:[password]@proxy.[proxy_name].com:[port_number] + ``` + + For `HTTP` protocol: + ``` + npm config set proxy http://[username]:[password]@proxy.[proxy_name].com:[port_number] + ``` + + - `https-proxy` + + Specifies to communicate with the proxy server using https communication. + + - `proxy` + + Specifies to communicate with the proxy server using http communication. + + - `[username]` + + Specifies the user name to log in to the proxy server. + + - `[password]` + + Specifies the password to log in to the proxy server. + + - `[proxy_name]` + + Specifies the IP address or the host name of the proxy server. + + - `[port_number]` + + Specifies the port number of the proxy server. + +3. Install Zowe CLI and Zowe CLI plug-ins from an NPM public online registry. diff --git a/docs/user-guide/cli-install-configure-zosmf-security.md b/docs/user-guide/cli-install-configure-zosmf-security.md new file mode 100644 index 0000000000..789f2fd523 --- /dev/null +++ b/docs/user-guide/cli-install-configure-zosmf-security.md @@ -0,0 +1,66 @@ +# Configuring z/OSMF Security + +Review the tasks that security administrators must complete to configure z/OSMF security for your installation of Zowe client-side components. + +:::info Required role: security administrator +::: + +## Configuring z/OS REST services SAF security + +:::note + +If you are connecting to the mainframe with methods other than a z/OSMF profile, you do not need to configure z/OSMF security. Other connection options might include using FTP, or your custom API. + +::: + +A security administrator must configure security to allow z/OSMF System Authorization Facility (SAF) access to the resources that Zowe client-side components require. Zowe client-side components use REST endpoints that are associated with each z/OSMF REST API. After you complete all z/OSMF and z/OSMF cloud provisioning configurations, you can test your connection to z/OSMF to verify that your Zowe client-side components can communicate with z/OS systems. + +:::caution + +Before you allow users to issue z/OS console commands with Zowe client-side components, security administrators should ensure that they provide access to commands that are appropriate for their organization. + +::: + +The following table details the required z/OSMF REST services and examples of the features they enable. + + +| z/OSMF REST Service | REST Endpoint | Description | More information | +| ----------- | ----------- | ---------- | ------------- | +| Cloud provisioning services | Endpoints that begin with: `/zosmf/provisioning/` | Cloud provisioning for development environments (`zowe provisioning list instance-info`). |
  • Used by Zowe CLI
  • [Cloud provisioning services](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-cloud-provisioning)
| +| TSO/E address space services | Endpoints that begin with: `/zosmf/tsoApp` | TSO commands (`zowe zos-tso issue`). |
  • Used by Zowe CLI, Zowe Explorer
  • [TSO/E address space services](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-tsoe-address-space)
  • [Class activations that z/OSMF requires](https://www.ibm.com/docs/en/zos/2.5.0?topic=guide-security-structures-zosmf#DefaultSecuritySetupForZosmf__ResourceAuthorizationsForRESTapi__title__1)
| +| z/OS console services | Endpoints that begin with: `/zosmf/restconsoles/`
Example: `/zosmf/restconsoles/defcn` | Console commands (`zowe zos-console issue`). Any MVS console command such as MODIFY and DISPLAY. |
  • Used by Zowe CLI, Zowe Explorer
  • [z/OS console services](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-zos-console)
  • [Resource authorizations for the z/OS console services REST interface](https://www.ibm.com/docs/en/zos/2.5.0?topic=guide-security-structures-zosmf#DefaultSecuritySetupForZosmf__zOSConsolesRestAPI__title__1)
| +| z/OS data set and file REST interface | Endpoints that begin with: `/zosmf/restfiles/` Example: `/zosmf/restfiles/ds/` | Create data sets (`zowe zos-files create`), delete data sets (`zowe zos-files delete`), read (download) data sets (`zowe zos-files download`), and write (upload) data sets (`zowe zos-files upload`).
Access to access method services (IDCAMS) (`zowe zos-files invoke access-method-services`). |
  • Used by Zowe CLI, Zowe Explorer
  • [z/OS data set and file REST interface](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-zos-data-set-file-rest-interface)
  • [Resource authorizations for the z/OS data set and file REST interface](https://www.ibm.com/docs/en/zos/2.5.0?topic=guide-security-structures-zosmf#DefaultSecuritySetupForZosmf__ResourceAuthorizationsForRESTdsfilesAPI__title__1)
| +| z/OS jobs REST interface | Endpoints that begin with: `/zosmf/restjobs/` Example: `/zosmf/restjobs/jobs//` | Submit jobs (`zowe zos-jobs submit`), purge jobs, and read job output.
List jobs (`zowe zos-jobs list`). |
  • Used by Zowe CLI, Zowe Explorer
  • [z/OS jobs REST interface](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-zos-jobs-rest-interface)
  • [Resource authorizations for the z/OS jobs REST interface](https://www.ibm.com/docs/en/zos/2.5.0?topic=guide-security-structures-zosmf#DefaultSecuritySetupForZosmf__ResourceAuthorizationsForRESTapi__title__1)
| +| z/OSMF workflow services | Endpoints that begin with: `/zosmf/workflow/` | Cloud provisioning for development environments (`zowe zos-workflows list active-workflows`). |
  • Used by Zowe CLI
  • [z/OSMF workflow services](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-zosmf-workflow)
| + +## Configuring z/OS console REST interface + +Review the following recommendations for configuring the security for z/OS console REST services: + +- Add the COMMON_TSO statement to the IZUPRMxx parmlib member to customize the z/OSMF options for the logon procedure. +- Define a value of at least 50000 KB as the size of the address space for the user's logon procedure. To help you prevent system memory exception errors from occurring, confirm that this value is acceptable in your environment. +- Ensure that the members in your z/OSMF user security group can issue TSO and CONSOLE commands. IBM provides RACF statements for user group IZUUSER. To prevent all z/OSMF users from issuing TSO and CONSOLE commands, you can create more z/OSMF user groups for more granular security. +- Ensure that the OPERCMD class is active and that your MVS commands are protected. MVS commands include, but are not limited to, the MVS and MVS.MCSOPER resource prefixes. +- Ensure that the z/OSMF user security groups can access (authorized) the logon procedure name and account number that is specified in the COMMON_TSO statement. +- Define a TSO segment for all the z/OSMF users. + +## Configuring z/OS data set and file REST interface + +Review the following recommendations for configuring the z/OS security for data set and file REST services: + +- Add the COMMON_TSO statement to the RESTAPI_FILE parmlib member to customize the z/OSMF options for the logon procedure. +- Define a value of at least 65536 KB as the size of the address space for the user's logon procedure. To help you prevent system memory exception errors from occurring, confirm that this value is acceptable in your environment. +- Authorize z/OSMF user groups and the z/OSMF server to CEA TSO/E address space services. +- Ensure that the z/OSMF user security groups can access (authorized) the logon procedure name and account number that is specified on the COMMON_TSO statement. +- Define a TSO segment for all the z/OSMF users. +- Define at least 20971520 KB (20 MB) the IPCMSGQBYTES option of your parmlib member named BPXPRMxx. IBM recommends this value to let TSO and z/OSMF communicate using z/OS USS interprocess communications. + +## Configuring z/OSMF plug-in security +Ensure that you implement all the required security for the plug-ins. For more information, see [Setting up structures for z/OSMF](https://www.ibm.com/docs/en/zos/2.5.0?topic=guide-security-structures-zosmf) in the IBM Documentation. + +:::note + +- For systems that are secured by RACF, ensure that the TRUSTED attribute is assigned to the CEA started task. +- To enable Zowe client-side components to authenticate to z/OSMF using certificates, security administrators can configure the certificates for users of Zowe client-side components. For more information, see [Using the z/OSMF REST services](https://www.ibm.com/docs/en/zos/2.2.0?topic=guide-using-zosmf-rest-services) in the IBM Documentation. + +::: diff --git a/docs/user-guide/cli-install-configure-zosmf.md b/docs/user-guide/cli-install-configure-zosmf.md new file mode 100644 index 0000000000..7b9909ee50 --- /dev/null +++ b/docs/user-guide/cli-install-configure-zosmf.md @@ -0,0 +1,41 @@ +# Configuring z/OSMF + +For client-side components to communicate with the mainframe, z/OSMF requires configuration to make this happen. + +:::info Required role: systems programmer +::: + +Complete the following IBM z/OSMF configuration tasks for the implementation of [Zowe CLI](../user-guide/user-roadmap-zowe-cli.md), [Zowe Explorer for Visual Studio Code](../getting-started/user-roadmap-zowe-explorer.md), or the [Zowe Explorer plug-in for IntelliJ IDEA](../user-guide/intellij-configure.md). + +:::note + +If you are connecting to the mainframe with methods other than a z/OSMF profile, you do not need to configure z/OSMF. Other connection options might include using FTP, or your custom API. + +::: + +## Obtaining z/OSMF installation and configuration materials + +Before you start the configuration process, review [Overview of z/OSMF](https://www.ibm.com/docs/en/zos/2.5.0?topic=zosmf-overview) in the IBM Documentation. + +## Installing and configuring z/OSMF + +Zowe client-side components were designed and tested to integrate with z/OSMF running on IBM version 2.5 z/OS mainframe systems. To use Zowe client-side components, ensure that your z/OS system meets the requirements that are described in the following table: + +| Requirement | Description | +| ----------- | ----------- | +| AXR (System Rexx) | The AXR (System Rexx) component lets z/OS perform Incident Log tasks. It also lets REXX execs execute outside of conventional TSO and batch environments.
For more information, see [Communicating with System REXX](https://www.ibm.com/docs/en/zos/2.5.0?topic=command-communicating-system-rexx) on the IBM Documentation. | +| CEA (Communications Enabled Applications) Server | CEA server is a co-requisite for the CIM server. The CEA server lets z/OSMF deliver z/OS events to C-language clients.
z/OSMF requires the CEA server to perform the following types of tasks:
  • Problem determination
  • Sysplex
  • z/OS classic interfaces
  • z/OS Operator Console
**Notes:**
  • Start the CEA server before you start z/OSMF (the IZU* started tasks).
  • Set up CEA server in Full Function Mode and assign the TRUSTED attribute to the CEA started task.
For more information, see [Customizing for CEA](https://www.ibm.com/docs/en/zos/2.5.0?topic=test-customizing-cea) on the IBM Documentation. | +| CIM (Common Information Model) Server | z/OSMF requires the CIM server to perform the following types of tasks:
  • Capacity provisioning
  • Problem determination
  • Workload management
**Note:** Start the CIM server before you start z/OSMF (the IZU* started tasks).
For more information, see [Configuring the CIM server for your system](https://www.ibm.com/docs/en/zos/2.5.0?topic=configurations-configuring-cim-server-your-system) on the IBM Documentation.
For more information on how to perform asynchronous operations, review the [required authorizations for z/OSMF](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-zos-jobs-rest-interface#izuhpinfo_api_restjobs__RequiredAuthorizationsForRestServices__title__1) on the IBM Documntation.| +| Console Command | The `CONSOLE` and `CONSPROF` commands must exist in the authorized command table. | +| Java version | IBM® 64-bit SDK for z/OS®, Java™ Technology Edition V8 SR4 FP10 (5655-DGH) or higher is required. However, we experienced problems accessing z/OSMF 2.2 using Java version 8. If you use z/OSMF 2.3, Java version 8.0_64 is required.

For more information, see [Software prerequisites for z/OSMF](https://www.ibm.com/docs/en/zos/2.5.0?topic=zosmf-software-prerequisites) on the IBM Documentation. | +| Maximum region size | To prevent exceeds maximum region size errors, ensure that you have a TSO maximum region size of at least 65536 KB for the z/OS system. | +| User IDs | User IDs require a TSO segment (access) and an OMVS segment. During workflow processing and REST API requests, z/OSMF may start one or more TSO address spaces under the following job names:
  • *userid*
  • *substr(userid, 1, 6)//CN* (Console)
Example: ```(userid = USRMY01, USRMY0CN )``` + +## Selecting and configuring your z/OSMF plug-ins + +| Plug-in | Functionality | Task | +| ----------- | ----------- | ----------- | +| (Optional) Cloud Portal | The Cloud Portal plug-in lets you make software services available to marketplace consumers and it adds the Marketplace and Marketplace Administration tasks to the z/OSMF navigation tree. | For information about how to enable the plug-in, see [Cloud provisioning marketplace](https://www.ibm.com/docs/en/zos/2.5.0?topic=services-cloud-provisioning-marketplace) on the IBM Documentation. | +| Configuration Assistant | The Configuration Assistant plug-in lets z/OSMF configure TCP/IP policy-based networking functions.
For more information about the functionality that the plug-in provides, see [Network Configuration Assistant](https://www.ibm.com/docs/en/zos/2.5.0?topic=configuration-network-assistant-task-summary) and [Security Configuration Assistant](https://www.ibm.com/docs/en/zos/2.5.0?topic=configuration-security-assistant-task) on the IBM Documentation. | For information about how to enable the plug-in, see Updating z/OS for the [Configuration Assistant plug-in](https://www.ibm.com/docs/en/zos/2.2.0?topic=ins-updating-zos-configuration-assistant-plug-in) on the IBM Documentation. | +| ISPF | The ISPF plug-in lets z/OSMF access traditional ISPF applications.
For information about the functionality that the plug-in provides, see [ISPF task overview](https://www.ibm.com/docs/en/zos/2.5.0?topic=interfaces-ispf) on the IBM Documentation. | For information about how to enable the plug-in, see [Updating z/OS for the ISPF service](https://www.ibm.com/docs/en/zos/2.5.0?topic=service-updating-zos-ispf) on the IBM Documentation. | +| Workload Management | The Workload Management plug-in lets z/OSMF operate and manage workload management service definitions and policies.
For information about the functionality that the plug-in provides, see [Workload Management task overview](https://www.ibm.com/docs/en/zos/2.5.0?topic=performance-workload-management-task) on the IBM Documentation. | For information about how to enable the plug-in, see Updating z/OS for the [Updating z/OS for the Workload Management service](hhttps://www.ibm.com/docs/en/zos/2.5.0?topic=service-updating-zos-workload-management) on the IBM Documentation. | diff --git a/docs/user-guide/cli-install-verify-your-installation.md b/docs/user-guide/cli-install-verify-your-installation.md new file mode 100644 index 0000000000..38bbef04af --- /dev/null +++ b/docs/user-guide/cli-install-verify-your-installation.md @@ -0,0 +1,116 @@ +# Verifying your Zowe CLI installation + +Verify that Zowe CLI has been installed successfully by checking your connection to z/OSMF and accessing the in-product help. + +:::info Required roles: systems administrator, devops architect +::: + +:::note + +Use these commands to validate connection to z/OSMF, not user credentials. To confirm credentials, issue any fully qualified command, such as `zowe zos-files list data-set [options]`. + +::: + +## Testing connections to z/OSMF + +Issue a command at any time to receive diagnostic information from the server and confirm that Zowe CLI can communicate with z/OSMF or other mainframe APIs. + +Refer to the following sections for instructions on how to connect to z/OSMF with different types of profiles. + +:::info Important + +When z/OSMF receives a request via a Zowe CLI command, z/OSMF uses an SSL/TLS certificate to ensure a secure connection during the user session. + +In the event that your z/OSMF instance does not have a SSL/TLS certificate registered with a Certificate Authority (CA), use the `--reject-unauthorized` (or `--ru`) `false` flag to the end of each command listed here to bypass this security check. + +Determine the potential security risks. For the most secure environment, system administrators configure a server keyring with a server certificate signed by a CA. For more information, see [Working with certificates](../user-guide/cli-using-working-certificates.md). + +::: + +### Connecting to z/OSM without a profile + +Follow these steps when you have installed Zowe CLI but have not yet created a configuration file, or the configuration file has an incomplete profile for z/OSMF. + +1. Verify that your Zowe CLI instance can communicate with z/OSMF: + + ``` + zowe zosmf check status --host --port --user --pass + ``` + + - `` + + Specifies the host. + + - `` + + Specifies the port. + + - `` + + Specifies the username. + + - `` + + Specifies the password. + +2. Verify that the installed z/OSMF services are plug-ins listed in the response. + + You have confirmed that Zowe CLI is connected to z/OSMF. + +### Connecting to z/OSMF with a default profile + +Follow these steps when you have created a default profile in a configuration file (such as a [global team config](../user-guide/cli-using-initializing-team-configuration/)): + +1. Verify the default profile can communicate with z/OSMF: + + ``` + zowe zosmf check status + ``` + +2. Check that the installed z/OSMF services and plug-ins are listed in the response. + + You have confirmed that Zowe CLI is connected to z/OSMF. + +### Connecting to z/OSM with a specific profile + +Follow these steps when you have created a custom profile in a configuration (such as a [global team configuration file](../user-guide/cli-using-initializing-team-configuration/)). + +1. Verify that you can use that specific profile to communicate with z/OSMF: + + ``` + zowe zosmf check status --zosmf-profile + ``` + + - `` + + Specifies the name of the custom profile. + +2. Check that the installed z/OSMF services and plug-ins are listed in the response. + + You have confirmed that Zowe CLI is connected to z/OSMF. + +### Troubleshooting Zowe CLI connection + +The preceding commands return a success or failure message and display information about your z/OSMF server, such as the z/OSMF version number. Report failures to your systems administrator and use the response information for diagnostic purposes. + +## Accessing Zowe CLI help + +The in-product help is used as a reference of all the commands and plug-ins that are installed on the computer. If any part of the installation corrupts during installation, the help does not display. + +### Viewing top level Zowe CLI help + +1. To view top-level help: + + ``` + zowe --help + ``` + + Alternatively, to display a full list of all available commands: + + ``` + zowe --available-commands + ``` + +2. Verify that the help content displays and includes installed plug-ins. + + You have confirmed that you successfully installed Zowe CLI. diff --git a/docs/user-guide/cli-installcli copy.md b/docs/user-guide/cli-installcli copy.md new file mode 100644 index 0000000000..e32d6348dc --- /dev/null +++ b/docs/user-guide/cli-installcli copy.md @@ -0,0 +1,114 @@ +# Installing Zowe CLI + +Follow these guidelines to install Zowe™ CLI on your computer. + +:::info**Required role:** systems administrator +::: + +If you want to get started using Zowe CLI quickly, see [Zowe CLI quick start](../getting-started/cli-getting-started.md). You can learn about new CLI features in the [Release notes](../whats-new/release-notes/release-notes-overview.md). + +After you install Zowe CLI and Zowe CLI plug-ins using your preferred installation method, see [Using CLI](../user-guide/cli-using-usingcli.md) to learn about how to connect Zowe CLI to the mainframe, create Zowe CLI profiles and team profiles, integrate Zowe CLI with API ML, enable daemon mode, and much, much more! + +## Installation guidelines + + + +To install CLI on **Windows**, **Mac**, and **Linux** operating systems, follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a local package](#install-zowe-cli-from-a-local-package). + +To install Zowe CLI on **z/Linux**, **z/OS UNIX System Services (USS)**, or on an operating system where the **Secure Credential Store** is *not required* or *cannot be installed*, use the following installation guidelines: + +- To install Zowe CLI on a z/Linux operating system and you **require** the Secure Credential Store: + 1. Follow the steps in [Configure Secure Credential Store on headless Linux operating systems](./cli-configure-scs-on-headless-linux-os.md). + 2. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a download](#install-zowe-cli-from-a-download). +- To install Zowe CLI on a z/Linux operating system and you **do not require** the Secure Credential Store: + 1. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a download](#install-zowe-cli-from-a-download). + 2. Follow the steps in [Configure Zowe CLI on operating systems where the Secure Credential Store is not available](./cli-configure-cli-on-os-where-scs-unavailable.md). +- To install Zowe CLI on a USS system or on an operating system where you **cannot install** the Secure Credential Store: + 1. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a download](#install-zowe-cli-from-a-download). + 2. Follow the steps in [Configure Zowe CLI on operating systems where the Secure Credential Store is not available](./cli-configure-cli-on-os-where-scs-unavailable.md). + +### Installation notes + +- As you are installing Zowe CLI, you might encounter error messages that relate to `cpu-features` and `ssh`. You can safely ignore error messages of this type; the installation completes successfully. This behavior can occur when you install CLI from npm and from a local package. + +## Prerequisites + +- Meet the [software requirements](../user-guide/systemrequirements-cli.md) for Zowe CLI. +- Meet the [software requirements](../user-guide/cli-swreqplugins.md) for each plug-in. + +### Prerequisite notes + +- If you are installing Zowe CLI on a computer that is running Node.js 16 on a Windows operating system, see [Installing Zowe CLI with Node.js 16 on Windows](../user-guide/cli-install-cli-nodejs-windows.md). + +- If you are running NPM version 7 (`npm@7`) or NPM version 8 (`npm@8`) on a Windows operating system, ensure that your computer is connected to the Internet. + + Issue the following command ***before*** you install Zowe CLI: + + ``` + npm install -g prebuild-install + ``` + +- Linux users ***might*** need to prepend `sudo` to `npm` commands. For more information, see [Troubleshooting Zowe CLI](../troubleshoot/cli/troubleshoot-cli.md). + +## Install Zowe CLI from a local package + +Use the following procedure to install Zowe CLI from a local package: + +1. Meet the [prerequisites](#prerequisites) for installing Zowe CLI. + +2. Navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Core** button. + +3. Read the End User License Agreement for Zowe and click **I agree** to download the core package. + + `zowe-cli-package-.zip` is downloaded to your computer. + +4. **(Optional)** Meet the [prerequisites](#prerequisites) for installing Zowe CLI plug-ins. +5. **(Optional)** Navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Plugins** button to download the plug-ins. + +6. **(Optional)** Read the End User License Agreement for Zowe plug-ins and click **I agree** to download the plugins package. + + `zowe-cli-plugins-next-.zip` is downloaded to your computer. + +7. Unzip the contents of `zowe-cli-package-.zip` (and optionally `zowe-cli-plugins-.zip`) to a working directory. + +8. To install Zowe CLI Core, open a command-line window and issue the following commands to the working directory that you used in Step 7: + + ``` + npm install -g zowe-cli.tgz + ``` + + :::note + + If an `EACCESS` error displays, see [Resolving EACCESS permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) in the npm documentation. + + ::: + +9. **(Optional)** To install Zowe CLI plug-ins, issue the following command to the working directory that you used in Step 7: + + ``` + zowe plugins install cics-for-zowe-cli.tgz db2-for-zowe-cli.tgz zos-ftp-for-zowe-cli.tgz mq-for-zowe-cli.tgz + ``` + +Zowe CLI and the optional plug-ins are installed on your computer. Issue the `zowe --help` command to view a list of available commands. For information about how to connect the CLI to the mainframe, create profiles and team profiles, integrate with API ML, enable daemon mode, and more, see [Using CLI](../user-guide/cli-using-usingcli.md). + +## Install Zowe CLI from npm + +Use the following procedure to install Zowe CLI from an npm registry: + +1. To install or update the core CLI, open a command-line window: + + ``` + npm install -g @zowe/cli@zowe-v2-lts + ``` + + Zowe CLI is installed. + +2. (Optional) Address the [Software requirements for CLI plug-ins](../user-guide/cli-swreqplugins.md). You can install most plug-ins without meeting the requirements. However, the plug-ins will not function until you configure the back-end APIs. The IBM Db2 plug-in requires additional configuration to install. + +3. (Optional) To install all available plug-ins to Zowe CLI, issue the following command: + + ``` + zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts + ``` + +Zowe CLI is installed on your computer. Issue the `zowe --help` command to view a list of available commands. For information about how to connect the CLI to the mainframe, create profiles, integrate with API ML, and more, see [Using Zowe CLI](../user-guide/cli-using-usingcli.md). \ No newline at end of file diff --git a/docs/user-guide/cli-installcli.md b/docs/user-guide/cli-installcli.md index 4abff506eb..53f99d132c 100644 --- a/docs/user-guide/cli-installcli.md +++ b/docs/user-guide/cli-installcli.md @@ -1,109 +1,116 @@ -# Installing Zowe CLI +# Installing Zowe CLI and Zowe CLI plug-ins -Install Zowe™ CLI on your computer. +Follow these guidelines to install Zowe™ CLI on your computer. -If your role is that of a systems administrator or you are familiar with command-line tools and want to get started using Zowe CLI quickly, see [Zowe CLI quick start](../getting-started/cli-getting-started.md). You can learn about new CLI features in the [Release notes](../whats-new/release-notes/release-notes-overview.md). +:::info Required role: systems administrator +::: -After you install Zowe CLI and Zowe CLI plug-ins using your preferred installation method, see [Using CLI](../user-guide/cli-using-usingcli.md) to learn about how to connect Zowe CLI to the mainframe, create Zowe CLI profiles and team profiles, integrate Zowe CLI with API ML, enable daemon mode, and much, much more! -## Installation guidelines - -To install CLI on **Windows**, **Mac**, and **Linux** operating systems, follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a local package](#install-zowe-cli-from-a-local-package). +If you want to get started using Zowe CLI quickly, see [Zowe CLI quick start](../getting-started/cli-getting-started.md). You can learn about new CLI features in the [release notes](../whats-new/release-notes/release-notes-overview.md). -***However***, to install Zowe CLI on **z/Linux**, **z/OS UNIX System Services (USS)**, or on an operating system where the **Secure Credential Store** is ***not required*** or ***cannot be installed***, use the following installation guidelines: +:::note notes -- To install Zowe CLI on a z/Linux operating system and you **require** the Secure Credential Store: - 1. Follow the steps in [Configure Secure Credential Store on headless Linux operating systems](./cli-configure-scs-on-headless-linux-os.md). - 2. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a local package](#install-zowe-cli-from-a-local-package). -- To install Zowe CLI on a z/Linux operating system and you **do not require** the Secure Credential Store: - 1. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a local package](#install-zowe-cli-from-a-local-package). - 2. Follow the steps in [Configure Zowe CLI on operating systems where the Secure Credential Store is not available](./cli-configure-cli-on-os-where-scs-unavailable.md). -- To install Zowe CLI on a USS system or on an operating system where you **cannot install** the Secure Credential Store: - 1. Follow the steps in [Install Zowe CLI from npm](#install-zowe-cli-from-npm) or [Install Zowe CLI from a local package](#install-zowe-cli-from-a-local-package). - 2. Follow the steps in [Configure Zowe CLI on operating systems where the Secure Credential Store is not available](./cli-configure-cli-on-os-where-scs-unavailable.md). +- As you install Zowe CLI, you might encounter **error messages** that relate to `cpu-features` and `ssh`. You can safely ignore error messages of this type; the installation completes successfully. This behavior can occur when you install CLI from npm and also from a local package. -### Installation notes +- **Linux users** might need to prepend `sudo` to `npm` commands. For more information, see [Known Zowe CLI issues](../troubleshoot/cli/known-cli.md#sudo-syntax-required-to-complete-some-installations). -- As you are installing Zowe CLI, you might encounter error messages that relate to `cpu-features` and `ssh`. You can safely ignore error messages of this type; the installation completes successfully. This behavior can occur when you install CLI from npm and from a local package. +::: -## Prerequisites +## Installing Zowe CLI and Zowe CLI plug-ins from a local package -- Meet the [software requirements](../user-guide/systemrequirements-cli.md) for Zowe CLI. -- Meet the [software requirements](../user-guide/cli-swreqplugins.md) for each plug-in. +To install Zowe CLI from a local package: -### Prerequisite notes +1. Meet the [Zowe CLI software requirements](../user-guide/systemrequirements-cli.md). -- If you are installing Zowe CLI on a computer that is running Node.js 16 on a Windows operating system, see [Installing Zowe CLI with Node.js 16 on Windows](../user-guide/cli-install-cli-nodejs-windows.md). +2. Navigate to [Download Zowe](https://www.zowe.org/download.html). In the **Client-side component installer** section, click the **Zowe \ CLI Core** button (where \ specifies the release number). -- If you are running NPM version 7 (`npm@7`) or NPM version 8 (`npm@8`) on a Windows operating system, ensure that your computer is connected to the Internet. +3. Read the End User License Agreement for Zowe and click **I agree** to download the core package. + + `zowe-cli-package-next-YYYYMMDD.zip` is downloaded to your computer (where YYYYMMDD indicates the year, month, and day of the build). + +4. If installing Zowe CLI plug-ins, meet the [software requirements](../user-guide/cli-swreqplugins.md) to install Zowe CLI plug-ins. + +5. If installing Zowe CLI plug-ins, navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Plugins** button (where \ specifies the release number). - Issue the following command ***before*** you install Zowe CLI: +6. If installing Zowe CLI plug-ins, read the End User License Agreement for Zowe and click **I agree** to download the plug-ins package. + + `zowe-cli-plugins-next-YYYYMMDD.zip` is downloaded to your computer. + +7. Unzip the contents of `zowe-cli-package-.zip` (and `zowe-cli-plugins-.zip`, if downloaded) to a working directory. + +8. To install Zowe CLI core, open a command-line window and issue the following commands to the working directory that was used the previous step: ``` - npm install -g prebuild-install + npm install -g zowe-cli.tgz ``` -- Linux users ***might*** need to prepend `sudo` to `npm` commands. For more information, see [Troubleshooting Zowe CLI](../troubleshoot/cli/troubleshoot-cli.md). + :::note + + If an `EACCESS` error displays, see [Resolving EACCESS permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) in npm Docs. + + ::: +9. To install all available Zowe CLI plug-ins, issue the following command to the working directory that was used in Step 7: + + ``` + zowe plugins install cics-for-zowe-cli.tgz db2-for-zowe-cli.tgz zos-ftp-for-zowe-cli.tgz mq-for-zowe-cli.tgz + ``` -## Install Zowe CLI from npm + Zowe CLI and the optional plug-ins are installed on your computer. -Use the following procedure to install Zowe CLI from an npm registry: +## Installing Zowe CLI and Zowe CLI plug-ins from an npm online registry -1. To install or update the core CLI, open a command-line window: +To install Zowe CLI from an npm registry: + +1. To install Zowe CLI core, open a command-line window and issue the following command: ``` - npm install -g @zowe/cli@zowe-v2-lts + npm install -g @zowe/cli@zowe-v3-lts ``` Zowe CLI is installed. -2. (Optional) Address the [Software requirements for CLI plug-ins](../user-guide/cli-swreqplugins.md). You can install most plug-ins without meeting the requirements. However, the plug-ins will not function until you configure the back-end APIs. The IBM Db2 plug-in requires additional configuration to install. +2. If installing Zowe CLI plug-ins, meet the [software requirements](../user-guide/cli-swreqplugins.md) to install Zowe CLI plug-ins. -3. (Optional) To install all available plug-ins to Zowe CLI, issue the following command: +3. If installing all available Zowe CLI plug-ins, issue the following command: ``` - zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/ims-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts + zowe plugins install @zowe/cics-for-zowe-cli@zowe-v3-lts @zowe/db2-for-zowe-cli@zowe-v3-lts @zowe/mq-for-zowe-cli@zowe-v3-lts @zowe/zos-ftp-for-zowe-cli@zowe-v3-lts ``` -Zowe CLI is installed on your computer. Issue the `zowe --help` command to view a list of available commands. For information about how to connect the CLI to the mainframe, create profiles, integrate with API ML, and more, see [Using Zowe CLI](../user-guide/cli-using-usingcli.md). - -## Install Zowe CLI from a local package + Zowe CLI and the optional plug-ins are installed on your computer. -Use the following procedure to install Zowe CLI from a local package: +## Other installation options -1. Meet the [prerequisites](#prerequisites) for installing Zowe CLI. +There are some users who might prefer to install Zowe CLI on the mainframe, or on an operating system where secure credential storage is not required or cannot be installed from its package. -2. Navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Core** button. - -3. Read the End User License Agreement for Zowe and click **I agree** to download the core package. +For those users, mainframe installation offers the ability to install Zowe CLI in one place yet still be accessible to multiple mainframe developers. This can help with training purposes, or for scripts that run on both a local computer and the mainframe. These users often request instructions on mainframe installation, and they are provided here. - `zowe-cli-package-.zip` is downloaded to your computer. +Note, however, that Zowe CLI was not designed for mainframe installation and unexpected behavior can occur. -4. **(Optional)** Meet the [prerequisites](#prerequisites) for installing Zowe CLI plug-ins. -5. **(Optional)** Navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Plugins** button to download the plug-ins. +:::caution + +Installing Zowe CLI on the mainframe is not supported by Zowe conformant support providers. By choosing this installation method, you need to perform your own independent troubleshooting if any problems arise. + +::: -6. **(Optional)** Read the End User License Agreement for Zowe plug-ins and click **I agree** to download the plugins package. +### Installing Zowe CLI on z/Linux - `zowe-cli-plugins-next-.zip` is downloaded to your computer. +Installation steps for Zowe CLI depend on whether your z/Linux environment requires the secure credential storage. -7. Unzip the contents of `zowe-cli-package-.zip` (and optionally `zowe-cli-plugins-.zip`) to a working directory. +#### Installing with secure credential storage -8. To install Zowe CLI Core, open a command-line window and issue the following commands to the working directory that you used in Step 7: + 1. Follow the steps in [Configuring secure credential storage on headless Linux operating systems](./cli-configure-scs-on-headless-linux-os.md). + 2. Follow the steps in [Installing Zowe CLI and Zowe CLI plug-ins from an npm online registry](#installing-zowe-cli-and-zowe-cli-plug-ins-from-an-npm-online-registry) or [Installing Zowe CLI and Zowe CLI plug-ins from a local package](#installing-zowe-cli-and-zowe-cli-plug-ins-from-a-local-package). - ``` - npm install -g zowe-cli.tgz - ``` +#### Installing without secure credential storage - :::note - - If an `EACCESS` error displays, see [Resolving EACCESS permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) in the npm documentation. + 1. Follow the steps in [Installing Zowe CLI and Zowe CLI plug-ins from an npm online registry](#installing-zowe-cli-and-zowe-cli-plug-ins-from-an-npm-online-registry) or [Installing Zowe CLI and Zowe CLI plug-ins from a local package](#installing-zowe-cli-and-zowe-cli-plug-ins-from-a-local-package). + 2. Follow the steps in [Configuring Zowe CLI where secure credential storage is not available](./cli-configure-cli-on-os-where-scs-unavailable.md). - ::: +### Installing Zowe CLI on a USS system, or an OS without secure credential storage -9. **(Optional)** To install Zowe CLI plug-ins, issue the following command to the working directory that you used in Step 7: +Follow the steps in [Configuring Zowe CLI where secure credential storage is not available](../user-guide/cli-configure-cli-on-os-where-scs-unavailable.md). - ``` - zowe plugins install cics-for-zowe-cli.tgz db2-for-zowe-cli.tgz zos-ftp-for-zowe-cli.tgz ims-for-zowe-cli.tgz mq-for-zowe-cli.tgz - ``` +## Next steps -Zowe CLI and the optional plug-ins are installed on your computer. Issue the `zowe --help` command to view a list of available commands. For information about how to connect the CLI to the mainframe, create profiles and team profiles, integrate with API ML, enable daemon mode, and more, see [Using CLI](../user-guide/cli-using-usingcli.md). \ No newline at end of file +After installing Zowe CLI, set environment variables, configure Zowe profiles, and, optionally, enable daemon mode. diff --git a/docs/user-guide/cli-installplugins.md b/docs/user-guide/cli-installplugins.md index d2478bc8ff..7e0aa2f22c 100755 --- a/docs/user-guide/cli-installplugins.md +++ b/docs/user-guide/cli-installplugins.md @@ -15,47 +15,40 @@ You can install the following Zowe plug-ins: Use either of the following methods to install plug-ins: -- Install from an online NPM registry. Use this method when your computer ***can*** access the Internet. +- Install from an online NPM registry. Use this method when your computer can access the Internet. For more information, see [Installing plug-ins from an online registry](#installing-plug-ins-from-an-online-registry). -- Install from a local package. With this method, you download and install the plug-ins from a bundled set of `.tgz` files. Use this method when your computer ***cannot*** access the Internet. +- Install from a local package. With this method, you download and install the plug-ins from a bundled set of `.tgz` files. Use this method when your computer cannot access the Internet. For more information, see [Installing plug-ins from a local package](#installing-plug-ins-from-a-local-package). ## Installing plug-ins from an online registry -Install Zowe CLI plug-ins on Windows, Mac, and Linux. The procedures in this article assume that you previously installed the core CLI. +The following procedure assumes that you previously installed Zowe CLI core. -**Follow these steps:** +To install Zowe CLI plug-ins on Windows, Mac, and Linux: -1. Meet the [software requirements for each plug-in](cli-swreqplugins.md) that you install. +1. Meet the [software requirements for each plug-in](cli-swreqplugins.md) to be installed. -2. Issue the following command to install a plug-in from public npm: +2. Install a plug-in from public npm: ``` zowe plugins install ``` - - Replace `` with the installation command syntax in the following table - | Plug-in | Syntax | - |---------|-----------------------------| - | IBM CICS Plug-in for Zowe CLI | `@zowe/cics-for-zowe-cli@zowe-v2-lts` | - | IBM Db2 Plug-in for Zowe CLI| `@zowe/db2-for-zowe-cli@zowe-v2-lts` | - | IBM z/OS FTP Plug-in for Zowe CLI | `@zowe/zos-ftp-for-zowe-cli@zowe-v2-lts` | - | IBM MQ Plug-in for Zowe CLI | `@zowe/mq-for-zowe-cli@zowe-v2-lts` | - | IBM IMS Plug-in for Zowe CLI
**DEPRECATED** | `@zowe/ims-for-zowe-cli@zowe-v2-lts` | - - :::warning + - `` + + Specifies the command syntax for the plug-in to be installed. Use the following table to determine the syntax for your plug-in. - As of Zowe v2.15, the **IBM IMS Plug-in** has been deprecated. + | Plug-in | Syntax | + |---------|-----------------------------| + | IBM CICS Plug-in for Zowe CLI | `@zowe/cics-for-zowe-cli@zowe-v3-lts` | + | IBM Db2 Plug-in for Zowe CLI| `@zowe/db2-for-zowe-cli@zowe-v3-lts` | + | IBM z/OS FTP Plug-in for Zowe CLI | `@zowe/zos-ftp-for-zowe-cli@zowe-v3-lts` | + | IBM MQ Plug-in for Zowe CLI | `@zowe/mq-for-zowe-cli@zowe-v3-lts` | - No additional security updates, bug fixes, or enhancements for the plug-in are expected. - - ::: - -3. (Optional) Issue the following command to install two or more plug-ins using one command. Separate the `` names with one space. +3. (Optional) Issue the following command to install two or more plug-ins using one command. Separate the `` names with a single space. ``` zowe plugins install <@zowe/my-plugin1> <@zowe/my-plugin2> <@zowe/my-plugin3> ... @@ -67,25 +60,32 @@ Install Zowe CLI plug-ins on Windows, Mac, and Linux. The procedures in this art ::: - You have successfully installed Zowe CLI plug-ins. + You have successfully installed the specified Zowe CLI plug-in(s). ## Installing plug-ins from a local package -Install plug-ins from a local package on any computer that has limited or no access to the Internet. The procedure assumes that you previously installed the core CLI. +The following procedure assumes that you previously installed Zowe CLI core. -**Follow these steps:** +To install plug-ins from a local package on any computer that has limited or no access to the Internet: -1. Meet the [software requirements for each plug-in](cli-swreqplugins.md) that you want to install. +1. Meet the [software requirements for each plug-in](cli-swreqplugins.md) that you want to install. -2. Obtain the installation files. +2. Obtain the installation files. - From the Zowe [Download](https://zowe.org/download/) website, click **Download Zowe CLI** to download the Zowe CLI installation package named `zowe-cli-package-*v*.*r*.*m*.zip` to your computer. + From the Zowe [Download](https://zowe.org/download/) website, click **Download Zowe CLI** to download the Zowe CLI installation package named `zowe-cli-package-.zip` to your computer. + + - `v` - :::note + Specifies the version number + + - `r` - `v` indicates the version, `r` indicates the release number, and `m` indicates the modification number. + Specifies the release number + + - `m` + + Specifies the modification number. - ::: 3. Open a command-line window, such as Windows Command Prompt. Browse to the directory where you downloaded the Zowe CLI installation package (.zip file). Issue the following command, or use your preferred method to unzip the files: @@ -94,7 +94,7 @@ Install plug-ins from a local package on any computer that has limited or no acc ``` **Example:** ``` - unzip zowe-cli-package-1.9.0.zip + unzip zowe-cli-package-3.0.0.zip ``` By default, the unzip command extracts the contents of the zip file to the directory where you downloaded the .zip file. You can extract the contents of the zip file to your preferred location. @@ -113,15 +113,6 @@ Install plug-ins from a local package on any computer that has limited or no acc | IBM Db2 Plug-in for Zowe CLI | `db2-for-zowe-cli.tgz` | | IBM z/OS FTP Plug-in for Zowe CLI | `zos-ftp-for-zowe-cli.tgz` | | IBM MQ Plug-in for Zowe CLI | `mq-for-zowe-cli.tgz` | - | IBM IMS Plug-in for Zowe CLI
**DEPRECATED** | `ims-for-zowe-cli.tgz` | - - :::warning - - As of Zowe v2.15, the **IBM IMS Plug-in** has been deprecated. - - No additional security updates, bug fixes, or enhancements for the plug-in are expected. - - ::: You have successfully installed the Zowe CLI plug-ins. @@ -136,7 +127,8 @@ zowe plugins validate [plugin] ``` - **`[plugin]`** - (Optional) Specifies the name of the plug-in that you want to + + Specifies the name of the plug-in that you want to validate. If you do not specify a plug-in name, the command validates all installed plug-ins. The name of the plug-in is not always the same as the name of the NPM package. @@ -145,7 +137,6 @@ zowe plugins validate [plugin] | IBM CICS Plug-in for Zowe CLI | `@zowe/cics-for-zowe-cli` | | IBM Db2 Plug-in for Zowe CLI| `@zowe/db2-for-zowe-cli` | | IBM z/OS FTP Plug-in for Zowe CLI | `@zowe/zos-ftp-for-zowe-cli` | - | IBM IMS Plug-in for Zowe CLI | `@zowe/ims-for-zowe-cli` | | IBM MQ Plug-in for Zowe CLI | `@zowe/mq-for-zowe-cli` | @@ -188,7 +179,7 @@ zowe plugins update [plugin...] [--registry ] The following example illustrates the syntax to use to update an installed plug-in to the latest version: ``` -zowe plugins update @zowe/my-plugin@zowe-v2-lts +zowe plugins update @zowe/my-plugin@zowe-v3-lts ``` The following example illustrates the syntax to use to update a plug-in to a specific version: @@ -225,7 +216,6 @@ The following table describes the uninstallation command syntax for each plug-in | IBM CICS Plug-in for Zowe CLI | `@zowe/cics-for-zowe-cli` | | IBM Db2 Plug-in for Zowe CLI| `@zowe/db2-for-zowe-cli` | | IBM z/OS FTP Plug-in for Zowe CLI | `@zowe/zos-ftp-for-zowe-cli` | -| IBM IMS Plug-in for Zowe CLI | `@zowe/ims-for-zowe-cli` | | IBM MQ Plug-in for Zowe CLI | `@zowe/mq-for-zowe-cli` | diff --git a/docs/user-guide/cli-mqplugin.md b/docs/user-guide/cli-mqplugin.md index ce98fc7fee..744b034b9d 100644 --- a/docs/user-guide/cli-mqplugin.md +++ b/docs/user-guide/cli-mqplugin.md @@ -1,8 +1,12 @@ # IBM® MQ Plug-in for Zowe CLI -The IBM MQ Plug-in for Zowe CLI lets you issue MQSC commands to a queue manager. MQSC commands let you to perform administration tasks. For example, you can define, alter, or delete a local queue object. +The IBM MQ Plug-in for Zowe CLI lets you issue MQSC commands to a queue manager. MQSC commands let you perform administration tasks. For example, you can define, alter, or delete a local queue object. -**Note:** For more information about MQSC commands and the corresponding syntax, see [MQSC commands](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.ref.adm.doc/q085130_.htm) on the IBM Knowledge Center. +:::note + +For more information about MQSC commands and the corresponding syntax, see [MQSC commands](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.ref.adm.doc/q085130_.htm) on the IBM Knowledge Center. + +::: ## Use cases @@ -10,11 +14,13 @@ You can use the plug-in to execute MQSC Commands. With MQSC commands you can man ## Using IBM MQ plug-in commands -For detailed documentation on commands, actions, and options available in this plug-in, see our Web Help. It is available for download in three formats: a PDF document, an interactive online version, and a ZIP file containing the HTML for the online version. +For detailed documentation on commands, actions, and options available in this plug-in, see our web help. + +There are several methods to view Zowe CLI web help: -- Browse Online -- Download (ZIP) -- Download (PDF) +- Use a web browser +- Extract from a ZIP file +- Download a PDF file ## Software requirements @@ -25,88 +31,73 @@ Before you install the plug-in, meet the software requirements in [Software requ Use one of the following methods to install or update the plug-in: - [Installing plug-ins from an online registry](cli-installplugins.md#installing-plug-ins-from-an-online-registry) - - [Installing plug-ins from a local package](cli-installplugins.md#installing-plug-ins-from-a-local-package) ## Creating a user profile -You create an mq profile to avoid entering your connection details each time that you issue a command. You can create multiple profiles and switch between them as needed. Use one of the following methods to create a profile: - -- **Create plug-in profiles using a configuration file:** Specify your profile and connection details in the `zowe.config.json` configuration file. - -- **Create plug-in profiles using a command:** Issue the `zowe profiles create` command to create the profile. - -We recommend that you create profiles using the configuration file. We do not recommend using profile commands because we are removing them in a future major release. +After you install the plug-in, create an MQ profile. An MQ profile is recommended to issue commands to the MQ resource. MQ profiles contain your host, port, user name, and password for the IBM MQ REST API server of your choice. You can create multiple profiles and switch between them as needed. +Specify your plug-in profile and connection details in the `zowe.config.json` configuration file. ### Creating plug-in profiles using a configuration file -When you issue various zowe config commands, such as `init`, `auto-init`, and `convert-profiles`, they create a `zowe.config.json` configuration file. When you install the MQ plug-in, the commands create an entry for an `mq profile` in your `zowe.config.json` file. - -Alternatively, you can create a mq profile manually by adding a section that contains the configuration details to your `zowe.config.json`ok configuration file. - -1. Browse to the following directory `C:\Users\\.zowe` +If you have the MQ plug-in installed and issue the `zowe config init`, `zowe config auto-init`, or `zowe config convert-profiles` command, the command creates an entry for a MQ profile in your `zowe.config.json file`. -2. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ. +Alternatively, you can create an MQ profile manually by adding a section that contains the configuration details to your `zowe.config.json` configuration file. - **NOTE:** If the file does not exist, issue the following command to create the configuration file: `zowe config init --gc` +#### Creating an MQ profile with a command -3. Add code to the "profiles" section as shown in the following example: +1. Install the IBM MQ Database Plug-in for Zowe CLI. +2. Create an MQ profile: - **Example:** ``` - "Your_mq_profile": { - "type": "mq", - "properties": { - "host": "Your_host_name", - "port": Your_port_number - }, - "secure": [ - "user", - "password" - ] - } + zowe config init ``` -4. Save the file - -You can now use your profile when you issue commands in the mq command group. - -### Creating plug-in profiles using a command - -The following steps describe how to create a profile using the `zowe profiles create` command. - -1. Open a terminal window and issue the following command: +3. Set the port number to the port configured for an MQ connection on your mainframe. ``` - zowe profiles create mq --host --port --user --password + zowe config set profiles.mq.properties.port ``` - **`profile_name`:** - - Specifies a name for your profile. + - `` - **`host`:** + Specifies the port number for the instance. - Specifies the host name for the instance. + You can now use your profile when you issue commands in the MQ command group. - **`user`:** +#### Creating an MQ profile manually - Specifies your user name to log in to the instance. +1. Install the IBM MQ Database Plug-in for Zowe CLI. - **`password`:** +2. Browse to the directory `C:\Users\\.zowe`. - Specifies your password to log in to the instance. +3. Open the `zowe.config.json` configuration file using a text editor or IDE, such as Visual Studio Code or IntelliJ IDEA. - **`port`:** - - Specifies the port number to connect to the instance. + :::note + + If the file does not exist, issue the following command to create the configuration file: + ``` + zowe config init --gc + ``` + + ::: - **Example:** +4. Add code to the "profiles" section as shown in the following example: ``` - zowe profiles create mq-profile queue1 --host mq.zowe.org --port 1443 --user zowe --password zowepass + "Your_mq_profile": { + "type": "mq", + "properties": { + "host": "Your_host_name", + "port": Your_port_number, + }, + "secure": [ + "user", + "password" + ] + } ``` -2. Press Enter. The result of the command displays as a success or failure message. +5. Save the file. -You can now use your profile when you issue commands in the mq command group. \ No newline at end of file + You can now use your profile when you issue commands in the MQ command group. diff --git a/docs/user-guide/cli-swreqplugins.md b/docs/user-guide/cli-swreqplugins.md index 374b20b6e4..027491ca07 100644 --- a/docs/user-guide/cli-swreqplugins.md +++ b/docs/user-guide/cli-swreqplugins.md @@ -1,17 +1,14 @@ -# Software requirements for Zowe CLI plug-ins +# Zowe CLI plug-ins software requirements -Before you use Zowe™ CLI plug-ins, complete the following steps: +Before installing a Zowe™ CLI plug-in, meet the software requirements to run the plug-in as expected. -**Important!** You can perform the required configurations for the plug-ins that you want to use ***before*** or ***after*** you install the plug-ins. However, if you do not perform the required configurations, the plug-ins will not function as designed. +:::info Required role: systems administrator +::: -| Plug-in | Required Configurations | +| Plug-in | Requirements | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| | [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| -| [IBM IMS Plug-in for Zowe CLI](cli-imsplugin.md)
**DEPRECATED** |
  • **As of Zowe v2.15, the IBM IMS Plug-in has been deprecated. No additional security updates, bug fixes, or enhancements are expected.**
  • Ensure that [IBM® IMS™ v14.1.0](https://www.ibm.com/support/knowledgecenter/en/SSEPH2_14.1.0/com.ibm.ims14.doc/ims_product_landing_v14.html) or later is installed and running in your mainframe environment.
  • Configure [IBM® IMS™ Connect](https://www.ibm.com/support/knowledgecenter/en/SSEPH2_13.1.0/com.ibm.ims13.doc.ccg/ims_ct_intro.html).
  • Configure [IBM IMS Operations APIs](https://github.com/zowe/ims-operations-api) to enable communication between the CLI and the IMS instance.
| - - -**Important!** You can perform the required configurations for the plug-ins that you want to use ***before*** or ***after*** you install the plug-ins. However, if you do not perform the required configurations, the plug-ins will not function as designed. diff --git a/docs/user-guide/cli-uninstall.md b/docs/user-guide/cli-uninstall.md index e42233aed9..50bad5b6a6 100644 --- a/docs/user-guide/cli-uninstall.md +++ b/docs/user-guide/cli-uninstall.md @@ -1,21 +1,32 @@ -# Uninstalling Zowe CLI +# Uninstalling Zowe CLI and Zowe CLI plug-ins You can uninstall Zowe™ CLI from the desktop if you no longer need to use it. -**Important\!** The uninstall process does not delete the profiles and credentials that you created when using the product from your computer. To delete the profiles from your computer, delete them before you uninstall Zowe CLI. +:::info Required roles: Systems administrator +::: -The following steps describe how to list the profiles that you created, delete the profiles, and uninstall Zowe CLI. +:::warning Important -1. Open a command-line window. +The uninstall process does not delete the profiles and credentials that you created when using the product from your computer. To delete the profiles from your computer, delete them before you uninstall Zowe CLI. - **Note:** If you do not want to delete the Zowe CLI profiles from your computer, go to Step 5. +::: + +To list the profiles that you created, delete the profiles, and uninstall Zowe CLI. + +1. Open a command line window. + + :::note + + If you do not want to delete the Zowe CLI profiles from your computer, proceed to Step 5. + + ::: 2. List all configuration files that you created. Issue the following command: ``` zowe config list --locations --root ``` - **Example:** + Example response for Windows: ``` $ zowe config list --locations --root @@ -23,17 +34,34 @@ The following steps describe how to list the profiles that you created, delete t $ ``` -3. Delete all of the configuration files that are listed. Issue the following command: - - **Tip:** For this command, use the results of the `zowe config list` - command. + Example response for Linux and Mac OS: ``` - rm C:\Users\SMITH-123\.zowe\zowe.config.json + $ zowe config list --locations --root + ~/.zowe/zowe.config.json + $ ``` - + + +3. Delete all of the configuration files that are listed. Issue the following command: + + :::tip + + For this command, use the results of the `zowe config list` command. + + ::: + + For Windows: + + ``` + del C:\Users\SMITH-123\.zowe\zowe.config.json + ``` + For Linux and Mac OS: + + ``` + rm ~/.zowe/zowe.config.json + ``` 4. Uninstall Zowe CLI by issuing the following command: @@ -41,10 +69,18 @@ The following steps describe how to list the profiles that you created, delete t npm uninstall --global @zowe/cli ``` - **Note:** You might receive an `ENOENT` error when issuing this command if you installed Zowe CLI from a local package (.tgz) and the package was moved from its original location. In the event that you receive the error, open an issue in the Zowe CLI GitHub repository. + :::note + + You might receive an `ENOENT` error when issuing this command if you installed Zowe CLI from a local package (.tgz) and the package was moved from its original location. To resolve this, add the `--force` option to the `npm uninstall --global @zowe/cli` command and to bypass any errors. + + ::: The uninstall process removes all Zowe CLI installation directories and files from your computer. 5. Delete the `~/.zowe` or `%homepath%\.zowe` directory on your computer. The directory contains the Zowe CLI log files and other miscellaneous files that were generated when you used the product. - **Tip:** Deleting the directory does not harm your computer. \ No newline at end of file + :::info + + Deleting the directory does not harm your computer. + + ::: diff --git a/docs/user-guide/cli-updatingcli.md b/docs/user-guide/cli-updatingcli.md index 850a55916c..3017122eab 100644 --- a/docs/user-guide/cli-updatingcli.md +++ b/docs/user-guide/cli-updatingcli.md @@ -1,98 +1,149 @@ -# Updating Zowe CLI +# Updating Zowe CLI and Zowe CLI plug-ins -Zowe™ CLI is updated continuously. You can update Zowe CLI to a more recent version using online registry method or the local package method. +Zowe™ CLI is updated continuously. You can update Zowe CLI to a more recent version using either the online registry or the local package method. + +:::info Required role: systems administrator +::: You must update Zowe CLI using the method that you used to install Zowe CLI. -## Updating to the Zowe CLI V2 Long-term Support (v2-lts) version +## Identifying the currently installed version of Zowe CLI and Zowe CLI plug-ins + +For Zowe CLI core, open a command line window and issue the following command: + +``` +zowe --version +``` + +For Zowe CLI plug-ins, open a command line window and issue the following command: + +``` +zowe plugins list +``` + +## Updating to the Zowe CLI V3 Long-term Support (v3-lts) version + +If you are running the Zowe CLI version included with Zowe release v2.0.0 to v2.15.x, you can update to `@zowe-v3-lts` (LTS version) to leverage the latest Zowe CLI and Zowe CLI plug-ins functionality. -If you are running Zowe CLI version v1.8.x to v1.27.x, you can update to `@zowe-v2-lts` (LTS version) to leverage the latest Zowe CLI and plug-ins functionality. +### Updating from an npm online registry -1. Update Zowe CLI. Open a command line window and issue the following command: +1. To update and install Zowe CLI core, open a command line window and issue the following command: ``` - npm install -g @zowe/cli@zowe-v2-lts + npm install -g @zowe/cli@zowe-v3-lts ``` -2. Update Zowe plug-ins. Issue the following command to install all Zowe plug-ins: +2. To update and install all Zowe plug-ins, open a command line window and issue the following command: ``` - zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/ims-for-zowe-cli@zowe-v2-lts @zowe/mq-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts + zowe plugins install @zowe/cics-for-zowe-cli@zowe-v3-lts @zowe/db2-for-zowe-cli@zowe-v3-lts @zowe/zos-ftp-for-zowe-cli@zowe-v3-lts @zowe/mq-for-zowe-cli@zowe-v3-lts ``` - **Note:** To install a subset of the plug-ins, remove the syntax for the plug-ins that you do not want to update. For example: + To install a subset of the plug-ins, remove the syntax for the plug-in(s) that you do not want to update. For example: ``` - zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts + zowe plugins install @zowe/db2-for-zowe-cli@zowe-v3-lts @zowe/zos-ftp-for-zowe-cli@zowe-v3-lts ``` -3. (Optional) Migrate your Zowe CLI profiles from your current installation to your V2 installation. Issue the following command: +3. When updating from Zowe V1 to Zowe V3, migrate your Zowe CLI profiles from your current installation to your V3 installation: ``` zowe config convert-profiles ``` - Although you can run Zowe CLI V2 successfully using CLI V1 profiles, we strongly recommend using CLI V2 profiles. - - **Note:** Profile data is backed up in case you want to revert the profiles to your previous Zowe CLI installation. + Profile data is backed up in case you want to revert the profiles to your previous Zowe CLI installation. -4. (Optional) If you no longer require the profiles for your previous Zowe CLI installation, you can delete them. Issue the following command: +4. When updating from Zowe V1 to Zowe V3, if you no longer require the profiles for your previous Zowe CLI installation, you can delete them: ``` zowe config convert-profiles --delete ``` - **Important:** We do not recommend deleting the profiles from your previous Zowe CLI installation until you have tested your V2 installation and are satisfied with its performance. + :::info Important + + We do not recommend deleting the profiles from your previous Zowe CLI installation until you have tested your V3 installation and are satisfied. -You updated to the Zowe CLI V2-LTS version! + ::: -Ensure that you review the [Release Notes](../whats-new/release-notes/v2_0_0.md), which describes **Notable Changes** in this version. We recommend issuing familiar commands and running scripts to ensure that your profiles/scripts are compatible. You might need to take corrective action to address the breaking changes. + You have successfully updated to the Zowe CLI V3-LTS version. -## Identify the currently installed version of Zowe CLI +5. See [Next steps](#next-steps) for recommended tasks after installation. -Issue the following command (case-sensitive): +### Updating from a local package -``` -zowe -V -``` +To update Zowe CLI core and Zowe CLI plug-ins from an offline (`.tgz`), local package, uninstall your current package then reinstall from a new package. -## Identify the currently installed versions of Zowe CLI plug-ins +1. To uninstall Zowe CLI and Zowe CLI plug-ins, follow the instructions in [Uninstalling Zowe CLI and Zowe CLI Plug-ins](../user-guide/cli-uninstall.md). -Issue the following command: +2. To install a new package for Zowe CLI and Zowe CLI plug-ins, follow the instructions in [Installing Zowe CLI and Zowe CLI plug-ins from a local package](../user-guide/cli-installcli.md#installing-zowe-cli-and-zowe-cli-plug-ins-from-a-local-package). -``` -zowe plugins list -``` +3. See [Next steps](#next-steps) for recommended tasks after installation. + +## Updating or reverting Zowe CLI and Zowe CLI plug-ins to a specific version + +If necessary, you can update or revert Zowe CLI to a known, previously released version. -## Update Zowe CLI from the online registry +### Updating or reverting from an npm online registry -You can update Zowe CLI to the latest version from the online registry on Windows, Mac, and Linux computers. +1. To update or revert Zowe CLI and Zowe CLI plug-ins to a specific known version, open a command line window and issue the following command: -**Note:** The following steps assume that you previously installed the CLI as described in [Install Zowe CLI from npm](cli-installcli.md#install-zowe-cli-from-npm). + ``` + npm install -g @zowe/cli@ + ``` + + - `` + + Specifies release number that Zowe CLI or Zowe CLI plug-ins are to be updated or reverted to. For example, `npm install -g @zowe/cli@8.0.0`. + +2. See [Next steps](#next-steps) for recommended tasks after installation. + +### Updating or reverting from a local package + +1. Uninstall Zowe CLI and Zowe CLI plug-ins. Follow the instructions in [Uninstalling Zowe CLI and Zowe CLI Plug-ins](../user-guide/cli-uninstall.md). + +2. Navigate to [Download Zowe](https://www.zowe.org/download.html). Select the specific release you want to update or revert to from **All Zowe V2.x Releases** or **All Zowe V3.x Releases**. + + The End User License Agreement for Zowe displays. + +3. Read the End User License Agreement for Zowe and click **I agree** to download the core package. -1. Update Zowe CLI. Open a command line window and issue the following command: + `zowe-cli-package-next-.zip` is downloaded to your computer (where `` indicates the year, month, and day of the build). + +4. If updating or reverting Zowe CLI plug-ins, navigate to [Download Zowe](https://www.zowe.org/download.html) and click the **Zowe \ CLI Plugins** button (where \ specifies the release number). + +5. If updating or reverting Zowe CLI plug-ins, read the End User License Agreement for Zowe and click **I agree** to download the plug-ins package. + + `zowe-cli-plugins-next-.zip` is downloaded to your computer. + +6. Unzip the contents of `zowe-cli-package-.zip` (and `zowe-cli-plugins-.zip`, if downloaded) to a working directory. + +7. To install Zowe CLI core, open a command-line window and issue the following command to the working directory that was used the previous step: ``` - npm install -g @zowe/cli@zowe-v2-lts + npm install -g zowe-cli.tgz ``` -2. Update Zowe plug-ins. Issue the following command to install all Zowe plug-ins: + :::note + + If an `EACCESS` error displays, see [Resolving EACCESS permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) in npm Docs. - **Note:** To install a subset of the plug-ins, remove the syntax for the plug-ins that you do not want to update. For example: + ::: + +8. To update or revert all available Zowe CLI plug-ins, issue the following command to the working directory that was used in Step 6: ``` - zowe plugins install @zowe/cics-for-zowe-cli@zowe-v2-lts @zowe/db2-for-zowe-cli@zowe-v2-lts @zowe/zos-ftp-for-zowe-cli@zowe-v2-lts + zowe plugins install cics-for-zowe-cli.tgz db2-for-zowe-cli.tgz zos-ftp-for-zowe-cli.tgz mq-for-zowe-cli.tgz ``` -3. Recreate any user profiles that you created before you updated to the latest version of Zowe CLI. + Zowe CLI and the optional plug-ins are installed on your computer. -## Update or revert Zowe CLI to a specific version + To update or revert a subset of the plug-ins, remove the syntax for the plug-in(s) that you do not want to update. For example: -Optionally, you can update Zowe CLI (or revert) to a known version. The following example illustrates the syntax to update Zowe CLI to version 7.0.0: + ``` + zowe plugins install db2-for-zowe-cli.tgz mq-for-zowe-cli.tgz + ``` -``` -npm install -g @zowe/cli@7.0.0 -``` +9. See [Next steps](#next-steps) for recommended tasks after installation. -## Update Zowe CLI from a local package +## Next steps -To update Zowe CLI from an offline (`.tgz`), local package, uninstall your current package then reinstall from a new package using the Install from a Local package instructions. For more information, see [Uninstalling Zowe CLI](cli-uninstall.md) and [Install Zowe CLI from a local package](cli-installcli.md#install-zowe-cli-from-a-local-package). +Review the [release notes](../whats-new/release-notes/release-notes-overview.md) for the notable changes in the newly installed version. -**Important!** Recreate any user profiles that you created before the update. \ No newline at end of file +Issue familiar commands and run scripts to ensure that your profiles/scripts are compatible. Take corrective action to address any breaking changes. diff --git a/docs/user-guide/cli-using-benefits-of-team-config.md b/docs/user-guide/cli-using-benefits-of-team-config.md new file mode 100644 index 0000000000..6d2472faa9 --- /dev/null +++ b/docs/user-guide/cli-using-benefits-of-team-config.md @@ -0,0 +1,13 @@ +# Benefits of team configuration + +[Team configuration](../appendix/zowe-glossary#team-configuration) can make the initial setup of Zowe CLI more efficient by making service connection details easier to share and maintain within your organization. + +Consider the following benefits of using team configuration for roles across your dev team: + +- For a **team leader**, or Dev-Ops advocate, **sharing global team configurations** managed from one location, such as a software change management system. This allows multiple team members to use the same configurations stored in a repository or server. + +- For a Dev-Ops advocate or **team leader**, quickly **onboarding new application developers** by sharing the configuration file that your team uses with the new team member. + +- For an **application developer** in a small shop where you have the dual roles of application developer *and* a Dev-Ops advocate, having the **flexibility to create team or user configurations** that are most suitable for your needs. + +- For a team member or **application developer**, efficiently managing **connection details in one location**. diff --git a/docs/user-guide/cli-using-command-precedence.md b/docs/user-guide/cli-using-command-precedence.md index 51fb32f7c3..3bed05bf02 100644 --- a/docs/user-guide/cli-using-command-precedence.md +++ b/docs/user-guide/cli-using-command-precedence.md @@ -5,12 +5,12 @@ You can provide your mainframe connection details (username, password, etc.) to When you issue a command, the CLI *searches* for your command arguments in the following order: 1. **Options** that you specify on individual commands. -2. **Environment variables** that you define in the computer's operating system. - For more information, see [Using environment variables](../user-guide/cli-using-using-environment-variables). -3. **Service profiles** that you create (i.e. z/OSMF profile or another mainframe service). -4. **Base profiles** that you create. +2. **Environment variables** that you define in the computer's operating system. + For more information, see [Using environment variables](../user-guide/cli-using-using-environment-variables). +3. **[Service profiles](../appendix/zowe-glossary.md#service-profile)** that you create (that is, a z/OSMF profile or another mainframe service). +4. **[Base profiles](../appendix/zowe-glossary.md#base-profile)** that you create. These can contain credentials for use with multiple services and/or an API ML login token. 5. **Default option value**. diff --git a/docs/user-guide/cli-using-creating-global-user-profiles.md b/docs/user-guide/cli-using-creating-global-user-profiles.md index d7fdf1faf7..31e1eba2e3 100644 --- a/docs/user-guide/cli-using-creating-global-user-profiles.md +++ b/docs/user-guide/cli-using-creating-global-user-profiles.md @@ -38,7 +38,7 @@ In your user-specific file , observe that the "defaults" object is empty and the "properties": {}, "secure": [] }, - "base": { + "global_base": { "type": "base", "properties": {}, "secure": [] @@ -67,7 +67,7 @@ Open the `~/.zowe/zowe.config.json` file in a text editor or IDE on your compute "port": 443 } }, - "base": { + "global_base": { "type": "base", "properties": { "host": "example1.com" @@ -80,7 +80,7 @@ Open the `~/.zowe/zowe.config.json` file in a text editor or IDE on your compute }, "defaults": { "zosmf": "zosmf", - "base": "base" + "base": "global_base" }, } ``` diff --git a/docs/user-guide/cli-using-creating-profiles.md b/docs/user-guide/cli-using-creating-profiles.md new file mode 100644 index 0000000000..8f66474085 --- /dev/null +++ b/docs/user-guide/cli-using-creating-profiles.md @@ -0,0 +1,317 @@ +# Creating profiles + +Configuration profiles are used to connect to different mainframe services, and you can structure each profile based on how that connection is made. + +For example, profiles can be nested to share the same connection information, or keep different information separate. Services can be accessed directly by Zowe CLI, or they can be accessed through the API Mediation Layer. + +Review the following scenarios to help determine the profile types best suited for your environment. + +As a team leader, you can share the configuration you create with your team members so they can easily access mainframe services. + +## Accessing LPARs that contain services that share the same credentials + +In the following configuration, nested profiles use the credentials from the same base profile to access services directly on multiple LPARs: + +``` +{ + "$schema": "./zowe.schema.json", + "profiles": { + "lpar1": { + "properties": { + "host": "example1.com" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "port": 443 + } + }, + "tso": { + "type": "tso", + "properties": { + "account": "ACCT#", + "codePage": "1047", + "logonProcedure": "IZUFPROC" + } + }, + "ssh": { + "type": "ssh", + "properties": { + "port": 22 + } + } + } + }, + "lpar2": { + "properties": { + "host": "example2.com" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "port": 1443 + } + } + } + }, + "project_base": { + "type": "base", + "properties": { + "rejectUnauthorized": true + }, + "secure": [ + "user", + "password" + ] + } + }, + "defaults": { + "zosmf": "lpar2.zosmf", + "tso": "lpar1.tso", + "ssh": "lpar1.ssh", + "base": "project_base" + }, + "autoStore": true +} +``` +## Accessing LPARs that contain services that do not share the same credentials + +In the following configuration, profiles are nested to use the credentials from parent profiles for different LPARs to access services directly on multiple LPARs. + +``` +{ + "$schema": "./zowe.schema.json", + "profiles": { + "lpar1": { + "properties": { + "host": "example1.com" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "port": 443 + } + }, + "tso": { + "type": "tso", + "properties": { + "account": "ACCT#", + "codePage": "1047", + "logonProcedure": "IZUFPROC" + } + }, + "ssh": { + "type": "ssh", + "properties": { + "port": 22 + } + } + }, + "secure": [ + "user", + "password" + ] + }, + "lpar2": { + "properties": { + "host": "example2.com" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "port": 1443 + } + } + }, + "secure": [ + "user", + "password" + ] + }, + "project_base": { + "type": "base", + "properties": { + "rejectUnauthorized": true + } + } + }, + "defaults": { + "zosmf": "lpar2.zosmf", + "tso": "lpar1.tso", + "ssh": "lpar1.ssh", + "base": "project_base" + }, + "autoStore": true +} +``` + +## Accessing LPARs that access services through one API Mediation Layer + +In the following configuration, services are accessed through the API ML (where multi-factor authentication (MFA) or single sign-on (SSO) is achievable) using token-based authorization stored in a base profile. + +``` +{ + "$schema": "./zowe.schema.json", + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "basePath": "ibmzosmf/api/v1" + } + }, + "cics": { + "type": "cics", + "properties": { + "basePath": "ibmcics/api/v1" + } + }, + "db2": { + "type": "db2", + "properties": { + "basePath": "ibmdb2/api/v1" + } + }, + "project_base": { + "type": "base", + "properties": { + "host": "example.com", + "port": 7554, + "rejectUnauthorized": true, + "tokenType": "apimlAuthenticationToken" + }, + "secure": [ + "tokenValue" + ] + } + }, + "defaults": { + "zosmf": "zosmf", + "cics": "cics", + "db2": "db2", + "base": "project_base" + }, + "autoStore": true +} +``` + +## Accessing LPARs that access services through one API Mediation Layer using certificate authentication + +In the following configuration, services are accessed through the API ML using certificate authentication stored in a base profile. + +``` +{ + "$schema": "./zowe.schema.json", + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "basePath": "api/v1" + } + }, + "cics": { + "type": "cics", + "properties": { + "basePath": "api/v1/cics" + } + }, + "db2": { + "type": "db2", + "properties": { + "basePath": "api/v1/db2" + } + }, + "project_base": { + "type": "base", + "properties": { + "certFile": "./zowe-cert.pem", + "certKeyFile": "./zowe-cert-key.pem", + "host": "example.com", + "port": 7554, + "rejectUnauthorized": true + } + } + }, + "defaults": { + "zosmf": "zosmf", + "cics": "cics", + "db2": "db2", + "base": "project_base" + }, + "autoStore": true +} +``` + +## Accessing services through multiple API ML gateways + +In the following configuration, the profiles are structured to connect to services using multiple API ML gateways. + +To authenticate to a specific API ML gateway from this configuration, you can run `zowe auth login apiml --base-profile lpar1` or `zowe auth login apiml --base-profile lpar2`. + +``` +{ + "$schema": "./zowe.schema.json", + "profiles": { + "lpar1": { + "properties": { + "host": "example1.com", + "port": 7554, + "tokenType": "apimlAuthenticationToken" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "basePath": "api/v1" + } + }, + "tso": { + "type": "tso", + "properties": { + "account": "ACCT#", + "codePage": "1047", + "logonProcedure": "IZUFPROC" + } + }, + "ssh": { + "type": "ssh", + "properties": { + "port": 22 + } + } + }, + "secure": [ + "tokenValue" + ] + }, + "lpar2": { + "properties": { + "host": "example2.com", + "port": 7554, + "rejectUnauthorized": false, + "tokenType": "apimlAuthenticationToken" + }, + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "basePath": "api/v1" + } + } + }, + "secure": [ + "tokenValue" + ] + } + }, + "defaults": { + "zosmf": "lpar2.zosmf", + "tso": "lpar1.tso", + "ssh": "lpar1.ssh" + }, + "autoStore": true +} +``` \ No newline at end of file diff --git a/docs/user-guide/cli-using-displaying-help.md b/docs/user-guide/cli-using-displaying-help.md index 1557f913ae..7c9eabb823 100644 --- a/docs/user-guide/cli-using-displaying-help.md +++ b/docs/user-guide/cli-using-displaying-help.md @@ -1,6 +1,7 @@ # Displaying help Zowe CLI has a command-line help system that details the commands, actions, and options available in the product. + ## Top-level help To view top-level help, open a command-line and issue the following command: @@ -9,15 +10,21 @@ To view top-level help, open a command-line and issue the following command: zowe --help ``` -![Issuing the help command](../images/guides/CLI/GetHelp.gif) + - An example of the Zowe CLI response: + + ![Issuing the help command](../images/guides/CLI/GetHelp.gif) -Alternatively, issue the following command to display a full list of all available commands: +Alternatively, to display a full list of all available commands: ``` zowe --ac ``` -**Tip:** All Zowe CLI commands begin with `zowe.` +:::tip + +All Zowe CLI commands begin with `zowe`. + +::: ## Group, action, and object help @@ -29,9 +36,9 @@ For example, issue the following command to learn about the `create` action in t zowe zos-files create --help ``` -## Launch local web help +## Launching local web help -Launch an interactive form of help in a web browser. When you issue the following command, web help is custom-generated to include commands for all of your *currently installed* plug-ins: +Launch an interactive form of help content in a web browser. When you issue the following command, web help is custom-generated to include commands for all of your currently installed plug-ins: ``` zowe --help-web @@ -42,12 +49,16 @@ Launching web help in browser... PS C:\Users\myName> ``` -**Tip:** Append `--help-web` to a specific command or action to launch directly into the appropriate web help page. -## Viewing web help +:::tip + +Append `--help-web` to a specific command or action to launch directly into the appropriate web help page. + +::: +## Viewing web help in other ways -We provide you with several methods to view Zowe CLI web help. You can browse Zowe CLI web help online, download the web help in a ZIP file that contains the HTML, or download the web help in a PDF file. +There are several methods to view Zowe CLI web help: -- Browse Online -- Download (ZIP) -- Download (PDF) +- Use a web browser +- Extract from a ZIP file +- Download a PDF file diff --git a/docs/user-guide/cli-using-editing-team-configuration.md b/docs/user-guide/cli-using-editing-team-configuration.md new file mode 100644 index 0000000000..77c789fdbb --- /dev/null +++ b/docs/user-guide/cli-using-editing-team-configuration.md @@ -0,0 +1,43 @@ +# Editing team configurations + +After you [initialize team configuration](../user-guide/cli-using-initializing-team-configuration), the newly created team profiles need additional details before they can be shared and applied in your environment. This could include information such as a port number or user credentials. + +You might also need to modify the configuration file to [create new profiles](../user-guide/cli-using-creating-profiles.md) for accessing mainframe services. + +## Adding, modifying team profiles + +To define additional mainframe services and other profiles in an existing global team configuration file: + +1. Open the `~/.zowe/zowe.config.json` file in a text editor or an IDE (such as Visual Studio Code) on your computer. + +2. Edit the file by adding to or modifying the profiles listed in the profiles object. + + Each profile contains connection and other frequently needed information for accessing various mainframe services, as in the following example: + + ``` + { + "$schema": "./zowe.schema.json", + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": { + "port": 443 + } + }, + "global_base": { + "type": "base", + "properties": { + "host": "example1.com" + }, + "secure": [ + "user", + "password" + ] + } + }, + "defaults": { + "zosmf": "zosmf", + "base": "global_base" + }, + } + ``` diff --git a/docs/user-guide/cli-using-global-storing-properties-automatically.md b/docs/user-guide/cli-using-global-storing-properties-automatically.md index fe8339a472..8eeaa2d28e 100644 --- a/docs/user-guide/cli-using-global-storing-properties-automatically.md +++ b/docs/user-guide/cli-using-global-storing-properties-automatically.md @@ -1,7 +1,9 @@ # Storing properties automatically -When you issue a command that is missing a required option value for a property (for example, host or password) the CLI prompts you to enter the option value. In the V1-LTS version of Zowe CLI, the value that was specified was not stored for future commands to use. As a result, you either responded to a prompt on every command issued or issued a profile update command to store the missing value. +When you issue a command that is missing a required option value for a property (for example, host or password) the CLI prompts you to enter the option value. -The `autoStore` property in the `zowe.config.json` file lets you store the option values for properties automatically. When you specify the `autoStore` property in `zowe.config.json` to `true`, the value that you enter when prompted is stored for future commands to use. The values for secure fields are stored securely in the credential vault, and the other values are written to `zowe.config.json` on disk. +The `autoStore` property in the `zowe.config.json` file lets you store the option values for properties automatically. When you specify the `autoStore` property in `zowe.config.json` to `true`, the value that you enter when prompted is stored for future commands to use. The values for secure fields are stored securely in the credential vault (if configured accordingly), and the other values are written to `zowe.config.json` on disk. -The default value of the `autoStore` property is true. However, if this behavior is undesirable (you do not want to store properties automatically), set the value of `autoStore` to false. A value of false uses the V1-LTS behavior, which prompts for missing values on all commands that you issue. \ No newline at end of file +The default value of the `autoStore` property is `true`. However, if you do not want to store properties automatically, set the value of `autoStore` to `false`. + +A value of `false` prompts for missing values on all commands that you issue. diff --git a/docs/user-guide/cli-using-initializing-team-configuration.md b/docs/user-guide/cli-using-initializing-team-configuration.md index c40bcdae8a..d7938ff5b5 100644 --- a/docs/user-guide/cli-using-initializing-team-configuration.md +++ b/docs/user-guide/cli-using-initializing-team-configuration.md @@ -1,14 +1,23 @@ # Initializing team configuration -Team configurations can be applied *globally* and *per project*, depending on the development project. See [Team configurations](../user-guide/cli-using-using-team-profiles.md) for more information. +Team configuration is a profile management method introduced in Zowe Version 2. + +:::info Required roles: Security administrator, DevOps architect +::: + +Under this method, team-specific profiles are saved in the `zowe.config.json` configuration file and user-specific profiles in the `zowe.config.user.json` configuration file. Team configuration profile management can be applied *globally* and/or *per project*, depending on the development project. See [Team configurations](../user-guide/cli-using-using-team-profiles.md) for more information. Use one of the following methods to initialize global team configuration. These instructions show how to create a configuration file that you can later open in a text editor or IDE (such as Visual Studio Code) to add or modify profiles. -**Note:** If API Mediation Layer is running on your site, [Connecting profiles to API Mediation Layer](#connecting-profiles-to-api-mediation-layer) is the recommended method to use to initialize team configuration. +:::note + +If API Mediation Layer is running on your site, [Connecting profiles to API Mediation Layer](#connecting-profiles-to-api-mediation-layer) is the recommended method to use to initialize team configuration. + +::: ## Creating a global team configuration file -1. Issue the following command: +1. To initialize a global team configuration file, open a command line window and issue the following command: ``` zowe config init --global-config @@ -20,36 +29,54 @@ Use one of the following methods to initialize global team configuration. These When the credentials are received, the `zowe.config.json` team configuration file is added to the local `.zowe` directory. Use a text editor or IDE to add or modify connection details for your mainframe services. - **Note:** Run the `zowe config init --global-config` command again after installing a new plug-in to add the plug-in profile to the global configuration file. See [Creating team plug-in profiles](#creating-team-plug-in-profiles) for information. + :::note + + Run the `zowe config init --global-config` command again after installing a new plug-in to add the plug-in profile to the global configuration file. See [Creating team plug-in profiles](#creating-team-plug-in-profiles) for information. + + ::: -3. (Optional) Issue a Zowe CLI command to test access to z/OSMF. +3. To test access to z/OSMF, issue a Zowe CLI command. - For example, list all data sets under your user ID by entering your information in the following example command: + For example, list all data sets under your user ID: ``` zowe zos-files list data-set "IBMUSER.*" ``` + - `IBMUSER` + + Specifies your user ID. + A list of data sets is returned, indicating Zowe CLI is successfully configured to access a z/OSMF instance. If the CLI returns an error message, verify that you have access to the target system. Examine the configuration files in a text editor to check that the entered information is correct. -**Important:** After the configuration file is in place (by using either the `zowe config init` command or a file provided by a system administrator), the `zowe profiles` commands used in Zowe v1 no longer function. Zowe CLI returns errors when deprecated profile commands are issued. +:::info Important + +After the configuration file is in place (by using either the `zowe config init` command or a file provided by a system administrator), the `zowe profiles` commands used in Zowe V1 no longer function. Zowe CLI returns errors when deprecated profile commands are issued. + +::: ## Creating team plug-in profiles After the `zowe.config.json` team configuration file is created and new plug-ins are installed, run the `zowe config init` (or `zowe config auto-init`, if using the API ML) command again to add the plug-in profiles to the configuration file. +To create a team plug-in profile: + 1. Install a new plug-in. - For example, run the following command to install the [IBM CICS Plug-in](../user-guide/cli-cicsplugin.md): + For example, open a command line window and issue the following command to install the [IBM CICS Plug-in](../user-guide/cli-cicsplugin.md) from an npm online registry: ``` zowe plugins install @zowe/cics-for-zowe-cli ``` - **Note:** If the `zowe.config.json` file has not yet been created in the `.zowe` directory, see [Creating a global team configuration file](#creating-a-global-team-configuration-file). + :::note + + If the `zowe.config.json` file has not yet been created in the `.zowe` directory, see [Creating a global team configuration file](#creating-a-global-team-configuration-file). + + ::: -2. Run the `zowe config init --global-config` or `zowe config auto-init --global-config` command. +2. Issue the `zowe config init --global-config` or `zowe config auto-init --global-config` command. This adds a plug-in profile to the configuration file in the `.zowe` home directory. @@ -69,32 +96,43 @@ After the `zowe.config.json` team configuration file is created and new plug-ins The plug-in profile has been successfully added to the `zowe.config.json` file in the `.zowe` home directory. - **Note:** To add plug-in profiles to a configuration file in the current working directory, enter the base command without the `--global-config` option: `zowe config init`. + :::note + + To add plug-in profiles to a configuration file in the current working directory, enter the base command without the `--global-config` option: `zowe config init`. + + ::: ## Connecting profiles to API Mediation Layer -If you are using the API Mediation Layer, set up the `zowe.config.json` file to automatically access the services that are registered to the API ML and support Single Sign-On. +You can use profiles to connect to the API Mediation Layer. This more efficient way to connect to the mainframe allows you to specify a host and port only once on a base profile instead of multiple host-and-port combinations across several service profiles. + +To set up the `zowe.config.json` file to automatically access the services that are registered to the API ML and support Single Sign-On: -1. Run the following command: +1. Open a command line window and issue the following command: ``` zowe config auto-init --global-config ``` + :::note + + To add a profile to a configuration file in the current working directory, enter the base command without the `--global-config` option: `zowe config auto-init`. + + ::: + 2. Respond to subsequent CLI prompts with the following information: - The host name and port to your API ML instance. - Your username and password. - A default profile is added to the configuration file in the `.zowe` home directory. + A default base profile is added to the configuration file in the `.zowe` home directory. -**Note:** To add a profile to a configuration file in the current working directory, enter the base command without the `--global-config` option: `zowe config init`. + :::note + + To use certificates instead of basic authentication (such as user ID and password), you can specify the options `--cert-file` and `--cert-key-file` on the base command (`zowe config auto-init`). For more information on how to log in with certificates, see [Integrating with API Mediation Layer](../user-guide/cli-using-integrating-apiml). + + ::: -**Using Certificates:** -If using certificates to authenticate, specify the details for the certificates by modifying the following example command: -``` -zowe auth login apiml --cert-file "/path/to/cert/file" --cert-key-file "/path/to/cert/key/file" -``` diff --git a/docs/user-guide/cli-using-initializing-user-configuration.md b/docs/user-guide/cli-using-initializing-user-configuration.md new file mode 100644 index 0000000000..9973804d75 --- /dev/null +++ b/docs/user-guide/cli-using-initializing-user-configuration.md @@ -0,0 +1,70 @@ +# Initializing user configuration + +As an application developer or Zowe CLI user, you can manage your connection details efficiently and in one location. + +Typically, that means the use of a team configuration file. An important convenience of team configuration is that it is easier to share connection information. Another advantage (whether you work in a team or are the sole developer in your organization) is that team configuration is optimized to leverage the broadest capabilities of Zowe CLI. + +However, there might come a time when applying your own *user* configuration file could make sense. + +The necessity of user configuration is rare, and setting up a user configuration file should not be a priority unless there is a specific need for one. For example, user configuration can be helpful when only one user needs access to a highly restricted project. + +If you do want to use user configuration, it is advised that you create your `zowe.config.user.json` file after you have a global team configuration `zowe.config.json` file in place. + +To learn more about how profiles and different configuration files work, see [How Zowe CLI uses configurations](../user-guide/cli-using-understand-profiles-configs.md). + +## Creating user profiles + +Generate a *user* configuration file that overrides the values defined in the global `zowe.config.json` file: + +1. If you do not already have a global team configuration file, open a command line prompt and issue the following command to generate one: + + ``` + zowe config init --global-config + ``` + + The configuration file `zowe.config.json` is created in the `ZOWE_CLI_HOME` directory. + + +2. Respond to subsequent prompts to create connection profiles for mainframe services. + +3. Generate the global user configuration file: + + ``` + zowe config init --global-config --user-config + ``` + + The configuration file `zowe.config.user.json` is created in the `ZOWE_CLI_HOME` directory. + + When created, the user configuration file contains profiles with no properties and the `defaults` object is empty. Refer to the following example. + + ```{ + "$schema": "./zowe.schema.json", + "profiles": { + "zosmf": { + "type": "zosmf", + "properties": {}, + "secure": [] + }, + "tso": { + "type": "tso", + "properties": {}, + "secure": [] + }, + "ssh": { + "type": "ssh", + "properties": {}, + "secure": [] + }, + "global_base": { + "type": "base", + "properties": {}, + "secure": [] + } + }, + "defaults": {}, + "autoStore": true + } + + ``` + +4. Use a text editor or IDE (such as Visual Studio Code) to add your connection details as properties in the `zowe.config.user.json` file to either override the same properties in `zowe.config.json`, or to add new connection details. diff --git a/docs/user-guide/cli-using-integrating-apiml.md b/docs/user-guide/cli-using-integrating-apiml.md index f04f4beee1..e85f6323bf 100644 --- a/docs/user-guide/cli-using-integrating-apiml.md +++ b/docs/user-guide/cli-using-integrating-apiml.md @@ -81,7 +81,7 @@ To access mainframe services through API ML using the token in your base profile * `--base-path`: Indicates the base path of the API ML instance that you want to access. - - To establish a base path, see instructions for [Zowe V2 profiles](#specifying-a-base-path-with-zowe-v2-profiles) or [Zowe V1 profiles](#specifying-a-base-path-with-zowe-v1-profiles). + - To establish a base path, see instructions for [Zowe V2 profiles](#specifying-a-base-path-with-zowe-v2-profiles). * `--disable-defaults`: Prevents default values from being stored in service profiles. If you do not use this flag, the defaults can override values in your base profile. :::note @@ -104,7 +104,7 @@ Use the following steps to specify a base path with Zowe V2 profiles: The format of base paths can vary based on how API ML is configured at your site. -2. Using the example included in Step 1, access the API ML instance by creating or updating a [service profile](../user-guide/cli-using-using-team-profiles#zowe-cli-profile-types), or issuing a command, with the `--base-path` value of `ibmzosmf/api/v1`. Your service profile uses the token and credentials stored in your default base profile. +2. Using the example included in Step 1, access the API ML instance by creating or updating a [service profile](../user-guide/cli-using-using-team-profiles.md#zowe-cli-profile-types), or issuing a command, with the `--base-path` value of `ibmzosmf/api/v1`. Your service profile uses the token and credentials stored in your default base profile. To create or update a service profile with the preceding base path in a **project** team configuration file: diff --git a/docs/user-guide/cli-using-issuing-first-command.md b/docs/user-guide/cli-using-issuing-first-command.md index 4ff4df4566..f1567bb6cb 100644 --- a/docs/user-guide/cli-using-issuing-first-command.md +++ b/docs/user-guide/cli-using-issuing-first-command.md @@ -1,9 +1,15 @@ # Issuing your first command -You can provide all connection options directly on commands to access a service. For example, issue the following command to list all data sets under the name `ibmuser` on the specified system: +Typically, users rely on [team configuration](../appendix/zowe-glossary.md#team-configuration) to connect to the mainframe and issue commands. + +But if you have just installed Zowe CLI and have not yet configured your profiles, you can provide all connection options directly in the command line to access a service. + +For example, issue the following command to list all data sets under the name `ibmuser` on the specified system: ``` zowe zos-files list data-set "ibmuser.*" --host host123 --port port123 --user ibmuser --password pass123 ``` -If you omit username, password, host, or port (and a value cannot be found in your configuration), the CLI prompts you to enter a value. +- If you omit username, password, host, or port, and a value cannot be found in your configuration, Zowe CLI prompts you to enter a value. + +However, this is not the most efficient way to communicate with the mainframe. To avoid having to enter connection details with every command repeatedly, use team profiles. diff --git a/docs/user-guide/cli-using-setting-environment-variables-in-automation-server.md b/docs/user-guide/cli-using-setting-environment-variables-in-automation-server.md index 9492249e12..8eb3474360 100644 --- a/docs/user-guide/cli-using-setting-environment-variables-in-automation-server.md +++ b/docs/user-guide/cli-using-setting-environment-variables-in-automation-server.md @@ -1,6 +1,11 @@ # Setting environment variables in an automation server -You can use environment variables in an automation server, such as Jenkins, to write more efficient scripts and make use of secure credential storage. Automation tools such as Jenkins automation server usually provide a mechanism for securely storing configuration (for example, credentials). In Jenkins, you can use withCredentials to expose credentials as an environment variable (ENV) or Groovy variable. +You can use environment variables in an automation server, such as Jenkins, to write more efficient scripts and make use of secure credential storage. Automation tools such as Jenkins automation server usually provide a mechanism for securely storing configuration (for example, credentials). In Jenkins, you can use `withCredentials` to expose credentials as an environment variable (ENV) or Groovy variable. -You can either set environment variables using the `SET` command within your scripts, or navigate to **Manage Jenkins \> Configure System \> Global Properties** and define an environment variable in the Jenkins GUI. For example: -![jenkins gui](../images/guides/CLI/envVarsJenkins.png) \ No newline at end of file + You can set environment variables by using one of the following options: + - The `SET` command within your scripts + - The Jenkins web interface to navigate to **Manage Jenkins \> Configure System \> Global Properties** and define an environment variable in the Jenkins GUI. + +For an example of using the web interface, see the following image: + +![jenkins gui](../images/guides/CLI/envVarsJenkins.png) diff --git a/docs/user-guide/cli-using-sharing-team-config-files.md b/docs/user-guide/cli-using-sharing-team-config-files.md index 2a3f92aced..fe590d3a99 100644 --- a/docs/user-guide/cli-using-sharing-team-config-files.md +++ b/docs/user-guide/cli-using-sharing-team-config-files.md @@ -1,41 +1,50 @@ -# Sharing team configuration files +# Sharing team configuration + +As a team leader, or DevOps advocate, you might want to share a team configuration globally in the following scenarios: + +- You want to share profiles with application developers so that they can work with a defined set of mainframe services. The recipient of the file places it in their local `~/.zowe` folder manually before issuing CLI commands. +- You want to add the profiles to your project directory in a software change management (SCM) tool, such as GitHub. When you store the profiles in an SCM tool, application developers can pull the project to their local computer and use the defined configuration. Zowe CLI commands that you issue from within the project directory use the configuration scheme for the project automatically. +- You want to enable test automation in a CI/CD pipeline, which lets your pipelines make use of the project configuration. Team leaders can share team configuration files using several methods: - Shared network drive - Project repository (for example, GitHub) - Web server -The following topics describe how to share the team configuration files. - ## Network drive +To use a network drive to share a team configuration file: + 1. Store the configuration files on a shared network drive. -2. Issue the following command: +2. Open a command line prompt and issue the following command: ``` zowe config import :\\zowe.config.json ``` - `` - The drive letter of the shared network drive + Specifies the drive letter of the shared network drive - `` - The directory path on the drive + Specifies the directory path on the drive - **Note:** You can specify any path that file management applications, such as Windows Explorer and Finder, can access. For example, a UNC network path (`\\\SharedZoweConfig\zowe.config.json`) or local file path (`C:\Users\\Downloads\zowe.config.json`). + :::note + + You can specify any path that file management applications, such as Windows Explorer and Finder, can access. For example, a UNC network path (`\\\SharedZoweConfig\zowe.config.json`) or local file path (`C:\Users\\Downloads\zowe.config.json`). + ::: ## Project repository and web server -Team leaders can import configuration files from a web URL that is in raw json format. The following steps describe how to import the configuration file from a GitHub repository and a web server. +To import the team configuration file from a GitHub repository and a web server: 1. Store the configuration files in a project repository or on a web server. 2. Issue the following command: - - **Project (GitHub) repository** + - **Project repository** (such as GitHub) ``` zowe config import https://:@/raw////zowe.config.json @@ -71,6 +80,12 @@ Team leaders can import configuration files from a web URL that is in raw json f zowe config import https://:@//zowe.config.json ``` + :::note + + You can host team configuration files on **private** and **public** web servers. The user name and password are required for only private URLs. However, to maintain the highest level of security, you should **not** store team configuration files on public URLs. + + ::: + - `` Specifies the user ID @@ -82,18 +97,21 @@ Team leaders can import configuration files from a web URL that is in raw json f Specifies the host name of the system - `` - - Specifies the path to the team configuration file + Specifies the path to the team configuration file + - **Note:** You can host team configuration files on **private** and **public** web servers. The user name and password are required for **only private URLs**. However, to maintain the highest level of security, you **should not store** team configuration files on public URLs. -**Tip:** To import the schema automatically from shared drives and from web servers, store the schema in the same directory as the `zowe.config.json` file. In the configuration file, reference the schema as a relative path at the top of the configuration file. + :::tip -**Example:** + To import the schema automatically from shared drives and from web servers, store the schema in the same directory as the `zowe.config.json` file. In the configuration file, reference the schema as a relative path at the top of the configuration file. + + **Example:** + + ``` + json + { + "$schema": "./zowe.schema.json", + ... + } -``` -json -{ - "$schema": "./zowe.schema.json", - ... -} \ No newline at end of file + ::: diff --git a/docs/user-guide/cli-using-team-managing-credential-security.md b/docs/user-guide/cli-using-team-managing-credential-security.md index 33b536bed2..5b1a3f418f 100644 --- a/docs/user-guide/cli-using-team-managing-credential-security.md +++ b/docs/user-guide/cli-using-team-managing-credential-security.md @@ -2,9 +2,9 @@ ## Secure credential storage -With the introduction of team profiles in Zowe CLI V2, the **Secure Credential Store (SCS) Plug-in** is deprecated. The `zowe scs` command group is obsolete. +The Zowe CLI **Secure Credential Store (SCS) Plug-in** was deprecated in Zowe V2, rendering the `zowe scs` command group obsolete. -Secure credential encryption is now included with the Zowe CLI core application. When a command using a profile with missing `user` and `password` information is issued, Zowe CLI V2 prompts you to enter the username and password. Both are then stored securely by default. +Secure credential encryption is included with the Zowe CLI core application. When a command using a profile with missing `user` and `password` information is issued, Zowe CLI prompts you to enter the username and password. Both are then stored securely by default. For other ways to store credentials securely, use the `zowe config` command group. See the following instructions. @@ -34,13 +34,13 @@ Create a configuration file and set its secure properties (such as usernames and ``` A configuration file is created, if one does not already exist. - Additionally, the `profiles.base.properties.user` and `profiles.base.properties.password` fields are added to the base profile `secure` array for that configuration file. Zowe CLI stores the username and password in the [secure credential store](../appendix/zowe-glossary#secure-credential-store). + Additionally, the `user` and `password` fields are added to the generated base profile's `secure` array for that configuration file. Zowe CLI stores the username and password in the [secure credential store](../appendix/zowe-glossary#secure-credential-store). 3. If needed, add other fields to the secure array. - Use a text editor or an IDE (such as Visual Studio Code) to edit the configuration file. - Issue the `zowe config set --secure ` command to secure a specific property in a specific profile. - For example, `zowe config set profiles.base.properties.password pw123 --secure` adds the `password` property to the base profile's `secure` array and saves the password `pw123` in the secure credential store. + For example, in a global configuration file, `zowe config set profiles.global_base.properties.password pw123 --secure` adds the `password` property to the `global_base` profile's `secure` array and saves the password `pw123` in the secure credential store. If you issue the command for a property that is already secured, the CLI prompts you to enter a new property value. diff --git a/docs/user-guide/cli-using-understand-profiles-configs.md b/docs/user-guide/cli-using-understand-profiles-configs.md index ae85e38fb5..906481cfc2 100644 --- a/docs/user-guide/cli-using-understand-profiles-configs.md +++ b/docs/user-guide/cli-using-understand-profiles-configs.md @@ -18,7 +18,7 @@ If configuration files were used in the example above, the user would have neede ## Learning the terminology -Zowe version 2.0 introduces the use of team profiles in configuration files. +As of Zowe V2, Zowe CLI relies on the profiles stored in configuration files to obtain connection information. Both *user* and *team* profiles are stored in configuration files, and these configuration files can either be *project* configuration files or *global* configuration files. It is helpful to understand how these differ. @@ -49,7 +49,7 @@ When checking all possible configuration file types, Zowe CLI categorizes files ![Zowe CLI Config File Table](../images/common/cli-config-file-table.jpg) -This order is applied no matter the directory in which you issue a Zowe CLI command. As a user, it can be easy to trace this logic when configuration files are all either in your ZOWE_CLI_HOME directory (i.e., broad scope) or your project directory (i.e., narrow scope). +This order is applied no matter the directory in which you issue a Zowe CLI command. As a user, it can be easy to trace this logic when configuration files are all either in your ZOWE_CLI_HOME directory (broad scope) or your project directory (narrow scope). But when there are configuration files across directories (meaning, in a project directory *and* a home directory), tracking how these files work together can seem more complicated. @@ -57,7 +57,7 @@ Read on to go over some examples. ## Using a profile found in multiple configuration files -Consider a user that has all configuration file types as in the following scenario: +Consider a user that has all configuration file types, as in the following scenario: | specificity type | file type | profile | property | value | |----------- | ----------- | ----------- | ----------- | ----------- | @@ -102,12 +102,12 @@ The table below shows how Zowe CLI determines which profiles, properties, and va | Configuration files in use                                                    | Specificity rules | Profiles, properties
and values used                                     | | :--------- | :------------ |:------------ | -| - global user profile
- global team profile | - When the same property exists within the same profile in both config files, the property value from the global user config is used.
- When the same profile exists in both config files, but a property of that profile exists in only one file, that property is used.
- If a profile exists in only one config file, that profile is used in its entirety. | **abc:** *direction:* south
**abc:** *numbers:* 123
**def:** *shape:* circle
**ghi:** *texture:* bumpy
**pqr:** *distance:* near | -| - project team profile
- global user profile
- global team profile | - When a profile exists in all three config files, the project team profile is used.*
- If a profile exists in only one config file, that profile is used in its entirety. | **abc:** *direction:* east
**def:** *shape:* square
**ghi:** *texture:* bumpy
**mno:** *fruit:* banana
**pqr:** *distance:* near | -| - project user profile
- project team profile
- global user profile
- global team profile | - When the same profile with the same properties exists in all four config files, the property values from the project user config is used.
- When the same profile exists in all four config files, the project files override the global files. If a property of the profile exists in only one of the two project configurations, that property is used.*
- If a profile exists in only one config file, that profile is used in its entirety. | **abc:** *direction:* north
**def:** *shape:* triangle
**ghi:** *texture:* bumpy
**jkl:** *temperature:* cold
**mno:** *fruit:* banana
**pqr:** *distance:* near | +|
  • global user profile
  • global team profile
|
  • When the same property exists within the same profile in both config files, the property value from the global user config is used.
  • When the same profile exists in both config files, but a property of that profile exists in only one file, that property is used.
  • If a profile exists in only one config file, that profile is used in its entirety.
| **abc:** *direction:* south
**abc:** *numbers:* 123
**def:** *shape:* circle
**ghi:** *texture:* bumpy
**pqr:** *distance:* near | +|
  • project team profile
  • global user profile
  • global team profile
|
  • When a profile exists in all three config files, the project team profile is used.*
  • If a profile exists in only one config file, that profile is used in its entirety.
| **abc:** *direction:* east
**def:** *shape:* square
**ghi:** *texture:* bumpy
**mno:** *fruit:* banana
**pqr:** *distance:* near | +|
  • project user profile
  • project team profile
  • global user profile
  • global team profile
|
  • When the same profile with the same properties exists in all four config files, the property values from the project user config is used.
  • When the same profile exists in all four config files, the project files override the global files. If a property of the profile exists in only one of the two project configurations, that property is used.*
  • If a profile exists in only one config file, that profile is used in its entirety.
| **abc:** *direction:* north
**def:** *shape:* triangle
**ghi:** *texture:* bumpy
**jkl:** *temperature:* cold
**mno:** *fruit:* banana
**pqr:** *distance:* near | -* If the same profile exists in both a global configuration file and a project configuration file, the project configuration profile completely replaces the global profile. This is true even when the project profile has fewer properties in the same profile found in the global file.

+* If the same profile exists in both a global configuration file and a project configuration file, the project configuration profile completely replaces the global profile. This is true even when the project profile has fewer properties in the same profile found in the global file.
-The rules above apply when profiles have the same name. To maintain the same set of properties in two different profiles, give each profile a different name so that Zowe CLI uses a specific profile, if needed. +The preceding rules apply when profiles have the same name. To maintain the same set of properties in two different profiles, give each profile a different name so that Zowe CLI uses a specific profile, if needed. For more information on how configuration files work together, see [How Zowe CLI team configuration files are merged together](https://github.com/zowe/zowe-cli/blob/master/docs/How_config_files_are_merged.md). diff --git a/docs/user-guide/cli-using-understanding-core-command-groups.md b/docs/user-guide/cli-using-understanding-core-command-groups.md index e4393811c5..2b9c0e3918 100644 --- a/docs/user-guide/cli-using-understanding-core-command-groups.md +++ b/docs/user-guide/cli-using-understanding-core-command-groups.md @@ -1,78 +1,87 @@ # Understanding core command groups -Zowe CLI contains command groups that focus on specific business processes. For example, the `zos-files` command group lets you interact with mainframe data sets. This article provides a brief synopsis of the tasks that you can perform with each group. For more information, see [Displaying help](../user-guide/cli-using-displaying-help.md). +Zowe CLI contains command groups that focus on specific business processes. -The commands available in the product are organized in a hierarchical structure. Command groups (for example, `zos-files`) contain actions (for example, `create`) that let you perform actions on specific objects (for example, a specific type of data set). For each action that you perform on an object, you can specify options that affect the operation of the command. -Zowe CLI contains the following command groups: +Zowe CLI commands are organized in a hierarchical structure. Command groups contain actions that let you perform actions on specific objects. For each action that you perform on an object, you can specify options that affect the operation of the command. + +For example, the `zos-files` command group can let you perform actions on data sets such as `create`, `edit`, `rename`, and more. + +Review the following Zowe CLI command groups to understand the actions available to them. ## auth -The auth command group lets you connect to Zowe API Mediation Layer authentication service and obtain a token, or disconnect from the authentication service and revoke the token. +The `auth` command group lets you connect to the Zowe API Mediation Layer authentication service and obtain a token, or disconnect from the authentication service and revoke the token. + +:::note -**Note:** For more information about `auth` syntax, actions, and options, open Zowe CLI and issue the following command: +For more information about `auth` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe auth -h ``` + +::: + ## config -The config command group lets you manage JSON projects, global configuration, and convert profiles (service profiles and base profiles) to team profiles. +The `config` command group lets you manage project and global team configurations, and JSON projects; and convert profiles (service profiles and base profiles) to team configs. -**Note:** For more information about `config` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `config` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe config -h ``` + +::: + ## daemon -The daemon command groups let you perform operations that control the daemon-mode functionality of the Zowe CLI. Daemon-mode runs the CLI command processor as a daemon to improve performance. +The `daemon` command groups let you perform operations that control the daemon-mode functionality of the Zowe CLI. Daemon-mode runs the CLI command processor as a background process to improve performance. + +:::note -**Note:** For more information about `daemon` syntax, actions, and options, open Zowe CLI and issue the following command: +For more information about `daemon` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe daemon -h ``` -**Important!** Using daemon mode contains various limitations and configuration requirements, depending on the operating system where the daemon is running. For more information, see **Preparing for installation** in [Using daemon mode](../user-guide/cli-using-using-daemon-mode.md). +::: + +:::info Important + +Using daemon mode contains various limitations and configuration requirements, depending on the operating system where the daemon is running. For more information, see **Preparing for installation** in [Using daemon mode](../user-guide/cli-using-using-daemon-mode.md). + +::: ## plugins -The plugins command group lets you install and manage third-party +The `plugins` command group lets you install and manage third-party plug-ins for the product. Plug-ins extend the functionality of Zowe CLI in the form of new commands. -With the plugins command group, you can perform the following tasks: + +With the `plugins` command group, you can perform the following tasks: * Install or uninstall third-party plug-ins. * Display a list of installed plug-ins. -* Validate that a plug-in integrates with the base product -properly. +* Validate that a plug-in integrates with the base product properly. + +:::note -**Note:** For more information about `plugins` syntax, actions, and options, open Zowe CLI and issue the following +For more information about `plugins` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe plugins -h ``` - -## profiles - -The profiles command group lets you create and manage profiles for use with other Zowe CLI command groups. Profiles allow you to issue commands to different mainframe systems quickly, without specifying your connection details with every command. -With the profiles command group, you can perform the following tasks: - -* Create, update, and delete profiles for any Zowe CLI command group that supports profiles. -* Set the default profile to be used within any command group. -* List profile names and details for any command group, including the default active profile. - -**Note:** For more information about `profiles` syntax, actions, and options, open Zowe CLI, and issue the following command: - -``` -zowe profiles -h -``` +::: ## provisioning -The provisioning command group lets you perform IBM z/OSMF provisioning tasks with templates and provisioned instances from Zowe CLI. +The `provisioning` command group lets you perform IBM z/OSMF provisioning tasks with templates and provisioned instances from Zowe CLI. -With the provisioning command group, you can perform the following +With the `provisioning` command group, you can perform the following tasks: * Provision cloud instances using z/OSMF Software Services templates. @@ -80,37 +89,48 @@ tasks: * List summary information about the templates that you used to provision cloud instances. You can filter the information by application (for example, DB2 and CICS) and by the external name of the provisioned instances. * List detail information about the variables used (and their corresponding values) on named, published cloud instances. -**Note:** For more information about `provisioning` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `provisioning` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe provisioning -h ``` +::: + ## zos-console -The zos-console command group lets you issue commands to the z/OS console by establishing an extended Multiple Console Support (MCS) console. +The `zos-console` command group lets you issue commands to the z/OS console by establishing an extended Multiple Console Support (MCS) console. -With the zos-console command group, you can perform the following +With the `zos-console` command group, you can perform the following tasks: -**Important\!** Before you issue z/OS console commands with Zowe CLI, security administrators should ensure that -they provide access to commands that are appropriate for your -organization. +:::info Important + +Before you issue z/OS console commands with Zowe CLI, security administrators should ensure that +they provide access to commands that are appropriate for your organization. + +::: * Issue commands to the z/OS console. -* Collect command responses and continue to collect solicited command responses on-demand. +* Collect command responses and continue to collect solicited command responses on demand. -**Note:** For more information about `zos-console` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `zos-console` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe zos-console -h ``` +::: + ## zos-files -The zos-files command group lets you interact with data sets on z/OS systems. +The `zos-files` command group lets you interact with data sets on z/OS systems. -With the zos-files command group, you can perform the following tasks: +With the `zos-files` command group, you can perform the following tasks: * Create partitioned data sets (PDS) with members, physical sequential data sets (PS), and other types of data sets from templates. You can specify options to customize the data sets you create. * Download mainframe data sets and edit them locally in your preferred Integrated Development Environment (IDE). @@ -118,88 +138,135 @@ With the zos-files command group, you can perform the following tasks: * List available mainframe data sets. * Interact with VSAM data sets directly, or invoke Access Methods Services (IDCAMS) to work with VSAM data sets. -**Note:** For more information about `zos-files` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `zos-files` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe zos-files -h ``` + +::: + ## zos-jobs -The zos-jobs command group lets you submit jobs and interact with jobs on z/OS systems. +The `zos-jobs` command group lets you submit jobs and interact with jobs on z/OS systems. -With the zos-jobs command group, you can perform the following tasks: +With the `zos-jobs` command group, you can perform the following tasks: -* Submit jobs from JCL that resides on the mainframe or a local file. +* Submit jobs from JCL that reside on the mainframe or a local file. * List jobs and spool files for a job. * View the status of a job or view a spool file from a job. -**Note:** For more information about `zos-jobs` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `zos-jobs` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe zos-jobs -h ``` -## zos-ssh +::: -The zos-ssh command group lets you issue Unix System Services shell commands by establishing an SSH connection to an SSH server. The zos-ssh command group was previously named `zos-uss`. +## zos-logs -With the zos-uss command group, you can perform the following task: +The `zos-logs` command group retrieves the z/OS operations logs. -**Important\!** Before you issue z/OS UNIX System Services commands with Zowe CLI, security administrators must provide access for your user ID to login via SSH. -* Issue z/OS UNIX System Services shell commands over an SSH connection and stream back the response. +With the `zos-logs` command group, you can perform the following task: + +* List z/OS operations logs within a specified time frame. + +:::note -**Note:** For more information about `zos-ssh` syntax, actions, and options, open Zowe CLI and issue the following command: +For more information about `zos-logs` syntax, actions, and options, open Zowe CLI and issue the following command: ``` -zowe zos-ssh -h +zowe zos-logs -h ``` -## zos-workflows +::: -The zos-workflows command group lets you create and manage z/OSMF workflows on a z/OS system. +## zos-ssh -With the zos-workflows command group, you can perform the following tasks: +The `zos-ssh` command group lets you issue Unix System Services shell commands by establishing an SSH connection to an SSH server. The zos-ssh command group was previously named `zos-uss`. -* Create or register a z/OSMF workflow based on the properties on a z/OS system -* Start a z/OSMF workflow on a z/OS system. -* Delete or remove a z/OSMF workflow from a z/OS system. -* List the z/OSMF workflows for a system or sysplex. +With the `zos-ssh` command group, you can perform the following task: + +:::info Important -**Note:** For more information about `zos-workflows` syntax, actions, and options, open Zowe CLI and issue the following command: +Before you issue z/OS UNIX System Services commands with Zowe CLI, security administrators must provide access for your user ID to login via SSH. + +::: + +* Issue z/OS UNIX System Services shell commands over an SSH connection and stream back the response. + +:::note + +For more information about `zos-ssh` syntax, actions, and options, open Zowe CLI and issue the following command: ``` -zowe zos-workflows -h +zowe zos-ssh -h ``` +::: + ## zos-tso -The zos-tso command group lets you issue TSO commands and interact with TSO address spaces on z/OS systems. +The `zos-tso` command group lets you issue TSO commands and interact with TSO address spaces on z/OS systems. -With the zos-tso command group, you can perform the following tasks: +With the `zos-tso` command group, you can perform the following tasks: * Execute REXX scripts * Create a TSO address space and issue TSO commands to the address space. * Review TSO command response data in Zowe CLI. -**Note:** For more information about `zos-tso` syntax, actions, and options, open Zowe CLI and issue the following +:::note + +For more information about `zos-tso` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe zos-tso -h ``` +::: + +## zos-workflows + +The `zos-workflows` command group lets you create and manage z/OSMF workflows on a z/OS system. + +With the `zos-workflows` command group, you can perform the following tasks: + +* Create or register a z/OSMF workflow based on the properties on a z/OS system. +* Start a z/OSMF workflow on a z/OS system. +* Delete or remove a z/OSMF workflow from a z/OS system. +* List the z/OSMF workflows for a system or sysplex. + +:::note + +For more information about `zos-workflows` syntax, actions, and options, open Zowe CLI and issue the following command: + +``` +zowe zos-workflows -h +``` + +::: + ## zosmf -The zosmf command group lets you work with Zowe CLI profiles and get general information about z/OSMF. +The `zosmf` command group lets you work with Zowe CLI profiles and get general information about z/OSMF. -With the zosmf command group, you can perform the following tasks: +With the `zosmf` command group, you can perform the following tasks: -* Create and manage your Zowe CLI `zosmf` profiles. Profiles let you store configuration information for use on multiple commands. You can create a profile that contains your username, password, and connection details for a particular mainframe system, then reuse that profile to avoid typing it again on every command. You can switch between profiles to quickly target different mainframe subsystems. For more information, see [Team configurations](../user-guide/cli-using-using-team-profiles.md). -* Verify that your profiles are set up correctly to communicate with z/OSMF on your system. For more information, see [Test Connections to z/OSMF](../user-guide/cli-using-test-zosmf-connection). +* Verify that your profiles are set up correctly to communicate with z/OSMF on your system. For more information, see [Testing connections to z/OSMF](../user-guide/cli-using-test-zosmf-connection). * Get information about the current z/OSMF version, host, port, and plug-ins installed on your system. -**Note:** For more information about `zosmf` syntax, actions, and options, open Zowe CLI and issue the following command: +:::note + +For more information about `zosmf` syntax, actions, and options, open Zowe CLI and issue the following command: ``` zowe zosmf -h ``` + +::: diff --git a/docs/user-guide/cli-using-using-daemon-mode.md b/docs/user-guide/cli-using-using-daemon-mode.md index 07fd84dfbd..10aa284076 100644 --- a/docs/user-guide/cli-using-using-daemon-mode.md +++ b/docs/user-guide/cli-using-using-daemon-mode.md @@ -1,23 +1,24 @@ -# Using daemon mode +# Configuring daemon mode Daemon mode significantly improves the performance of Zowe CLI commands by running Zowe CLI as a persistent background process (daemon). Running Zowe CLI as daemon lets Zowe absorb the one-time startup of Node.js modules, which results in significantly faster responses to Zowe commands. -When you run Zowe in daemon mode, you run all Zowe commands as you normally run them. The first time you run a command, it starts the daemon in the background automatically and runs your desired Zowe command. Since the first Zowe command starts the daemon, the first command usually runs slower than a traditional Zowe command. However, subsequent Zowe commands run significantly faster. The daemon continues to run in the background until you close your terminal window. +:::info Required roles: Security administrator, DevOps architect +::: -**Important:** We do not recommend using daemon mode in an environment where multiple users use the same system. For example, a shared Linux server. +When you run Zowe CLI in daemon mode, you run all Zowe commands as you normally run them. The first time you run a command, it starts the daemon in the background automatically and runs your desired Zowe command. Since the first Zowe command starts the daemon, the first command usually runs slower than a traditional Zowe command. However, subsequent Zowe commands run significantly faster. The daemon continues to run in the background until you close your terminal window. ## Preparing for installation Review the following installation notes before you configure Zowe CLI to run in daemon mode: - Daemon mode does not function on z/OS UNIX System Services (USS) systems. -- When you want to run Zowe CLI to run in daemon mode on **z/Linux** operating systems, you must build the daemon mode binary on the z/Linux systems. For information about how to build the binary, see [Configure Secure Credential Store on headless Linux operating systems](cli-configure-scs-on-headless-linux-os.md). The sections [Enable daemon mode](#enable-daemon-mode) and [Disable daemon mode](#disable-daemon-mode) (in this article) **do not apply** to running Zowe CLI in daemon mode on z/Linux operating systems. -- We do not recommend using daemon mode in an environment where multiple users use the same system. For example, a shared Linux server. -- When you are running Zowe on a Windows operating system in a virtual environment (for example, Windows Sandbox), you might receive an error message that indicates that a library named `VCRUNTIME140.dll` is missing. To correct the error, install Visual C++ Redistributable for Visual Studio 2015. For more information, see [Download Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145). +- When you want Zowe CLI to run in daemon mode on z/Linux operating systems, you must build the daemon mode binary on the z/Linux systems. For information about how to build the binary, see [Configuring daemon mode on z/Linux operating systems](../user-guide/cli-configure-daemon-on-zlinux-os.md). The sections [Enabling daemon mode](#enabling-daemon-mode) and [Disabling daemon mode](#disabling-daemon-mode) (in this article) **do not apply** to running Zowe CLI in daemon mode on z/Linux operating systems. +- We do not recommend using daemon mode in an environment where multiple users use the same system. For example, a shared Linux server. This could result in increased consumption of system resources. +- When you are running Zowe on a Windows operating system in a virtual environment (for example, Windows Sandbox), you might receive an error message that indicates that a library named `VCRUNTIME140.dll` is missing. To correct the error, install Visual C++ Redistributable for Visual Studio 2015. For more information, see [Download Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145) in the Microsoft Download Center. -## Enable daemon mode +## Enabling daemon mode -The following steps describe how to enable daemon mode and how to configure Zowe to run Zowe CLI constantly in daemon mode. +To enable daemon mode and configure Zowe to run Zowe CLI constantly in daemon mode: 1. Open a terminal window and issue the following command: @@ -25,64 +26,72 @@ The following steps describe how to enable daemon mode and how to configure Zowe zowe daemon enable ``` - The command copies the Zowe executables for your operating system into the `$ZOWE_CLI_HOME/bin` (`.zowe/bin`) directory. The next command that you issue starts the daemon. -2. Add the path to the Zowe executable to your PATH environment variable. For example: + The command copies the Zowe executable for your operating system into the `$ZOWE_CLI_HOME/bin` (`.zowe/bin`) directory. The next command that you issue starts the daemon. + +2. Add the binary file path to the Zowe executable to your PATH environment variable. For example: ``` C:\Users\\.zowe\bin ``` - **Important!** Ensure that you position the path to your Zowe executables before the path into which NPM installed the Node.js script. For example, `C:\Program Files\nodejs\zowe.cmd`. For information about configuring environment variables, see the documentation for your computer's operating system. + :::info Important - **Alternative configuration**: By default, the daemon binary creates or reuses a file in the user's home directory each time a Zowe CLI command runs. In some cases, this behavior might be undesirable. To change the location that the daemon uses, see [Setting CLI daemon mode properties](../user-guide/cli-configuringcli-ev.md#setting-cli-daemon-mode-properties). - - **Note:** Complete the environment variable configuration step (Step 2) only once. + Ensure that you position the path to your Zowe executable before the path into which NPM installed the Node.js script. For example, `C:\Program Files\nodejs\zowe.cmd`. For information about configuring environment variables, see the documentation for your computer's operating system. -The following example illustrates running Zowe CLI commands with daemon mode enabled: + ::: - ``` - zowe --version - Starting a background process to increase performance ... - 7.0.0-next.202110211759 + You have successfully configured Zowe CLI to run on daemon mode. Each time a Zowe CLI command is issued, the daemon binary is loaded from the user's home directory to run the Zowe executable. - zowe --version - 7.0.0-next.202110211759 - ``` -**Note:** When you are running Zowe CLI in daemon mode using a Git Bash terminal on a Windows operating system, special characters might display using the wrong code page. For example, the default code page 437 renders a form-feed character (\f) as an emoji (♀️). To correct the problem, issue the command `chcp.com 65001` to change the code page to UTF-8. If you want the change to be persistent, add the command to your `.bashrc` file. + :::note + + In some cases, using the home directory might be undesirable. (For example, the home directory resides on a network drive and has poor file performance.) To change the location that the daemon uses, see [Setting CLI daemon mode properties](../user-guide/cli-configuringcli-ev.md#setting-cli-daemon-mode-properties). + + ::: + +## Restarting daemon mode + +Daemon mode is a long-running background process that significantly improves Zowe CLI performance by, essentially, waiting for work to perform. When you make changes to your work environment, daemon mode does not capture the changes. -## Restart daemon mode +Restarting daemon mode lets the daemon capture the changes. -Daemon mode is a long-running background process (waits for work) that significantly improves Zowe CLI performance. When you make changes to your work environment, daemon mode does not capture the changes. Restarting daemon mode lets the daemon capture the changes. Issue the following command to stop the currently running daemon and start a new daemon: +To stop the currently running daemon and start a new daemon, open a command line window and issue the following command: ``` zowe daemon restart ``` -You **must** restart daemon mode under the following scenarios: +### Changes that require daemon mode restart + +You must restart daemon mode under the following scenarios: - You changed the value of any of the following [Zowe CLI environment variables](cli-configuringcli-ev.md): - `ZOWE_CLI_HOME` - `ZOWE_APP_LOG_LEVEL` - `ZOWE_IMPERATIVE_LOG_LEVEL` - You installed, updated, or uninstalled a plug-in. -- You installed a newer version of Zowe CLI and daemon mode **was running** while you installed the newer version of Zowe CLI. +- You installed a newer version of Zowe CLI and daemon mode was running while you installed the newer version of Zowe CLI. + +:::note + +When you install another version of Zowe CLI, you should always run the `zowe daemon enable` command again. + +::: - **Note:** When you install another version of Zowe CLI, you should always run the `zowe daemon enable` command again. -- You issued a Zowe command and the following message appeared: +- You issued a Zowe command and the following message displays: ``` You may be running mismatched versions of Zowe executable and Zowe daemon. ``` - You created or updated the `.zowe.env.json` file in your home directory or the path set in the `ZOWE_CLI_HOME` environment variable. See [Configuring an environment variables file](../user-guide/cli-configuringcli-evfile) for more information. -## Disable daemon mode +## Disabling daemon mode -You can disable Zowe from running in daemon mode at any time. For example, daemon mode lacks functionality that you desire, such as viewing colored-coded commands. +You can disable Zowe CLI from running in daemon mode at any time. For example, if the daemon experiences an unexpected error. -1. Open a terminal window and issue the following command: +To disable daemon mode, open a terminal window and issue the following command: - ``` - zowe daemon disable - ``` + ``` + zowe daemon disable + ``` - The disable command stops daemon mode, removes the Zowe executables from your `.zowe/bin` directory, and disables daemon mode. \ No newline at end of file +The `disable` command stops daemon mode, removes the Zowe executable from your `.zowe/bin` directory, and disables daemon mode. diff --git a/docs/user-guide/cli-using-using-environment-variables.md b/docs/user-guide/cli-using-using-environment-variables.md index 2d4e2c5a73..51d9c889e1 100644 --- a/docs/user-guide/cli-using-using-environment-variables.md +++ b/docs/user-guide/cli-using-using-environment-variables.md @@ -10,7 +10,7 @@ You can define environment variables to execute commands more efficiently. Store The term *environment* can refer to your operating system, container environment, or automation server such as Jenkins. -Consider assigning a variable in the scenarios outlined in the following table. +Consider assigning a variable in the scenarios outlined in the following table. See [Formatting environment variables](cli-using-formatting-environment-variables.md) for instructions. | Use case | Example | Benefit | | - | - | - | diff --git a/docs/user-guide/cli-using-using-team-profiles.md b/docs/user-guide/cli-using-using-team-profiles.md index 061e6529a6..8123d4a2c3 100644 --- a/docs/user-guide/cli-using-using-team-profiles.md +++ b/docs/user-guide/cli-using-using-team-profiles.md @@ -1,6 +1,6 @@ # Team configurations -Zowe CLI V2 introduces the concept of **team profiles**, which add *team* configurations to the *user* configurations already in use by Zowe CLI V1. +Zowe CLI is configured through the use of **profiles** stored and managed in configuration files. ## Types of configuration files @@ -24,19 +24,19 @@ Both team and user configurations can be applied either *globally* or *per proje ## Zowe CLI profile types -Configuration files are made up of multiple profiles that can be used by Zowe CLI. These profiles contain credentials and/or settings that are applied by the commands run in the CLI. +Configuration files are made up of multiple profiles that can be used by Zowe CLI. These profiles contain credentials and/or settings that are applied by the commands issued in the CLI. -The following profile types were introduced in Zowe V1 and continue to be used in Zowe V2: +- **Service profiles** let you store connection information for specific mainframe service, such as IBM z/OSMF. Plug-ins can introduce other service profile types to a configuration file, such as the `cics` profile to connect to IBM CICS. -- **Service profiles** let you store connection information for specific mainframe service, such as IBM z/OSMF. Plug-ins can introduce other service profile types, such as the `cics` profile to connect to IBM CICS. +- **Base profiles** let you store connection information for use with one or more services. Depending on your configuration file type, the base profile can be either a `global_base` or `project_base` profile. Typically, there is only one base profile in a configuration file. -- **Base profiles** let you store connection information for use with one or more services. Typically, there is only one base profile in a configuration file. Service profiles can pull information from a base profile as needed, so that you can specify a common username and password once. A base profile can optionally store tokens to connect to the Zowe API Mediation Layer, which improves security by enabling Multi-Factor Authentication (MFA) and Single Sign-on (SSO). + Service profiles can pull information from a base profile as needed, so that you can specify a common username and password only once. A base profile can optionally store tokens to connect to the Zowe API Mediation Layer, which improves security by enabling Multi-Factor Authentication (MFA) and Single Sign-on (SSO). - **Parent profiles** let you nest service profiles that share some of the same properties and values into groups. There can be multiple parent profiles within a configuration file. This makes it possible to define shared properties (for example, hostname or credentials) only once in your configuration file, rather than duplicating values for each service profile. Parent profiles and nested service profiles are useful when your configuration uses multiple kinds of authentication or if your configuration is used to connect to multiple hosts. ## Updating secure credentials -To change an existing username or password in a team config profile, use the `zowe config secure` command for a quick update: +To change an existing username or password used by a team config profile, use the `zowe config secure` command for a quick update: 1. Open the Zowe CLI command prompt. @@ -55,38 +55,3 @@ To change an existing username or password in a team config profile, use the `zo New values are saved in the [secure credential store](../appendix/zowe-glossary#secure-credential-store). After the last secure value is submitted, the user returns to the system command prompt. For more ways to secure credentials in config profiles, see [Managing credential security](../user-guide/cli-using-team-managing-credential-security). - -## Benefits of team profiles - -Using team profiles in configuration files helps to improve the initial setup of Zowe CLI by making service connection details easier to share and easier to store within projects. - -Consider the following benefits of using team profiles: - -- As an application developer or team member, you can manage your connection details efficiently in one location. - -- As a Dev-Ops advocate, or team leader, you can share global configurations with your team members so that they can easily access mainframe services. You can add the file directly to your project in a software change management (SCM) application. - -- As a Dev-Ops advocate, you can quickly onboard new application developers by sharing the configuration file that your team uses with the new team member. - -- As an application developer in a small shop where your role is that of an application developer *and* a Dev-Ops advocate, you can create whatever configuration type is most suitable for your needs! - -## Important information about team profiles - -With the introduction of team profiles, the Secure Credential Store (SCS) Plug-in is deprecated. Secure credential encryption is now handled by the the secure array in the `zowe.config.json` file. - -You can convert all of your Zowe CLI and Zowe CLI plug-ins V1 profiles to team profiles by issuing the following command: - -``` -zowe config convert-profiles -``` -:::caution - -You can continue using Zowe CLI V1 profiles with Zowe CLI V2. However, we highly recommend that you implement V2 profiles with Zowe CLI V2. - - If plain text credentials exist in the original V1 profiles and are converted, the resulting V2 team configuration file, `zowe.config.json`, will also contain plain text credentials. - -::: - -- Commands in the `zowe config` [command group](../user-guide/cli-using-understanding-core-command-groups#config) now let you manage security for any option value. - -- Zowe CLI V2 prompts you to enter the username and password securely by default. diff --git a/docs/user-guide/cli-using-usingcli.md b/docs/user-guide/cli-using-usingcli.md index 624c956021..dad62ed1e2 100644 --- a/docs/user-guide/cli-using-usingcli.md +++ b/docs/user-guide/cli-using-usingcli.md @@ -1,6 +1,6 @@ # Using Zowe CLI -In this section, learn about how to use Zowe CLI, including connecting to the mainframe, managing profiles, integrating with API Mediation Layer, and more. +In this section, learn how to use Zowe CLI, including how to connect to the mainframe, manage profiles, integrate with the API Mediation Layer, and more. You can use the CLI interactively from a command window on any computer on which it is installed, or run it in a container or automation environment. @@ -8,30 +8,42 @@ You can use the CLI interactively from a command window on any computer on which Text colors could be difficult to read in some terminals. If this is the case, we suggest either adjusting the terminal settings, or setting the `FORCE_COLOR` [environment variable](../user-guide/cli-configuringcli-ev.md#setting-other-environment-variables) to `0`. For other accessibility options, check the accessibility settings for your operating system or terminal. ::: -## Supported CPU architectures, operating systems, and package/resource managers -Zowe CLI supports the following CPU architectures: +Text colors could be difficult to read in some terminals. If this is the case, we suggest either adjusting the terminal settings, or setting the `FORCE_COLOR` [environment variable](../user-guide/cli-configuringcli-ev.md#setting-other-environment-variables) to `0`. For other accessibility options, check the accessibility settings for your operating system or terminal. + +::: + +## Supported platforms + +### CPU architecture + - x64 -- Apple Silicon (M1+) with Rosetta - - The [IBM Db2 Database Plug-in for Zowe CLI](../user-guide/cli-db2plugin) has limited support on Apple Silicon. To use the Db2 plug-in, a complete re-install of Zowe CLI and CLI plug-ins is required. See [M1 processor installation](../user-guide/cli-db2-install-m1) for information. +- Apple Silicon (M1+) + :::note + The [IBM Db2 Database Plug-in for Zowe CLI](../user-guide/cli-db2plugin) has limited support on Apple Silicon. To use the Db2 plug-in, a complete re-install of Zowe CLI and CLI plug-ins is required. See [Apple Silicon processor installation](../user-guide/cli-db2-install-m1) for information. + ::: + ### Operating systems - MacOS 10.15+ - Unix-like: - [CentOS](https://www.centos.org/) 8+ - [Debian](https://www.debian.org/) 11+ - - [RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 8+ + - [Red Hat Enterprise Linux (RHEL)](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 8+ - [Ubuntu](https://ubuntu.com/) 20.04+ - - Windows 10+ ### Package/resource managers -- [NodeJS](https://nodejs.org/en) -- [npm](https://www.npmjs.com/) 6+ -- [PnPM](https://pnpm.io/) +- [NodeJS](https://nodejs.org/en) LTS versions +- [npm](https://www.npmjs.com/) versions applicable to NodeJS LTS versions +- [pnpm](https://pnpm.io/) - [Yarn](https://yarnpkg.com/)
->Using Zowe CLI on [z/OS Unix Systems Services](https://www.ibm.com/docs/en/zos/2.4.0?topic=descriptions-zos-unix-system-services) is not supported at this time. If you would like to use it on USS in the future, show your interest by voting for the enhancement in the [Zowe CLI GitHub repository](https://github.com/zowe/zowe-cli/issues/1680). +:::info share your feedback + +Using Zowe CLI on [z/OS Unix Systems Services](https://www.ibm.com/docs/en/zos/2.4.0?topic=descriptions-zos-unix-system-services) is not supported at this time. If you would like to use it on USS in the future, show your interest by voting for the enhancement in the [Zowe CLI GitHub repository](https://github.com/zowe/zowe-cli/issues/1680). + +::: diff --git a/docs/user-guide/cli-using-working-certificates.md b/docs/user-guide/cli-using-working-certificates.md index a4b3978dbe..211042ef81 100644 --- a/docs/user-guide/cli-using-working-certificates.md +++ b/docs/user-guide/cli-using-working-certificates.md @@ -2,21 +2,56 @@ Certificates authorize communication between a server and client, such as z/OSMF and Zowe CLI. The client CLI must "trust" the server to successfully issue commands. Use one of the following methods to let the CLI communicate with the server. ## Configure certificates signed by a Certificate Authority (CA) -System Administrators can configure the server with a certificate signed by a Certificate Authority (CA) trusted by Mozilla. When a CA trusted by Mozilla exists in the certificate chain, the CLI automatically recognizes the server and authorizes the connection. -**Related information:** -- [Using certificates with z/OS client/server applications](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.icha700/icha700_Using_certificates_with_z_OS_client_server_applications.htm) in the IBM Knowledge Center. -- [Configuring the z/OSMF key ring and certificate](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua300/izuconfig_KeyringAndCertificate.htm) in the IBM Knowledge Center. +System administrators can configure the server with a certificate signed by a Certificate Authority (CA) trusted by Mozilla. When a CA trusted by Mozilla exists in the certificate chain, the CLI automatically recognizes the server and authorizes the connection. + +:::info find out more + +- [Using certificates with z/OS client/server applications](https://www.ibm.com/docs/en/zos/2.5.0?topic=certificates-using-zos-clientserver-applications) in the IBM Documentation. +- [Configuring the z/OSMF key ring and certificate](https://www.ibm.com/docs/en/zos/2.5.0?topic=configurations-configuring-zosmf-server-certificate-key-ring) in the IBM Documentation. - [Certificate management in Zowe API Mediation Layer](../extend/extend-apiml/certificate-management-in-zowe-apiml.md) - [Mozilla Included CA Certificate List](https://wiki.mozilla.org/CA/Included_Certificates) + +::: + ## Extend trusted certificates on client -If your organization uses self-signed certificates in the certificate chain (rather than a CA trusted by Mozilla), you can download the certificate to your computer add it to the local list of trusted certificates. Provide the certificate locally using the `NODE_EXTRA_CA_CERTS` environment variable. Organizations might want to configure all client computers to trust the self-signed certificate. -[This blog post](https://medium.com/@dkelosky/zowe-cli-providing-node-extra-ca-certs-117727d936e5) outlines the process for using environment variables to trust the self-signed certificate. + +If your organization uses self-signed certificates in the certificate chain (rather than a CA trusted by Mozilla), you can download the certificate to your computer and add it to the local list of trusted certificates. Provide the certificate locally using the `NODE_EXTRA_CA_CERTS` environment variable. + +Organizations might want to configure all client computers to trust the self-signed certificate. + +:::info find out more + +The blog post [Zowe CLI: Providing NODE_EXTRA_CA_CERTS](https://medium.com/@dkelosky/zowe-cli-providing-node-extra-ca-certs-117727d936e5) outlines the process for using environment variables to trust a self-signed certificate. + +::: + ## Bypass certificate requirement + If you do not have server certificates configured at your site, or you want to trust a known self-signed certificate, you can append the `--reject-unauthorized false` flag to your CLI commands. Setting the `--reject-unauthorized` flag to `false` rejects self-signed certificates and essentially bypasses the certificate requirement. -**Important!** Understand the security implications of accepting self-signed certificates at your site before you use this command. +:::warning important -**Example:** +Understand the security implications of accepting self-signed certificates at your site before you use this command. + +::: + +To bypass the certificate requirement, open a command line window and issue the following command with your information: ``` zowe zosmf check status --host --port --user --pass --reject-unauthorized false ``` + +- `` + + Specifies the host name. + +- `` + + Specifies the port number. + +- `` + + Specifies the user name. + +- `` + + Specifies the user password. diff --git a/docs/user-guide/cli-using-writing-scripts.md b/docs/user-guide/cli-using-writing-scripts.md index 47b1e01cfc..d2bf2b9283 100644 --- a/docs/user-guide/cli-using-writing-scripts.md +++ b/docs/user-guide/cli-using-writing-scripts.md @@ -2,19 +2,35 @@ You can combine multiple Zowe CLI commands in bash or shell scripts to automate actions on z/OS. Implement scripts to enhance your development workflow, automate repetitive test or build tasks, and orchestrate mainframe actions from continuous integration/continuous deployment (CI/CD) tools such as Jenkins or TravisCI. -**Note:** The type of script that you write depends on the programming languages that you use and the environment where the script is executed. The following is a general guide to Zowe CLI scripts. Refer to third-party documentation to learn more about scripting in general. +:::note -**Follow these steps:** +The type of script that you write depends on the programming languages that you use and the environment where the script is executed. The following is a general guide to Zowe CLI scripts. Refer to third-party documentation to learn more about scripting in general. + +::: + +To write a script: 1. Create a new file on your computer with the extension .sh. For example, `testScript.sh`. - **Note:** On Mac and Linux, an extension is not required. To make the file executable, issue the command `chmod u+x testScript`. -2. **(Mac and Linux only)** At the top of the file, specify the interpreter that your script requires. For example, type `#!/bin/sh` or `#!/bin/bash`. + :::note + + On Mac and Linux, an extension is not required. To make the file executable, issue the command `chmod u+x testScript`. + + ::: +2. For Mac and Linux only: At the top of the file, specify the interpreter that your script requires. For example, type `#!/bin/sh` or `#!/bin/bash`. - **Note:** The command terminal that you use to execute the script depends on what you specify at the top of your script. Bash scripts require a bash interpreter (bash terminal), while shell scripts can be run from any terminal. + :::note + + The command terminal that you use to execute the script depends on what you specify at the top of your script. Bash scripts require a bash interpreter (bash terminal), while shell scripts can be run from any terminal. + + ::: 3. Write a script using a series of Zowe CLI commands. - **Tip:** You can incorporate commands from other command-line tools in the same script. You might choose to "pipe" the output of one command into another command. + :::tip + + You can incorporate commands from other command-line tools in the same script. You might choose to "pipe" the output of one command into another command. + + ::: 4. From the appropriate command terminal, issue a command to execute the script. The command you use to execute script varies by operating system. The script runs and prints the output in your terminal. You can run scripts manually, or include them in your automated testing and delivery pipelines. @@ -27,7 +43,11 @@ Refer to the [Zowe CLI Sample Scripts repository](https://github.com/zowe/zowe-c The script in this example lists specified data sets, then loops through the list of data sets and deletes each file. You can use a similar script to clean up temporary data sets after use. -**Note:** Run this script from a bash terminal. +:::note + +Run this script from a bash terminal. + +::: ``` #!/bin/bash @@ -48,7 +68,11 @@ done The script in this example submits a job, waits for the job to enter output status, and saves the spool files to local files on your computer. -**Note:** Run this script from a bash terminal. +:::note + +Run this script from a bash terminal. + +::: ``` #! /bin/env bash @@ -72,4 +96,4 @@ while read -r id; do zowe zos-jobs view spool-file-by-id "$jobid" "$id" > ./${jobid}_spool_${id}.txt echo "Saved spool DD to ./${jobid}_spool_${id}.txt" done <<< "$spool_ids" -``` \ No newline at end of file +``` diff --git a/docs/user-guide/configmgr-using.md b/docs/user-guide/configmgr-using.md index 59dec96b12..13df27951c 100644 --- a/docs/user-guide/configmgr-using.md +++ b/docs/user-guide/configmgr-using.md @@ -1,15 +1,9 @@ -# Using the Configuration Manager +# Zowe Configuration Manager When you install the Zowe™ server components on z/OS, a utility called `configmgr` or "Configuration Manager" is bundled within. It can be used directly in a few ways, or leveraged by the `zwe` command to empower it with several abilities and even performance enhancements. The purpose of Configuration Manager is to deliver unified, validated configuration data to programs without requiring the programs to know where the configuration is stored or prove that the configuration is valid. This reduces the burden on each Zowe component to support different data storage types such as both datasets AND files and also ensures that all Zowe components have sufficient configuration validation to avoid silent or hard-to-troubleshoot errors. -## Using zwe with Configuration Manager - -Starting in Zowe version 2.3, the `zwe` command can use `configmgr` to gain several abilities and even performance enhancements. This is designed to be non-disruptive, with no changes needed to Zowe Components that are v2 conformant. The biggest change is that enabling Configuration Manager mode enforces strict validation of Zowe configuration. This is helpful to ensure there's no configuration problems and even helps pinpoint issues, but if you previously had silent issues in your configuration, enabling this may reveal them. - -To enable Configuration Manager mode, you can either set `zowe.useConfigmgr=true` in your Zowe configuration file, or you can add the `--configmgr` flag to a `zwe` command you are using. Not all `zwe` operations support Configuration Manager yet, but many do and eventually all will. - ## Validation error reporting Configuration Manager will not let Zowe servers start unless the configuration passes validation when checking it against the Zowe configuration schema. @@ -156,6 +150,10 @@ Here are some examples of templates that you can use to simplify your configurat ![templating example](../images/configure/templating.png) +### Template functions + + + ## Configuration Manager Unix executable `configmgr` is a file located within `/bin/utils` in the Zowe server component runtime for z/OS. If you run it with no arguments, it prints a help command that details what you can do with it. `configmgr` commands focus on providing input files and schemas, and then providing output such as validation success or printing the configuration. diff --git a/docs/user-guide/configure-data-sets-jobs-api.md b/docs/user-guide/configure-data-sets-jobs-api.md deleted file mode 100644 index 054d56f3a6..0000000000 --- a/docs/user-guide/configure-data-sets-jobs-api.md +++ /dev/null @@ -1,31 +0,0 @@ -# Configuring APIs for Jobs and Datasets (Deprecated) - -Review the security considerations for Zowe APIs and learn how to prevent the Denial of Service (DoS) attacks. - -The default configuration before Zowe version 1.14.0 contains **Data sets and Unix files** and **Jobs** API microservices which might be vulnerable to DoS attacks in the form of slow https attacks. You can add additional configuration to the start script of these components in order to prevent resource starvation via slow https attacks. - -- To update the configuration of the **Data sets and Unix files** component, modify the `start.sh` script within the runtime component directory `/zowe/runtime/components/files-api/bin`. -- To update the configuration of the **Jobs** component, modify the `start.sh` script within the runtime component directory `/zowe/runtime/components/jobs-api/bin`. - -Ensure that the `-Dserver.connection-timeout=8000` parameter is set. This parameter specifies how long the component waits to receive all the required information from the client that makes a request. - -See a snippet of a configured `start.sh` script for the Jobs component as follows: - -```shell -_BPX_JOBNAME=${ZOWE_PREFIX}${COMPONENT_CODE} java -Xms16m -Xmx512m -Dibm.serversocket.recover=true -Dfile.encoding=UTF-8 \ - -Djava.io.tmpdir=/tmp -Xquickstart \ - -Dserver.port=${JOBS_API_PORT} \ - -Dcom.ibm.jsse2.overrideDefaultTLS=true \ - -Dserver.ssl.keyAlias=${KEY_ALIAS} \ - -Dserver.ssl.keyStore=${KEYSTORE} \ - -Dserver.ssl.keyStorePassword=${KEYSTORE_PASSWORD} \ - -Dserver.ssl.keyStoreType=${KEYSTORE_TYPE} \ - -Dserver.compression.enabled=true \ - -Dserver.connection-timeout=8000 \ - -Dconnection.httpsPort=${GATEWAY_PORT} \ - -Dconnection.ipAddress=${ZWE_haInstance_hostname} \ - -Dspring.main.banner-mode=off \ - -Djava.protocol.handler.pkgs=com.ibm.crypto.provider \ - -jar ${ROOT_DIR}/components/jobs-api/bin/jobs-api-server-1.0.0-boot.jar & -``` -In version 1.14.0 and later, the preceding snippet reflects the default configuration. diff --git a/docs/user-guide/configure-zowe-runtime.md b/docs/user-guide/configure-zowe-runtime.md index bc95048b0c..53efa6b085 100644 --- a/docs/user-guide/configure-zowe-runtime.md +++ b/docs/user-guide/configure-zowe-runtime.md @@ -29,14 +29,11 @@ Another option to initialize Zowe z/OS runtime is to configure Zowe with z/OSMF * Configure the Zowe instance directory * Enable the API ML gateway -* Enable the metrics service * Enable the API catalog * Enable automatic discovery * Enable a caching service * Enable an application server * Enable the ZSS component -* Enable the jobs API -* Enable the files API * Enable JES Explorer * Enable MVS Explorer * Enable USS Explorer diff --git a/docs/user-guide/configure-zowe-zosmf-workflow.md b/docs/user-guide/configure-zowe-zosmf-workflow.md index 09b6739bfe..13baa6f33b 100644 --- a/docs/user-guide/configure-zowe-zosmf-workflow.md +++ b/docs/user-guide/configure-zowe-zosmf-workflow.md @@ -14,14 +14,11 @@ You can complete the following tasks with the z/OSMF workflow: - Configure the Zowe instance directory - Enable the API ML Gateway -- Enable the metrics service - Enable the API catalog - Enable automatic discovery - Enable a caching service - Enable an application server - Enable the ZSS component -- Enable the jobs API -- Enable the files API - Enable JES Explorer - Enable MVS Explorer - Enable USS Explorer diff --git a/docs/user-guide/initialize-vsam-dataset.md b/docs/user-guide/initialize-vsam-dataset.md index e5352ddff8..e5189e3d48 100644 --- a/docs/user-guide/initialize-vsam-dataset.md +++ b/docs/user-guide/initialize-vsam-dataset.md @@ -1,10 +1,13 @@ # Creating VSAM caching service datasets +:::info Deprecated: The Caching service uses Infinispan by default, no longer requiring the VSAM setup action. +::: + Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are started, either on the same LPAR or different LPARs connected through sysplex distributor. If you are only running a single Zowe instance on a single LPAR you do not need to create a caching service so you may skip this step. In an HA setup the different Zowe API Mediation Gateway servers share the same northbound port (by default `7554`), and client traffic to this port is distributed between separate gateways that in turn dispatch their work to different services. When any of the services individually become unavailable the work can be routed to available services, which means that the initial northbound request will be fulfilled. -There are different storage methods that can be used as as the caching service for Zowe. One of these is `VSAM` and this chapter describes how to create the data sets if you are using `VSAM` as your caching service. If you are using another caching service such as `redis` or `infinispan` then you do not need to create any VSAM files and you can skip the step described in this chapter. For more information on the different caching services see [Configuring the Caching Service for HA](../user-guide/configure-caching-service-ha.md). +There are different storage methods that can be used as as the caching service for Zowe. One of these is `VSAM` and this chapter describes how to create the data sets if you are using `VSAM` as your caching service. By default you do not need this step because `infinispan` is the storage mode used instead. For more information on the different caching services see [Configuring the Caching Service for HA](../user-guide/configure-caching-service-ha.md). ## Using `zwe init vsam` command diff --git a/docs/user-guide/initialize-zos-system.md b/docs/user-guide/initialize-zos-system.md index b171ee8619..53f46dc2d3 100644 --- a/docs/user-guide/initialize-zos-system.md +++ b/docs/user-guide/initialize-zos-system.md @@ -17,10 +17,10 @@ Creates the user IDs and security manager settings. APF authorizes the LOADLIB containing the modules that need to perform z/OS privileged security calls. - **certificate** Configures Zowe to use TLS certificates. -- **vsam** -Configures the VSAM files needed to run the Zowe caching service used for high availability (HA) - **stc** Configures the system to launch the Zowe started task. +- (Deprecated) **vsam** +Configures the VSAM files needed if the Caching service is set to VSAM mode. This is not required nor the default, and exists for compatibility. :::info Recommendation: We recommend you to run these sub commands one by one to clearly see the output of each step. To successfully run `zwe init security`, `zwe init apfauth`, and `zwe init certificate`, it is likely that your organization requires elevated permissions. We recommend you consult with your security administrator to run these commands. For more information about tasks for the security administrator, see the section [Configuring security](./configuring-security.md) in this configuration documentation. @@ -66,4 +66,4 @@ For more information about security administrator tasks, see: ## Next steps -For detailed information about individual `zwe init` subcommands, see [zwe init subcommand overview](./zwe-init-subcommand-overview.md). \ No newline at end of file +For detailed information about individual `zwe init` subcommands, see [zwe init subcommand overview](./zwe-init-subcommand-overview.md). diff --git a/docs/user-guide/install-configure-zos-extensions.md b/docs/user-guide/install-configure-zos-extensions.md index 48970663ff..af8d1ff763 100644 --- a/docs/user-guide/install-configure-zos-extensions.md +++ b/docs/user-guide/install-configure-zos-extensions.md @@ -81,8 +81,6 @@ The Zowe runtime directory delivers its core components in the `/co /app-server /explorer-jes /explorer-mvs - /files-api - /jobs-api /... ``` diff --git a/docs/user-guide/install-nodejs-zos.md b/docs/user-guide/install-nodejs-zos.md index 3f1ccf616a..6a1c2b24b7 100644 --- a/docs/user-guide/install-nodejs-zos.md +++ b/docs/user-guide/install-nodejs-zos.md @@ -7,7 +7,7 @@ Before you install Zowe™ on z/OS, you must install IBM SDK for Node.js on :::note Node.js is required when installing the Zowe servers on z/OS. -Node.js is not required if using Docker instead of z/OS, or if running Zowe without the app-server enabled on v2.16.0 or higher. +Node.js is not required if using Docker instead of z/OS, or if running Zowe without the app-server enabled. ::: - [Supported Node.js versions](#supported-nodejs-versions) diff --git a/docs/user-guide/install-zos.md b/docs/user-guide/install-zos.md index a920e600b8..914b690d4f 100644 --- a/docs/user-guide/install-zos.md +++ b/docs/user-guide/install-zos.md @@ -46,7 +46,7 @@ Notify your organization's network administrator to assign port numbers, reserve In most cases, the system programmer performs the Zowe installation and configuration, and starts Zowe. Ensure that your system programmers have general knowledge about SMP/E, z/OSMF workflows, and regular maintanance procedures. In many cases, the system programmer also prepares jobs for other administrators. -## End-to-end installation +## End-to-end installation The following diagram illustrates the full ecosystem for installing Zowe server-side components for z/OS. @@ -155,10 +155,9 @@ Now that you have the permissions, certificates, files, and datasets necessary t - Enabling or disabling components so you only run what you need - Changing the network ports Zowe runs on to suit your environment - Customizing the behavior of a component, such as turning on optional features or logging +- Splitting, templating, and placing your configuration into PARMLIBs with the [Zowe Configuration Manager](./configmgr-using.md) :::tip -We recommended that the first customization you perform is to [set `zwe` to use the Configuration Manager](./configmgr-using.md) - See the [Zowe YAML configuration file reference](../appendix/zowe-yaml-configuration.md) for other customization options. ::: @@ -180,4 +179,4 @@ For more information on the server configuration file, see the [Zowe YAML config ## Next step -Before starting the installation process, first review the article [Preparing for installation](./installandconfig.md) and the address the requirements outlined in the sub-articles in this section. \ No newline at end of file +Before starting the installation process, first review the article [Preparing for installation](./installandconfig.md) and the address the requirements outlined in the sub-articles in this section. diff --git a/docs/user-guide/install-zowe-client-side-components.md b/docs/user-guide/install-zowe-client-side-components.md new file mode 100644 index 0000000000..030e7988f2 --- /dev/null +++ b/docs/user-guide/install-zowe-client-side-components.md @@ -0,0 +1,23 @@ +# Installing Zowe client-side components + +Review this article to prepare to install, configure, and deploy Zowe client-side components. + +:::info Required roles: systems programmer, security administrator, storage administrator +::: + +To prepare for an installation or upgrade, your installation team should review the configuration requirements for both z/OSMF and the particular component to be installed. + +Doing so can help you complete the process faster without any delays due to missing pre-requisites that may require a system administrator to configure. + +To install your product, we recommend that your team understands the following topics: + +- JCL +- TSO/ISPF +- Your organization's IT environment, enterprise structure, and region structure +- z/OS environment and installing software in this environment +- z/OS UNIX System Services + +Consult with the following team roles, as required: +- Security administrator for access +- Storage administrator for DASD allocations +- Systems programmer for z/OS and VTAM definitions diff --git a/docs/user-guide/intellij-configure.md b/docs/user-guide/intellij-configure.md index bdc321195d..8ee7f0cb44 100644 --- a/docs/user-guide/intellij-configure.md +++ b/docs/user-guide/intellij-configure.md @@ -1,44 +1,52 @@ -# Configuring Zowe IntelliJ plug-in +# Configuring the plug-in -After you install the Zowe Intellij plug-in, you must create a z/OSMF connection to your mainframe and some working sets. +After you install the Zowe Explorer plug-in for Intellij IDEA, you must create a z/OSMF connection to your mainframe and some working sets. :::note -z/OS v2.1 or later is required z/OSMF configuration. The plug-in is in active development state. +z/OS v2.3 or later is required with a REST API z/OSMF configured properly. To use it, you need the user ID to be connected to the IZUUSER RACF group. Contact your RACF administrator to complete the setup process. ::: ## Creating z/OSMF connection There are two ways to create a z/OSMF connection: -- using the in-built plug-in feature -- using Zowe Config v2 +- using the in-built plug-in's connection configurations **(1)** +- using Zowe Team Config v2 **(2)** -### Creating the connection using the plug-in feature +![Create plug-in's connection or Zowe Config](../images/intellij/create_plugins_connection_or_zowe_config.png) -You can create a z/OSMF connection to your mainframe either by manually specifying all the needed information through the Settings tab, or by clicking the "+" sign. The z/OSMF port should be specified at the end of the address. +### Creating the connection using the plug-in's connection configurations + +You can create a connection to a z/OSMF REST API either by manually specifying all the needed information through the "Settings" tab **(1)**, or by clicking the "+" sign **(2)**. + +![Create a connection through "Settings"](../images/intellij/create_connection_settings.png)     ![Create a connection using "+" button](../images/intellij/create_connection_plus.png) To create the connection: -1. In Zowe Explorer click **+** button +1. In the Zowe Explorer click **+** button 2. Select **Connection** -3. Type in all the necessary information -4. Wait until the connection is tested +3. Type in all the necessary information in the dialog +4. Wait until the connection test is finished and all the necessary information is fetched ![Configure IntelliJ z/OSMF connection](../images/intellij/connection_create.gif) ### Creating the connection using Zowe Config v2 -*Prerequisite: Zowe CLI installed ([click here for the guide](https://docs.zowe.org/stable/user-guide/cli-installcli))* +To create the z/OSMF connection with Zowe Config v2 there are two ways. + +The first scenario - adding already existing Zowe Config v2 from a local opened project +1. Open the project with the **zowe.config.json** +2. *Zowe config file detected* notification should appear, click **Add Zowe Connection** +3. Wait until the connection is tested + +![Configure IntelliJ z/OSMF connection using Zowe Config v2](../images/intellij/create_connection_zowe_config_file.gif) -To create the z/OSMF connection with Zowe Config v2: -1. In command line, issue: `zowe config init` -2. Enter all the required information -3. After that, *Zowe config file detected* notification should appear, click **Add Zowe Connection** -4. If the connection test is failed, click **Add Anyway** -5. In Zowe Config change all the wrong parameters to the correct ones -6. Click appeared *Reload* button in the editor -7. Wait until the connection is tested +The second scenario - creating a new Zowe Config v2 from scratch: +1. In the Zowe Explorer click **+** button +2. Select **Zowe Team Configuration** +3. Fill in all the necessary information in the dialog +4. Wait until the connection test is finished and all the necessary information is fetched -![Configure IntelliJ z/OSMF connection using Zowe Config v2](../images/intellij/connection_zowe_config_v2.gif) +![Configure Zowe Team v2 from scratch](../images/intellij/create_connection_zowe_config_plus.gif) After the configuration is made, you will be able to use all the features of the plug-in. diff --git a/docs/user-guide/intellij-copy-cut.md b/docs/user-guide/intellij-copy-cut.md new file mode 100644 index 0000000000..987747abae --- /dev/null +++ b/docs/user-guide/intellij-copy-cut.md @@ -0,0 +1,327 @@ +# Copying and moving data using the plug-in + +The essential feature of the plug-in is to provide the ability to copy and move content between different entities and systems. The plug-in provides functionalities to copy and move any kind of information possible (also in terms of security). + +## Copy and move: the same system + +There are different options to copy and move z/OS data sets and members between each other, as well as USS files. It is possible to move and copy files and data sets either through keyboard shortcut buttons and context menu, or using **Drag & Drop**. + +### Copy and move: a data set member copy and move examples + +:::important note +Make sure the parameters of the target data set allow you to paste a new member. Sometimes there is an error occures during paste operation to the data set due to the directory blocks value being not enough to fit the member. +::: + +To copy member from one data set to another: +1. Right click on the member to be copied, select **Copy** + +![Copy cut: member copy](../images/intellij/copy_cut_member_copy.png) + +2. Right click on the target PDS / PDS/E data set, select **Paste** + +![Copy cut: member copy select paste](../images/intellij/copy_cut_member_copy_select_paste.png) + +3. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: member copying dialog](../images/intellij/copy_cut_member_copy_dialog.png) + +4. After the operation is completed, the data set will be automatically refreshed and the member will appear in the list of the data set members + +![Copy cut: member copy result](../images/intellij/copy_cut_member_copy_result.png) + +To move a member from one data set to another: +1. Right click on the member to be moved, select **Cut** + +![Copy cut: member cut](../images/intellij/copy_cut_member_cut.png) + +2. Right click on the target PDS / PDS/E data set, select **Paste** + +![Copy cut: member cut select paste](../images/intellij/copy_cut_member_cut_select_paste.png) + +:::note +You can use a **Drag & Drop** feature to accomplish the same action +::: + +3. A confirmation dialog for the member to be moved will appear, select **Yes** + +![Copy cut: member cut confirmation dialog](../images/intellij/copy_cut_member_cut_moving_confirmation.png) + +4. A dialog about the move operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: member moving dialog](../images/intellij/copy_cut_member_cut_dialog.png) + +5. After the operation is completed, the data set will be automatically refreshed and the member will appear in the list of the data set members + +![Copy cut: member cut result](../images/intellij/copy_cut_member_copy_result.png) + +The member will disappear from the source data set. + +![Copy cut: member cut result source](../images/intellij/copy_cut_member_cut_result_source.png) + +### Copy and move: a PS data set to a PDS member copy example + +The plug-in allows to copy and move PS data sets to PDS / PDSE data sets. The data set will become a member of the target data set. The name of the member will be trimmed to the last element of the source HLQ. If there are already a member with the same name as the newly pasted one has, the name will be changed to the same data set member's name with the last character(s) replaced with the next available number to form a non-conflicting name of the member. + +:::important note +Make sure the parameters of the target data set allow you to paste a new member. Sometimes there is an error occures during paste operation to the data set due to the directory blocks value being not enough to fit the member. +::: + +To copy a sequential data set to a partitioned data set: +1. Right click on the PS to be copied, select **Copy** + +![Copy cut: PS to PDS copy right click](../images/intellij/copy_cut_ps_to_pds_copy.png) + +2. Right click on the target PDS / PDS/E data set, select **Paste** + +![Copy cut: PS to PDS copy select paste](../images/intellij/copy_cut_member_copy_select_paste.png) + +3. If there is a conflicting name member in the data set exists, the plug-in will suggest a new name to apply to the member to appear in the data set members list. Click **Ok** to agree to use the new name + +![Copy cut: PS to PDS copy conflicts](../images/intellij/copy_cut_ps_to_pds_copy_conflicts.png) + +4. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: PS to PDS copying dialog](../images/intellij/copy_cut_ps_to_pds_copy_dialog.png) + +5. After the operation is completed, the data set will be automatically refreshed and the member will appear in the list of the data set members + +![Copy cut: PS to PDS copy result](../images/intellij/copy_cut_ps_to_pds_copy_result.png) + +### Copy and move: a USS file to a USS folder move example + +To move USS file or folder to another USS folder: +1. Right click on the folder or the file to be moved, select **Cut** + +![Copy cut: USS file to USS folder cut](../images/intellij/copy_cut_uss_to_uss_cut.png) + +2. Right click on the target USS folder, select **Paste** + +![Copy cut: USS file to USS folder cut select paste](../images/intellij/copy_cut_uss_to_uss_cut_select_paste.png) + +:::note +You can use a **Drag & Drop** feature to accomplish the same action +::: + +3. A confirmation dialog for the file to be moved will appear, select **Yes** + +![Copy cut: USS file to USS folder cut confirmation dialog](../images/intellij/copy_cut_member_cut_moving_confirmation.png) + +4. A dialog about the move operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: USS file to USS folder moving dialog](../images/intellij/copy_cut_uss_to_uss_moving_dialog.png) + +5. After the operation is completed, the path will be automatically refreshed and the file will appear in the refreshed list. Also the file will disappear from the source path + +![Copy cut: USS file to USS folder cut result](../images/intellij/copy_cut_uss_to_uss_cut_result.png) + +### Copy and move: a PDS / PDS/E member to a USS folder copy example + +There is also a functionality provided by the plug-in to copy and move PS, PDS / PDS/E data sets and members to a USS path. + +To copy a PDS / PDS/E member to a USS folder: +1. Right click on the member to be copied, select **Copy** + +![Copy cut: member to USS copy](../images/intellij/copy_cut_member_copy.png) + +2. Right click on the target USS folder, select **Paste** + +![Copy cut: member to USS copy select paste](../images/intellij/copy_cut_uss_to_uss_copy_select_paste.png) + +3. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: member to USS copying dialog](../images/intellij/copy_cut_member_to_uss_copy_dialog.png) + +4. After the operation is completed, the USS path will be automatically refreshed and the newly pasted USS file will appear + +![Copy cut: member to USS copy result](../images/intellij/copy_cut_member_to_uss_copy_result.png) + +### Copy and move: a PDS / PDS/E data set to a USS folder move example + +While moving or copying a partitioned data set to the USS path, it will be converted to a USS folder with USS files. + +To move a PDS / PDS/E data set to a USS path: +1. Right click on the PDS to be copied, select **Cut** + +![Copy cut: PDS to USS cut](../images/intellij/copy_cut_pds_to_uss_cut.png) + +2. Right click on the target USS folder, select **Paste** + +![Copy cut: PDS to USS cut paste](../images/intellij/copy_cut_pds_to_uss_cut_paste.png) + +:::note +You can use a **Drag & Drop** feature to accomplish the same action +::: + +3. A confirmation dialog for the file to be moved will appear, select **Yes** + +![Copy cut: PDS to USS cut confirmation dialog](../images/intellij/copy_cut_member_cut_moving_confirmation.png) + +4. A dialog about the move operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: PDS to USS moving dialog](../images/intellij/copy_cut_pds_to_uss_moving_dialog.png) + +5. After the operation is completed, the path will be automatically refreshed and the folder will appear in the refreshed list. Also the data set will disappear from the z/OS part + +![Copy cut: PDS to USS cut result](../images/intellij/copy_cut_pds_to_uss_cut_result.png) + +### Copy and move: a USS file to a PDS / PDS/E data set move example + +Also, it is possible to copy and move a USS file to a PDS / PDS/E data set. The file will become a PDS member. + +:::important note +The contents of the source files and data sets will stay the same, until you try to copy/move a file from USS to a z/OS partitioned data set. If the file lines are longer than the specified for the PDS / PDS/E logical record length, the plug-in will cut the rest of the line, exceeding the LRECL, for each of the exceeding lines. +::: + +To move a USS file to a PDS / PDS/E data set: +1. Right click on the file to be copied, select **Cut** + +![Copy cut: USS to PDS cut](../images/intellij/copy_cut_uss_to_pds_cut.png) + +2. Right click on the target PDS / PDS/E data set, select **Paste** + +![Copy cut: USS to PDS cut paste](../images/intellij/copy_cut_uss_to_pds_cut_paste.png) + +:::note +You can use a **Drag & Drop** feature to accomplish the same action +::: + +3. A confirmation dialog for the file to be moved will appear, select **Yes** + +![Copy cut: USS to PDS cut confirmation dialog](../images/intellij/copy_cut_member_cut_moving_confirmation.png) + +4. Also, the warning dialog about placing a USS file under a PDS / PDS/E data set will appear. It will describe the actual result of this operation. Click **Ok** + +![Copy cut: USS to PDS cut placing warning](../images/intellij/copy_cut_uss_to_pds_cut_placing_warning.png) + +5. A dialog about the move operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: USS to PDS moving dialog](../images/intellij/copy_cut_uss_to_pds_moving_dialog.png) + +6. After the operation is completed, the data set will be automatically refreshed and the list of the members will be refreshed with the new member in the list present. Also the file will disappear from the USS path + +![Copy cut: USS to PDS cut result](../images/intellij/copy_cut_uss_to_pds_cut_result.png) + +:::note +You could notice the new member name. It is formed from the first 8 alphanumeric characters of the source file. Also, when there are member name conflicts, there is a resolution mechanism implemented in the plug-in. The new name will be formed as the change of the conflicting name, adding the next available number to the new name of the new member. +::: + +## Cross-system copy and move + +The plug-in provides a functionality to move and copy z/OS data sets and USS files between different systems. E.g.: a user has two systems with different IPs. So, it is possible to copy or move files and data sets either from the first IP to the second, or vice versa. The rules of copying and moving that are described previously, are the same for this action. + +### Copy and move: a PDS / PDS/E data set to a USS path cross-system copy example + +To copy a PDS / PDS/E data set to a USS path in a different system: +1. Right click on the data set to be copied, select **Copy** + +![Copy cut: PDS to USS cross-system copy](../images/intellij/copy_cut_pds_to_uss_cross_copy.png) + +2. Right click on the target system's USS path, select **Paste** + +![Copy cut: PDS to USS cross-system copy select paste](../images/intellij/copy_cut_pds_to_uss_cross_copy_paste.png) + +3. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Copy cut: PDS to USS cross-system copy dialog](../images/intellij/copy_cut_pds_to_uss_cross_copy_dialog.png) + +4. After the operation is completed, the USS path will be automatically refreshed and the path will be refreshed with the new USS folder in the list present + +![Copy cut: PDS to USS cross-system copy result](../images/intellij/copy_cut_pds_to_uss_cross_copy_result.png) + +## Downloading USS files and folders and z/OS data sets and members + +There is a feature to download USS files and folders, as well as z/OS data sets and members. Both **Copy** and **Cut** functionalities are available for the downloading feature. + +### Download feature: a USS file download as a copy operation + +To copy a USS file to a local machine: +1. Right click on the z/OS system's USS file, select **Copy** + +![Download: USS file copy](../images/intellij/download_uss_copy.png) + +2. Right click in the local project's explorer view, select **Paste** + +![Download: USS file copy paste](../images/intellij/download_uss_copy_paste.png) + +3. If there are conflicts in the names of the entities being copied, the plug-in will ask for the option to select: + - **Skip the conflicting file(s) (1)** - will skip the entities copying + - **Replace the file(s) in the destination (2)** - will replace the entities in the destination with the being copied ones + - **Decide for each file (3)** - will ask separately for each entity being copied + +For the example purposes, select **Decide for each file (3)** + +![Download: USS file copy decide](../images/intellij/download_uss_copy_name_conflicts.png) + +4. The next dialog window will appear, asking what to do with the conflicting file: + - **Skip (1)** - will skip the entity copying + - **Overwrite (2)** - will overwrite the entity with the same name in the destination + - **Use new name (3)** - will create a new entity as a copy of the entity being copied with a new name, provided by the plug-in + +For the example purposes, select **Use new name(3)** + +![Download: USS file copy decide single](../images/intellij/download_uss_copy_single_conflict.png) + +5. The final warning dialog will appear, notifying that the operation may be against the security rules in your company. Select **Yes** + +:::warning do it on your own risk! +Do not proceed with the operation if your organization does not allow you to distribute information from your mainframe. It may contain sensitive data that is not meant to be distributed outside a mainframe. +::: + +![Download: USS file copy security warning](../images/intellij/download_uss_copy_security_warning.png) + +6. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Download: USS file copy final dialog](../images/intellij/download_uss_copy_final_dialog.png) + +7. After the operation is completed, the file will appear in your local project's tree + +![Download: USS file copy result](../images/intellij/download_uss_copy_result.png) + +## Uploading files to a USS subsystem and z/OS data sets + +It is also possible with the plug-in to upload files to a USS path and z/OS data set as a member + +### Upload feature: a file to a PDS / PDS/E member upload as a copy operation + +:::important note +Make sure the parameters of the target data set allow you to paste a new member. Sometimes there is an error occures during paste operation to the data set due to the directory blocks value being not enough to fit the member. +::: + +:::important note +The contents of the source files and data sets will stay the same, until you try to copy/move a file from USS to a z/OS partitioned data set. If the file lines are longer than the specified for the PDS / PDS/E logical record length, the plug-in will cut the rest of the line, exceeding the LRECL, for each of the exceeding lines. +::: + +To upload a file as a copy operation from a local machine to a PDS / PDS/E data sets as a member: +1. Right click on a file on the local project's tree, select **Copy** + +![Upload: local file to PDS copy](../images/intellij/upload_file_to_pds_copy.png) + +2. Right click on the destination PDS / PDS/E, select **Paste** + +![Upload: local file to PDS copy paste](../images/intellij/upload_file_to_pds_copy_paste.png) + +3. The truncation warning will appear, click **Ok** + +![Upload: local file to PDS copy truncation warning](../images/intellij/upload_file_to_pds_copy_member_truncation.png) + +4. A dialog about the copy operation appears. It is also possible to cancel the operation until it is finished + +![Upload: local file to PDS copy dialog](../images/intellij/upload_file_to_pds_copy_dialog.png) + +5. After the operation is completed, a new member will appear in the destination PDS / PDS/E + +:::note +Check the content of the member after the operation. It could be truncated due to LRECL of the data set. +::: + +![Upload: local file to PDS copy result](../images/intellij/upload_file_to_pds_copy_result.png) + +## Current limitations + +There are still some features in development and are not possible to accomplish with the plug-in: +1. **Folder uploading to a USS path** +2. **File uploading to a z/OS mask as a PS data set** +3. **USS folder copy to a z/OS mask as a PDS / PDS/E data set** +4. **Folder uploading to a z/OS mask as a PDS / PDS/E data set** + +If you have some ideas regarding these operations or want to make a change in the existing one, please, [reach out to us](https://openmainframeproject.slack.com/archives/C020BGPSU0M). diff --git a/docs/user-guide/intellij-install-prereqs.md b/docs/user-guide/intellij-install-prereqs.md new file mode 100644 index 0000000000..f7e6107d8e --- /dev/null +++ b/docs/user-guide/intellij-install-prereqs.md @@ -0,0 +1,19 @@ +# Prerequisites + +The plug-in is supported on all of the operating systems with GUI. To use the plug-in, you need to install an IntelliJ IDEA platform's IDE. The platform has a nubmer of IDEs for different purposes. E.g. if you have Java/Kotlin developers, there is an IntelliJ IDEA IDE, for Python developers, there is a PyCharm IDE, for web developers, there is a WebStorm IDE, etc. + +There are two **Community** versions of the IDEs: **IntelliJ IDEA Community** and **PyCharm Community**. It means that these IDEs are open-source and free of charge. The plug-in is supported on any IntelliJ IDEA IDE, it is enough to have the **Community** version of any of the IDEs to work with the plug-in. + +:::note +Most of the other IntelliJ IDEA IDEs are available under the *Ultimate* version. It means that they are available to use after purchasing them. They have a 30-day trial if you want to try them before the purchase. +::: + +To install the **IntelliJ IDEA Community**: +1. Proceed to the [official JetBrains download page](https://www.jetbrains.com/idea/download) +2. Scroll down to the **Community** version of the IDE, select the binary to download + +![Download IntelliJ](../images/intellij/download_intellij.png) + +3. After the binary is downloaded, walk through the installation wizard and install the IDE + +After these steps, you will be ready to proceed with the plug-in installation. diff --git a/docs/user-guide/intellij-install.md b/docs/user-guide/intellij-install.md index 06bd30d3a9..053566482a 100644 --- a/docs/user-guide/intellij-install.md +++ b/docs/user-guide/intellij-install.md @@ -1,15 +1,125 @@ -# Zowe IntelliJ plug-in -## Installing +# Installing the plug-in -You can install the plug-in in your Intellij-based IDE directly from the marketplace or download it from https://plugins.jetbrains.com/plugin/18688-zowe-explorer +There are two ways to install the plug-in: +1. **(Preferred)** Install the plug-in directly inside IntelliJ IDEA +2. Download and install binaries either from [JetBrains Marketplace page](https://plugins.jetbrains.com/plugin/18688-zowe-explorer) or from our [GitHub repository](https://github.com/zowe/zowe-explorer-intellij) + +## Installing inside IntelliJ IDEA To install the plug-in from IntelliJ: -1. Go to **File -> Settings...** (`Ctrl`+`Alt`+`S` for short). -2. Select **Plugins** and then **Marketplace** on top of the window. +1. At the right top corner click the gear button and from the dropdown list select the **Plugins** option + +![Select plugins from the dropdown](../images/intellij/install_in_intellij_plugins.png) + +2. Select the **Marketplace** tab on top of the window + +![Select marketplace tab](../images/intellij/install_in_intellij_marketplace.png) + 3. Type **Zowe Explorer** and click **Install**. -4. Wait until the plug-in is installed, then click **OK**. -Contact your RACF administrator so that your user is in the IZUUSER RACF group. +![Search for the plugin and install](../images/intellij/install_in_intellij_search_and_install.png) + +4. Wait until the plug-in is installed, then click **Restart IDE**. IntelliJ IDEA will ask you if you want to restart the IDE to applly all the changes in plugins. Select **Restart**, wait until the IDE is restarted + +![Restart the IDE](../images/intellij/install_in_intellij_restart.png) + +After the IDE is restarted, the plug-in's icon will appear at the right top corner. It means that you are ready to work with it. + +![After installed](../images/intellij/install_in_intellij_after_install.png) + +:::note +Sometimes the plug-in's icon appear at some different place, other than the right top corner. To fix it, right-click on the icon, in the **Move To** dropdown select the **Right Top** option. + +![Change the corner](../images/intellij/install_in_intellij_corner_change.png) + +::: + +## Downloading binaries + +:::warning ALWAYS DOUBLE-CHECK THE BINARIES YOU ARE TRYING TO INSTALL! +We are responsible for the genuine software provided by the zowe community only. If you have any questions regarding the installation or the usage of the plug-in, feel free to contact any person directly related to Zowe +::: + +There are three ways of downloading binaries of the Zowe Explorer plug-in for IntelliJ IDEA: +1. [JetBrains Marketplace page](https://plugins.jetbrains.com/plugin/18688-zowe-explorer) +2. [GitHub Releases](https://github.com/zowe/zowe-explorer-intellij/releases) of our repository +3. [GitHub Actions](https://github.com/zowe/zowe-explorer-intellij/actions) of our repository + +### Downloading binaries from JetBrains Marketplace page + +1. Proceed to the [JetBrains Marketplace page](https://plugins.jetbrains.com/plugin/18688-zowe-explorer) of the plug-in +2. Click **Get** button or select the **Versions** tab + +![Get IntelliJ plug-in](../images/intellij/get_plugin.png) + +3. Select the compatibility option and the channel of the distribution: + - **Stable** - the stable versions of the plug-in + - **EAP** - the *Early Access Program* versions of the plug-in, sometimes are provided for the EAP versions of the IntelliJ IDEA + - **Preview** - the next versions of the plug-in, that contain the bleeding-edge features of the plug-in, which may be unstable + +![Select compatibility and channel](../images/intellij/select_compatibility_and_channel.png) + +4. Select the version of the plug-in you want to download, click **Download** button against it + +![Download plug-in from JetBrains Marketplace](../images/intellij/download_plugin_marketplace.png) + +### Downloading binaries from GitHub Releases + +1. Proceed to the [GitHub Releases](https://github.com/zowe/zowe-explorer-intellij/releases) of the repository +2. Select the release version you want to install and click on the .zip file to download the binary + +:::note +Prefer the "*-signed.zip" over the regular one +::: + +![Download plug-in from GitHub Releases](../images/intellij/download_plugin_releases.png) + +### Downloading binaries from GitHub Actions + +:::note +You need to be logged into a GitHub account to be able to download artifacts +::: + +1. Proceed to the [GitHub Actions](https://github.com/zowe/zowe-explorer-intellij/actions) of the repository +2. Select a build workflow + +![Select a build workflow actions](../images/intellij/actions_select_workflow.png) + +3. Select the build of a branch you want to download + +![Select the build of a branch actions](../images/intellij/actions_select_build.png) + +4. At the bottom of the page, in the *Artifacts* section, select the .zip file with the version build to download + +![Download the build actions](../images/intellij/actions_download_artifact.png) + +## Installing binaries + +After the .zip is downloaded, do the next steps: +1. At the right top corner click the gear button and from the dropdown list select the **Plugins** option + +![Select plugins from the dropdown](../images/intellij/install_in_intellij_plugins.png) + +2. Near the **Installed** tab, click the gear button, from the dropdown select the **Install Plugin from Disk** option + +![Install from disk](../images/intellij/install_from_bin_from_disk.png) + +3. In the **Choose Plugin File** dialog window, search for the .zip you want to install. Select it and click **OK** button + +![Search for .zip](../images/intellij/install_from_bin_search_for_zip.png) + +4. The plug-in will appear in the **Installed** tab, click the **Restart IDE** button, and then the **Restart** button in the dialog window. + +![Restart after install from .zip](../images/intellij/install_from_bin_restart.png) + +After the IDE is restarted, the plug-in's icon will appear at the right top corner. It means that you are ready to work with it. + +![After installed](../images/intellij/install_in_intellij_after_install.png) + +:::note +Sometimes the plug-in's icon appear at some different place, other than the right top corner. To fix it, right-click on the icon, in the **Move To** dropdown select the **Right Top** option. + +![Change the corner](../images/intellij/install_in_intellij_corner_change.png) -![Intall IntelliJ](../images/intellij/intellij-install.gif) +::: diff --git a/docs/user-guide/intellij-jes-explorer.md b/docs/user-guide/intellij-jes-explorer.md new file mode 100644 index 0000000000..b0600b5964 --- /dev/null +++ b/docs/user-guide/intellij-jes-explorer.md @@ -0,0 +1,143 @@ +# Working with JES Explorer + +Using the plug-in, you will be able to: +- view a status of a job, view full log of a job run +- view and edit job's JCL, submit a JCL right after they are edited +- purge a job +- sort jobs + +After you set up a [JES Working Set](./intellij-working-sets.md#jes-working-set) and create a job filter to display jobs, you are all set up to work with JES Explorer. + +## Creating a jobs filter + +To see and manipulate JES jobs, you need to specify a jobs filter to search for jobs. + +To create a jobs filter: +1. Proceed to the **JES Explorer**, right click on a **JES Working Set**, select **New > Jobs Filter** + +![Create a job filter](../images/intellij/jes_purge_job_create_filter.png) + +2. Specify the parameters in the **Create Jobs Filter** dialog: + - **Prefix (1)** - the prefix for a jobs search. Can be specified as a wildcard + - **Owner (2)** - the owner for a jobs search. Can be specified as a wildcard + - **Job ID (3)** - the exact job ID for a job search + +:::note +You can specify either **prefix + owner** or a **job ID** only. A mix of the parameters is not allowed. +::: + +After the parameters are specified, click **OK** + +![Specify parameters for a job filter](../images/intellij/jes_purge_job_filter_dialog.png) + +Now, you are ready to proceed to work with JES jobs. + +## Viewing a job status + +The job status is displayed depending on the actual status of the job with the respective colouring. + +To view a job status: +1. Proceed to the **JES Explorer**, reveal a **JES Working Set** and a **Jobs Filter**. There are different statuses depending on the state of a job: + - ENDED AT: \. RC = CC 0000 - the job is ended successfully, displaying the actual date and time of the job finish + - ENDED AT: \. RC = \ - the job is ended with an error or a warning, displaying the actual date and time of the job finish + - STARTED AT: \ - the job is started but is in progress and not yet completed, displaying the actual date and time of the job start + - PENDING INPUT / QUEUED - the job is not started yet as it is waiting in the queue until the same job already started is finished + +![See job status in JES Explorer](../images/intellij/jes_status.png) + +## Viewing job spool files and job's run logs + +All the spool files available for the jobs could be viewed in the plug-in. + +To view the job spool files: +1. At the **JES Explorer** tab, reveal a JES Working Set and a jobs filter + +![Find a job](../images/intellij/jes_spool_view.png) + +2. Double click on the job or click **>** on the left of it. You will see all the spool files, available for the job + +:::note +If the job is still in progress, it is possible that not all the spool files are available yet. Just wait until the job is finished and refresh the view by right clicking and selecting **Refresh**. +::: + +![Reveal spool files](../images/intellij/jes_spool_view_reveal.png) + +3. Double click on any of the spool files to see the content of it. The lines will be displayed in the editor in a reader mode + +![Spool file in editor](../images/intellij/jes_spool_view_editor.png) + +To view all the spool files merged in one log: +1. Right click on the job in **JES Explorer**, select **View Job** + +![View merged spool files](../images/intellij/jes_spool_console.png) + +2. The merged spool files log will be displayed in the **Zowe Jobs** console view. There are two buttons to manipulate the job in there: + - **Go To Job (1)** - reveals the job in **JES Explorer**. If the job is not yet visible in the JES Explorer, the plug-in provides a dialog to create a filter for the exact job to present + - **Purge Job (2)** - removes the job from JES + +:::note +If the job is completed successfully, the plug-in can hide the successful steps. To show them, right click on the job in the console view and select **Show Successful Steps** and it will show all the spool files of the job as steps. +::: + +![Merged spool files in console](../images/intellij/jes_spool_console_shown.png) + +## View and edit job's JCL code + +The plug-in provides the possibility to view and edit a JCL code of the job in the JES Explorer. The JCL will appear in the IDE's editor. You could change the JCL and submit the job with a new code. + +To view and edit the JCL code of a JES job: +1. Right click on the job in **JES Explorer**, select **Edit JCL** + +![Select edit jcl](../images/intellij/jes_jcl_edit.png) + +2. After the JCL content is fetched, it will be displayed in the IDE's editor. You can change the JCL as much as you want. Also, the editor allows to submit the JCL again. Click the **Submit Job** button + +![Click submit button](../images/intellij/jes_jcl_edit_run_button.png) + +3. When the job is submitted, the console of the job's execution will appear, providing the actual information about the job run + +![Console with the job run](../images/intellij/jes_jcl_edit_console.png) + +4. Also, it is possible to see the status of the job being run. On the appropriate **Job Filter** in the **JES Explorer**, right click and select **Refresh** + +![Refresh job filter after edit and run](../images/intellij/jes_jcl_edit_refresh.png) + +5. After refresh is completed, a new list with jobs will be displayed with the submitted job and its respective status + +![After job filter refreshed](../images/intellij/jes_jcl_edit_after_refresh.png) + +## Purge a job + +To purge a job from a JES: +1. Specify a **Jobs Filter**. After the jobs are fetched, right click on a job to purge, select **Purge** (or press **Delete** button when the job is selected) + +![Click Purge](../images/intellij/jes_purge_click_purge.png) + +2. When the job is being purged, a "purge" dialog will appear until the job is purged + +![Purge dialog](../images/intellij/jes_purge_dialog.png) + +3. After the job is purged, a notification about the job is purged will appear and the **Jobs Filter** will be refreshed + +![Notification about the job purge](../images/intellij/jes_purge_success_notification.png) + +## Sort jobs + +For the improved user experience, there is a feature of the plug-in to sort jobs for a specified jobs filter. + +To sort jobs: +1. Proceed to the **JES Explorer**, reveal a **Jobs Filter**, right click on it, select **Sort**. There are will be options: + - **Job Name (1)** - to sort jobs by their names + - **Job Creation Date (2)** - to sort jobs by their creation date and time. Jobs are sorted by this option by default + - **Job Completion Date (3)** - to sort jobs by their completion date and time + - **Job Status (4)** - to sort jobs by their status. It means that the return code will be analyzed by the status, displayed in the JES Explorer + - **Job Owner (5)** - to sort jobs by their owners + - **Job ID (6)** - to sort jobs by their IDs + +Also, there is a possibility to change the order for the items to be displayed: **Ascending (7)** (by default) or **Descending (8)**. For the example purposes, select **Job Name** + +![Select job name when sorting](../images/intellij/jes_sort.png) + +2. The list will be refreshed with the new sort order + +![Sorted jobs by job name](../images/intellij/jes_sort_sorted.png) diff --git a/docs/user-guide/intellij-settings.md b/docs/user-guide/intellij-settings.md new file mode 100644 index 0000000000..0993f2f481 --- /dev/null +++ b/docs/user-guide/intellij-settings.md @@ -0,0 +1,41 @@ +# Working with plug-in's settings + +Before you start to use the plug-in, there are some settings that will help you to customize the way you are working with it. To open the plug-in's settings: +1. Open the **Zowe Explorer** tab **(1)**, click the **Settings** button **(2)**. The action will open all the configurations of the plug-in + +![Open plug-in's settings](../images/intellij/plugin_open_settings.png) + +2. After the window of the configuration appears, there are some tabs: +- **Connections (1)** - to manage the connections to z/OS you have. From there, you can add a new connection and delete or edit the old one +- **JES Working Sets (2)** - to manage the JES Working Sets +- **Working Sets (3)** - to manage the Files Working Sets +- **TSO Sessions (4)** - to manage TSO Sessions +- **Settings (5)** - the actual customization options of the plug-in + +Click the **Settings** tab to proceed to the customization options + +![In the settings](../images/intellij/plugin_all_configurations.png) + +3. At the **Settings** tab, there are two available customization options: +- **Batch amount to show per fetch (1)** - the amount of data sets to show under a mask. The option is editable and accepts integer numbers +- **Enable auto-sync with mainframe (2)** - the option to save content of the edited data sets and USS files automatically if selected + +![Other settings](../images/intellij/plugin_other_settings.png) + +## Batch amount to show per fetch + +There could be a huge amount of data sets / files under a specified mask. Sometimes the loading of their list could take a lot of time. To eliminate this problem, the plug-in provides the ability to control the amount of items loading at one time. The option is called **Batch amount to show per fetch**. By default, it is set to **100** entries. It means that when the request to display entities under a mask contains more than the specified number, it will show the first "x" entities with the button to load more of them. You can load the next amount by double-clicking on the **load more** at the bottom of the list. + +![Batch size option](../images/intellij/batch_size.gif) + +## Enable auto-sync with mainframe + +It is possible to synchronize the file or data set you are editing either manually or automatically. The method of synchronizing is controlled by the **Enable auto-sync with mainframe** option. When it is marked, you don't need to manually synchronize the file / data set whilst editing it, the plug-in decides by itself, when to synchronize it. In case you want to be sure that you control the process of synchronizing the content with a mainframe, or in case you have some limitations for calls to z/OSMF REST API, or for some other reason, you can disable this option and continue with manual synchronization. The synchronization process starts either by the button in the editor (![Sync button](../images/intellij/plugin_sync_button.png)), appearing if there are any changes in the file, or by pressing simultaneously **Ctrl + Shift + S (Cmd + Shift + S for MacOS)**. + +If the manual synchronization is turned on, and you try to close the file in the editor, the plug-in will ask what to do with the content. Clicking **Yes** will synchronize the content, **No** will delete the local changes: + +![Yes or No before close](../images/intellij/plugin_save_before_close.png) + +Here's how auto-synchronization works: + +![Auto-sync option](../images/intellij/sync_option.gif) diff --git a/docs/user-guide/intellij-tso-cli.md b/docs/user-guide/intellij-tso-cli.md new file mode 100644 index 0000000000..f8ee9ee980 --- /dev/null +++ b/docs/user-guide/intellij-tso-cli.md @@ -0,0 +1,49 @@ +# Working with TSO console + +The plug-in provides a functionality to work with TSO in a console way directly from the IntelliJ IDEA. With this feature it is possible to enter commands and see their results, open multiple sessions to different z/OS instances, as well as the same z/OS instance, issue a PA1 command to the console in case the attention functionality is needed to be triggered. + +To start working with TSO console, you need to set up a [Connection](./intellij-configure.md#creating-zosmf-connection). After that, the **TSO Sessions** functionality will be allowed to work with. + +## Creating a TSO Session + +To create a TSO Session: +1. Open settings with the wrench button + +![Open settings with wrench button](../images/intellij/tso_sessions_wrench.png) + +2. Go to **TSO Sessions** tab + +![Go to TSO Sessions](../images/intellij/tso_sessions_go_to_sessions.png) + +3. At the **TSO Sessions** tab, click on the **+** button + +![Click add TSO Session](../images/intellij/tso_sessions_add.png) + +4. The **Add TSO Session** dialog will appear. You need to specify a name of the TSO Session in order to be able to create it. Also, you can select a connection to be used together with the session parameters. To setup such things as reconnection timeout and reconnection attempts count, use the **Advanced Parameters** section. Also, you can reset the defaults of the parameters by clicking **Reset Default Values** button. After all the parameters are set up, click **OK** button + +![Fill in parameters, click OK](../images/intellij/tso_sessions_add_dialog.png) + +5. After the actions are done, a new **TSO Session** will be added to the list. Click **Apply** and then **OK** buttons to save the new session + +![TSO Session created](../images/intellij/tso_sessions_created.png) + +## Creating a TSO Console + +After a [**TSO Session**](./intellij-tso-cli.md#creating-a-tso-session) is created, it is possible to create a **TSO Console**. + +To create a **TSO Console**: +1. Click **+** button, select **Zowe TSO Console** + +![Creating TSO Console](../images/intellij/tso_console_create.png) + +2. The **Select TSO Session** dialog will appear. Select the appropriate **TSO Session** to use during a TSO console run, click **OK** button + +![Select TSO Session dialog](../images/intellij/tso_console_dialog.png) + +3. When the **TSO Session** is selected, the **TSO Console** will appear. In there you could see the actual information about the session being used, the welcoming message and the prompt, where it is possible to enter TSO commands. Also there are 2 buttons to manipulate the behavior of the console: + - **Reopen Session (1)** - will reopen the current TSO Console session with the same parameters + - **Cancel Command (PA1) (2)** - will send the **PA1** command to the TSO console in order to issue a cancellation of the previous command (it is blocked when there is nothing to cancel) + +![TSO Console appeared](../images/intellij/tso_console_created_console.png) + +From this point, you are ready to use the **TSO Console** diff --git a/docs/user-guide/intellij-use-cases.md b/docs/user-guide/intellij-use-cases.md new file mode 100644 index 0000000000..979f31c928 --- /dev/null +++ b/docs/user-guide/intellij-use-cases.md @@ -0,0 +1,16 @@ +# Use cases + +## What can I do using the plug-in? + +The plug-in provides the ability to work with a mainframe through z/OSMF REST API. It has such functionalities as: +- Working with [z/OS data sets](./intellij-zos-files.md) and [USS Files](./intellij-uss-files.md): you can create new entities, [copy and move](./intellij-copy-cut.md) them, delete, edit right in the IDE, check and change properties +- Working with [JES jobs](./intellij-jes-explorer.md): you can submit a job, see an output of any job, edit and run JCL right through the JES Explorer, see and change the status of a job +- Working with [TSO](./intellij-tso-cli.md): you can submit any TSO command through the plug-in's TSO Command Line Interface in a console way, see the output of TSO commands + +## Who is the plugin intended for? + +The plug-in is suitable for your needs if you meet one or more of the criteria: +- You are a **System Programmer** and use **COBOL** / **JCL** / **PLI/I**: with the plug-in, you can easily change the source code, situated on a mainframe, right in the IDE's editor, without the risk of exposing your data anywhere, as all the content is stored under and displayed from the secure IntelliJ's storage. With a bunch of available plug-ins, it will provide the most of opportunities to work with your programs, written on mainframe-specific languages +- You are a **System Administrator** / **System Operator**: the plug-in's **TSO CLI** provides the way of interacting with a mainframe the same as the other tools do, extending the User Experience to the highest possible peak +- You are a **QA** / **Test Automation** person: it gives as much possibilities to check the actual content of a mainframe as the most modern technologies do, reducing latencies in any interaction with the components of the system +- You are a **Java** / **Kotlin** / **Scala** developer: IntelliJ IDEA provides native support for **JVM languages**, so it is more suitable for these technologies to develop for a mainframe diff --git a/docs/user-guide/intellij-using.md b/docs/user-guide/intellij-using.md deleted file mode 100644 index 04bed44067..0000000000 --- a/docs/user-guide/intellij-using.md +++ /dev/null @@ -1,179 +0,0 @@ -# Using Zowe IntelliJ plug-in - -Learn how to work with the Zowe IntelliJ plug-in, including working with datasets, USS files, and jobs. - -## Settings - -Before you start to use the plug-in, there are some settings available. First one - synchronization option. - -### Auto-sync option - -It is possible to synchronize the file or dataset you are editing either manually or automatically. The method is controlled by **Enable auto-sync with mainframe** option. When it is checked, you don't need to manually synchronize the file/dataset whilst you are editing it, the IntelliJ platform decides by itself, when and how to synchronize it. The plug-in is using this feature and allows users to avoid additional sync action. In case you want to be sure that you control the process of syncing with the mainframe, or in case you have some limitations for calls to z/OSMF, or for some other reason, you can disable this option and continue with manual synchronization either by button, appearing if there are any changes in the file, or by pressing simultaneously **Ctrl + Shift + S (Cmd + Shift + S for MacOS)**. - -![Auto-sync option](../images/intellij/sync_option.gif) - -### Batch size option - -Mainframe z/OS and USS filesystems could have a lot of datasets/files under a specified mask. Sometimes the loading of datasets/files list could take a lot of time if there are a lot of entries. To eliminate this problem, the plug-in provides the ability to control the amount of items loading at one time. It is called **Batch amount to show per fetch** in **Settings**. By default, it is set to **100** entries. When the list contains more than the specified number, you can load next amount of entries, specified in this option, double-clicking by **load more** item in the **File Explorer** view. - -![Batch size option](../images/intellij/batch_size.gif) - -## Working with Files Working Sets - -To work with z/OS datasets or USS files, you need to [set up a Files Working Set](intellij-working-sets.md#files-working-set). The most of the functions are available under context menu in Files Working Set view. - -Using the plug-in, you will be able to: -- create, rename, view, edit, delete PS, PDS, PDS/e datasets, as well as PDS and PDS/e members -- use feature **Allocate Like** to create a dataset with parameters of another dataset -- use feature **Migrate** for datasets -- submit JCL jobs with **Submit Job** -- create, rename, view, edit, delete USS files and folders -- copy, move z/OS datasets and USS files, both inside the filesystem, and between them, as well as between systems with different IP address - -### Working with z/OS PS datasets - -![Work with PS datasets](../images/intellij/create_edit_rename_delete_ps.gif) - -### Working with z/OS PDS datasets - -![Work with PDS datasets](../images/intellij/pds_create_and_props.gif) - -### "Allocate Like" feature - -To issue the **Allocate Like**, click the right mouse button on any of datasets and select **Allocate Like**. - -!["Allocate Like" feature](../images/intellij/allocate_like.gif) - -### "Submit Job" feature - -To issue the **Submit Job**, click the right mouse button on any of PS datasets or PDS members and select **Submit Job**. - -!["Submit Job" feature](../images/intellij/submit_jcl.gif) - -### Working with USS files - -There is a possibility to work with USS filesystem using the plug-in. Plug-in allows users to create files with a specific set of access rules, edit the file, rename, delete them, copy and move. With the existing ones, it is also possible to change the rules. Also the plug-in allows to change encoding of the file to a desired one, so the content of the file is shown correctly. - -About the encoding: there is two different options for encoding change. One is **Reload** option, which allows users to reload the file with the specified encoding. It means that the file won't be converted to that encoding, and the plug-in just opens it with the specified one. The second option is **Convert**. This option converts the file to the specified encoding, changing it contents. It means that the plug-in will try to change the file bytes if it is possible, and then will display the contents with the changed bytes. - -![Work with USS files](../images/intellij/work_with_uss.gif) - -### Copy/move functionality - -There are some options to copy and move z/OS datasets and members, and USS files. - -**Important note**: the contents of the source files and datasets will stay the same, until you try to copy/move a file from USS to a z/OS partitioned dataset. If the file contents are longer than the specified for the PDS logical record length, then firstly the content will be cut to the specified LRECL, and the rest is going to be on the next lines. - -It is possible to move and copy files and datasets either through keyboard shortcut buttons and context menu, or using drag and drop. - -To move a member from one dataset to another: -1. Right click on the member to be moved -2. Select **Cut** -3. On the target dataset click **Paste** -4. ...or just drag and drop it - -![Move member from one PDS to another](../images/intellij/move_mem_to_ds.gif) - -If a sequential dataset is being moved to PDS, the name will be trimmed to the last element in the HLQ. - -To move a sequential dataset to a partitioned dataset: -1. Right click on the PS to be moved -2. Select **Cut** -3. On the target dataset click **Paste** -4. ...or just drag and drop it - -To copy member from one dataset to another: -1. Right click on the member to be copied -2. Select **Copy** -3. On the target dataset click **Paste** - -![Move PS to PDS and copy member from one PDS to another](../images/intellij/pds_copy_move_ds.gif) - -To move USS file or folder to another USS folder: -1. Right click on the folder or the file to be moved; -2. Select **Cut** -3. On the target folder click **Paste** -4. ...or just drag and drop it - -![Move USS file or folder to another USS folder](../images/intellij/move_uss_folder_to_uss_folder.gif) - -To copy PDS member to USS filesystem: -1. Right click on the member to be copied -2. Select **Copy** -3. On the target folder or the USS filesystem mask click **Paste** - -![Copy member to USS](../images/intellij/copy_mem_to_uss.gif) - -While moving or copying a partitioned dataset to the USS filesystem, it will be converted to a USS folder. All the contents will become USS files. - -To move a PDS to USS filesystem: -1. Right click on the PDS to be copied -2. Select **Cut** -3. On the target folder or the USS filesystem mask click **Paste** -4. ...or just drag and drop it - -![Move PDS to USS](../images/intellij/pds_move_zos_to_uss.gif) - -Also, it is possible to copy/move USS file to PDS dataset. The file will become the PDS member. - -**Be aware**: the file name being copied/moved should be no more than 8 symbols. Also, see [the limitations and rules](#copymove-functionality) for the file being copied - -To move USS file to a PDS: -1. Right click on the file to be copied -2. Select **Cut** -3. On the target PDS click **Paste** -4. ...or just drag and drop it - -![Copy member to USS and USS file to PDS](../images/intellij/move_uss_to_pds.gif) - -### Cross-system copy - -The plug-in makes it possible to move and copy z/OS datasets and USS files between different system. E.g.: a user has two systems, the first - z/OS 2.3, the second - z/OS 2.4. So, it is possible to copy or move files and datasets either from z/OS 2.3 to z/OS 2.4, or vice versa. The rules of copying and moving that are described previously, are also applicable to such kind of action. - -To copy/move element from one system to another: -1. Right click on the element to be copied/moved -2. Select **Copy**/**Cut** -3. On the target system's element click **Paste** - -*(Use drag and drop to move elements faster)* - -![Cross-system operations](../images/intellij/cross_system_copy.gif) - -## Working with JES Working Sets - -To operate with your JCL jobs, ensure you [create a JES Working Set](intellij-working-sets.md#jes-working-set) first, which will hold all the filters for the JES Explorer. - -With the plug-in it is possible to view a status of jobs, view full log of a job run, view and edit jobs' JCLs, submit them right after they are edited, purge them. - -To edit JCL of a job and run it just after it is edited: -1. Right click on a job -2. Select **Edit JCL**, the JCL will appear in the editor -3. Change the JCL as you want -4. Click green button **Submit Job** in the edittor - -After the job is started, a console view will appear. In the console view it is possible to see the full execution log of the job. - -To view the execution log of the job again: -1. Right click on the job -2. Select **View Job** - -Also, it is possible to control the job execution through the console view. - -If you don't need the job anymore: -1. Right click on the job -2. Select **Purge Job** *(**Delete** is the keyboard shortcut)* - -![Working with jobs](../images/intellij/work_with_jes_jobs.gif) - -## TSO Command Line Interface - -Starting from the v1.0.0 of the plug-in, there is a feature to send TSO commands directly from the IntelliJ Platform IDE. - -To start using the TSO Command Line Interface: -1. Click **+** in the Zowe Explorer view -2. Select **TSO Console** -3. In the dialog appeared, type in all the necessary parameters *(the default ones are most likely to fit)*, click **OK** - -After that, the TSO Command Line Interface should appear. You can type in TSO commands, as well as run any possible scripts. - -![TSO CLI](../images/intellij/tso_cli.gif) diff --git a/docs/user-guide/intellij-uss-files.md b/docs/user-guide/intellij-uss-files.md new file mode 100644 index 0000000000..d992dff100 --- /dev/null +++ b/docs/user-guide/intellij-uss-files.md @@ -0,0 +1,89 @@ +# Working with USS Files + +Using the plug-in, you will be able to: +- create, rename, view, edit, delete USS files and folders +- submit JCL jobs with **Submit Job** option +- change the encoding a USS file content is displayed or saved in +- manipulate USS files and folders rights +- copy, move USS files and folders, both inside the filesystem, and between them, as well as between systems with different IP address +- sort USS paths + +After you set up a [Files Working Set](./intellij-working-sets.md#files-working-set) and create a mask to display USS paths, it is possible to manipulate USS files and folders. + +## Basic operations + +The plug-in allows users to work with USS part of a mainframe. As the basic operations, you can create files with a specific set of permits, edit files, rename and delete them. Also, you can submit a job from a USS file if it is a JCL. + +![Work with USS files](../images/intellij/work_with_uss.gif) + +## Working with permissions + +The plug-in allows users to edit permissions of the USS files and folders: +1. Right-click on the file in USS explorer, click **Properties** + +![Click USS properties](../images/intellij/uss_click_properties.png) + +2. In the **File Properties** dialog window, select the **Permissions** tab + +![USS Permissions tab](../images/intellij/uss_properties_possible_changes.png) + +3. In there, you will have three options to change when needed: **Owner permissions (1)**, **Group permissions (2)** and **Permissions for all users (3)**. To change any of the options, click one of them + +![USS permissions open drop-down](../images/intellij/uss_properties_change_owner_perms.png) + +4. From the drop-down list, select a new value + +![USS permissions select from drop-down](../images/intellij/uss_properties_change_owner_perms_select.png) + +5. Click the **OK** button for the changes to be applied + +![USS permissions click OK](../images/intellij/uss_properties_change_owner_perms_ok.png) + +## Working with files encoding + +Sometimes it is necessary to display file content in a specific encoding or save it in some different encoding. To do so: +1. Double-click the USS file to open it in the editor + +![Open USS file in editor](../images/intellij/intellij_open_uss_file.png) + +2. In the **File Properties** dialog window, you should be at the **General** tab. Click the **File encoding** button for the drop-down list to appear + +![USS General tab, click file encoding](../images/intellij/uss_props_general_tab.png) + +3. Select the encoding you want the file content to be in + +![USS select new encoding](../images/intellij/uss_encoding_select_option.png) + +4. After the actions, the encoding change dialog will appear. It will ask you to choose between the 2 options: + - **Reload (1)** - changes the file tag, specifying the encoding to show the file in. This action does not actually rewrite the contents of the file and just changes the way it is displayed in the editor + - **Convert (2)** - tries to convert the file to the specified encoding, actually changing the content of the file. This option will also change the file tag, and after that it will try to modify the content, changing the file bytes to the respective ones to try to display the same content with the actually different bytes + +![USS encoding change dialog](../images/intellij/uss_encoding_dialog.png) + +5. Click the option you want to perform on the file. Sometimes it is not possible to correctly reload or convert the file content to the encoding you select. In this case, the *Warning* icon will appear in the button of an action that is not possible to perform correctly. You will be still able to perform the operation, but the additional warning dialog will appear, describing the issue + +:::warning make sure you know what you are doing +The contents after clicking **Reload anyway** or **Convert anyway** could be unpredictable. Do it only in the cases where you are sure nothing will go wrong. +::: + +![USS encoding warning dialog](../images/intellij/uss_encoding_warning_dialog.png) + +After the operation is finished, the content of the file will be reloaded. If you had some characters that were not visible in the default encoding, and you selected the correct encoding, the content will be displayed regarding the option you've selected. + +## Sort a USS path + +There is a functionality of the plug-in to sort USS files and folders. The plug-in allows to sort not only the root path, but any USS path you have in your working tree. + +To sort USS files and folders list: +1. Right click on a USS path, select **Sort**. The list of sorting options will appear: + - **File Name (1)** - to sort USS entities by name + - **File Type (2)** - to sort USS entities by type + - **File Modification Date (3)** - to sort USS entities by modification date. USS path is sorted by this option by default + +Also, there is a possibility to change the order for the items to be displayed: **Ascending (4)** (by default) or **Descending (5)**. For the example purposes, select **File Name** + +![Sort USS files](../images/intellij/uss_sort.png) + +2. The list will be refreshed with the new sort order + +![Sort USS files result](../images/intellij/uss_sort_result.png) diff --git a/docs/user-guide/intellij-working-sets.md b/docs/user-guide/intellij-working-sets.md index bdaf903860..fa7ea088a7 100644 --- a/docs/user-guide/intellij-working-sets.md +++ b/docs/user-guide/intellij-working-sets.md @@ -1,39 +1,44 @@ -# Working Sets Concept +# Working with plug-in's Working Sets -We use term "Working Sets" to describe the place to store sets of masks and filters. These items are stored separately for each working set. The working set is more like "profile" and is used to logically aggregate sets for each separate need (both for users and to separate the different items to categories, in case it is needed). +## The concept + +We use term "Working Sets" to describe the place to store sets of masks and filters. These items are stored separately for each working set. The working set is more like a "profile" *(don't confuse with the "Zowe Profile")* and is used to logically aggregate sets for different separate needs (both for users' convenience and to separate the different items to categories, in case it is needed). There are two types of working sets: -- **Files Working Sets** - are used to store z/OS and USS masks -- **JES Working Sets** - are used to store JCL Job filters +- **Files Working Sets** - are to store z/OS and USS masks +- **JES Working Sets** - are to store JES Job filters + +You can create working sets either through **Settings** or by clicking **+** button and selecting **Working Set** / **JES Working Set** from a dropdown in the plug-in's tab. -You can create working sets either through **Settings** or by clicking on **+** button. -*Note: you can create a working set only when a connection is set up.* +:::note +You can create a working set only when a connection is set up. +::: ## Files Working Set -This type of working sets is used to store z/OS and USS masks. **Masks** are similar to filters, they are used to show z/OS datasets and USS files under a specified path. +This type of working sets is used to store z/OS and USS masks. **Masks** are similar to filters, they are used to show z/OS data sets and USS files under a specified path. To create Files working set: 1. Press **+** button 2. Select **Working Set** -3. Type in the Working Set name (it should be unique) and select an appropriate connection -4. Add some masks +3. Type the Working Set's name in the **Working Set Name** field (it should be unique) and select the connection under which to create the Working Set +4. Add some masks to the newly created Working Set. It can be both z/OS data set masks or USS Files masks 5. Click **OK** ![Configure IntelliJ files working set](../images/intellij/create_files_working_set.gif) ## JES Working Set -This type of working sets is used to operate with your JCL jobs, see their logs, view and edit JCL with further job run. It will hold all the filters for the JES Explorer. +This type of Working Sets is used to operate with your JES Jobs, see their logs, view and edit JCL and later run it. It holds all the filters for the JES Explorer. -To create JES working set: +To create JES Working Set: -1. Select **JES Explorer** tab +1. Select the **JES Explorer** tab 2. Press **+** button 3. Select **JES Working Set** -4. Type in the Working Set name (it should be unique) and select an appropriate connection -5. Add some JCL filters +4. Type the Working Set's name in the **Working Set Name** field (it should be unique) and select the connection under which to create the Working Set +5. Add some **JCL filters** 6. Click **OK** ![Configure IntelliJ JES working set](../images/intellij/create_jes_working_set.gif) diff --git a/docs/user-guide/intellij-zos-files.md b/docs/user-guide/intellij-zos-files.md new file mode 100644 index 0000000000..021fe52125 --- /dev/null +++ b/docs/user-guide/intellij-zos-files.md @@ -0,0 +1,86 @@ +# Working with z/OS data sets + +Using the plug-in, it is possible to: +- create, rename, view, edit, delete PS, PDS, PDS/e data sets, as well as PDS and PDS/e members +- use the feature **Allocate Like** to create a data set with parameters of the other data set +- use the feature **Migrate** and **Recall** for archived data sets +- submit JCL jobs with **Submit Job** option +- copy, move z/OS data sets, both inside the filesystem, and between them, as well as between systems with different IP address +- sort data sets + +After you set up a [Files Working Set](./intellij-working-sets.md#files-working-set) and create a mask to display data sets on the z/OS part, it is possible to manipulate PS, PDS and PDS/E data sets + +## Allocating a data set + +To allocate a data set: +1. Right-click on any entity, related to z/OS data sets (it could be **Files Working Set**, **z/OS data sets mask**, any **other data set or member**) +2. Select **New** -> **Dataset** + +![New -> Dataset](../images/intellij/plugin_create_dataset.png) + +3. Specify the necessary fields. There are some custom options to help with specifying the data set parameters: + - **Choose preset (1)** - the option provides the most commonly used data set presets both for PS and PDS options. Selecting on of the presets will automatically setup all the necessary fields to create the selected type of a data set (the presets are described more later) + - **Dataset name (2)** - the name of the data set to be created. It automatically provides the template of the data set name with the user's HLQ as the starting string and **.\** string that is intended to be changed by the user + - **Dataset organization (3)** - the data set organization to be used. The options are: **PS (Physical Sequential)**, **PO (Partitioned Organization)** and **PO-E (Partitioned Organization - Extended)** + - **Allocation unit hint (4)** - a small UI improvement hint for better understanding the allocation units and their relative values to each other + +All the other parameters are the same as the z/OS provides to allocate a new data set. In the **Advanced Parameters** section, there are some additional fields to setup if your prefer to set yourself such things as **Volume**, **Device Type**, **Storage class**, etc. + +![Create data set dialog](../images/intellij/plugin_create_dataset_fields.png) + +If you want to choose a preset, there are 5 options available for now: + - **Custom Dataset (1)** - all the fields are set by the user + - **Sequential Dataset (2)** - the fields are set to allocate a template PS data set + - **PDS Dataset (3)** - the fields are set to allocate a template PDS data set + - **PDS with empty member Dataset (4)** - the fields are set to allocate a template PDS data set with an empty member inside + - **PDS with sample JCL member Dataset (5)** - the fields are set to allocate a template PDS data set with a member with a template JCL job inside + +![Data set presets](../images/intellij/plugin_dataset_presets.png) + +4. After specifying all the necessary fields, click **OK** + +![Click OK for allocating a data set](../images/intellij/plugin_create_dataset_ok.png) + +5. When the data set is allocated, the plug-in will suggest creating a mask to display the data set created under. Click **Add mask (1)** to add the mask and **Skip (2)** to skip the mask creation + +![Add mask or skip](../images/intellij/plugin_create_mask_or_skip.png) + +## Working with z/OS PS data sets + +Here you can see a possible scenario of working with PS data sets + +![Work with PS data sets](../images/intellij/create_edit_rename_delete_ps.gif) + +## Working with z/OS PDS / PDS/E data sets + +Here you can see a possible scenario of working with PDS / PDS/E data sets + +![Work with PDS data sets](../images/intellij/pds_create_and_props.gif) + +## "Allocate Like" feature + +To issue the **Allocate Like**, right-click on any of data sets and select **Allocate Like**. + +!["Allocate Like" feature](../images/intellij/allocate_like.gif) + +## "Submit Job" feature + +To issue the **Submit Job**, right-click on any of PS data sets or PDS / PDS/E members and select **Submit Job**. + +!["Submit Job" feature](../images/intellij/submit_jcl.gif) + +## Sort a data sets mask + +To sort z/OS data sets list: +1. Right click on a data sets mask, select **Sort**. The list of sorting options will appear: + - **Dataset Name (1)** - to sort by data set names + - **Dataset Type (2)** - to sort by data set types (PS / PO / PO-E) + - **Dataset Modification Date (3)** - to sort by data set modification date and time. Data sets list is sorted by this option by default + +Also, there is a possibility to change the order for the items to be displayed: **Ascending (4)** (by default) or **Descending (5)**. For the example purposes, select **Dataset Name** + +![Sort data sets by name](../images/intellij/datasets_sort.png) + +2. The list will be refreshed with the new sort order + +![Sort data sets result](../images/intellij/datasets_sort_result.png) diff --git a/docs/user-guide/k8s-config.md b/docs/user-guide/k8s-config.md index 398e0b105d..5405b93f45 100644 --- a/docs/user-guide/k8s-config.md +++ b/docs/user-guide/k8s-config.md @@ -334,8 +334,6 @@ To manually create the [ConfigMaps](https://kubernetes.io/docs/concepts/configur * `components.discovery.port` is `7553`, * `components.gateway.port` is `7554`, * `components.caching-service.port` is `7555`, - * `components.jobs-api.port` is `7600`, - * `components.files-api.port` is `7559`, * `components.app-server.port` is `7556`. * `components.caching-service.storage.mode` should NOT be set to `VSAM`. `redis` is suggested. Follow [Redis configuration](https://docs.zowe.org/stable/extend/extend-apiml/api-mediation-redis/#redis-configuration) documentation to customize other Redis related variables. Leave the value to empty for debugging purposes. * Must append and customize these 2 values into `zowe.environments` section: @@ -380,9 +378,7 @@ discovery-pdb 1 N/A 0 1d explorer-jes-pdb 1 N/A 0 1d explorer-mvs-pdb 1 N/A 0 1d explorer-uss-pdb 1 N/A 0 1d -files-api-pdb 1 N/A 0 1d gateway-pdb 1 N/A 0 1d -jobs-api-pdb 1 N/A 0 1d ``` ## `HorizontalPodAutoscaler` @@ -410,9 +406,7 @@ discovery-hpa StatefulSet/discovery 34%/70% 1 3 1 explorer-jes-hpa Deployment/explorer-jes 10%/70% 1 3 1 9m59s explorer-mvs-hpa Deployment/explorer-mvs 10%/70% 1 3 1 9m59s explorer-uss-hpa Deployment/explorer-uss 10%/70% 1 3 1 9m59s -files-api-hpa Deployment/files-api 8%/70% 1 3 1 9m59s gateway-hpa Deployment/gateway 20%/60% 1 5 1 9m59s -jobs-api-hpa Deployment/jobs-api 8%/70% 1 3 1 9m59s ``` ## Kubernetes v1.21+ diff --git a/docs/user-guide/k8s-using.md b/docs/user-guide/k8s-using.md index 4006a3f82c..1b55169a73 100644 --- a/docs/user-guide/k8s-using.md +++ b/docs/user-guide/k8s-using.md @@ -68,16 +68,16 @@ Here are a few commands you can use to monitor your environment: ## Stopping, pausing or removing Zowe containers -To temporarily stop a component, locate the `Deployment` component and scale down to `0`. For example, if you want to stop the `jobs-api` container, run this command: +To temporarily stop a component, locate the `Deployment` component and scale down to `0`. For example, if you want to stop the `api-catalog` container, run this command: ``` -kubectl scale -n zowe deployment jobs-api --replicas=0 +kubectl scale -n zowe deployment api-catalog --replicas=0 ``` You can later re-enable a component by scaling the component back to 1 or more. -If you want to permanently remove a component, you can delete the component `Deployment`. To use `jobs-api` as an example, run this command: +If you want to permanently remove a component, you can delete the component `Deployment`. To use `api-catalog` as an example, run this command: ``` -kubectl delete -n zowe deployment jobs-api +kubectl delete -n zowe deployment api-catalog ``` diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index 6f0d7cba63..db5ab2ab78 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -18,21 +18,21 @@ When Zowe is ready, the app-server can be found at `https://:/zlux/ui/v1/`, which will redirect to `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +`https://:/zlux/ui/v1/`, which redirects to `https://:/zlux/ui/v1/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html`. Although you access the App server via the Gateway port, the App server still needs a port assigned to it which is the value of the *components.app-server.port* variable in the Zowe configuration file. -(Not recommended): If the mediation layer is not used, the Desktop will be accessible from the App server directly at `/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html` +(Not recommended): If the mediation layer is not used, the Desktop is accessible from the App server directly at `/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html`. ## Accessing ZSS The `zss` server should be accessed through the `gateway` when both are present. When both are ready, ZSS can be accessed from the API Mediation Layer Gateway, such as -`https://:/zss/api/v1/` +`https://:/zss/api/v1/`. Although you access the ZSS server via the Gateway port, the ZSS server still needs a port assigned to it which is the value of the *components.zss.port* variable in the Zowe configuration file. -If the mediation layer is not used, ZSS directly at `https://:/` +If the mediation layer is not used, ZSS directly at `https://:/`. ## Configuration file @@ -117,17 +117,6 @@ When running, the App Server will access the server's settings and read or modif These directories dictate where the Configuration Dataservice will store content. For more information, see the [Configuration Dataservice documentation](../extend/extend-desktop/mvd-configdataservice.md) -### Old defaults -Prior to Zowe release 2.0.0, the location of the configuration directories were initialized to be within the `` folder unless otherwise customized. 2.0.0 does have backwards compatibility for the existence of these directories, but `` folder no longer exists, so they should be migrated to match the ones specified in the Zowe configuration file. - -| Folder | New Location | Old Location | Note -|--------|--------------|--------------|----- -| siteDir | `/app-server/site` | `/workspace/app-server/site` | -| instanceDir | `/app-server` | `/workspace/app-server` | instanceDir term isn't used anymore. workspaceDirectory is used -| groupsDir | `/app-server/groups` | `/workspace/app-server/groups` | -| usersDir | `/app-server/users` | `/workspace/app-server/users` | -| pluginsDir | `/app-server/plugins` | `/workspace/app-server/plugins` | - ## App plugin configuration @@ -191,28 +180,26 @@ If the directory or file specified cannot be created, the server will run (but i Running ZSS requires a Zowe configuration file configuration that is similar to the one used for the Zowe App Server (by structure and property names). The attributes that are needed for ZSS (*components.zss*) at minimum, are: *port*, *crossMemoryServerName*. -By default, ZSS is configured to use HTTPS with the same certificate information and port specification as the other Zowe services. If you are looking to use AT-TLS instead, then you must set *component.zss.tls* variable to false and define `component.zss.agent.http` section with port, ipAddresses, and attls: true as shown below +By default, ZSS is configured to use HTTPS with the same certificate information and port specification as the other Zowe services. If you are looking to use AT-TLS instead, then you must set either *zowe.network.server.tls.attls* or *component.zss.zowe.network.tls.attls* to true. -(Recommended) Example of the agent body: +(Recommended) Example of default ZSS with native TLS: ``` zss: enabled: true - tls: true port: 7557 crossMemoryServerName: ZWESIS_STD ``` -(Not recommended) Unsecure, HTTP example with AT-TLS: +(Not recommended) Example with AT-TLS: ``` zss: enabled: true port: 7557 crossMemoryServerName: ZWESIS_STD - tls: false - agent: - http: - ipAddresses: ["127.0.0.1"] - attls: true + zowe: + network: + tls: + attls: true ``` ### ZSS 64 or 31 bit modes @@ -223,11 +210,11 @@ Two versions of ZSS are included in Zowe, a 64 bit version and a 31 bit version. You can check which version of ZSS you are running by looking at the logs. At startup, the message ZWES1013I states which mode is being used, for example: -`ZWES1013I ZSS Server has started. Version 2.0.0 64-bit` +`ZWES1013I ZSS Server has started. Version 3.0.0 64-bit` Or -`ZWES1013I ZSS Server has started. Version 2.0.0 31-bit` +`ZWES1013I ZSS Server has started. Version 3.0.0 31-bit` #### Verifying which ZSS mode plugins support @@ -623,7 +610,7 @@ For information on endpoint URLs, see [Using dataservices with RBAC](../extend/e [Multi-factor authentication](https://www.ibm.com/support/knowledgecenter/SSNR6Z_2.0.0/com.ibm.mfa.v2r0.azfu100/azf_server.htm) is an optional feature for Zowe. -As of Zowe version 1.8.0, the Zowe App Framework, Desktop, and all apps present in the SMP/E or convenience builds support [out-of-band MFA](https://www.ibm.com/support/knowledgecenter/SSNR6Z_2.0.0/com.ibm.mfa.v2r0.azfu100/azf_oobconcepts.htm) by entering an MFA assigned token or passcode into password field of the Desktop login screen, or by accessing the app-server `/auth` REST API endpoint. +The Zowe App Framework, Desktop, and all apps present in the SMP/E or convenience builds support [out-of-band MFA](https://www.ibm.com/support/knowledgecenter/SSNR6Z_2.0.0/com.ibm.mfa.v2r0.azfu100/azf_oobconcepts.htm) by entering an MFA assigned token or passcode into password field of the Desktop login screen, or by accessing the app-server `/auth` REST API endpoint. For a list of compatible MFA products, see [Known compatible MFA products](../getting-started/zowe-security-authentication.md#multi-factor-authentication-mfa). @@ -706,11 +693,9 @@ When you **disable** cluster mode, you will lose the following benefits: ### To turn the cluster mode on -- In Zowe V1, do NOT include the `ZLUX_NO_CLUSTER` environment variable in the `instance.env` configuration. -- In Zowe V2, do NOT include the `zowe.environments.ZLUX_NO_CLUSTER `in the `zowe.yaml` file. +- Do NOT include the `zowe.environments.ZLUX_NO_CLUSTER `in the `zowe.yaml` file. ### To turn the cluster mode off -- In Zowe V1, include `ZLUX_NO_CLUSTER=1` in the `instance.env` configuration. -- In Zowe V2, include `zowe.environments.ZLUX_NO_CLUSTER=1` in the `zowe.yaml` file. +- Include `zowe.environments.ZLUX_NO_CLUSTER=1` in the `zowe.yaml` file. diff --git a/docs/user-guide/mvd-using.md b/docs/user-guide/mvd-using.md index d0c35a19a5..0fa07c67a1 100644 --- a/docs/user-guide/mvd-using.md +++ b/docs/user-guide/mvd-using.md @@ -12,10 +12,18 @@ From a supported browser, open the Zowe Desktop at `https://zowe.externalDomains Where: -- *zowe.externalDomains* is the host on which you are running the Zowe Application Server, its the - value that was assigned in the zowe configuration file. +- *zowe.externalDomains* is the host on which you are running the Zowe Application Server, its the value that was assigned in the zowe configuration file. - *zowe.externalPort* is the value of Gateway port that was assigned in the zowe configuration file. +### Alternative Desktop access + +The above URL can be modified with query parameters for the following purposes: + +| Action | Query Parameter | Example | Detail | +|--------|-----------------|---------|--------| +| Access Desktop without Gateway proxy | zwed-no-redirect=1 | `https://zowe.externalDomains[0]:components.app-server.port/?zwed-no-redirect=1` | When the APIML Gateway is running, the Desktop should be reached through it instead of going to the app-server port directly. The Desktop avoids direct access by redirecting users to the gateway URL when possible. To disable this behavior for direct access, you can use "zwed-no-redirect=1". This is intended for troubleshooting and is not recommended otherwise since some Desktop apps will not work without being accessed via the gateway URL. | +| Access the Zowe v2 Desktop | use-v2-desktop=true | `https://zowe.externalDomains[0]:zowe.externalPort/zlux/ui/v1/?use-v2-desktop=true` | Zowe V3 includes the Zowe v2 Desktop for ease of transition. By default, the V3 desktop is used but if you have an app that does not yet work on the V3 Desktop, you can use the v2 Desktop through this parameter. The v2 desktop is in maintenance mode and no longer receives enhancements. | + ### Logging in and out of the Zowe Desktop diff --git a/docs/user-guide/providing-feedback-and-contributing-client-side.md b/docs/user-guide/providing-feedback-and-contributing-client-side.md new file mode 100644 index 0000000000..b3d04c2c1a --- /dev/null +++ b/docs/user-guide/providing-feedback-and-contributing-client-side.md @@ -0,0 +1,80 @@ +# Providing feedback and contributing + +To help make Zowe client-side components better, you are welcome to contribute in different ways. + +## Zowe CLI + +### Chatting with the Zowe CLI community + +Chat with the community on [Slack](https://openmainframeproject.slack.com/archives/CC8AALGN6). + +### Filing an issue for Zowe CLI + +Go to the [Zowe CLI issue list](https://github.com/zowe/zowe-cli/issues) to file an issue. Include all relevant information. + +## Zowe Explorer + +### Chatting with the Zowe Explorer community + +Chat with the community on [Slack](https://openmainframeproject.slack.com/archives/CUVE37Z5F) by indicating whether the message about Zowe Explorer, Zowe Explorer for IBM CICS extension, or the Zowe Explorer FTP Extension. + +### Filing an issue for Zowe Explorer and Zowe Explorer extensions + +Before filing an issue, check if the error stems from either Zowe Explorer, the Zowe Explorer for IBM CICS extension or the Zowe Explorer FTP Extension. + +To file an issue: + +1. To check the error source, expand the error message that displays in VS Code and review the **Source** description: + + ![Image that shows how to check the error source](../images/ze/ZE-ftp-find-source.gif) + - Errors arising from Zowe Explorer identify the **Source** as *Zowe Explorer (Extension)*. + - Errors arising from the Zowe Explorer CICS extension identify the **Source** as *Zowe Explorer for IBM CICS (Extension)*. + - Errors arising from the Zowe Explorer FTP extension identify the **Source** as *Zowe Explorer Extension for FTP (Extension)*. + +2. Go to the extension repository to file an issue. Include all relevant information. + - [Zowe Explorer issue list](https://github.com/zowe/zowe-explorer-vscode/issues) + - [Zowe Explorer for IBM CICS issue list](https://github.com/zowe/cics-for-zowe-client/issues) + - [Zowe Explorer FTP Extension issue list](https://github.com/zowe/zowe-explorer-vscode/issues) + - Add the label `zFTP` to indicate the extension. + +## Zowe Explorer plug-in for IntelliJ IDEA + +### Chatting with the Zowe Explorer plug-in for IntelliJ IDEA community + +Chat with the community in [Slack](https://openmainframeproject.slack.com/archives/C020BGPSU0M). + +### Filing an issue for Zowe Explorer plug-in for IntelliJ IDEA + +Go to the [Zowe Explorer plug-in for IntelliJ IDEA issue list](https://github.com/zowe/zowe-explorer-intellij/issues) to file an issue. Include all relevant information. + +## Zowe Client SDKs + +### Chatting with the Zowe Client SDKs community + +Chat with the community on [Slack](https://openmainframeproject.slack.com/archives/C010AUS5MK5) by indicating whether the message is about Zowe Client Node.js SDK, Zowe Client Python SDK, Zowe Client Kotlin SDK, or Zowe Client Java SDK. + +### Filing an issue for Zowe Client Java SDK + +Go to the [Zowe Client Java SDK issue list](https://github.com/zowe/zowe-client-java-sdk/issues) to file an issue. Include all relevant information. + +### Filing an issue for Zowe Client Kotlin SDK + +Go to the [Zowe Client Kotlin SDK issue list](https://github.com/zowe/zowe-client-kotlin-sdk/issues) to file an issue. Include all relevant information. + +### Filing an issue for Zowe Client Node.js SDK + +Go to the [Zowe Client Node.js SDK issue list](https://github.com/zowe/zowe-cli/issues) to file an issue. Include all relevant information. + +### Filing an issue for Zowe Client Python SDK *technical preview* + +Go to the [Zowe Client Python SDK issue list](https://github.com/zowe/zowe-client-python-sdk/issues) to file an issue. Include all relevant information. + +## Zowe Chat *technical preview* + +### Chatting with the Zowe Chat community + +Chat with the community on [Slack](https://openmainframeproject.slack.com/archives/C03NNABMN0J). + +### Filing an issue for Zowe Chat + +Go to the [Zowe Chat issue list](https://github.com/zowe/zowe-chat/issues) to file an issue. Include all relevant information. diff --git a/docs/user-guide/sdks-using.md b/docs/user-guide/sdks-using.md index 3f350a3f97..1ef139fbee 100644 --- a/docs/user-guide/sdks-using.md +++ b/docs/user-guide/sdks-using.md @@ -4,128 +4,11 @@ Leverage the Zowe Client Software Development Kits (SDKs) to build client applic The SDKs include programmatic APIs, each of which performs a particular mainframe task. For example, one API package provides the ability to upload and download z/OS data sets. You can leverage that package to rapidly build a client application that interacts with data sets. -The following SDKs are available: - -- Zowe Java Client SDK -- Zowe Node.js Client SDK -- Zowe Python Client SDK - -## SDK documentation - -For detailed SDK documentation, see the following: -- [Zowe Node.js SDK](https://docs.zowe.org/stable/typedoc/index.html) -- [Zowe Client Python SDK](https://zowe-client-python-sdk.readthedocs.io/en/latest/) - -## Software requirements - -### Java SDK - -Requires Java runtime version 11 and above. - -### Node.js SDK - -If you install Node SDK packages from the online registry, the required dependencies are installed automatically. - -If you download Node SDK packages from Zowe.org, the folder contains dependencies that you must install manually. Extract the TGZ files from the folder, copy the files to your project, and issue the following commands to install the dependencies. - -``` -npm install imperative.tgz -``` - -``` -npm install core-for-zowe-sdk.tgz -``` - -### Python SDK - -If you install Python SDK packages from the online registry, the required dependencies are installed automatically. - -If you download the Python SDK packages from Zowe.org, the downloaded folder contains dependencies that you must install manually. Extract the WHL files from the folder, copy the files to your project, and issue the following command for each dependency: - -``` -pip install .whl -``` - -## Getting started - -To get started, import the SDK packages to your project. You can pull the packages from an online registry, or download the packages from Zowe.org to install locally. - -### Install Java SDK from an online registry - -To install this library in your project, use a build tool such as Maven, Gradle or Ant. Use the following link to get the necessary artifact: - -https://mvnrepository.com/artifact/org.zowe.client.java.sdk/zowe-client-java-sdk - -For a Maven project add the SDK as a dependency by updating your `pom.xml` as follows: - -``` - - org.zowe.client.java.sdk - zowe-client-java-sdk - 2.2.0 - -``` - -For a Gradle project add the SDK as a dependency by updating your `build.gradle` as follows: - -``` - implementation group: 'org.zowe.client.java.sdk', name: 'zowe-client-java-sdk', version: '2.2.0' -``` - -The version 2.2.0 can change. Look at the artifact link to select latest version. - -### Install Node.js from an online registry - -Pull the packages from an online registry such as npm. - -1. In command-line window, navigate to your project directory. Issue the following command to install a package from the registry: - - - To import a Node.js package: `npm install ` - - *where* `` is the name of the SDK package that you want to install, such as `zos-files-for-zowe-sdk`. - - The packages are installed. Node packages are defined in `package.json` in your project. - -2. **(Optional)** You might want to automatically update the SDK version when updates become available, or you might want to prevent automatic updates. - - - To define the versioning scheme for Node packages, use [semantic versioning](https://docs.npmjs.com/about-semantic-versioning). - -### Install Python SDK from an online registry - -Pull the packages from an online registry such as PyPi. - -1. In command-line window, navigate to your project directory. Issue the following command to install a package from the registry: - - - To import a Python package: `pip install ` - - *where* `` is the name of the SDK package that you want to install, such as `zos-files-for-zowe-sdk`. - - Python packages are installed by default to `$PYTHONPATH/Lib/site-packages` (Linux) or to the Python folder in your local `/AppData` folder (Windows). - -2. **(Optional)** You might want to automatically update the SDK version when updates become available, or you might want to prevent automatic updates. - - - To define versioning for Python packages, specify versions or version ranges in a `requirements.txt` file checked-in to your project. For more information, see [pip install](https://pip.pypa.io/en/stable/cli/pip_install/) in the pip documentation. - -### Install Node.js and Python SDKs from a local package - -Download and install the packages. - -1. Navigate to [Zowe.org Downloads](https://www.zowe.org/download.html). Select your desired programming language in the **Zowe Client SDKs** section. - - The SDK is downloaded to your computer. - -2. Unzip the SDK folder, which contains the packages for each set of functionality (such as z/OS Jobs). Copy each file that you want to install and paste them into your project directory. - -3. Install required dependencies, which are included in the bundle. See [Software requirements](#software-requirements) above for more information. - -4. In a command-line window, navigate to your project directory. Issue *one* of the following commands. - - - To install a Node.js package: `npm install .tgz` - - To install a Python package: `pip install .whl` - - *where* `` is the name of the package that you want to install, such as `zos-files-for-zowe-sdk`. - - Repeat the command for each package that you need. Packages are now installed. +The following SDKs are available. +- Zowe Client Java SDK +- Zowe Client Kotlin SDK +- Zowe Client Node.js SDK +- Zowe Client Python SDK *technical preview* ## SDK documentation @@ -290,10 +173,13 @@ For Node SDK usage and syntax examples, refer to the following package READMEs: - [z/OS USS](https://www.npmjs.com/package/@zowe/zos-uss-for-zowe-sdk) - Work with UNIX system services (USS) files on z/OS. - [z/OS Workflows](https://www.npmjs.com/package/@zowe/zos-workflows-for-zowe-sdk) - Create and manage z/OSMF workflows on z/OS. -### Using - Python +### Using Python For information about the Python SDK, including usage and syntax examples, see the [Python SDK ReadTheDocs](https://zowe-client-python-sdk.readthedocs.io/en/latest/). -## Contributing +### Using Kotlin + +For information about Zowe Client Kotlin SDK, including a setup guide and source code documentation, see the [Zowe Client Kotlin SDK docs](https://zowe.github.io/zowe-client-kotlin-sdk/). -For information about contributing to the open-source Zowe SDKs, see [Developing for Zowe SDKs](../extend/extend-sdks.md). +### Using Java +For information about how to use Zowe Client Java SDK, see [this README.md section](https://github.com/zowe/zowe-client-java-sdk/?tab=readme-ov-file#examples). diff --git a/docs/user-guide/systemrequirements-cli.md b/docs/user-guide/systemrequirements-cli.md index 81e1e071c1..c52e6e0fe7 100644 --- a/docs/user-guide/systemrequirements-cli.md +++ b/docs/user-guide/systemrequirements-cli.md @@ -1,10 +1,13 @@ -# Zowe CLI System requirements +# Zowe CLI system requirements Before installing Zowe CLI, ensure that your environment meets the prerequisites that are described here. +:::info Required role: systems administrator +::: + ## Client-side requirements -Zowe CLI is supported on Windows, Linux, and Mac operating systems. Meet the following requirements before you install the CLI: +Zowe CLI is supported on Windows, Linux, and Mac operating systems. Meet the following requirements before you install the CLI. ### Node.js @@ -18,7 +21,7 @@ To install Node.js: 2. Restart the command prompt after installing Node.js, if required. - 3. Verify that Node.js is installed: + 3. Verify that Node.js is installed. Issue the following command in the command prompt: ``` node --version @@ -27,13 +30,9 @@ To install Node.js: If you issue the `node --version` command and get an error message, confirm that your PATH environment variable includes the path to the Node.js installation location. -:::info important -If you are installing Zowe CLI with Node.js 16 on a Windows operating system, see [Installing Zowe CLI with Node.js 16 on Windows](../user-guide/cli-install-cli-nodejs-windows.md). -::: - ### npm -Node Package Manager (npm) is included with most Node.js installations and is used to install and manage Node.js packages on your personal computer. +Node Package Manager (npm) is included with most Node.js installations and is used to install and manage Node.js packages on your personal computer. (Zowe CLI supports the npm version packaged with Node.js.) Your installed version of npm must be compatible with your version of Node.js. @@ -51,17 +50,11 @@ To determine the installed version of npm: If your npm version is not compatible, install a new version of Node.js. -:::info important - If you are running npm version 8.11.0 or 8.12.0 and you are installing Zowe CLI on a computer that cannot access the Internet or has restricted Internet access, your Zowe CLI installation appears to complete successfully. - - However, when you issue Zowe commands that access the Secure Credential Store, the commands return error messages. To circumvent this problem, install npm 8.12.1 or later on your computer. If you cannot upgrade to 8.12.1 or later, see [Zowe Commands Fail with Secure Credential Errors](../troubleshoot/cli/known-cli.md#zowe-commands-fail-with-secure-credential-errors). -::: - -### Secure Credential Store +### Secure credential storage On Linux systems, you must install the packages `gnome-keyring` and `libsecret` (or `libsecret-1-0` on Debian and Ubuntu). -For information about how to configure Secure Credential Store on headless Linux and z/Linux, see [Configure Secure Credential Store on headless Linux operating systems](../user-guide/cli-configure-scs-on-headless-linux-os.md). +For information on performing this configuration, see [Configuring secure credential storage on headless Linux operating systems](../user-guide/cli-configure-scs-on-headless-linux-os.md). ### Plug-in client requirements @@ -77,17 +70,21 @@ Ensure that you meet the client-side requirements for the **IBM Db2** plug-in *b IBM z/OSMF must be configured and running. -You do not need to install the full Zowe solution to install and use Zowe CLI. Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can issue Zowe CLI commands successfully. z/OSMF enables the core capabilities, such as retrieving data sets, executing TSO commands, submitting jobs, and more. If Zowe API Mediation Layer (API ML) is configured and running, Zowe CLI users can choose to connect to API ML rather than to every separate service. +You do not need to install the full Zowe solution to install and use Zowe CLI. + +Minimally, an instance of IBM z/OSMF must be running on the mainframe before you can issue Zowe CLI commands successfully. z/OSMF enables the core capabilities, such as retrieving data sets, executing TSO commands, submitting jobs, and more. + +If Zowe API Mediation Layer (API ML) is configured and running, Zowe CLI users can choose to connect to API ML rather than to every separate mainframe service. ### Plug-in services Services for plug-ins must be configured and running. -Plug-ins communicate with various mainframe services. The services must be configured and running on the mainframe before issuing plug-in commands. For example, the CICS plug-in requires an instance of IBM CICS Transaction Server on the mainframe with the CICS Management Client Interface (CMCI) API running. +Plug-ins communicate with various mainframe services. The services must be configured and running on the mainframe before issuing plug-in commands. For example, the CICS plug-in requires an instance of IBM CICS on the mainframe with CICS management client interface (CMCI) (REST services) running. For more information, see [Software requirements for CLI plug-ins](./cli-swreqplugins.md) ### Zowe CLI on z/OS is not supported -Zowe CLI can be installed on an IBM z/OS environment and run under Unix System Services (USS). However, the IBM Db2 plug-in cannot run on z/OS due to native code requirements. As such, Zowe CLI is *not supported* on z/OS and is currently experimental. +Zowe CLI can be installed on an IBM z/OS environment and run under Unix System Services (USS). However, the IBM Db2 plug-in and the Zowe Secrets SDK cannot run on z/OS due to native code requirements. This means that any z/OS credentials display as plain text on a team configuration file. As such, Zowe CLI is *not supported* on z/OS and is currently experimental. ## Free disk space diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index abc81bbd57..19f60503be 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/user-guide/systemrequirements-zos.md @@ -16,10 +16,10 @@ Be sure your z/OS system meets the following prerequisites: ### z/OS -- z/OS version is in active support, such as Version 2.4, 2.5, and 3.1 +- z/OS version is in active support, such as Version 2.5, and 3.1 :::note Notes: - * Zowe Version 2.11 or higher is required when using z/OS Version 3.1. + * z/OS V2.4 reached end of support on 30 September, 2024. For more information, see the [z/OS v2.4 lifecycle details](https://www.ibm.com/support/pages/zos24x-withdrawal-notification). * z/OS V2.3 reached end of support on 30 September, 2022. For more information, see the [z/OS v2.3 lifecycle details](https://www.ibm.com/support/pages/zos23x-withdrawal-notification). ::: @@ -90,15 +90,15 @@ Zowe consumption reference data were measured with the default Zowe configuratio ### Java -- IBM SDK for Java Technology Edition V8 +- IBM® Semeru Runtime Certified Edition for z/OS® version 17 ### z/OSMF (Optional) -- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.4, Version 2.5, or Version 3.1. +- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.5, or Version 3.1. z/OSMF is included with z/OS so does not need to be separately installed. If z/OSMF is present, Zowe detects z/OSMF during configuration and uses z/OSMF for the following purposes: - - Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). If z/OSMF is not available, Zowe is still able to provide SSO by generating its own JWT and making direct SAF calls. + - Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). - REST API services for Files (Data Sets and USS), JES, and z/OSMF workflows. These are used by some Zowe applications such as the Zowe Explorers in the Zowe Desktop. If z/OSMF REST APIs are not present, other Zowe desktop application, such as the File Editor that provides access to USS directories and files as well as MVS data sets and members, will work through the Zowe Z Secure Services (ZSS) component to access z/OS resources. diff --git a/docs/user-guide/systemrequirements-zosmf.md b/docs/user-guide/systemrequirements-zosmf.md index dba1e50afa..2925eafff8 100644 --- a/docs/user-guide/systemrequirements-zosmf.md +++ b/docs/user-guide/systemrequirements-zosmf.md @@ -79,8 +79,8 @@ If your implementation uses an external security manager other than RACF (for ex - [Configure z/OS Management Facility for ACF2](https://techdocs.broadcom.com/us/en/ca-mainframe-software/security/ca-acf2-for-z-os/16-0/installing/configure-z-os-management-facility-for-ca-acf2.html) ::: -## z/OSMF REST services for the Zowe CLI -The Zowe CLI uses z/OSMF Representational State Transfer (REST) APIs to work with system resources and extract system data. Ensure that the following REST services are configured and available. +## z/OSMF REST services for Zowe clients +[Zowe clients](../appendix/zowe-glossary.md#zowe-client-projects) use z/OSMF Representational State Transfer (REST) APIs to work with system resources and extract system data. Ensure that the following REST services are configured and available. z/OSMF REST services | Requirements | Resources in IBM knowledge Center ---|---|--- diff --git a/docs/user-guide/user-roadmap-zowe-cli copy.md b/docs/user-guide/user-roadmap-zowe-cli copy.md new file mode 100644 index 0000000000..950395b49b --- /dev/null +++ b/docs/user-guide/user-roadmap-zowe-cli copy.md @@ -0,0 +1,161 @@ +# Installing Zowe CLI overview + +The resources here provide information about various Zowe CLI topics, such as learning basic skills, installation, developing, and troubleshooting. + +:::tip + +To identify the resources most relevant for you, use the following definitions of Zowe CLI skill levels. + +- **Beginner:** You're starting out and want to learn the fundamentals. +- **Intermediate:** You have some experience but want to learn more in-depth skills. +- **Advanced:** You have lots of experience and are looking to learn about specialized topics. + +::: + +## Fundamentals + +> Zowe skill level: Beginner + +- [**Zowe CLI overview**](../getting-started/overview.md#zowe-cli) + + New to Zowe CLI? This overview topic provides an introduction to Zowe CLI. + +- [**Architecture**](../getting-started/zowe-architecture.md#zowe-architecture) + + Review the Zowe architecture to understand how Zowe CLI works in the Zowe framework. + +- [**Zowe CLI FAQs**](../getting-started/zowe_faq.md#zowe-cli-faq) + + If you have a question, check out the FAQ, which answers the most commonly asked questions about Zowe CLI. + +## Quick start + +> Zowe skill level: Beginner + +- [**Zowe CLI quick start**](../getting-started/cli-getting-started.md) + + Get started with Zowe CLI quickly and easily. + +- [**Blog: Getting Started with Zowe CLI**](https://medium.com/zowe/getting-started-with-zowe-cli-7a29420c6be7) + + This blog explains how to get started with Zowe CLI quickly. + +## Installing + +> Zowe skill level: Beginner + +- [**System requirements**](../user-guide/systemrequirements-cli.md) + + Review this topic to ensure that your system meets the requirements for installing Zowe CLI. + +- [**Installing Zowe CLI**](../user-guide/cli-installcli.md) + + Follow the steps to install a new release of Zowe CLI. + +## Configuring and updating + +> Zowe skill level: Intermediate + +- [**Configuring Zowe CLI environment variables**](../user-guide/cli-configuringcli-ev.md) + + Explains how to configure Zowe CLI environment variables, such as changing log levels, setting the home directory location, and daemon mode. + +- [**Updating Zowe CLI**](../user-guide/cli-updatingcli.md) + + Learn how to update Zowe CLI to a more recent version using different methods. + +## Using Zowe CLI and plug-ins + +> Zowe skill level: Intermediate + +- [**Using Zowe CLI**](../user-guide/cli-using-usingcli.md) + + Learn about how to use Zowe CLI, including connecting to the mainframe, managing profiles, integrating with API Mediation Layer, and more. + +- [**Zowe CLI extensions and plug-ins**](../user-guide/cli-extending.md) + + This information guides you to explore the extensions and plug-ins available to Zowe CLI and install plug-ins to extend the capabilities of Zowe CLI. Plug-ins add functionality to the product in the form of new command groups, actions, objects, and options. + +- **Docs: Zowe CLI command reference guide** + + View detailed documentation on commands, actions, and options in Zowe CLI. The reference document is based on the `@zowe-v3-lts` version of the CLI. + + The content also contains the web help for all Zowe ecosystem-conformant plug-ins that contributed to this website. + + You can read an interactive online version, download a PDF document, or download a ZIP file containing the HTML for the online version: + - Browse online + - Download CLI reference in PDF format + - Download CLI reference in ZIP format + +- **Best practices** + + Are you looking for recommendations and tips on how to best use Zowe CLI to meet your needs? These resources provide best practices recommendations. + + - [**Blog: Zowe CLI Tips & Tricks**](https://medium.com/modern-mainframe/zowe-cli-tips-tricks-79607b8dbd4e) + +- [**Zowe CLI and TSO commands**](https://medium.com/zowe/zowe-ci-and-tso-commands-14e5445fca1e) + + This blog shows how to configure and use the TSO command feature of Zowe. + +## Developing a Zowe CLI plug-in + +> Zowe skill level: Advanced + +Zowe CLI extenders can build plug-ins that provide new commands. + +- [**Developing for the CLI**](../extend/extend-cli/cli-developing-a-plugin.md) + + Learn about developing for Zowe CLI. + +- [**Zowe CLI core repository**](https://github.com/zowe/zowe-cli) + + If you want to start working with the code immediately, check out this code repository. + +- [**Tutorials**](../extend/extend-cli/cli-devTutorials.md#tutorials) + + Follow these tutorials to get started working with a sample plug-in. + +## Contributing to Zowe CLI + +> Zowe skill level: Advanced + +- [**Contributing guidelines**](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) + + This document is a summary of conventions and best practices for development within Zowe CLI or development of Zowe CLI plug-ins. The guidelines contain critical information about working with the code, running, writing, and maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. + +- [**Conformance Program**](../extend/zowe-conformance-program.md) + + This topic introduces the Zowe Conformance Program. Conformance provides Independent Software Vendors (ISVs), System Integrators (SIs), and end users greater confidence that their software will behave as expected. As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe CLI, you are encouraged to get certified today. + +- [**Blog: Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) + + This blog describes the Conformance Program in more details. + +## Troubleshooting and support + +- [**Troubleshooting Zowe CLI**](../troubleshoot/cli/troubleshoot-cli.md) + + Learn about the tools and techniques that are available to help you troubleshoot and resolve problems. You can also find a list of common issues about Zowe CLI. + +- [**Submit an issue**](https://github.com/zowe/zowe-cli/issues/new) + + If you have an issue that is specific to Zowe CLI, you can submit an issue against the `zowe-cli` repository on GitHub. + +## Community resources + +- [**Slack channel**](https://openmainframeproject.slack.com/) + + Join the #zowe-cli Slack channel to ask questions about Zowe CLI, propose new ideas, and interact with the Zowe community. + +- [**Zowe CLI squad meetings**](https://lists.openmainframeproject.org/g/zowe-dev/calendar) + + Join Zowe CLI squad meetings to get involved. + +- [**Zowe CLI Blogs on Medium**](https://medium.com/zowe/search?q=Zowe%20CLI) + + Read a series of blogs about Zowe CLI on Medium to explore use cases, best practices, and more. + +- **Community Forums** + + Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe). + diff --git a/docs/user-guide/user-roadmap-zowe-cli.md b/docs/user-guide/user-roadmap-zowe-cli.md index f1c8c598af..f1cc7ce8bd 100644 --- a/docs/user-guide/user-roadmap-zowe-cli.md +++ b/docs/user-guide/user-roadmap-zowe-cli.md @@ -1,161 +1,59 @@ -# Zowe CLI +# Installing Zowe CLI -The resources here provide information about various Zowe CLI topics, such as learning basic skills, installation, developing, and troubleshooting. +For a better understanding of Zowe CLI, review the various reference materials that document the application. -:::tip +Get to know what's new in the Zowe ecosystem, review the quick start guide, and find ways to get the most out of Zowe CLI. -To identify the resources most relevant for you, use the following definitions of Zowe CLI skill levels. +## About Zowe CLI -* Beginner: You're starting out and want to learn the fundamentals. -* Intermediate: You have some experience but want to learn more in-depth skills. -* Advanced: You have lots of experience and are looking to learn about specialized topics. -::: - -## Fundamentals - -> Zowe skill level: Beginner - -- [**Zowe CLI overview**](../getting-started/overview.md#zowe-cli) - - New to Zowe CLI? This overview topic introduces what is Zowe CLI. - -- [**Architecture**](../getting-started/zowe-architecture.md#zowe-architecture) - - Review the Zowe architecture to understand how Zowe CLI works in the Zowe framework. - -- [**Zowe CLI FAQs**](../getting-started/zowe_faq.md#zowe-cli-faq) - - If you have a question, it's a good idea to try the FAQ, which answers the most commonly asked questions about Zowe CLI. - - -## Quick start - -> Zowe skill level: Beginner - -- [**Zowe CLI quick start**](../getting-started/cli-getting-started.md) - - Get started with Zowe CLI quickly and easily. - -- [**Blog: Getting Started with Zowe CLI**](https://medium.com/zowe/getting-started-with-zowe-cli-7a29420c6be7) - - This blog enables you to get started with Zowe CLI quickly. - -## Installing - -> Zowe skill level: Beginner - -- [**System requirements**](../user-guide/systemrequirements-cli.md) - - Review this topic to ensure that your system meets the requirements for installing Zowe CLI. - -- [**Installing Zowe CLI**](../user-guide/cli-installcli.md) - - Follow the steps to install a new release of Zowe CLI. - -## Configuring and updating - -> Zowe skill level: Intermediate - -- [**Configuring Zowe CLI environment variables**](../user-guide/cli-configuringcli-ev.md) +- Check out [**Zowe release notes**](../whats-new/release-notes/release-notes-overview.md) to learn about the latest Zowe CLI updates. - Explains how to configure Zowe CLI environment variables, such as changing log levels, setting the home directory location, and daemon mode. +- Watch **Office Hours** videos that outline major features in [Zowe CLI V2](../getting-started/zowe-office-hours.md) and [Zowe CLI V3](../whats-new/zowe-v3-office-hours.md). -- [**Updating Zowe CLI**](../user-guide/cli-updatingcli.md) +- New to Zowe? Pick up terms and basic concepts with the [**Zowe Glossary**](../appendix/zowe-glossary.md). - Learn how to update Zowe CLI to a more recent version using different methods. +## Zowe CLI quick start -## Using Zowe CLI and plug-ins +Ready to start using Zowe CLI *right now*? Speed up the installation process with the [**Zowe CLI quick start**](../getting-started/cli-getting-started.md) to get Zowe CLI up and running in your environment sooner. -> Zowe skill level: Intermediate +## Getting the most from Zowe CLI -- [**Using Zowe CLI**](../user-guide/cli-using-usingcli.md) +The following blog posts on the publishing platform Medium go over use cases and provide recommendations on best practices, providing tips on how to best use Zowe CLI to meet your needs. - Learn about how to use Zowe CLI, including connecting to the mainframe, managing profiles, integrating with API Mediation Layer, and more. +- [Zowe CLI: Getting started with **Team Config**.](https://medium.com/zowe/zowe-cli-team-config-101-be57345ed668) -- [**Zowe CLI extensions and plug-ins**](../user-guide/cli-extending.md) +- [**Password management** for Zowe CLI profiles](https://medium.com/zowe/password-management-for-zowe-cli-profiles-c57f64d1fe88) - This information guides you to explore the extensions and plug-ins available to Zowe CLI and install plug-ins to extend the capabilities of Zowe CLI. Plug-ins add functionality to the product in the form of new command groups, actions, objects, and options. +- [**Enterprise rollout** of Zowe CLI](https://medium.com/zowe/enterprise-rollout-of-zowe-cli-2b0a84357de3) -- **Docs: Zowe CLI command reference guide** +- [Zowe CLI **Tips & Tricks**](https://medium.com/modern-mainframe/zowe-cli-tips-tricks-79607b8dbd4e) - View detailed documentation on commands, actions, and options in Zowe CLI. The reference document is based on the `@zowe-v2-lts` version of the CLI. +- [Zowe CLI and **TSO commands**](https://medium.com/zowe/zowe-ci-and-tso-commands-14e5445fca1e) - The content also contains the web help for all Zowe ecosystem-conformant plug-ins that contributed to this website. - - You can read an interactive online version, download a PDF document, or download a ZIP file containing the HTML for the online version: - - Browse online - - Download CLI reference in PDF format - - Download CLI reference in ZIP format +:::info find out more -- **Best practices** +Check out **Medium** for more informative blogs on [Zowe CLI](https://medium.com/zowe/search?q=Zowe%20CLI). - Are you looking for recommendations and tips on how to best use Zowe CLI to meet your needs? These resources provide best practices recommendations. - - - [**Blog: Zowe CLI Tips & Tricks**](https://medium.com/modern-mainframe/zowe-cli-tips-tricks-79607b8dbd4e) - -- [**Zowe CLI and TSO commands**](https://medium.com/zowe/zowe-ci-and-tso-commands-14e5445fca1e) - - This blog shows how to configure and use the TSO command feature of Zowe. - -## Developing a Zowe CLI plug-in - -> Zowe skill level: Advanced - -Zowe CLI extenders can build plug-ins that provide new commands. - -- [**Developing for the CLI**](../extend/extend-cli/cli-developing-a-plugin.md) - - Learn about developing for Zowe CLI. - -- [**Zowe CLI core repository**](https://github.com/zowe/zowe-cli) - - If you want to start working with the code immediately, check out this code repository. - -- [**Tutorials**](../extend/extend-cli/cli-devTutorials.md#tutorials) - - Follow these tutorials to get started working with a sample plug-in. +::: ## Contributing to Zowe CLI -> Zowe skill level: Advanced - -- [**Contributing guidelines**](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) - - This document is a summary of conventions and best practices for development within Zowe CLI or development of Zowe CLI plug-ins. The guidelines contain critical information about working with the code, running, writing, and maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly. - -- [**Conformance Program**](../extend/zowe-conformance-program.md) - - This topic introduces the Zowe Conformance Program. Conformance provides Independent Software Vendors (ISVs), System Integrators (SIs), and end users greater confidence that their software will behave as expected. As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe CLI, you are encouraged to get certified today. - -- [**Blog: Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) - - This blog describes the Conformance Program in more details. - -## Troubleshooting and support - -- [**Troubleshooting Zowe CLI**](../troubleshoot/cli/troubleshoot-cli.md) - - Learn about the tools and techniques that are available to help you troubleshoot and resolve problems. You can also find a list of common issues about Zowe CLI. - -- [**Submit an issue**](https://github.com/zowe/zowe-cli/issues/new) - - If you have an issue that is specific to Zowe CLI, you can submit an issue against the `zowe-cli` repository on GitHub. +- Review the [**Contributing guidelines**](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) for a summary of conventions and best practices for development of Zowe CLI. -## Community resources +## Zowe CLI community resources -- [**Slack channel**](https://openmainframeproject.slack.com/) - - Join the #zowe-cli Slack channel to ask questions about Zowe CLI, propose new ideas, and interact with the Zowe community. +The Zowe ecosystem is more than a collection of applications and extensions. An entire community exists to work on enhancements, help answer questions, and discuss plans for the future of the open source project. -- [**Zowe CLI squad meetings**](https://lists.openmainframeproject.org/g/zowe-dev/calendar) +- Join the [**#zowe-cli**](https://openmainframeproject.slack.com/archives/CC8AALGN6) Slack channel to **ask questions about Zowe CLI**, propose new ideas, and interact with the Zowe community. - Join Zowe CLI squad meetings to get involved. +- You can join **Zowe CLI squad meetings** to get involved. The meeting schedule is posted in the [Zowe calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe). -- [**Zowe CLI Blogs on Medium**](https://medium.com/zowe/search?q=Zowe%20CLI) +- **Discuss Zowe topics** in the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe). - Read a series of blogs about Zowe CLI on Medium to explore use cases, best practices, and more. +- If you have an issue that is specific to Zowe CLI, you can [**submit an issue**](https://github.com/zowe/zowe-cli/issues/new) in the `zowe-cli` repository on GitHub. -- **Community Forums** +## Zowe Conformance Program - Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe). +Administered by the Open Mainframe Project, the [Zowe Conformance Program](../extend/zowe-conformance-program.md) aims to give users the confidence that when they use a product, app, or distribution that leverages Zowe, they can **expect a high level of common functionality**, **interoperability**, and **user experience**. +Read the blog post [**Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) for more details about the Conformance Program, including useful references. diff --git a/docs/user-guide/verify-zowe-runtime-install.md b/docs/user-guide/verify-zowe-runtime-install.md index 8af891f364..b8fc189e12 100644 --- a/docs/user-guide/verify-zowe-runtime-install.md +++ b/docs/user-guide/verify-zowe-runtime-install.md @@ -65,14 +65,14 @@ The response `UP` confirms that API Mediation Layer is installed and is running Zowe z/OS services usually are registered with Zowe APIML Discovery and exposed with certain service url like `//api/v1`. -Here we give an example of verifying `jobs-api` shipped with Zowe. Please be aware that `jobs-api` is not enabled by default if you created your Zowe configuration file from `example-zowe.yaml`. To enable `jobs-api`, you need to set `components.jobs-api.enabled` to be `true` and restart Zowe. You can verify the installation of `jobs-api` service from an internet browser by entering the following case-sensitive URL: +To verify a service is necessary to call any available endpoint, for example: ``` -https://hostName:gatewayPort/jobs/api/v1/jobs?prefix=* +https://hostName:gatewayPort/serviceId/api/v1/version ``` where, `gatewayPort` is the port number that is assigned to `zowe.externalPort` in the `zowe.yaml` file used to launch Zowe. For more information, see [Domain and port to access Zowe](../appendix/zowe-yaml-configuration#domain-and-port-to-access-zowe). -The above link should prompt you to login. After you input correct user name and password of your target z/OS system, you should see JSON format data of all jobs running on the system. +The path `serviceId/api/v1/version` depends on a specific service. You can also use API Catalog to verify a registered service. diff --git a/docs/user-guide/ze-cics-usage-tips.md b/docs/user-guide/ze-cics-usage-tips.md index 8331a73327..67b1082068 100644 --- a/docs/user-guide/ze-cics-usage-tips.md +++ b/docs/user-guide/ze-cics-usage-tips.md @@ -1,9 +1,13 @@ # Usage tips -The following tips can help you perform tasks more efficiently when working with the CICS extension: +Make the best use of the Zowe Explorer CICS Extension with the following tips. -- All menu action commands available when right-clicking a profile or resource (excluding **Show Attributes**) can be applied to multiple items. To do this, select the multiple nodes of the same type before right-clicking and selecting the command. +## Multi-select functionality -- To select multiple nodes, you can hold `Ctrl` or `Cmd` key while clicking on the resources. You can also select multiple consecutive nodes by selecting the first item in a list of nodes and then holding the `Shift` key while selecting the last item in the list. +Apply an action to multiple objects at the same time for increased efficiency. All menu action commands available when right-clicking a profile or resource (excluding **Show Attributes**) can be applied to multiple items. To do this, select the multiple nodes of the same type before right-clicking and selecting the command. -- Click the refresh icon at the top of the CICS view to reload the resources in every region. +To select multiple nodes, hold the `Ctrl` or `Cmd` key while selecting the resources. You can also select multiple consecutive nodes by selecting the first item in a list of nodes and then holding the `Shift` key while selecting the last item in the list. + +## Refreshing the resources view + +Click the **Refresh** icon at the top of the **CICS** tree view to reload the resources in every region. diff --git a/docs/user-guide/ze-create-zowe-explorer-cics-ext-profiles.md b/docs/user-guide/ze-create-zowe-explorer-cics-ext-profiles.md index e4f65a03cb..ead48910ad 100644 --- a/docs/user-guide/ze-create-zowe-explorer-cics-ext-profiles.md +++ b/docs/user-guide/ze-create-zowe-explorer-cics-ext-profiles.md @@ -1,99 +1,77 @@ -# Creating Zowe Explorer CICS Extension profiles +# Managing Zowe Explorer CICS Extension profiles -You need to have a Zowe Explorer profile to use all functions of the extension. +To use all functions of the Zowe Explorer CICS extension, you need to have a Zowe Explorer profile. -If you already have a Zowe CICS CLI profile, the CICS tree loads the default profile on startup. +If you already have a Zowe CICS CLI profile, the CICS tree in the VS Code **Side Bar** loads the default profile on startup. -If you do not have an existing Zowe CICS CLI profile, follow these steps to create one: +If you do not have an existing Zowe CICS CLI profile, refer to the following instructions. ## Using Zowe team configuration -1. Select the **+** button in the CICS tree. +1. Expand the **CICS** tree in the **Side Bar**, and click the **+** icon. -2. Select the **Create New CICS profile** option to open the config file. +2. In the **Quick Pick** menu, select the **Create New CICS profile** option to open the configuration file. If no configuration file is available, select the **Create a new Team Configuration File** option from the **Quick Pick** menu. -3. Edit the config file to add a CICS profile. + The active configuration file opens in an **Editor**. If none exists, a new configuration file opens in an **Editor**. -4. Save the config file. +3. Edit the configuration file to add a CICS profile. -5. Click the **Refresh** button at the top level of the CICS tree or run the `Zowe Explorer for IBM CICS: Refresh` option in the command palette to refresh the Zowe Explorer for IBM CICS extension. +4. Save the configuration file. -6. Select the **+** button in the CICS tree and click the newly created profile to load it into view. +5. Refresh the Zowe Explorer for IBM CICS extension. Either click the **Refresh** icon at the top of the **CICS** tree in the **Side Bar**, or select the `Zowe Explorer for IBM CICS: Refresh` option in the **Command Palette**. -![Zowe CICS Explorer profiles from config](../images/ze-cics/create-profile-from-config.gif) +6. In the **CICS** tree, select the **+** icon and select the newly created profile from the **Quick Pick** menu to display it in the **CICS** tree. -### Using Zowe V1 profiles + ![Zowe CICS Explorer profiles from config](../images/ze-cics/create-profile-from-config.gif) -1. Select the **+** button in the CICS tree. +::: Note -2. Select the **Create a CICS profile** option to open a panel that defines connection details. - -**Note**: The connection must point to a CICS region's CICS Management Client Interface (CMCI) TCP/IP host name and port number. The region can be a WUI server in a CICSPlex, or else a stand-alone Single Management Application Programming (SMSS) region. +The CICS profile must specify a CICS region's CICS Management Client Interface (CMCI) TCP/IP host name and port number. The region can be a WUI server in a CICSPlex or a stand-alone CICS System Management Single Server (SMSS) region. Configuring a CICS region to have a connection is a system programmer task and more details can be found in [Setting up CMCI with CICSPlex SM](https://www.ibm.com/docs/en/cics-ts/5.3?topic=explorer-setting-up-cmci-cicsplex-sm) or [Setting up CMCI in a stand-alone CICS region](https://www.ibm.com/docs/en/cics-ts/5.3?topic=suace-setting-up-cmci-in-stand-alone-cics-region). If your CMCI connection is configured to use a self-signed certificate that your PC's trust store does not recognize, see [Overriding untrusted TLS certificates](ze-override-tls-certs.md). -![Zowe CICS Explorer profiles](../images/ze-cics/create-profile.gif) +::: To show more than one CICS profiles in the tree, select the **+** button and choose from the list of profiles. Only profiles that are not already included in the CICS tree are shown. ## Updating profiles -### Updating profiles using Zowe team profiles +1. Expand the **CICS** tree in the **Side Bar**, and right-click a profile to open up the profile menu actions. -1. Right-click a profile to open up the profile menu actions. +2. Select the **Update Profile** option. -2. Select the **Update Profile** button to open the config file. + The associated configuration file opens in an **Editor**. -3. Edit the config file to update the profile(s). +3. Edit the configuration file to update the profile(s). -4. Save the config file. +4. Save the configuration file. -5. Click the **Refresh** button at the top level of the CICS tree or run the `Zowe Explorer for IBM CICS: Refresh` option in the command palette to refresh the Zowe Explorer for IBM CICS extension. +5. Refresh the Zowe Explorer for IBM CICS extension. Either click the **Refresh** icon at the top of the **CICS** tree in the **Side Bar**, or select the `Zowe Explorer for IBM CICS: Refresh` option in the **Command Palette**. ![Zowe CICS Explorer update profiles from config](../images/ze-cics/update-profile-from-config.gif) -### Updating Zowe V1 profiles - -1. Right-click a profile to open up the profile menu actions. - -2. Select the **Update Profile** button to update the session details. - - This opens a panel with fields containing the details that are used to create the connection. You can modify all fields apart from the **Profile Name**. - -3. Once the details are updated, click the **Update Profile** button to apply the changes to the profile. - - ![Zowe CICS Explorer update profiles](../images/ze-cics/update-profile.gif) +## Hiding and unhiding profiles -## Hiding profiles +1. Expand the **CICS** tree in the **Side Bar**, and right-click the desired profile. -1. Right-click the profile you want to hide to open the menu actions. +2. Select the **Hide Profile** option to hide it from the **CICS** tree view. -2. Select **Hide Profile** to hide it from the CICS view. - -3. To unhide the profile, click the **+** button and select the profile from the quick pick list. +3. To unhide the profile, click the **+** icon at the top of the **CICS** tree and select the profile from the **Quick Pick** menu. ![Zowe CICS Explorer hide profiles](../images/ze-cics/hide-profile.gif) ## Deleting profiles -### Deleting Zowe team profiles +1. Expand the **CICS** tree in the **Side Bar**, and right-click the desired profile. -1. Right-click the team profile you want to delete to open the menu actions. +2. Select the **Delete Profile** option. -2. Select **Delete Profile**, which opens the config file. + The associated configuration file opens in an **Editor**. -3. Edit the config file to remove the cics profile entry. +3. Edit the configuration file to remove the profile. -4. Save the config file. +4. Save the configuration file. -5. Click the **Refresh** button at the top level of the CICS tree or run the `Zowe Explorer for IBM CICS: Refresh` option in the command palette to refresh the Zowe Explorer for IBM CICS extension. +5. Refresh the Zowe Explorer for IBM CICS extension. Either click the **Refresh** icon at the top of the **CICS** tree in the **Side Bar**, or select the `Zowe Explorer for IBM CICS: Refresh` option in the **Command Palette**. ![Zowe CICS Explorer delete profiles from config](../images/ze-cics/delete-profile-from-config.gif) - -### Deleting Zowe V1 profiles - -1. Right-click the Zowe V1 profile you want to delete to open the menu actions. - -2. Select **Delete Profile** and click the **Yes** button when prompted to confirm the action of permanently deleting the profile. The functionality deletes the CICS profile from the persistent storage directory `~/.zowe/profiles/cics`. - -![Zowe CICS Explorer delete profiles](../images/ze-cics/delete-profile.gif) diff --git a/docs/user-guide/ze-ftp-install-ze-ftp-ext.md b/docs/user-guide/ze-ftp-install-ze-ftp-ext.md index fc61be474c..f1e448ffab 100644 --- a/docs/user-guide/ze-ftp-install-ze-ftp-ext.md +++ b/docs/user-guide/ze-ftp-install-ze-ftp-ext.md @@ -11,10 +11,4 @@ Zowe Explorer FTP extension adds the FTP protocol to the [Zowe Explorer](https:/ 2. Close and reopen VS Code to check that the notification message "Zowe Explorer was modified for FTP support" displays. Once installed, the notification displays every time you open VS Code to confirm that the FTP extension is available. - -## Uninstalling - -1. Click the **Extension** icon on the **Activity Bar** in VS Code to display a list of installed extensions. - -2. Click on **Zowe Explorer Extension for FTP** to open a tab in the Editor area. -3. Click the **Uninstall** icon at the top of the tab. Select the **Reload Required** button at the top of the tab to complete the uninstall. + \ No newline at end of file diff --git a/docs/user-guide/ze-ftp-supported-functions.md b/docs/user-guide/ze-ftp-supported-functions.md index 20ad60603c..9363d679f9 100644 --- a/docs/user-guide/ze-ftp-supported-functions.md +++ b/docs/user-guide/ze-ftp-supported-functions.md @@ -1,6 +1,6 @@ # Supported functionality -The functionality available in Zowe Explorer FTP Extension is detailed in the following list: +Review the following list for the functionality available in Zowe Explorer FTP Extension. ## Supported data set functionalities @@ -39,6 +39,7 @@ The functionality available in Zowe Explorer FTP Extension is detailed in the fo - View file in text/binary mode - Edit file - Save file +- Copy/paste folders and files - Create a new directory/new file - Upload file - Rename file/directory diff --git a/docs/user-guide/ze-ftp-using-ze-ftp-ext.md b/docs/user-guide/ze-ftp-using-ze-ftp-ext.md index 3a78ade9f9..8c42b04fc5 100644 --- a/docs/user-guide/ze-ftp-using-ze-ftp-ext.md +++ b/docs/user-guide/ze-ftp-using-ze-ftp-ext.md @@ -1,12 +1,4 @@ # Using Zowe Explorer FTP Extension -## System Requirements - -Ensure that you can obtain remote access to a z/OS FTP service before using the extension. - -Some functionality within the FTP extension requires the FTP server on the mainframe to be configured with the `JESINTERFACELevel` parameter set to `2`. For more information, see the [JESINTERFACELEVEL (FTP server) statement](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-jesinterfacelevel-ftp-server-statement). - - The `JESINTERFACELevel` parameter can be found in multiple locations within the mainframe, depending on your site's security policies. -Contact your system administrator to determine if your FTP server is configured with the correct `JESINTERFACELevel`. For more information, see [FTP configuration statements in FTP.DATA](https://www.ibm.com/docs/en/zos/2.5.0?topic=protocol-ftp-configuration-statements-in-ftpdata). ## Using @@ -18,17 +10,17 @@ When transferring files, data sets, or data set members, use only ASCII characte To use the FTP Extension with Zowe Explorer: -1. Select the **Zowe Explorer** icon on the **Activity Bar** in VS Code. +1. Select the **Zowe Explorer** icon on the **Activity Bar** in Visual Studio Code. -2. Hover over the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar and select the corresponding **+** icon to view the Zowe CLI FTP profiles in the **picker** dropdown list. +2. Hover over the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar and select the corresponding **+** icon to view the Zowe CLI FTP profiles in the **Quick Pick** menu. - If you do not have an existing FTP profile, see [Creating an FTP profile with Zowe Explorer](../user-guide/ze-ftp-using-ze-ftp-ext#creating-an-ftp-profile-with-zowe-explorer). + If you do not have an existing FTP profile, see [Creating an FTP profile with Zowe Explorer](#creating-an-ftp-profile-with-zowe-explorer). 3. Select a profile to display it in the **Side Bar**. 4. Hover over the profile and click the **Search** icon. -5. Enter the applicable values in the **picker** field: +5. Enter the applicable values in the **Quick Pick**: - For data sets, select or enter the data set name. - For USS, select or enter the path. - For jobs, select or enter the job owner and job prefix. @@ -39,8 +31,8 @@ If you do not have an existing Zowe FTP profile, you can create one graphically 1. Select the **Zowe Explorer** icon on the **Activity Bar** in VS Code. -2. Expand **UNIX SYSTEM SERVICES (USS)** and click the **+** icon. -3. In the **picker** drop-down menu, select the **Create a New Connection to z/OS** option. -4. Enter a profile name and press `Enter`. +2. Expand the **UNIX SYSTEM SERVICES (USS)** tree and click the **+** icon. +3. In the **Quick Pick** menu, select the **Create a New Connection to z/OS** option. +4. Enter a profile name and press the `Enter` key. 5. Select the **zftp** connection type from the dropdown list of available connection options. 6. Continue providing values for the remaining prompts, which are specific for FTP-type connections. diff --git a/docs/user-guide/ze-install-configuring-ze.md b/docs/user-guide/ze-install-configuring-ze.md new file mode 100644 index 0000000000..8b7d4d0618 --- /dev/null +++ b/docs/user-guide/ze-install-configuring-ze.md @@ -0,0 +1,81 @@ +# Configuring Zowe Explorer + +:::info Required role: Developer +::: + +Configure Zowe Explorer in the settings file so the extension performs according to your preferences. + +To access Zowe Explorer settings: + +1. Click the **Manage** icon at the bottom of the **Activity Bar**. +2. Select the **Settings** option. +3. Open the **Extension** option listed in the **Commonly Used** menu. +4. Select **Zowe Explorer** to access its settings. +5. Scroll the list to find the setting that needs modification. + +## Modifying creation settings for data sets, USS files, and jobs + +1. In Zowe Explorer settings, scroll to a data set, USS file, or job setting type. +2. Click the setting's corresponding **Edit in settings.json** link. + + This opens the `settings.json` file in an **Editor** tab. (The suggestions widget also opens if the functionality is enabled.) + +3. Edit the settings in the file as needed. +4. Save the file to keep changes. + + ![Configure Zowe settings](../images/ze/ZE-Configuration2.gif) + +## Modifying temporary file location settings + +Change the default folder location where temporary files are stored: + + 1. Navigate to Zowe Explorer settings. + 2. Under the data set, USS, or jobs settings that you want to edit, click the **Edit in settings.json** link. + 3. Modify the following definition in the file: + + ```json + "zowe.files.temporaryDownloadsFolder.path": "/path/to/directory" + ``` + + Replace `/path/to/directory` with the new folder location. + + 4. Save the file to keep the change. + +## Modifying the `Secure Credentials Enabled` setting + +When environment conditions do not support the Zowe CLI built-in credential manager, change the `Secure Credentials Enabled` setting: + + 1. Navigate to Zowe Explorer settings. + 2. Scroll to **Security: Secure Credentials Enabled**. + 3. Deselect the checkbox to disable secure credentials. + + When disabled, if the `autoStore` setting in the `zowe.config.json` file is set to `true`, z/OS credentials are stored as text in the file. + + If the `autoStore` setting is set to `false`, you are prompted for the missing credentials in VS Code. The credentials are stored and used for the duration of the session. + +## Setting confirmation requirements for submitting jobs + +Submitting the wrong job can risk potential problems on your server. This can happen when the user enters the wrong job or inadvertently selects the **Submit Jobs** option. + +To help prevent this, enable the option to require confirmation before submitting a job. Once enabled, a dialog window asking for user confirmation displays when **Submit Jobs** is selected. + +![Confirm Submit Job](../images/ze/ZE-SubmitJobConfirm.gif) + +To configure confirmation settings for submitting a job: + +1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. + +2. Select the **User** or **Workspace** tab, depending on the settings you want to update. +3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**. +4. In the **Jobs: Confirm Submission** section, open the drop-down menu to select a different confirmation setting. + - If enabled, a confirmation dialog displays when a job matching the selected option is submitted. + +## Modifying level of detail included in logs + +To define the level of detail included in log files: + +1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. + +2. Select the **User** or **Workspace** tab, depending on the settings you want to update. +3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**. +4. In the **Logger** section, open the drop-down menu to select a different detail setting. diff --git a/docs/user-guide/ze-install-uninstall-ze.md b/docs/user-guide/ze-install-uninstall-ze.md new file mode 100644 index 0000000000..e704aa8a1c --- /dev/null +++ b/docs/user-guide/ze-install-uninstall-ze.md @@ -0,0 +1,50 @@ +# Uninstalling Zowe Explorer + +You can uninstall Zowe™ Explorer from Visual Studio Code (VS Code) if you no longer need to use it. + +:::info Required roles: systems administrator +::: + +:::warning Important +The uninstall process does not delete the profiles and credentials that you created when using the product from your computer. To delete the profiles from your computer, delete them before you uninstall Zowe Explorer. +::: + +## Uninstalling the Zowe Explorer VS Code extension + +Uninstall Zowe Explorer once any installed Zowe Explorer extensions have already been removed. See [Uninstalling Zowe Explorer CICS Extension](#uninstalling-zowe-explorer-cics-extension) and [Uninstalling Zowe Explorer FTP Extension](#uninstalling-zowe-explorer-ftp-extension) for instructions. + +1. Navigate to the **Extensions** icon on the **Activity Bar** in VS Code to display a list of installed extensions. +2. Find `Zowe Explorer` and click it. + + An Editor tab opens with the marketplace page for Zowe Explorer. + +3. Click **Uninstall** at the top of the Editor tab. +4. A reload may be required. If a button appears for reload, click it. + + Zowe Explorer is no longer installed. + +## Uninstalling Zowe Explorer CICS Extension + +To uninstall the Zowe Explorer CICS Extension: + +1. Navigate to the **Extensions** icon on the **Activity Bar** in VS Code to display a list of installed extensions. +2. Find `Zowe Explorer for IBM CICS` and click it. + + An Editor tab opens with the marketplace page for Zowe Explorer CICS Extension. +3. Click **Uninstall** at the top of the Editor tab. +4. A reload may be required. If a button appears for reload, click it. + + Zowe Explorer CICS Extension is no longer installed. + +## Uninstalling Zowe Explorer FTP Extension + +To uninstall the Zowe Explorer FTP Extension: + +1. Click the **Extension** icon on the **Activity Bar** in VS Code to display a list of installed extensions. +2. Find `Zowe Explorer FTP Extension` and click it. + + An Editor tab opens with the marketplace page for Zowe Explorer FTP Extension. +3. Click **Uninstall** at the top of the Editor tab. +4. A reload may be required. If a button appears for reload, click it. + + Zowe Explorer FTP Extension is no longer installed. diff --git a/docs/user-guide/ze-install-verify-your-installation.md b/docs/user-guide/ze-install-verify-your-installation.md new file mode 100644 index 0000000000..eaf6d8f42a --- /dev/null +++ b/docs/user-guide/ze-install-verify-your-installation.md @@ -0,0 +1,18 @@ +# Verifying your Zowe Explorer installation + +Verify that Zowe Explorer has been installed successfully by searching data sets to test your connection to z/OSMF. + +:::info Required roles: systems administrator, DevOps architect +::: + +## Using your profile to search data sets + +1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. +2. Click the **Search** icon. +3. Use the **input box** field to enter your username and password when prompted. +4. Select the **+ Create a new filter** option. +5. Enter the criteria to filter search results. + + If Zowe Explorer is able to connect with z/OSMF and the user credentials are valid, the filtered data sets display in the **DATA SETS** tree view. + + If there is a problem with the z/OSMF connection and/or user credentials, an error displays. See [Troubleshooting Zowe Explorer](https://docs.zowe.org/stable/troubleshoot/ze/troubleshoot-ze.md) for possible next steps. \ No newline at end of file diff --git a/docs/user-guide/ze-install-zowe-explorer-cics-ext.md b/docs/user-guide/ze-install-zowe-explorer-cics-ext.md index 165eaff952..62c9f03741 100644 --- a/docs/user-guide/ze-install-zowe-explorer-cics-ext.md +++ b/docs/user-guide/ze-install-zowe-explorer-cics-ext.md @@ -1,48 +1,36 @@ -# Zowe Explorer CICS Extension -## Installing +# Installing Zowe Explorer CICS Extension +## Installation methods -You can install or update the extension from Visual Studio Code Extensions or from a VSIX file. +Install or update the Zowe Explorer CICS Extension from Visual Studio Code Extensions or from a `VSIX` file. ### Installing from Visual Studio Code Extensions -1. Navigate to **Extensions** tab of your VS Code application. +1. Select the **Extensions** tab on the **Side Bar** of the VS Code application. -2. Search for `Zowe Explorer for IBM CICS` and click it. +2. Search for `Zowe Explorer for IBM CICS` and select the matching search result. -3. Click **Install** at the top of the page. +3. Click the **Install** button at the top of the **Editor** page. - If Zowe Explorer is not installed, this automatically installs it for you as part of the installation. + The extension is installed. If Zowe Explorer is not already installed, it also installs automatically. -### Installing from a VSIX file +### Installing from a `VSIX` file -Before you install Zowe Explorer CICS Extension from a VSIX file, ensure that Zowe Explorer is installed. Zowe Explorer is a required dependency. For more information, see [Installing Zowe Explorer](https://docs.zowe.org/stable/user-guide/ze-install#installing). +Before you install Zowe Explorer CICS Extension from a `VSIX` file, ensure that Zowe Explorer is installed. Zowe Explorer is a required dependency. See [Installing Zowe Explorer](../user-guide/ze-install.md#installing-zowe-explorer) for instructions.. -If Zowe Explorer is installed, you can install Zowe Explorer CICS Extension from a VSIX file. +If Zowe Explorer is installed, you can install Zowe Explorer CICS Extension from a `VSIX` file. -1. Visit the [download site](https://github.com/zowe/cics-for-zowe-client). Select the **Latest** button, which directs to a page that includes the latest version of `.vsix` file. Download it to your PC. +1. Go to the [Zowe Explorer for IBM CICS Extension download](https://github.com/zowe/cics-for-zowe-client) site. Select the **Latest** button, which directs to a page that includes the latest version of the `.vsix` file. Download it to your PC. ![Download Zowe CICS Explorer](../images/ze-cics/cics-latest-vsix.png) -2. Open the Extensions icon in the side bar, navigate to the **...** menu, press **Install from VSIX ...** and select the downloaded `Zowe.cics-extension-for-zowe-2.x.x.vsix` file. +2. Open the Extensions icon in the **Side Bar**, navigate to the **...** menu, select **Install from VSIX ...** and select the downloaded `Zowe.cics-extension-for-zowe-3.x.x.vsix` file. ![Installing Zowe CICS Explorer](../images/ze-cics/zowe-cics-explorer-install.gif) -The following message indicates that the extension is installed successfully. + The following message indicates that the extension is installed successfully. -![Zowe CICS Explorer install completed](../images/ze-cics/info-message-install-completed.png) + ![Zowe CICS Explorer install completed](../images/ze-cics/info-message-install-completed.png) -The Zowe Explorer pane shows tree views for **Data Sets**, **Unit System Services (USS)** and **Jobs**, and a new view for **CICS**. + The Zowe Explorer pane shows tree views for **Data Sets**, **Unit System Services (USS)** and **Jobs**, and a new view for **CICS**. -![CICS tree in Zowe pane](../images/ze-cics/cics-tree-in-zowe-pane.png) - -## Uninstalling - -To uninstall the Zowe Explorer CICS extension from the VS Code Extensions tab: - -1. Navigate to the **Extensions** tab of the VS Code application. - -2. Find `Zowe Explorer for IBM CICS` and click it. - -3. A panel opens. Click **Uninstall** at the top of the page. - -4. A reload may be required. If a button appears for reload, click it and the extension is no longer installed. + ![CICS tree in Zowe pane](../images/ze-cics/cics-tree-in-zowe-pane.png) diff --git a/docs/user-guide/ze-install.md b/docs/user-guide/ze-install.md index d4368a6e53..2e728d010f 100644 --- a/docs/user-guide/ze-install.md +++ b/docs/user-guide/ze-install.md @@ -1,139 +1,103 @@ -# Visual Studio Code (VS Code) Extension for Zowe +# Installing and updating Zowe Explorer -codecov -slack +codecov +slack -The Zowe Explorer extension for Visual Studio Code (VS Code) modernizes the way developers and system administrators interact with z/OS mainframes, and lets you interact with data sets, USS files, and jobs. +:::info Required roles: systems administrator +::: -Install the extension directly to [VSCode](https://code.visualstudio.com/) to enable the extension within the GUI. Working with data sets and USS files from VSCode can be more convenient than using 3270 emulators, and complements your Zowe CLI experience. The extension provides the following benefits: +Install Zowe Explorer directly to [Visual Studio Code](https://code.visualstudio.com/) to enable the extension within the GUI. + +Working with data sets and USS files from VS Code can be more convenient than using 3270 emulators, and complements your Zowe CLI experience. The extension provides the following benefits: - Enables you to create, modify, rename, copy, and upload data sets directly to a z/OS mainframe. - Enables you to create, modify, rename, and upload USS files directly to a z/OS mainframe. - Provides a more streamlined way to access data sets, USS files, and jobs. - Lets you create, edit, and delete Zowe CLI `zosmf` compatible profiles. -**Note:** Zowe Explorer is a subcomponent of [Zowe](https://zowe.org/home/). The extension demonstrates the potential for plug-ins powered by Zowe. - -## Software Requirements - -Ensure that you meet the following prerequisites before you use the extension: - -- Get access to z/OSMF. -- Install [Visual Studio Code](https://code.visualstudio.com/). -- Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](https://docs.zowe.org/stable/user-guide/systemrequirements-zosmf#z-os-requirements). -- Create a Zowe CLI `zosmf` profile so that the extension can communicate with the mainframe. -- For development, install [Node.js](https://nodejs.org/en/download/) v14.0 or later. - -### Profile notes: +:::note -- You can use existing Zowe CLI `zosmf` profiles created with Zowe CLI v.2.0.0 or later. +Zowe Explorer is a subcomponent of [Zowe](https://zowe.org/home/). The extension demonstrates the potential for plug-ins powered by Zowe. -- Zowe CLI `zosmf` profiles that are created in Zowe Explorer can be interchangeably used in Zowe CLI. - -- *Optionally*, you can continue using Zowe CLI V1 profiles with Zowe Explorer. For more information, see [Working with Zowe Explorer profiles](https://docs.zowe.org/stable/user-guide/ze-profiles#working-with-zowe-explorer-profiles). +::: ## Installing Zowe Explorer -Use the following steps to install Zowe Explorer: +### Installing from VS Code Extensions + +To install Zowe Explorer: -1. Address [the software requirements](#software-requirements). -2. Open Visual Studio Code, and navigate to the **Extensions** tab on the **Activity Bar**. +1. Address [the system requirements](#system-requirements). +2. Open VS Code, and navigate to the **Extensions** tab on the **Activity Bar**. 3. Type `Zowe Explorer` in the **Search** field. - - Zowe Explorer appears in the list of extensions in the **Side Bar**. + `Zowe Explorer` appears in the list of extensions in the **Side Bar**. 4. Click the green **Install** button to install the extension. -5. Restart Visual Studio Code. +5. Restart VS Code. The extension is now installed and available for use. -* **Note:** For information about how to install the extension from a `VSIX` file and run system tests on the extension, see the [Developer README](https://github.com/zowe/zowe-explorer-vscode#build-locally). - -You can also watch the following videos to learn how to get started with Zowe Explorer, and work with data sets. - - +### Installing from a `VSIX` file - +For information about how to install the extension from a `VSIX` file and run system tests on the extension, see the [Developer README](https://github.com/zowe/vscode-extension-for-zowe#build-locally). -## Configuring Zowe Explorer +## Changing the installed version of Zowe Explorer -Configure Zowe Explorer in the settings file of the extension. +Depending on their circumstances, developers might want to run a specific version of Zowe Explorer. -To access the extension settings, follow these steps: +:::important -1. Click the **Settings** icon at the bottom of the **Activity Bar**. +Releases older than Zowe Explorer v2.10 do not support secure credentials in Visual Studio Code v1.83+ due to the removal of the keytar library from VS Code. -2. Select the **Settings** option. -3. Open the **Extension** option listed in the **Commonly Used** menu. -4. Select **Zowe Explorer** to access its settings. -5. Scroll the list to find the setting that needs modification. +::: -### Modifying creation settings for data sets, USS files, and jobs +To install a particular version on VS Code: -Follow these steps: +1. Refer to [Installing Zowe Explorer](#installing-zowe-explorer) to install Zowe Explorer for Visual Studio Code if not already installed. +2. In VS Code, select the **Extensions** tab on the **Activities Bar** to display a list of installed extensions. +3. In the **Side Bar**, click the **Manage** icon next to Zowe Explorer to open a dropdown menu that lists available options. +4. Select **Install Another Version…** to open a dropdown menu that lists previous versions of Zowe Explorer. +5. Click the version of Zowe Explorer you want to install. -1. In Zowe Explorer settings, scroll to a data set, USS file, or job setting type. -2. Click the setting's corresponding **Edit in settings.json** link. +#### Preventing automatic updates to retain a specific version - This opens the `settings.json` file in an **Editor** tab. (The suggestions widget also opens if the functionality is enabled.) +By default, VS Code automatically updates extensions as new versions are released. Refer to the following steps to prevent automatic updates: -3. Edit the settings in the file as needed. -4. Save the file to keep changes. - - ![Configure Zowe settings](../images/ze/ZE-Configuration2.gif) - -### Modifying temporary file location settings - -Change the default folder location where temporary files are stored with the following steps: - - 1. Navigate to Zowe Explorer settings. - 2. Under the data set, USS, or jobs settings that you want to edit, click the **Edit in settings.json** link. - 3. Modify the following definition in the file: - - ```json - "zowe.files.temporaryDownloadsFolder": { - "folderPath": "/path/to/directory" - } - ``` - - Replace **/path/to/directory** with the new folder location. +1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. +2. Select the **User** or **Workspace** tab, depending on which settings you want to update. +3. In the Settings navigation menu, click **Features** and click **Extensions**. +4. In the **Auto Update** dropdown menu, select **None**. This prevents VS Code from updating your extensions automatically. -4. Save the file to keep the change. + VS Code is configured to stop updating your extensions, and Zowe Explorer extensions, automatically. -### Modifying the `Secure Credentials Enabled` setting +## Installing Zowe Explorer extensions -When environment conditions do not support the Zowe CLI built-in Credential Manager, change the `Secure Credentials Enabled` setting with the following steps: +### Installing from VS Code Extensions - 1. Navigate to Zowe Explorer settings. - 2. Scroll to **Security: Secure Credentials Enabled**. - 3. Deselect the checkbox to disable secure credentials. +1. Navigate to **Extensions** tab of your VS Code application. +2. In the **Search** field, enter the name of the Zowe Explorer extension. - When disabled, if the `autoStore` setting in the `zowe.config.json` file is set to *true*, z/OS credentials are stored as text in the file. + The name of the extension appears in the list that displays in the **Side Bar**. - If the `autoStore` setting is set to *false*, you are prompted for the missing credentials in Visual Studio Code. These are stored and used for the duration of the session. +3. Click **Install** at the top of the page. -### Setting confirmation requirements for submitting jobs + The selected extension is installed in VS Code. -Submitting the wrong job can risk potential problems on your server. This can happen when the user enters the wrong job or inadvertently selects the **Submit Jobs** option. -To help prevent this, enable the option to require confirmation before submitting a job. Once enabled, a dialog window asking for user confirmation displays when **Submit Jobs** is selected. +### Installing Zowe Explorer Extension for FTP from a `VSIX` file -![Confirm Submit Job](../images/ze/ZE-SubmitJobConfirm.gif) +1. Go to the [Zowe Explorer Extension for FTP download](https://open-vsx.org/extension/Zowe/zowe-explorer-ftp-extension) site. -To configure confirmation settings for submitting a job, follow these steps: +2. Select the `DOWNLOAD` button to download the latest version of the `.vsix` file. -1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. +3. Open the Extensions icon in the **Side Bar**, navigate to the **...** menu, select **Install from VSIX ...** and select the downloaded `Zowe.zowe-explorer-ftp-extension-3.x.x-next.` file. -2. Select the **User** or **Workspace** tab, depending on the settings you want to update. -3. In the Settings navigation menu, open the **Extensions** menu and click **Zowe Explorer**. -4. In the **Jobs: Confirm Submission** section, open the drop-down menu to select a different confirmation setting. - - If enabled, a confirmation dialog displays when a job matching the selected option is submitted. + A message displays to confirm the installation was successful. -## Relevant Information +4. Close and reopen VS Code to check that the notification message "Zowe Explorer was modified for FTP support" displays. -In this section you can find useful links and other information relevant to Zowe Explorer that can improve your experience with the extension. + Once installed, the notification displays every time you open VS Code to confirm that the FTP extension is available. -- For information about how to develop for Eclipse Theia, see [Theia README](https://github.com/zowe/zowe-explorer-vscode/wiki/Developing-for-Theia). -- For information about how to create a VSCode extension for Zowe Explorer, see [VSCode extensions for Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/wiki/Extending-Zowe-Explorer). +## Updating Zowe Explorer and Zowe Explorer extensions -- Visit the **#zowe-explorer** channel on [Slack](https://openmainframeproject.slack.com/) for questions and general guidance. +By default, VS Code automatically updates extensions as new versions are released. To stop automatic updates, see [Preventing automatic updates to retain a specific version](#preventing-automatic-updates-to-retain-a-specific-version). diff --git a/docs/user-guide/ze-override-tls-certs.md b/docs/user-guide/ze-override-tls-certs.md index 875ba5c95f..5e79a38d9a 100644 --- a/docs/user-guide/ze-override-tls-certs.md +++ b/docs/user-guide/ze-override-tls-certs.md @@ -1,9 +1,35 @@ # Overriding untrusted TLS certificates -If the CMCI connection uses a TLS certificate that does not exist in your PC's trust store, then by default the connection is rejected because the certificate could be from an unsafe site. +There are times when a user might want to override a rejected TLS certificate. -To override this behavior, set the `Only accept trusted TLS certificates` field to `False` on the form when creating or updating the profile. This is the same as setting `rejectUnauthorized=false` on the Zowe CICS CLI profile. +By default, if the CICS Management Client Interface (CMCI) connection uses a TLS certificate that does not exist in your PC's trust store, Zowe Explorer rejects the connection because the certificate could originate from an unsafe site. -If you define a profile to accept trusted TLS certificates only when the Zowe Explorer first connects, it detects the mismatch and display a message. You can select **Yes** to override the profile's setting to accept the untrusted certificate authority. +You might want to override this behavior if you are using certificates not signed by a recognized certificate-issuing authority. For instance, z/OSMF might only have certificates created on the mainframe, resulting in self-signed certificates. Zowe Explorer rejects these types of certificates by default as a security measure. -![Image that shows how to accept untrusted TLS certificate](../images/ze-cics/untrusted-cert.gif) +There are two ways to override a rejected TLS certificate. + +## Updating the CICS profile with Zowe Explorer + +1. Attempt the CMCI connection. + + Zowe Explorer rejects the TLS certificate and displays a pop-up message warning about the certificate. + +2. Select the **Yes** option on the warning. + + Zowe Explorer updates the `rejectUnauthorized` property in the respective CICS profile to `false` and updates the **CICS** tree with the modified profile. + + ![Image that shows how to accept untrusted TLS certificate](../images/ze-cics/untrusted-cert.gif) + +## Updating the CICS profile manually + +1. Expand the **CICS** tree in the Visual Studio Code **Side Bar**, and right-click a profile to open up the profile menu actions. + +2. Select the **Update Profile** option. + + The associated configuration file opens in an **Editor**. + +3. Edit the configuration file to set the `rejectUnauthorized` property in the respective CICS profile to `false`. + +4. Save the configuration file. + +5. Refresh the Zowe Explorer for IBM CICS extension. Either click the **Refresh** icon at the top of the **CICS** tree in the **Side Bar**, or select the `Zowe Explorer for IBM CICS: Refresh` option in the **Command Palette**. diff --git a/docs/user-guide/ze-profiles.md b/docs/user-guide/ze-profiles.md index 2888917205..0e67966bef 100644 --- a/docs/user-guide/ze-profiles.md +++ b/docs/user-guide/ze-profiles.md @@ -1,22 +1,19 @@ -# Zowe Explorer profiles +# Creating Zowe Explorer profiles After you install Zowe Explorer, you must have a Zowe Explorer profile to use all functions of the extension. -:::info -You can continue using Zowe V1 profiles with Zowe Explorer V2. See [Working with Zowe V1 profiles](#working-with-zowe-v1-profiles) for more information. +:::info Required roles: Systems administrator ::: -## Configuring Zowe V2 profiles +## Configuring Zowe profiles -Zowe V2 uses *team profiles* to simplify profile management by letting you edit, store, and share mainframe connection details in one location, a configuration file. +Zowe uses [team configuration](/appendix/zowe-glossary.md#team-configuration) to simplify profile management by letting you edit, store, and share mainframe connection details in one location, a configuration file. -You can use a text editor or an IDE to populate configuration files with the connection information for your mainframe services. By default, your *global* team configuration file is located in the `.zowe` home folder, whereas the *project* configuration file is located in the main directory of your project. - -You can create profiles that you use globally, given that the names of the globally-used profiles are different from your other profile names. +You can use a text editor or an IDE to populate configuration files with profiles, which contain the connection information for your mainframe services. By default, your *global* team configuration file is located in the `.zowe` folder in your home folder, whereas a *project* configuration file is located in the main directory of your project. :::note -When multiple profiles are available in Zowe CLI, project configuration takes precedence over global configuration. To learn more, see [How Zowe CLI uses configurations](../user-guide/cli-using-understand-profiles-configs). +When multiple profiles with the same name are available in Zowe Explorer, project configuration takes precedence over global configuration. To learn more, see [How Zowe CLI uses configurations](../user-guide/cli-using-understand-profiles-configs). ::: @@ -29,7 +26,7 @@ Create a team configuration file: 3. Click the **+** icon. 4. Select **Create a New Team Configuration File**. 5. If no workspace is open, a global configuration file is created. If a workspace is open, choose either a global configuration file or a project-level configuration file. -6. Edit the config file to include the host information and save the file. +6. Edit the configuration file to include the host information and save the file. 7. Refresh Zowe Explorer by either clicking the button in the notification message shown after creation, `alt` + `z`, or the `Zowe Explorer: Refresh Zowe Explorer` command palette option. Your team configuration file appears either in your `.zowe` folder if you choose the global configuration file option, or in your workspace directory if you choose the project-level configuration file option. The notification message that displays in VS Code after the configuration file creation includes the path of the file created. @@ -38,32 +35,32 @@ Create a team configuration file: Change profile validations and edit the profiles in your project or global configuration files: -1. Right-click on your profile. +1. Right-click on a profile icon in the **DATA SETS**, **USS**, or **JOBS** tree view. 2. Select the **Manage Profile** option to choose from several authentication and profile management actions for the credentials detected in your Zowe Explorer session. Authentication options display according to the detected credentials: - **Add Credentials** to store a username and password. Credentials are stored securely in the credential vault when the team or user profile has values in the `secure` array. Otherwise, the credentials are stored as plain text in the profile. - **Update Credentials** to update the username and password. Credentials are stored securely in the credential vault when the team or user profile has values in the `secure` array. Otherwise, the credentials are stored as plain text in the profile. - - **Log in to authentication service** to obtain a new authentication token when the token in the profile is no longer valid or is missing - - **Log out of authentication service** to invalidate the token in the profile so a valid token is not stored + - **Log in to authentication service** to obtain a new authentication token when the token in the profile is no longer valid or is missing. + - **Log out of authentication service** to invalidate the token in the profile so a valid token is not stored. Profile management options displays for specific profile actions: - - **Disable/Enable Profile Validation** to disable or enable validation of access to z/OSMF - - **Edit Profile** to update profile information in an **Editor** tab - - **Hide Profile** to hide the profile name from the tree view - - **Delete Profile** to manually remove the profile information in an **Editor** tab + - **Disable/Enable Profile Validation** to disable or enable validation of access to z/OSMF. + - **Edit Profile** to update profile information in an **Editor** tab. + - **Hide Profile** to hide the profile name from the tree view. + - **Delete Profile** to manually remove the profile information in an **Editor** tab. 3. Refresh the view by clicking the **Refresh** icon in the **DATA SETS**, **USS**, or **JOBS** tree view. You successfully edited your configuration file. -### Sample profile configuration +### Example profiles configuration -View the profile configuration sample. In the sample, the default `lpar1.zosmf` profile will be loaded upon activation. +Review the profile examples below to understand how settings are organized in a configuration file. In this example, the default `lpar1.zosmf` profile is loaded upon activation. -You can use the sample to customize your profile configuration file. Ensure that you edit the `host` and `port` values before you work in your environment. +You can use this example to customize your own profiles in a configuration file. Ensure that you edit the `host` and `port` values before you work in your environment. ```json { @@ -106,7 +103,7 @@ You can use the sample to customize your profile configuration file. Ensure that } } }, - "my_base": { + "project_base": { "type": "base", "properties": { "rejectUnauthorized": false @@ -119,121 +116,43 @@ You can use the sample to customize your profile configuration file. Ensure that "tso": "lpar1.tso", "ssh": "lpar1.ssh", "zftp": "lpar1.zftp", - "base": "my_base" + "base": "project_base" }, "plugins": [] } ``` -## Working with Zowe V1 profiles - -:::info - -Zowe V1 profiles are defined by having one yaml file for each user profile. - -::: - -### Managing Zowe V1 profiles - -You must have a `zosmf` compatible profile before you can use Zowe Explorer. You can set up a profile to retain your credentials, host, and port name. In addition, you can create multiple profiles and use them simultaneously. - -To create a `zosmf` compatible profile: - -1. Navigate to the explorer tree. -2. Click the **+** button next to the **DATA SETS**, **USS**, or **JOBS** bar. - - :::note - - If you already have a profile, select it from the drop-down menu in the **picker** field. - - ::: - -3. Select the **Create a New Connection to z/OS** option. - - :::note - - When you create a new profile, username and password fields are optional. However, the system prompts you to specify your credentials when you use the new profile for the first time. - - ::: - -4. Follow the instructions, and enter all required information to complete the profile creation. - - New Connection - - You successfully created a Zowe CLI `zosmf` profile. Now you can use all the functionalities of the extension. - -To edit a profile: - -1. Right-click the profile and select **Update Profile** option. - -2. Edit the profile information in the **picker** field. - - Edit a Profile - -To hide a profile from the tree view, right-click the profile and select the **Hide Profile** option. - -To delete a profile from your system, right-click the profile and select the **Delete Profile** option. - -### Validating profiles - -Zowe Explorer includes the profile validation feature that helps to ensure that z/OSMF is accessible and ready for use. If a profile is valid, the profile is active and can be used. By default, the feature is automatically enabled. You can disable the feature by right-clicking on your profile and selecting the **Disable Validation for Profile** option. Alternatively, you can enable or disable the feature for all profiles in the VS Code settings. - -1. Navigate to the VS Code settings. -2. Open Zowe Explorer Settings. -3. Enable or disable the automatic validation of profiles option. -4. Restart VS Code. - -### Using base profiles and tokens with existing profiles +## Using base profiles and tokens with existing profiles As a Zowe user, you can leverage the base profile functionality to access multiple services through Single Sign-on. Base profiles enable you to authenticate using Zowe API Mediation Layer (API ML). You can use base profiles with more than one service profile. For more information, see [Base Profiles](../user-guide/cli-using-using-profiles-v1.md#base-profiles). -Before you log in and connect your service profile, ensure that you have [Zowe CLI](../user-guide/cli-install-cli-checklist.md) v6.16 or higher installed. - -#### Accessing services through API ML using SSO - -Connect your service profile with a base profile and token: - -1. Open Zowe CLI and issue the following command: - - ``` - zowe auth login apiml - ``` +::: note -2. Follow the onscreen instructions to complete the login process. +If you want to access services through multiple API ML gateways, the same following steps apply. However, you must first edit your configuration file to follow a specific structure. - A local base profile is created that contains your token. For more information about the process, see [Token Management](../user-guide/cli-using-integrating-apiml.md#how-token-management-works). - -3. Run Zowe Explorer and click the **+** icon. +Review [Accessing services for multiple API ML instances](../user-guide/cli-using-creating-profiles.md#accessing-services-for-multiple-api-ml-instances) to see how profiles are structured in the configuration file. -4. Select the profile you use with your base profile with the token. - - The profile appears in the tree and you can now use this profile to access z/OSMF via the API Mediation Layer. - -For more information, see [Integrating with API Mediation Layer](../user-guide/cli-using-integrating-apiml.md). - -#### Logging in to the Authentication Service - -If the token for your base profile is no longer valid, you can log in again to get a new token with the **Log in to Authentication Service** feature. - -:::note +::: -- The feature is only available for base profiles. -- The feature supports only API Mediation Layer at the moment. Other extenders may use a different authentication service. +### Accessing services through API ML using SSO -::: +Connect your service profile with a base profile and token: -1. Open Zowe Explorer. -2. Right-click your profile. -3. Select the **Log in to Authentication Service** option. +1. Right-click on the profiles you want to connect through with the API ML. +2. Select the **Manage Profile** option from the context menu +3. In the **Quick Pick**, select **Log in to Authentication Service**. +4. In the next **Quick Pick** menu, select the appropriate option for authenticating to the API ML +5. Answer the proceeding prompts for information. - You are prompted to enter your username and password beforehand. + Tokens are stored either in a base profile or, if using a nested profile structure, in a parent profile that has a secure array that contains `tokenValue`. If not using a nested profile structure, and if a base profile does not exist, a base profile is created that contains your token. For more information about API integration and using tokens, see [Token Management](../user-guide/cli-using-integrating-apiml.md#how-token-management-works). - The token is stored in the corresponding base profile. +### Logging out of the API ML using SSO -If you do not want to store your token, request from the server to end the session of your token. Use the **Log out from Authentication Service** feature to invalidate the token. +If you do not want to store your token, request the server to revoke your token and delete it from your local profile. Use the **Log out from Authentication Service** feature to invalidate the token. 1. Open Zowe Explorer. 2. Right-click your profile. -3. Select the **Log out from Authentication Service** option. +3. Select the **Manage Profile** option. +4. In the **Quick Pick**, select the **Log out from Authentication Service** option. Your token has been successfully invalidated. diff --git a/docs/user-guide/ze-usage-tips.md b/docs/user-guide/ze-usage-tips.md index 49ab53a35e..2307f8501e 100644 --- a/docs/user-guide/ze-usage-tips.md +++ b/docs/user-guide/ze-usage-tips.md @@ -3,27 +3,35 @@ Make the best use of Zowe Explorer with the following tips. ## Data sets, USS, and jobs persistence settings -You can store any data sets, USS files, or jobs permanently in the **Favorites** tab. Right-click on a data set, USS file, or job and click **Add Favorite**. + +Store any data sets, USS files, or jobs permanently in the **Favorites** tab. Right-click on a data set, USS file, or job and click **Add Favorite**. ## Identify syntax errors with a syntax highlighter -Zowe Explorer supports a syntax highlighter for data sets. To enhance the experience of using the extension, you can download an extension that highlights syntax. + +Zowe Explorer supports syntax highlighting for data sets and USS files. To enable syntax highlighting, download a Visual Studio Code extension that provides syntax highlighting. ## Configure the detected language of a file or data set -You can configure Visual Studio Code to use a specific language for a particular file extension type. This prevents the language for a file or data set opened in Zowe Explorer to be detected incorrectly. To set file associations, see [Add a file extension to a language](https://code.visualstudio.com/docs/languages/overview#_add-a-file-extension-to-a-language). +Configure Visual Studio Code to use a specific language for a particular file extension type. This prevents the language for a file or data set opened in Zowe Explorer from being detected incorrectly. To set file associations, see [Add a file extension to a language](https://code.visualstudio.com/docs/languages/overview#_add-a-file-extension-to-a-language). -## Edit a profile -You can edit existing profiles listed in the **Side Bar** by clicking the profile's **Edit** icon (next to the **Search** icon). The feature lets you modify the information inside your profile. +## Manage a profile + +Manage existing profiles listed in the **Side Bar**. Right-click the profile and select **Manage Profile** in the context menu to see a list of options in the **Quick Pick**. Choose the option desired for managing the profile. ## Delete a profile -In Zowe V1, you can permanently delete profiles by right-clicking the profile and selecting the **Delete Profile** option. The feature deletes the profile from your `.zowe` folder. In Zowe V2, right-click the profile, and select **Delete Profile** to open the configuration file and manually delete the profile. -:::tip -Alternatively, you can delete a profile by using the VS Code **Command Palette**. Press `F1` on your keyboard, then select the **Zowe Explorer: Delete a Profile Permanently** option. In Zowe V1, you select the profile to delete. In Zowe V2, the configuration file opens for you to delete the profile manually. -::: +Delete a profile displayed in the **Side Bar**. Right-click the profile and select **Manage Profile** in the context menu to see a list of options in the **Quick Pick**. Select **Delete Profile** to open the associated configuration file and manually delete the profile. ## Hide a profile -You can hide a profile from the **Side Bar** by right-clicking the profile and selecting the **Hide Profile** option. If necessary, add the profile back by clicking the **+** icon on the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar. + +Hide a profile from the **Side Bar**. Right-click the profile, select the **Manage Profile** option in the context menu, and then click **Hide Profile** in the **Quick Pick**. If necessary, add the profile back by clicking the **+** icon on the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar. + +## Multi-select functionality + +Apply an action to multiple objects at the same time for increased efficiency. This is available in actions such as **Copy** (data sets, USS), **Delete**, and **Add to Favorites**. + +Use the `Shift` key to select a continuous range of items, or select multiple items by pressing the `Ctrl` key as you select each item. Once the items are selected, right-click to choose the action from the menu. ## Open recent members -Zowe Explorer lets you open a list of members you have previously worked on. You can access the list by pressing `Ctrl`+`Alt`+`R` or `Command`+`Option`+`R`. + +Zowe Explorer lets you open a list of members you have previously worked on. Access the list by pressing `Ctrl`+`Alt`+`R` or `Command`+`Option`+`R`. diff --git a/docs/user-guide/ze-usage.md b/docs/user-guide/ze-usage.md index ac48cf28bd..1ed928777f 100644 --- a/docs/user-guide/ze-usage.md +++ b/docs/user-guide/ze-usage.md @@ -1,79 +1,22 @@ # Using Zowe Explorer -Review this section to familiarize yourself with Zowe Explorer and make the best use of its available options and features. - -## Supported operating systems, environments, and platforms - -### Operating systems - -- MacOS 10.15 (Catalina), 11 (Big Sur), 12 (Monterey) -- Unix-like: - - [CentOS](https://www.centos.org/) 8+ - - [RHEL](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) 8+ - - [Ubuntu](https://ubuntu.com/) 20.04+ -- Windows 10+ - -### Integrated development environments: - -- [VS Code](https://code.visualstudio.com/) 1.53.2+ -- [Eclipse Che](https://www.eclipse.org/che/) -- [Red Hat CodeReady Workspaces](https://www.redhat.com/en/technologies/jboss-middleware/codeready-workspaces) -- [Theia](https://theia-ide.org/) 1.18+ - -:::note - -Zowe Explorer is compatible with Theia 1.18.0 or higher. However, we recommend using a [Theia community release](https://theia-ide.org/releases/) as Zowe Explorer could experience possible unexpected behaviors with the latest Theia releases. - -::: +Familiarize yourself with Zowe Explorer and make the best use of its available options and features. ## Using Zowe Explorer in remote environments -As of Zowe Version 2.11, Zowe Explorer and the Zowe Explorer API no longer use `node-keytar`, which was used to manage mainframe credentials. This change might cause some users issues when trying to interact with remote environments. +As of Zowe Version 2.11, Zowe Explorer and the Zowe Explorer API no longer use `node-keytar`, which was used to manage mainframe credentials. This change might cause issues for some users when trying to interact with remote environments. See [Usage in Remote Environments](https://github.com/zowe/zowe-explorer-vscode/wiki/Usage-in-Remote-Environments) to learn more about how to resolve credential errors. -## Using a specific version of Zowe Explorer - -Depending on their circumstances, developers might want to keep using a specific version of Zowe Explorer. To ensure that a particular version remains installed on VS Code, refer to the procedure for one of the following scenarios: - -### Zowe Explorer is installed - -#### **Preventing automatic version updates** - -By default, VS Code automatically updates extensions as new versions are released. Refer to the following steps to prevent automatic updates: - -1. On the VS Code menu bar, click **File**, **Preferences**, and click **Settings** to display the Settings editor. - -2. Select the **User** or **Workspace** tab, depending on which settings you want to update. -3. In the Settings navigation menu, click **Features** and click **Extensions**. -4. In the **Auto Update** dropdown menu, select **None**. This prevents VS Code from updating your extensions automatically. - -#### **Installing a specific previous version** - -1. Select the **Extensions** tab on the **Activities Bar** to display a list of installed extensions. - -2. In the **Side Bar**, click the **Gear** icon next to Zowe Explorer to open a dropdown menu that lists available options. -3. Select **Install Another Version…** to open a dropdown menu that lists previous versions of Zowe Explorer. -4. Click the version of Zowe Explorer you want to install. - -### Zowe Explorer is not installed - -If Zowe Explorer is not installed, you can install the current release of the extension and then revert to a previous version. - -#### **Installing a previous version of Zowe Explorer** - -1. Select the **Extensions** tab on the **Activities Bar** to display the **Search Extensions in Marketplace** field. -2. In the **Side Bar**, search for `Zowe Explorer`. Click the **Install** button on the Zowe Explorer search result item. This opens a Zowe Explorer tab in the **Editor** area. +## Credentials in Zowe Explorer - ![Zowe Explorer search result item](../images/ze/ZE-zowe-explorer-result-item.jpg "Zowe Explorer search result item") -

+When working in remote or virtualized environments — such as Eclipse Che, GitHub Codespaces, CodeReady Workspaces — administrators may find the configuration process for storing credentials securely too cumbersome. Instead, they might prefer to rely on the security tools integrated with these environments, such as file access permissions. To do so, administrators need to disable Zowe Explorer's credential management functionality. -3. Click the **Down** arrow next to the **Uninstall** button. Select **Install Another Version…** to open a dropdown menu that lists previous versions of Zowe Explorer. -4. Search for and click the version of Zowe Explorer you want to install. +:::note -## Credentials in Zowe Explorer +Consider other options. Use the [Kubernetes Secrets plug-in for Zowe CLI and Zowe Explorer](https://github.com/zowe/zowe-cli-secrets-for-kubernetes/blob/main/README.md) as an option for storing credentials in a Kubernetes containerized environment, or create your own [Custom Credential Managers in Zowe Explorer and Zowe CLI](https://medium.com/zowe/custom-credential-managers-in-zowe-explorer-b37faeee4c29). -When working in remote or virtualized environments — such as Eclipse Che, GitHub Codespaces, CodeReady Workspaces — administrators may find the configuration process for storing credentials securely too cumbersome. Instead, they may prefer to rely on the security tools integrated with these environments, such as file access permissions. To do so, administrators need to disable Zowe Explorer's credential management functionality. +::: ### Preventing Zowe Explorer from storing credentials @@ -82,25 +25,19 @@ When working in remote or virtualized environments — such as Eclipse Che, 2. Find the `autoStore` property. 3. Set the `autoStore` property to `false`. - Credentials will be stored on a per profile/per panel basis until one of the following takes place: + Credentials are stored on a per profile/per panel basis until one of the following takes place: - - Data Sets/USS/Jobs tree refresh caused by an update to the `zowe.config.json` file + - **Data Sets**/**USS**/**Jobs** tree refresh caused by an update to the `zowe.config.json` file - Zowe Explorer refresh in the **Command Palette** - Reload of the Visual Studio Code window - Closing and reopening the VS Code window ### Disabling Secure Credential Storage of credentials -#### Zowe Explorer v2 +#### Zowe Explorer V2 and V3 1. Navigate to **Settings** in VS Code. 2. In Zowe Explorer Settings, uncheck the **Zowe Security: Secure Credentials Enabled** checkbox. When disabled and `autoStore` is set to True in `zowe.config.json`, z/OS credentials are stored as plain text in the configuration file. - -#### Zowe Explorer v1 - -1. Navigate to **Settings** in VS Code. - -2. In Zowe Explorer Settings, leave the **Zowe Security: Credential Key** field blank. diff --git a/docs/user-guide/ze-use-cases.md b/docs/user-guide/ze-use-cases.md index 08a271dece..72a02e7064 100644 --- a/docs/user-guide/ze-use-cases.md +++ b/docs/user-guide/ze-use-cases.md @@ -8,7 +8,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. 2. Click the **Search** icon. -3. Use the **picker** field to select or enter the patterns you want to apply as filters. +3. Use the **Quick Pick** field to select or enter the patterns you want to apply as filters. The data sets that match your pattern(s) display in the **Side Bar**. @@ -20,7 +20,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. 2. Click the **Search** icon. -3. In the **picker** field, enter or select a search pattern in the `HLQ.ZZZ.SSS(MEMBERNAME)` format to filter out and display the specified member in the **Side Bar**. +3. In the **Quick Pick** field, enter or select a search pattern in the `HLQ.ZZZ.SSS(MEMBERNAME)` format to filter out and display the specified member in the **Side Bar**. ![View Data Set With Member Pattern](../images/ze/ZE-member-filter-search.gif) @@ -33,7 +33,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**, and select the data set you want to rename. 2. Right-click the data set and select the **Rename Data Set** option. -3. Enter the new name of the data set in the **picker** field. +3. Enter the new name of the data set in the **input box**. ![Rename Data Set](../images/ze/ZE-rename.gif) @@ -42,7 +42,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**, and select the member you want to copy. 2. Right-click the member and select the **Copy Member** option. 3. Right-click the data set where the member is to be contained and select the **Paste Member** option. -4. In the **picker** field, enter the name of the copied member. +4. In the **input box**, enter the name of the copied member. ![Copy Data Set Member](../images/ze/ZE-copy-member.gif) @@ -73,9 +73,9 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**. 2. Right-click the profile you want to create a data set with and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create and press `Enter`. -5. Select **Edit Attributes** in the **picker** drop-down menu and press `Enter`. +3. Enter a name for your data set in the **input box** and press `Enter`. +4. From the **Quick Pick** menu, select the data set type that you want to create and press `Enter`. +5. Select **Edit Attributes** in the **Quick Pick** menu and press `Enter`. The attributes list for the data set displays. You can edit the following attributes: @@ -113,7 +113,7 @@ The following use cases demonstrate the various functionalities available in Zow - Volume Serial -6. Select the attribute you want to edit, provide the value in the **picker** field, and press `Enter`. +6. Select the attribute you want to edit, provide the value in the **input box**, and press `Enter`. 7. (Optional) Edit the parameters of your data set. 8. Select the **+ Allocate Data Set** option to create the data set and list it in the **Side Bar**. @@ -124,11 +124,11 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**. 2. Right-click on the profile where you want to create a data set and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create. +3. Enter a name for your data set in the **input box** and press `Enter`. +4. From the **Quick Pick** menu, select the data set type that you want to create. 5. Select **+Allocate Data Set** to create your data set. 6. In the **Side Bar**, right-click your newly-created data set and select **Create New Member**. -7. Enter a name for your new data set member in the **picker** field and press **Enter**. +7. Enter a name for your new data set member in the **input box** and press **Enter**. The member is created and opened in an **Editor** tab. ### Deleting a data set member and a data set @@ -136,7 +136,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**. 2. Open the profile and data set containing the member you want to delete. 3. Right-click the member and select **Delete Member**. -4. Confirm the deletion by selecting **Delete** on the **picker** drop-down menu. +4. Confirm the deletion by selecting **Delete** on the **Quick Pick** menu. 5. To delete a data set, right-click the data set and select **Delete Data Set**, then confirm the deletion. **Note:** You can delete a data set before you delete its members. @@ -147,7 +147,7 @@ The following use cases demonstrate the various functionalities available in Zow 1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. 2. Select the **Search** icon. -3. In the **picker** field, enter or select a search pattern to filter search results in the **Side Bar**. +3. In the **Quick Pick** field, enter or select a search pattern to filter search results in the **Side Bar**. 4. Right-click a data set or member and select the **Show Attributes** option. This displays the attributes in an **Editor** tab. @@ -157,7 +157,7 @@ The following use cases demonstrate the various functionalities available in Zow ### Viewing and accessing multiple profiles simultaneously 1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. -2. Select the profiles from the **picker** drop-down to add them to the **Side Bar**. +2. Select the profiles from the **Quick Pick** menu to add them to the **Side Bar**. 3. Click the **Search** icon for each profile to search and select associated data sets. ![Add Profile](../images/ze/ZE-mult-profiles.gif) @@ -170,7 +170,7 @@ Filter partitioned data set members in the **DATA SETS** tree view by **Date Mod 1. In the **DATA SETS** tree, click on the **Filter** icon to the right of a profile, or right-click on a profile and select the **Filter PDS members…** option. - The filter selection menu appears in the **picker** field. + The filter selection menu appears in the **Quick Pick** field. 2. Select a filter type from the list of available options: - **Date Modified** - **User ID** @@ -185,7 +185,7 @@ Filter partitioned data set members in the **DATA SETS** tree view by **Date Mod 1. In the **DATA SETS** tree, right-click on a data set and select the **Filter PDS members…** option. - The filter selection menu appears in the **picker** field. + The filter selection menu appears in the **Quick Pick** field. 2. Select a filter type from the list of available options: - **Date Modified** - **User ID** @@ -204,8 +204,8 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 1. In the **DATA SETS** tree, click on the **Sort** icon to the right of a profile, or right-click on a profile and select the **Sort PDS members…** option. - The sorting selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. + The sorting selection menu appears in the **Quick Pick** field. +2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **Quick Pick** menu. 3. Select a sort type from the list of available options: - **Name** - **Date Modified** @@ -220,8 +220,8 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam #### Sorting members for a single data set 1. In the **DATA SETS** tree, right-click on a data set and select the **Sort PDS members…** option. - The sort selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. + The sort selection menu appears in the **Quick Pick** field. +2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **Quick Pick** menu. 3. Select a sort type from the list of available options: - **Name** - **Date Modified** @@ -247,7 +247,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 1. Expand **DATA SETS** in the **Side Bar**. 2. Right-click a data set and select the **Allocate Like (New File with Same Attributes)** option. -3. Enter the new data set name in the **picker** field and press `Enter`. +3. Enter the new data set name in the **input box** and press `Enter`. ![Allocate Like](../images/ze/ZE-allocate.gif) @@ -257,7 +257,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. 2. Hover over the profile you want to search and click the **Search** icon. -3. In the **picker** field, enter or select the path that you want as the root of your displayed tree and press `Enter`. +3. In the **Quick Pick** field, enter or select the path that you want as the root of your displayed tree and press `Enter`. All child files and directories of that path display in the **Side Bar**. @@ -278,7 +278,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 2. Select a USS file you want to rename. 3. Right-click the USS file and select the **Rename USS file** option. -4. In the **picker** field, change the name of the USS file and press `Enter`. +4. In the **input box**, change the name of the USS file and press `Enter`. ### Downloading, editing, and uploading existing USS files @@ -301,7 +301,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. 2. Right-click the directory where you want to add the new directory. -3. Select the **Create Directory** option and enter the directory name in the **picker** field. +3. Select the **Create Directory** option and enter the directory name in the **input box**. 4. Press `Enter` to create the directory. #### Creating a file @@ -309,7 +309,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam 1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. 2. Right-click the directory to which you want to add the new file. -3. Select the **Create File** option and enter the file name in the **picker** field. +3. Select the **Create File** option and enter the file name in the **input box**. 4. Press `Enter` to create the file. #### Deleting a file @@ -330,7 +330,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam ### Viewing and accessing multiple USS profiles simultaneously 1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**, and click the **+** icon. -2. Select or enter a profile in the **picker** drop-down menu to add it to the **Side Bar**. +2. Select or enter a profile in the **Quick Pick** drop-down menu to add it to the **Side Bar**. ![View Profiles](../images/ze/ZE-profile2.gif) @@ -360,7 +360,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam Alternatively, press the `F1` key to open the **Command Pallette**, then select the **Zowe Expolorer: Issue MVS Command** option. -3. In the **picker** field, enter a new command or select a saved command. +3. In the **Quick Pick** field, enter a new command or select a saved command. 4. Press `Enter` to execute the command. ![Issue a MVS command](../images/ze/ZE-Jobs-Issue-TSO-Command.gif) @@ -372,7 +372,7 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam Alternatively, press the `F1` key to open the **Command Pallette**, then select the **Zowe Explorer: Issue TSO Command** option. -3. In the **picker** field, enter a new command or select a saved command. +3. In the **Quick Pick** field, enter a new command or select a saved command. 4. Press `Enter` to execute the command. The output displays in the **Output** panel. diff --git a/docs/user-guide/ze-use-cics-resources.md b/docs/user-guide/ze-use-cics-resources.md index 0ffe5dd709..8a9249c0f8 100644 --- a/docs/user-guide/ze-use-cics-resources.md +++ b/docs/user-guide/ze-use-cics-resources.md @@ -3,83 +3,134 @@ Expand a CICS profile to see the region name, and expand the region to view its resources. - If the CICS profile is connected to a CMAS region that is part of a CICSPlex, the tree shows all of the regions managed by the CICSPlex. - -- If the CICS profile is for an SMSS region, then just one region is shown. Inactive regions in a plex are shown with an empty icon. +- If the CICS profile is for an SMSS region, then only one region displays. Inactive regions in a plex display with an empty icon. ## Showing and filtering resources in a region -Expand a CICS region to show folders for the resource types **Programs**, **Transactions**, and **Local Files**. Expand each type to show the resources. The number of resources in a resource tree appears in square brackets next to the tree name. +1. Expand the **CICS** tree in the **Side Bar** and navigate to a CICS region. + +2. Expand the CICS region to show folders for the **Programs**, **Transactions**, and **Local Files** resource types. + +3. Expand each resource type to view their resources. (The number of resources in a resource tree displays in square brackets next to the tree name.) -The list of resources is pre-filtered to exclude many of the IBM supplied ones to narrow the contents to just include user programs. + The list of resources is pre-filtered to exclude many of the IBM-supplied resources. This narrows the contents to include only user programs. -- Use the search icon against a resource type to apply a filter. You can enter an exact resource name or use wildcards. The search history is saved so you can recall previous searches. +4. Use the **Search** icon in a resource type to apply a filter. -- To reset the filter to its initial criteria, use the clear filter icon against the resource type. If you want to see all resources in a region (including IBM supplied ones), use __*__ as a filter. + Enter an exact resource name or use wildcards. The search history is saved so you can recall previous searches. + + To reset the filter to its initial criteria, use the **Clear** filter icon in the resource type. To see all resources in a region (including those supplied by IBM), use an `*` as a filter. -![Zowe CICS Explorer Filter](../images/ze-cics/region-filter.gif) + ![Zowe CICS Explorer Filter](../images/ze-cics/region-filter.gif) -**Tip:** To apply multiple filters, separate entries with a comma. You can append any filter with an __*__, which indicates wildcard searching. + ::: Tip + + To apply multiple filters, separate entries with a comma. Append a filter with an `*` to indicate wildcard searching. + + ::: ## Showing and filtering resources in a plex -Similar to filtering resources in a region, you can apply a filter on a all region resources in a plex. +Apply a filter on all region resources in a plex. + +1. Expand the **CICS** tree in the **Side Bar** and navigate to the **Regions** tree. -- Use the search icon inline with the **Regions** tree and then select **Regions**, **Programs**, **Local Transactions** or **Local Files** from the drop-down menu to specify which resource type the filter should be applied for all regions in the plex. +2. In the **Quick Pick**, select **Regions**, **Programs**, **Local Transactions**, or **Local Files**. -- To reset the filter to its initial criteria, use the clear filter icon against the **Regions** tree. This opens a drop-down menu that gives the option to clear the filter for all the **Regions**, **Programs**, **Local Transactions** or **Local Files** in the plex, and the option **All** to clear all filters in the plex. + This specifies the resource type to apply as the filter for all regions in the plex. + +3. To reset the filter to its initial criteria, select the **Clear** filter icon on the **Regions** tree. + + This displays a **Quick Pick** menu that gives the option to clear the filter for all the **Regions**, **Programs**, **Local Transactions** or **Local Files** in the plex, and the option **All** to clear all filters in the plex. ![Zowe CICS Explorer Plex Filter](../images/ze-cics/plex-filter.gif) -**Tip:** To apply multiple filters, separate entries with a comma. You can append any filter with an __*__, which indicates wildcard searching. +::: Tip + +To apply multiple filters, separate entries with a comma. Append a filter with an`*` to indicate wildcard searching. + +::: ## Showing and filtering resources in an 'All' resource tree Plexes includes **All Programs**, **All Local Transactions** and **All Local Files** trees that contain all the corresponding resources from all regions in the plex. -- To view resources under these trees, use the search icon inline with the tree and apply a filter. +To view resources under these trees: + +1. Expand the **CICS** tree in the **Side Bar** and navigate to the desired tree. + +2. Select the **Search** icon in the desired tree and apply a filter from the **Quick Pick**. ![Zowe CICS Explorer All Resource Filter](../images/ze-cics/all-resources.gif) -- If the applied filter results in over 500 records, you can change the filter to narrow the search, or click the **view X more ...** item to retrieve 'X' more resources. + If the applied filter results in more than 500 records, change the filter to narrow the search, or click the **view X more ...** option to retrieve the specified quantity of resources. ## Showing attributes -Right-click the program to open a pop-up menu that lists the available actions that can be performed. +1. Expand the **CICS** tree in the **Side Bar** and navigate to a program. -For every resource, including a CICS region, the **Show Attributes** option opens a viewer that lists all attributes and their values. The attributes page has a filter box at the top that lets you search for attributes matching the criteria. +2. Right-click the program. + + A context menu lists the available actions that can be performed. + +3. Select the **Show Attributes** option. + + All attributes and their values open in an **Editor**. Use the filter box at the top of the **Editor** to search for attributes matching the search criteria. ![Zowe CICS Explorer Show Attributes](../images/ze-cics/show-attributes.gif) ## Enabling and disabling -1. Right-click a program, local transaction, or local file to open a pop-up menu that lists the available actions that can be performed. +1. Expand the **CICS** tree in the **Side Bar** and navigate to a program, local transaction, or local file. + +2. Right-click a program, local transaction, or local file. + + A context menu lists the available actions that can be performed. + +3. Select the **Disable [CICS resource]** option. -2. Click **Disable [CICS resource]** to disable the resource. A disabled resource is identified by `(Disabled)` text next to its name. + The resource is disabled. A disabled resource is identified by a `(Disabled)` indicator next to its name. -When a resource is already disabled, you can re-enable it by clicking **Enable [CICS resource]** in the pop-up menu. +4. To enable resource, right-click a disabled program, local transaction, or local file and select the **Enable [CICS resource]** option from the context menu to re-enable it. ![Zowe CICS Explorer Disable and Enable](../images/ze-cics/disable-enable.gif) ## New copy and phase in -Use the new copy and the phase in actions against a CICS program to get the CICS region to load a fresh copy of the selected program into memory. This could be useful after you edited a COBOL program source and successfully compiled it into a load library and now want to test your change. +Use the **New Copy** and the **Phase In** actions against a CICS program to get the CICS region to load a fresh copy of the selected program into memory. This could be useful after you edited a COBOL program source and successfully compiled it into a load library and now want to test your change. -The `New copy count` for a program which is greater than zero is shown next to the program item in the CICS resource tree. +1. Expand the **CICS** tree in the **Side Bar** and navigate to a program. + +2. Select the program and click on the **New Copy** icon next to it, or right-click a program and select the **New Copy** option from the context menu. + + The program is applied to the CICS region to use it on the associated transaction, and a pop-up message displays the status of the operation. + + The `New copy count` for a program is shown next to the program in the **CICS** tree. + +3. Select the program and click on the **Phase In** icon next to it, or right-click a program and select the **Phase In** option from the context menu. + + The program is applied to the CICS region whether or not the program is actively running, and a pop-up message displays the status of the operation. ![Zowe CICS Explorer NewCopy Program](../images/ze-cics/new-copy.gif) ## Opening and closing local files -**Open a local file** +To open a local file: 1. Right-click a closed local file. -2. Select **Open Local File** to toggle the `openstatus` attribute to `OPEN`. +2. Select the **Open Local File** option from the context menu. + + The `openstatus` attribute for the file is set to `OPEN`. -**Close a local file** +To close a local file: -1. Right-click an open local file and select **Close Local File**. -2. When prompted, choose one option: **Wait**, **No Wait**, or **Force**. +1. Right-click an open local file. +2. Select the **Close Local File** option from the context menu. +3. When prompted, choose one of the following options from the pop-up window: + - **Wait** for the file/resource to not be in use. + - **No Wait** to close the file/resource without waiting. + - **Force** to abort any process that was using the file/resource. - After you select an option, the local file name is appended with a `(Closed)` label upon success. + After an option is selected, the local file name is appended with a `(Closed)` label. ![Zowe CICS Explorer Close a Local File](../images/ze-cics/open-close.gif) diff --git a/docs/user-guide/ze-using-zowe-explorer-cics-ext.md b/docs/user-guide/ze-using-zowe-explorer-cics-ext.md index 9050a65258..11e0b4c311 100644 --- a/docs/user-guide/ze-using-zowe-explorer-cics-ext.md +++ b/docs/user-guide/ze-using-zowe-explorer-cics-ext.md @@ -1,31 +1,13 @@ # Using Zowe Explorer CICS Extension -The CICS Extension for Zowe Explorer adds additional functionality to the popular Visual Studio Code extension, [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode). This extension allows you to interact with CICS regions and programs, and run commands against them. - -## System requirements - -### Client side requirements - -- [Visual Studio Code](https://code.visualstudio.com/download) - -- [Zowe Explorer V2](../user-guide/ze-install#installing-zowe-explorer) - -### Server side requirements - -The following services must be installed, configured, and running on the mainframe: - -- CMCI APIs - -- z/OSMF (optional but recommended) +The CICS Extension for Zowe Explorer adds additional functionality to the popular Visual Studio Code extension [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode). This extension allows you to interact with CICS regions and programs, and run commands against them. ## Features -- **Load profiles** directly from a locally installed Zowe instance. - Create new Zowe CICS profiles and connect to them. -- **Update** session details, and **delete** profiles by using the user-friendly interface. - **Work with multiple regions** that contain programs, local transactions, and local files within a plex in a comprehensible tree-like format. - Perform actions such as **Enable**, **Disable**, **New Copy**, and **Phase In** directly from the UI. - Perform additional actions on local files including **Open** and **Close** directly from the UI. - View and search attributes of resources and regions by right-clicking and using the dynamic filtering feature. - **Apply multiple filters** to regions, programs, local transactions, and local files. -- View and interact with all resources under a plex. +- View and interact with various resources (regions, transactions, programs, libraries, local files, and more) under a plex. diff --git a/docs/user-guide/ze-working-with-commands.md b/docs/user-guide/ze-working-with-commands.md new file mode 100644 index 0000000000..a03774ee4f --- /dev/null +++ b/docs/user-guide/ze-working-with-commands.md @@ -0,0 +1,49 @@ +# Working with commands + +You can issue the same commands used in ISPF with Zowe Explorer. + +MVS commands can be used to obtain information from the zOS console, while SSH commands can be used to issue shell commands to Unix System Services (USS). TSO commands can be used to invoke mainframe scripts in a zOS terminal session. + +## Issuing MVS commands + +1. Expand **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** in the **Side Bar**. +2. Right-click on your profile and select the **Issue MVS Command** option. + + Alternatively, press the `F1` key to open the **Command Palette**, and then select the **Zowe Expolorer: Issue MVS Command** option. + +3. In the **Quick Pick**, enter a new command or select a saved command. +4. Press the `Enter` key to execute the command. + + The output displays in the **Output** panel. + +> Example command: Issue `D T` to get the system time. + +## Issuing SSH commands + +1. Expand **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** in the **Side Bar**. +2. Right-click on your profile and select the **Issue Unix Command** option. + + Alternatively, press the `F1` key to open the **Command Palette**, then select the **Zowe Explorer: Issue Unix Command** option. + +3. In the **Quick Pick**, enter a new command or select a saved command. +4. Press the `Enter` key to execute the command. + + The output displays in the **Output** panel. + +> Example command: Issue `ls` to list the contents of the current directory. + +## Issuing TSO commands + +1. Expand **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** in the **Side Bar**. +2. Right-click on your profile and select the **Issue TSO Command** option. + + Alternatively, press the `F1` key to open the **Command Palette**, then select the **Zowe Explorer: Issue TSO Command** option. + +3. In the **Quick Pick**, enter a new command or select a saved command. +4. Press the `Enter` key to execute the command. + + The output displays in the **Output** panel. + + ![Issue a TSO command](../images/ze/ZE-TSO-Command.gif) + +> Example command: Issue `profile` to get information on your zOS system user profile. diff --git a/docs/user-guide/ze-working-with-data-sets.md b/docs/user-guide/ze-working-with-data-sets.md index 5d44a316bc..8c099f9aa3 100644 --- a/docs/user-guide/ze-working-with-data-sets.md +++ b/docs/user-guide/ze-working-with-data-sets.md @@ -1,25 +1,37 @@ # Working with data sets +## Viewing and accessing multiple profiles simultaneously + +1. Expand the **DATA SETS** tree in the **Side Bar**, and click the **+** icon. +2. Select the profiles from the **Quick Pick** menu to add them to the **Side Bar**. +3. Click the **Search** icon for each profile to search and select associated data sets. + + ![Add Profile](../images/ze/ZE-mult-profiles.gif) + ## Viewing data sets and using multiple filters -1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. -2. Click the **Search** icon. -3. Use the **picker** field to select or enter the patterns you want to apply as filters. - - The data sets that match your pattern(s) display in the **Side Bar**. +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to view. + + Search results display under the profile in the **Side Bar**. :::tip - - To use multiple filters, separate individual entries with a comma. You can append or postpend any filter with an \* to indicate a wildcard search. You cannot enter an \* as the entire pattern. + + To use multiple filters, separate individual entries with a comma. You can append or postpend any filter with an `*` to indicate a wildcard search. You cannot enter an `*` as the entire pattern. ::: ![View Data Set](../images/ze/ZE-multiple-search.gif) ## Viewing data sets with member filters -1. Expand **DATA SETS** in the **Side Bar**, and hover over the profile you want to filter. -2. Click the **Search** icon. -3. In the **picker** field, enter or select a search pattern in the `HLQ.ZZZ.SSS(MEMBERNAME)` format to filter out and display the specified member in the **Side Bar**. +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile. + +3. In the **Quick Pick**, enter or select a search pattern in the `HLQ.ZZZ.SSS(MEMBERNAME)` format to filter search results. + + The specified member displays under the profile in the **Side Bar**. ![View Data Set With Member Pattern](../images/ze/ZE-member-filter-search.gif) @@ -28,30 +40,49 @@ 1. Hover over **DATA SETS** in the **Side Bar**. 2. Click the **Refresh All** icon. + The list of data sets is updated to reflect the latest changes. + ## Renaming data sets -1. Expand **DATA SETS** in the **Side Bar**, and select the data set you want to rename. -2. Right-click the data set and select the **Rename Data Set** option. -3. Enter the new name of the data set in the **picker** field. +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to view. + + Search results display under the profile in the **Side Bar**. + +3. Right-click the desired data set and select the **Rename Data Set** option. +4. Enter the new name of the data set in the **input box**. + + The data set is renamed and displays the new name in the **Side Bar**. ![Rename Data Set](../images/ze/ZE-rename.gif) ## Copying data set members -1. Expand **DATA SETS** in the **Side Bar**, and select the member you want to copy. -2. Right-click the member and select the **Copy Member** option. -3. Right-click the data set where the member is to be contained and select the **Paste Member** option. -4. In the **picker** field, enter the name of the copied member. +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to view. + + Search results display under the profile in the **Side Bar**. +3. Right-click the desired member and select the **Copy** option. +4. Right-click the data set where the member is to be contained and select the **Paste** option. +5. In the **Quick Pick**, enter the name of the copied member. ![Copy Data Set Member](../images/ze/ZE-copy-member.gif) ## Editing and uploading a data set member -1. Expand **DATA SETS** in the **Side Bar**, and select a profile to open it. -2. Open the data set with the member you want to edit. -3. Click on the member name to display it in an **Editor** tab. -4. Edit the document. -5. Press `Ctrl`+`S` or `Command`+`S` to save the changes and upload the data set to the mainframe. +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to view. + + Search results display under the profile in the **Side Bar**. +3. Open the data set with the member you want to edit. +4. Click on the member name to display it in an **Editor**. +5. Edit the document in the **Editor**. +6. Press the `Ctrl`+`S` or `Command`+`S` keys to save the changes. + + The changes are saved and the edited data set is uploaded to the mainframe. :::note @@ -61,24 +92,55 @@ ![Edit and upload a data set member](../images/ze/ZE-edit-upload.gif) +## Uploading a local file to a data set + +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the desired data set. + + Search results display under the profile in the **Side Bar**. + +3. Right-click on the desired PDS and select the **Upload Member...** option to upload a local file as a member of that data set. + + A file explorer window opens. +4. In the file explorer, select the desired file and click **Upload File**. + + The selected file is uploaded as a member of the data set and appears as a new member in the **DATA SETS** tree after the upload is complete. + +## Comparing data set members + +1. Expand the **DATA SETS** tree in the **Side Bar**. + +2. Click on the **Search** icon next to a profile to search for a pattern that matches the desired data set. + + Search results display under the profile in the **Side Bar**. +3. Right-click on the desired member and select the **Select for Compare** option. +4. Right-click a second member and select the **Compare with Selected** option. + + The first selected member displays in an **Editor** on the left; the second member displays on the right. + ## Preventing merge conflicts -1. Expand **DATA SETS** in the **Side Bar**, and navigate to the member you want to edit. -2. Edit the document in the **Editor** tab. -3. Press `Ctrl`+`S` or `Command`+`S` to save the changes. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the desired data set. + + Search results display under the profile in the **Side Bar**. +3. Select the member to open the file in an **Editor**. +4. Edit the document in the **Editor**. +5. Press the `Ctrl`+`S` or `Command`+`S` keys to save the changes. If the original content in your local version no longer matches the same file in the mainframe, a warning message displays advising the user to compare both versions. -4. If necessary, use the editor tool bar to resolve merge conflicts. +6. If necessary, use the editor tool bar to resolve merge conflicts. ![Prevent merge conflicts](../images/ze/ZE-save.gif) ## Creating data sets and specifying parameters -1. Expand **DATA SETS** in the **Side Bar**. -2. Right-click the profile you want to create a data set with and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create and press `Enter`. -5. Select **Edit Attributes** in the **picker** drop-down menu and press `Enter`. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Right-click on the profile you want to create a data set with and select **Create New Data Set**. +3. Enter a name for your data set in the **input box** and press the `Enter` key. +4. From the **Quick Pick** menu, select the data set type that you want to create and press the `Enter` key. +5. Select **Edit Attributes** in the **Quick Pick** menu and press the `Enter` key. The attributes list for the data set displays. You can edit the following attributes: @@ -116,58 +178,43 @@ - Volume Serial -6. Select the attribute you want to edit, provide the value in the **picker** field, and press `Enter`. +6. Select the attribute you want to edit, provide the value in the **input box**, and press the `Enter` key. 7. (Optional) Edit the parameters of your data set. -8. Select the **+ Allocate Data Set** option to create the data set and list it in the **Side Bar**. +8. Select the **+ Allocate Data Set** option. + + The data set is created and listed under the profile in the **Side Bar**. ![Set Parameters](../images/ze/ZE-set-params.gif) ## Creating data sets and data set members -1. Expand **DATA SETS** in the **Side Bar**. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. In the **Side Bar**, right-click on a partitioned data set and select **Create New Member**. +3. Enter a name for your new data set member in the **input box** and press the `Enter` key. -2. Right-click on the profile where you want to create a data set and select **Create New Data Set**. -3. Enter a name for your data set in the **picker** field and press `Enter`. -4. From the **picker** drop-down menu, select the data set type that you want to create. -5. Select **+Allocate Data Set** to create your data set. -6. In the **Side Bar**, right-click your newly-created data set and select **Create New Member**. -7. Enter a name for your new data set member in the **picker** field and press **Enter**. - The member is created and opened in an **Editor** tab. + The member is created and opened in an **Editor**. ## Deleting a data set member and a data set -1. Expand **DATA SETS** in the **Side Bar**. +1. Expand the **DATA SETS** tree in the **Side Bar**. 2. Open the profile and data set containing the member you want to delete. 3. Right-click the member and select **Delete Member**. -4. Confirm the deletion by selecting **Delete** on the **picker** drop-down menu. +4. Confirm the deletion by selecting **Delete** on the **Quick Pick** menu. 5. To delete a data set, right-click the data set and select **Delete Data Set**, then confirm the deletion. - :::note - - You can delete a data set before you delete its members. - - ::: - ![Delete](../images/ze/ZE-delete-ds.gif) ## Viewing data set, member attributes -1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. -2. Select the **Search** icon. -3. In the **picker** field, enter or select a search pattern to filter search results in the **Side Bar**. -4. Right-click a data set or member and select the **Show Attributes** option. - - The attributes display in an **Editor** tab. - - ![View Data Set, Member Attributes](../images/ze/ZE-show-attributes.gif) +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to upload to. -## Viewing and accessing multiple profiles simultaneously + Search results display under the profile in the **Side Bar**. +3. Right-click a data set or member and select the **Show Attributes** option. -1. Expand **DATA SETS** in the **Side Bar**, and click the **+** icon. -2. Select the profiles from the **picker** drop-down to add them to the **Side Bar**. -3. Click the **Search** icon for each profile to search and select associated data sets. + The attributes display in an **Editor**. - ![Add Profile](../images/ze/ZE-mult-profiles.gif) + ![View Data Set, Member Attributes](../images/ze/ZE-show-attributes.gif) ## Filtering partitioned data set members @@ -175,14 +222,15 @@ Filter partitioned data set members in the **DATA SETS** tree view by **Date Mod ### Filtering all partitioned data set members under a specific profile -1. In the **DATA SETS** tree, click on the **Filter** icon to the right of a profile. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Navigate to a profile and click on the **Filter** icon to the right of the profile. - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: + The filter selection menu appears in the **Quick Pick**. +3. Select a filter type from the list of available options: - **Date Modified** - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. +4. In the **Quick Pick**, enter a valid value for the selected filter. +5. Press the `Enter` key to confirm the filter. Expanded data sets display a filtered list of members under the selected profile in the **DATA SETS** tree. @@ -190,14 +238,18 @@ Filter partitioned data set members in the **DATA SETS** tree view by **Date Mod ### Filtering members for a single partitioned data set -1. In the **DATA SETS** tree, right-click on a data set and select the **Filter PDS members…** option. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to filter. - The filter selection menu appears in the **picker** field. -2. Select a filter type from the list of available options: + Search results display under the profile in the **Side Bar**. +3. In the **DATA SETS** tree, right-click on a data set and select the **Filter PDS members…** option. + + The filter selection menu appears in the **Quick Pick**. +4. Select a filter type from the list of available options: - **Date Modified** - **User ID** -3. Enter a valid value for the selected filter. -4. Press the `Enter` key to confirm the filter. This overrides any *profile* filter preferences that might be in effect for the single data set. +5. In the **Quick Pick**, enter a valid value for the selected filter. +6. Press the `Enter` key to confirm the filter. This overrides any *profile* filter preferences that might be in effect for the single data set. The selected data set displays a filtered list of members in the **DATA SETS** tree. @@ -209,11 +261,12 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam ### Sorting all partitioned data set members under a specific profile -1. In the **DATA SETS** tree, click on the **Sort** icon to the right of a profile. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Sort** icon to the right of a profile. - The sorting selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: + The sorting selection menu appears in the **Quick Pick**. +3. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **Quick Pick** menu. +4. Select a sort type from the list of available options: - **Name** - **Date Created** - **Date Modified** @@ -225,10 +278,16 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam ### Sorting members for a single partitioned data set -1. In the **DATA SETS** tree, right-click on a data set and select the **Sort PDS members…** option. - The sort selection menu appears in the **picker** field. -2. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **picker** menu. -3. Select a sort type from the list of available options: +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the data set that you want to sort. + + Search results display under the profile in the **Side Bar**. + +3. Right-click on a data set and select the **Sort PDS members…** option. + + The sort selection menu appears in the **Quick Pick**. +4. To change the sorting direction, select the **Sort Direction** option and select a direction type from the **Quick Pick** menu. +5. Select a sort type from the list of available options: - **Name** - **Date Created** - **Date Modified** @@ -238,24 +297,51 @@ Sort partitioned data set members in the **DATA SETS** tree view by member **Nam ![Sorting a single PDS](../images/ze/ZE-sorting-a-specific-PDS.gif) -## Submiting a JCL +## Submitting a JCL -1. Expand **DATA SETS** in the **Side Bar**. -2. Select the data set or data set member you want to submit. -3. Right-click the data set or member and select the **Submit Job** option. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the desired data set. + + Search results display under the profile in the **Side Bar**. +3. Right-click the desired data set or data set member and select the **Submit Job** option. + + The job is submitted and runs on the mainframe. :::note - - Click on the hyperlink on the notification pop-up message to view the job. + + To view the status of the job, click on the hyperlink on the notification pop-up message. ::: ![Submit a JCL](../images/ze/ZE-submit-jcl.gif) +## Submitting a local file as JCL + +1. Go to the **File** menu and select the **Open File...** option. +2. Select the desired file on your personal computer. + + The file opens as an **Editor** in VS Code. +3. Right-click on the file's **Editor** and select the option **Submit as JCL**. + + A dialog window opens to ask confirmation, then the **Quick Pick** displays a list of profiles to use for the submit action. Respond to the prompt(s) as necessary. + + The job is submitted and runs on the mainframe. + + :::note + + To view the status of the job, click on the hyperlink on the notification pop-up message. + + ::: + ## Allocate like -1. Expand **DATA SETS** in the **Side Bar**. -2. Right-click a data set and select the **Allocate Like (New File with Same Attributes)** option. -3. Enter the new data set name in the **picker** field and press `Enter`. +1. Expand the **DATA SETS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile to search for a pattern that matches the desired data set. + + Search results display under the profile in the **Side Bar**. +3. Right-click a data set and select the **Allocate Like (New File with Same Attributes)** option. +4. Enter the new data set name in the **input box** and press the `Enter` key. + + The new data set displays under the selected profile. ![Allocate Like](../images/ze/ZE-allocate.gif) \ No newline at end of file diff --git a/docs/user-guide/ze-working-with-jobs.md b/docs/user-guide/ze-working-with-jobs.md index 0a8b6277f5..65be90e471 100644 --- a/docs/user-guide/ze-working-with-jobs.md +++ b/docs/user-guide/ze-working-with-jobs.md @@ -1,27 +1,68 @@ # Working with jobs -### Viewing a job +## Viewing job spool output -1. Expand **JOBS** in the **Side Bar**. -2. Open a directory with JCL files. -3. Right-click on the JCL file you want to view, and select the **Get JCL** option. +1. Expand the **JOBS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter search criteria. + + Search results display under the profile in the **Side Bar**. + +3. Expand a job to view its spool files. + +## Viewing job contents + +1. Expand the **JOBS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter search criteria. + + Search results display under the profile in the **Side Bar**. +3. Right-click on the job you want to view, and select the **Get JCL** option. + + Job contents display in an **Editor**. + + :::note + + To edit the job and run it again, make the changes in the **Editor**, right click the **Editor**, and select the **Submit as JCL** option. For instructions, see Step 3 in [Submitting a local file as JCL](../user-guide/ze-working-with-data-sets.md#submitting-a-local-file-as-jcl). + + ::: ![View JOB](../images/ze/ZE-jobs-get-jcl.gif) ## Downloading spool content -1. Expand **JOBS** in the **Side Bar**. -2. Open a directory with JCL files. -3. Click the **Download** icon next to a folder with the spool content. -4. Save the file on your computer. +### Downloading spool files from a job + +1. Expand the **JOBS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter search criteria. + + Search results display under the profile in the **Side Bar**. +3. Right-click on the desired job and select either: + + - **Download All** to download all the spool files to a folder on your local disk. + - **Download All (Binary)** to download all the spool files in binary format on your local disk. + + The selected files are saved in a folder that is the job name in the specified location. ![Download Spool](../images/ze/ZE-jobs-download-spool.gif) +### Downloading a single spool file + +1. Expand the **JOBS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter search criteria. + + Search results display under the profile in the **Side Bar**. +3. Expand the job containing the desired spool file. +4. Right-click on the spool file and select either: + + - **Download All** to download all the spool file contents to a folder on your local disk. + - **Download All (Binary)** to download all the spool file contents in binary format on your local disk. + + The selected file is saved in the specified location. + ## Sorting jobs 1. Expand **JOBS** in the **Side Bar**. 2. Click on the **Sort** icon to the right of a profile. -3. Select the **Sort Direction** option and select either **Ascending** or **Descending** from the **picker** field. +3. In the **Quick Pick**, select the **Sort Direction** option and select either **Ascending** or **Descending**. 4. Select a sort type from the list of available options: - **Job ID (default)** - **Date Submitted** @@ -31,59 +72,35 @@ ![Sorting jobs by date completed](../images/ze/ZE-sorting-jobs-by-date-completed.gif) -## Issuing MVS commands - -1. Expand **JOBS** in the **Side Bar**. -2. Right-click on your profile and select the **Issue MVS Command** option. - - Alternatively, press the `F1` key to open the **Command Pallette**, and then select the **Zowe Expolorer: Issue MVS Command** option. - -3. In the **picker** field, enter a new command or select a saved command. -4. Press `Enter` to execute the command. - - ![Issue a MVS command](../images/ze/ZE-Jobs-Issue-TSO-Command.gif) - -## Issuing TSO commands - -1. Expand **JOBS** in the **Side Bar**. -2. Right-click on your profile and select the **Issue TSO Command** option. - - Alternatively, press the `F1` key to open the **Command Pallette**, then select the **Zowe Explorer: Issue TSO Command** option. - -3. In the **picker** field, enter a new command or select a saved command. -4. Press `Enter` to execute the command. - - The output displays in the **Output** panel. - - ![Issue a TSO command](../images/ze/ZE-TSO-Command.gif) - ## Polling a spool file Users can periodically refresh a spool file during long-running jobs to get the latest job outputs. This avoids having to close and reopen a spool file to get the latest job outputs. -There are two main ways to poll a spool file — automatically at set intervals or manually on demand. +There are two ways to poll a spool file: automatically at set intervals or manually on demand. ### Defining a default interval for polling spool files
-1. Click on the **Settings** icon on the **Activity Bar** and select **Settings**. +1. Click on the **Manage** icon on the **Activity Bar** and select **Settings**. 2. In either the **User** or **Workspace** tab, click on the **Extensions** option to open the menu. 3. Select **Zowe Explorer**. 4. In the **Jobs: Poll Interval** field, enter a valid time interval, in milliseconds. - - Value must be greater than or equal to 1000 ms (1 second). -5. Press **Enter** to start the polling action. + - Value must be greater than or equal to 1000 ms (or 1 second). +5. Press the `Enter` key to start the polling action. ### Polling a spool file at set intervals
-1. Expand **JOBS** in the **Side Bar**. -2. Navigate to the spool file by expanding its corresponding profile and job folder. -3. Right click the spool file and select **Start Polling**. +1. Expand the **JOBS** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter search criteria. + + Search results display under the profile in the **Side Bar**. +3. Right click on the desired spool file and select the **Start Polling** option. - Repeat this step with additional spool files to poll multiple files simultaneously. 4. The **Poll interval (in ms) for: <spoolfilename>** field displays the current interval value. - The default value is set to 5000 ms. - Change the value by entering a different number (must be greater than or equal to 1000 ms). -5. Press **Enter** to confirm the interval time and start the polling action. +5. Press the `Enter` key to confirm the interval time and start the polling action. The poll request is added to the poller, and the selected spool file is marked with a "**P**" in the **Side Bar** and any corresponding **Editor** tabs. @@ -98,7 +115,7 @@ There are two main ways to poll a spool file — automatically at set interv Spool files being polled are marked with a "**P**" in the **Side Bar**. -2. Right click the spool file and select **Stop Polling**. +2. Right click the spool file and select the **Stop Polling** option. The poll request is removed from the poller, and the selected spool file is no longer marked with a "**P**" in the **Side Bar** and any corresponding **Editor** tabs. @@ -108,7 +125,7 @@ There are two main ways to poll a spool file — automatically at set interv To manually poll a spool file: -1. In the **Side Bar**, double click a spool file to open it in an **Editor** tab. +1. In the **Side Bar**, double click a spool file to open it in an **Editor**. 2. With the spool file in an active tab, press the keyboard shortcut. - See [Configuring the keyboard shortcut for manual polling](#configuring-the-keyboard-shortcut-for-manual-polling) to set the keyboard shortcut. @@ -125,5 +142,5 @@ To manually poll a spool file: 3. Select the **Edit** icon to designate a different keyboard shortcut. - The default shortcut is the `F5` key.
- - The entered key(s) can be used to activate polling. \ No newline at end of file + + The entered key(s) can be used to activate polling. diff --git a/docs/user-guide/ze-working-with-uss-files.md b/docs/user-guide/ze-working-with-uss-files.md index f2fbff56a9..025053fa0d 100644 --- a/docs/user-guide/ze-working-with-uss-files.md +++ b/docs/user-guide/ze-working-with-uss-files.md @@ -1,12 +1,20 @@ # Working with USS files +## Viewing and accessing multiple USS profiles simultaneously + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**, and click the **+** icon. +2. Select or enter a profile in the **Quick Pick** menu to add it to the **Side Bar**. + + The profile displays in the **Side Bar**. + + ![View Profiles](../images/ze/ZE-profile2.gif) + ## Viewing Unix System Services (USS) files -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Hover over the profile you want to search and click the **Search** icon. -3. In the **picker** field, enter or select the path that you want as the root of your displayed tree and press `Enter`. - - All child files and directories of that path display in the **Side Bar**. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. :::note @@ -16,28 +24,73 @@ ![Enter Path](../images/ze/ZE-path.gif) +## Dragging and dropping USS files + +To select one or more files or folders in the tree and drag them to a folder or session to relocate them: + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. +3. Select the files or folders you want to move. + - Select multiple items by pressing the `Ctrl` key as you select each item. + - Select a continuous range of items by selecting the first item in the range. Then hold down the `Shift` key until selecting the last item in the range. +4. Click and hold the region containing the selected items to start the drag process. +5. As the items are selected, move your cursor to the desired folder or session. Release the mouse button to start the move operation. + - If the move operation might overwrite one or more files, an “overwrite confirmation" message displays. Select **Confirm** to relocate these items. Select **Cancel** to stop the move operation. + - Items can be moved across different profiles or LPARs, which may cause a brief delay due to the transfer process. +6. When items are moved, the tree view refreshes and the moved items appear in the destination folder. + + ![Dragging and dropping USS files](../images/ze/ZE-uss-drag-drop.gif) ## Refreshing the list of files 1. Hover over **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. 2. Click the **Refresh All** button. + The list of directories and child files is updated to reflect the latest changes. + ![Refresh All](../images/ze/ZE-refreshUSS.gif) ## Renaming USS files -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. -2. Select a USS file you want to rename. -3. Right-click the USS file and select the **Rename USS file** option. -4. In the **picker** field, change the name of the USS file and press `Enter`. + All child files and directories of that path display under the profile in the **Side Bar**. + +3. Select a USS file you want to rename. +4. Right-click the USS file and select the **Rename USS file** option. +5. In the **input box**, enter the new name of the USS file and press the `Enter` key. + + The file is renamed and the new name displays in the **Side Bar**. + +## Copying and pasting USS folders and files + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. +3. Select the files or folders you want to move. + - Select multiple items by pressing the `Ctrl` key as you select each item. + - Select a continuous range of items by selecting the first item in the range, then hold down the `Shift` key until selecting the last item in the range. +4. Right-click the selected items and select the **Copy** option from the menu +5. Navigate in the USS tree to the folder where you want to paste the files. + + Files can be moved across different profiles or LPARs, which may cause a brief delay due to the transfer process. +6. Right-click on the folder and select the **Paste** option from the menu. + + The copied items display in the new location. ## Downloading, editing, and uploading existing USS files -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Navigate to the file you want to download and click on the file name. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. +3. Click on the file name of the file you want to download. - This displays the file in an **Editor** tab. + The file contents display in an **Editor**. :::note @@ -45,47 +98,87 @@ ::: -3. Edit the document. -4. Press `Ctrl`+`S` or `Command`+`S` to save the changes and upload the USS file to the mainframe. +4. Edit the document in the **Editor**. +5. Press the `Ctrl`+`S` or `Command`+`S` keys to save the changes. + + The changes are saved and the USS file is uploaded to the mainframe. ![Edit](../images/ze/ZE-editUSS.gif) +## Uploading a local file to a USS directory + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. + +3. Right-click on the desired directory and select the **Upload Files...** option to upload one or more local files to the directory. + + A file explorer window opens. +4. In the file explorer, select the desired file(s) and click **Upload Files**. + + The selected file(s) is uploaded to the USS directory and appears as new file name in the **UNIX SYSTEM SERVICES (USS)** tree. + +## Comparing USS files + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. +3. Right-click on the desired file and select the **Select for Compare** option. +4. Right-click a second file and select the **Compare with Selected** option. + + The first selected file displays in an **Editor** on the left; the second file displays on the right. + ## Creating and deleting USS files and directories ### Creating a directory -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. -2. Right-click the directory where you want to add the new directory. -3. Select the **Create Directory** option and enter the directory name in the **picker** field. -4. Press `Enter` to create the directory. +3. Right-click the desired directory and select the **Create Directory** option. +4. Enter the directory name in the **input box**. +5. Press the `Enter` key to create the directory. + + A new directory is created and displays in the selected directory. ### Creating a file -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. + + All child files and directories of that path display under the profile in the **Side Bar**. + +3. Right-click the desired directory and select the **Create File** option. +4. Enter the file name in the **input box**. +5. Press the `Enter` key to create the directory. -2. Right-click the directory to which you want to add the new file. -3. Select the **Create File** option and enter the file name in the **picker** field. -4. Press `Enter` to create the file. + A new file is created and displays in the selected directory. ### Deleting a file -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. -2. Right-click the file you want to remove. -3. Select the **Delete** option and click **Delete** again to confirm and delete the file. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. -### Deleting a directory + All child files and directories of that path display under the profile in the **Side Bar**. -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**. -2. Right-click the directory you want to remove. -3. Select the **Delete** button and click **Delete** again to confirm and delete the directory and all its child files and directories. +3. Right-click on the file you want to remove. +4. Select the **Delete** option and click **Delete** again to confirm and delete the file. - ![Create and Delete](../images/ze/ZE-CreateDelete.gif) + The file is deleted and no longer displays in the selected directory. -## Viewing and accessing multiple USS profiles simultaneously +### Deleting a directory + +1. Expand the **UNIX SYSTEM SERVICES (USS)** tree in the **Side Bar**. -1. Expand **UNIX SYSTEM SERVICES (USS)** in the **Side Bar**, and click the **+** icon. -2. Select or enter a profile in the **picker** drop-down menu to add it to the **Side Bar**. +2. Click on the **Search** icon next to a profile and enter the path of the desired directory. +3. Right-click the directory you want to remove. +4. Select the **Delete** button and click **Delete** again to confirm and delete the directory and all its child files and directories. - ![View Profiles](../images/ze/ZE-profile2.gif) \ No newline at end of file + The directory is deleted and no longer displays in the **Side Bar**. + + ![Create and Delete](../images/ze/ZE-CreateDelete.gif) diff --git a/docs/user-guide/zowe-getting-started-tutorial.md b/docs/user-guide/zowe-getting-started-tutorial.md index dd1ab3f48d..4c34eab304 100644 --- a/docs/user-guide/zowe-getting-started-tutorial.md +++ b/docs/user-guide/zowe-getting-started-tutorial.md @@ -4,21 +4,21 @@ Learn how to start using Zowe components, applications, and plug-ins. ## Zowe server-side components -- [Using Zowe Desktop](mvd-using.md) - [Using Zowe API Mediation Layer](api-mediation/using-api-mediation-layer.md) +- [Using Zowe Desktop](mvd-using.md) - [Zowe cross memory server](../user-guide/configure-xmem-server.md) ## Zowe client-side components - [Using Zowe CLI](cli-using-usingcli.md) -- [Using Zowe Explorer](ze-usage.md) +- [Using Zowe Explorer plug-in for IntelliJ IDEA](intellij-use-cases.md) +- [Using Zowe Explorer for Visual Studio Code](ze-usage.md) - [Using Zowe SDKs](sdks-using.md) ### Explore available plug-ins - [Zowe CLI plug-ins](cli-extending.md) -- [Zowe Explorer extensions](ze-using-zowe-explorer-cics-ext.md) -- [Using Zowe IntelliJ Plug-in](intellij-using.md) +- [Zowe Explorer extensions for Visual Studio Code](ze-using-zowe-explorer-cics-ext.md) ### Incubator components diff --git a/docs/user-guide/zwe-init-subcommand-overview.md b/docs/user-guide/zwe-init-subcommand-overview.md index 7ded39da9f..fa21b906c8 100644 --- a/docs/user-guide/zwe-init-subcommand-overview.md +++ b/docs/user-guide/zwe-init-subcommand-overview.md @@ -10,7 +10,6 @@ Some of the following `zwe init` subcommands require elevated permissions. See t * [Initializing Zowe security configurations (`zwe init security`)](#initializing-zowe-security-configurations-zwe-init-security) * [Performing APF authorization of load libraries (`zwe init apfauth`)](#performing-apf-authorization-of-load-libraries-zwe-init-apfauth) * [Configuring Zowe to use TLS certificates (`zwe init certificate`)](#configuring-zowe-to-use-tls-certificates-zwe-init-certificate) -* [Creating VSAM caching service datasets (`zwe init vsam`)](#creating-vsam-caching-service-datasets-zwe-init-vsam) * [Installing Zowe main started tasks (`zwe init stc`)](#installing-zowe-main-started-tasks-zwe-init-stc) ## Initializing Zowe custom data sets (`zwe init mvs`) @@ -139,17 +138,6 @@ Zowe supports using either file-based (PKCS12) or z/OS key ring-based (when on z For more information, see [Configuring certificates](./configure-certificates). -## Creating VSAM caching service datasets (`zwe init vsam`) - -Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are started, either on the same LPAR or different LPARs connected through sysplex distributor. If you are only running a single Zowe instance on a single LPAR you do not need to create a caching service so you may skip this step. - -:::info Required roles: system programmer -::: - -The command `zwe init vsam` uses the template JCL in `SZWESAMP(ZWECSVSM)` to copy the source template member from `zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM)` and creates a target JCL member in `zowe.setup.mvs.jcllib(ZWECVSCM)` with values extracted from the `zowe.yaml` file. - -For more information about `zwe init vsam`, see [Creating VSAM caching service datasets](./configure-caching-service-ha#vsam) - ## Installing Zowe main started tasks (`zwe init stc`) Execute the subcommand `zwe init stc` to install Zowe main started tasks. @@ -194,6 +182,20 @@ Copy IBMUSER.ZWEV2.CUST.JCLLIB(ZWESASTC) to USER.PROCLIB(ZWESASTC) #> ``` +## (Deprecated) Creating VSAM caching service datasets (`zwe init vsam`) + +This command is no longer required as the Caching service by default uses Infinispan instead. You only need to run this command if you wish the Caching service to use VSAM for its storage medium. + +Zowe can work in a high availability (HA) configuration where multiple instances of the Zowe launcher are started, either on the same LPAR or different LPARs connected through sysplex distributor. If you are only running a single Zowe instance on a single LPAR you do not need to create a caching service so you may skip this step. + +:::info Required roles: system programmer +::: + +The command `zwe init vsam` uses the template JCL in `SZWESAMP(ZWECSVSM)` to copy the source template member from `zowe.setup.mvs.hlq.SZWESAMP(ZWECVCSM)` and creates a target JCL member in `zowe.setup.mvs.jcllib(ZWECVSCM)` with values extracted from the `zowe.yaml` file. + +For more information about `zwe init vsam`, see [Creating VSAM caching service datasets](./configure-caching-service-ha#vsam) + + ## Next steps After each of the `zwe init` subcommands run successfully, the next step is to complete [configuring security](./configuring-security). diff --git a/docs/whats-new/breaking-changes-v3.md b/docs/whats-new/breaking-changes-v3.md index 2a8e34bf16..ed145312ec 100644 --- a/docs/whats-new/breaking-changes-v3.md +++ b/docs/whats-new/breaking-changes-v3.md @@ -12,9 +12,9 @@ Review this article for details about changes to various Zowe components that ar |----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Authentication endpoints will not support the route `/api/v1/gateway`, and instead will support only `/gateway/api/v1` | If you use the endpoints directly, change the URLs to start with `/gateway/api/v1`. If you use ZAAS client to integrate with API Mediation Layer, no action is required as the change is handled in the ZAAS client code. | | Spring Enabler will be updated to Spring Boot 3 and Spring 6. Spring Boot 2 and Spring 5 versions will no longer be supported | Upgrade extending services based on the Spring Enabler to Spring Boot 3 and Spring 6. | -| Datasets API will be archived | This service was disabled by default in Version 2. If you enable the service via `components.data-sets.enabled: true` and use the APIs documented in [Data sets Swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/datasets.json), it is necessary to move to the usage of the similar z/OSMF endpoints. | -| Jobs API will be archived | The service was disabled by default in Version 2. If you enable the service via `components.jobs.enabled: true` and use the APIs documented in [Jobs Swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/jobs.json), it is necessary to move to the usage of the similar z/OSMF endpoints. | -| Metrics service will be archived | The service was in Technical Preview. Currently there is no replacement. In V3, the Open Telemetry standard will be implemented, which will serve as a replacement. | +| Datasets API has been removed, as the project is archived. | This service was disabled by default in Version 2. If you enable the service via `components.data-sets.enabled: true` and use the APIs documented in [Data sets Swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/datasets.json), it is necessary to move to the usage of the similar z/OSMF endpoints. | +| Jobs API has been removed, as the project is archived. | The service was disabled by default in Version 2. If you enable the service via `components.jobs.enabled: true` and use the APIs documented in [Jobs Swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/zowe/docs-site/docs-staging/api_definitions/jobs.json), it is necessary to move to the usage of the similar z/OSMF endpoints. | +| Metrics service has been removed, as the project is archived. | The service was in Technical Preview. Currently there is no replacement. In V3, the Open Telemetry standard will be implemented, which will serve as a replacement. | | IMS API will be archived | The service was not fully supported. If you were using the API, please reach out to the IBM team for follow-up steps. | | Java 17 will be required for the API Mediation Layer to run | For V3, it is necessary to update z/OS to version 2.5 or later as this brings support of Java 17. It is necessary to install Java 17 and provide the path to Java 17 to Zowe Java configuration. | | z/OSMF in version V2R5 with APAR PH12143 applied | If you are running a version of z/OS before 3.1, validate that the PH12143 APAR was applied to the z/OSMF installation used by Zowe. | @@ -24,6 +24,14 @@ Review this article for details about changes to various Zowe components that ar The current API Gateway contains the Authentication and Authorization Service. This service will be separated as a standalone service. The Authentication and Authorization Service is the only API ML service that directly requires z/OS. + +## Application Framework + +### Breaking changes + +* Updated Angular to Version 18 from Version 12. Apps built upon Angular, excluding iframe apps, will need to be updated to be compatible with the V3 Desktop. + + ## CLI ### Breaking changes @@ -47,11 +55,11 @@ The current API Gateway contains the Authentication and Authorization Service. T * Updating Webpack to version 5 * Updating Typescript to 4.9 -## Explorer for Intellij +## Explorer for Intellij IDEA ### Important updates -* Explorer for Intellij will be part of the Zowe Core +* Explorer for IntelliJ IDEA will be part of the Zowe Core * Working with USS Files * Working with Data Sets * Working with JES Working Sets diff --git a/docs/whats-new/zowe-v3-frequently-asked-questions.md b/docs/whats-new/zowe-v3-frequently-asked-questions.md index 1dc04341de..260e4aeba8 100644 --- a/docs/whats-new/zowe-v3-frequently-asked-questions.md +++ b/docs/whats-new/zowe-v3-frequently-asked-questions.md @@ -46,27 +46,27 @@ No. ZSS runs in either 31-bit or 64-bit mode, which means it can accommodate only one type of plug-in. -2. Are Angular and Webpack updated to the latest current versions? +2. Have the versions of libraries used in the Desktop changed? - In Zowe V3, the Application Framework uses Angular 16 and Webpack 5, which are the latest current releases. + In Zowe V3, the Application Framework uses Angular 18 with associated libraries such as webpack 5. 3. What _React_ versions are supported by Zowe Desktop? - It is possible for Desktop extensions to use different versions of _React_. While the Desktop is not built on _React_, it is still compatible with extensions that import _React_. - -4. Is the Zowe Server Install Wizard application running on Zowe Desktop or on z/OS? - - The Zowe Server Install Wizard runs on a laptop/desktop and connects to z/OS via standard methods. - -5. Is it possible to validate and change the `zowe.yaml` file and job definition within the Zowe Server Install Wizard? - - Yes. + Zowe v3's React compatibility has not changed. It is possible for Desktop extensions to use different versions of _React_. While the Desktop is not built on _React_, it is still compatible with extensions that import _React_. ### Zowe System Installation and Configuration 1. Does Zowe provide a Software Bill of Materials (SBOM)? SBOMs are available in the SPDX format from the [Bill of Materials](https://docs.zowe.org/stable/appendix/bill-of-materials/) page on Zowe Docs. + +2. Is the Zowe Server Install Wizard application running on Zowe Desktop or on z/OS? + + The Zowe Server Install Wizard runs on a laptop/desktop and connects to z/OS via standard methods. + +3. Is it possible to validate and change the `zowe.yaml` file and job definition within the Zowe Server Install Wizard? + + Yes. ## User questions diff --git a/sidebars.js b/sidebars.js index 53b3cba405..7a4c55700f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -6,38 +6,38 @@ module.exports = { type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) label: "Release notes", className: "ToCheadercolor", - link: {type:"doc", id:"whats-new/release-notes/release-notes-overview"}, + link: { type: "doc", id: "whats-new/release-notes/release-notes-overview" }, items: [ "whats-new/release-notes/v3_0_0", - { - type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) - label: "Zowe V2 release notes", - className: "ToCheadercolor", - collapsed: false, - items: [ - "whats-new/release-notes/v2_18_0", - "whats-new/release-notes/v2_17_0", - "whats-new/release-notes/v2_16_0", - "whats-new/release-notes/v2_15_0", - "whats-new/release-notes/v2_14_0", - "whats-new/release-notes/v2_13_0", - "whats-new/release-notes/v2_12_0", - "whats-new/release-notes/v2_11_0", - "whats-new/release-notes/v2_10_0", - "whats-new/release-notes/v2_9_0", - "whats-new/release-notes/v2_8_0", - "whats-new/release-notes/v2_7_0", - "whats-new/release-notes/v2_6_1", - "whats-new/release-notes/v2_6_0", - "whats-new/release-notes/v2_5_0", - "whats-new/release-notes/v2_4_0", - "whats-new/release-notes/v2_3_1", - "whats-new/release-notes/v2_3_0", - "whats-new/release-notes/v2_2_0", - "whats-new/release-notes/v2_1_0", - "whats-new/release-notes/v2_0_0", - ], - }, + ], + }, + { + type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) + label: "Zowe V2 release notes", + className: "ToCheadercolor", + collapsed: false, + items: [ + "whats-new/release-notes/v2_18_0", + "whats-new/release-notes/v2_17_0", + "whats-new/release-notes/v2_16_0", + "whats-new/release-notes/v2_15_0", + "whats-new/release-notes/v2_14_0", + "whats-new/release-notes/v2_13_0", + "whats-new/release-notes/v2_12_0", + "whats-new/release-notes/v2_11_0", + "whats-new/release-notes/v2_10_0", + "whats-new/release-notes/v2_9_0", + "whats-new/release-notes/v2_8_0", + "whats-new/release-notes/v2_7_0", + "whats-new/release-notes/v2_6_1", + "whats-new/release-notes/v2_6_0", + "whats-new/release-notes/v2_5_0", + "whats-new/release-notes/v2_4_0", + "whats-new/release-notes/v2_3_1", + "whats-new/release-notes/v2_3_0", + "whats-new/release-notes/v2_2_0", + "whats-new/release-notes/v2_1_0", + "whats-new/release-notes/v2_0_0", ], }, ], @@ -46,24 +46,27 @@ module.exports = { type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) label: "Zowe fundamentals", className: "ToCheadercolor", - link: {type:"doc", id:"getting-started/overview"}, + link: { type: "doc", id: "getting-started/overview" }, collapsed: false, items: [ "getting-started/zowe-architecture", { type: "category", label: "Zowe security", - link: {type: "doc", id: "getting-started/zowe-security-overview"}, + link: { type: "doc", id: "getting-started/zowe-security-overview" }, items: [ - { type: "doc", - label: "Glossary of Zowe Security terminology", - id: "appendix/zowe-security-glossary", + { + type: "doc", + label: "Glossary of Zowe Security terminology", + id: "appendix/zowe-security-glossary", }, - { type: "doc", + { + type: "doc", label: "Zowe Certificates overview", id: "getting-started/zowe-certificates-overview", }, - { type: "doc", + { + type: "doc", label: "Zowe User Authentication", id: "getting-started/zowe-security-authentication", } @@ -72,13 +75,13 @@ module.exports = { "getting-started/zowe-high-availability" ], }, - "getting-started/zowe_faq", - "appendix/zowe-glossary", - "getting-started/zowe-resources", + "getting-started/zowe_faq", + "appendix/zowe-glossary", + "getting-started/zowe-resources", { type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) label: "Zowe V3", - link: {type:"doc", id:"whats-new/breaking-changes-v3"}, + link: { type: "doc", id: "whats-new/breaking-changes-v3" }, items: [ "whats-new/zowe-v3-frequently-asked-questions", "whats-new/zowe-v3-office-hours", @@ -88,7 +91,7 @@ module.exports = { { type: "category", // doc(default), 'link'(external links), 'ref'(page without without sidebar) label: "Zowe V2", - link: {type:"doc", id:"getting-started/zowe-v2-overview"}, + link: { type: "doc", id: "getting-started/zowe-v2-overview" }, items: [ "getting-started/zowe_v2_faq", "getting-started/zowe-office-hours", @@ -96,7 +99,7 @@ module.exports = { type: "doc", label: "Migrating from Zowe V1 to Zowe V2", className: "ToCitemcolor", - id:"extend/migrate-extensions", + id: "extend/migrate-extensions", }, ], }, @@ -107,13 +110,13 @@ module.exports = { { type: "category", label: "Installing Zowe server-side components", - link: {type: "doc", id: "user-guide/install-zos"}, + link: { type: "doc", id: "user-guide/install-zos" }, collapsed: false, items: [ { type: "category", label: "Preparing for installation", - link: {type: "doc", id: "user-guide/installandconfig"}, + link: { type: "doc", id: "user-guide/installandconfig" }, items: [ "user-guide/zos-components-installation-checklist", "user-guide/systemrequirements-zos", @@ -127,17 +130,17 @@ module.exports = { ] }, { - type: "category", - label: "Installing Zowe Server Install Wizard", - link: {type:"doc", id: "user-guide/install-zowe-server-install-wizard"}, - items: [ - "user-guide/troubleshooting-zowe-server-install-wizard", - ] - }, + type: "category", + label: "Installing Zowe Server Install Wizard", + link: { type: "doc", id: "user-guide/install-zowe-server-install-wizard" }, + items: [ + "user-guide/troubleshooting-zowe-server-install-wizard", + ] + }, { type: "category", label: "Installing Zowe via SMP/E", - link: {type:"doc", id: "user-guide/install-zowe-smpe-overview"}, + link: { type: "doc", id: "user-guide/install-zowe-smpe-overview" }, items: [ "user-guide/install-zowe-smpe", ] @@ -145,7 +148,7 @@ module.exports = { { type: "category", label: "Installing Zowe via z/OSMF from PSWI and SMP/E workflow", - link: {type:"doc", id:"user-guide/zosmf-install"}, + link: { type: "doc", id: "user-guide/zosmf-install" }, items: [ "user-guide/install-zowe-pswi-address-requirements", "user-guide/systemrequirements-zosmf", @@ -153,20 +156,20 @@ module.exports = { { type: "category", label: "Installing Zowe via z/OSMF from PSWI", - link: {type:"doc", id:"user-guide/install-zowe-pswi"}, + link: { type: "doc", id: "user-guide/install-zowe-pswi" }, items: [ "user-guide/install-zowe-pswi-acquire", "user-guide/install-zowe-pswi-deployment", ], - }, - "user-guide/install-zowe-smpe-zosmf-workflow", - ], + }, + "user-guide/install-zowe-smpe-zosmf-workflow", + ], }, "user-guide/install-zowe-zos-convenience-build", { type: "category", label: "Installing Zowe via a containerization build (PAX file)", - link: {type:"doc", id:"user-guide/k8s-introduction"}, + link: { type: "doc", id: "user-guide/k8s-introduction" }, items: [ "user-guide/k8s-prereqs", "user-guide/k8s-downloading", @@ -174,15 +177,15 @@ module.exports = { "user-guide/k8s-using", ], }, - { + { type: "category", label: "Configuring", - link: {type:"doc", id:"user-guide/configuring-overview"}, + link: { type: "doc", id: "user-guide/configuring-overview" }, items: [ { type: "category", label: "Initializing Zowe z/OS runtime", - link: {type:"doc", id:"user-guide/configure-zowe-runtime"}, + link: { type: "doc", id: "user-guide/configure-zowe-runtime" }, items: [ "user-guide/initialize-zos-system", "user-guide/zwe-init-subcommand-overview", @@ -193,18 +196,18 @@ module.exports = { { type: "category", label: "Configuring security", - link: {type:"doc", id:"user-guide/configuring-security"}, + link: { type: "doc", id: "user-guide/configuring-security" }, items: [ "user-guide/initialize-security-configuration", "user-guide/apf-authorize-load-library", "user-guide/configure-zos-system", "user-guide/assign-security-permissions-to-users", - ], + ], }, { type: "category", label: "Configuring certificates", - link: {type:"doc", id:"user-guide/configure-certificates"}, + link: { type: "doc", id: "user-guide/configure-certificates" }, items: [ "user-guide/certificates-configuration-questionnaire", "user-guide/certificate-configuration-scenarios", @@ -218,20 +221,20 @@ module.exports = { { type: "category", label: "Configuring the Zowe cross memory server (ZIS)", - link: {type:"doc", id:"user-guide/configure-xmem-server"}, + link: { type: "doc", id: "user-guide/configure-xmem-server" }, items: [], - }, + }, { type: "category", label: "Configuring high availability (optional)", - link: {type:"doc", id:"user-guide/zowe-ha-overview"}, + link: { type: "doc", id: "user-guide/zowe-ha-overview" }, items: [ "user-guide/configure-sysplex", "user-guide/systemrequirements-zosmf-ha", "user-guide/configure-caching-service-ha", ] } - ] + ] }, { type: "category", @@ -286,17 +289,17 @@ module.exports = { "user-guide/api-mediation/configuration-access-specific-instance-of-service", "user-guide/api-mediation/configuration-distributed-load-balancer-cache", "user-guide/api-mediation/configuration-set-consistent-service-id", - { - "type": "category", - "label": "Customizing management of API ML load limits", - "link": { "type": "doc", "id": "user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits" }, - "items": [ - "user-guide/api-mediation/configuration-connection-limits", - "user-guide/api-mediation/configuration-gateway-timeouts", - "user-guide/api-mediation/configuration-customizing-java-heap-sizes" + { + "type": "category", + "label": "Customizing management of API ML load limits", + "link": { "type": "doc", "id": "user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits" }, + "items": [ + "user-guide/api-mediation/configuration-connection-limits", + "user-guide/api-mediation/configuration-gateway-timeouts", + "user-guide/api-mediation/configuration-customizing-java-heap-sizes" + ] + } ] - } - ] }, { "type": "category", @@ -321,71 +324,111 @@ module.exports = { "user-guide/api-mediation/configuration-customizing-the-api-catalog-ui", "user-guide/api-mediation/configuration-at-tls", "user-guide/api-mediation/configuration-logging", - "user-guide/api-mediation/wto-message-on-startup", + "user-guide/api-mediation/wto-message-on-startup", ] - } - ], - }, + } + ], + }, { type: "category", label: "Installing Zowe client-side components", + link: { type: "doc", id: "user-guide/install-zowe-client-side-components" }, collapsed: false, items: [ { type: "category", - label: "Zowe CLI", - link: {type:"doc", id:"user-guide/user-roadmap-zowe-cli"}, + label: "Configuring z/OSMF", + link: { type: "doc", id: "user-guide/cli-install-configure-zosmf" }, items: [ - "user-guide/systemrequirements-cli", - "user-guide/cli-install-cli-checklist", - { + "user-guide/cli-install-configure-zosmf-security", + ], + }, + { type: "category", - label: "Installing Zowe CLI", - link: {type:"doc", id:"user-guide/cli-installcli"}, + label: "Zowe CLI installation", + link: { type: "doc", id: "user-guide/user-roadmap-zowe-cli" }, items: [ - "user-guide/cli-configure-scs-on-headless-linux-os", - "user-guide/cli-configure-cli-on-os-where-scs-unavailable", - "user-guide/cli-install-cli-nodejs-windows", - ], - }, - "user-guide/install-cli-via-proxy", + "user-guide/cli-install-cli-checklist", + { + type: "category", + label: "Zowe CLI system requirements", + link: { type: "doc", id: "user-guide/systemrequirements-cli" }, + items: [ + "user-guide/cli-swreqplugins", + ], + }, + "user-guide/cli-install-configure-install-online-registry-proxy", "user-guide/cli-updatingcli", - "user-guide/cli-uninstall", { type: "category", - label: "Advanced Zowe CLI configuration", + label: "Configuring Zowe CLI", items: [ "user-guide/cli-configuringcli-ev", "user-guide/cli-configuringcli-evfile", + "user-guide/cli-using-initializing-team-configuration", + { + type: "category", + label: "Configuring daemon mode", + link: { type: "doc", id: "user-guide/cli-using-using-daemon-mode" }, + items: [ + "user-guide/cli-configure-daemon-on-zlinux-os", + ], + }, ], - }, + }, + "user-guide/cli-uninstall", + "user-guide/cli-install-verify-your-installation", ], }, + { type: "category", - label: "Zowe Explorer", - link: {type:"doc", id:"getting-started/user-roadmap-zowe-explorer"}, + label: "Zowe Explorer installation", + link: { type: "doc", id: "getting-started/user-roadmap-zowe-explorer" }, items: [ + "user-guide/ZE-install-checklist", "getting-started/ZE-system-reqs", "user-guide/ze-install", + { + type: "category", + label: "Installing Zowe Explorer extensions", + link: { type: "doc", id: "getting-started/install-ze-extensions" }, + items: [ + "user-guide/ze-install-zowe-explorer-cics-ext", + "user-guide/ze-ftp-install-ze-ftp-ext", + ], + }, "user-guide/ze-profiles", + "user-guide/ze-install-configuring-ze", + "user-guide/ze-install-verify-your-installation", + "user-guide/ze-install-uninstall-ze", + ], + }, + { + type: "category", + label: "Zowe Explorer plug-in for IntelliJ IDEA", + items: [ + "user-guide/intellij-install-prereqs", + "user-guide/intellij-install", + "user-guide/intellij-configure", ], }, + "getting-started/install-zowe-sdks", { type: "category", - label: "Zowe Chat (Technical Preview)", - link: {type:"doc", id:"user-guide/zowe-chat/introduction"}, + label: "Zowe Chat (technical preview)", + link: { type: "doc", id: "user-guide/zowe-chat/introduction" }, items: [ "user-guide/zowe-chat/systemrequirements-chat", { type: "category", label: "Configuring chat platforms", - link: {type:"doc", id:"user-guide/zowe-chat/chat_configure_chat_platforms"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_configure_chat_platforms" }, items: [ { type: "category", label: "Configuring Mattermost", - link: {type:"doc", id:"user-guide/zowe-chat/chat_prerequisite_mattermost"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_prerequisite_mattermost" }, items: [ "user-guide/zowe-chat/chat_prerequisite_install_mattermost", "user-guide/zowe-chat/chat_prerequisite_mattermost_admin_account", @@ -398,13 +441,13 @@ module.exports = { { type: "category", label: "Configuring Microsoft Teams", - link: {type:"doc", id:"user-guide/zowe-chat/chat_prerequisite_teams"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_prerequisite_teams" }, items: [ "user-guide/zowe-chat/chat_prerequisite_teams_create_app_developer_portal", { type: "category", label: "Creating a bot for Microsoft Teams bot app", - link: {type:"doc", id:"user-guide/zowe-chat/chat_prerequisite_teams_create_bot"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_prerequisite_teams_create_bot" }, items: [ "user-guide/zowe-chat/chat_prerequisite_teams_create_bot_framework", "user-guide/zowe-chat/chat_prerequisite_teams_create_bot_azure", @@ -413,7 +456,7 @@ module.exports = { { type: "category", label: "Configuring messaging endpoint", - link: {type:"doc", id:"user-guide/zowe-chat/chat_prerequisite_teams_configure_endpoint"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_prerequisite_teams_configure_endpoint" }, items: [ "user-guide/zowe-chat/chat_prerequisite_teams_configure_endpoint_framework", "user-guide/zowe-chat/chat_prerequisite_teams_configure_endpoint_azure", @@ -424,7 +467,7 @@ module.exports = { { type: "category", label: "Configuring Slack", - link: {type:"doc", id:"user-guide/zowe-chat/chat_prerequisite_slack"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_prerequisite_slack" }, items: [ "user-guide/zowe-chat/chat_prerequisite_slack_create_app", { @@ -446,7 +489,7 @@ module.exports = { { type: "category", label: "Configuring Zowe Chat", - link: {type:"doc", id:"user-guide/zowe-chat/chat_configure_server"}, + link: { type: "doc", id: "user-guide/zowe-chat/chat_configure_server" }, items: [ "user-guide/zowe-chat/chat_configure_mattermost", "user-guide/zowe-chat/chat_configure_teams", @@ -457,17 +500,9 @@ module.exports = { "user-guide/zowe-chat/chat_uninstall", ], }, - { - type: "category", - label: "Zowe IntelliJ Plug-in", - link: {type:"doc", id:"user-guide/intellij-install"}, - items: [ - "user-guide/intellij-configure", - ], - }, + ], + }, ], -}, - ], "use": [ "user-guide/zowe-getting-started-tutorial", { @@ -478,7 +513,7 @@ module.exports = { { type: "category", label: "Using Zowe Desktop", - link: {type:"doc", id:"user-guide/mvd-using"}, + link: { type: "doc", id: "user-guide/mvd-using" }, items: [ "user-guide/mvd-editor", ], @@ -486,13 +521,13 @@ module.exports = { { type: "category", label: "Using Zowe API Mediation Layer", - link: {type:"doc", id:"user-guide/api-mediation/using-api-mediation-layer"}, + link: { type: "doc", id: "user-guide/api-mediation/using-api-mediation-layer" }, items: [ "getting-started/user-roadmap-apiml", { type: "category", label: "Using Single Sign On", - link: {type:"doc", id:"user-guide/api-mediation-sso"}, + link: { type: "doc", id: "user-guide/api-mediation-sso" }, items: [ "user-guide/authenticating-with-jwt-token", "user-guide/authenticating-with-client-certificates", @@ -503,7 +538,7 @@ module.exports = { { type: "category", label: "Using multi-factor authentication (MFA)", - link: {type:"doc", id:"user-guide/api-mediation/using-multi-factor-authentication"}, + link: { type: "doc", id: "user-guide/api-mediation/using-multi-factor-authentication" }, items: [ ], }, @@ -537,7 +572,7 @@ module.exports = { { type: "category", label: "Using the Caching Service", - link: {type:"doc", id:"user-guide/api-mediation/api-mediation-caching-service"}, + link: { type: "doc", id: "user-guide/api-mediation/api-mediation-caching-service" }, items: [ ], }, @@ -550,10 +585,9 @@ module.exports = { ], }, "user-guide/api-mediation/api-mediation-update-password", - "user-guide/api-mediation-metrics-service", "user-guide/api-mediation/api-mediation-smf", ], - }, + }, ], }, { @@ -564,7 +598,7 @@ module.exports = { { type: "category", label: "Using Zowe CLI", - link: {type:"doc", id:"user-guide/cli-using-usingcli"}, + link: { type: "doc", id: "user-guide/cli-using-usingcli" }, items: [ "user-guide/cli-using-displaying-help", "user-guide/cli-using-command-precedence", @@ -572,34 +606,31 @@ module.exports = { "user-guide/cli-using-issuing-first-command", { type: "category", - label: "Using team profiles", - link: {type:"doc", id:"user-guide/cli-using-using-team-profiles"}, + label: "Using team configuration", + link: { type: "doc", id: "user-guide/cli-using-using-team-profiles" }, items: [ - "user-guide/cli-using-initializing-team-configuration", - "user-guide/cli-using-test-zosmf-connection", - "user-guide/cli-using-team-configuration-application-developers", - "user-guide/cli-using-team-configuration-team-leaders", - "user-guide/cli-using-sharing-team-config-files", + { + type: "category", + label: "Benefits of team configuration", + link: { type: "doc", id: "user-guide/cli-using-benefits-of-team-config" }, + items: [ + "user-guide/cli-using-editing-team-configuration", + "user-guide/cli-using-creating-profiles", + "user-guide/cli-using-sharing-team-config-files", + "user-guide/cli-using-initializing-user-configuration", + ], + }, "user-guide/cli-using-understand-profiles-configs", "user-guide/cli-using-team-managing-credential-security", "user-guide/cli-using-global-storing-properties-automatically", ], }, - { - type: "category", - label: "Configuring daemon mode", - link: {type:"doc", id:"user-guide/cli-using-using-daemon-mode"}, - items: [ - "user-guide/cli-configure-daemon-on-zlinux-os", - ], - }, - "user-guide/cli-using-using-profiles-v1", "user-guide/cli-using-integrating-apiml", "user-guide/cli-using-working-certificates", { type: "category", label: "Using environment variables", - link: {type:"doc", id:"user-guide/cli-using-using-environment-variables"}, + link: { type: "doc", id: "user-guide/cli-using-using-environment-variables" }, items: [ "user-guide/cli-using-formatting-environment-variables", "user-guide/cli-using-setting-environment-variables-in-automation-server", @@ -610,83 +641,85 @@ module.exports = { { type: "category", label: "Zowe CLI plug-ins", - link: {type:"doc", id:"user-guide/cli-extending"}, + link: { type: "doc", id: "user-guide/cli-extending" }, items: [ - "user-guide/cli-swreqplugins", "user-guide/cli-installplugins", "user-guide/cli-cicsplugin", { type: "category", label: "IBM® Db2® Database Plug-in for Zowe CLI", - link: {type:"doc", id:"user-guide/cli-db2plugin"}, + link: { type: "doc", id: "user-guide/cli-db2plugin" }, items: [ "user-guide/cli-db2-install-m1", ], }, "user-guide/cli-ftpplugin", - "user-guide/cli-imsplugin", "user-guide/cli-mqplugin", "user-guide/cli-idfplugin", ], - }, + }, ], - }, + }, { type: "category", label: "Using Zowe Explorer", - link: {type:"doc", id:"user-guide/ze-usage"}, + link: { type: "doc", id: "user-guide/ze-usage" }, items: [ "user-guide/ze-usage-tips", "user-guide/ze-working-with-data-sets", "user-guide/ze-working-with-uss-files", "user-guide/ze-working-with-jobs", + "user-guide/ze-working-with-commands", { type: "category", label: "Zowe Explorer extensions", items: [ { type: "category", - label: "Zowe Explorer CICS Extension", - link: {type:"doc", id:"user-guide/ze-install-zowe-explorer-cics-ext"}, + label: "Using Zowe Explorer CICS Extension", + link: { type: "doc", id: "user-guide/ze-using-zowe-explorer-cics-ext" }, items: [ - "user-guide/ze-using-zowe-explorer-cics-ext", + "user-guide/ze-cics-usage-tips", "user-guide/ze-create-zowe-explorer-cics-ext-profiles", "user-guide/ze-use-cics-resources", "user-guide/ze-override-tls-certs", - "user-guide/ze-cics-usage-tips", - "user-guide/ze-provide-feedback-contribute", ], }, { type: "category", - label: "Zowe Explorer FTP Extension", - link: {type:"doc", id:"user-guide/ze-ftp-install-ze-ftp-ext"}, + label: "Using Zowe Explorer FTP Extension", + link: { type: "doc", id: "user-guide/ze-ftp-using-ze-ftp-ext" }, items: [ - "user-guide/ze-ftp-using-ze-ftp-ext", "user-guide/ze-ftp-supported-functions", - "user-guide/ze-ftp-provide-feedback-contribute", ], }, ], }, ], }, - "user-guide/zowe-chat/chat_use_interact_methods", { type: "category", - label: "Using Zowe IntelliJ Plug-in", - link: {type:"doc", id:"user-guide/intellij-using"}, + label: "Using Zowe Explorer plug-in for IntelliJ IDEA", items: [ + "user-guide/intellij-use-cases", + "user-guide/intellij-settings", "user-guide/intellij-working-sets", + "user-guide/intellij-zos-files", + "user-guide/intellij-uss-files", + "user-guide/intellij-copy-cut", + "user-guide/intellij-jes-explorer", + "user-guide/intellij-tso-cli", ], }, - "user-guide/sdks-using", + "user-guide/sdks-using", + "user-guide/zowe-chat/chat_use_interact_methods", + "user-guide/providing-feedback-and-contributing-client-side", ], }, ], "extending": [ "extend/extend-zowe-overview", - "extend/zowe-conformance-program", + "extend/zowe-conformance-program", { type: "category", label: "Developing server-side components", @@ -725,7 +758,7 @@ module.exports = { { type: "category", label: "Plain Java Enabler", - link: {type:"doc", id:"extend/extend-apiml/onboard-plain-java-enabler"}, + link: { type: "doc", id: "extend/extend-apiml/onboard-plain-java-enabler" }, items: [ "extend/extend-apiml/onboard-plain-java-enabler-external-configuration", "extend/extend-apiml/api-mediation-message-service", @@ -735,13 +768,13 @@ module.exports = { "extend/extend-apiml/onboard-micronaut-enabler", "extend/extend-apiml/onboard-nodejs-enabler", "extend/extend-apiml/onboard-static-definition", - "extend/extend-apiml/custom-metadata", + "extend/extend-apiml/custom-metadata", ] }, { type: "category", label: "API ML Routing Overview", - link: {type:"doc", id:"extend/extend-apiml/api-mediation-routing"}, + link: { type: "doc", id: "extend/extend-apiml/api-mediation-routing" }, items: [ "extend/extend-apiml/implementing-routing-to-the-api-gateway", "extend/extend-apiml/api-mediation-versioning", @@ -751,7 +784,7 @@ module.exports = { { type: "category", label: "Runtime Extensions", - link: {type:"doc", id:"extend/extend-apiml/create-apiml-extension"}, + link: { type: "doc", id: "extend/extend-apiml/create-apiml-extension" }, items: [ "extend/extend-apiml/implement-new-saf-provider" ] @@ -761,7 +794,7 @@ module.exports = { label: "Zowe API Mediation Layer Security", items: [ "extend/extend-apiml/api-medation-sso-integration-extenders", - "extend/extend-apiml/zaas-client", + "extend/extend-apiml/zaas-client", ], }, ], @@ -784,10 +817,10 @@ module.exports = { "extend/extend-desktop/mvd-apptoappcommunication", "extend/extend-desktop/mvd-iframecomm", "extend/extend-desktop/mvd-errorreportingui", + "extend/extend-desktop/mvd-server-config", "extend/extend-desktop/mvd-logutility", - "extend/extend-desktop/mvd-conda", ], - }, + }, ], }, { @@ -798,28 +831,36 @@ module.exports = { { type: "category", label: "Developing for Zowe CLI", - link: {type:"doc", id:"extend/extend-cli/cli-devTutorials"}, + link: { type: "doc", id: "extend/extend-cli/cli-devTutorials" }, items: [ - "extend/extend-cli/cli-setting-up", + { + type: "category", + label: "Tutorials for extenders", + link: { type: "doc", id: "extend/extend-cli/cli-tutorials" }, + items: [ + "extend/extend-cli/cli-setting-up", + "extend/extend-cli/cli-installing-sample-plugin", + "extend/extend-cli/cli-extending-a-plugin", + "extend/extend-cli/cli-developing-a-plugin", + "extend/extend-cli/cli-implement-profiles", + ], + }, + "extend/extend-cli/cli-authentication-mechanisms", "extend/extend-cli/cli-creating-plug-in-lifecycle-actions", - "extend/extend-cli/cli-installing-sample-plugin", - "extend/extend-cli/cli-extending-a-plugin", - "extend/extend-cli/cli-developing-a-plugin", - "extend/extend-cli/cli-implement-profiles", ], }, - + "extend/extend-ze/ze-extensions", "getting-started/user-roadmap-client-sdk", - "extend/extend-sdks", + "extend/extend-sdks", ], - }, + }, ], "troubleshooting": [ { type: "category", label: "Troubleshooting overview", - link: {type:"doc", id:"troubleshoot/troubleshooting"}, + link: { type: "doc", id: "troubleshoot/troubleshooting" }, items: [ "troubleshoot/troubleshoot-zowe-release", "troubleshoot/troubleshoot-check-your-zowe-version", @@ -839,7 +880,7 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe API Mediation Layer", - link: {type:"doc", id:"troubleshoot/troubleshoot-apiml",}, + link: { type: "doc", id: "troubleshoot/troubleshoot-apiml", }, items: [ "troubleshoot/troubleshoot-apiml-error-codes", ], @@ -847,7 +888,7 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe Application Framework", - link: {type:"doc", id:"troubleshoot/app-framework/app-troubleshoot"}, + link: { type: "doc", id: "troubleshoot/app-framework/app-troubleshoot" }, items: [ "troubleshoot/app-framework/app-mustgather", "troubleshoot/app-framework/app-issue", @@ -861,7 +902,7 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe Launcher", - link: {type:"doc", id:"troubleshoot/launcher/launcher-troubleshoot"}, + link: { type: "doc", id: "troubleshoot/launcher/launcher-troubleshoot" }, items: [ "troubleshoot/launcher/launcher-error-codes" ], @@ -876,7 +917,7 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe CLI", - link: {type:"doc", id:"troubleshoot/cli/troubleshoot-cli"}, + link: { type: "doc", id: "troubleshoot/cli/troubleshoot-cli" }, items: [ "troubleshoot/cli/mustgather-cli", "troubleshoot/cli/use-individual-troubleshoot-commands", @@ -890,7 +931,7 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe CLI plug-ins", - link: {type:"doc", id:"troubleshoot/cli/troubleshoot-cli-plugins"}, + link: { type: "doc", id: "troubleshoot/cli/troubleshoot-cli-plugins" }, items: [ "troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in", ], @@ -898,17 +939,17 @@ module.exports = { { type: "category", label: "Troubleshooting Zowe Explorer", - link: {type:"doc", id:"troubleshoot/ze/troubleshoot-ze"}, + link: { type: "doc", id: "troubleshoot/ze/troubleshoot-ze" }, items: [ "troubleshoot/ze/known-ze", "troubleshoot/ze/ze-known-limits", "troubleshoot/ze/ze-issues", ], }, + "troubleshoot/troubleshoot-intellij", "troubleshoot/zowe-chat-troubleshoot/troubleshooting", - "troubleshoot/troubleshoot-intellij", ], - } + } ], "contributing": [ "contribute/roadmap-contribute", @@ -925,7 +966,7 @@ module.exports = { { type: "category", label: "UI Guidelines", - link: {type:"doc", id:"contribute/guidelines-ui/ui"}, + link: { type: "doc", id: "contribute/guidelines-ui/ui" }, items: [ "contribute/guidelines-ui/colors", "contribute/guidelines-ui/typography", @@ -937,38 +978,27 @@ module.exports = { "contribute/contributing", ], "reference": [ - "appendix/zowe-cli-command-reference", + "appendix/server-component-manifest", "appendix/zowe-api-reference", - { - type: "category", - label: "ZWE Server Command Reference", - link: {type:"doc", id:"appendix/zwe_server_command_reference_overview"}, - items: [ - { - type: "autogenerated", - dirName: "appendix/zwe_server_command_reference" - } - ] - }, { type: "category", label: "Zowe Chat command reference", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/zowe-chat-command-reference"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/zowe-chat-command-reference" }, items: [ { type: "category", label: "zos commands", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/zos-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/zos-article" }, items: [ { type: "category", label: "zos job", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/job/job-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/job/job-article" }, items: [ { type: "category", label: "zos job list", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/job/list/list-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/job/list/list-article" }, items: [ "appendix/zowe-chat-command-reference/zos/job/list/zos-job-list-status", ] @@ -978,12 +1008,12 @@ module.exports = { { type: "category", label: "zos dataset", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/dataset/dataset-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/dataset/dataset-article" }, items: [ { type: "category", label: "zos dataset list", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/dataset/list/list-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/dataset/list/list-article" }, items: [ "appendix/zowe-chat-command-reference/zos/dataset/list/zos-dataset-list-status", "appendix/zowe-chat-command-reference/zos/dataset/list/zos-dataset-list-member", @@ -994,12 +1024,12 @@ module.exports = { { type: "category", label: "zos file", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/file/file-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/file/file-article" }, items: [ { type: "category", label: "zos file list", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/file/list/list-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/file/list/list-article" }, items: [ "appendix/zowe-chat-command-reference/zos/file/list/zos-file-list-status", "appendix/zowe-chat-command-reference/zos/file/list/zos-file-list-mounts", @@ -1010,12 +1040,12 @@ module.exports = { { type: "category", label: "zos command", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/command/command-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/command/command-article" }, items: [ { type: "category", label: "zos command issue", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/command/issue/issue-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/command/issue/issue-article" }, items: [ "appendix/zowe-chat-command-reference/zos/command/issue/zos-command-issue-console", ] @@ -1025,12 +1055,12 @@ module.exports = { { type: "category", label: "zos help", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/help/help-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/help/help-article" }, items: [ { type: "category", label: "zos help list", - link: {type:"doc", id:"appendix/zowe-chat-command-reference/zos/help/list/list-article"}, + link: { type: "doc", id: "appendix/zowe-chat-command-reference/zos/help/list/list-article" }, items: [ "appendix/zowe-chat-command-reference/zos/help/list/zos-help-list-command", ] @@ -1041,8 +1071,19 @@ module.exports = { }, ] }, + "appendix/zowe-cli-command-reference", "appendix/zowe-yaml-configuration", - "appendix/server-component-manifest", + { + type: "category", + label: "ZWE Server Command Reference", + link: { type: "doc", id: "appendix/zwe_server_command_reference_overview" }, + items: [ + { + type: "autogenerated", + dirName: "appendix/zwe_server_command_reference" + } + ] + }, "appendix/bill-of-materials", { type: "link", diff --git a/static/stable/Zowe_CLI_Installation_Checklist.xlsx b/static/stable/Zowe_CLI_Installation_Checklist.xlsx index 3f625013e0..41fbaaf054 100644 Binary files a/static/stable/Zowe_CLI_Installation_Checklist.xlsx and b/static/stable/Zowe_CLI_Installation_Checklist.xlsx differ diff --git a/versioned_docs/_version-v2.13.x/user-guide/cli-using-usingcli.md b/versioned_docs/_version-v2.13.x/user-guide/cli-using-usingcli.md index 10c2a421d2..a44a836112 100644 --- a/versioned_docs/_version-v2.13.x/user-guide/cli-using-usingcli.md +++ b/versioned_docs/_version-v2.13.x/user-guide/cli-using-usingcli.md @@ -4,7 +4,11 @@ In this section, learn about how to use Zowe CLI, including connecting to the ma You can use the CLI interactively from a command window on any computer on which it is installed, or run it in a container or automation environment. -**Tip:** If you want to use the CLI together with a screen reader to provide accessibility, we recommend using the Mac™ Terminal application enabled for Accessibility through [System Preferences > Accessibility](https://support.apple.com/zh-sg/guide/terminal/trml1020/mac). On Windows™, adjust the Properties settings in Command Prompt. For other operating systems, or for alternative terminals, check the specification for the terminal to ensure that it meets accessibility requirements. +:::tip + +If you want to use the CLI together with a screen reader to provide accessibility, we recommend using the Mac™ Terminal application enabled for Accessibility through [System Preferences > Accessibility](https://support.apple.com/guide/terminal/use-macos-accessibility-features-trml1020/mac). On Windows™, adjust the Properties settings in Command Prompt. For other operating systems, or for alternative terminals, check the specification for the terminal to ensure that it meets accessibility requirements. + +::: ## Supported CPU architectures, operating systems, and package/resource managers diff --git a/versioned_docs/_version-v2.13.x/user-guide/zowe-getting-started-tutorial.md b/versioned_docs/_version-v2.13.x/user-guide/zowe-getting-started-tutorial.md index dd1ab3f48d..0993c9f8f6 100644 --- a/versioned_docs/_version-v2.13.x/user-guide/zowe-getting-started-tutorial.md +++ b/versioned_docs/_version-v2.13.x/user-guide/zowe-getting-started-tutorial.md @@ -6,6 +6,7 @@ Learn how to start using Zowe components, applications, and plug-ins. - [Using Zowe Desktop](mvd-using.md) - [Using Zowe API Mediation Layer](api-mediation/using-api-mediation-layer.md) +- [Using Zowe IntelliJ Plug-in](intellij-using.md) - [Zowe cross memory server](../user-guide/configure-xmem-server.md) ## Zowe client-side components @@ -18,7 +19,6 @@ Learn how to start using Zowe components, applications, and plug-ins. - [Zowe CLI plug-ins](cli-extending.md) - [Zowe Explorer extensions](ze-using-zowe-explorer-cics-ext.md) -- [Using Zowe IntelliJ Plug-in](intellij-using.md) ### Incubator components