Approver and Notification Administration
Serena XML supports the following approver and notification administration tasks for general use:
-
List Application Approvers - APPROVER APL LIST
-
Download Global Notification File - NOTYFILE SERVICE DOWNLOAD
-
Notify User - USER SERVICE NOTIFY
The syntax that identifies these functions appears in the name attribute of the <service> tag, as follows:
<service name="APPROVER">
<service name="NOTYFILE">
<message name="NOTIFY">
List Application Approvers - APPROVER APL LIST
This function lists authorized approvers for a named application. Both regular and emergency approvers are included in the scope of this function. Approvers assigned to review an application by a customized ChangeMan ZMF exit are omitted. If no approvers are defined for the application, no results are returned.
The Serena XML service/scope/message tags for a message to list application approvers are:
<service name="APPROVER">
<scope name="APL">
<message name="LIST">
These tags appear in both request and reply messages.
APPROVER APL LIST — Requests
All application approver list requests require the application name in the <applName> tag and the approver list type in <approverListType>. Serena XML supports four types of application approver lists:
-
Planned Approvers — Enter "0" (zero) in the <approverListType> tag to request all regular approvers for planned packages in the named application.
-
Unplanned Approvers — Enter "1" in the <approverListType> tag to request all emergency approvers for unplanned packages in the named application.
-
All Approvers — Enter "2" in the <approverListType> tag to request both approver types for the named application.
-
Description of Named Approver — Name the approver entity of interest in the <approverEntity> tag. Enter "2" in the <approverListType> tag to request both approver types. The function returns the named approver’s description and notification information, as defined for the named application.
Data structure details for the <request> tag appear in Exhibit 11-32.
Exhibit 11-32. APPROVER APL LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Required | 1 | String (4), variable | ZMF application name. NOTE: OK to omit trailing blanks. |
| <approverEntity> | Optional | 0 - 1 | String (8), variable | Security system entity ID for desired package approver or group. |
| <approverListType> | Required | 1 | String (1) | Code for type of approver to include in results. Values: 0 = Planned package approvers only. 1 = Unplanned package approvers only. 2 = Both planned & unplanned package approvers. |
APPROVER APL LIST — Replies
The Serena XML reply to a package approver list request returns zero to many <result> tags. Each <result> tag contains a description and notification information for one application approver entity defined to the security package for your system. Individual approver TSO user IDs are not included in the results.
A standard <response> data element follows the last <result> tag, if any, to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. As the last tag returned in the reply message, the <response> tag serves as an end-of-list marker.
Data structure details for the <result> tag follow in Exhibit 11-33.
Exhibit 11-33. APPROVER APL LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Optional | 1 | String (4), fixed | ZMF application name. Same as first 4 bytes of package name. |
| <approvalOrder> | Optional | 0 - 1 | Integer (2), variable | Approval level or sequence assigned to this approver entity for hierarchical approvals. |
| <approverDesc> | Optional | 0 - 1 | String (44), variable | Text description of approver level or function (e.g., project leader, QA manager) for <approverEntity>. |
| <approverEntity> | Optional | 1 | String (8), variable | Security system entity ID of authorized application approver. |
| <approverListType> | Optional | 1 | String (1) | Code for type of approver to include in results. Values: 0 = Planned package approvers only. 1 = Unplanned package approvers only. 2 = Both planned & unplanned package approvers. |
| <isInterfacingApprover> | Optional | 0 - 1 | String (1), variable | Is this an interfacing approver? Y = Yes N = No |
| <notification> | Optional | 0 - 35 | Complex | Describes notifications sent when this approver entity takes an approval action. See Exhibit 11-34. |
The <result> data structure contains zero to many instances of the complex subtag,<notification>, which contains tags of its own. Each <notification> structure identifies a notification agent type and a list of user IDs or email addresses to be used by that agent when sending notifications to the approver entity. Data structure details follow in Exhibit 11-34.
Exhibit 11-34. <notification> Subtag Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <notifierType> | Optional | 0 - 1 | Integer (1) | ZMF code for notification method to use with notifications sent to users in <userList>. Values: 1 = MVSSEND message 4 = Email 5 = SERNET agent email 6 = Batch messaging job |
| <userList> | Optional | 0 - 1 | String (44), variable | List of individual approvers to notify when the named approver entity takes an approval action. List consists of user TSO IDs or E-mail addresses separated by commas. NOTE: TSO user ID required if <notifierType> = 1. NOTE: E-mail addresses required if <notifierType> = 5. |
Download Global Notification File - NOTYFILE SERVICE DOWNLOAD
Serena XML can request a download of the global notification file to your local client system. The request message takes no parameter values. The reply message contains global notification file records.
The Serena XML service/scope/message tags for a message to download the global notification file are:
<service name="NOTYFILE">
<scope name="SERVICE">
<message name="DOWNLOAD">
These tags appear in both request and reply messages.
NOTYFILE SERVICE DOWNLOAD — Requests
The request message for this function contains an empty <request> data element. The <request> tag is required to identify the message as a request rather than a reply.
Note
XML syntax allows both a long form and a short form for empty tags. An empty <request> tag can therefore be coded in one of two ways.
Long form:
<request>
</request>
<request\>
NOTYFILE SERVICE DOWNLOAD — Replies
The reply message for this function returns one <result> data element containing zero to many
Data structure details for the <result> data element appear in Exhibit 11-35.
Exhibit 11-35. NOTYFILE SERVICE DOWNLOAD <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <line> | Optional | 0 - ∞ | String, variable | A bytewise image of one record in the ZMF global notification file. |
Notify User - USER SERVICE NOTIFY
This function sends either a predefined or free-format notification message to one or more users of ChangeMan ZMF. Values for predefined message variables may be substituted either from the request message or from system data maintained by ChangeMan ZMF. Notifications may be sent by any one of the following means:
-
MVS/TSO Send — MVSSEND message to users on the same mainframe LPAR as the XML client that issues the request.
-
Email — E-mail using SMTP
-
Batch — Creates a batch messaging job using ISPF file tailoring, where the appropriate request values and package information are supplied to the file tailoring skeleton in ISPF variables. (Refer to example file tailoring skeleton CMN$$NTF in ChangeMan ZMF.)
The Serena XML service/scope/message tags for a message to notify users are:
<service name="USER">
<scope name="SERVICE">
<message name="NOTIFY">
These tags appear in both request and reply messages.
USER SERVICE NOTIFY — Requests
The user notification request message requires a sender, a recipient, a notification method, and either a <messageType> entry or the actual message content in <textMessage>. Serena XML supports two types of user notifications:
-
Generic Text Message — To send a generic text message, enter a blank character (not a null or empty tag) in <messageType> and supply the free-format text message contents in <textMessage>.
-
Predefined Message — To send a predefined text message, enter the desired message type code in <messageType>. Required variables for the message type may be populated in the Serena XML request, or the <loadPackageInfo> tag can request that ChangeMan ZMF populate their values from the package master.
Data structure details for the <request> tag appear in Exhibit 11-36.
Exhibit 11-36. USER SERVICE NOTIFY <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <actionDate> | Optional | 0 - 1 | Date, yyyymmdd | Date of action taken. Substitute for (Date) variable in predefined message. |
| <actionTime> | Optional | 0 - 1 | Time, hhmmss | Time of action taken. Substitute for (Time) variable in predefined message. |
| <applName> | Optional | 0 - 1 | String (4), variable | ZMF application name. Same as first four bytes of <package>. NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>. NOTE: OK to omit trailing blanks. |
| <cmnSubSystemId> | Optional | 0 - 1 | String (1) | ZMF subsystem ID of started task to process batch messaging job. NOTE: If <notifierType> value = 6, this tag is required. NOTE: Default value is blank. |
| <creator> | Optional | 0 - 1 | String (8), variable | TSO user ID of package creator. Substituted for (Creator) variable in predefined message. |
| <formNumber> | Optional | 0 - 1 | String (3), variable | Online form number to be substituted for (Form) variable in predefined message. |
| <isApprovalOrderEnabled> | Optional | 0 - 1 | String (1) | Substituted for variable in predefined message. Values: Y = Yes, use hierarchical approval order. N = No, don’t use hierarchical approval. |
| <jobCard01> | Optional | 0 - 1 | String (72), variable | First of up to four JCL job cards used with batch messaging job. NOTE: If <notifierType> value = 6, this tag is required. |
| <jobCard02> | Optional | 0 - 1 | String (72), variable | Second of up to four JCL job cards used with batch messaging job. |
| <jobCard03> | Optional | 0 - 1 | String (72), variable | Third of up to four JCL job cards used with batch messaging job. |
| <jobCard04> | Optional | 0 - 1 | String (72), variable | Fourth of up to four JCL job cards used with batch messaging job. |
| <loadPackageInfo> | Optional | 0 - 1 | String (1) | Y = Yes, retrieve info from package master rather than XML request. N = No, don’t retrieve info from package master; use values in XML request. NOTE: Tag is required with value = Y if value in <messageType> is R. NOTE: If Y, <package> also required. |
| <messageType> | Required | 1 | String (1) | Code for predefined message format. Values: Blank = Generic message. 0 = ‘CMN4600I - ChangeMan package (Package) awaits your approval.’ 1 = ‘CMN400I - Package (Package) approved by (User) on (Date) at (Time).’ 2 = ‘CMN400I - Package (Package) backed out by (User) on (Date) at (Time).’ 3 = ‘CMN400I - Package (Package) baselined by (User) on (Date) at (Time).’ |
| 5 = ‘CMN400I - Package (Package) deleted by (User) on (Date) at (Time).’ 7 = ‘CMN400I - Package (Package) distributed by (User) on (Date) at (Time).’ 8 = ‘CMN400I - Package (Package) frozen by (User) on (Date) at (Time).’ 9 = ‘CMN400I - Package (Package) installed by (User) on (Date) at (Time).’ B = ‘CMN400I - Package (Package) rejected by (User) on (Date) at (Time).’ C = ‘CMN400I - Package (Package) cycled by (User) on (Date) at (Time).’ R = ‘CMN4600I - ChangeMan release (Release) awaits your approval.’ NOTE: If blank, tags <textMessage> & <textLength> are also required. NOTE: If value is 0, the <package> tag is also required. NOTE: If value is 1, 2, 3, 7, 8, 9, B, or C, tags <package>, <actionDate>, & <actionTime> are also required. NOTE: If value is 5, tags <package>, <actionDate>, <actionTime>, & <actionType> are also required. Value in <actionType> must be 1. NOTE: If value is R, a release ID must be retrieved via <loadPackageInfo> tag value = Y. |
||||
| <notifierType> | Required | 1 | String (1) | Code for notification method to use with recipients. Values: 1 = MVSSEND message 2 = Email using SMTP 3 = SERNET agent email 4 = Batch messaging job NOTE: If value = 6, tags <skelsName>, <jobCard01>, and <cmnSubSytemID> are also required. |
| <package> | Optional | 0 - 1 | String (10), variable | ZMF name of package. Value substituted for (Package) variable in predefined messages. NOTE: Required if <loadPackageInfo> value is Y. |
| <packageId> | Optional | 0 - 1 | String (6), variable | ZMF package number. Same as last six bytes of <package>. NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>. NOTE: OK to omit leading zeroes. |
| <packageLevel> | Optional | 0 - 1 | String (1) | Code for package complexity or level in hierarchy. Substituted for variable in predefined message. Values: 1 = Simple package 2 = Complex package 3 = Super package 4 = Participating package |
| <packageStatus> | Optional | 0 - 1 | String (1) | Code for status of package in lifecycle. Substituted for variable in predefined message. Values: 1 = Approved 2 = Backed out 3 = Baselined 4 = Complex/super pkg closed 5 = Deleted (memo delete) 6 = Development 7 = Distributed 8 = Frozen 9 = Installed A = Complex/super pkg open B = Rejected C = Temporary change cycle completed |
| <packageTitle> | Optional | 0 - 1 | String (72), variable | Working title of package. Substituted for variable in predefined message. |
| <packageType> | Optional | 0 - 1 | String (1) | Package install type code. Substituted for variable in predefined message. Values: 1 = Planned permanent 2 = Planned temporary 3 = Unplanned permanent 4 = Unplanned temporary |
| <recipient> | Required | 1 | String (44), variable | One or more recipient user IDs or e-mail addresses separated by delimiters, as appropriate for the notification method. NOTE: If <notifierType> value = 1, this tag contains comma-delimited list of TSO user IDs. NOTE: If <notifierType> value = 4 or 5, this tag contains semicolon-delimited list of email addresses. NOTE: If <notifierType> value = 6, tag format depends on batch notification file tailoring skeleton in <skelsName>. |
| <requestorDept> | Optional | 0 - 1 | String (4), variable | Department code of requestor. Substituted for variable in predefined message. |
| <requestorName> | Optional | 0 - 1 | String (25), variable | Name of requestor. Substituted for variable in predefined message. |
| <requestorPhone> | Optional | 0 - 1 | String (15), variable | Phone number of requestor. Substituted for variable in predefined message. |
| <sender> | Required | 1 | String (8), variable | TSO user ID of user taking reported action. Substituted for (User) variable in predefined messages. |
| <skelsName> | Optional | 0 - 1 | String (8), variable | Name of batch notification file tailoring skeleton. Default value is CMN$$NTF. NOTE: If <notifierType> value = 6, this tag is required. |
| <subject> | Optional | 0 - 1 | String (50), variable | Entry for email or batch message "Subject" field. NOTE: Used only if <messageType> value is blank. NOTE: Used only if <notifierType> value is 5 or 6. |
| <textMessage> | Optional | 0 - 1 | String (1024), variable | Free-format text of message. NOTE: Required if value is blank in <messageType>. NOTE: If used, <textLength> tag also required. |
| <workChangeRequest> | Optional | 0 - 1 | String (12), variable | Work order or change request ID. Substituted for variable in predefined message. |
USER SERVICE NOTIFY — Replies
The reply message for this function contains no <result> data elements. It does, however, return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.