Executing a Project Using the Command Line – Precision Bridge

Introduction

As discussed in this article, you can use the PrecisionBridge_cmd.exe application to perform command line operations. You will need to provide as a minimum, the location of the project to be run. A full list of parameters that can be used is given at the end of this article.

Parameters

The -p parameter is mandatory, this defines the location of the project folder that is to be run. All other parameters are optional. Therefore at its most simple, a project can be executed with the following command:

PrecisionBridgeCmd.exe "-p=<path to project>"

<path to project> must be either an absolute path to the project's root folder, or a relative path to the project folder from the current folder (which will be the folder containing PrecisionBridge.exe)

Note that there must be no whitespace either side of the = character and that if the path contains spaces, the parameter must be enclosed in double quotes.

For example:

PrecisionBridgeCmd.exe "-p=C:\Users\Admin\Documents\Precision Bridge Projects\Projects\Attachment Testing\A2S Attachments"

Server Authentication for Command Line Execution

It should be noted that for command line execution, the authentication details for source and target server need to be saved within the project folder. These are saved in the files source.dat and target.dat. The password component of authentication is encrypted in the file. To ensure the authentication details are saved in this way, open the project using the Precision Bridge Client, enter the authentication details for both source and target and check the Save Authentication options. When the project is opened, the two authentication files are created.

Available Parameters

Note that:

Most parameters have both a long and short name. For example, -p and -project both define the project path.
All parameter identifiers are case insensitive
No whitespace should be included between the parameter identifier and the = or between the = and the value.
Many parameters override execution settings in the project.
If an unrecognised parameter is defined, the execution will fail with an error.
Any parameter/value pairs that include spaces should be enclosed in double quotes.
Any embedded backslash or double quote characters in parameter values should be escaped with a preceding backslash

Below is a list of all available parameters for Command Line Execution:

Parameter

Notes

-project=<path>

-p=<path>

This MANDATORY parameter specifies the root folder of the project that is to be run. <path> can be either an absolute path, or a path relative to the executable (PrecisionBridgeCmd.exe).

-help

-h

This parameter writes to output a short description of all valid parameters that can be used.

All other parameters will be ignored if this is found and execution will terminate after help has been output

-out=<path>{:overwrite}

-o=<path>{:overwrite}

This parameter redirects output from the program to the file given by <path>.

The file will be created if it does not exist, however its parent folder must already exist.

The optional :overwrite suffix can be used to force executions performed to overwrite any existing log file.

-executeNow

-e

Instructs the program to run the execution immediately after the project has been loaded and execution initialised.

This will override any scheduling defined in the execution settings for the project.

The -st parameter must not also be included in the arguments.

-scheduleTime=<time>

-st=<time>

Instructs the program to delay execution until the defined time.

This time must be in the format HH:mm:ss and will be interpreted as being in the same time zone as the target server.

The -e parameter must not also be included.

This will override any value defined in the execution settings

-scheduleDate=<date>

-sd=<date>

Instructs the program to delay execution until the defined date.

The date must have the format yyyy-MM-dd.

The parameter is only valid if an -st value has been defined as well.

This will override any value defined in the execution settings.

-scheduleRepeatPeriod=<value>

-srp=<value>

Instructs the program to repeat execution at the period given by<value>.

The value must be one of the following:

· monthly

· weekly

· daily

· 12h

· 6h

· 4h

· 2h

· h

· 30m

· 15m

· 10m

· 5m

· None

This will override any value defined in the execution settings.

-scheduleEnd=<datetime>

-se=<datetime>

This sets a timestamp after which executions should not be started.

The format of <datetime> must be yyyy-MM-ddTHH:mm:ss.

The time will be interpreted as being in the timezone of the target server.

This will override any value defined in the execution settings.

-notificationEmail=<email>

-ne=<email>

On completion of an execution, or on any failure, a notification will be sent to the email address given by <email>.

This will override any value defined in the execution settings.

Note that this functionality depends on notification emails having been configured using the Precision Bridge Client.

-logFile=<path>

-lf=<path>

Log output from the execution will be directed to this file instead of the default location.

This will override any value defined in the execution settings.

If the log file does not exist, it will be created, but the parent folder must already exist.

-logLevel=<value>

-li=<value>

The level of logging performed will be set to this value.

The value must be one of:

· detail

· info

· warning

· error

· none

This will override any value defined in the execution settings.

-variable=<varName>:<value>

-v=<varName>:<value>

This allows Project Variables defined in the project to be given values for execution.

The varName must match a variable defined in the project.

Multiple -v arguments can be added if there are multiple variables in the project.

The values given here will override any values defined in the execution settings.

Examples

PrecisionBridgeCmd.exe "-p=D:\MyProject" -e -out="D:\MyProject\execOutput.txt:overwrite"

The above command will load and run the project MyProject. The project will be executed immediately after loading (-e) All output from the process will be written to execOutput.txt, overwriting any existing file.

PrecisionBridgeCmd.exe "-p=D:\MyProject" -st=02:00:00 -ne=user@server.com

The above command will load project MyProject. It will then wait until the scheduled time of 02:00:00 is reached before executing. The time will be assumed to be in the timezone that the target server uses. For most servers this is UTC, however for Service Now, it is the timezone for the user that is used to connect to Service Now. On completion of the execution, or on failure, a notification will be sent to the email address user.server.com.

PrecisionBridgeCmd.exe "-p=D:\MyProject" -e -srp=h "-se=2021-06-01-01 00:00:00"

The above command will load project MyProject. The schedule end date/time (-se) will then be checked to see if it has passed already. If it has not, execution will be performed immediately (-e). Once execution has completed, a further execution will be scheduled to occur one hour after the first one started (-srp). The execution will be run again at this time. This will continue until an execution would be scheduled after the schedule end date/time, when the process will terminate.

Return Values

On completion of the execution, Precision Bridge will analyse the counts and set the return value as follows:

Errors reported – return 2
Warnings Reported (but no errors) – return 1
No warnings or errors reported – return 0
Fatal Exception – return -1

Related articles