Please Note: Despite the availability of this tool it is still considered to be in development and does not undergo our normal test procedures. It should only be used as a supplementary tool and we will not provide any guarantees for bug fixings or feature improvements.
Feenics uses a bespoke declarative scripting tool called fit which is deployed as a docker image. The full run of the command is:
docker run --rm -i --net fit_net -v fit_vol:/app/Feenics -v $(pwd):/app/scripts feenics/fit
Since docker run commands are rather lengthy it’s recommended that fit be added as an alias in your terminal shell environment of choice (This wiki assumes bash but other shells, such as zsh and powershell should also work)
| Parameter | Description | Purpose |
|---|---|---|
--rm |
Automatically remove the container when it exits | fit is stateless and so a named container should not be maintained from one execution to the next |
-i |
Keep STDIN open even if not attached | allow fit to receive it’s input from the STDIN, particularly useful with the aggregation verb |
--net fit_net |
Connect a container to a network | allows fit to connect to other services running on the same docker virtual network |
-v fit_vol:/app/Feenics |
Bind mount a volume | fit needs a place on the host to store its profile files this establishes a volume for that purpose |
-v $(pwd):/app/scripts |
Bind mount a volume | Mounts the current directory to a directory called scripts in the container. Used by the -f command of the fit run verb. Assumes running with bash shell. |
For bash shell users add the following to the ~/.bash_profile or ~/.bash_aliases file.
fit=docker run --rm -i --net keep_net -v fit_vol:/app/Feenics -v $(pwd):/app/scripts feenics/fit
This change will take effect on next login, or use
source ~/.bash_profile
to load the profile into the current terminal session.
For Windows Powershell users refer to Microsoft Powershell documentation on aliases.
A fit profile describes a connection to a Feenics host. The profile is saved on the host computer in the fit_vol volume maintained by docker. The contents of the file is not encrypted and thus are only as secure as the workstation/user it is saved on. A profile can be created with the configure verb and a complete set of parameters. Alternatively, run fit using an additional -t parameter on the docker command. This will connect the TTY to the container, and allow fit to prompt for the connection values. Use fit configure --help for the set of parameters that must be set.
fit configure -@ default -a https://dev-api.feenicsdev.com -i keep-v3.feenicshosting.com -e wss://dev-events.feenicsdev.com -u exampleUsername -p examplePassword -t " "
Be cautious of setting a default profile if you routinely switch between various environments, such as dev vs production. If that is the case, make sure that the default profile references a service/instance that is of limited/no value (such as dev)
After setting the profile, try it out with the test verb.
fit test
Connected to *your instance commonName* (yourInstanceFQDN) on https://keepapi.feenicshosting.com version x.x.
The first argument for fit must be one of the defined verbs. Use the –help option to get a list of verb with descriptions for each verb.
fit --help
fit 23.9.76
Copyright (C) 2023 fit
configure Supply Configuration information to be saved to disk for future reference
test Test saved configuration
list Test saved configuration
get Get object by Key
search Search
command Command Mercury Readers
aggregate Execute an Aggregate Query
get-info-template Get object by Key
send-message Send a message to a person
rename-fqdn Rename an FQDN for an existing instance
subscribe Subscribe to events
controller-change-type Change the type of a Controller from Ep to Lp or Lp to Ep
reset-access-levels Reset AccessLevels to Badge Type Defaults
get-instance Lookup an instance by FQDN
move-instance Move an instance to a new parent
get-object-count get the count of objects for an instance
get-event-type Get Event Type
get-cards-for-controller Get Cards For Controller
change-host Change hostname for configured controller
get-bearer-token returns 'Authorization: Bearer <token from profile connection>'
list-instructions List all available script instructions
run run the spec file (FITS)
get-image Get image for object
get-script-schema Get the fit-script schema to either a file or stdout
migrate-to-secure-pin Migrate current CardAssignment PINs to SecurePin
help Display more information on a specific command.
version Display version information.
Use the –help option with a verb to get the set of options specific for that verb.
fit configure --help
fit 23.9.76
Copyright (C) 2023 fit
-a, --ApiAddress URL of the Keep Server to connect to. For example https://api.feenicshosting.com for US customers
-i, --Instance The login name of the instance. The same value that is supplied when logging in using the Windows, Web, or Mobile Clients
-u, --Username The username name to connect with. May be proceeded with an different instance name in the system hierarchy
-p, --Password The password to be used for this user to connect.
-r, --Replace Update existing configuration with new values
-c, --Copy Copy this existing configuration
-e, --EventPublisher Url of the MQTT Event Publisher for this API Service
-t, --TFA TFA Secret if enabled
--new-password new password to set if 'must change password on next login' is true
-d, --Delete Delete named profile
-@, --Profile (Default: default) Saved Profile Name
-l, --LoggingLevel (Default: Information) Logging Level(Verbose, Debug, Information, Warning, Error, Fatal)
--help Display this help screen.
--version Display version information.
fit is able to subscribe to events in real time. Use the -t option to provide a template for the event output in human readable format. More typical use case is to transform the published event message into something more concise. Event subscription runs over a separate web socket from a separate service independent to the API Server. This service end point must be added to the configuration.
fit configure -r -e wss://dev-events.feenicsdev.com
Once configured use the subscribe verb to establish a connection to the event publisher. The event messages produced are an extension to the EventMessageData. Fit adds the property EventData to the message, which is the JSON rendering of the EventDataBsonBase64 string that is also included. The EventData property of the event message is free-form and its contents will vary depending on the event type. Use the -d option to change the duration of the subscription, or the -l to limit the total number of events reported. Also note that DateTime properties such as PublishedOn, and OccurredOn are returned as Unix Epoch (milliseconds since 1970-01-01), and DateTime values are UTC.
{
"PublishedOn": { "$date": 1567596623176 }
}
For example, the following command will subscribe to all events for a period of 1 hours (3600 seconds) and use jq to format the output to include only the PublishedOn date, MessageLong value, and all EventData.
fit subscribe -d 3600 | jq -c '{d:.PublishedOn."$date"| (. / 1000 | todate),m:.MessageLong,meta:.EventData}'
{
"d": "2019-09-04T11:37:28Z",
"m": "Login attempted by user System Administrator. Outcome: Passed",
"meta": {
"Outcome": "Passed",
"User": {
"CommonName": "System Administrator"
}
}
}
fit can run a type of JSON-based scripts to accomplish more complex tasks. For full documentation refer to the github wiki.
{
"instructions": [
{
"writeLine": "Hello, world"
}
]
}
fit run -@profile -f scripts/hello_world.json -l Information
[INF] Hello, world