@bit2winlab/bit2win-tempo NPM

b2w-sfdx-plugin-tempo

Tempo is a SFDX plugin that allow the orchestration of different bit2win related actions (e.g. Catalog, Datamap and flow management) and other sfdx actions (beta). The plugin can be used to automatize deployment actions and limit the number of error related to manual procedure.

Beta Please note that the tempo plugin is currenty in beta, contact your bit2win representatives if you plan to use it in a production environment.

System requirement

The functionality is released as a sfdx plugins. In order to work the following requirements must be met:

Node version ">=16.0.0" installed
Salesforce CLI 7.185 or later installed https://developer.salesforce.com/tools/sfdxcli

Installation steps

Run the command sfdx plugins install @bit2winlab/bit2win-tempo

bit2win:configuration

This folder contains all the commands related to the configuration of an environment

bit2win:configuration:loadbasedata

This command loads a set of predefined configurations in order to set up an org for the first use. The command can be launched from anywhere but requires an authenticated username and a devhub username in case of scratch loading.

Input parameters

-u | --targetusername: Scratch org user or alias
-v | --targetdevhubusername: Dev hub user
-b | --b2wginendpoint: Endpoint for the b2wgin services
-i | --b2wginuser: b2wgin user
-p | --b2wginpassword: b2wgin password
-s | --devorg: If true enable the settings of additional configuration (only for scratch org or sandboxes)
-e | --symphonyendpoint: Endpoint for the symphony services
-r | --symphonyuser: User for the symphony services
-w | --symphonypassword: Password for the symphony services
-n | --synchtoolendpoint: User for the synchtool services
-h | --synchtooluser: User for the synchtool services
-t | --synchtoolpassword: Password for the synchtool services
-p | --loaddatamaps: If true load all the datamaps (Only for first time installation)
-d | --updatedatamaps: If true update all the datamaps
-l | --showlog: If present activate verbose mode

The plugin will:

Generate the remote site settings for the endpoints provided
Load smart browser LOV
Load dynamic summary LOV
Load payback LOV
Create base integration administrations
Create a default cart admin
Synchronize the endpoints provided
Create the b2wgin connected app (if b2wgin credentials are provided)
Create the symphony connected app (if symphony credentials are provided)
Create the synchtool connected app (if synchtool credentials are provided)
Load all datamaps (if --loaddatamaps option is passed)
Update all datamaps (if --updatedatamaps option is passed)
(Only for scratch org) Activate flexi pages in the org
(Only for scratch org) Activate flexi pages for the b2win records detail
(Only for scratch org) Configure base custom settings
(Only for scratch org) Set up org settings (disable lightning advanced cache)

Example

sfdx bit2win:configuration:loadbasedata -u test-scratch@example.com --b2wginendpoint https://b2wginep.herokuapp.com/ --b2wginuser test_user_gin --b2wginpassword test_password_gin --loaddatamaps --devorg -v t.est@devhub.ifneeded.com

bit2win:configuration

This folder contains all the commands related to the datamap management

bit2win:datamap:export

Export the xml definitions of the requested datamaps

Input parameters

-u | --targetusername: Username or alias of the target org
-f | --targetfolder: folder where to save the extracted datamap files
-t | --type: Type of extraction. Available values are:
- list: accept a list of values separated by ","
- file: retrieve the list of datamaps from a file. The file contains a JSON definition {datamaps:[]} where the datamaps array contains the list of datamaps to retrieve
- class: retrieve a subset of datamaps
-v | --value: based on the type contains:
- The list of datamaps to extract (type: list)
- The path of the file (type: file)
- The class of extraction ("b2wgin","ordermanagement","synchtool","all")

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:export --targetusername myOrg@example.com --type list --value b2wgin_item,b2wgin_configuration

bit2win:datamap:import

Import the xml definitions of the requested datamaps

Input parameters

-u | --targetusername: Username or alias of the target org
-f | --sourcefolder: Folder containing the .xml files to import

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:import --targetusername myOrg@example.com --sourcefolder C:\\Users\\tester\\datamaps

bit2win:datamap:publish

Publish the list of datamaps provided to Heroku

Input parameters

-u | --targetusername: Username or alias of the target org
-t | --type: Type of extraction. Available values are:
- list: accept a list of values separated by ","
- file: retrieve the list of datamaps from a file. The file contains a JSON definition {datamaps:[]} where the datamaps array contains the list of datamaps to retrieve
- class: retrieve a subset of datamaps
-v | --value: based on the type contains:
- The list of datamaps to extract (type: list)
- The path of the file (type: file)
- The class of extraction ("b2wgin","ordermanagement","synchtool","all")

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:publish --targetusername myuser@mydomain.com --value CatalogXml2,ComplexProduct --type list

bit2win:datamap:reset

Reset the datamaps requested:

Input parameters

-u | --targetusername: Username or alias of the target org
-t | --type: Type of extraction. Available values are:
- list: accept a list of values separated by ","
- file: retrieve the list of datamaps from a file. The file contains a JSON definition {datamaps:[]} where the datamaps array contains the list of datamaps to retrieve
- class: retrieve a subset of datamaps
-v | --value: based on the type contains:
- The list of datamaps to extract (type: list)
- The path of the file (type: file)
- The class of extraction ("b2wgin","ordermanagement","synchtool","all")

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:reset --targetusername myuser@mydomain.com --value CatalogXml2,ComplexProduct --type list

bit2win:datamap:load

Load the datamaps requested:

Input parameters

-u | --targetusername: Username or alias of the target org
-t | --type: Type of extraction. Available values are:
- list: accept a list of values separated by ","
- file: retrieve the list of datamaps from a file. The file contains a JSON definition {datamaps:[]} where the datamaps array contains the list of datamaps to retrieve
- class: retrieve a subset of datamaps
-v | --value: based on the type contains:
- The list of datamaps to extract (type: list)
- The path of the file (type: file)
- The class of extraction ("b2wgin","ordermanagement","synchtool","all")

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:load --targetusername myuser@mydomain.com --value CatalogXml2,ComplexProduct --type list

bit2win:datamap:update

Update the datamaps requested.

Input parameters

-u | --targetusername: Username or alias of the target org
-t | --type: Type of extraction. Available values are:
- list: accept a list of values separated by ","
- file: retrieve the list of datamaps from a file. The file contains a JSON definition {datamaps:[]} where the datamaps array contains the list of datamaps to retrieve
- class: retrieve a subset of datamaps
-v | --value: based on the type contains:
- The list of datamaps to extract (type: list)
- The path of the file (type: file)
- The class of extraction ("b2wgin","ordermanagement","synchtool","all")

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:update --targetusername myuser@mydomain.com --value CatalogXml2,ComplexProduct --type list

bit2win:datamap:getlist

This method returns the datamaps available in the target org

Input parameters

-u | --targetusername: Username or alias of the target org

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:datamap:getlist --targetusername myuser@mydomain.com

bit2win:catalog

This folder contains all the commands related to the catalog management

bit2win:catalog:deploy

Retrieve a catalog from the sourceorg and deploy it in the target org provided

Input parameters

-c | --catalogexternalid: NESource_Catalog_Idc field of the catalog,
-u | --sourceusername: Source username for the target org
-t | --targetusername: Target username for catalog import
-i | --ignoreerrors: Ignore publish errors
-s | --savedirectory: If present save the catalog zip into the directory provided,
-d | --delta: Activate delta mode. This could lead to destructive actions. Default false
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:deploy --catalogexternalid 0981ddasd00001 --sourceusername source@test.com --targetusername target@test.com

bit2win:catalog:export

Export a catalog into a .zip file into the system

Input parameters

-u | --targetusername: Username or alias of the target org
-c | --catalogexternalid: NESource_Catalog_Idc field of the catalog
-i | --ignoreerrors: Ignore publish errors
-s | --savedirectory: If present save the catalog zip into the directory provided
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
catalog_url: Url where the catalog archive generated is stored
zip_file: Path to the zip file generated (if requested)

Example

sfdx bit2win:catalog:export --targetusername myuser@mydomain.com --catalogexternalid 0981ddasd00001

bit2win:catalog:import

Import the catalog from a .zip file to the provided target org

Input parameters

-u | --targetusername: Username or alias of the target org
-c | --catalogfileurl: File url of the catalog. Only url are allowed,
-i | --ignoreerrors: Ignore publish errors
-d | --delta: Activate delta mode. This could lead to destructive actions. Default false.
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:import --targetusername myuser@mydomain.com --catalogfileurl https://synchtoolendpoint.com/filedownload/

bit2win:catalog:publish

Publish the selected catalog

Input parameters

-u | --targetusername: Username or alias of the target org
-c | --catalogexternalid: NESource_Catalog_Idc field of the catalog,
-i | --ignoreerrors: Ignore publish errors
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:publish --targetusername myuser@mydomain.com --catalogexternalid 0981ddasd00001

bit2win:catalog:recreateprograms

Recreate all the programs from the selected catalog including the ones related to the catalog items

Input parameters

-u | --targetusername: Username or alias of the target org
-c | --catalogexternalid: NESource_Catalog_Idc field of the catalog
-i | --ignoreerrors: Ignore recreate errors
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:recreateprograms --targetusername myuser@mydomain.com --catalogexternalid 0981ddasd00001

bit2win:catalog:synchronize

Synchronize all the rules of a catalog, including the ones related to the catalog items

Input parameters

-u | --targetusername: Username or alias of the target org
-c | --catalogexternalid: NESource_Catalog_Idc field of the catalog
-i | --ignoreerrors: Ignore synch errors
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:synchronize --targetusername myuser@mydomain.com --catalogexternalid 0981ddasd00001

bit2win:catalog:item

This folder contains all the commands related to the catalog item management. Please notice that only export is available beacuse in order to load the archive generated by the export the generic bit2win:catalog:import command can be used

bit2win:catalog:item:deploy

Retrieve a list of catalog items from the sourceorg and deploy it in the target org provided

Input parameters

-c | --itemexternalids: NEIdc field of the catalog items to deploy, , use ; as separator
-u | --sourceusername: Source username for the target org
-t | --targetusername: Target username for catalog items import
-i | --ignoreerrors: Ignore publish errors
-s | --savedirectory: If present save the catalog items zip into the directory provided,
-d | --delta: Activate delta mode. This could lead to destructive actions. Default false
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:item:deploy --itemexternalids 0981ddasd00001 --sourceusername source@test.com --targetusername target@test.com

bit2win:catalog:item:export

Export a list of catalog items into a .zip file

Input parameters

-u | --username: Username or alias of the target org
-x | --itemexternalids: NEIdc field of the catalog items to export, use ; as separator
-i | --ignoreerrors: Ignore publish errors, default false
-s | --savedirectory: If present save the catalog zip into the directory provided
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
export_url: Url where the catalog items archive generated is stored
zip_file: Path to the zip file generated (if requested)

Example

sfdx bit2win:catalog:item:export --username myuser@mydomain.com --itemexternalids 0981ddasd00001

bit2win:catalog:item:publish

Publish the requested catalog items

Input parameters

-u | --username: Username or alias of the target org
-x | --itemexternalids: NEIdc field of the catalog items to publish, use ; as separator,
-i | --ignoreerrors: Ignore publish errors, default false
-s | --includeSubCategories: Include sub categories in request
-e | --skipExpiredElement: Skip expired items based in the expirationDate input
-d | --expirationDate: Set expiration date to use
-v | --version: Version to publish, if null then all version will be published, if equal to "last" only the latest version will be published
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:item:publish --username myuser@mydomain.com --x 0981ddasd00001

bit2win:catalog:item:recreateprograms

Recreate all the programs from the selected catalog items

Input parameters

-u | --username: Username or alias of the target org
-x | --itemexternalids: NEIdc field of the catalog items to publish use ; as separator,
-i | --ignoreerrors: Ignore publish errors, default false
-s | --includeSubCategories: Include sub categories in request
-e | --skipExpiredElement: Skip expired items based in the expirationDate input
-d | --expirationDate: Set expiration date to use
-v | --version: Version to publish, if null then all version will be published, if equal to "last" only the latest version will be published
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:item:recreateprograms --username myuser@mydomain.com --itemexternalids 0981ddasd00001

bit2win:catalog:item:synchronize

synchronize all the rules related to the selected catalog items

Input parameters

-u | --username: Username or alias of the target org
-x | --itemexternalids: NEIdc field of the catalog items to publish use ; as separator,
-i | --ignoreerrors: Ignore publish errors, default false
-s | --includeSubCategories: Include sub categories in request
-e | --skipExpiredElement: Skip expired items based in the expirationDate input
-d | --expirationDate: Set expiration date to use
-v | --version: Version to publish, if null then all version will be published, if equal to "last" only the latest version will be published
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:catalog:item:synchronize --username myuser@mydomain.com --itemexternalids 0981ddasd00001

bit2win:archetype

This folder contains all the commands related to the archetypes management.

bit2win:archetype:export

This method is used to export an archetyope into a zip file.

Input parameters

-u | --username: Username or alias of the target org
-x | --externalids: Bit2ArchetypesExternal_Idc field of the record to be exported, use ; as separator,
-t | --type: Type of export (archetype, instance, row)
-s | --scopes: filter data exported (archetype, row, instance). Default all
-d | --savedirectory: Save the export zip into the directory provided
-n | --archivename: Force the name of the archive file, if not provided a random name will be generated
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
zip_file: Path to the zip file generated

Example

sfdx bit2win:archetype:export --u myuser@mydomain.com -d C:/test/test/Sfdx-Plugin/projectgen/ -x a1X1q000000HjiaEAC -t archetype

bit2win:archetype:import

Import an archive into the selected environment

Input parameters

-u | --username: Username or alias of the target org
-f | --archive: Path to the zip file to import
-s | --synchafterfinish: Ignore publish errors, default false
-s | --savedirectory: Synch rules after finish
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
export_url: Url where the catalog items archive generated is stored
zip_file: Path to the zip file generated (if requested)

Example

sfdx bit2win:archetype:import --targetusername myuser@mydomain.com --archive C:/test/test/Sfdx-Plugin/projectgen/export.zip

bit2win:archetype:synchronize

This method is used to syncrhonize an archetype instance or all the instances related to an archetype

Input parameters

-u | --username: Username or alias of the target org
-x | --itemexternalids: NESource_Catalog_Idc of an instance or an archetype, use ; as limitator
-t | --type: archetype or instance. Type of synchronization
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:archetype:synchronize --targetusername myuser@mydomain.com --externalids 0981ddasd00001;0981ddasd00002

bit2win:flow

This folder contains all the commands related to the flow management

bit2win:flow:deploy

Retrieve a flow from the sourceorg and deploy it in the target org provided

Input parameters

-f | --flowname: Unique flow name
-u | --sourceusername: Source username for flow export
-t | --targetusername: Target username for flow import
-d | --deleteafter: Delete the zip file after import. Default false.
-s | --savedirectory: If present save the catalog zip into the directory provided
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:flow:deploy --flowname go_flow --savedirectory C:/test --sourceusername source@test.com --targetusername target@test.com

bit2win:flow:export

Export a flow into a .zip file into the system

Input parameters

-u | --targetusername: Username or alias of the target org
-f | --flowname: Unique flow name
-s | --savedirectory: Save the flow zip into the directory provided
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
zip_file: path of the zip file generated

Example

sfdx bit2win:flow:export --targetusername myuser@mydomain.com --flowname test_flow

bit2win:flow:import

Import the flow from a .zip file to the provided target org

Input parameters

-u | --targetusername: Username or alias of the target org
-f | --flowarchive: Zip file containing the flow definition
-f | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

sfdx bit2win:flow:import --targetusername myuser@mydomain.com --flowarchive c:/flow/flowdef.zip

bit2win:project

Projects commands are used to generate and manage a bit2win metadata project starting from an existing org. At this moment only metadata related to the archetypes are supported.

PLEASE BE AWARE THIS IMPLEMENTATION IS STILL IN BETA AND NOT GENERALLY AVAILABLE

bit2win:project:diff

Visualize the diff between the project and a source org.

Input parameters

-u | --username: Source username for the target org
-c | --contexts: Project context, only "archetypes" are available in this version
-l | --showlog: Set true to activate verbose mode

Ouput

Shows a table in the prompt with the list of differences

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull
diffs: differences found

Example

bit2win:project:diff -u admin@test.com

bit2win:project:generate

Generate a bit2win metadata project. The project is useful to keep an history of the status of the data into a bit2win environment and to leverage the features of a version control software (e.g. git). In this version only the archetypes are managed by the project.

Input parameters

-u | --username: Source username for the target org
-c | --contexts: Project context, only "archetypes" are available in this version
-d | --targetdir: Target directory for project generation
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

bit2win:project:generate -u admin@test.com -d C:/projects/myfirsttest/

bit2win:project:push

Push all changes to the target org, please be aware of destructive changes like delete.

Input parameters

-u | --username: Source username for the target org
-s | --synchafterfinish: Synch rules after finish, default false
-l | --showlog: Set true to activate verbose mode

Ouput

errorCode: String, "0" if the process is successfull
errorMessage: String, empty if the process is successfull

Example

bit2win:project:push -u admin@test.com

bit2win:tempo

Tempo is the main way to organize a bit2win plugin deployment. Tempo acts like a sequencer that is able to:

Call a bit2win command
Call an sfdx program. Only a partial support is provided, the goal of the plugin is not to provide a sfdx command orchestrator.
Use the response of a command as input of another one
Use variables to store reusable data
Use global variables for predefined values

tempo definition file

The "tempo definition file" (tempodef) is a JSON file containing all the information required to the plugin to work properly. The tempodef is divided into two main structures:

variables: used to store reusable data (e.g. the username of a specific org)
queue: used to define the list of commands to execute
startsFrom: used to start the queue from a specific step. Usefull for testing purpose

You can see in the following example a basic configuration:

{
	"variables":
	{
		"usernameScratch":"test@example.com",
    "usernameDev":"test@dev.com",
    "datamapfolder":"C:/Sfdx-Plugin/TempoTest/datamaps",
    "genericfolder":"C:/Sfdx-Plugin/TempoTest"
	},
  "queue":
  [
      {
          "tempoaction":"force:org:list",
          "verbose":"{!Global.empty}",
          "temponame":"testing custom"
      },
      {
          "tempoaction":"bit2win:datamap:export",
          "targetusername":"{!usernameScratch}",
          "type":"class",
          "value":"b2wgin",
          "targetfolder":"{!datamapfolder}",
          "temponame":"Exporting datamap definition"
      },
      {
          "tempoaction":"bit2win:datamap:import",
          "targetusername":"{!usernameScratch}",
          "sourcefolder":"{!datamapfolder}"
      }
  ]
}

In the folder "example" you can also find two common tempodef definition.

Tempo variables

Tempo variables can be divided into three main type:

Definition variables
Global variables
Session variables

Definition variables

Definition variables are used to store information that can be reused in more than one command in the queue. A common example is the username of a source/target org, that is usually used in all the bit2win commands. In order to define a definition variable put a new value in the "variables" object in the tempo def.

"variables":
{
  "usernameScratch":"test@example.com"
}

A variable in the used in the queue with the notiation "{!variablename}":

{
    "tempoaction":"bit2win:datamap:export",
    "targetusername":"{!usernameScratch}",
    "type":"class",
    "value":"b2wgin",
    "targetfolder":"{!datamapfolder}",
    "temponame":"Exporting datamap definition"
}

Is possible to compose the input with variable and not variable data, for example "{!folderroot}\data"

A variable can be also retrieve from the environment variables using the "{!env.varname}" notation, for example.

"variables":
{
  "itemsexternalid":"{!env.ITEMS_IDS}"
}

will retrieve the "ITEMS_IDS" environment variable to populate the tempo variable.

Global variables

Global variables are basic values that can be used inside a command. A global variable is defined with the {!Global.varname} notation. The following GlobalVars are supported:

Global.true: equal to the true boolean value
Global.false: equal to the false boolean value
Global.empty: equal to the "" value.

Session variables

Session variables are defined not from a configuration but from the ouput of a previous step. This is usefull to, for example, retrieve the name of the file generated during an export process.

The session variables are defined as {#stepId.step_outputname}

for example:

{
    "tempoaction":"bit2win:catalog:export",
    "targetusername":"{!usernameDev}",
    "catalogexternalid":"a0G1Q00000vRp37CCC",
    "ignoreerrors":false,
    "savedirectory":"{!genericfolder}",
    "tempoid":"exportcatalog"
},
{
    "tempoaction":"bit2win:catalog:import",
    "targetusername":"{!usernameDev}",
    "catalogfileurl":"{#exportcatalog.catalog_url}",
    "ignoreerrors":false,
    "delta":false
}

The "catalogfileurl" input value dependes on the "catalog_url" output of the "exportcatalog" step. In order to a session parameter to work an "tempoid" in the step must be defined.

Tempo queue

The queue is the list of commands that the tempo engine can execute. A tempo queue element is a json object describing the command to be execute and the list of parameters that can be passed.

Before the execution the plugin will validate the request by checking that: