@pdfbutler/migration-cli 0.0.11 → 0.0.12

package/README.md

@@ -7,7 +7,8 @@
 v0.0.11 updates: <br/>
 
 - '-b' flag disables backend export. If specified, the export operation doesn't use a PDF Butler backend process for exporting the configuration. By default, backend export is enabled.
-- New '-l --logs' flag. Use this flag to enable a more detailed log of the migration process..
+- New '-l --logs' flag. Use this flag to enable a more detailed log of the migration process.
+- New '-p --partial' flag. Use this flag to ignore invalid document configurations and allow the export of document configuration files with the backend part.
 
 ## About
 
@@ -15,7 +16,7 @@ v0.0.11 updates: <br/>
 
 ### Main features of the plugin:
 
-Export and import configurations: The plugin enables easy export and import of PDF Butler configurations. This is particularly useful for moving settings between different Salesforce environments or projects, ensuring consistency and ease of management.
+Export and import configurations: The plugin enables bulk export and import of PDF Butler configurations. This is particularly useful for moving settings between different Salesforce environments or projects, ensuring consistency and ease of management.
 Migration customization: The plugin provides users with the ability to customize the migration process using various flags and parameters to meet individual needs. With this plugin, you can specify the target Salesforce account, use environment variables for authentication, define custom URLs for import or export, and other parameters of your choice.
 
 ## Installation
@@ -73,7 +74,7 @@ Export PDF Butler configurations.
 
 ```
 USAGE
-$ sf butler pb export [--target | -t <value>] [--id | -i <value>] [--out | -o <value>] [--stage | -s <value>] [--backend | -b] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [--unzip | -u]
+$ sf butler pb export [--target | -t <value>] [--id | -i <value>] [--out | -o <value>] [--stage | -s <value>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [--backend | -b] [--unzip | -u] [-l | --logs] [-p | --partial]
 
 FLAGS
     -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Required)
@@ -86,6 +87,7 @@ FLAGS
     -u, --unzip                  Use this flag to unzip the exported configuration. (Optional)
     -b, --backend                Use this flag to disable PDF Butler backend export. (Optional)
     -l, --logs                   Use it to get a more detailed log of migration process. (Optional)
+    -p, --partial                Use this flag to ignore invalid document configurations and allow the export of document configuration files with the backend part.
 
 DESCRIPTION
     Export DocConfigs and related DataSource files from your organization.
@@ -97,29 +99,41 @@ DESCRIPTION
 
     To initiate an export, ensure you specify the necessary parameters, including the target org, PDF Butler docuemnt configuration ID,
     output path, define PDF Butler credentials for backend authentication, specify endpoints and stage.
-    Additionally, you have the flexibility to enable or disable backend exports, get a more detailed log of migration process and even choose to unzip the exported configuration.
+    Additionally, you have the flexibility to enable or disable backend exports, ignore invalid document configurations and allow the export of document configuration files with the backend part, get a more detailed log of migration process and even choose to unzip the exported configuration.
 
 EXAMPLES
-    Run with --unzip and --backend flags
+    Run with --backend flag only
 
         $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
             -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
-            -a 'pdf_butler_user_name-ADMIN:admin_password' -b -u
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -b
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
 
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json'
+                file 'docconfig_id.json'
             }
 
-    Run with --backend flag only
+    Run without --backend flag
 
         $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
             -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
-            -a 'pdf_butler_user_name-ADMIN:admin_password' -b
+            -a 'pdf_butler_user_name-ADMIN:admin_password'
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
 
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json'
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
+                    Directory 'ConfigTypes',
+                    Directory 'DataSources',
+                    file 'doc-config.json',
+                    file 'TemplateName.docx'
+                }
             }
 
     Run with --unzip flag only
@@ -128,10 +142,33 @@ EXAMPLES
             -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
             -a 'pdf_butler_user_name-ADMIN:admin_password' -u
 
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json',
-                Unziped directory 'archive_name'{
+                file 'docconfig_id.json',
+                Unziped directory 'docconfig_id'{
+                    Directory 'ConfigTypes',
+                    Directory 'DataSources',
+                    file 'doc-config.json',
+                    file 'TemplateName.docx'
+                }
+            }
+
+    Run without --unzip flag
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password'
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
+        # Created:
+            Directory 'sfdc/export_folder_name'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
                     Directory 'ConfigTypes',
                     Directory 'DataSources',
                     file 'doc-config.json',
@@ -143,7 +180,7 @@ EXAMPLES
 
         $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
             -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
-            -a 'pdf_butler_user_name-ADMIN:admin_password' --logs
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -l
 
         # Console output:
             Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
@@ -155,8 +192,8 @@ EXAMPLES
 
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json',
-                zip file'archive_name.zip'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
                     Directory 'ConfigTypes',
                     Directory 'DataSources',
                     file 'doc-config.json',
@@ -175,8 +212,96 @@ EXAMPLES
 
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json',
-                zip file'archive_name.zip'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
+                    Directory 'ConfigTypes',
+                    Directory 'DataSources',
+                    file 'doc-config.json',
+                    file 'TemplateName.docx'
+                }
+            }
+
+    Run with --partial flag only and docconfig with backend part
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -p
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
+        # Created:
+            Directory 'sfdc/export_folder_name'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
+                    Directory 'ConfigTypes',
+                    Directory 'DataSources',
+                    file 'doc-config.json',
+                    file 'TemplateName.docx'
+                }
+            }
+
+    Run with --partial flag only and docconfig without backend part
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id_1, document_configuration_id_2'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -p
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
+        # Created:
+            Directory 'sfdc/export_folder_name'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
+                    Directory 'ConfigTypes',
+                    Directory 'DataSources',
+                    file 'doc-config.json',
+                    file 'TemplateName.docx'
+                }
+            }
+
+    Run without --partial flag and docconfig without backend part
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id_1, document_configuration_id_2'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password'
+
+        # Console output:
+            Error (1): One or more docConfigs have no backend.
+
+    Run with --backend flag and other optional flags
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -b [-u | -l | -p]
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
+        # Created:
+            Directory 'sfdc/export_folder_name'{
+                file 'docconfig_id.json'
+            }
+
+    Run with --unzip and --logs flags
+
+        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
+            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
+            -a 'pdf_butler_user_name-ADMIN:admin_password' -u -l
+
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+            DocConfig exported - 10061
+            Exported data from backend - 71940
+            Exported data from backend has been archived
+            User has read/write permissions
+            Archive unzipped and recorded locally
+
+        # Created:
+            Directory 'sfdc/export_folder_name'{
+                file 'docconfig_id.json',
+                Unziped directory 'docconfig_id'{
                     Directory 'ConfigTypes',
                     Directory 'DataSources',
                     file 'doc-config.json',
@@ -190,10 +315,13 @@ EXAMPLES
             -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://www.pdfbutler.com'
             -a 'pdf_butler_user_name-ADMIN:admin_password'
 
+        # Console output:
+            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0
+
         # Created:
             Directory 'sfdc/export_folder_name'{
-                file 'docconfig.json',
-                zip file'archive_name.zip'{
+                file 'docconfig_id.json',
+                zip file'docconfig_id.zip'{
                     Directory 'ConfigTypes',
                     Directory 'DataSources',
                     file 'doc-config.json',
@@ -237,7 +365,10 @@ FLAG DESCRIPTIONS
         If specified, the exported configuration will be unzipped after the export process is complete.
 
     -l, --logs
-         Use this flag to enable a more detailed log of the migration process.
+        Use this flag to get a more detailed log of migration process.
+
+    -p, --partial
+        Use this flag to ignore invalid document configurations and allow the export of document configuration files with the backend part.
 ```
 
 ## butler pb import
@@ -253,7 +384,8 @@ FLAGS
     -a, --auth-env-var=<value>    The PDF Butler credentials for backend authentication. (Required)
     -e, --endpoint=<value>        The URL PDF Butler endpoint for import. (Required)
     -s, --stage=<value>           The CADMUS stage. (Required)
-    -f, --config=<value>          The path to the configuration file or directory containing configurations to import. (Required)
+    -f, --config=<value>          The path to the directory containing configurations to import. (Required)
+    -l, --logs                   Use it to get a more detailed log of migration process. (Optional)
 
 DESCRIPTION
     Import DocConfigs and related DataSource files into your organization.
@@ -291,4 +423,140 @@ FLAG DESCRIPTIONS
     -f, --config <value>
         Specifies the path to the configuration file or directory containing configurations to import.
         This flag is required to determine which configurations to import.
+        
+    -l, --logs
+        Use this flag to get a more detailed log of migration process.
+```
+
+## Typical errors and solutions
+
+Typical errors that may occur when using the plugin and their solutions.
+
+### Export
+
+- EPERM operation not permitted, chmod 'path_to_directory_to_export'.
+
+```
+SOLUTION: error typically occurs due to insufficient permissions. To resolve it, make sure you have the necessary permissions to write to the specified directory. You can use the chmod command to change the directory permissions.
+
+```
+
+- Error (1): Flag --target expects a value.
+
+```
+SOLUTION: When using the --target flag, make sure to provide a valid Salesforce org username after the flag.
+
+```
+
+- Error (1): No authorization information found for sfusername@sandbox.com.
+
+```
+SOLUTION: Ensure that you have provided the correct Salesforce username. Double-check your credentials and ensure that they are properly configured in the plugin.
+
+```
+
+- Error (1): Flag --id expects a value.
+
+```
+SOLUTION: When using the --id flag, make sure to provide a valid value after the flag. It should specify the ID or identifiers required for the export.
+
+```
+
+- Error (1): No matching Doc Configs ids found.
+
+```
+SOLUTION: Verify that the Doc Config IDs you provided are correct and exist in the system.
+
+```
+
+- Error (1): One or more docConfigs have no backend.
+
+```
+SOLUTION: This error indicates that some document configurations are missing backend part. Review the document configurations and ensure that they are properly configured with the required server modules. Or you can add the "-p --partial" flag to enable exporting those docconfigs that have a backend part.
+
+```
+
+- Error (1): Flag --out expects a value.
+
+```
+SOLUTION: When using the --out flag, ensure that you specify a valid directory path where the output should be saved.
+
+```
+
+- Error (1): Flag --stage expects a value.
+
+```
+SOLUTION: When using the --stage flag, make sure to provide a valid CADMUS stage.
+
+```
+
+- Error (1): Flag --auth-env-var expects a value.
+
+```
+SOLUTION: When using the --auth-env-var flag, provide the PDF Butler credentials for backend authentication. Ensure that the PDF Butler credentials is correctly set and contains the required credentials (Username and Admin password).
+
+```
+
+- Error (1): Flag --endpoint expects a value.
+
+```
+SOLUTION: When using the --endpoint flag, specify the correct endpoint URL as the value.
+
+```
+
+- Error (1): Response code 401 (Unauthorized).
+
+```
+SOLUTION: This error indicates that your request lacks proper authentication. Double-check your credentials like PDF Butler Username or PDF Butler Admin password. Correct example: 'Username-ADMIN:Admin_password'
+
+```
+
+- Error (1): System.LicenseException: The Apex Class RestImportDocConfig is part of the AppExchange Package PDF Butler, and requires a license to use.
+
+```
+SOLUTION: To resolve this error, you need to acquire the required license for the AppExchange Package PDF Butler to use the plugin command. Contact your Salesforce administrator or license provider to obtain the necessary license.
+
+```
+
+### Import
+
+- Error (1): Flag --target expects a value.
+
+```
+SOLUTION: When using the --target flag, make sure to provide a valid Salesforce org username after the flag.
+```
+
+- Error (1): Flag --auth-env-var expects a value.
+
+```
+SOLUTION:
+
+```
+
+- Error (1): Flag --auth-env-var expects a value.
+
+```
+SOLUTION: When using the --auth-env-var flag, provide the PDF Butler credentials for backend authentication. Ensure that the PDF Butler credentials is correctly set and contains the required credentials (Username and Admin password).
+
+```
+
+- Error (1): Flag --endpoint expects a value.
+
+```
+SOLUTION: When using the --endpoint flag, specify the correct endpoint URL as the value.
+
+```
+
+- Error (1): Flag --stage expects a value.
+
+```
+SOLUTION: When using the --stage flag, make sure to provide a valid CADMUS stage.
+
+```
+
+- Error (1): Flag --config expects a value.
+
+```
+SOLUTION: When using the --config flag, ensure that you specify a valid directory path to docconfigs.
+
 ```

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.11",
+  "version": "0.0.12",
   "commands": {
     "butler:pb:export": {
       "id": "butler:pb:export",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pdfbutler/migration-cli",
   "description": "[![NPM](https://img.shields.io/npm/v/pdfbutler-migration-cli.svg?label=pdfbutler-migration-cli)](https://www.npmjs.com/package/pdfbutler-migration-cli) [![Downloads/week](https://img.shields.io/npm/dw/pdfbutler-migration-cli.svg)](https://npmjs.org/package/pdfbutler-migration-cli) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/salesforcecli/pdfbutler-migration-cli/main/LICENSE.txt)",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "script": {
     "postinstall": "sf plugins link @pdfbutler/migration-cli"
   },