keepcli is a command line toolused primarily for issuing search and aggregate queries. Additional verbs are added to the environment from time to time.
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.
keepcli is distributed as a docker image. Docker must be installed and the docker daemon running to use keepcli.
docker run feenics/keepcli --version
will pull the latest version of keepcli and display the current version.
keepcli stores credential information in the folder /app/Feenics/KeepCli within the running container. To save configurations from one invocation to the next this folder must be mapped to a volume on the host file system. add -v keepcli_vol:/app/Feenics to the docker run command.
Since keepcli will be run many times per day it’s important to cleanup the containers filesystem when container exits. They really pile up over the course of the day.
Attach STDIN, STDOUT, STDERR from the container to the host. This is required to redirect keepcli output to other programs, such as jq
Attach a pseudo tty. This is required during configuration of a profile, as keepcli will prompt the user for missing configuration values. Otherwise this option is not required. It is also not required if providing all the configuration values as arguments.
It is common to create an bash alias in the users profile to make execution of keepcli simplier. Remember a shell alias can’t be used in other bash scripts.
alias keepcli='docker run -i --rm -v keepcli_vol:/app/Feenics feenics/keepcli:latest'
keepcli supports multiple profiles. Each profile is stored as a unique file with .json extension inside the /app/Feenics/KeepCli folder, which should be mapped to volume. Use the -@ or --profile option to name the profile. If not supplied the name default is assumed.
These configuration files are unencrypted, and only as secure as the workstation & user profile on which they reside
docker run --rm -it -v keepcli_vol:/app/Feenics feenics/keepcli configure \
-a https://keepapi.feenicshosting.com \
-i *yourinstance* \
-u *yourusername* \
-e wss://keepevents.feenicshosting.com \
-p *yourpassword*
--TFA " "
After setting the profile, try it out with the test verb.
keepcli test
Connected to *your instance commonName* (yourInstanceFQDN) on https://keepapi.feenicshosting.com version x.x.
The first argument for keepcli must be one of the defined verb. Use the –help option to get a list of verb with descriptions for each verb.
keepcli --help
Copyright (C) 2019 KeepCli
configure Supply Configuration information to be saved to disk...
test Test saved configuration
list Test saved configuration
get Get object by Key
search Search
command Command Mercury Readers
aggregate Execute an Aggregate Query
getinfotemplate Get object by Key
message Send a message to a person
renameFqdn Rename an FQDN for an existing instance
remove Remove saved configuration
subscribe Subscribe to events
controller-changetype Change the type of a Controller from Ep to Lp or Lp to Ep
get-bearer-token returns 'Authorization: Bearer < token from profile connection >'
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.
keepcli configure --help
KeepCli 1.0.32
Copyright (C) 2019 KeepCli
-a, --ApiAddress URL of the Keep Server to connect to. For example https://keepapi.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 user 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
-@, --Profile (Default: default) Saved Profile Name
--help Display this help screen.
--version Display version information.
There are number of circumstances when making a cUrl call to the Keep by Feenics API is necessary as part of application development and testing. To make a curl call to the API, a valid access token is required. keepcli can be used to get an access_token.
curl -s -H 'Accept: application/json' -H "$(keepcli get-bearer-token)" $(keepcli test -j | jq -r .BaseAddress)/api | jq '{Cn:.CommonName, Fqdn:.FullyQualifiedDomainName, Key:.Key}'
This script uses the -j option on the test verb to return a JSON value similar to:
{
"CommonName": "feenicsdev Origo TEST",
"FullyQualifiedDomainName": "feenicsdev",
"BaseAddress": "https://keepapi.feenicshosting.com",
"Key": "5d6e6ebd22ac6900016d96b4",
"Version": "2.0.4.157",
"Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJzdWIiOiI1ZDZlNmVkYjIyYWM2OTAwMDE2ZDk2YmIiLCJpbnN0YW5jZSI6IjVkNmU2ZWJkMjJhYzY5MDAwMTZkOTZiNCIsIm5iZiI6MTU2NzUyMjM0NiwiZXhwIjoxNTY3NjA4NzQ2LCJpYXQiOjE1Njc1MjIzNDZ9.ChSSbhqq6gGJaIkT7KjnRzbGtk9l6WuM5UT34ZGneS8"
}
This JSON value is piped to jq to extract the baseAddress field.
the curl command in this case simply returns the InstanceInfo object for the logged in user
The Keep by Feenics API offers a search facility leverages the MongoDB search syntax. For example to find the zero or more people with a given name (first name) of Ralph use:
keepcli search -s '{"GivenName":"Ralph"}' | jq .
This will return one more PersonInfo objects. Use jq to filter out only specific fields.
keepcli search -s '{"GivenName":"Ralph"}' | jq '{cn:.CommonName, cards:.CardAssignments}'
The keepcli 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.
keepcli 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. keepcli 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 it’s 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). Also all 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.
keepcli 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"
}
}
}