Ivercy

Custom Commands in Ivercy

With Ivercy 1.3.14 we introduced the new Custom Commands feature. Custom Commands are external commands that you define.

Technically a Custom Command is a command line, you can execute on your computer, completely unrelated to Ivercy. Ivercy itself does almost nothing there.

…nothing, except two details.

  1. Ivercy integrates a custom menu into its Ribbon to run the command. - This is convenient, but you could also create your own add-in to do the same with moderate effort.
  2. It provides a set of variables you can insert into your custom command line. These variables are, of course, related to your Access project under version control and enables you to make external version control related commands available right inside your Access development environment.

Some examples of commands I can think of:

  • Show the Blame (Annotate in TFS) for one particular object in your project. – The Blame or Annotation shows when each line in a file was last edited and by whom. (This command is probably the main reason we implemented Custom Commands.)
  • Apply a Label (Tag) to the repository folder directly from the development environment.
  • Start a build of the project using an automated build script.

Custom Command Properties

New Custom Commands can be defined in the Ivercy Options Dialog, in the Global Options section. Due to being defined globally each command will be available in all Access projects you manage with Ivercy.

Here is the list of properties for Custom Commands.

  • Command – The command line to be executed. Usually the path to an executable (.exe) file. Can also be a path to a file that should be opened with the standard application for that file type. - Mandatory.
  • CommandArguments – All arguments that should be passed to the exe specified in the command line (Command). – Optional.
  • Id – Unique id for this command. A default value will be autogenerated by Ivercy. – Mandatory.
  • Name – Name of the command. The name will be used in the menu item for the command.
  • RibbonItemImageMso – The idMso / imageMso for a predefined icon/image in Microsoft Office. - Optional. (Reference: Icon gallery with the imageMso in Access/Office 2010)

Custom Command Variable Syntax

Variables can be embedded anywhere inside a command line string (Command) or in the command line arguments (CommandArguments).

Each variable for a Custom Command must be enclosed in curly brackets.

Variable names consist of the $ sign, a section name, a dot, followed by the specific variable name.

Example: {$Repository.User}      -- User name for the source code control repository

Some variables can end with a numeric index to reference one of multiple elements.

Example: {$SccAuxPath. Item2}  -- Second item from the AuxPath

Custom Command Variable List

Here is a list of all currently supported variables for custom commands.

Variable Section / Name

Explanation

Repository

Data related to the (remote) source code control repository.

$Repository.Path

The full repository path to your project.

The exact format of the path is not defined. It should be in a format that you source code control system understands.

$Repository.Path.ItemX

The repository path is usually separated by forward slashes (/ ). ItemX refers to an item in that path where the X is the 1-based index of that item.

E.g. {$Repository.Path.Item2} will return the repository name for TFS/Azure DevOps.

$Repository.User

The username you connected to the repository with.

Note: The repository password is usually handled and protected by the SCC-Client and Ivercy never has any access to it.

               

 

SccAuxPath

The AuxPath (aka. AuxProjPath) is proprietary data to help your source code control system connect to its repository.

This usually contains the base URL of the source code control server.

You can open the Ivercy_Config.xml file for your project to see the AuxPath used there by your SCC-System.

$SccAuxPath.ItemX

With many SCC-Systems (e.g. VSS, TFS, Vault) the AuxPath is separated by pipes (|) into multiple items. ItemX refers to an item in that path where the X is the 1-based index of that item.

$SccAuxPath.ItemX:Y

Hack for Sourcegear Vault. Vault separates some items into sub items by using the colon (:).

Y refers to the sub item of an AuxPath item.

E.g. {$SccAuxPath.Item2:2} will return the numeric repository id for Vault.

 

 

SccLocal

Information local copy of your source code control project

$SccLocal.Path

Base project path. This is the path containing your Access file.

$SccLocal.WorkingDir

The sub directory of the project directory containing all the temporary and miscellaneous data used by Ivercy internally. (_IvercyTmp)

 

 

SelectedObject

The Access object currently selected in the Access Navigation Pane.

If multiple objects are selected, this will be one random object from the selection.

$SelectedObject.FileName

The file name of the object when exported to the working folder.

$SelectedObject.Name

The name of the object.

$SelectedObject.TypeName

The name of the objects type (e.g. Form, Report, …) always in English regardless of the language of your Office or Windows installation.

$SelectedObject.ObjectType

The numeric object type. Identical with AcObjectType for most object types. Maybe different for Tables (=Data&Misc-Objects) and object types not supported by Ivercy (e.g. Views and Diagrams in ADPs).

$SelectedObject.SccStatus

The numeric source code control status of the object. Unsupported – May be subject to change without notice.

               

 

CurrentObject

The current object according to Access (=Application.CurrentObjectName). If an object is open and activated in design view it will be the current object.

We recommend to not rely on CurrentObject in any other situation.

$CurrentObject.FileName

The file name of the object when exported to the working folder.

$CurrentObject.Name

The name of the object.

$CurrentObject.TypeName

The name of the objects type (e.g. Form, Report, …) always in English regardless of the language of your Office or Windows installation.

$CurrentObject.ObjectType

The numeric object type. Identical with AcObjectType for most object types. Maybe different for Tables (=Data&Misc-Objects) and object types not supported by Ivercy (e.g. Views and Diagrams in ADPs).

$CurrentObject.SccStatus

The numeric source code control status of the object. Unsupported – May be subject to change without notice.

 

 

AccessProject

Information about the Access project

$AccessProject.FileName

The file name of the access project

$AccessProject.Name

The name of the access project. = File name without the extension.

$AccessProject.FullPath

The full path to the database project.

               

 

Input

Variables in the Input section can be used to retrieve user input with an input box.

 

There are no predefined variables in this section. They will be defined by you putting them into the command line.

 

Entering a value for any defined user input variable is mandatory. If you do not enter anything and press OK it will cancel the command execution.

 

If you use the same name for an Input-Variable multiple times within one command (command line and arguments) you will be prompted only once, and the entered value will be used for each occurrence of that Input-Variable in the whole Custom Command.

$Input.YouNameIt

This will show an input box asking you to enter the value for YouNameIt.

 

 

 

Environment

The Environment section will try to retrieve the variable value from the windows environment variables.

 

E.g. {$Environment.Computername} will retrieve the local computer name from the Windows process environment.

$Environment.AnyVariable

Will try to retrieve the variable “AnyVariable” from the execution environment of the current process (Microsoft Access).

 

If you need additional variables for a custom command, please let us know.

Custom Command Line Examples

The Custom Command variables in the following examples are bolded for emphasis.

Sourcegear Vault - Blame

This command line for Sourcegear Vault will show the Blame for the selected Access object in the default web browser:

https://your.vaultserver.com/VaultService/VaultWeb/Blame.aspx?repid={$SccAuxPath.Item2:2}&path={$Repository.Path}/{$SelectedObject.FileName}&version=-1&includedversions=20

Azure DevOps – Annotate

This command line for Azure DevOps will show the Annotate view for the selected Access object in the default web browser:

Command: https://dev.azure.com/youraccount/{$Repository.Path.Item2}/_versionControl?path={$Repository.Path}/{$SelectedObject.FileName}&_a=annotate

Change Directory and Run Batch Script

This command line combine with the following arguments will run cmd.exe, change the current directory to the ..\Build directory relative to the directory of the project and then execute the bat-script startBuild in that directory with the repository user and password (requested as input from the user) as arguments.

Warning: If you pass arguments to cmd.exe in this way they will be shown in the title bar of the cmd window. Not ideal for a password! It would be more secure to prompt for the password from the script and hide the input during entry. But this is beyond the scope of this text.

Note: Our existing build scripts do a lot of operations with paths relative to the execution directory. That is the requirement for combining the directory change command with the script execution.

Command:

{$Environment.ComSpec}

CommandArguments:

/K cd /D "{$SccLocal.Path}\..\Build" && startBuild.bat {$Repository.User} "{$Input.EnterRepositoryPassword}"

Your examples?

If you used Ivercy Custom Commands for innovative or unusual purposes, please let us know. We are interested to see what you use this feature for!