License sync improvements (github#29546)

content/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud.md

@@ -22,6 +22,8 @@ To ensure that you see up-to-date license details on {% data variables.product.p
 
 If you don't want to enable {% data variables.product.prodname_github_connect %}, you can manually sync license usage by uploading a file from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_dotcom_the_website %}.
 
+When you synchronize license usage, only the user ID and email addresses for each user account on {% data variables.product.prodname_ghe_server %} are transmitted to {% data variables.product.prodname_ghe_cloud %}.
+
 {% data reusables.enterprise-licensing.view-consumed-licenses %}
 
 {% data reusables.enterprise-licensing.verified-domains-license-sync %}

content/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise.md

@@ -14,32 +14,57 @@ shortTitle: Troubleshoot license usage
 
 ## About unexpected license usage
 
-If the number of consumed licenses for your enterprise is unexpected, you can review your consumed license report to audit your license usage across all your enterprise deployments and subscriptions. If you find errors, you can try troubleshooting steps. For more information about viewing your license usage, see "[Viewing license usage for GitHub Enterprise](/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise)" and "[Viewing the subscription and usage for your enterprise account](/billing/managing-billing-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account)."
+If the number of consumed licenses for your enterprise is unexpected, you can review your consumed license report to audit your license usage across all your enterprise deployments and subscriptions. For more information, see "[Viewing license usage for GitHub Enterprise](/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise)" and "[Viewing the subscription and usage for your enterprise account](/billing/managing-billing-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account)."
 
-For privacy reasons, enterprise owners cannot directly access the details of user accounts.
+If you find errors, you can try troubleshooting steps.
+
+For privacy reasons, enterprise owners cannot directly access the details of user accounts unless you use {% data variables.product.prodname_emus %}.
 
 ## About the calculation of consumed licenses
 
-{% data variables.product.company_short %} bills for each person who uses deployments of {% data variables.product.prodname_ghe_server %}, is a member of an organization on {% data variables.product.prodname_ghe_cloud %}, or is a {% data variables.product.prodname_vs_subscriber %}. For more information about the people in your enterprise who are counted as consuming a license, see "[About per-user pricing](/billing/managing-billing-for-your-github-account/about-per-user-pricing)."
+{% data variables.product.company_short %} bills for each person who uses deployments of {% data variables.product.prodname_ghe_server %}, is a member of one of your organizations on {% data variables.product.prodname_ghe_cloud %}, or is a {% data variables.product.prodname_vs_subscriber %}. For more information about the people in your enterprise who consume a license, see "[About per-user pricing](/billing/managing-billing-for-your-github-account/about-per-user-pricing)."
+
+For each user to consume a single seat regardless of how many deployments they use, you must synchronize license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}. For more information, see "[Syncing license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud)."
+
+After you synchronize license usage, {% data variables.product.prodname_dotcom %} matches user accounts on {% data variables.product.prodname_ghe_server %} with user accounts on {% data variables.product.prodname_ghe_cloud %} by email address.
+
+First, we first check the primary email address of each user on {% data variables.product.prodname_ghe_server %}. Then, we attempt to match that address with the email address for a user account on {% data variables.product.prodname_ghe_cloud %}. If your enterprise uses SAML SSO, we first check the following SAML attributes for email addresses.
 
-{% data reusables.enterprise-licensing.about-license-sync %}
+- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`
+- `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
+- `username`
+- `NameID`
+- `emails`
+
+If no email addresses found in these attributes match the primary email address on {% data variables.product.prodname_ghe_server %}, or if your enterprise doesn't use SAML SSO, we then check each of the user's verified email addresses on {% data variables.product.prodname_ghe_cloud %}. For more information about verification of email addresses on {% data variables.product.prodname_dotcom_the_website %}, see "[Verifying your email address](/enterprise-cloud@latest/get-started/signing-up-for-github/verifying-your-email-address){% ifversion not ghec %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}."{% endif %}
 
 ## Fields in the consumed license files
 
 The {% data variables.product.prodname_dotcom_the_website %} license usage report and {% data variables.product.prodname_ghe_server %} exported license usage file include a variety of fields to help you troubleshoot license usage for your enterprise. 
+
 ### {% data variables.product.prodname_dotcom_the_website %} license usage report (CSV file)
 
 The license usage report for your enterprise is a CSV file that contains the following information about members of your enterprise. Some fields are specific to your {% data variables.product.prodname_ghe_cloud %} (GHEC) deployment, {% data variables.product.prodname_ghe_server %} (GHES) connected environments, or your {% data variables.product.prodname_vs %} subscriptions (VSS) with GitHub Enterprise.
 
 | Field | Description
 | ----- | -----------
-| Name | First and last name for the user's account on GHEC.
-| Handle or email | GHEC username, or the email address associated with the user's account on GHES.
-| Profile link | Link to the {% data variables.product.prodname_dotcom_the_website %} profile page for the user's account on GHEC.
-| License type | Can be one of: `Visual Studio subscription` or `Enterprise`.
-| License status | Identifies if a user account on {% data variables.product.prodname_dotcom_the_website %} successfully matched either a {% data variables.product.prodname_vs_subscriber %} or GHES user.<br><br>Can be one of: `Matched`, `Pending Invitation`, `Server Only`, blank.
-| Member roles | For each of the organizations the user belongs to on GHEC, the organization name and the person's role in that organization (`Owner` or `Member`) separated by a colon<br><br>Each organization is delimited by a comma.
-| Enterprise role | Can be one of: `Owner` or `Member`.
+| github_com_login | The username for the user's GHEC account
+| github_com_name | The display name for the user's GHEC account
+| github_com_profile | The URL for the user's profile page on GHEC
+| github_com_user	| Whether or not the user has an account on GHEC |
+| github_com_member_roles | For each of the organizations the user belongs to on GHEC, the organization name and the user's role in that organization (`Owner` or `Member`) separated by a colon<br><br>Organizations delimited by commas |
+| github_com_enterprise_role | Can be one of: `Owner`, `Member`, or `Outside collaborator`
+| github_com_verified_domain_emails | All email addresses associated with the user's GHEC account that match your enterprise's verified domains |
+| github_com_saml_name_id | The SAML username |
+| github_com_orgs_with_pending_invites | All pending invitations for the user's GHEC account to join organizations within your enterprise |
+| license_type | Can be one of: `Visual Studio subscription` or `Enterprise`
+| enterprise_server_user| Whether or not the user has at least one account on GHES |
+| enterprise_server_primary_emails | The primary email addresses associated with each of the user's GHES accounts |
+| enterprise_server_user_ids | For each of the user's GHES accounts, the account's user ID
+| total_user_accounts | The total number of accounts the person has across both GHEC and GHES
+| visual_studio_subscription_user | Whether or not the user is a {% data variables.product.prodname_vs_subscriber %} |
+| visual_studio_subscription_email | The email address associated with the user's VSS |
+| visual_studio_license_status | Whether the Visual Studio license has been matched to a {% data variables.product.company_short %} user |
 
 {% data variables.product.prodname_vs_subscriber %}s who are not yet members of at least one organization in your enterprise will be included in the report with a pending invitation status, and will be missing values for the "Name" or "Profile link" field.
 
@@ -59,32 +84,16 @@ Your {% data variables.product.prodname_ghe_server %} license usage is a JSON fi
 
 ## Troubleshooting consumed licenses
 
-If the number of consumed seats is unexpected, or if you've recently removed members from your enterprise, we recommend that you audit your license usage.
-
-To determine which users are currently consuming seat licenses, first try reviewing the consumed licenses report for your enterprise{% ifversion ghes %} and/or an export of your {% data variables.product.prodname_ghe_server %} license usage{% endif %} for unexpected entries.
-
-There are two especially common reasons for inaccurate or incorrect license seat counts.
-- The email addresses associated with a user do not match across your enterprise deployments and subscriptions.
-- An email address for a user was recently updated or verified to correct a mismatch, but a license sync job hasn't run since the update was made.
-
-When attempting to match users across enterprises, {% data variables.product.company_short %} identifies individuals by the verified email addresses associated with their {% data variables.product.prodname_dotcom_the_website %} account, and the primary email address associated with their {% data variables.product.prodname_ghe_server %} account and/or the email address assigned to the {% data variables.product.prodname_vs_subscriber %}.
-
-Your license usage is recalculated shortly after each license sync is performed. You can view the timestamp of the last license sync job, and, if a job hasn't run since an email address was updated or verified, to resolve an issue with your consumed license report you can manually trigger one. For more information, see "[Syncing license usage between GitHub Enterprise Server and GitHub Enterprise Cloud](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud)."
-
-{% ifversion ghec or ghes %}
-If your enterprise uses verified domains, review the list of enterprise members who do not have an email address from a verified domain associated with their {% data variables.product.prodname_dotcom_the_website %} account. Often, these are the users who erroneously consume more than one licensed seat. For more information, see "[Viewing members without an email address from a verified domain](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-members-without-an-email-address-from-a-verified-domain)."
-{% endif %}
-
-{% note %}
-
-**Note:** For privacy reasons, your consumed license report only includes the email address associated with a user account on {% data variables.product.prodname_dotcom_the_website %} if the address is hosted by a verified domain. For this reason, we recommend using verified domains with your enterprise account on {% data variables.product.prodname_dotcom_the_website %}. Then, if one person is erroneously consuming multiple licenses, you can more easily troubleshoot, as you will have access to the email address that is being used for license deduplication.
+To ensure that the each user is only consuming a single seat for different deployments and subscriptions, try the following troubleshooting steps.
 
-{% endnote %}
+1. To help identify users that are consuming multiple seats, if your enterprise uses verified domains for {% data variables.product.prodname_ghe_cloud %}, review the list of enterprise members who do not have an email address from a verified domain associated with their account on {% data variables.product.prodname_dotcom_the_website %}. Often, these are the users who erroneously consume more than one licensed seat. For more information, see "[Viewing members without an email address from a verified domain](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-members-without-an-email-address-from-a-verified-domain)."
 
-{% ifversion ghec %}
+   {% note %}
 
-If your license includes {% data variables.product.prodname_vss_ghe %} and your enterprise also includes at least one {% data variables.product.prodname_ghe_server %} connected environment, we strongly recommend using {% data variables.product.prodname_github_connect %} to automatically synchronize your license usage. For more information, see "[About Visual Studio subscriptions with GitHub Enterprise](/enterprise-cloud@latest/billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise)."
+  **Note:** To make troubleshooting easier, we recommend using verified domains with your enterprise account on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[Verifying or approving a domain for your enterprise](/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise)."
 
-{% endif %}
+  {% endnote %}
+1. After you identify users who are consuming multiple seats, make sure that the same email address is associated with all of the user's accounts. For more information about which email addresses must match, see "[About the calculation of consumed licenses](#about-the-calculation-of-consumed-licenses)."
+1. If an email address was recently updated or verified to correct a mismatch, view the timestamp of the last license sync job. If a job hasn't run since the correction was made, manually trigger a new job. For more information, see "[Syncing license usage between GitHub Enterprise Server and GitHub Enterprise Cloud](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud)."
 
 If you still have questions about your consumed licenses after reviewing the troubleshooting information above, you can contact {% data variables.contact.github_support %} through the {% data variables.contact.contact_enterprise_portal %}.

content/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise.md

@@ -14,21 +14,20 @@ shortTitle: View license usage
 
 ## About license usage for {% data variables.product.prodname_enterprise %}
 
-{% ifversion ghec %}
+You can view license usage for {% data variables.product.product_name %} on {% data variables.product.product_location %}.
 
-You can view license usage for your enterprise account on {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_dotcom_the_website %}.
+If you use both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %} and sync license usage between the products, you can view license usage for both on {% data variables.product.prodname_dotcom_the_website %}. For more information about license sync, see "[Syncing license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud)."
 
-{% data reusables.enterprise-licensing.you-can-sync-for-a-combined-view %}
+{% ifversion ghes %}
 
-{% elsif ghes %}
+For more information about viewing license usage on {% data variables.product.prodname_dotcom_the_website %} and identifying when the last license sync occurred, see "[Viewing license usage for {% data variables.product.prodname_enterprise %}](/enterprise-cloud@latest/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise)" in the {% data variables.product.prodname_ghe_cloud %} documentation.
 
-You can view license usage for {% data variables.product.prodname_ghe_server %} on {% data variables.product.product_location %}.
+{% endif %}
 
-{% data reusables.enterprise-licensing.you-can-sync-for-a-combined-view %} For more information about the display of license usage on {% data variables.product.prodname_dotcom_the_website %} and identifying when the last license sync occurred, see "[Viewing license usage for {% data variables.product.prodname_enterprise %}](/enterprise-cloud@latest/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise)" in the {% data variables.product.prodname_ghe_cloud %} documentation.
+You can also use the REST API to return consumed licenses data and the status of the license sync job. For more information, see "[GitHub Enterprise administration](/enterprise-cloud@latest/rest/enterprise-admin/license)" in the REST API documentation.
 
 To learn more about the license data associated with your enterprise account and how the number of consumed user seats are calculated, see "[Troubleshooting license usage for GitHub Enterprise](/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise)."
 
-{% endif %}
 
 ## Viewing license usage on {% ifversion ghec %}{% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}{% data variables.product.product_location %}{% endif %}
 

content/rest/enterprise-admin/license.md

@@ -4,6 +4,8 @@ intro: The License API provides information on your Enterprise license.
 versions:
   ghes: '*'
   ghae: '*'
+  ghec: '*'
+  fpt: '*'
 topics:
   - API
 miniTocMaxHeadingLevel: 3

data/reusables/enterprise-licensing/about-license-sync.md

@@ -1,3 +1 @@
-For a person using multiple {% data variables.product.prodname_enterprise %} environments to only consume a single license, you must synchronize license usage between environments. Then, {% data variables.product.company_short %} will deduplicate users based on the email addresses associated with their user accounts. Multiple user accounts will consume a single license when there is a match between an account's primary email address on {% data variables.product.prodname_ghe_server %} and/or an account's verified email address on {% data variables.product.prodname_dotcom_the_website %}. For more information about verification of email addresses on {% data variables.product.prodname_dotcom_the_website %}, see "[Verifying your email address](/enterprise-cloud@latest/get-started/signing-up-for-github/verifying-your-email-address){% ifversion not ghec %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}."{% endif %}
-
-When you synchronize license usage, only the user ID and email addresses for each user account on {% data variables.product.prodname_ghe_server %} are transmitted to {% data variables.product.prodname_ghe_cloud %}.
+For a person using multiple {% data variables.product.prodname_enterprise %} environments to only consume a single license, you must synchronize license usage between environments. Then, {% data variables.product.company_short %} will deduplicate users based on the email addresses associated with their user accounts. For more information, see "[Troubleshooting license usage for {% data variables.product.prodname_enterprise %}](/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise#about-the-calculation-of-consumed-licenses)."