deploy: 4fbfc28c9e

docs/bestpractices/index.xml

@@ -95,8 +95,8 @@ All APIs pages apply the behavior to first specify all field values and then ins
 <li>number for field “No.”</li>
 <li>displayName for field Name</li>
 </ul>
-<h2 id="default-fields">Default fields</h2>
-<p>An API should at least expose these fields:</p>
+<h2 id="mandatory-fields">Mandatory fields</h2>
+<p>These fields should always be part of the API Page:</p>
 <ul>
 <li>SystemId
 <ul>
@@ -105,7 +105,7 @@ All APIs pages apply the behavior to first specify all field values and then ins
 </li>
 <li>SystemModifiedAt
 <ul>
-<li>This field should be exposed with the name <code>lastModifiedDateTime</code>. If you choose a different name, then the webhook functionality may not work properly.</li>
+<li>This field should be exposed with the name <code>lastModifiedDateTime</code>. If you choose a different name, then the webhook functionality will not work properly.</li>
 </ul>
 </li>
 </ul>
@@ -222,11 +222,11 @@ All APIs pages apply the behavior to first specify all field values and then ins
 <h2 id="naming-conventions-and-telemetry-schema">Naming conventions and telemetry schema</h2>
 <p>To make it easy for the consumer of telemetry to work with the data, please</p>
 <ul>
-<li>use PascalCasing. This makes all fields in Application Insights look the same (signal logged through the AL LogMessage method will have “al” prefixed to dimension names.</li>
-<li>never use fields/custom dimension keys with spaces or special characters. This makes the KQL queries so much easier to write</li>
+<li>use <strong>PascalCasing</strong>. This makes all fields in Application Insights look the same (signal logged through the AL LogMessage method will have “al” prefixed to dimension names.</li>
+<li><strong>Do not use special characters or spaces</strong> for fields/custom dimension keys. This makes the KQL queries so much easier to write</li>
 <li>for custom dimensions, consider using prefixes that helps the telemetry consumer understand where the dimension is coming from (e.g. HttpStatusCode, SqlStatement, …)</li>
 </ul>
-<p>Consider always having a “message” field that expresses in human readable form what the telemetry event is about.
+<p>Consider always having a <strong>“message”</strong> field that expresses in human readable form what the telemetry event is about.
 If you do, let message names follow the Object ActionInPastTense pattern
 Some examples</p>
 <ul>
@@ -252,10 +252,10 @@ Some examples</p>
 </span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">end</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
 </span></span></span><span style="display:flex;"><span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">end</span><span style="color:#000;font-weight:bold">;</span><span style="color:#f8f8f8;text-decoration:underline">
 </span></span></span></code></pre></div><h2 id="objects-emitting-telemetry-signals">Objects emitting telemetry signals</h2>
-<p>Telemetry data includes information about the object that emitted the telemetry signal. It’s recommended to call Session.LogMessage() from within the object that causes a situation that you want to have telemetry for. That will make it easier to analyze where exactly in the code an issue occurred.</p>
+<p>Telemetry data includes information about the object that emitted the telemetry signal. It’s recommended to call Session.LogMessage() <strong>from within the object</strong> that causes a situation that you want to have telemetry for. That will make it easier to analyze where exactly in the code an issue occurred.</p>
 <p>Of course it is possible to have a single object as a central place to emit telemetry signals. The telemetry data includes a callstack, so eventually it would be possible to trace back to the exact place where an issue occurred. But that requires a more complicated query, so it would be better to emit telemetry signals right from place in the code where an issue occurred.</p>
 <h2 id="candidate-data-for-telemetry">Candidate data for telemetry</h2>
-<p>Telemetry must be actionable for the customer. Do not emit signals that they cannot act on (knowing about CPU performance counters on the database is useless if the partner cannot scale the database)</p>
+<p>Telemetry must be <strong>actionable</strong> for the customer. Do not emit signals that they cannot act on (knowing about CPU performance counters on the database is useless if the partner cannot scale the database)</p>
 <p>Also, note that customers pay for data ingestion. So be mindful to not flood their telemetry resources. Consider to use TelemetryScope::ExtensionPublisher by default and only use TelemetryScope::All in case the customer can also act on the data.</p>
 <p>If you do not know where to start, consider using telemetry for deflection. In Dynamics 365 Business Central, they started with signal about authorization (successful/failed) to deflect support cases that was due to disabled users/wrong licenses.</p>
 <h2 id="how-customers-use-telemetry">How customers use telemetry</h2>
@@ -268,7 +268,7 @@ Some examples</p>
 <p>Customers typically start in the Application Insights portal and then move on to use more advanced tools for analytics (KQL, Power BI, Excel, …). Once they have seen the light, they will likely start alerting on telemetry using Azure Monitor Alerts or setting up Power Automate flows.</p>
 <p>Business Central have developed a telemetry maturity model (based on the Gartner BI maturity model) for how organizations can evolve to use telemetry proactively in their business processes.</p>
 <h2 id="privacy">Privacy</h2>
-<p>Telemetry must be privacy compliant.</p>
+<p>Telemetry must be <strong>privacy compliant</strong>.</p>
 &lt;p>For privacy reasons, events that have a DataClassification other than SystemMetadata aren&amp;rsquo;t sent to Application Insight resources set up on the tenant. During development of your extension, it&amp;rsquo;s good practice to have a privacy review of the use of LOGMESSAGE calls to ensure that customer data isn&amp;rsquo;t mistakenly leaked into Application Insights resources.&lt;/p></description></item><item><title>Docs: DeleteAll</title><link>https://alguidelines.dev/docs/bestpractices/deleteall/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://alguidelines.dev/docs/bestpractices/deleteall/</guid><description>
 &lt;p>&lt;em>Created by waldo, Described by waldo&lt;/em>&lt;/p>
 &lt;h2 id="description">Description&lt;/h2>