Azure Communication Services technical documentation table of contents update
Technical documentation is like a map for using a platform—whether you're building services, solving problems, or learning new features, great documentation shows you the way to the solution you need. But what good is a map if it’s hard to read or confusing to follow? That’s why easy-to-navigate documentation is so important. It saves time, reduces frustration, and helps users focus on what they want to achieve. Azure Communication Services is a powerful platform, and powerful platforms require great documentation for both new and experienced developers. Our customers tell us consistently that our docs are a crucial part of their experience of using our platform. Some studies suggest that documentation and samples are the most important elements of a great developer experience. In this update, we’re excited to share how we’ve improved our technical documentation’s navigation to make it quicker and simpler than ever to find the information you need when you need it. Why did we change? In order for our content to be useful to you, it first needs to be findable. When we launched Azure Communication Services, the small number of articles on our site made it easy to navigate and find relevant content. As we’ve grown, though, our content became harder to find for users due to the quantity of articles they need to navigate. To refresh your memory, the table of contents on our docs site used to be structured with these base categories: Overview Quickstart Tutorials Samples Concepts Resources References These directory names describ e the type of content they contain. This structure is a very useful model for products with a clearly-defined set of use cases, where typically a customer’s job-to-be-done is more constrained, but it breaks down when used for complex, powerful platforms that support a broad range of use cases in the way that Azure Communication Services does. We tried a number of small-scale changes to address the problems people were having on our site, such as having certain directories default to open on page load, but as the site grew, we became concerned that our site navigation model was becoming confusing to users and having a negative impact on their experience with our product. We decided to test that hypothesis and consider different structures that might serve our content and our customers better. Our user research team interviewed 18 customers with varying levels of experience on our platform. The research uncovered several problems that customers were having with the way our docs navigation was structured. From confusing folder titles, to related topics being far away from each other in the nav model, to general confusion around what folder titles meant, to problems finding some of the most basic information about using our platform, and a host of other issues, our user research made it clear to us that we had a problem that we needed to fix for our users. What did we change in this release? To help address these issues, we made a few key changes to make our table of contents simpler and easier to navigate. The changes we made were strictly to site navigation, not page content, and they include: We've restructured the root-level navigation to be focused on communication modality and feature type, rather than content type, to better model our customers' jobs-to-be-done. Topics include All supported communication channels Horizontal features that span more than one channel Topics of special interest to our customers, like AI Basic needs, like troubleshooting and support This will allow customers to more easily find the content they need by focusing on the job they need to do, rather than on the content type. We've simplified the overview and fundamentals sections to make the site less overwhelming on first load. We've surfaced features that customers told us were difficult to find, such as UI Library, Teams interop, and Job router. We've organized the content within each directory to roughly follow a beginner->expert path to make content more linear, and to make it easier for a user to find the next step in completing their task. We've removed unnecessary layers in our nav, making content easier to find. We've added a link to pricing information to each primitive to address a common customer complaint, that pricing information is difficult to find and understand. We've combined quickstarts, samples, and tutorials into one directory per primitive, called "Samples and tutorials", to address a customer complaint that our category names were confusing. We added a directory to each primitive for Resources, to keep important information close by. We added root-level directories for Common Scenarios, Troubleshooting, and Help and support. We did a full pass across all TOC entries to ensure correct casing, and edited entries for readability and consistency with page content, as well as for length to adhere to Microsoft guidelines and improve readability. These changes have led us to a structure that we feel less taxing for the reader, especially on first visit, maps more closely to the customer’s mental model of the information by focusing on the job-to-be-done rather than content type, helps lead them through the content from easiest to hardest, helps make it easier for them to find the information they need when they need it, and helps remind them of all the different features we support. Here’s what the table of contents looks like on page load as of Feb 6: These changes are live now. You can see them on the Azure Communication Services Technical documentation site. What’s next: In the coming weeks we will continue to make refinements based on customer feedback and our assessment of usage metrics. Our content team will begin updating article content to improve readability and enhance learning. We will be monitoring our changes and seeking your feedback. How will we monitor the effectiveness of our changes? To track the effectiveness of our changes and to be sure we haven’t regressed, we’ll be tracking a few key metrics Bounce rates: We’ll be on the lookout for an increase in bounce rates, which would indicate that customers are frequently landing on pages that don’t meet their expectations. Page Views: We’ll be tracking the number of page views for our most-visited pages across different features. A decrease in page views for these pages will be an indicator that customers are not able to find pages that had previously been popular. Customer Interviews: We will be reaching out to some of you to get your impressions of the new structure of our content over the coming weeks. Customer Surveys: We've created a survey that you can use to give us your feedback. We'll also be adding this link to select pages to allow you to tell us what you think of our changes while you're using them! So, give our new site navigation a try, and please don’t hesitate to share your feedback either by filling out our survey or by sending an email to acs-docs-feedback@microsoft.com. We look forward to hearing from you! A623Views2likes0CommentsGuest Post: Send emails with PowerShell and managed identity using Azure Communication Services
Today, we’re featuring a guest author, Luke Murray, a Microsoft Most Valuable Professional (MVP) for Azure. He’s written an article we’re sharing below, focused on Azure Communication Services Email and PowerShell. We’ll turn it over to Luke to share more! Azure Communication Services brings rich communication APIs to all your apps across any device on any platform, using the same reliable and secure infrastructure that powers Microsoft Teams. Please follow these steps to set up Azure Communication Services resources in the Azure portal as pre-requisites for sending an email. 1. Create Azure Communication Services resource. 2.Create Email Communication Service. 3. Connect them, you can use a free Azure supplied domain name, or bring in your own custom domain. Today, we will explore using Email as part of Azure Communication Services, using their REST API and PowerShell to send an email. In this example, I will access a token from Azure Communication Services. I will make a GET request to the identity endpoint of Azure Communication Services using the OAuth identity from the system-managed identity. This will return a token we can use to authenticate against the REST API. Here's a step-by-step explanation of the script: The script first defines the subject and body of the email. The body is an HTML string that contains the email content. It checks if the email body is not empty. If the email body is not empty, it gets an access token from Azure Communication Services. This is done by making a GET request to the identity endpoint of Azure Communication Services. The access token is then printed to the console. If there's an error retrieving the access token, the script catches the exception and prints the error message and response details on the console. The script then constructs the URI for the email-sending endpoint and defines the headers for the REST API call. The headers include the content type and the access token that was obtained in the authorization header. The script defines the body for the REST API call. This includes the sender address, the email content (subject and body), the recipients, the reply-to address, and a flag to disable user engagement tracking. The script then converts the PowerShell object to JSON and attempts to send the email by making a POST request to the email-sending endpoint. The request and response details are logged to the console. If the email is sent incorrectly, the script catches the exception and logs the error message and stack trace to the console. Further information on the authentication process: The script first defines the resource ID for Azure Communication Services and the communication endpoint URL. It then constructs the URI for the identity endpoint. This URI includes the environment variable IDENTITY_ENDPOINT (automatically set by Azure when using Managed Identity) and the resource ID. The script then attempts to get an access token from the identity endpoint. It does this by sending a GET request to the identity endpoint with a header that includes Metadata: true. This tells the identity endpoint that the request is coming from within Azure. If the request is successful, the response will include an access token, which is then extracted from it. This access token can then be used to authenticate requests to Azure Communication Services. The token tells Azure Communication Services that the request comes from an authenticated source (in this case, the Managed Identity) and should be allowed. (This authentication was initially written to be used in an Azure Automation Runbook, with the System Managed Identity assigned Contributor rights to the Azure Communication Services resource (not the Email Communication Services) Here is the PowerShell script to send an email using Azure Communication Services using the System Managed identity of an Azure Automation account: $emailSubject = "Important: Server Maintenance Notification" $EmailRecipient = "ituser@contoso.com" $emailBody = @" <html> <body> <p>Dear User,</p> <p>This is to inform you that a <b><i>server maintenance is scheduled for the next week</i></b>.</p> <p>The servers will be down from 10:00 PM to 2:00 AM.</p> <p>Please save your work and log off during this period to avoid any data loss.</p> <p>If you have any questions or concerns, please contact our IT Support team.</p> <p>Thank you for your understanding and cooperation.</p> <p>Best Regards,</p> <p>IT Support Team</p> </body> </html> "@ if ($emailBody -ne "") { Write-Output $emailBody # Define the resource ID for Azure Communication Services $ResourceID = 'https://communication.azure.com' # Define the communication endpoint URL $communicationendpointurl = "azcomm-contoso.australia.communication.azure.com" # Update with your communication endpoint URL # Construct the URI for the identity endpoint $Uri = "$($env:IDENTITY_ENDPOINT)?api-version=2018-02-01&resource=$ResourceID" # Debug output # Print the constructed URI and headers Write-Output "URI: $Uri" Write-Output "Headers: @{ Metadata = 'true' }" # Try to get the access token try { # Invoke a GET request to the identity endpoint to get the access token $AzToken = Invoke-WebRequest -Uri $Uri -Method GET -Headers @{ Metadata = "true" } -UseBasicParsing | Select-Object -ExpandProperty Content | ConvertFrom-Json | Select-Object -ExpandProperty access_token # Print the obtained access token Write-Output "Access Token: $AzToken" } catch { # If there's an error, print the error message and response details Write-Error "Failed to get access token: $_" Write-Output "Response Status Code: $($_.Exception.Response.StatusCode.Value__)" Write-Output "Response Status Description: $($_.Exception.Response.StatusDescription)" Write-Output "Response Content: $($_.Exception.Response.GetResponseStream() | %{ $_.ReadToEnd() })" } # Construct the URI for the email sending endpoint $uri = "https://$communicationendpointurl/emails:send?api-version=2023-03-31" # Define the headers for the REST API call # Include the content type and the obtained access token in the Authorization header $headers = @{ "Content-Type" = "application/json" "Authorization" = "Bearer $AzToken" } # Define the body for the REST API call $apiResponse = @{ headers = @{ id = (New-Guid).Guid } senderAddress = 'DoNotReply@7647475b-a51b-4901-8674-917e6abea743.azurecomm.net' content = @{ subject = $emailSubject html = $emailBody } recipients = @{ to = @( @{ address = $EmailRecipient displayName = $EmailRecipient } ) } replyTo = @( @{ address = "example@contoso.com" displayName = "Contoso" } ) userEngagementTrackingDisabled = $true } # Convert the PowerShell object to JSON $body = $apiResponse | ConvertTo-Json -Depth 10 # Send the email try { # Log the request details Write-Output "Sending email..." Write-Output "URI: $uri" Write-Output "Headers: $headers" Write-Output "Body: $body" # Make the request $response = Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body -UseBasicParsing # Log the response Write-Output "Response: $response" # Return the response $response } catch { # Log the error Write-Error "Failed to send email: $_" Write-Output "Exception Message: $($_.Exception.Message)" Write-Output "Exception StackTrace: $($_.Exception.StackTrace)" } } You can run this script in an Azure Automation Runbook (and theoretically in an Azure Function) to send an email using Azure Communication Services and the System Managed Identity—and there is no need to maintain or store client secrets! I did a previous article: Deploying and Testing Azure Email Communication Services that uses Azure Service Principal for authentication. In this blog, we use OAuth using a System Assigned Managed Identity.1.4KViews2likes0Comments