Administering DM Handlers

New DM types can be registered with Perforce IPLM using custom DM Handlers. Once registered, IPs managing their data with the new DM type have the same functionality as other IPs in IPLM.

DM Handler overview

DM Handlers are integrated into Perforce IPLM through an integration script (detailed below) that links the various workspace and release management functions (IP Release, IP update IP diff, IP load, IP unload) that Perforce IPLM needs to perform when it manages IPs.

DM Handlers are managed by administrators using the Perforce IPLM CLI client or the Public API. See API documentation for more details.

As of IPLM Cache Release 1.9 DM Handler based IPs can also be used with IPLM Cache. See below for details.

DM Handler fields

When adding or editing a DM Handler in the Perforce IPLM platform, the following fields are available to configure the DM Handler. 

Field Definition
Name Name of DM (required). Consider using a namespaced DM name to avoid possible future namespace collisions.
Short_name Short name of DM
Description Description of DM
Script Full path to combined script for IP management operations. See Define Custom IP Operations below for implementation details. Not all IP operations must be used, but if a particular IP operation is not required for given DM type, that operation must be implemented to return an empty response or similar neutral response in the status field, such as "OK".
DM_property_set Name of existing property set containing properties that are passed to scripts as part of payload.
Repo_path_required True/False - indicate whether repo_path is required for this DM type. Default is False.

Command line

DM Handlers can be managed with the 'pi dmtype' command from IPLM CLI (or alternatively using the API).

pi dmtype Command 
> pi dm -h
Usage: pi dmtype [-h] SUBCOMMAND ...

Description: Commands related to DM Types. These subcommands are used to add,
edit, delete and list information about DM Types.

Optional arguments:
  -h, --help            Show this help message and exit

Available sub-commands:
  SUBCOMMAND
    add                 Create a new DM Type.
    delete (del, remove, rm)
                        Delete an existing DM Type.
    edit                Edit an existing DM Type.
    list (ls)           List all matching DM Types.

Adding a New DM Handler

New DM Handlers can be created with the 'pi dmtype add' command. This action is only available to users with administrative privileges. 

pi dmtype add Command 
> pi dm add -h
Usage: pi dmtype add [-h] [--template TEMPLATE | identifier]

Description: Create a new DM Type. The command puts the DM Type specification
into a temporary file and invokes the editor specified by the EDITOR
environment variable. Saving the file adds the DM Type.

Positional arguments:
  identifier            The name of the DM Type being created.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to add the DM Type. The
                        template is an ASCII file that defines the DM Type.
                        This can be used to add DM Types with a script and
                        avoid the interactive editor. To read the template
                        from STDIN, set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Deleting a DM Handler

Existing DM Handlers can be deleted using the 'pi dmtype delete' command. Only Perforce IPLM admins can delete a DM Handler. Note that if any IPs exist in Perforce IPLM that use the specified DM Handler type, the delete operation will fail. Those IPs must first be deleted or obliterated before the DM Handler type can be deleted. Built in DM types cannot be deleted.

pi dmtype delete Command 
> pi dm del -h
Usage: pi dmtype delete [-h] identifier

Description: Delete an existing DM Type. This command will mark a DM Type as
inactive.

Positional arguments:
  identifier  The name of the DM Type to delete.

Optional arguments:
  -h, --help  Show this help message and exit

Editing a DM Handler

Existing DM Handlers can be edited using the 'pi dmtype edit' command. This command is only available to users with administrative privilege.

pi dmtype edit Command 
> pi dm edit -h
Usage: pi dmtype edit [-h] [--template TEMPLATE] identifier

Description: Edit an existing DM Type. The command puts the DM Type
specification into a temporary file and invokes the editor specified by the
EDITOR environment variable. Saving the file edits the DM Type.

Positional arguments:
  identifier            The name of the DM Type being edited.

Optional arguments:
  --template TEMPLATE, -t TEMPLATE
                        Use the specified template to edit the DM Type. The
                        template is an ASCII file that defines the DM Type.
                        This can be used to edit DM Types with a script and
                        avoid the interactive editor. To read the template
                        from STDIN, set TEMPLATE='-'.
  -h, --help            Show this help message and exit

Listing DM Handlers

DM Handlers and built in DMs defined in the system can be listed using the 'pi dmtype list' command.

pi dmtype list Command 
> pi dm list -h
Usage: pi dmtype list [-h]
                      [--format {csv,json,long,table,template} | --verbose]
                      [--model MODEL]
                      [identifier [identifier ...]]

Description: List all matching DM Types. A variety of format and filtering
options are supported.

Positional arguments:
  identifier            Filter DM Types by name.

Optional arguments:
  --format {csv,json,long,table,template}
                        Return the results using the specified data structure.
                        The template format produces files that can be used by
                        the pi add|edit commands with the --template option.
  --model MODEL         Use the specified report model (table report only).
  --verbose, -v         Alias for --format long.
  -h, --help            Show this help message and exit

Configuring the Output Format

Perforce IPLM can display the list output in a number of different formats

Command Option Format Description
--format table The default format option, a list of values in table format.
template Lists the DM Handler in the 'pi dm edit' CLI template format. The template format returns at most one result.
long Displays detailed information about the DM Handler, equivalent to --verbose, v output
json Display the list of DM Handlers in json format. Note that the Perforce IPLM API should be used for scripting purposes.
csv Display the list of DM Handlers in comma separated value format.
--verbose, -v
Displays detailed information about the DM Handler, equivalent to --format long output
--model MODEL
Display a custom table format MODEL defined in piclient.conf. See the Client Configuration section for more details concerning the configuration of display models.

Verbose mode output example

> pi dm list gitcdm -v
DM Type GITCDM:
    Short Name                - GITDMH
    Description               - git DM Handler
    Script                    - /usr/share/mdx/products/piextras/custom_dm/gitcdm/gitcdm.sh
    Property Set              - git
    Repo-Path Required        - True
    Created on                - 2020-06-11 22:49:10 -0400 EDT by admin

Found 1 matching object(s).

Table Output

Table Output Example 
> pi dm list gitcdm
┌─────────┬────────┬───────────────┬──────────────┐
│ DM TYPE │ ABBR   │ DESCRIPTION   │ PROPERTY SET │
╞═════════╪════════╪═══════════════╪══════════════╡
│ GITCDM  │ GITCDM │ git DM Handler │ git          │
└─────────┴────────┴───────────────┴──────────────┘
Found 1 matching object(s).

Create an IP with a DM Handler type

Once a DM Handler type has been created and configured, a user can Create New IPs using a the new DM Handler type. Create an IP using existing Perforce IPLM command:

pi ip add Command 
pi ip add

Specify DM Handler Short Name in the IP's "dm_type" section. Also provide a Repo Path in the repo_path field, (if the DM Handler requires a Repo Path, as indicated in DM Handler definition).

Once the new IP is created it can be used as any other IP in Perforce IPLM. The IP will also support IP related commands, depending on operations supported by the DM Handler script.

Script implementation details

Define Custom IP Operations

The DM operations needed to integrate a new DM type are provided via a script identified in "Script" field of DM Handler type definition. The script can support IP diff, load, release, update, unload, check, and cache-supported custom operations.

IP Diff Operation

This script compares the contents of two IP Versions. This is used both when comparing between two IP Versions and when comparing the contents of a Workspace IP directory with an IP Version. In the latter case, the "right" structure below will not be provided to the script.

The returned payload is a collection of files and their respective version/status on the left and right sides, as displayed by the `pi ip diff` command. For each file, left and right can be missing (for instance, when a file was present in left but has been removed in right, that file should not have a "right" structure. Same when a new file has been added in right -- in that case, that file should not have a "left" structure).

The script is used by other Pi Client commands in the context of DM Handler operations. For example a diff is required for a release.

  • 'arguments' field: a string that includes any arguments passed to the pi ip load command via the --args argument
  • 'cache-operation' field: indicates the load is targeting the IP cache, the DM Handler script may be able to skip some steps for the operation.
  • 'ip-path' field: always holds the full path to the IPV, whether in a local workspace or in the cache
  • 'debug' field: is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • Input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: consists of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded.

Script Input Payload Format 

{
  "operation": "diff",
  "arguments": "-arguments passed -to the -diff command"  "payload_version": "1", 
  "debug": True|False,
  "ws-path": "/tmp/workspace_dir",
  "ws-resources": [
    {
      "left": {
        "ipid": {
          "library": "drinks",
          "ip": "vodka",
          "version": 1,
          "line": "TRUNK",
          "alias": "BANANA"        },
        "contents": { … Contents object as defined by the user … },
        "repo-path": "//depot/drinks/vodka/trunk", [optional]
        "ip-path": "/tmp/workspace_dir/drinks.vodka",
        "cache-operation": True|False,
        "properties": { [optional]
          "property1": value1,
          "property2": value2
        }
      },
      "right": { … Same structure as "left" … } [optional]
    },
  ]
}

Script Output Payload Format

The outer status/message fields are used to indicate an error that prevented processing the resources. If this is ERR, the resources field should be ignored.

The ws-resources should be returned in the identical order to the stdin payload order, and contain every IP.

The ws-resources status/message can be used to indicate an error when processing a particular IP. If this is ERR, then the diffs field should be ignored. This error message will be reported as a summary by the calling command.

If there’s a diff, then the diff status field will contain the details.

Status can be any of the following (case-insensitive):

  • "ADDED" - the file has been created, but not committed yet
  • "MODIFIED" - the file is modified, but not committed yet
  • "DELETED" - the file is marked for deletion, but not committed yet
  • "MISSING" - the file has been removed without notifying the DM system (rm'd)
  • "REMOVED" - the file is at a version that is considered deleted (see p4 delete + p4 submit)

The diff status field can be used in conjunction with the version field to indicate changes. For example, a version field with the accompanying "MODIFIED" status will indicate that a given file or object is at a specific version, which is different from the expected version. It is also possible to have status with no version, for example, "MODIFIED" with no version might indicate that the file or object is opened for edit.

If the version field has a value, then PI should use that when generating output (for example, for 'pi ip diff'). If there is no version specified, then the status field can be used when generating output. 

Usually, version and status will be mutually exclusive, except for "REMOVED" status.

The "MODIFIED" status field is of particular importance because it will be used by PI to proceed with a release (PI does a diff before it does a release).

Script Output Payload Format 
{
 "status": "OK" or "ERR",
 "message": [optional],
 "payload_version": "1",
 "ws-resources": [
  {
    "status": "OK" or "ERR", 
    "message": [optional],
    "diffs": { 
      <filename>: { 
       "left": { [optional] 
        "version": <left_version>, 
        "status": <left_status> 
       }, 
       "right": { … Same structure as "left" … } [optional] 
      }
   }
 ],
}

Load IP operation

The Load IP operation loads an IPV into a workspace. The script is invoked via 'pi ip load' CLI command, which passes a JSON payload to the script as defined below. When invoked, the operation responds with loading IPV data as well as a success message as defined in the format below. In case of failure, the script returns a failure message as defined by the format below.

  • 'arguments' field: a string that includes any arguments passed to the pi ip load command via the --args argument
  • 'unix-group' field: indicates the permissions that should be applied to the 'ip-path' directory when it's created. As an optimization this could be applied to the 'ip-path' directory, not the contents under that directory.
  • 'cache-operation' field:  indicates the load is targeting the IP cache, the DM Handler script may be able to skip some steps for the operation. The load behavior is different based on the setting of the 'cache-operation' field:
    1. 'cache-operation'=False: The ip-path directory is not created by PiClient, the DM Handler script is responsible for creating the IPV directory, populating it with the correct data, and setting the correct permissions
    2. 'cache-operation'=True: The ip-path directory is created by IPLM Cache, The DM Handler script is responsible for populating the already existing directory with the correct data. The DM Handler script will not create the directory or set permissions.
  • 'ip-path' field: always holds the full path to the IPV, whether in a local workspace or in the cache
  • 'umask' field: contains the umask setting that should be set on the IPV directory
  • 'debug' field: is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • Input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: consists of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded.

Script Input Payload Format

{
  "operation": "load",
  "arguments": "-arguments passed -to the -load command",
  "payload_version": "1",
  "debug": True|False,
  "ws-path": "/tmp/workspace_dir",
  "language": "en_US",
  "ws-resources": [
    {
      "ipid": {
        "library": "drinks",
        "ip": "vodka",
        "version": 1,
        "line": "TRUNK",
        "alias": "BANANA"      },
      "contents": { … Contents object as defined by the user (if available)… },
      "repo-path": "//depot/drinks/vodka/trunk", [optional]
      "ip-path": "/tmp/workspace_dir/drinks.vodka",
  "unix-group": "string", 
  "cache-operation": True|False,
  "umask": "0750",
      "properties": { [optional]
        "property1": value1,
        "property2": value2,
      }
    }
  ]
}

Script Response Message Format

The 'status'/'message' fields should contain error information when an issue arises that prevents processing the resources. If this is ERR, the 'ws-resources' field should be ignored.

The' ws-resources' items should be returned in the same order as the stdin payload was provided, and contain every IP.

The 'ws-resources' 'status'/'message' can be used to indicate an error when processing this particular IP. This error message will be reported as a summary by the calling command.

Returned 'payload_version' field is set based on the format version in use by the DM Handler script.

Script Response Message Format 
{
   "status": "OK" or "ERR",
   "message": "Message to display if error during load" [optional],
   "payload_version": "1",
   "ws-resources": [
     {
       "status": "OK" or "ERR",
       "message": [optional],
     },
  ]
}

Release IP Operation

When a DM Handler Type IP is released, Perforce IPLM calls the release operation with the payload defined below. If the script is successful, it returns the IP contents to be used in the new release. If the script fails, Pi prints an error message and the release fails. 

The standard procedure for releasing an IP is:

First to make sure that there are changes to the IPV, so the IP Diff script will be called before every IP release operation.

A user may also want to perform additional checks - for instance, a release should be rejected if there are still open files in the IPV directory.

After an IPV passes the pre-release check, the Perforce IPLM release uses that payload to perform the same actions as defined for non-DM Handlers.

  • "modified" field: value in the update payload is set to True|False according to the following criteria:
    • True: There are any files with a status field entry (as returned by the DM Handler diff function) including "ADDED", "MODIFIED", "DELETED", "MISSING" or "REMOVED"
    • False: There are no files reported with a status field entry indicating a modified but not checked in file in the IP in the workspace 
      • Note that differing checked in file versions returned by the DM Handler diff will NOT set the modified field to True.
  • 'description' field: is populated with the --description message passed to the release command
  • 'arguments' field: field is a string that includes any arguments passed to the pi release command via the --args argument
  • 'revision' field: contains the value provided to the --revision argument passed to the release command, empty if not a revision release.

  • 'ws-resources' field: The length of the ws-resources field can be used to indicate if this a hierarchical operation or not.

  • 'cache-operation' field: indicates the load is targeting the IP cache, the DM Handler script may be able to skip some steps for the operation.

  • 'ip-path' field: variable always holds the full path to the IPV, whether in a local workspace or in the cache

  • 'debug' field: variable is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: will consist of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded

Script Input Payload Format 

{
  "operation": "release",
  "arguments": "-arguments passed -to the -release command",
  "ws-path": "/tmp/workspace_dir",
  "ignore-open-files": True|False,
  "payload_version": "1",
  "debug": True|False,
  "language": "en_US",
  "ws-resources": [
  {
    "ipid": {
    "library": "drinks",
    "ip": "vodka",
    "version": 1,
    "line": "TRUNK",
    "alias": "BANANA"  },
  "description": "message provided to the release command",
  "revision": "revision string" [optional, if empty indicates not a revision release]
  "contents": { … Contents object as defined by the user (if available)… },
  "repo-path": "//depot/drinks/vodka/trunk", [optional]
  "cache-operation": True|False,
  "ip-path": "/tmp/workspace_dir/drinks.vodka",
  "modified": True|False,
  "properties": { [optional]
    "property1": value1,
    "property2": value2,
   }
  },
 ]
}

Script Output Payload Format

A release is an atomic action, it either works for all resources, or none are released. The stdin ws-resources list length can be used to indicate if this is supported by the particular DM Handler implementation or not.

The status/message fields are used for when there’s an error that prevented releasing the resources. If this is ERR, the ws-resources field should be ignored.

The ws-resources should be returned in the same order as they came in in the stdin payload, and contain every IP.

If there were no new contents to release, the contents will contain the same information as the input payload

Script Output Payload Format 
{
  "status": "OK" or "ERR",
  "message": [optional],
  "payload_version": "1",
  "ws-resources": [
    "contents" { content object as defined by customer } [required if successful operation]
  ]
}

Update Workspace operation

The script performs an operation by updating an IP as defined for the given DM. The script is invoked via 'pi update' CLI command, which passes a JSON payload to the script as defined below.

When invoked, the script responds with loading the IPV data as well as a success message as defined in the format below. In case of failure, the script returns a failure message as defined by the format below.

  • "modified" field: value in the update payload is set to True|False according to the following criteria:
    • True: There are any files with a status field entry (as returned by the DM Handler diff function) including "ADDED", "MODIFIED", "DELETED", "MISSING" or "REMOVED"
    • False: There are no files reported with a status field entry indicating a modified but not checked in file in the IP in the workspace 
      • Note that differing checked in file versions returned by the DM Handler diff will NOT set the modified field to True.
  • 'arguments' field: a string that includes any arguments passed to the pi ip load command via the --args argument
  • 'unix-group' field: indicates the directory ownership of the 'ip-path' directory. If this has changed, it will need to updated on the filesystem. As an optimization this could be applied to this directory only, not the contents.
  • 'cache-operation' field: indicates the update is targeting the IP cache, the DM Handler script may be able to skip some steps for the operation.
  • 'ip-path' field: always holds the full path to the IPV, whether in a local workspace or in the cache
  • 'umask' field: contains the umask setting that should be set on the IPV directory
  • 'debug' field: is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • Input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: consists of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded.

Script Input Payload Format

{
  "operation": "update",
  "arguments": "-arguments passed -to the -update command"  "update_mode": "PROMOTE" | "KEEP_LOCAL" | "FORCE",
  "payload_version": "1",
  "debug": True|False,
  "language": "en_US",  
  "ws-path": "/tmp/workspace_dir",
  "ws-resources": [
    {
      "ipid": {
      "library": "drinks",
      "ip": "vodka",
      "version": 1,
      "line": "TRUNK",
      "alias": "BANANA"    },
    "contents": { … Contents object as defined by the user (if available)… },
    "original_ipid": { … Same as ipid … },
    "original_contents": { … Same as contents …},
    "repo-path": "//depot/drinks/vodka/trunk", [optional]
    "ip-path": "/tmp/workspace_dir/drinks.vodka",
    "unix-group": "string", 
    "umask": "0750",
    "modified": True|False,
    "cache-operation": True|False,
    "properties": { [optional]
        "property1": value1,
        "property2": value2
   }
  },
 ]
}

Script Response Message Format

The 'status'/'message' fields should contain error information when an issue arises that prevents processing the resources. If this is ERR, the 'ws-resources' field should be ignored.

The' ws-resources' items should be returned in the same order as the stdin payload was provided, and contain every IP.

The 'ws-resources' 'status'/'message' can be used to indicate an error when processing this particular IP. This error message will be reported as a summary by the calling command.

Script Response Message Format 
{
  "status": "OK" or "ERR",
  "message": "Message to display if error during update",
  "payload_version": "1",
  "ws-resources": [
    {
      "status": "OK" or "ERR",
      "message": [optional],
    }
}

Remove IP from Workspace operation (Unload)

The script performs an operation for removing IP directories and files from a workspace. The script is invoked via Update operation, which passes a JSON payload to the script as defined below

When invoked, the script responds with deleting the IP data as well as a success message as defined in the format below. In case of failure, the script returns a failure message as defined by the format below.

The unload operation will always be called regardless of the results of the preliminary call to the DM Handler diff function.

  • "modified" field: value in the update payload is set to True|False according to the following criteria:
    • True: There are any files with a status field entry (as returned by the DM Handler diff function) including "ADDED", "MODIFIED", "DELETED", "MISSING" or "REMOVED"
    • False: There are no files reported with a status field entry indicating a modified but not checked in file in the IP in the workspace 
      • Note that differing checked in file versions returned by the DM Handler diff will NOT set the modified field to True.
  • 'arguments' field: a string that includes any arguments passed to the pi ip load command via the --args argument
  • 'cache-operation' field: indicates the unload is targeting the IP cache, the DM Handler script may be able to skip some steps for the operation.
  • 'ip-path' field: always holds the full path to the IPV, whether in a local workspace or in the cache
  • 'debug' field: is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • Input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: consists of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded.

Script Input Payload Format

Script Input Payload Format 
{
  "operation": "unload"  "arguments": "-arguments passed -to the -update command",
  "payload_version": "1",
  "debug": True|False,
  "ws-path": "/tmp/workspace_dir",
  "language": "en_US",
  "ws-resources": [
    {
      "ipid": {
      "library": "drinks",
      "ip": "vodka",
      "version": 1,
      "line": "TRUNK",
      "alias": "BANANA"    },
    "contents": { … Contents object as defined by the user (if available)… },
    "repo-path": "//depot/drinks/vodka/trunk", [optional]
    "ip-path": "/tmp/workspace_dir/drinks.vodka",
    "modified": True|False,
    "cache-operation": True|False,
    "properties": { [optional]
      "property1": value1,
      "property2": value2,
    }
   },
  ]
}

Script Response Message Format

The 'status'/'message' fields should contain error information when an issue arises that prevents processing the resources. If this is ERR, the 'ws-resources' field should be ignored.

The' ws-resources' items should be returned in the same order as the stdin payload was provided, and contain every IP.

The 'ws-resources' 'status'/'message' can be used to indicate an error when processing this particular IP. This error message will be reported as a summary by the calling command.


Script Response Message Format 
{
  "status": "OK" or "ERR",
  "message": "Message to display if error during update" [optional],
  "payload_version": "1",
  "ws-resources": [
  {
    "status": "OK" or "ERR",
    "message": [optional],
  }
}

IPLM Cache Check Operation 

The IPLM Cache server performs Check operations on IPVs loaded in the cache. This function performs that check for a given DM Handler.

The precise checks to be implemented will vary based on the underlying DM system, examples of what is checked for the Perforce P4 Core DM are:

  1. Contents check - are the expected files in the IPV?
    1. Are p4 have, find, and the IPV filelist consistent?
  2. Ownership and permissions check
  3. Does the .p4config file exist?
  4. Does the Perforce client exist and is it correct?
  5. Are there any open files associated with the p4 client?

DM Handlers check operations will vary based on the DM but should replicate the appropriate requirements from the Perforce Helix requirements, as well as adding any additional checks specific to the DM.

When a DM Handler Type IP subject to a IPLM Cache check, IPLM Cache calls the DM Handler script with the payload defined below. If the script is successful, it returns the script output payload with status "OK". If the script fails, the output payload should have status "ERR", and a message describing the problems that exist with the cached IP.

  • 'ip-path' field: always holds the full path to the IPV, whether in a local workspace or in the cache
  • 'umask' field: variable contains the umask setting that should be checked versus the setting on the IPV directory
  • 'debug' field: is set based on the presence or absence of the '--debug/-d' flag provided to PiClient
  • Input 'payload_version' field: is set based on the format version of the input payload in use by IPLM. The returned 'payload_version' field is set based on the format version in use by the DM Handler script.
  • 'language' field: consists of a country code. The DM Handler can provide messaging in the requested language if supported. Script payloads are UTF-8 encoded.

Script Input Payload Format

{
  "operation": "check",
  "payload_version": "1",
  "debug": True|False,
  "language": "en_US",
  "ws-resources": [
    {
      "ipid": {
      "library": "drinks",
      "ip": "vodka",
      "version": 1,
      "line": "TRUNK",
      "alias": "BANANA"    },
    "contents": { … Contents object as defined by the user (if available)… },
    "repo-path": "//depot/drinks/vodka/trunk", [optional]
    "ip-path": "/tmp/workspace_dir/drinks.vodka",
    "unix-group": "string", 
    "umask": "0750",
    "uuid": "7332f652-ad39-4e3c-bbad-2ee14ab5c287",
    "properties": { [optional]
      "property1": value1,
      "property2": value2,
    }
   },
  ]
}

Script Response Message Format

The 'status'/'message' fields should contain error information when an issue arises that prevents processing the resources. If this is ERR, the 'ws-resources' field should be ignored.

The' ws-resources' items should be returned in the same order as the stdin payload was provided, and contain every IP.

The 'ws-resources' 'status'/'message' can be used to indicate an error when processing this particular IP. This error message will be reported as a summary by the calling command.

Script Response Message Format 
{
  "status": "OK" or "ERR",
  "message": "Message to display if error during update" [optional],
  "payload_version": "1",
  "ws-resources": [
  {
    "status": "OK" or "ERR",
    "message": [optional],
  }
}

Sample DM Handler Script

#!/usr/bin/env python

import json
import os
import shutil
import sys
import subprocess

from methodics.tools.custom_dm import DMHandler


class SVNX(DMHandler):

    def load(self):
        repo_path = os.path.expandvars(self.payload['repo-path'])
        ip_path = self.payload['ip-path']
        cmd = ['svn', 'checkout', repo_path, ip_path]

        contents = self.payload.get('contents')
        if contents:
            cmd.extend(['-r', str(contents.get('revision'))])

        subprocess.check_output(cmd)
        return self.success()

    def diff(self):
        # TODO - need a real diff
        # TODO - extract left [and right] from payload
        diffs = {'some.file': {'left': {'version': 1}}}
        return self.success(diffs=diffs)

    def release(self):
        ip_path = self.payload['ip-path']
        repo_path = os.path.expandvars(self.payload['repo-path'])
        # TODO - verify the repo path
        os.chdir(ip_path)
        # TODO - useful error message on mixed revisions
        svn_rev = int(subprocess.check_output('svnversion'))

        contents = {'revision': svn_rev}

        return self.success(contents=contents)

    def update(self):
        cmd = ['svn', 'update']

        contents = self.payload.get('contents')
        if contents:
            cmd.extend(['--revision', str(contents.get('revision'))])

        os.chdir(self.payload['ip-path'])
        subprocess.check_output(cmd)
        return self.success()

    def unload(self):
        shutil.rmtree(self.payload['ip-path'])
        return self.success()


# exec from here
if __name__ == '__main__':
    sys.exit(SVNX().process())