CMCI Feedback Support

- Added support for cmci feedback include BAS feedback errors
- Added new integration test with BAS installation error to cover feedback support
- Updated names on integration tests
- Updated cmci_variables template and all int tests to explicitly use secure/ non-secure ports
- Removed copyright statements from ignore.txt files: Can't have a # on the first line of those files

Author: Tom-Latham

plugins/module_utils/cmci.py

@@ -44,8 +44,8 @@
 COMPLEX_FILTER = 'complex_filter'
 SCHEME = 'scheme'
 INSECURE = 'insecure'
+FEEDBACK = 'feedback'
 TIMEOUT = 'timeout'
-
 GET_PARAMETERS = 'get_parameters'
 
 
@@ -152,6 +152,33 @@ def is_alphanumeric(value):
     return re.match('^([A-Za-z0-9]{1,100})$', value, flags=0)
 
 
+def read_node(node):
+    result = [
+        OrderedDict(
+            # Copy feedback from result, stripping @ from attributes
+            # Feedback nodes can contain error types with further information
+            [(k[1:], v) if k[0] == '@'
+             else read_error_detail(k, v)
+             for k, v in n.items()]
+        ) for n in node
+    ]
+    return result
+
+
+def read_error_detail(key, value):
+    # Xmltodict parses inner error types as Dicts when there is only one item in it even though it may well be a list
+    # if multiple results were returned. If we find a dict here, wrap it in a list so we can account for only one result or many
+    # being returned
+    if not isinstance(value, list):
+        value = [value]
+    return key, \
+        [
+            OrderedDict(
+                [(k[1:], v) for k, v in error.items()]
+            ) for error in value
+        ]
+
+
 class AnsibleCMCIModule(object):
 
     def __init__(self, method):
@@ -364,12 +391,13 @@ def handle_response(self, response_dict):  # type: (Dict) -> None
                 records_node = response_node['records']
                 resource_type = self._p[TYPE].lower()
                 if resource_type in records_node:
-                    records = records_node[resource_type]
-                    # Copy records in result, stripping @ from attributes
-                    self.result['records'] = [
-                        {k[1:]: v for k, v in record.items()}
-                        for record in records
-                    ]
+                    self.result['records'] = read_node(records_node[resource_type])
+
+            if 'errors' in response_node:
+                errors_node = response_node['errors']
+                if FEEDBACK in errors_node:
+                    feedback = errors_node[FEEDBACK]
+                    self.result[FEEDBACK] = read_node(feedback)
 
             # Non-OK CPSM responses fail the module
             if cpsm_response_code != 1024:
@@ -534,7 +562,10 @@ def _do_request(self):  # type: () -> Dict
                 process_namespaces=True,
                 namespaces=namespaces,
                 # Make sure we always return a list for the resource node
-                force_list=(self._p.get(TYPE).lower(),)
+                force_list=(
+                    self._p.get(TYPE).lower(),
+                    FEEDBACK
+                )
             )
 
             return r
@@ -674,7 +705,7 @@ def _get_complex_filter(self, i, path):
             if not is_alphanumeric(attribute):
                 self._fail(
                     "Filter attribute with value {0} was not valid. Valid characters are A-Z a-z 0-9."
-                        .format(attribute)
+                    .format(attribute)
                 )
 
             value = escape_quotes(value)
@@ -685,7 +716,6 @@ def _get_complex_filter(self, i, path):
             else:
                 return attribute + operator + '\'' + value + '\''
 
-
     def _convert_filter_operator(self, operator, path):
         if operator in ['<', 'LT']:
             return '<'

plugins/modules/cmci_action.py

@@ -244,6 +244,239 @@
       description: The URL used for the request.
       returned: success
       type: str
+feedback:
+    description: Diagnostic data from FEEDBACK records associated with the request
+    returned: cmci error
+    type: list
+    elements: dict
+    contains:
+        action:
+            description: The name of the action that has failed.
+            returned: cmci error
+            type: str
+        attribute1:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        attribute2:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        attribute3:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        attribute4:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        attribute5:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        attribute6:
+            description: The name of one of up to six attributes associated with the error.
+            returned: cmci error
+            type: str
+        eibfn:
+            description: The function code associated with the request.
+            returned: cmci error
+            type: str
+        eibfn_alt:
+            description: The name of the function associated with the request.
+            returned: cmci error
+            type: str
+        errorcode:
+            description: The CICSPlex® SM error code associated with the resource.
+            returned: cmci error
+            type: str
+        eyu_cicsname:
+            description: The name of the CICS region or CICSplex associated with the error.
+            returned: cmci error
+            type: str
+        keydata:
+            description: A string of data that identifies the instance of a resource associated with the error.
+            returned: cmci error
+            type: str
+        resp:
+            description: The CICS RESP code or the CICSPlex SM API EYUDA response code as a numeric value.
+            returned: cmci error
+            type: str
+        resp2:
+            description: The CICS RESP2 code or the CICSPlex SM API EYUDA reason code as a numeric value.
+            returned: cmci error
+            type: str
+        resp_alt:
+            description: >
+                The text equivalent for the resp value. For example, the text equivalent of a resp value of 16 is INVREQ.
+            returned: cmci error
+            type: str
+        installerror:
+            description: >
+                Contains diagnostic data from a BINSTERR record associated with a CICS® management client interface PUT install request.
+            returned: cmci error
+            type: list
+            elements: dict
+            contains:
+                eibfn:
+                    description: The function code associated with the request.
+                    returned: cmci error
+                    type: str
+                eyu_cicsname:
+                    description: The name of the CICS region or CICSplex associated with the installation error.
+                    returned: cmci error
+                    type: str
+                cresp1:
+                    description: The CICS RESP code or the CICSPlex® SM API EYUDA response code as a numeric value.
+                    returned: cmci error
+                    type: str
+                cresp2:
+                    description: The CICS RESP2 code or the CICSPlex SM API EYUDA reason code as a numeric value.
+                    returned: cmci error
+                    type: str
+                errorcode:
+                    description: The CICSPlex SM error code associated with the resource.
+                    returned: cmci error
+                    type: str
+                ressname:
+                    description: The name of the resource associated with the error.
+                    returned: cmci error
+                    type: str
+                resver:
+                    description: The version number of the resource associated with the error.
+                    returned: cmci error
+                    type: str
+        inconsistentscope:
+            description: >
+                Contains diagnostic data from a BINCONSC record associated with a CICS® management client interface PUT request.
+            returned: cmci error
+            type: list
+            elements: dict
+            contains:
+                eibfn:
+                    description: The function code associated with the request.
+                    returned: cmci error
+                    type: str
+                eyu_cicsname:
+                    description: The name of the CICS region or CICSplex associated with the installation error.
+                    returned: cmci error
+                    type: str
+                erroroperation:
+                    description: A numeric value that identifies the operation being performed when the error occurred.
+                    returned: cmci error
+                    type: str
+                errorcode:
+                    description: The CICSPlex® SM error code associated with the resource.
+                    returned: cmci error
+                    type: str
+                targetassignment:
+                    description: The assignment for the target scope.
+                    returned: cmci error
+                    type: str
+                targetdescription:
+                    description: The resource description for the target scope.
+                    returned: cmci error
+                    type: str
+                relatedassignment:
+                    description: The resource assignment for the related scope.
+                    returned: cmci error
+                    type: str
+                relateddescription:
+                    description: The resource description for the related scope.
+                    returned: cmci error
+                    type: str
+                relatedscope:
+                    description: The name of the related scope.
+                    returned: cmci error
+                    type: str
+        inconsistentset:
+            description: >
+                Contains diagnostic data from a BINCONRS record associated with a CICS® management client interface PUT request.
+            returned: cmci error
+            type: list
+            elements: dict
+            contains:
+                candidatename:
+                    description: The name of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidateversion:
+                    description: The version number of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidategroup:
+                    description: The resource group of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidateassignment:
+                    description: The assignment of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidatedescription:
+                    description: The description of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidateusage:
+                    description: The assignment usage of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidatesystemgroup:
+                    description: The system group of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidatetype:
+                    description: The system type of the candidate resource.
+                    returned: cmci error
+                    type: str
+                candidateoverride:
+                    description: The assignment override of the candidate resource.
+                    returned: cmci error
+                    type: str
+                eyu_cicsname:
+                    description: The name of the CICS region associated with the installation error.
+                    returned: cmci error
+                    type: str
+                erroroperation:
+                    description: >
+                        A numeric value that identifies that the operation being performed when the error occurred
+                    returned: cmci error
+                    type: str
+                existingname:
+                    description: The name of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingversion:
+                    description: The version number of the existing resource.
+                    returned: cmci error
+                    type: str
+                existinggroup:
+                    description: The resource group of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingassignment:
+                    description: The assignment of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingdescription:
+                    description: The description of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingusage:
+                    description: The assignment usage of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingsystemgroup:
+                    description: The system group of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingtype:
+                    description: The system type of the existing resource.
+                    returned: cmci error
+                    type: str
+                existingoverride:
+                    description: The assignment override of the existing resource.
+                    returned: cmci error
+                    type: str
 """