Automated commit 'Update identity-profile-process-identities.yaml description to clearl… (#1629)

* Update identity-profile-process-identities.yaml description to clearly explain when to run it and what operations it performs.

* Update identity-profile-process-identities.yaml

Additional information about this operation.

* Update identity-profile-process-identities.yaml

Another small fix to the description.

* Update identity-profile-process-identities.yaml

another small fix

* Update identity-profile-process-identities.yaml

more fixes

* More description updates' by github action: 8561194679

idn/beta/paths/identities-process.yaml

@@ -4,16 +4,19 @@ post:
     - Identities
   summary: Process a list of identityIds
   description: |
-    You could use this endpoint to:
+    This operation should not be used to schedule your own identity processing or to perform system wide identity refreshes. The system will use a combination of [event-based processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#event-based-processing) and [scheduled processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#scheduled-processing) that runs every day at 8:00 AM and 8:00 PM in the tenant's timezone to keep your identities synchronized. 
+   
+    This endpoint will perform the following tasks:
     1. Calculate identity attributes, including applying or running any rules or transforms (e.g. calculate Lifecycle State at a point-in-time it's expected to change).
     2. Evaluate role assignments, leading to assignment of new roles and removal of existing roles.
     3. Enforce provisioning for any assigned accesses that haven't been fulfilled (e.g. failure due to source health).
     4. Recalculate manager relationships.
     5. Potentially clean-up identity processing errors, assuming the error has been resolved.
     
-    To learn more, refer to the [identity processing documentation](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html).
-
     A token with ORG_ADMIN or HELPDESK authority is required to call this API.
+  externalDocs:
+    description: 'Learn more about manually processing identities here'
+    url: 'https://documentation.sailpoint.com/saas/help/setup/identity_processing.html'
   security:
     - UserContextAuth:
         - "idn:identity:manage"

idn/beta/paths/identity-profile-process-identities.yaml

@@ -6,8 +6,21 @@ post:
   description: >-
     Process identities under the profile
 
+    This operation should not be used to schedule your own identity processing or to perform system wide identity refreshes. The system will use a combination of [event-based processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#event-based-processing) and [scheduled processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#scheduled-processing) that runs every day at 8:00 AM and 8:00 PM in the tenant's timezone to keep your identities synchronized. 
+
+    This should only be run on identity profiles that have the `identityRefreshRequired` attribute set to `true`. If `identityRefreshRequired` is false, then there is no benefit to running this operation. Typically, this operation is performed when a change is made to the identity profile or its related lifecycle states that requires a refresh.
+
+    This operation will perform the following activities on all identities under the identity profile.
+
+    1. Updates identity attribute according to the identity profile mappings.
+    2. Determines the identity's correct manager through manager correlation.
+    3. Updates the identity's access according to their assigned lifecycle state.
+    4. Updates the identity's access based on role assignment criteria.
 
     A token with ORG_ADMIN authority is required to call this API.
+  externalDocs:
+    description: 'Learn more about manually processing identities here'
+    url: 'https://documentation.sailpoint.com/saas/help/setup/identity_processing.html'
   parameters:
     - in: path
       name: identity-profile-id

idn/v3/paths/identity-profile-process-identities.yaml

@@ -6,8 +6,21 @@ post:
   description: >-
     Process identities under the profile
 
+    This operation should not be used to schedule your own identity processing or to perform system wide identity refreshes. The system will use a combination of [event-based processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#event-based-processing) and [scheduled processing](https://documentation.sailpoint.com/saas/help/setup/identity_processing.html?h=process#scheduled-processing) that runs every day at 8:00 AM and 8:00 PM in the tenant's timezone to keep your identities synchronized. 
+
+    This should only be run on identity profiles that have the `identityRefreshRequired` attribute set to `true`. If `identityRefreshRequired` is false, then there is no benefit to running this operation. Typically, this operation is performed when a change is made to the identity profile or its related lifecycle states that requires a refresh.
+
+    This operation will perform the following activities on all identities under the identity profile.
+
+    1. Updates identity attribute according to the identity profile mappings.
+    2. Determines the identity's correct manager through manager correlation.
+    3. Updates the identity's access according to their assigned lifecycle state.
+    4. Updates the identity's access based on role assignment criteria.
 
     A token with ORG_ADMIN authority is required to call this API.
+  externalDocs:
+    description: 'Learn more about manually processing identities here'
+    url: 'https://documentation.sailpoint.com/saas/help/setup/identity_processing.html'
   parameters:
     - in: path
       name: identity-profile-id