Merge branch 'main' into release-updatecenterv2-publicpreview

Author: v-alje

articles/active-directory/app-provisioning/media/workday-pronoun-data/enable-pronoun-display-preference.png

@@ -69,6 +69,10 @@ items:
         href: export-import-provisioning-configuration.md  
       - name: Provisioning reports
         href: ../reports-monitoring/concept-provisioning-logs.md?context=%2fazure%2factive-directory%2fapp-provisioning%2fcontext%2fapp-provisioning-context
+    - name: Workday provisioning scenarios
+      items:
+      - name: Retrieve pronoun information
+        href: workday-retrieve-pronoun-information.md
     - name: Troubleshoot application provisioning
       items:
       - name: Known issues

articles/active-directory/app-provisioning/media/workday-pronoun-data/get-workers-response-with-pronoun.png

@@ -0,0 +1,94 @@
+---
+title: Retrieve pronoun information from Workday
+description: Learn how to retrieve pronoun information from Workday
+services: active-directory
+author: kenwith
+manager: rkarlin
+ms.service: active-directory
+ms.subservice: app-provisioning
+ms.topic: reference
+ms.workload: identity
+ms.date: 07/05/2022
+ms.author: kenwith
+ms.reviewer: arvinh, chmutali
+---
+
+# Configure Azure AD provisioning to retrieve pronoun information from Workday
+This article describes how you can customize the following two HR-driven provisioning apps to fetch pronoun information from Workday.
+
+* [Workday to on-premises Active Directory user provisioning](../saas-apps/workday-inbound-tutorial.md)
+* [Workday to Azure Active Directory user provisioning](../saas-apps/workday-inbound-cloud-only-tutorial.md)
+
+## About pronoun information in Workday
+Workday introduced the ability for workers to [display pronoun information](https://community.workday.com/node/731178) in their worker profile in Workday 2021 R1 release. The ability to fetch pronoun data using Workday Web Services (WWS) API call was introduced in [Get_Workers API version 38.1](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v38.1/Get_Workers.html) in Workday 2022 R1 release. 
+
+>[!NOTE]
+>Links to certain Workday community notes and documents in this article require Workday community account credentials. Please check with your Workday administrator or partner to get the required access.
+
+## Enabling pronoun data in Workday
+This section describes steps required to enable pronoun data in Workday. We recommend engaging your Workday administrator to complete the steps listed below. 
+1. Ensure that pronoun display and sharing preferences are enabled as per Workday guidelines. Refer Workday documents: 
+   
+   [Steps: Set Up Gender Pronouns to Display on a Worker Profile * Human Capital Management * Reader * Administrator Guide (workday.com)](https://doc.workday.com/r/gJQvxHUyQOZv_31Vknf~3w/7gZPvVfbRhLiPissprv6lQ)
+   
+   [Steps: Set Up Public Profile Preferences * Human Capital Management * Reader * Administrator Guide (workday.com)](https://doc.workday.com/r/gJQvxHUyQOZv_31Vknf~3w/FuENV1VTRTHWo_h93KIjJA)
+
+1. Use Workday **Maintain Pronouns** task to define preferred pronoun data (HE/HIM, SHE/HER, and THEY/THEM) in your Workday tenant.
+1. Use Workday **Maintain Localization Settings task -> Personal Information** area to activate pronoun data for different countries. 
+1. Select the Workday Integration System Security Group used with your Azure AD integration. Update the [domain permissions for the security group](../saas-apps/workday-inbound-tutorial.md#configuring-domain-security-policy-permissions), so it has GET access for the Workday domain **Reports: Public Profile**.
+    >[!div class="mx-imgBorder"] 
+    >![Screenshot of permissions to setup in Workday.](./media/workday-pronoun-data/workday-pronoun-permissions.png)
+1. Activate Pending Security Policy changes.
+1. Select a worker in your Workday tenant for testing purposes. Set pronoun information for this worker using the **Edit Personal Information** task. Ensure that the worker has enabled pronoun display to all in their public profile preference. 
+
+    >[!div class="mx-imgBorder"] 
+    >![Screenshot of enabling pronoun display option.](./media/workday-pronoun-data/enable-pronoun-display-preference.png)
+
+1. Use Workday Studio or Postman to invoke [Get_Workers API version 38.1](https://community.workday.com/sites/default/files/file-hosting/productionapi/Human_Resources/v38.1/Get_Workers.html) for the test user using the Workday Azure AD integration system user. In the SOAP request header specify the option Include_Reference_Descriptors_In_Response. 
+    ```
+      <bsvc:Workday_Common_Header>
+         <bsvc:Include_Reference_Descriptors_In_Response>true</bsvc:Include_Reference_Descriptors_In_Response>
+      </bsvc:Workday_Common_Header> 
+    ```
+1. In the Get_Workers response, you will now see pronoun information. 
+
+    >[!div class="mx-imgBorder"] 
+    >![Screenshot of Workday Get Workers API response.](./media/workday-pronoun-data/get-workers-response-with-pronoun.png)
+
+>[!NOTE]
+>If you are not able to retrieve pronoun data in the *Get_Workers* response, then troubleshoot Workday domain security permissions. Ensure your integration security group has permission to the segmented security group that grants access to the pronoun data. 
+
+Once you confirm that pronoun data is available in the *Get_Workers* response, go to the next step of updating your Azure AD provisioning app configuration. 
+ 
+## Updating Azure AD provisioning app to retrieve pronouns
+
+To retrieve pronouns from Workday, you'll need to update your Azure AD provisioning app to query Workday using v38.1 of the Workday Web Services. We recommend testing this configuration first in your test/sandbox environment before implementing the change in production. 
+
+1. Sign-in to Azure portal as administrator. 
+1. Open your *Workday to AD User provisioning* app OR *Workday to Azure AD User provisioning* app. 
+1. In the **Admin Credentials** section, update the **Tenant URL** to include the Workday Web Service version v38.1 as shown below.
+
+     >[!div class="mx-imgBorder"] 
+     >![Screenshot of Azure portal provisioning app with Workday version.](./media/workday-pronoun-data/update-workday-version.png)
+
+1. Open the **Attribute mappings** blade. Scroll down and click **Show advanced options**. Click on **Edit attribute list for Workday**.
+1. If your provisioning app is configured to use the default WWS API version v21.1, then [reference this article to review and update the XPATHs for each attribute](workday-attribute-reference.md#xpath-values-for-workday-web-services-wws-api-v30).
+1. Add a new attribute called **PreferredPronoun** with XPATH 
+
+     `/wd:Worker/wd:Worker_Data/wd:Personal_Data/wd:Personal_Information_Data/wd:Pronoun_Reference/@wd:Descriptor`
+
+1. Save your changes. 
+1. You can now add a new attribute mapping to flow the Workday attribute **PreferredPronoun** to any attribute in AD/Azure AD.
+1. If you want to incorporate pronoun information as part of display name, you can update the attribute mapping for displayName attribute to use the below expression. 
+
+     `Switch([PreferredPronoun], Join("", [PreferredNameData], " (", [PreferredPronoun], ")"), "", [PreferredNameData])`
+
+1. If worker *Aaron Hall* has set his pronoun information in Workday as `HE/HIM`, then the above expression will set the display name in Azure AD as: *Aaron Hall (HE/HIM)*
+1. Save your changes. 
+1. Test the configuration for one user with provisioning on demand. 
+ 
+## Next steps
+
+* [Learn how to configure Workday to Active Directory provisioning](../saas-apps/workday-inbound-tutorial.md)
+* [Learn how to configure write back to Workday](../saas-apps/workday-writeback-tutorial.md)
+* [Learn more about supported Workday Attributes for inbound provisioning](workday-attribute-reference.md)

articles/active-directory/app-provisioning/media/workday-pronoun-data/update-workday-version.png

@@ -33,8 +33,8 @@ This article provides a reference for required and optional settings that are us
 | telemetry.metrics.local.statsd.endpoint | StatsD endpoint. | Yes, if `telemetry.metrics.local` is set to `statsd`; otherwise no.  | N/A |
 | telemetry.metrics.local.statsd.sampling | StatsD metrics sampling rate. Value must be between 0 and 1, for example, 0.5. |  No | N/A |
 | telemetry.metrics.local.statsd.tag-format | StatsD exporter [tagging format](https://github.com/prometheus/statsd_exporter#tagging-extensions). Value is one of the following: `ibrato`, `dogStatsD`, `influxDB`. | No | N/A |
-| telemetry.metrics.cloud | Whether or not to [enable emitting metrics to Azure Monitor](how-to-configure-cloud-metrics-logs.md). | No |    `true` |
-| observability.opentelemetry.enabled | Whether or not to enable [emitting metrics to an OpenTelemetry collector](how-to-deploy-self-hosted-gateway-kubernetes-opentelemetry.md) on Kubernetes. | No | `false` |
+| telemetry.metrics.cloud | Indication whether or not to [enable emitting metrics to Azure Monitor](how-to-configure-cloud-metrics-logs.md). | No |    `true` |
+| observability.opentelemetry.enabled | Indication whether or not to enable [emitting metrics to an OpenTelemetry collector](how-to-deploy-self-hosted-gateway-kubernetes-opentelemetry.md) on Kubernetes. | No | `false` |
 | observability.opentelemetry.collector.uri | URI of the OpenTelemetry collector to send metrics to. | Yes, if `observability.opentelemetry.enabled` is set to `true`; otherwise no. | N/A |
 | observability.opentelemetry.histogram.buckets | Histogram buckets in which OpenTelemetry metrics should be reported. Format: "*x,y,z*,...". | No | "5,10,25,50,100,250,500,1000,2500,5000,10000" |
 
@@ -51,10 +51,11 @@ This article provides a reference for required and optional settings that are us
 | telemetry.logs.local.journal.endpoint  | Journal endpoint.   |Yes if `telemetry.logs.local` is set to `journal`; otherwise no. | N/A |
 | telemetry.logs.local.json.endpoint | UDP endpoint that accepts JSON data, specified as file path, IP:port, or hostname:port. | Yes if `telemetry.logs.local` is set to `json`; otherwise no. | 127.0.0.1:8888  |
 
-## Ciphers
+## Security
 
 | Name  | Description | Required | Default |
 | ------------- | ------------- | ------------- | ----|
+| certificates.local.ca.enabled | Indication whether or not to the self-hosted gateway should use local CA certificates that are mounted. This requires the self-hosted gateway to run as root or with user ID 1001. | No | `false` |
 | net.server.tls.ciphers.allowed-suites |   Comma-separated list of ciphers to use for TLS connection between API client and the self-hosted gateway. | No | N/A |
 | net.client.tls.ciphers.allowed-suites | Comma-separated list of ciphers to use for TLS connection between the self-hosted gateway and the backend. | No | N/A |
 

articles/active-directory/app-provisioning/media/workday-pronoun-data/workday-pronoun-permissions.png

@@ -6,6 +6,7 @@ author: mrbullwinkle
 manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: metrics-advisor
+ms.custom: applied-ai-non-critical-metrics-advisor
 ms.topic: how-to
 ms.date: 07/02/2021
 ms.author: mbullwin

articles/active-directory/app-provisioning/toc.yml

@@ -7,6 +7,7 @@ author: mrbullwinkle
 manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: metrics-advisor
+ms.custom: applied-ai-non-critical-metrics-advisor
 ms.topic: conceptual
 ms.date: 09/14/2020
 ms.author: mbullwin

articles/active-directory/app-provisioning/workday-retrieve-pronoun-information.md

@@ -7,6 +7,7 @@ author: mrbullwinkle
 manager: nitinme
 ms.service: applied-ai-services
 ms.subservice: metrics-advisor
+ms.custom: applied-ai-non-critical-metrics-advisor
 ms.topic: how-to
 ms.date: 09/14/2020
 ms.author: mbullwin