Message Submission and b2een4

Message Submission is a collection of eight HTTP endpoints that allow the creation and processing of a multi-file submission session.

  • Multiple files may be uploaded and added to an open session. When the file uploads are complete the session may be committed.
  • It is possible to add, list and delete session files prior to commitment of the session.
  • Committing a session is an instruction to the server to execute a script against the files uploaded in that session.
  • As file processing may take some time, it is possible to request the status of a committed submission for progress updates.
  • Finally the session may be closed. Closing a session optionally allows a server side script to be executed on this closing session.

Note

Because it is possible for sessions to go uncommitted or unclosed a server side process will automatically remove stale sessions and its associated files.

Endpoints

Message Submit Endpoints

b2een4 is a desktop utility that is designed to work with the Message Submission endpoints allowing a user to drop files into folders in their local file system and have them collected and processed by the server.

Downloading b2een4

Getting started with b2een4

  • Download and install b2een
  • Log your b2een client in - with your Portal username and password (After successful login, b2een will create a set of folders on your computer where you will be able to drop the files you want to submit
  • If need be, check your b2een status bar icon - you may click on “Show status” to display connection statuses and error logs
  • Drop your files directly in the “Amalto-b2een/[intstancename]” folder automatically created by b2een

Configuration and Customisation

1. Visibility

By default b2een4 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

Required User Permissions

Required for session creation, submission and status updates:

messages=edit, messages=read, messages=submit

Required to remove files from an open session or delete a session:

messages=delete

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)