npm package: @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/packag
Author: pdfbutler
Latest version: 0.0.29

# pdfbutler-migration-cli

[![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://www.npmjs.com/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)

## Warning

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.
- `-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: <br/>

- 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: <br/>

- The `-c | --clone` flag has been added to the import command. Use `-c | --clone` to allow inserting new DocConfigs instead of updating existing ones.

v0.0.18 updates: <br/>
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.

v0.0.20 updates: <br/>
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: <br/>
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).

v0.0.28 updates: <br/>
DocConfigs with Templates — Export & Import Support

- Export and import operations now support DocConfigs together with their associated template DocConfigs.
- Use `-m | --templates` to include templates during both export and import.

DataSource — Export & Import Support

- DataSource import requires PDF Butler package version v1.505 or higher.
- `exportdatasource` — Exports PDF Butler DataSources from the org.
- `importdatasource` — Imports PDF Butler DataSources into the org from JSON

SB Sign Request Template — Export & Import Support

- `butler:sb:export:signtemplate` — Exports Sign Request Templates from the org and saves them as JSON files for backup or migration.
- `butler:sb:import:signtemplate` — Imports Sign Request Templates into the org from previously exported JSON files

v0.0.29 updates: <br/>
Export Pack — DocConfig Export Modes
- `exportpack` now supports DocConfig export modes via `-d | --docconfig`:
  - `none` (default) or without flag: export only pack JSON.
  - `lead`: export only leading DocConfig (without pack JSON).
  - `pack`: export only pack DocConfigs (without leading and without pack JSON).
  - `full`: export both pack JSON and all related DocConfigs.

Export Pack — Backend Bundle Support
- `exportpack` now supports backend bundle export for DocConfigs with:
  - `-a | --auth-env-var`, `-e | --endpoint`, `-s | --stage`
  - `-u | --unzip` to extract backend files instead of writing zip archives
  - `-m | --templates` to recursively export template DocConfigs

Import Pack — DocConfig Import Modes
- `importpack` now supports selective DocConfig import mode via `-d | --docconfig`:
  - `pack`: import only pack DocConfigs.
  - `lead`: import only leading DocConfig.
  - `full` (default): import DocConfigs and then import the pack.

Import Pack — Backend Bundle Support
- `importpack` backend/template import enhancements:
  - `-a | --auth-env-var`, `-e | --endpoint`, `-s | --stage` for backend upload.
  - `-m | --templates` to include template dependency DocConfigs.
  - `-c | --clone` to insert new DocConfigs instead of updating existing ones.

Backend Export Modes
- `-b | --backend` now supports modes: `full` (default, export SFDC + backend), `only` (backend only), and `none` (SFDC only).
- Backward compatibility: using `-b` without a value is interpreted as `--backend none`.


## 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 installation the plugin runs:

```
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](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth.htm) 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! <br/>
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]

$ sf butler sb export signtemplate [options]
$ sf butler sb import signtemplate [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 sb export signtemplate

Export Sign Request Template records from your organization.

```
USAGE
$ sf butler sb export signtemplate -i <value> -f <value> [--json] [-t <value>] [-l] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org.
    -i, --id=<value>             The Customer Template ID to export. For bulk export, enter multiple IDs separated by whitespaces. (Required)
    -f, --folder=<value>         The output root folder path. Files will be saved to the signRequestTemplates subfolder. (Required)
    -l, --logs                   Enable detailed logs for the export process.
    --session=<value>            Salesforce Session ID for authentication.
    --instance=<value>           Salesforce Instance URL for authentication.

DESCRIPTION
    Export Sign Request Template records from your organization.

EXAMPLES
    $ sf butler:sb:export:signtemplate -t my-org -i "a0Bxx0000000011 a0Bxx0000000012" -f "./export/sb"
```

## butler sb import signtemplate

Import Sign Request Template records into your organization.

```
USAGE
$ sf butler sb import signtemplate -i <value> -f <value> [--json] [-t <value>] [-l] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org.
    -i, --id=<value>             The Customer Template ID to import. For bulk import, enter multiple IDs separated by whitespaces. (Required)
    -f, --folder=<value>         The export root folder path that contains the signRequestTemplates subfolder. (Required)
    -l, --logs                   Enable detailed logs for the import process.
    --session=<value>            Salesforce Session ID for authentication.
    --instance=<value>           Salesforce Instance URL for authentication.

DESCRIPTION
    Import Sign Request Template records into your organization.

EXAMPLES
    $ sf butler:sb:import:signtemplate -t my-org -i "a0Bxx0000000011" -f "./export/sb"
```

## 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 <value>] [--unzip | -u] [-l | --logs] [-p | --partial] [-m | --templates] [--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=<value>        Backend export mode: full | only | none. (Optional, default: full)
    -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)
    -m, --templates              Include template DocConfigs in the export. (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 full (default)

        $ 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' --backend full

        # 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 --backend 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' --backend only

        # Console output:
            Connected to sfusername@sandbox.com (00D06000001aXGkEAM) with API version 58.0

        # Created:
            Directory 'export_folder_name/archive_or_folder_name'{
                zip file'docconfig_id.zip'{
                    Directory 'ConfigTypes',
                    Directory 'DataSources',
                    file 'doc-config.json',
                    file 'TemplateName.docx'
                }
            }

    Run with --backend none

        $ sf butler pb export -t sfusername@sandbox.com -i 'document_configuration_id'
            -o 'export_folder_name/archive_or_folder_name' -s 'TEST'
            --backend none

        # 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 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
        Controls what to export: full (SFDC + backend), only (backend only), none (SFDC only).
        Default value is full. For backward compatibility, using -b without a value is treated as --backend none.

    -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.

    -m, --templates
        Include template DocConfigs in the export.

    --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] [-m | --templates] [--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)
    -m, --templates               Include template DocConfigs in the import. (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 -m

    #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)

    -m, --templates
        Include template DocConfigs in the import.

    --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 exportdatasource

Export PDF Butler DataSource files.

```
USAGE
$ sf butler pb exportdatasource [--target | -t <value>] [--id | -i <value>] [--folder | -f <value>] [--stage | -s <value>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [-l | --logs] [-p | --parents] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Optional)
    -i, --id=<value>             The DataSource ID(s) to export. For bulk export, enter multiple IDs separated by commas or spaces. (Required)
    -f, --folder=<value>         The output folder where DataSource JSON files will be saved. (Required)
    -s, --stage=<value>          The CADMUS stage. (Required)
    -a, --auth-env-var=<value>   The PDF Butler credentials for backend authentication. (Optional)
    -e, --endpoint=<value>       The URL PDF Butler endpoint for export. (Optional)
    -l, --logs                   Use it to get a more detailed log of migration process. (Optional)
    -p, --parents                Automatically export parent DataSources recursively when detected. (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 DataSources from your organization into JSON files.

    The command writes files into:
    ./<folder>/sfdc/<DataSourceId>.json

EXAMPLES
    Export a single DataSource:

        $ sf butler pb exportdatasource -t sfusername@sandbox.com -i '00Dxxxxxxxxxxxx' -f 'export' -s 'TEST'

    Export multiple DataSources:

        $ sf butler pb exportdatasource -t sfusername@sandbox.com -i '00Dxxx, 00Dyyy' -f 'export' -s 'TEST' -l

    Export with parent DataSources:

        $ sf butler pb exportdatasource -t sfusername@sandbox.com -i '00Dxxx' -f 'export' -s 'TEST' -p
```

## butler pb importdatasource

Import PDF Butler DataSource files.

```
USAGE
$ sf butler pb importdatasource [--target | -t <value>] [--id | -i <value>] [--folder | -f <value>] [--stage | -s <value>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [-l | --logs] [-p | --parents] [--session <value>] [--instance <value>]

FLAGS
    -t, --target=<value>         The Salesforce org username credentials to connect to the target org. (Optional)
    -i, --id=<value>             The DataSource ID(s) to import. For bulk import, enter multiple IDs separated by commas or spaces. (Required)
    -f, --folder=<value>         The folder that contains exported DataSource JSON files. (Required)
    -s, --stage=<value>          The CADMUS stage. (Optional)
    -a, --auth-env-var=<value>   The PDF Butler credentials for backend authentication. (Optional)
    -e, --endpoint=<value>       The URL PDF Butler endpoint for import. (Optional)
    -l, --logs                   Use it to get a more detailed log of migration process. (Optional)
    -p, --parents                Resolve and import parent DataSources first, then child DataSources. (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 DataSources from JSON files into your organization.

    The command reads files from:
    ./<folder>/sfdc/<DataSourceId>.json

EXAMPLES
    Import a single DataSource:

        $ sf butler pb importdatasource -t sfusername@sandbox.com -i '00Dxxxxxxxxxxxx' -f 'export' -s 'TEST'

    Import multiple DataSources:

        $ sf butler pb importdatasource -t sfusername@sandbox.com -i '00Dxxx, 00Dyyy' -f 'export' -s 'TEST' -l

    Import with parent DataSources first:

        $ sf butler pb importdatasource -t sfusername@sandbox.com -i '00Dxxx' -f 'export' -s 'TEST' -p
```

## butler pb exportpack

<span style="color: red;">Important!</span> Make sure you have installed PDF Butler version equal or higher than v1.440. <br/>

Export PDF Butler Pack.

```
USAGE
$ sf butler pb exportpack [--target | -t <value>] [--pack | -p <value>] [--out | -o <value>] [--logs | -l] [--docconfig | -d <none|pack|lead|full>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [--stage | -s <value>] [--unzip | -u] [--templates | -m] [--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)
    -d, --docconfig=<none|pack|lead|full>
                                 Export mode for related DocConfigs. (Optional, default: none)
    -a, --auth-env-var=<value>   The PDF Butler credentials for backend authentication. (Optional)
    -e, --endpoint=<value>       The URL PDF Butler endpoint for backend export. (Optional)
    -s, --stage=<value>          The CADMUS stage for backend export. (Optional)
    -u, --unzip                  Unzip backend export instead of saving DocConfig archives as zip files. (Optional)
    -m, --templates              Include template DocConfigs for recursive export. (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'
            }

    Export only leading DocConfig (without pack JSON):

        $ sf butler pb exportpack -p customer_pack_id
            -t sfusername@sandbox.com -a pdf_butler_user-ADMIN:admin_password
            -e https://eu1.pdfbutler.com -s TEST -o ./export/pack -l
            --session <session_id> --instance <instance_url> -u -m -d lead

        # Created:
            Directory './export/pack/sfdc'{
                file 'leading_docconfig_id.json'
            }

    Export only pack DocConfigs (without leading and without pack JSON):

        $ sf butler pb exportpack -p customer_pack_id
            -t sfusername@sandbox.com -a pdf_butler_user-ADMIN:admin_password
            -e https://eu1.pdfbutler.com -s TEST -o ./export/pack -l
            --session <session_id> --instance <instance_url> -u -m -d pack

        # Created:
            Directory './export/pack/sfdc'{
                file 'pack_docconfig_id_1.json'
                file 'pack_docconfig_id_2.json'
            }

    Export full content (pack JSON + DocConfigs + backend zips):

        $ bin\dev butler:pb:exportpack -p customer_pack_id
            -t sfusername@sandbox.com -a pdf_butler_user-ADMIN:admin_password
            -e https://eu1.pdfbutler.com -s TEST -o ./export/pack -l
            --session <session_id> --instance <instance_url> -u -m -d full

        # Created:
            Directory './export/pack'{
                Directory 'sfdc'{
                    file 'customer_pack_id.json'
                    file 'docconfig_id.json'
                    file 'template_docconfig_id.json'
                },
                file 'docconfig_id.zip'
                file 'template_docconfig_id.zip'
            }

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

<span style="color: red;">Important!</span> Make sure you have installed PDF Butler version equal or higher than v1.440. <br/>

Import PDF Butler Pack.

```
USAGE
$ sf butler pb importpack [--target | -t <value>] [--pack | -p <value>] [--folder | -f <value>] [-logs | -l] [--docconfig | -d <pack|lead|full>] [--auth-env-var | -a <value>] [--endpoint | -e <value>] [--stage | -s <value>] [--templates | -m] [--clone | -c] [--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)
    -d, --docconfig=<pack|lead|full>
                                 Import mode for related DocConfigs. (Optional, default: full)
                                 Note: if mode is not full, only DocConfigs are imported and pack import is skipped.
    -a, --auth-env-var=<value>   The PDF Butler credentials for backend upload. (Optional)
    -e, --endpoint=<value>       The URL PDF Butler endpoint for backend upload. (Optional)
    -s, --stage=<value>          The CADMUS stage for backend upload. (Optional)
    -m, --templates              Include template dependency DocConfigs during import. (Optional)
    -c, --clone                  Insert new DocConfigs instead of updating existing 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 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

    Import only pack DocConfigs (skip pack import):

        $ bin\dev butler:pb:importpack -p customer_pack_id
            -f ./export/pack -t sfusername@sandbox.com -l -d pack

    Import only leading DocConfig (skip pack import):

        $ bin\dev butler:pb:importpack -p customer_pack_id
            -f ./export/pack -t sfusername@sandbox.com -l -d lead

    Import full content with templates and clone mode:

        $ bin\dev butler:pb:importpack -p customer_pack_id -f ./export/pack
            -t sfusername@sandbox.com -a pdf_butler_user-ADMIN:admin_password
            -e https://eu1.pdfbutler.com -s TEST -l --session <session_id>
            --instance <instance_url> -m -c -d full

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

<span style="color: red;">Important!</span> Make sure you have installed PDF Butler version equal or higher than v1.440. <br/>

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

<span style="color: red;">Important!</span> Make sure you have installed PDF Butler version equal or higher than v1.440. <br/>

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.

```

- Error (1): DataSource import failed. Check the JSON and try again.

```
SOLUTION: Ensure PDF Butler package version is at least v1.505 and validate the DataSource JSON files.

```