Contact Us!
303|905-4110

bpi.form.admin was introduced to BP Forms at release 3.8.  It provides a service subroutine called bpi.form.admin.sub() and a command-line interface.  The utility is intended to allow programmers to administer the Blue Prairie Forms phantoms more easily by allowing them to script and programmatically control the management of the Blue Prairie Forms phantoms.

Command Line Interface

bpi.form.admin phantomName|* {switches}
Element Value Type Description
bpi.form.admin   command This is the program name
phantomName|*   param The name of the phantom you wish to administer.  The Phantom name is the unique value assigned to the phantom thread.  This is defined in the BPI.PHANTOM.CONTROL file and is the value defined by the 'key' parameter (e.g., key=bpiform1).  7/31/2024: Update, * is now supported for all admin actions.
{switches}     Switches are used to declare the action to be performed or to modify the output of the action.
  -status action will display the status of the targeted phantomName(s)
  -start action will start the targeted phantomName.  After starting the phantom, you can verify its status using the -status action.
  -kill action will kill the targeted phantom.  Note, this only passes a request to the phantom that it should kill itself.  It does not actually issue a unix kill command.  If you need to perform a harsh kill such as a kill -15 or kill -9, then you will need to retrieve the pid of the target phantom using the -status action then issue the kill directive yourself.  There is no unix-level kill directive available in the api at this time.  If your program needs to verify that the kill was successful, you will need to call the -status action and confirm that the pid for the target phantomName is blank as your indication.  Depending on the sleep cycle of the phantom and the business of the phantom, it could take time before the phantom observes the kill action request and kills itself. Write your verification code accordingly.
  -ping action will return a message indicating the successful (or failed) attempted to ping the Open Office server associated with the targeted phantomName.
  -ssh action will ssh you to the open office server as the user associated with the target phantomName.
  -h action display help page and exit
       
  -verbose{n} modifier Specifies the level of verbosity that will be used during execution.  Default is 0
  -pretty modifier Display output will be in 'pretty' human readable format (this is the default)
  -raw modifier Output from the command will be in the form of a multiValue array suitable for easy parsing
  -json modifier Output will be in jSON format useful for more advanced parsing
  -try modifier Not currently supported

Subroutine API (bpi.form.admin.sub)

 

action      = 0
phantomName = \bpiform1\
bpi.form.admin.sub(phantomName, action, param, control, tryFor, verbose, returnVar, status, message)
IF returnVar<1,3> NE \\ THEN
CRT \Phantom Name \:returnVar<1,1>:\ is running on pid \:returnVar<1,3>
END ELSE
CRT \Phantom Name \:returnVar<1,1>:\ is not running\
END

 

Param Direction Type Description
phantomName Passed string The name of the phantom (the value of key= in the BPI.FORM.PHANTOM.CONTROL record). for the targeted phantom.  For status action, the value of asterisk (*) indicates all phantoms should be targeted. 7/31/24: * is now supported for all admin actions (e.g., start/kill).
action Passed integer The action code.  See the bpi.bp.form bpi.form.phantom.include record for a list of action codes.  Look at the definitions starting with "a."
param bi-directional array Caution, certain actions may overwrite this array.
control Returned array

An array of information about the targeted phantom(s).  For a definition of the control array schema, see the bpi.bp.form bpi.form.phantom.include record.  Look for the definitions starting with "c."

tryFor Passed integer

Not currently supported.  An integer indicating the number of seconds that an action should be performed until successful or until number of seconds expires.  Currently, you must manage this in your own program.

verbose Passed integer

An integer indicating level of verbosity.  Zero means no verbose messages.  The higher the number, the more messaging will be sent to the screen.

returnVar Returned array

An attribute/multivalue delimited array where each attribute contains information about each requested phantomName (one per attribute) and each attribute is delimited by multivalue mark with phantomName, action, and value.

For example:

bpiform1]0]12345^bpiform2]0]12346

would indicate that:

phantomName bpiform1, status (0), is running on pid 12345

phantomName bpiform2, status (0), is running onpid 12346

 

status Returned signed integer

Generally, a zero indicates success whereas anything else indicates an error.

message Returned string

A descriptive string related to errors encountered.

 

Permissions implications

To use the full function of the utility, the user issuing the bpi.form.admin command must be in the special security group bpifuser.  Certain functions also require that the user be a member of the user group bpifadm.  See /etc/sudoers for your current configuration.

A user can be added to the groups using this Linux/Unix command:

 

usermod -a -G bpifuser <targetUserName>
usermod -a -G bpifadm <targetUserName>

Then you will need to logout and back in before the changes will take effect.  This security feature allows you to open administrator privileges to only the users on your system that should be allowed to administer the phantoms.  Remember too that if you plan to embed the bpi.form.admin or bpi.form.admin.sub into processes such as end-of-day procedures or cron procedures, the user that will execute the command will need to be added to the groups above as advised.  See the Blue Prairie Forms documentation Managing Users for more information about configuring users and visudo to maintain proper system security.

 

Example Code:

 

CALL bpi.form.admin.sub("bpiform1",0,param,control,tryFor,5,returnVar,status,message)

The above example checks the status (second param is zero which according the bpi.form.phantom.include record states that zero is action 'status' (aka getList).

Action code definitions (from bpi.form.phantom.include)

EQU a.getlist           TO 0        ;*(this is passed by the -status action)
EQU a.start             TO 1
EQU a.kill              TO 2
EQU a.ping              TO 3
EQU a.test              TO 4
EQU a.count             TO 5
EQU a.getpid            TO 6
EQU a.getoostatus       TO 7
EQU a.getprinterstatus  TO 8
EQU a.ssh               TO 9