@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.
'-l --logs' flag. Use this flag to enable a more detailed log of the migration process.
'-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.

v.0.0.18 updates: This release introduces several new commands to enhance the management and deployment of PDFButler Packs and administrative settings in your org. Here’s a breakdown of the new commands and their functionality:

'exportpack'. Allows you to export a PDFButler Pack from the org to an external file.
'importpack'. Facilitates importing a previously exported PDFButler Pack into your org.
'adminsettings'. Allows you to configure critical PDFButler settings such as the service URL, region, and stage.
'admincredentials'. Enables you to securely provide or update the PDFButler admin credentials.

v.0.0.20 updates This release introduces an alternative authentication method to enhance flexibility when connecting to Salesforce. The new functionality includes support for session-based authentication, allowing users to connect without relying solely on username. Additionally, two new optional flags, --session and --instance, have been added to all commands to support this authentication method:

'--session'. Allows you to provide a Salesforce Session Id for authentication.
'--instance'. Specifies the Salesforce Instance URL for authentication.

v.0.0.24 updates This release introduces enhancements to filename handling, improving compatibility and usability when working with zipped files, particularly in Windows environments.

'--cut'. Trim filenames to a maximum of 150 characters to prevent issues when extracting a zipped file on Windows, as Windows Explorer cannot support file paths longer than 255 characters.
'--shortpaths'. The filename is just the DC name (drop the Stage and long DC Id in the filename).

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

Alternatively, you can provide the --session and --instance flags directly during command execution to authenticate using a Salesforce Session ID and Instance URL. This method allows you to bypass the browser-based login and authenticate seamlessly:

command ... --session "SessionId" --instance "https://yourInstance.sale

Pay attention! If you provide only the --target flag, authentication will occur using the specified target org credentials. However, if you also include the --session and --instance flags, these values will take precedence, and the authentication process will rely on the session-based method. This allows for a flexible authentication approach tailored to your needs.

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]
$ sf butler pb exportpack [options]
$ sf butler pb importpack [options]
$ sf butler pb adminsettings [options]
$ sf butler pb admincredentials [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] [--session <value>] [--instance <value>]

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 Customer Pack Id.  (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)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

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

        $ 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

        $ 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

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


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.

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

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] [--session <value>] [--instance <value>]

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)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

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)

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

butler pb exportpack

Important! Make sure you have installed PDF Butler version equal or higher than v1.440.

Export PDF Butler Pack.

USAGE
$ sf butler pb exportpack [--target | -t <value>] [--pack | -p <value>] [--out | -o <value>] [--logs | -l] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Required)
    -p, --pack=<value>             The Customer Pack Id of the PDF Butler Pack to export.
                                 For bulk export, enter multiple Customer Pack Ids separated by commas.  (Required)
    -o, --out=<value>            The value specifies the path to the folder with the exported configuration and archive name. (Required)
    -l, --logs                    Use it to get a more detailed log of migration process. (Optional)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

DESCRIPTION
    Export PDFButler Pack with related DocConfig, DataSources and Actionables from your organization.

    You must run this command from the termianl.

    By default, all your exported data is stored in a json file.

    To initiate an export, ensure you specify the necessary parameters, including the target org, Customer Pack Id and output path.

EXAMPLES
    Export single pack:

        $ sf butler pb exportpack -t sfusername@sandbox.com -p 'customer_pack_id'
            -o 'export_folder_name/folder_name' -l

        # Console output:
            [INFO] Username: "sfusername@sandbox.com"
            [INFO] Packs to retrieve: "customer_pack_id"
            [INFO] Directory to output: "export_folder_name/folder_name"
            [INFO] Try to connect to the org
            [INFO] Connected to sfusername@sandbox.com (session_id) with API version 62.0
            [INFO] Try to export pack by Id: customer_pack_id
            [INFO] Calling the service...
            [INFO] Saving to the directory
            [INFO] Directory hierarchy: ./export_folder_name/folder_name/sfdc
            [INFO] File path: ./export_folder_name/folder_name/sfdc/customer_pack_id.json
            [INFO] Data successfully written to ./export_folder_name/folder_name/sfdc/customer_pack_id.json

        # Created:
            Directory 'export_folder_name/folder_name/sfdc'{
                file 'customer_pack_id.json'
            }
    
    Export multiple packs:

        $ sf butler pb exportpack -t sfusername@sandbox.com -p 'customer_pack_id1, customer_pack_id2'
            -o 'export_folder_name/folder_name' -l

        # Console output:
            [INFO] Username: "sfusername@sandbox.com"
            [INFO] Packs to retrieve: "customer_pack_id1, customer_pack_id12"
            [INFO] Directory to output: "export_folder_name/folder_name"
            [INFO] Try to connect to the org
            [INFO] Connected to sfusername@sandbox.com (session_id) with API version 62.0
            [INFO] Try to export pack by Id: customer_pack_id1
            [INFO] Calling the service.
            [INFO] Saving to the directory
            [INFO] Directory hierarchy: ./export_folder_name/folder_name/sfdc
            [INFO] File path: ./export_folder_name/folder_name/sfdc/customer_pack_id1.json
            [INFO] Data successfully written to ./export_folder_name/folder_name/sfdc/customer_pack_id1.json
            [INFO] Try to export pack by Id: customer_pack_id12
            [INFO] Calling the service.
            [INFO] Saving to the directory
            [INFO] Directory hierarchy: ./export_folder_name/folder_name/sfdc
            [INFO] File path: ./export_folder_name/folder_name/sfdc/customer_pack_id12.json
            [INFO] Data successfully written to ./ -/sfdc/customer_pack_id12.json

        # Created:
            Directory 'export_folder_name/folder_name/sfdc'{
                file 'customer_pack_id1.json'
                file 'customer_pack_id2.json'
            }

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

    -p, --pack <value>
        Specifies the Customer Pack Id of the PDF Butler Pack to be exported.
        This ID uniquely identifies the pack you want to export. It is a required parameter.

    -o, --out <value>
        Specifies the path to the directory where to export packs. This flag is required.

    -l, --logs
        Use it to get a more detailed log of migration process.

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

butler pb importpack

Important! Make sure you have installed PDF Butler version equal or higher than v1.440.

Import PDF Butler Pack.

USAGE
$ sf butler pb importpack [--target | -t <value>] [--pack | -p <value>] [--folder | -f <value>] [-logs | -l] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Required)
    -p, --pack=<value>             The Customer Pack Id of the PDF Butler Pack to export.
                                 For bulk export, enter multiple Customer Pack Ids separated by commas.  (Required)
    -f, --folder=<value>            The value specifies the path to the folder with the exported packs. (Required)
    -l, --logs                    Use it to get a more detailed log of migration process. (Optional)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

DESCRIPTION
    Import PDFButler Pack with related DocConfig, DataSources and Actionables 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, Customer Pack Id and folder path.

EXAMPLES
    import single pack:

        $ sf butler pb importpack -t sfusername@sandbox.com -p 'customer_pack_id'
            -f 'export_folder_name/folder_name/sfdc' -l

        # Console output:
            [INFO] Username: "sfusername@sandbox.com"
            [INFO] Packs to import: "customer_pack_id1"
            [INFO] Folder to retrieve: "export_folder_name/folder_name/sfdc"
            [INFO] Try to connect to the org
            [INFO] Connected to sfusername@sandbox.com (session_id) with API version 62.0
            [INFO] Retrieving items from the directory
            [INFO] Files found in folder: 1
            [INFO] Successfully imported  export_folder_name/folder_name/sfdc/customer_pack_id1.json
    
    Import multiple packs:

        $ sf butler pb importpack -t sfusername@sandbox.com -p 'customer_pack_id1, customer_pack_id2'
            -f 'export_folder_name/folder_name' -l

        # Console output:
            [INFO] Username: "sfusername@sandbox.com"
            [INFO] Packs to import: "customer_pack_id1, customer_pack_id2"
            [INFO] Folder to retrieve: "export_folder_name/folder_name/sfdc"
            [INFO] Try to connect to the org
            [INFO] Connected to sfusername@sandbox.com (session_id) with API version 62.0
            [INFO] Retrieving items from the directory
            [INFO] Files found in folder: 2
            [INFO] Successfully imported  export_folder_name/folder_name/sfdc/customer_pack_id1.json
            [INFO] Successfully imported  export_folder_name/folder_name/sfdc/customer_pack_id2.json

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

    -p, --pack <value>
        Specifies the unique Customer Pack Id of the PDF Butler Pack to be imported.
        This ID uniquely identifies the packs you want to import. It is a required parameter.

    -f, --folder <value>
        Specifies the path to the directory containing packs to import.
        This flag is required to determine which paksc to import.

    -l, --logs
        Use it to get a more detailed log of migration process.

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

butler pb adminsettings

Important! Make sure you have installed PDF Butler version equal or higher than v1.440.

Provide PDF Butler App Settings.

USAGE
$ sf butler pb adminsettings [--target | -t <value>] [--url | -u <value>] [--region | -r <value>] [--stage | -s <value>] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Required)
    -u, --url=<value>             The Cadmus Endpoint to set. (Required)
    -r, --region=<value>            The value specifies the region of PDF Butler account. (Required)
    -s, --stage=<value>            The value specifies the stage of the organisation. (Required)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

DESCRIPTION
    Allows you to configure critical PDFButler settings such as the service URL, region, and stage.

    You must run this command from the termianl.

EXAMPLES
    Set settings:

        $ sf butler pb adminsettings -t sfusername@sandbox.com -u 'https://us1.pdfbutler.com'
            -r 'LOCAL' -s 'TEST'

        # Console output:
            [INFO] Authenticating user: sfusername@sandbox.com
            [INFO] Connected to sfusername@sandbox.com (Org ID: org_id)
            [INFO] Sending data to ***:
            {
                "url":"https://us1.pdfbutler.com/",
                "region":"LOCAL",
                "stage":"TEST"
            }
            [INFO] Successfully imported settings.

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

    -u, --url <value>
        The base URL for the PDFButler service.

    -r, --region <value>
        Specifies the geographic region for the service (e.g., EU, US).

    -s, --stage <value>
        The deployment stage (e.g., dev, staging, production).

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

butler pb admincredentials

Important! Make sure you have installed PDF Butler version equal or higher than v1.440.

Setup the PDF Butler Admin Credentials.

USAGE
$ sf butler pb admincredentials [--target | -t <value>] [--username | -u <value>] [--password | -p <value>] [--user-password <value>] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Required)
    -u, --username=<value>             The admin username for PDFButler. (Required)
    -p, --password=<value>            The admin password for PDFButler. (Required)
    --user-password=<value>            The user password for PDFButler. (Required)
    --session=<value>            This flag is used to provide a Salesforce Session ID for authentication.
    --instance=<value>           This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

DESCRIPTION
    Enables you to securely provide or update the PDFButler admin credentials.

    You must run this command from the termianl.

EXAMPLES
    Set settings:

        $ sf butler pb admincredentials -t sfusername@sandbox.com -u 'username' 
             -p 'ADMIN_password' --user-password 'USER_password' -l

        # Console output:
            [INFO] Authenticating user: sfusername@sandbox.com
            [INFO] Connected to sfusername@sandbox.com (Org ID: org_id)
            [INFO] Sending data to endpoint: {
                "username": "sfusername@sandbox.com",
                "password": "ADMIN_password",
                "userPassword": "USER_password"
            }
            [INFO] Successfully imported user credentials.

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

    -u, --username <value>
        The admin username for PDFButler

    -p, --password <value>
        The admin password for PDFButler.

    --user-password <value>
        The user password for PDFButler.

    --session
        This flag is used to provide a Salesforce Session ID for authentication.
    
    --instance
        This flag specifies the Salesforce Instance URL. The Instance URL corresponds to the specific Salesforce environment (e.g., production, sandbox) you are connecting to.

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

9 months ago

8 months ago

8 months ago

8 months ago

6 months ago

11 months ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago