Doc Changes

-Doc changes in accordance with changes to PR#57 as well as comments in this PR. -Mostly wording and naming changes, and removal of clear_running_userid Signed-off-by: Elijah Swift <elijah.swift@ibm.com>
ambitus · Dec 20, 2023 · 26053bc · 26053bc
1 parent 80b4878
commit 26053bc
Show file tree

Hide file tree

Showing 7 changed files with 65 additions and 88 deletions.
diff --git a/common/check_for_and_setup_RACF_authorizations.md b/common/check_for_and_setup_RACF_authorizations.md
diff --git a/common/downstream_fatal_error.md b/common/downstream_fatal_error.md
@@ -11,17 +11,17 @@ Understanding the `DownstreamFatalError` exception.
 &nbsp;
 
 {: .note }
-> _pyRACF requires a response xml string from an internal call to the IRRSMO00 callable service to provide proper output. If the response string that pyRACF receives is empty, or if IRRSMO00 indicates a failing return code, pyRACF raises a `DownstreamFatalError` and terminates processing the response from IRRSMO00._
+> _pyRACF expects IRRSMO00 to return a string containing XML data. If IRRSMO00 returns an empty string, or if the **SAF Return Code** in the result XML is greater than `4`, `DownstreamFatalError` is raised._
 
 &nbsp;
 
-After executing any operation, pyRACF expects a non-empty response string from IRRSMO00 that indicates a RACF command image was built and processed in order to parse such a response and surface information back to the user. When pyRACF detects an empty response string, or a return code indicating an issue with command image processing, a `DownstramFatalError` is raised and processing terminates. It is possible that the command was executed prior to reaising this error, but this is not the case for any known causes of this error.
+pyRACF expects IRRSMO00 to return a non-empty response string after processing a request. If IRRSMO00 returns an empty response string or the **SAF Return Code** is greater than `4`, indicating that there was an issue with command image processing, a `DownstramFatalError` will be raised. It is possible that RACF commands are executed in this situation, but this is not the case for any known causes of this error.
 
 ## RACF Authorizations
 
 &nbsp;
 
-A common cause of this error is that the user does not have proper RACF authorizations as outlined in [our dependencies note](../../index). One of the possible failures is `READ` authority to the `IRR.IRRSMO00.PRECHECK` resource in the `XFACILIT` class, which is required for `set` or `alter` operations. If you are not certain if you have this authority or if this has been established in your environment, please consult our [Check for & set up RACF Authorizations](../check_for_and_setup_RACF_authorizations) documentation. The other possibility is `ALTER` authority to the `userid.IRRSMO00` resource in the `SURROGAT` class, which is required to run pyRACF commands as another userid. Please review our [run as userid](../run_as_userid) documentation for more information on this feature.
+A common cause of this error is that the user does not have the proper RACF authorizations as outlined in [our dependencies note](../../index). One of the possible failures is the user not having `READ` authority to the `IRR.IRRSMO00.PRECHECK` resource in the `XFACILIT` class, which is required for `set` or `alter` operations. If you are not certain if you have this authority or if this has been established in your environment, please consult our [Check for & set up RACF Authorizations](../setup_precheck) documentation. Another possibility is the user not having `ALTER` authority to the `userid.IRRSMO00` resource in the `SURROGAT` class, which is required to run pyRACF commands as another userid. Please review our [run as userid](../run_as_userid) documentation for more information on this feature.
 
 ###### Python Script
 ```python
@@ -32,7 +32,7 @@ user_admin = UserAdmin()
 
 try:
     user_admin.set_uid("squidwrd", 123456)
-except AddOperationError as e:
+except DownstreamFatalError as e:
     print(e.message)
 ```
 
@@ -57,7 +57,7 @@ user_admin = UserAdmin(run_as_userid="ESWIFT")
 
 try:
     user_admin.set_uid("squidwrd", 123456)
-except AddOperationError as e:
+except DownstreamFatalError as e:
     print(e.message)
 ```
 
@@ -77,7 +77,7 @@ For the `run_as_userid` feature, you must have at least UPDATE access to `ESWIFT
 
 &nbsp;
 
-As stated, this error can also appear if IRRSMO00 raises a problem with data passed in from pyRACF. This may happen when pyRACF receives data or data-types that do not align with use-cases for the traits in use. In this case, or others where a response is returned from IRRSMO00, you can review the initial command as well as error messages and information in the `result` dictionary as a part of the error.
+As stated, this error can also appear if there is a problem with the data pyRACF passes to IRRSMO00. In this situation, you can review the `request_xml` and the `result_dictionary`, which are stored as attributes in the `DownstreamFatalError` exception object for more information.
 
 ###### Python Script
 ```python
@@ -88,7 +88,7 @@ user_admin = UserAdmin()
 
 try:
     user_admin.alter("squidwrd", traits={"base:special": "STRING"})
-except AddOperationError as e:
+except DownstreamFatalError as e:
     print(e.message)
 ```
 

diff --git a/common/run_as_userid.md b/common/run_as_userid.md
@@ -3,24 +3,27 @@ layout: default
 parent: Common
 ---
 
-# Run as UserID
+# Run as Userid
 
-Run pyRACF commands as another UserID.
+Run pyRACF commands as another user.
 {: .fs-6 .fw-300 }
 
 &nbsp;
 
-{: .experimental }
-> _This functionality is **Experimental** and is subject to major changes and even being removed entirely._
+{: .note}
+> _Changes made using the functionality described here are scoped to the target "Admin" object instance._
 
 &nbsp;
 
-{: .note}
-> _Changes made using the functionality described here are scoped to the target "Admin" object instance._
+{: .warning}
+> _In order to use `run_as_userid`, the caller must have `UPDATE` access to the `userid.IRRSMO00` resource in the `SURROGAT` class, where `userid` represents the specific userid you wish to execute commands as. Further information can be found outlined in [our dependencies note](../../index)._
+
+&nbsp;
+
+The **Running Userid** can be set using the `run_as_userid` class attribute on any "Admin" object as shown in the below example. The **Running Userid** can also be set using the `set_running_userid()` function, which is a class function available on all "Admin" objects.
 
 &nbsp;
 
-pyRACF can now leverage a feature of IRRSMO00 where commands can be run under a specified userid. In order to take advantage of this feature, the caller must have `UPDATE` access to the `userid.IRRSMO00` resource in the `SURROGAT` class, where userid represents the specific userid you wish to execute commands as. Further information can be found outlined in [our dependencies note](../../index).
 
 ## Example
 
@@ -29,7 +32,7 @@ pyRACF can now leverage a feature of IRRSMO00 where commands can be run under a
 from pyracf import UserAdmin
 
 user_admin = UserAdmin(run_as_userid="squidwrd")
-# Any future commands would be run under squidwrd's authority
+# All subsequent requests will be made using squidwrd's authority.
 ```
 
 ## `SecurityAdmin.set_running_userid()`
@@ -49,15 +52,15 @@ def set_running_userid(
 
 &nbsp;
 
-Set the **z/OS userid** this Admin object will use to run pyRACF commands.
+Set the **z/OS userid** this "Admin" object will use to run pyRACF commands.
 
 #### 📥 Parameters
 * `new_userid`<br>
-  The **z/OS userid** this Admin object will use to run pyRACF commands. If you pass in `None`, this will clear any userid previously set for this Admin object.
+  The **z/OS userid** this "Admin" object will use to run pyRACF commands. If you pass in `None`, this will clear any userid previously set for this "Admin" object.
 
 #### ❌ Raises
 * `UserIdError`<br>
-  Raises `UserIdError` when the **z/OS userid** passed is not a valid string from 1 to 8 characters in length (or `None`).
+  Raises `UserIdError` when the **z/OS userid** provided is not a string value between 1 to 8 characters in length.
 
 #### 💻 Example
 
@@ -67,36 +70,17 @@ from pyracf import UserAdmin
 
 user_admin = UserAdmin()
 user_admin.set_running_userid("squidwrd")
-# Any future commands would be run under squidwrd's authority
+# All subsequent requests will be made using squidwrd's authority.
 ```
 
-## `SecurityAdmin.clear_running_userid()`
-
-```python
-def clear_running_userid(self) -> None:
-```
-
-#### 📄 Description
-
-&nbsp;
-
-{: .experimental }
-> _This functionality is **Experimental** and is subject to major changes and even being removed entirely._
-
-&nbsp;
-
-Clear the **z/OS userid** this Admin object will use to run pyRACF commands.
-
-#### 💻 Example
-
 ###### Python REPL
 ```python 
 from pyracf import UserAdmin
 
 user_admin = UserAdmin(run_as_userid="squidwrd")
-# Any commands run here would be run under squidwrd's authority
-user_admin.clear_running_userid()
-# Any future commands would be run under the calling user's authority
+# All subsequent requests will be made using squidwrd's authority.
+user_admin.set_running_userid(None)
+# All subsequent requests will be made using the calling user's authority.
 ```
 
 ## `SecurityAdmin.get_running_userid()`
@@ -109,12 +93,7 @@ def get_running_userid(self) -> None:
 
 &nbsp;
 
-{: .experimental }
-> _This functionality is **Experimental** and is subject to major changes and even being removed entirely._
-
-&nbsp;
-
-Obtain the **z/OS userid** this Admin object will use to run pyRACF commands.
+Obtain the **z/OS userid** this "Admin" object will use to run pyRACF commands.
 
 #### 💻 Example
 

diff --git a/common/security_request_error.md b/common/security_request_error.md
@@ -19,7 +19,8 @@ When the **Return Code** of a **Security Result** returned by IRRSMO00 is **NOT*
 
 &nbsp;
 
-For an understanding of return or reason codes returned from IRRSMO00, you can review [IRRSMO00's Return and Reason Codes documentation]](https://www.ibm.com/docs/en/zos/2.3.0?topic=operations-return-reason-codes). The 'Messages' list shown in the sample below also contains any error messages or other such information. 
+{: .note}
+> _For an understanding of IRRSMO00 return and reason codes, see the [IRRSMO00 Return and Reason Codes](https://www.ibm.com/docs/en/zos/3.2.0?topic=operations-return-reason-codes) documentation._
 
 ###### Python Script
 ```python

diff --git a/common/setup_precheck.md b/common/setup_precheck.md
@@ -0,0 +1,34 @@
+---
+layout: default
+parent: Common
+---
+
+# Setup Precheck
+
+How to set up and check IRRSMO00 precheck configuration.
+{: .fs-6 .fw-300 }
+
+&nbsp;
+
+In order to use `set` or `alter` functions in pyRACF, users must have `READ` authority to the `IRR.IRRSMO00.PRECHECK` resource as outlined in [our dependencies note](../../index).
+
+&nbsp;
+
+A function called `setup_precheck` is included with pyRACF to help streamline this process. You can use this function to verify your level of access, or define the `IRR.IRRSMO00.PRECHECK` profile with no universal access.`
+
+## Example
+
+###### Python Script
+```python
+from pyracf import setup_precheck
+
+setup_precheck()
+```
+
+###### Console Output
+```
+'IRR.IRRSMO00.PRECHECK' is already defined, and you already have 'ALTER' access!
+You are ready to start using pyRACF!
+Please ensure other users of pyRACF also have at least 'READ' access.
+Review our documentation at https://ambitus.github.io/pyracf/ as well!
+```
diff --git a/common/userid_error.md b/common/userid_error.md
@@ -10,7 +10,7 @@ Understanding the `UserIdError` exception.
 
 &nbsp;
 
-When a caller specifies a **z/OS userid** for pyRACF to run commands under, an `UserIdError` will be raised if the specified **z/OS userid** is not a string from 1 to 8 characters in length. An `UserIdError` can be handled as follows.
+When the **Running Userid** is being set through an "Admin" object constructor or the `set_running_userid()` function on an `"Admin"` object, a `UserIdError` will be raised if the specified **z/OS userid** is not a string between 1 to 8 characters in length. A `UserIdError` can be handled as follows.
 
 ###### Python Script
 ```python

diff --git a/index.md b/index.md
@@ -61,11 +61,8 @@ Python interface into the RACF management application programming interface.
 
 &nbsp;
 
-[Download & Install From GitHub](https://github.com/ambitus/pyracf/releases)
-
-&nbsp;
-
-[Check for & set up RACF Authorizations](../common/check_for_and_setup_RACF_authorizations)
+1. [Download & Install From GitHub](https://github.com/ambitus/pyracf/releases)
+2. [IRRSMO00 Precheck Setup](../common/setup_precheck)
 
 ### Use