@pdfbutler/migration-cli
v0.0.29
Published
[](https://www.npmjs.com/package/pdfbutler-migration-cli) [](https://npmjs.org/packag
Maintainers
andriiisakovReadme
pdfbutler-migration-cli
Warning
v0.0.11 updates:
-bflag 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 | --logsflag. Use this flag to enable a more detailed log of the migration process.-p | --partialflag. 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 | --idflag 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 | --cloneflag has been added to the import command. Use-c | --cloneto allow inserting new DocConfigs instead of updating existing ones.
v0.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.
v0.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).
v0.0.28 updates: DocConfigs with Templates — Export & Import Support
- Export and import operations now support DocConfigs together with their associated template DocConfigs.
- Use
-m | --templatesto 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: Export Pack — DocConfig Export Modes
exportpacknow 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
exportpacknow supports backend bundle export for DocConfigs with:-a | --auth-env-var,-e | --endpoint,-s | --stage-u | --unzipto extract backend files instead of writing zip archives-m | --templatesto recursively export template DocConfigs
Import Pack — DocConfig Import Modes
importpacknow 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
importpackbackend/template import enhancements:-a | --auth-env-var,-e | --endpoint,-s | --stagefor backend upload.-m | --templatesto include template dependency DocConfigs.-c | --cloneto insert new DocConfigs instead of updating existing ones.
Backend Export Modes
-b | --backendnow supports modes:full(default, export SFDC + backend),only(backend only), andnone(SFDC only).- Backward compatibility: using
-bwithout 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 installIf you've installed Node.js on your computer, you can use npm to install Salesforce CLI:
npm install @salesforce/cli --globalFor installation the plugin runs:
sf plugins install @pdfbutler/migration-cliTo see your installed plugins and their versions, run:
sf pluginsTo see which versions of the core Salesforce-provided plugins are installed on your computer, run:
sf plugins --coreBefore 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 webAlternatively, 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.salePay 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]
$ 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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -i 'document_configuration_id'
-o 'export_folder_name/archive_or_folder_name' -s 'TEST'
--backend none
# Console output:
Connected to [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] (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 [email protected] -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 [email protected] -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 [email protected] -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 [email protected] -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 [email protected] -i '00Dxxxxxxxxxxxx' -f 'export' -s 'TEST'
Export multiple DataSources:
$ sf butler pb exportdatasource -t [email protected] -i '00Dxxx, 00Dyyy' -f 'export' -s 'TEST' -l
Export with parent DataSources:
$ sf butler pb exportdatasource -t [email protected] -i '00Dxxx' -f 'export' -s 'TEST' -pbutler 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 [email protected] -i '00Dxxxxxxxxxxxx' -f 'export' -s 'TEST'
Import multiple DataSources:
$ sf butler pb importdatasource -t [email protected] -i '00Dxxx, 00Dyyy' -f 'export' -s 'TEST' -l
Import with parent DataSources first:
$ sf butler pb importdatasource -t [email protected] -i '00Dxxx' -f 'export' -s 'TEST' -pbutler 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] [--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 [email protected] -p 'customer_pack_id'
-o 'export_folder_name/folder_name' -l
# Console output:
[INFO] Username: "[email protected]"
[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 [email protected] (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 [email protected] -p 'customer_pack_id1, customer_pack_id2'
-o 'export_folder_name/folder_name' -l
# Console output:
[INFO] Username: "[email protected]"
[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 [email protected] (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 [email protected] -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 [email protected] -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 [email protected] -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
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] [--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 [email protected] -p 'customer_pack_id'
-f 'export_folder_name/folder_name/sfdc' -l
# Console output:
[INFO] Username: "[email protected]"
[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 [email protected] (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 [email protected] -p 'customer_pack_id1, customer_pack_id2'
-f 'export_folder_name/folder_name' -l
# Console output:
[INFO] Username: "[email protected]"
[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 [email protected] (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 [email protected] -l -d pack
Import only leading DocConfig (skip pack import):
$ bin\dev butler:pb:importpack -p customer_pack_id
-f ./export/pack -t [email protected] -l -d lead
Import full content with templates and clone mode:
$ bin\dev butler:pb:importpack -p customer_pack_id -f ./export/pack
-t [email protected] -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
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 [email protected] -u 'https://us1.pdfbutler.com'
-r 'LOCAL' -s 'TEST'
# Console output:
[INFO] Authenticating user: [email protected]
[INFO] Connected to [email protected] (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 [email protected] -u 'username'
-p 'ADMIN_password' --user-password 'USER_password' -l
# Console output:
[INFO] Authenticating user: [email protected]
[INFO] Connected to [email protected] (Org ID: org_id)
[INFO] Sending data to endpoint: {
"username": "[email protected]",
"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 [email protected].
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.