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