velocity-cmd

Enables you to execute Watson Explorer Engine SOAP/REST API functions from the command line.

Synopsis

velocity-cmd [-h|-help]
    [-installation-dir /path/to/velocity/installation]
    [-list]
    [-list-xml]
    [-user userid]
    {<function> [help|<name>=<value>]}

Description

The velocity-cmd command is located in the bin subdirectory of a Watson Explorer Engine installation. This command enables you to execute any Watson Explorer Engine SOAP/REST API function from the command line. Additionally, the command can be used to provide detailed help for an API function.

The velocity-cmd command must be able to contact an executable that supports the full Watson Explorer Engine SOAP/REST API. When using velocity.aspx as the primary executable for Watson Explorer Engine, you must use the velocity-config command to modify the global/api-url variable to explicitly set the location of the velocity.aspx application, as in the following example:

 velocity-config global/api-url=http://url/to/velocity.aspx

Note: Since this command can only be run by an authenticated administrative user of the server on which Watson Explorer Engine is installed, authentication to Watson Explorer Engine is assumed. However, for some functions it is appropriate to identify the user (such as queries, annotations, etc.). When this is required, the -U or -user parameter should be specified.

Options

-h|-help Displays the command line help message and exits.
-installation-dir Defines the location of the Watson Explorer Engine installation. If the default installation directory was used, this parameter is not necessary.
-list Displays a list of all the available API functions. This list is very long, make sure your terminal buffer is sufficiently large enough to accommodate it.
-list-xml Displays a list of all the available API functions in xml format. This list is very long, make sure your terminal buffer is sufficiently large enough to accommodate it.
-user Defines the user to be used when executing the API function. The default is none.
Note: Any user specified using this parameter must already exist within Watson Explorer Engine.
<function> help Returns comprehensive help about the specified function.
<function> <name>=<value> Performs the Watson Explorer Engine REST API function using the specified parameters. The API response is then delivered to the command line. The xml header is not included in the response. Any API function may be performed by the velocity-cmd command, consult the API Developers Manual for a complete list of available API commands and expected syntax.

When executed with no arguments, the velocity-cmd command displays the same output as if it had been called with its -help option.

Messages

If the installation directory has been specified incorrectly, the following message will appear:

There has been a problem:
      The directory 'directory' does not appear to be a
      valid Velocity Installation.  Your installation may
      be incomplete or you may need to specify the '-I' option, followed
      by the name of the directory in which Velocity is
      installed. (ID: CLI_BAD_VELOCITY_DIR_ERROR)

If a user that does not exist in Watson Explorer Engine has been specified, the following message will appear:

There has been a problem:
      (ID: CORE_AUTHENTICATE_ERROR) Login failed because
           the user does not exist or the password was incorrect.

If an API call that does not exist in the Watson Explorer Engine SOAP/REST API is specified, the following message will appear:

There has been a problem:
      (ID: XML_FUNCTION_NOT_DEFINED_ERROR) "function""API call" is not defined

See the Velocity API Developers Guide for detailed information about any other messages that you may receive from the velocity-config command.

Examples

Input Example:

./velocity-cmd -list

Output Example:

List functions:
 alert-list-xml: Retrieves a list of alerts for all users.
     This function has no inputs
     returns:
         Type:       nodeset
     throws:
       - alert-list

 alert-run: Starts the alert service and run alerts for user or id provided.
      input:
          - user: Run all alerts for this user.
              Type:           nmtoken
              Required:       No
          - alert-id: Run alert which has this id.
              Type:           string
              Required:       No
      throws:
          - alert-run

 alert-service-start: Starts the alert service and run all user alerts.
     This function has no inputs
     throws:
         - alert-service-start

 alert-service-status-xml: Retrieves the status of the alert service, whether it is running or not.
     This function has no inputs
     returns:
         Type:       nodeset
     throws:
         - alert-service-status
 .
 .
 .

Input Example:

./velocity-cmd -U administrator dictionary-list-xml

Output Example:

<dictionaries>
  <dictionary name="english" />
  <dictionary name="doc-search-dictionary" />
  <dictionary name="test" />
  <dictionary name="default" />
  <dictionary name="base" />
</dictionaries>

Exit Status

Exits with status 0 when the command is successful.

Note: On Linux systems, exit codes above 127 are returned by the shell. Please consult the documentation for the shell that you are using for more information.