manual/src/main/asciidoc/shell-commands.adoc

//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
=== SSH Shell Commands

Apache Unomi provides its own Apache Karaf Shell commands to make it easy to control the application
lifecycle or perform queries or modifications on the internal state of the system.

All Apache Unomi-specific commands are namespaced and use the `unomi:` namespace. You can use the Apache Karaf Shell's
autocompletion to list all the commands available.

==== Using the shell

You can connect to the Apache Karaf SSH Shell using the following command:

    ssh -p 8102 karaf@localhost

The default username/password is karaf/karaf. You should change this as soon as possible by editing the `etc/users.properties` file.

Once connected you can simply type in :

    unomi:

And hit the <tab> key to see the list of all the available Apache Unomi commands. Note that some commands
are only available when the application is started.

You can also use the `help` command on any command such as in the following example:

```
karaf@root()> help unomi:migrate
DESCRIPTION
        unomi:migrate

    This will Migrate your date in ES to be compliant with current version.
    It's possible to configure the migration using OSGI configuration file: org.apache.unomi.migration.cfg,
    if no configuration is provided then questions will be prompted during the migration process.

SYNTAX
        unomi:migrate [fromVersionWithoutSuffix] [skipConfirmation]

ARGUMENTS
        fromVersionWithoutSuffix
                Origin version without suffix/qualifier (e.g: 1.2.0)
                (defaults to 1.2.0)
        skipConfirmation
                Should the confirmation before starting the migration process be skipped ?
                (defaults to false)

```
==== Lifecycle commands

The commands control the lifecycle of the Apache Unomi server and are used to migrate, start or stop the server.

.Table Lifecycle commands
|===
|Command|Arguments|Description

|migrate
|fromVersion
|This command must be used only when the Apache Unomi application is NOT STARTED. It will perform migration of the data stored in ElasticSearch using the argument fromVersion as a starting point.

|stop
|n/a
|Shutsdown the Apache Unomi application

|start
|n/a
|Starts the Apache Unomi application. Note that this state will be remembered between Apache Karaf launches, so in general it is only needed after a first installation or after a `migrate` command

|version
|n/a
|Prints out the currently deployed version of the Apache Unomi application inside the Apache Karaf runtime.
|===

==== Runtime commands

These commands are available once the application is running. If an argument is between brackets [] it means it is optional.

.Table Runtime commands
|===
|Command|Arguments|Description

|rule-list
|[maxEntries] [--csv]
|Lists all the rules registered in the Apache Unomi server. The maxEntries (defaults to 100) will allow you to specify
how many entries need to be retrieved. If the value is inferior to the total value, a message will display the total
value of rules registered in the server. If you add the "--csv" option the list will be output as a CSV formatted table
|rule-view
|rule-id
|Dumps a single rule in JSON. The rule-id argument can be retrieved from the `rule-list` command output.
|rule-remove
|rule-id
|Removes a single rule from Apache Unomi. The `rule-id` argument can be retrieved from the `rule-list` command output.
Warning: no confirmation is asked, be careful with this command.
|rule-reset-stats
|n/a
|Resets the rule statistics. This is notably useful when trying to understand rule performance and impact
|rule-tail
|n/a
|Dumps any rule that is executed by the server. Only executed rules are logged here. If you want to have more detailed
information about a particular rule's condition evaluation and if it's already been raised use the `rule-watch` command
instead. This tail will continue until a CTRL+C key combination is pressed.
|rule-watch
|rule-ids
|Dumps detailed evaluation and execution information about the rules that are where specified in the `rule-ids` arguments
(you can specify multiple rule identifiers separated by spaces). The `Status` column has the following values: EVALUATE -
indicates that the rule's conditions are being evaluated (but they might not be satisfied), AR PROFILE - means the rule
has already been raised for the profile and will therefore not execute again for this profile, AR SESSION - means the
rule has already been executed for this session and will therefore only executed when another session for the profile is
created, EXECUTE means the rule's actions are being executed.

|event-tail
|n/a
|Dumps any incoming events to the Apache Unomi server to the console. Use CTRL+C to exit tail
|event-view
|event-id
|Dumps a single event in JSON. The `event-id` can be retrieved from the event-tail command output.
|event-list
|[max-entries] [event-type] [--csv]
|List the last events processed by Apache Unomi. The `max-entries` parameter can be used to control how many events are
displayed (default is 100). The `event-type` makes it possible to filter the list by event type. The `--csv` argument is used to output the list as a CSV list instead of an ASCII table.
|event-search
|profile-id [event-type] [max-entries]
|This command makes it possible to search for the last events by `profile-id` and by `event-type`. A `max-entries`
parameter (with a default value of 100) is also accepted to control the number of results returned by the search.

|action-list
|[--csv]
|Lists all the rule actions registered in the Apache Unomi server. This command is useful when developing plugins to
check that everything is properly registered. If you add the "--csv" option the list will be output as a CSV formatted table
|action-view
|action-id
|Dumps a single action in JSON. The action-id argument can be retrieved from the `action-list` command output.

|condition-list
|[csv]
|List all the conditions registered in the server. If you add the "--csv" option the list will be output as a CSV formatted table
|condition-view
|condition-id
|Dumps a single condition in JSON. The condition-id can be retrieved from the `condition-list` command output.

|profile-list
|[--csv]
|List the last 10 modified profiles. If you add the "--csv" option the list will be output as a CSV formatted table
|profile-view
|profile-id
|Dumps a single profile in JSON. The profile-id argument can be retrieved from the `profile-list` command output.
|profile-remove
|profile-id
|Removes a profile identified by `profile-id` argument. Warning: no confirmation is asked so be careful with this command!

|segment-list
|[--csv]
|Lists all the segments registered in the Apache Unomi server. If you add the "--csv" option the list will be output as a CSV formatted table
|segment-view
|segment-id
|Dumps a single segment in JSON. The segment-id argument can be retrieved from the `segment-list` command output.
|segment-remove
|segment-id
|Removes a single segment identified by the `segment-id` argument. Warning: no confirmation is asked so be careful with
this command!

|session-list
|[--csv]
|Lists the last 10 sessions by last event date. If you add the "--csv" option the list will be output
                                                as a CSV formatted table
|session-view
|session-id
|Dumps a single session in JSON. The session-id argument can be retrieved from the `session-list`, `profile-list` or
 `event-tail` command output.

|deploy-definition
|[bundleId] [type] [fileName]
|This command can be used to force redeployment of definitions from bundles. By default existing definitions will not
be overriden unless they come from SNAPSHOT bundles. Using this command you can override this mechanism. Here are some
examples of using this command: `unomi:deploy-definition 175 rule *` will redeploy all the rules provided by bundle with
id 175. If you launch the command without any arguments you will get prompts for what you want to deploy from which bundle.
If you want to deploy all the definitions of a bundle you can also use wildcards such as in the following example: `deploy-definition 175 * *`.
It is also possible to give no argument to this command and it will then interactively request the definitions you want
to deploy.
|undeploy-definition
|[bundleId] [type] [fileName]
|This command does the opposite of the `deploy-definition` command and works exactly the same way in terms of arguments
and interactive mode except that it undeploys definitions instead of deploying them. This command can be very useful when
working on a plugin. For example to remove all the definitions deployed by a plugin you can simply use the following
command: `undeploy-definition BUNDLE_ID * *` when `BUNDLE_ID` is the identifier of the bundle that contains your plugin.

|===