feat: change role name and structure

Author: sean-freeman

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

roles/sap_pyrfc/README.md

@@ -0,0 +1,99 @@
+# sap_rfc Ansible Role
+
+The sap_rfc Ansible Role executes SAP RFCs, 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

roles/sap_rfc/README.md

@@ -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)

roles/sap_pyrfc/SUPPLEMENTARY.md renamed to roles/sap_rfc/SUPPLEMENTARY.md

@@ -1,21 +1,21 @@
-pyrfc_first_run: true
+#pyrfc_first_run: true
 
-sap_nwrfc_sdk: nwrfc750P_8-70002752.zip
+#sap_nwrfc_sdk: nwrfc750P_10-70002752.zip
 
-target_function: STFC_CONNECTION
-
-target_parameters:
-  REQUTEXT: "Hello SAP!"
-
-target_connection:
-  ashost: s4hana.poc.cloud
-  sysid: TDT
-  sysnr: "01"
-  client: "400"
-  user: DDIC
-  passwd: Password1
-  lang: EN
+#target_connection:
+#  ashost: s4hana.poc.cloud
+#  sysid: TDT
+#  sysnr: "01"
+#  client: "400"
+#  user: DDIC
+#  passwd: Password1
+#  lang: EN
 #  trace: 3
 #  saprouter: /H/111.22.33.44/S/3299/W/e5ngxs/H/555.66.777.888/H/
 #  gwhost: gateway.poc.cloud
 #  ghserv: gateway.poc.cloud
+
+target_function: STFC_CONNECTION
+
+target_parameters:
+  REQUTEXT: "Hello SAP!"

roles/sap_pyrfc/defaults/main.yml renamed to roles/sap_rfc/defaults/main.yml

@@ -7,9 +7,10 @@
   ansible.builtin.include_tasks: python_pyrfc_discover.yml
   when: not pyrfc_first_run | bool
 
+# Use Ansible Task block to call sap_pyrfc Ansible Module in the Ansible Collection for sap_libs
 # RFC call using variables set by the Ansible Playbook when calling this Ansible Role
 - name: Execute Ansible Module to call PyRFC using the virtualenv Python3
-  community.sap_operations.sap_pyrfc:
+  community.sap_libs.sap_pyrfc:
     function: "{{ target_function }}"
     parameters: "{{ target_parameters }}"
     connection: "{{ target_connection }}"

roles/sap_pyrfc/tasks/main.yml renamed to roles/sap_rfc/tasks/main.yml

@@ -38,7 +38,7 @@
     virtualenv_command: virtualenv
     virtualenv_python: python3
 
-# Use task block to call Ansible Module in the Ansible Collection for sap_operations
+# Use task block to call Ansible Module in the Ansible Collection for sap_launchpad
 - name: Execute Ansible Module to download SAP software
   community.sap_launchpad.software_center_download:
     suser_id: "{{ suser_id }}"