Skip to content

Commit

Permalink
PD-5269: custom policy checks language cleanliness
Browse files Browse the repository at this point in the history
  • Loading branch information
@adrian-velonis1
adrian-velonis1 committed Dec 4, 2024
1 parent d9995e4 commit b03fccb
Showing 1 changed file with 27 additions and 31 deletions.
58 changes: 27 additions & 31 deletions Content/liquibase-pro/policy-checks/custom-policy-checks/home.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@
<h1>Custom Policy Checks</h1>
<p>Custom Policy Checks allow you to enforce compliance for a wide array of security, code standards, data quality, and other policies using Python scripts. This feature expands the capabilities of <MadCap:xref href="../home.htm">Policy Checks</MadCap:xref> and allows all <MadCap:variable name="General.LBPro" /> users who write Python scripts to create nearly any check for their workflow.</p>
<p>You can create checks tailored to your specific policies and technical contexts so you don't have to wait for your specific check to be created and released by <MadCap:variable name="General.Liquibase" /> developers.</p>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">
<br />This is a <MadCap:variable name="General.LBPro" /> feature, so you need a <a href="https://docs.liquibase.com/workflows/liquibase-pro/how-to-apply-your-liquibase-pro-license-key.html" target="_blank"><MadCap:variable name="General.LBPro" /> License Key</a> to use it. <br /><br />The <MadCap:variable name="General.Liquibase" />&#160;<a href="https://mvnrepository.com/artifact/org.liquibase.ext/liquibase-checks">Checks extension</a>, which includes all Custom Policy Check functionality, is available to <MadCap:variable name="General.Liquibase" /> Pro 4.29.0+ users only on MacOS or Linux. This extension is required to use the Python-based custom policy checks.</p>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">This is a <MadCap:variable name="General.LBPro" /> feature, so you need a <a href="https://docs.liquibase.com/workflows/liquibase-pro/how-to-apply-your-liquibase-pro-license-key.html" target="_blank"><MadCap:variable name="General.LBPro" /> License Key</a> to use it. <br /><br />The <MadCap:variable name="General.Liquibase" />&#160;<a href="https://mvnrepository.com/artifact/org.liquibase.ext/liquibase-checks">Checks extension</a>, which includes all Custom Policy Check functionality, is available to <MadCap:variable name="General.Liquibase" /> Pro 4.29.0+ users only on MacOS or Linux. This extension is required to use the Python-based custom policy checks.</p>
<h2>Uses</h2>
<p><MadCap:variable name="General.Liquibase" /> provides a <MadCap:xref href="../checks/home.htm">Library of Policy Checks</MadCap:xref>, but you may find that they don't fully serve the nuanced conditions and contexts you need to evaluate all your policy enforcement goals. Custom policy checks add the flexibility and power of Python to greatly expand your ability to parse and inspect your <MadCap:variable name="General.changelog" />s and databases for compliance.</p>
<h2>Create a Custom Policy Check</h2>
Expand Down Expand Up @@ -95,38 +94,35 @@ <h3>Create a new check</h3>
sys.exit(1) # exit from the check</MadCap:codeSnippetBody>
</MadCap:codeSnippet>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;">If you're new to Python, it is a best practice to read the <a href="https://docs.python.org/3/library/distribution.html">official Python tutorials</a> before making custom checks.</p>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">If your check requires a <MadCap:xref href="../../../commands/inspection/snapshot.html">snapshot</MadCap:xref> of a database with hundreds or thousands of objects, this will take time and impact performance.</p>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">If your check requires a <MadCap:xref href="../../../commands/inspection/snapshot.html">snapshot</MadCap:xref> of a large database, this will take time and impact performance.</p>
</ol>
<h3>Configure and customize your new check in the CLI</h3>
<p>In the CLI, run this command to <b>initiate the customization process</b>:</p><pre><code class="language-text">liquibase checks customize --check-name=CustomCheckTemplate</code></pre>
<p>The CLI prompts you to finish configuring your file. A message displays:</p><pre><code class="language-text">This check cannot be customized directly because one or more fields does not have a default value.</code></pre>
<p><MadCap:variable name="General.Liquibase" /> will then create a copy of this check and initiate the customization workflow.</p>
<ol>
<li>In the CLI, run this command to <b>initiate the customization process</b>:</li><pre><code class="language-text">liquibase checks customize --check-name=CustomCheckTemplate</code></pre>
<p>The CLI prompts you to finish configuring your file. <br />A message displays:</p><pre><code class="language-text">This check cannot be customized directly because one or more fields does not have a default value.</code></pre>
<p><MadCap:variable name="General.Liquibase" /> will then create a copy of this check and initiate the customization workflow.</p>
<ol>
<li><b>Give your check a short name</b> for easier identification. In this example, we will name the check <code class="language-text">CustomCheckNoTables</code>.<br />Now you have successfully created the check <code class="language-text">CustomCheckNoTables</code> from <code class="language-text">CustomCheckTemplate</code>.</li>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">The new check short name <code class="language-text">CustomCheckNoTables</code> and all of its associated information comes from the Python script you created. Your company may have their own coding standards that these scripts must adhere to.</p>
<li>Set the <b>severity</b> to return a code of 0-4 when triggered. In this example, we will set the severity to <code class="language-text">1</code>. Options:</li>
<MadCap:snippetBlock src="../../../Z_Resources/Snippets/def/attributes/cli/policy-checks/cli-checks-severity-customization.flsnp" />
<li>Set the <b>script description</b> for the custom check. In this example we will set the description to:</li><pre><code class="language-text">This script looks to see if any tables exist and notifies you if one is detected.</code></pre>
<li>Set the <b>script scope</b> for the custom check to <code class="language-text">database</code>. The Python sample provided in this tutorial requires it.</li>
<p>In general, you should set the scope to <code class="language-text">changelog</code> or <code class="language-text">database</code> depending on what your custom script does:</p>
<ul>
<li><code class="language-text">changelog</code>: This scope indicates the check reviews all current <MadCap:variable name="General.changeset" />s. Set the scope to <code class="language-text">changelog</code> when your check will inspect and trigger based on conditions or actions determined in a <MadCap:variable name="General.changeset" />.</li>
<li><code class="language-text">database</code>: This scope indicates the check runs once for each database object. Set the the scope to <code class="language-text">database</code> when your check will inspect and trigger based on the existing state of a database schema. This can mean you're looking for the presence of keys, indexes, or table name patterns.</li>
</ul>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;">It is a best practice for your custom checks to have <b>only one scope</b>, not both scopes.</p>
<li>
<p>Set the <b>script message</b>. This message will display when the check is triggered. In this example we will leave this blank, as we are handling the message in the script.</p>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;"><b>Option for advanced users:</b> You can create <MadCap:xref href="status-message-variable.htm">Script Message Variables for Custom Policy Checks</MadCap:xref> which are identified in your Python script.</p>
</li>
<li>Set the <b>script type</b>. In <MadCap:variable name="General.LBPro" /> 4.29.0, Python is the only available script type.</li>
<li>Set the <b>script path</b>. This is the relative path where your script is stored, whether it is stored locally or in a repository.</li>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;">It is a best practice to store all of your scripts in the same folder for easy access.</p>
<p>In this example, we will set the path to <code class="language-text">Scripts/custom-check-no-tables.py</code>.</p>
<li>Set the <b>script argument</b>. This is a way for you to pass dynamic information into the custom policy check without modifying the Python code. The script arguments allow your Python scripts remain reusable with different variables.</li>
<li>Set whether the check requires a <b><MadCap:xref href="../../../commands/inspection/snapshot.html">snapshot</MadCap:xref></b>:</li><pre><code class="language-text">REQUIRES_SNAPSHOT (options: true, false) [false]:</code></pre>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">You may need to query the database if the <MadCap:variable name="General.changelog" /> requires a snapshot. Requiring a snapshot calls for a database connection and impacts performance. It can take time to process if your database has hundreds or thousands of objects.</p>
</ol>
<li><b>Give your check a short name</b> for easier identification. In this example, we will name the check <code class="language-text">CustomCheckNoTables</code>.<br />Now you have successfully created the check <code class="language-text">CustomCheckNoTables</code> from <code class="language-text">CustomCheckTemplate</code>.</li>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">The new check short name <code class="language-text">CustomCheckNoTables</code> and all of its associated information comes from the Python script you created. Your company may have their own coding standards that these scripts must adhere to.</p>
<li>Set the <b>severity</b> to return a code of 0-4 when triggered. In this example, we will set the severity to <code class="language-text">1</code>. Options:</li>
<MadCap:snippetBlock src="../../../Z_Resources/Snippets/def/attributes/cli/policy-checks/cli-checks-severity-customization.flsnp" />
<li>Set the <b>script description</b> for the custom check. In this example we will set the description to:</li><pre><code class="language-text">This script looks to see if any tables exist and notifies you if one is detected.</code></pre>
<li>Set the <b>script scope</b> for the custom check to <code class="language-text">database</code>. The Python sample provided in this tutorial requires it.</li>
<p>In general, you should set the scope to <code class="language-text">changelog</code> or <code class="language-text">database</code> depending on what your custom script does:</p>
<ul>
<li><code class="language-text">changelog</code>: specifies that the check reviews all current <MadCap:variable name="General.changeset" />s. Set the scope to <code class="language-text">changelog</code> when your check will inspect and trigger based on conditions or actions determined in a <MadCap:variable name="General.changeset" />.</li>
<li><code class="language-text">database</code>: specifies that the check runs once for each database object. Set the scope to <code class="language-text">database</code> when your check will inspect and trigger based on the existing state of a database schema. This can mean you're looking for the presence of keys, indexes, or table name patterns.</li>
</ul>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;">It is a best practice for your custom checks to have <b>only one scope</b>, not both scopes.</p>
<li>
<p>Set the <b>script message</b>. This message will display when the check is triggered. In this example we will leave this blank, as we are handling the message in the script.</p>
<p class="tip" MadCap:autonum="&lt;b&gt;Tip: &lt;/b&gt;"><b>Option for advanced users:</b> You can create <MadCap:xref href="status-message-variable.htm">Script Message Variables for Custom Policy Checks</MadCap:xref> which are identified in your Python script.</p>
</li>
<li>Set the <b>script type</b>. In <MadCap:variable name="General.LBPro" /> 4.29.0, Python is the only available script type.</li>
<li>Set the <b>script path</b>. This is the relative path where your script is stored, whether it is stored locally or in a repository.</li>
<p>In this example, we will set the path to <code class="language-text">Scripts/custom-check-no-tables.py</code>.</p>
<li>Set the <b>script argument</b>. This allows you to pass dynamic information into the custom policy check without modifying the Python code. The script arguments allow your Python scripts remain reusable with different variables.</li>
<li>Set whether the check requires a <b><MadCap:xref href="../../../commands/inspection/snapshot.html">snapshot</MadCap:xref></b>:</li><pre><code class="language-text">REQUIRES_SNAPSHOT (options: true, false) [false]:</code></pre>
<p class="note" MadCap:autonum="&lt;b&gt;Note: &lt;/b&gt;">If your check requires a snapshot, it may need to query the database, which can impact performance.</p>
<p>You have now successfully created and customized a policy check!</p>
</ol>
<h2>Run your new check</h2>
Expand Down

0 comments on commit b03fccb

Please sign in to comment.