p4 extension

Manage the Helix Core Server extensibility mechanism.

Syntax

p4 extension --sample extName

p4 extension --package dir

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

p4 extension --delete extFQN [ --name instName ] [ --revision=n ]
             [ --path filespec ] [--yes]

p4 extension --configure extFQN [ --revision=n ] [ -o | -i ]

p4 extension --configure extFQN [ --revision=n ] [ -o | -i 
               --name instName

p4 extension --run instName [ extArguments ]

p4 extension --list --type type

Description

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

Extensions provide a way to customize the behavior of the Helix Core Server with user-supplied logic. Extensions are self-contained packages of third-party code and assets run within the Helix Core Server. Extensions can be used for many use cases, such as 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.

Extensions coexist with triggers (see p4 triggers), but offer more functionality. The Helix Core Server runs Extensions natively, without relying on external processes, so Extensions provide a portable, versioned runtime with automatic replication and a programmatic API.

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.

Configuration and access

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.

Note

For an extension to be active, it must have a global configuration and at least one instance configuration. See the --configure option. 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.

Naming rules

Extensions are referred to by their Fully-Qualified Name (extFQN). This is the combination of the Extension's namespace, name, and optional depot file revision. For example,

a namespace of ExampleInc and name of extName would be referred to as ExampleInc::extName
with a revision of 6, the combination would be ExampleInc::extName#6

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

Note

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

Options

--sample	Creates a skeleton of a new Extension. The argument is the name of the Extension to create as well as the name of the local directory where the files are placed. The sample Extension has placeholder values that should be replaced when developing the code. (See Naming rules.)
--package	Creates a packaged Extension file from the named directory of files, preparing it for `--install` on the server. The resulting file has the same name as the directory, but with the `.p4-extension` suffix. Packaging is done client-side and requires a version 2020.1 or later command-line client.
--install	The `--install` flag is passed the full name of a packaged Extension file residing on the client and installs it server-side, where it can then be instantiated with `--configure`.
--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`	The `--configure` flag is used to supply details about an Extension's configuration. There are two parts to configuring an Extension: the global configuration the instance configuration. To create a global configuration, use `--configure` with the `FQN` of the Extension. To create an instance configuration, use the `--configure` option with the `--name` option. The `--name` option takes the name of the configuration to create or modify. More than one named instance is allowed for most event types that an Extension can be coded to work with, such as the `change-submit` event. However, the `auth-check` event allows only one named instance.
--list	Displays information about installed Extensions. The value of the `--type` flag determines which data is reported. Values for `--type` are: `extensions` `configs`, further narrowed by `global` and `instance` Adding the `--path` option filters instance configuration output to instances whose events are path-based and match the specified filespec.
--delete	Deletes an extension, its configurations, or both. To remove the named instance config, include the --name option. For example: `p4 extension --delete myCompany::fileSizeCheck --name=fileSizeCheck-instance --yes` To remove all revisions of an extension and its configurations, omit the `--name` option. For example: `p4 extension --delete myCompany::fileSizeCheck` To remove one specific revision and its instances, include the --revision option. For example: `p4 extension --delete myCompany::fileSizeCheck --name=fileSizeCheck-instance --revision=2 --yes` To delete file-based instances registered under the specified path, use the `--path` option. For example: `p4 extension --delete ExampleInc::extD1 --path=//depot/... --yes`
--run	Executes the Extension-supplied command. An Extension can implement its own end-user commands that behave similarly to native Helix Core commands in that they can have tagged output, send RPC-level messages, and open forms client-side. However, Extension-supplied commands are restricted to reporting output and cannot access client-side content. The `--run` option takes an instance configuration as its argument, and any other arguments are left to the Extension to interpret.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
N/A	N/A	`super`