Audit Plugin
Contentstack lets you perform audit operations to find out the missing references in the exported stacks data using the Audit plugin in Contentstack CLI.
The Audit plugin provides users with detailed reports about any issues related to the following, in a given stack data:
- References in Content Types, Global Fields, and Entries.
- Content types used in Workflows and Extensions.
- Branches used in custom roles and workflows.
- Title field, select field, publish details, and mandatory fields of entries.
- Publish details of Assets.
- Field rules in content types.
Additionally, it includes commands that validate and resolve these references, fields, publish details, field rules, and content types.
This step-by-step guide lets you install and use the Audit plugin in CLI.
Prerequisites
- Contentstack account
- CLI installed and configured (version 1.9.1 or above)
- Exported content generated using CLI (version 1.9.0 or above) available on local machine
Commands
The Audit plugin lets you perform the following operation in Contentstack CLI:
Supported Modules
Issue Identification in References
The cm:stacks:audit command allows you to validate references and identify the issues.
- Open the terminal.
- Fire the following command:
csdx cm:stacks:audit
- Enter the local path where the data is stored.
Note: If you exported data from a branch-enabled stack, make sure to provide the complete local path up to the branch. For example, C:\Users\...\CLI\Content\branch_folder.
You have successfully performed an audit operation to find the missing references in your stack.
Alternatively, you can pass the path in the command as given below:
csdx cm:stacks:audit --data-dir <path>
csdx cm:stacks:audit
Options
- -c, --config=config: [optional] Path of the external config.
- -d, --data-dir=data-dir: [optional] Path where the data is stored.
- --columns=columns: Show only the specified columns (comma-separated).
- --csv: The output is in the CSV format [alias: --output=csv].
- --filter=filter: Filter property by partial string matching. For example: name=foo.
- --modules=modules: Provide the list of modules to be audited. [options: content-types|global-fields|entries|extensions|workflows|custom-roles|assets|field-rules]
- --no-header: Hide table headers in output.
- --no-truncate: The output is not truncated to fit the screen.
- --output=output: Specify the output format. [options: csv|json|yaml]
- --report-path=report-path: Path to store the audit reports.
- --sort=sort: Property to sort by (prepend '-' for descending).
- --show-console-output: Displays the audit result for individual modules.
Note: If the custom role or the workflow module has branches enabled and you want audit to operate on all the branches except a particular branch, then you can provide that specific branch name using the --config flag as given below:
{
"branch": "<branch-name>"
}Examples
- To perform the audit operation by providing the path to store the audit reports:
csdx cm:stacks:audit --report-path <path>
- To perform the audit operation by fetching the results in CSV format and providing the path to store the audit reports:
csdx cm:stacks:audit --report-path <path> --csv
- To perform the audit operation with a name filter and by providing the path to store the audit reports:
csdx cm:stacks:audit --report-path <path> --filter="name=<filter-value>"
- To perform the audit operation by providing the module for which the audit must be performed, along with the path to store the audit reports:
csdx cm:stacks:audit --report-path <path> --modules=content-types
Issue Resolution in References
The cm:stacks:audit:fix command allows you to validate references and actively resolve the identified issues.
- Open the terminal.
- Fire the following command:
csdx cm:stacks:audit:fix
- Enter the local path where the data is stored.
- In the prompt that appears, enter the following:
- Yes, to overwrite the existing file.
- No, to skip overwriting the existing file.
Note: The prompt appears only if you have not passed the --copy-dir flag.
You have successfully performed an audit operation to fix the missing references in your stack.
Alternatively, you can pass the path in the command as given below:
csdx cm:stacks:audit:fix --data-dir <path>
csdx cm:stacks:audit:fix
or
csdx audit:fix
Options
- -c, --config=config: [optional] Path of the external config.
- -d, --data-dir=data-dir: [optional] Path where the data is stored.
- --copy-path=copy-path: Provide the path to backup the copied data.
- --columns=columns: Show only the specified columns (comma-separated).
- --copy-dir: [recommended] Create backup from the original data.
- --csv: The output is in the CSV format [alias: --output=csv].
- --filter=filter: Filter property by partial string matching. For example: name=foo.
- --modules=modules: Provide the list of modules to be audited. [options: content-types|global-fields|entries|extensions|workflows|custom-roles|assets|field-rules]
- --no-header: Hide table headers in output.
- --no-truncate: The output is not truncated to fit the screen.
- --output=output: Specify the output format. [options: csv|json|yaml]
- --report-path=report-path: Path to store the audit reports.
- --sort=sort: Property to sort by (prepend '-' for descending).
- --fix-only=fix-only: Provide the list of fix options. [options: reference|global_field|json:rte|json:extension|blocks|group|content_types]
- --show-console-output: Displays the audit-fix result for individual modules.
- If the custom role or the workflow module has branches enabled and you want audit to operate on all the branches except a particular branch, then you can provide that specific branch name using the --config flag as given below:Passing this flag makes the auditing process check and remove all branches except the one specified in the config file.
{ "branch": "<branch-name>" } - When you use the --copy-dir flag, a copy of the original data gets created and the audit fix operation occurs on the copied data.
- By default, audit:fix does not populate values in the select fields. To enable this behavior, use the –-config flag and provide a configuration file containing the following keys:
{ "fixSelectField": true }
Examples
- To perform the audit fix operation on a copied version of the original data:
csdx cm:stacks:audit:fix --copy-dir
- To perform the audit operation on a copied version of the original data by providing the path to store the audit reports:
csdx cm:stacks:audit:fix --report-path <path> --copy-dir
- To perform the audit fix operation with a name filter and by providing the path to store the audit reports:
csdx cm:stacks:audit:fix --report-path <path> --filter="name=<filter-value>"
- To perform the audit operation on a copied version of the original data by providing the backup directory path to store the copied data, along with the path to store the audit reports:
csdx cm:stacks:audit:fix --report-path <path> --copy-dir --copy-path <path>
Limitation
- The Audit plugin currently supports audit operations for identifying and fixing issues in the following areas:
- To find and fix missing reference issues in:
- To find and fix the following in a given exported stack data:
- Missing content types in Workflows and Extensions.
- Missing branches in workflows and custom roles.
- Publish details of entries and assets.
- Select, title, and mandatory fields of entries.
- Field rules of content types.
More articles in "Contentstack CLI Core Commands"