Merge pull request #9 from sean-freeman/main

feat: change role name and structure

Author: sean-freeman

README.md

@@ -16,6 +16,7 @@ This Ansible Collection executes various SAP Systems operational tasks, includin
 - **SAP administration tasks**
   - Start/Stop of SAP HANA and SAP NetWeaver (in any configuration)
   - Update SAP profile files
+  - Execute SAP RFCs
 
 ## Contents
 
@@ -38,6 +39,7 @@ Within this Ansible Collection, there are various Ansible Roles and Ansible Modu
 | [sap_fapolicy](/roles/sap_fapolicy) | update service `fapolicyd` for generic / sap nw / sap hana related uids |
 | [sap_firewall](/roles/sap_firewall) | update service `firewalld` for generic / sap nw / sap hana related ports |
 | [sap_profile_update](/roles/sap_profile_update) | update default and instance profiles |
+| [sap_rfc](/roles/sap_rfc) | executes SAP RFCs |
 | [sap_rhsm](/roles/sap_rhsm) | Red Hat subscription manager registration |
 
 #### Ansible Modules

galaxy.yml

@@ -1,3 +1,5 @@
+---
+
 ### REQUIRED
 # The namespace of the collection. This can be a company/brand/organization or product namespace under which all
 # content lives. May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with
@@ -40,19 +42,20 @@ tags: []
 # collection label 'namespace.name'. The value is a version range
 # L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version
 # range specifiers can be set and are separated by ','
-dependencies: {}
+dependencies:
+  community.sap_libs: '*'
 
 # The URL of the originating SCM repository
-repository: http://example.com/repository
+repository: https://github.com/sap-linuxlab/community.sap_operations
 
 # The URL to any online docs
-documentation: http://docs.example.com
+documentation: https://github.com/sap-linuxlab/sap-linuxlab.github.io/blob/master/README.md
 
 # The URL to the homepage of the collection/project
-homepage: http://example.com
+homepage: https://sap-linuxlab.github.io
 
 # The URL to the collection issue tracker
-issues: http://example.com/issue/tracker
+issues: https://github.com/sap-linuxlab/community.sap_operations/issues
 
 # A list of file glob-like patterns used to filter any files or directories that should not be included in the build
 # artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This

playbooks/sample-sap-pyrfc.yml renamed to playbooks/sample-sap-rfc.yml

@@ -5,7 +5,7 @@
   vars:
     suser_id: 'S00000000'
     suser_password: 'password'
-    sap_nwrfc_sdk: nwrfc750P_8-70002752.zip
+    sap_nwrfc_sdk: nwrfc750P_10-70002752.zip
     reuse_connection:
       ashost: s4hana.poc.cloud
       sysid: TDT
@@ -29,7 +29,7 @@
         REQUTEXT: 'Hello SAP!'
       target_connection: "{{ reuse_connection }}"
     include_role:
-      name: community.sap_operations.sap_pyrfc
+      name: community.sap_operations.sap_rfc
     register: sap_rfc_output1
 
   - name: DEBUG - Output of STFC_CONNECTION
@@ -47,7 +47,7 @@
           - COLUMN0: test
       target_connection: "{{ reuse_connection }}"
     include_role:
-      name: community.sap_operations.sap_pyrfc
+      name: community.sap_operations.sap_rfc
     register: sap_rfc_output2
 
   - name: DEBUG - Output of STFC_STRUCTURE

plugins/module_utils/pyrfc_handler.py

@@ -0,0 +1,99 @@
+# sap_rfc Ansible Role
+
+The sap_rfc Ansible Role executes an SAP Remote Function Call (RFC), and performs setup as necessary ([`PyRFC`](https://github.com/SAP/PyRFC) open source by SAP, and [`SAP NWRFC SDK`](https://support.sap.com/en/product/connectors/nwrfcsdk.html)).
+
+## Ansible Role Overview
+
+The sap_rfc Ansible Role uses:
+- the Ansible Module `sap_pyrfc` from the Ansible Collection `sap_libs`, which leverages the open-source [`PyRFC`](https://github.com/SAP/PyRFC) bindings for the proprietary [`SAP NWRFC SDK`](https://support.sap.com/en/product/connectors/nwrfcsdk.html).
+- the Ansible Module `software_center_download` from the Ansible Collection `sap_launchpad`, which on first-run is used to download the [`SAP NWRFC SDK`](https://support.sap.com/en/product/connectors/nwrfcsdk.html).
+
+Appropriate target SAP System user authorizations are required for the execute of the RFCs, and on first-run to obtain the [`SAP NWRFC SDK`](https://support.sap.com/en/product/connectors/nwrfcsdk.html) an SAP User ID with download privileges is required.
+
+The Ansible Role does not contain any system-altering RFCs by default when executed.
+
+The Ansible Task variables define the RFC actions to be executed. Examples are given below.
+
+## Ansible Role Requirements and Dependencies
+
+### Dependencies on other Ansible Roles
+
+To execute successfully, this Ansible Role is dependant on the Ansible Collections:
+- `community.sap_launchpad` on first run
+- `community.sap_libs` for every run
+
+The first run will setup Python altinstall, subsequent runs on the same host will re-use the Python altinstall where PyRFC enabled. This is to protect the System default Python installation from additional or altered versions of Python Packages.
+
+### Operating System
+
+This role has been tested on target systems using RHEL 8.x, and is designed for Linux operating systems.
+
+This role has not been tested and amended for SAP NetWeaver Application Server instantiations on IBM AIX or Windows Server.
+
+Assumptions for executing this role include:
+
+- The target host has access to the SAP System (i.e. the SAP NetWeaver Application Server instance)
+- Registered OS License and OS Package repositories are available (from the relevant content delivery network of the OS vendor)
+
+## Examples
+
+A sample [Ansible Playbook for using the sap_rfc Ansible Role](../../playbooks/sample-sap-rfc.yml) is provided, which provides:
+
+- Ansible Vars for SAP User ID with download privileges for first-run
+- Ansible Vars for SAP System connection details and user authorization
+
+The Ansible Role is designed to provide for all different RFCs. Therefore, the RFC parameters _(IMPORTING, EXPORTING, CHANGING)_ can accept the following data types:
+
+- Data elements (string, integer etc.)
+- ABAP Structure
+- ABAP Table
+
+These RFC parameter data elements are mapped to the equivilant Python data type (e.g. string, integer, dictionary, list). Examples of these are shown below.
+
+### Examples of Ansible Task variables for different RFC parameters
+
+**RFC parameter requires a data element:**
+
+- Commonly string or integer
+- For this input type the PyRFC Python module requires a Python string or integer
+- Ansible Task must declare the parameter name and use a YAML variable
+
+`Ansible Task code example for data element:`
+```yaml
+target_parameters:
+  VAR: 'ECHO'
+```
+
+**RFC parameter requires an ABAP Structure:**
+
+- For this input type the PyRFC Python module requires a Python Dictionary.
+- Ansible Task must declare the parameter name and use a YAML dictionary (key:value)
+
+`Ansible Task code example for ABAP Struture:`
+```yaml
+target_parameters:
+  IMPORTSTRUCT:
+    RFCFLOAT: 1.1
+    RFCCHAR1: 'A'
+```
+
+**RFC requires an ABAP Table:**
+
+- For this input type the PyRFC Python module requires a Python List.
+- The Ansible Task must declare the parameter name and use a YAML list
+
+`Ansible Task code example for ABAP Table:`
+```yaml
+target_parameters:
+  RFCTABLE:
+    - COLUMN0: SAP
+    - COLUMN1: 1.23
+```
+
+## Supplementary information
+
+The [Supplementary information](./SUPPLEMENTARY.md) provides:
+- Context of SAP NWRFC SDK and PyRFC
+  - Explanation of samples from SAP NWRFC SDK
+- Brief explanation of SAP RFCs
+- Security concerns with RFCs and SAP Systems

plugins/modules/sap_pyrfc.py

@@ -1,4 +1,4 @@
-# Supplementary information for sap_pyrfc Ansible Role
+# Supplementary information for sap_rfc Ansible Role
 
 ## Brief explanation of SAP RFCs
 
@@ -44,7 +44,7 @@ Other connectors/bindings to have previously existed but are infrequently used w
 
 This additional context is to avoid confusion. By default the SAP NetWeaver RFC SDK includes two sample ALE programs (rfcexec or startrfc) as reference implementations which support the SAP IDoc scenario.
 
-Neither of these sample programs are used by sap_pyrfc Ansible Role or the underlying PyRFC bindings.
+Neither of these sample programs are used by sap_rfc Ansible Role or the underlying sap_pyrfc Ansible Module and the PyRFC bindings.
 
 These sample ALE programs appear in documentation available on help.sap.com under the IDoc Interface/ALE section:
 - Using startrfc, [SAP NetWeaver AS - IDoc Interface/ALE - Inbound: Triggering the SAP System](https://help.sap.com/viewer/8f3819b0c24149b5959ab31070b64058/7.52.3/en-US/4b4c43dd3b71265ce10000000a421937.html)