@pdfbutler/migration-cli NPM

pdfbutler-migration-cli

Warning

v0.0.11 updates:

'-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 '-p --partial' flag. Use this flag to ignore invalid document configurations and allow the export of document configuration files with the backend part.

v0.0.14 updates:

The '-i --id' flag has been added to the import command to specify the IDs of the PDF Butler document configurations that require importing. This is a required flag.

v0.0.17 updates:

The '-c' or '--clone' flag has been added to the import command. Use '-c' or '--clone' to allow inserting new DocConfigs instead of updating existing ones.

About

@pdfbutler/migration-cli is a Salesforce plugin designed to simplify and automate the process of migrating configurations within the PDF Butler system in the Salesforce environment. PDF Butler is a powerful tool for generating and automating documents in the Salesforce platform, and the use of this CLI plugin allows users to easily manage configurations and transfer them between different Salesforce instances or projects.

Main features of the plugin:

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

To install this plugin, make sure you have Node.js and npm (Node Package Manager) installed on your computer. If you don't have them, you can download Node.js from the official website, and npm will be installed along with it.

npm install
yarn install

If you've installed Node.js on your computer, you can use npm to install Salesforce CLI:

npm install @salesforce/cli --global

For install the plugin run:

sf plugins install @pdfbutler/migration-cli

To see your installed plugins and their versions, run:

sf plugins

To see which versions of the core Salesforce-provided plugins are installed on your computer, run:

sf plugins --core

Before running commands that require access to the Salesforce org, you must be authorized in the target org. One of the options to authorize an org is by running a CLI command and entering your credentials in the browser that automatically opens:

sf org login web

After the installation and authorization are complete, you can call this plugin by using its name in the terminal or command prompt to export and import PDF Butler configurations in Salesforce. For example:

$ sf butler pb export [options]
$ sf butler pb import [options]

Recommended CLI Shell:

Windows - PowerShell
MacOS - zsh
Linux - bash

One of the common errors in Windows Command Prompt is incorrectly parsing command parameters within quotes.

Commands

butler pb export

Export PDF Butler configurations.

USAGE
$ 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)
    -i, --id=<value>             The ID of the PDF Butler document configuration to export.
                                 For bulk export, enter multiple docuemnt configuration IDs separated by whitespaces.  (Required)
    -o, --out=<value>            The value specifies the path to the folder with the exported configuration and archive name. (Required)
    -s, --stage=<value>          The CADMUS stage. (Required)
    -a, --auth-env-var=<value>   The PDF Butler credentials for backend authentication. (Required)
    -e, --endpoint=<value>       The URL PDF Butler endpoint for export. (Required)
                                 Please use the following region-specific URLs on the region in which you registered:
                                 US: https://us1.pdfbutler.com
                                 EU: https://eu1.pdfbutler.com
                                 APAC: https://apac1.pdfbutler.com
                                 CA: https://ca1.pdfbutler.com

    -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. (Optional)

DESCRIPTION
    Export DocConfigs and related DataSource files from your organization.

    You must run this command from the termianl.

    By default, all your exported data is stored in a zip file.
    To unzip the data to a directory during the export process, use the -u | flag --unzip.

    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,
    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 --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://eu1.pdfbutler.com'
            -a 'pdf_butler_user_name-ADMIN:admin_password' -b

        # Console output:
            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0

        # Created:
            Directory 'export_folder_name/archive_or_folder_name/sfdc'{
                file 'docconfig_id.json'
            }

    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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    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

        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'docconfig_id.json',
                },
                zip file'docconfig_id.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    Run with --logs 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://eu1.pdfbutler.com'
            -a 'pdf_butler_user_name-ADMIN:admin_password' -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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'docconfig_id.json',
                },
                zip file'docconfig_id.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    Run without --logs 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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    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 (bulk export)

        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id_1, invalid_document_configuration_id_2'
            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'docconfig_id_1.json',
                },
                zip file'docconfig_id_1.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    Run without --partial flag (bulk export)

        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id_1, invalid_document_configuration_id_2'
            -o 'export_folder_name/archive_or_folder_name' -s 'TEST' -e 'https://eu1.pdfbutler.com'
            -a 'pdf_butler_user_name-ADMIN:admin_password'

        # Console output:
            Error (1): One or more docConfigs have no backend.

    Run without --partial flag (bulk export)

        $ 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://eu1.pdfbutler.com'
            -a 'pdf_butler_user_name-ADMIN:admin_password'

        # Created:
            Directory 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'docconfig_id_1.json',
                    file 'docconfig_id_2.json',
                },
                zip file'docconfig_id_1.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                },
                zip file'docconfig_id_2.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    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://eu1.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 'export_folder_name/archive_or_folder_name/sfdc'{
                file 'docconfig_id_1.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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'document_configuration_id.json',
                },
                Unziped directory 'document_configuration_id'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    Run without 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://eu1.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 'export_folder_name/archive_or_folder_name'{
                Directory 'sfdc'{
                    file 'document_configuration_id.json',
                },
                zip file'document_configuration_id.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

FLAG DESCRIPTIONS
    -t, --target <value>
        Specifies the Salesforce org username credentials to connect to the target org where the PDF Butler configurations are stored.
        This flag is required to authenticate and access the PDF Butler configurations.

    -i, --id <value>
        Specifies the unique ID of the PDF Butler document configuration to be exported. For bulk export, enter multiple docuemnt configuration IDs separated by whitespaces.
        This ID uniquely identifies the configuration you want to export. It is a required parameter.

    -o, --out <value>
        Specifies the path to the folder with the exported configuration and the archive or folder name for data sources.
        For example, if the flag is defined with the following values '-o butler/docConfigs', the result will be the following path: ./butler/docConfigs .
        This flag is required to determine where the exported configuration will be saved.

    -s, --stage <value>
        Specifies the stage or environment for the export process.
        This flag helps in categorizing or labeling the exported data according to different stages. For example: TEST, UAT, PROD.
        It is a required parameter.

    -e, --endpoint <value>
        Specifies a URL for the PDF Butler endpoint for export. For example: https://eu1.pdfbutler.com. It is a required parameter.

    -a, --auth-env-var <value>
        Specifies the PDF Butler credentials for backend authentication. For authenification should be used PDF butler username and admin password.
        String shouldn't contain whitespase. Format: 'YOUR_USERNAME + -ADMIN + ':' + YOUR_ADMIN_PASSWORD'. For example: test_user_dev-ADMIN:test_pass.
        It is a required parameter.

    -b, --backend
        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.

    -u, --unzip
        Use this flag to indicate that the exported configuration should be unzipped.
        If specified, the exported configuration will be unzipped after the export process is complete.

    -l, --logs
        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

Import PDF Butler document configurations and related DataSource files.

USAGE
$ sf butler pb import [--target | -t <value>] [--id | -i <value>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [--stage | -s <value>] [--config | -f <value>] [-c | --clone]

FLAGS
    -t, --target=<value>          The Salesforce org username credentials to connect to the target org. (Required)
    -i, --id=<value>              The ID of the PDF Butler docuemnt configurations to import.
                                  For bulk import, enter multiple docuemnt configuration IDs separated by whitespaces.(Required)
    -a, --auth-env-var=<value>    The PDF Butler credentials for backend authentication. (Required)
    -e, --endpoint=<value>        The URL PDF Butler endpoint for import. (Required)
                                  Please use the following region-specific URLs on the region in which you registered:
                                  US: https://us1.pdfbutler.com
                                  EU: https://eu1.pdfbutler.com
                                  APAC: https://apac1.pdfbutler.com
                                  CA: https://ca1.pdfbutler.com

    -s, --stage=<value>           The CADMUS stage. (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)
    -c, --clone                   Use this flag to disables the update of existing docconfigs and allows to create new ones. (Optional)

DESCRIPTION
    Import DocConfigs and related DataSource files into your organization.

    You must run this command from the termianl.

    To initiate an import, ensure you specify the necessary parameters, including the target org,
    define PDF Butler credentials for backend authentication, endpoint, stage, and the path to the configuration file or directory.
    All the targets are required parameters.

EXAMPLE
    Import configurations with --clone flag to the organization:

    $ sf butler pb import -t sfusername@sandbox.com -i 'document_configuration_id' -f .export_folder_name/archive_or_folder_name
        -e 'https://eu1.pdfbutler.com' -a 'pdf_butler_user_name-ADMIN:admin_password' -s 'UAT' -c

    #Imported:
        Insert a new Doc config with a unique 'customerDocumentConfigId'.

    Import configurations without --clone flag to the organization:

    $ sf butler pb import -t sfusername@sandbox.com -i 'document_configuration_id' -f .export_folder_name/archive_or_folder_name
        -e 'https://eu1.pdfbutler.com' -a 'pdf_butler_user_name-ADMIN:admin_password' -s 'UAT'

    #Imported:
        Update existing Doc config based on document_configuration_id.

    Bulk import configurations to the organization:

    $ sf butler pb import -t sfusername@sandbox.com -i 'document_configuration_id document_configuration_id2' -f .export_folder_name/archive_or_folder_name
        -e 'https://eu1.pdfbutler.com' -a 'pdf_butler_user_name-ADMIN:admin_password' -s 'UAT'

    #Imported:
        2 Doc configs, where the value of the field 'customerDocumentConfigId' is equal to document_configuration_id and document_configuration_id2, respectively.

FLAG DESCRIPTIONS
    -t, --target <value>
        Specifies the Salesforce org username credentials to connect to the target
        org where the PDF Butler configurations will be imported. This flag is required for authentication.

    -i, --id <value>
        Specifies the unique ID of the PDF Butler document configuration to be imported.
        This ID uniquely identifies the configuration you want to import. It is a required parameter.

    -a, --auth-env-var <value>
        Specifies the PDF Butler credentials for backend authentication. For authenification should be used PDF butler username and admin password.
        String shouldn't contain whitespase. Format: 'YOUR_USERNAME + -ADMIN + ':' + YOUR_ADMIN_PASSWORD'. For example: test_user_dev-ADMIN:test_pass.
        It is a required parameter.

    -e, --endpoint <value>
        Specifies a URL endpoint for import. Use this flag if you need to specify a custom import endpoint.

    -s, --stage <value>
        Specifies the stage or environment for the import process.
        This flag helps in categorizing or labeling the imported data according to different stages. For example: TEST, UAT, PROD.
        It is a required parameter.

    -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.

    -c, --clone
        Use this flag to disables the update of existing docconfigs and allows to create new ones. (Optional)

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.

force salesforce sfdx salesforcedx sfdx-plugin sf-plugin sf pdfbutler

@oclif/core @salesforce/core @salesforce/kit @salesforce/sf-plugins-core adm-zip got graceful-fs tslib

@everything-registry/sub-chunk-709

2 months ago

2 months ago

7 months ago

7 months ago

7 months ago

7 months ago

7 months ago

7 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago

8 months ago