Skip to content

Intro to P6 Cmd

P6 Cmd (p6cmd) is a small utility that is designed for the Platform 6 users. It can be installed on-premise by Platform 6 customers and allows the submission of file(s) to their instances using on-site scripts or ‘file drop’ folder monitoring.

Message Submission Definition

Message Submission is a process of sending one or more files to a Platform 6 instance and triggering a script to process those files. Success or failure results are returned to the message submitter as submission acknowledgement

Message Submission without a user interface (or Portal) is regarded as a more efficient method of regularly transferring files from on-premise folders to a Platform 6 instance for processing and is much easier to automate and integrate into existing on-premise batch processing activities

Platform 6 Message Submission is by its nature flexible and configurable allowing it to fit many project requirements. For example, it has successfully been deployed to a large international supplier community allowing the bulk and regular submission of invoices

The latest release of P6 Cmd can be downloaded from here:

Warning

SSO authentication is not available for this application. If you haven’t already, you are required to define a password by editing your profile here

P6 Cmd icon

The ‘6’ icon in the notification area of your Task bar (on Windows) or in your Menu bar (on Mac) provides quick access links

  • “Login…” leads to a login page where you shall initially enter your platform6 credentials

  • “Show status” leads to a page displaying four areas:

    1. Status - provides statuses regarding Internet connectivity and login
    2. Login - leads you to the login page (it is greyed when already logged in)
    3. Log Files - allows you to display P6 Sync log and error logs
    4. Quit - well… speaks for itself!

  • “Open P6 Portal…” leads you to the Portal

  • “Logout” removes stored credentials and forces a new user login
  • “Quit P6 Cmd”

Note

The task bar icon is only visible when p6cmd is started in ‘interactive mode’. i.e. Is being used via the browser interface

The browser interface

The browser interface is started automatically after first installation. Once a user has logged in (to access their P6 instances), it is no longer required that P6 Cmd should continue running in this mode. Feel free to quit the browser UI once login is complete.

Folder usage

During execution, P6 Cmd may automatically create a folder structure on your computer, with a parent folder named “platform6”

On Windows, the “platform6” folder is created on C: in the root (“/”) folder

On OS X, the “platform6” folder is under your user folder (so the path is “/Users/[Your OS X user]/platform6”)

When using p6cmd for file submission, three folders are added beneath a folder named according to each target instance. For example, when targeting an instance with a name of dev:

$ls -al $HOME/platform6/dev
total 16
drwxr-xr-x  6 simontemple  staff   192 23 Feb 11:40 .
drwxr-xr-x  6 simontemple  staff   192 21 Feb 18:24 ..
drwxr-xr-x  5 simontemple  staff   160 23 Feb 11:38 error
drwxr-xr-x  2 simontemple  staff    64 23 Feb 11:40 outbound
drwxr-xr-x  2 simontemple  staff    64 15 Feb 10:17 sent

Folder Usage

  • a file that is selected for submission is moved into the outbound folder until the submission is complete
  • files that are accepted by the instance are moved to the sent folder once the submission is complete
  • files that are rejected by the instance are moved to the error folder is the submission fails. A file called error.log is also created in this folder that contains details of why the submission failed

User Permissions

A developer user must have permission messages=* to perform foldermonitor or submit operations

Using the Command Line Interface (CLI)

Once you have logged in, the CLI can be used to interact with your P6 instance(s).

The CLI is designed for use from batch files or shell script, executed by schedulers or run as a service on Windows

To enable CLI access, the p6cmd install folder must be on your PATH.

Warning

On macOS you have to manually add the following you your .bashrc/.profile file: 

export PATH="/Applications/P6 Cmd.app/Contents/MacOS:$PATH"

On Windows the user who installs P6 Cmd will automatically have p6cmd added to their PATH. Other users of Windows must extend their on PATH as follows

PATH="C:\Program Files (x86)\Platform6\p6cmd;%PATH%"

Once on the PATH you can invoke the CLI to get help:

$ p6cmd -help 

Usage of p6cmd:
  -console
        Enable console logging
  -debug
        Enable debug level logging
  -env string
        Infrastructure environment name (dev, staging or prod) (default "prod")
  -headless
        Running without a desktop UI
  -home string
        Location of root folder (default "/Users/simontemple/platform6")
  -ignoretlserrors
        Ignore TLS/SSL related errors
  -instance value
        [Optional and can repeat] Instance names to target
  -monitorfolders
        Enable folder monitoring for each targeted instance that supports message submission
  -p6noproxy
        Bypass the Platform6 Proxy
  -p6proxyoverride string
        Platform6 Proxy override
  -port string
        Web server localhost listen port, 0 = auto assigned (default "0")
  -sparam value
        [Optional and can repeat] Submission session parameter(s)
  -submit string
        File path or pattern of file(s) to send to each targeted instance that supports message submission
  -version
        Print version information

Configuring defaults

The browser UI provides access to a ‘configuration’ screen where a user can configure a number of defaults to save having to re-type them each time on the command line.

Configuration and Customisation for Message Submission

1. Visibility

By default, p6cmd will not consider a P6 Instance as a message submission capable instance unless the following configuration property is set:

p6.messagesubmit.exclude = false

Note

The message submission endpoints are always available on an instance but not advertised via the /info endpoint response as default, instead they are advertised with an id of filesubmit

2. Stale session detection

The following configuration property can be set to override the default value of: 1200000 milli seconds (20 mins)

p6.default.messageSubmit.timeout

3. Default Script Name To Execute

The following configuration property can be used to override the default value of: MessageSubmission

p6.default.messageSubmit.script

4. Response result for unprocessed files

The following configuration property can be used to override the default of: WARNING

p6.default.messageSubmit.unprocessedResult

It must be one of: OK, WARNING, ERROR

5. Attributes Set On The /new Endpoint

  • script_name The name of the script to execute when a session is committed or closed
  • [any] All other attributes will be forwarded to the MessageSubmission script as pipeline variables

MessageSubmission Script

This script will be executed when a submission session is committed or closed (when cancel = false)

The following pipeline variables will be made available to the MessageSubmission script:

  • attribute.[key]=[value] (attribute key/value pairs given when the session was created via the /new endpoint)
  • entity.[n].attribute.[key]=[value] (attribute key/value pairs given when a file entity was added to the session)
  • entity.[n].name (name of file entity)
  • entity.[n].size (size of file entity))
  • entity.[n].uri (uri of server storage location of entity)
  • platform6.request.user.permissions (permissions string of user invoking the endpoints)
  • platform6.request.user (username of user invoking the endpoints)

The following pipeline variables are expected as a response and are mapped to the session status response:

  • _entity_[entity name]_id_[n]_ (Id(s) generated by processing the entity)
  • _entity_[entity name]_message_ (Per entity processing message)
  • _entity_[entity name]_result_ (Per entity result: One of OK, WARNING, ERROR)
  • platform6.response.status (Overall session processing result: true|false)
  • platform6.response.value (Overall session processing result message)

Examples CLI Invocations

  1. File drop folder monitoring 
    $p6cmd -monitorfolders
Logging to: /Users/simontemple/.config/p6cmd/p6cmd.log
    - p6cmd will create a monitor folder for each instance the current user is associated with (and supports message submission) All files copied or dropped into the folder will be submitted to the associated instance. - The contents of the p6cmd.log in this case will look like this: 
Version: 1.0.0, Build: 2022-02-23_03:57:34PM (d9ce0e2), Platform: darwin:amd64, Using: go1.17.6 (dev) on 8 CPUs. TimeZone: GMT (0)

INFO: 2022/02/23 15:59:09 restclient.go:189: Port assigned by OS: 56765
INFO: 2022/02/23 15:59:09 restclient.go:226: No http proxy enabled.
INFO: 2022/02/23 15:59:10 restclient.go:531: Created file monitor(s): 1
INFO: 2022/02/23 15:59:10 filestore.go:53: Ensuring file store structure...
INFO: 2022/02/23 15:59:11 filestore.go:97: File store structure ready: /Users/simontemple/platform6/dev
INFO: 2022/02/23 15:59:11 foldermonitor.go:211: Starting folder monitor...

Note

Folder monitoring once started will not end until the process is stopped via a SIGINT signal; via the command shell or process manager

  1. Submit a group of files to a single instance and exit 
    $p6cmd -instance dev -submit "/Users/simontemple/Downloads/*.csv"
Logging to: /Users/simontemple/.config/p6cmd/p6cmd.log
$ echo $?
2
  • p6cmd will move the file(s) matching the pattern ~/Downloads/*.csv to the instance folder dev (creating it if does not already exist) and then attempts to submit the files
  • The exit code of 2 indicates that the submission failed (0 = sent without error). Examination of the error.log file in the error folder shows Submission script not found: MessageSubmission
  • MessageSubmission is the name of the script run on the instance as default. For this project the script has been called CSVSubmission so the p6cmd should be:
$p6cmd -instance dev -submit "/Users/simontemple/Downloads/*.csv" -sparam _script_name_=CSVSubmission -sparam foo=bar
Logging to: /Users/simontemple/.config/p6cmd/p6cmd.log
$ echo $?
0

Note

Multiple -sparam arguments are allowed. Each key/value pair are passed as pipeline variables to the submission script. Here, the reserved key of _script_name_ is being used to specify the name of the script to process this submission