Adding information on how to identify job approver (#9374)

* Adding content on how to identify job approver

* Adding code snippets for API calls

* Adding instructions on how to get th workflow ID

* Adding short intro

* Updating obsolete xref

Author: yaningo

jekyll/_cci2/workflows.adoc

@@ -277,6 +277,80 @@ curl --request POST \
   --header "Circle-Token: ${CIRCLE_TOKEN}" \
   --header 'content-type: application/json' \
 ----
+--
+
+
+=== Identify the user who approved a job
+
+To identify the user who approved a job, you can use the CircleCI web app or the API.
+
+[.tab.identify.CircleCI_web_app]
+--
+* If the user signed up via GitHub, the (non-clickable) avatar of the GitHub user appears next to the approval job. Hovering over that avatar brings up a tooltip with the user's name as specified in their GitHub/Bitbucket account settings.
+
+* If the user signed up via email, the anonymous avatar appears next to the approval job; hovering over that avatar brings up a tooltip with the user's email address.
+--
+
+[.tab.identify.API]
+--
+. Set up your API authentication. Steps are available in the xref:api-developers-guide#add-an-api-token[API developers guide].
+. You need the workflow ID so you can use the link:https://circleci.com/docs/api/v2/index.html#operation/listWorkflowJobs[get a workflow's jobs] endpoint to get the user ID. You can get the workflow ID using xref:variables#[pipeline values or environment variables], or by xref:outbound-webhooks#[receiving webhooks] or link:https://circleci.com/docs/api/v2/index.html#tag/Pipeline/operation/listWorkflowsByPipelineId[polling the API]
++
+[,shell]
+----
+curl --request GET \
+  --url https://circleci.com/api/v2/workflow/<workflow-ID>/job \
+  --header "Circle-Token: ${CIRCLE_TOKEN}" \
+  --header 'content-type: application/json' \
+----
+
+. In the JSON response, take note of the value associated with the `approved_by` key. This is the user ID of the user who approved the job.
++
+[,json]
+----
+ "name" : "hold",
+ "project_slug" : "gh/<org>/<project>",
+ "approved_by" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
+ "type" : "approval",
+ "status" : "success",
+----
+
+. Then use the link:https://circleci.com/docs/api/v2/index.html#operation/getUser[user information] endpoint to get the username or email address.
++
+[,shell]
+----
+curl --request GET \
+  --url https://circleci.com/api/v2/user/<user-ID> \
+  --header "Circle-Token: ${CIRCLE_TOKEN}" \
+  --header 'content-type: application/json' \
+----
+
+** If the user who approved the job signed up via GitHub or Bitbucket, the response from the user information endpoint will have the following format:
++
+[,json]
+----
+ {
+   "name" : "User’s name as specified in their VCS account settings",
+   "login" : "VCS username",
+   "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
+ }
+----
+
+** If the user who approved the job signed up via email, the response from the user information endpoint will have the following format:
++
+[,json]
+----
+ {
+   "name" : "Email address",
+   "login" : "Email address",
+   "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
+ }
+----
+
+TIP: You can find detailed instructions in link:https://support.circleci.com/hc/en-us/articles/360044820493-How-to-Find-hold-Step-Approver-in-a-Workflow[this support article]
+
+
+
 --
 
 === Cancel a job