p4 extension

Manage the Helix Core Server extensibility mechanism.

Syntax conventions

p4 extension --sample myExt

p4 extension --package myExt

p4 extension --install myExt.p4-extension [--yes]

p4 extension --delete [--revision] [--path] ExampleInc::myExt [--yes]

p4 extension --configure ExampleInc::myExt [--revision] [-o]

p4 extension --configure ExampleInc::myExt[--revision] [-i] --name ExampleInc::myExt

p4 extension --run ExampleInc::myExt [ arguments ]

p4 extension --list --type type

Description

p4 extension manages the installation, versioning, and configuration of Helix Core Server Extensions.

Extensions are a means for customizing parts of the Helix Core with user-supplied logic. Extensions are self-contained packages of third-party code and assets run within the Helix Core Server, used for change submission validation, form validation, external authentication, external job fix integration, external archive integration, and command policies. For a list of events that Extensions can register for, see the list of trigger types in the output of p4 help triggers.

The Helix Core Server runs Extensions natively, without relying on external processes, so it can provide a portable, versioned runtime with automatic replication and a programmatic API.

Extensions coexist with triggers (see p4 triggers), but Extensions offer more functionality.

Extensions are versioned within the Helix Core Server and are stored in a special depot, named .p4-extensions by default. The extension depot is only accessible to the super user and by read-only commands. The extension depot is created automatically.

Installing or upgrading an Extension creates a changelist with information about pre- and post-install versions.

An Extension can implement custom commands that a user can run. For example,

p4 extension --run myInstanceConfig validateFileSize pathToFile

where validateFileSize represents a custom command and pathToFile represents an argument that is relevant to the custom command.

About configuration

After installation, Extensions must be configured before use.

Firstly, the super user runs p4 extension --configure extName to supply various global details about the Extension's configuration, such as the list of groups whose members can create instances of the Extension, or Extension runtime limits.

Secondly, the super user uses the --configure and --name options together to create a named instance of the Extension, parameterizing the Extension to be run with specific settings. The --name option takes the name of the configuration to create or modify and the --configure option takes the name of the Extension. More than one named instance is allowed.

The p4 extension command requires super access granted by p4 protect. Users who are members of groups specified in the ExtAllowedGroups field of an Extension's global configuration and who are either a depot or repo owner can create or configure instances of file-based Extensions to operate on the sections of the server they manage.

For more information about Extensions, see p4 help serverextensionintro and Helix Core Extensions Developer Guide.

Naming rules

Extensions are referred to by their fully-qualified name. This is the combination of the namespace, name, and, optionally, the revision of the Extension that is installed on a server (as opposed to the version of the extension code). For example, a namespace of ExampleInc and a name of ExtName would be referred to as ExampleInc::ExtName

Options

--sample	Create a skeleton of a new Extension in a directory. Pass it the name of the Extension to be created. (See Naming rules.) p4 extension --sample myExt This allows you to then use the --package option.
--package	The --package option creates a packaged Extension file from the named directory of files. For example, p4 extension --package myExt The resulting file has the same name as the directory, but with the .p4-extension suffix. An Extension must be packaged before it can be installed by using the --install option.
--yes	Note To actually perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete. Tip -y is equivalent to --yes
--install	The full name of an Extension file on the client. The command installs it server-side. Packaged Extensions have the p4-extension file suffix. For example, p4 extension --install myExt.p4-extension --yes Note To actually perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.
--name	The name of the instance configuration to create or modify.
--revision	Which depot version of the Extension to configure. The default is the head revision. This option applies to the --configure option. This flag applies to the --configure option when used with or without the --name option.
--configure	An Extension is not active until it has been configured. The default global configuration is: p4 extension --configure ExampleInc::myExt and your global configuration might be: p4 extension --configure myCompany::fileSizeCheck and the corresponding instance configuration might be: p4 extension --configure myCompany::extName --name Release1.0-fileSizeCheckInst An Extension can have multiple configurations, depending on the events it registers for. Each configuration of an Extension can point to a different version of the Extension.
--list	Displays the installed extensions and their instances. To list all Extensions: p4 extension --list --type=extensions To list all instance configurations: p4 extension --list --type=configs You can replace --type=configs with --type=global or --type=instance to filter results accordingly. Adding --path=<path> filters output to instance configurations that are path-based and their path argument matches the given <path>. The output of p4 extension --list --type=extensions indicates the status of extension configuration: status Requires a global configuration status Requires instance configuration to enable the extension status Global and instance configuration enabled Note For an extension to be active, an extension must have a global configuration and at least one instance configuration.
--delete	Deletes an extension, its configurations, or both. To remove the named instance config, include the --name option: p4 extension --delete myCompany::fileSizeCheck --name=fileSizeCheck-instance --yes To remove all revisions of an extension and its configurations, omit the --name option: p4 extension --delete myCompany::fileSizeCheck To remove one specific revision and its instances, include the --revision option: p4 extension --delete myCompany::fileSizeCheck --name=fileSizeCheck-instance --revision=2 --yes To delete file-based instances registered under the specified path: p4 extension --delete ExampleInc::extD1 --path=//depot/... --yes Note To actually perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.
--run	Executes the specified Extension. An Extension can implement custom end-user commands, executed by passing the --run flag the name of an instance config and supplying any optional arguments the Extension might need.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
N/A	N/A	super, unless the Configurables - alphabetical list configurable is set to 1. Users who are members of groups specified in the ExtAllowedGroups field of an Extension's global configuration, and who are either a depot or repo owner, can create and configure instances of file-based Extensions to operate on the sections of the server they manage.