Vantiq CLI Reference Guide

Overview

The Vantiq Command Line Interface (CLI) is a tool for managing development resources for a Vantiq project. The Vantiq CLI manages both system defined resources such as:

The CLI will also manage user defined resources (though not all commands apply to these resources).

The major commands available in the CLI include:

Command line options available include:

Installation

Prerequisites

The Vantiq CLI is a Java (Groovy) application and requires an installation of Java 8.

Download

The Vantiq CLI is available as a downloadable zip file accessible from the Resources page of the developer UI.

Once downloaded the zip file can be expanded in any directory and will create a sub-directory with the name vantiq-x.x.x, where x.x.x is the version of the CLI. It is recommended that the directory ./vantiq-x.x.x/bin be added to your path. Once installed and the PATH set, the CLI can be invoked on the command line. On Mac/Linux:

vantiq <command>

On Windows operating systems:

vantiq.bat <command>

The following examples in this document use the Mac/Linux form, vantiq. If you are on Windows, use the vantiq.bat command.

Profile

The command line can obtain credentials from a profile file. On Mac/Linux, the profile file is ~/.vantiq/profile. On Windows, the profile file is %UserProfile%\.vantiq\profile.

Entries in the profile file take the following form:

system
{
    url = 'https://dev.vantiq.com'
    username = 'myUsername'
    password = 'myPassword'
}
personal {
    username = 'myPersonalName'
    password = 'myPersonalPassword'
}
oauth1 {
    url = 'https://dev.vantiq.com'
    // this is my token for namespace ABC
    token = 'rTTbtHd8Z7gFPEQPE32137HfYNDg8YA84zmOWtVbdYg='
}

Specifying the ‘url’ is optional. The url will default to the standard values (depicted in the example). If both token and password are specified, the password is used instead of the token.

Note that the profile file may contain multiple profiles with each profile given a name. These profiles can then be easily referenced when invoking the vantiq CLI via the ‘-s’ flag.

Command Line Options

-s profileName

Specify the name of a profile, stored in: ~/.vantiq/profile, that supplies the identify of the service implementation to access and the credentials used to access the service. Default: base

-b baseURL

Specifies the base URL that identifies the Vantiq system. Default: https://dev.vantiq.com

-u username

Specifies the user’s assigned username to connect to the Vantiq system.

-p password

Specifies the user’s assigned password to connect to the Vantiq system.

-t token

Specifies the user’s access token to connect to the Vantiq system. If a password is specified, it is used instead of the token.

If the -s option is used to specify a profile and any of the -b, -u, -p, or -t options are also specified, then the command-line options override the values that are provided in the ~/.vantiq/profile file. Note that the profile file should be in ASCII or UTF-8 file-encoding.

-v

Prints the CLI version and the URL for the connected Vantiq service.

Other Options

Options that are unique to specific CLI commands are described in the documentation for each command.

Supported Commands

Help

The help command displays a short summary of the commands available in the CLI.

vantiq help

List

The list command displays a list of all resources of the type specified in the command.

vantiq list <resource>

There are no variations of the command. This command applies to both system and user-defined resources. For system resources it will display the resource’s primary identifier (typically “name”). For user defined resources it prints the id property.

Find

The find command finds an individual instance of an resource by name or query.

vantiq find <resource> <resourceId>

When performing a find for system defined resources you can use the <resourceName> variant, since all system resources are known to have this property. For user defined resources use the <resourceId> option instead. In this case you provide a query which selects the desired instance(s). The query is expressed as a JSON document in the same form as the where parameter in the REST API.

The output is the “external” form of the given resource instance which can be used for either the load or import commands. Typically this will be a single JSON file named “<resourceId>.json”, with the following exceptions:

Load

The load command will load a resource instance effectively defining or redefining the named resource. The load command accepts the “external” form of the resource as produced by find and export. For most resources this consists of a single file containing the JSON representation of the artifact. For these resources the command format is:

vantiq load <resource> <filename>

The exceptions to this are:

Delete

The delete command is used to delete an resource instance.

vantiq delete <resource> <resourceId>

Any artifact may be deleted although namespaces and users can only be deleted by sufficiently privileged administrators. For system resources the resourceId is the name of the instance while for user defined resources it is the id property.

Select

The select command is a convenience to allow you to retrieve data from the Vantiq database without having to develop an app. Any data type for which the user has read privileges may be queried.

vantiq select <resource> [<resourceId>]

The resource parameter specifies the name of the resource from which to select.

The resourceId parameter is optional. If specified then it will be used to query for the resource instance with the given id. If resourceId is not specified, all instances of the resource will be returned.

Insert

The insert command is a convenience for loading relatively small quantities of data into the Vantiq database (recommended maximum 1000 objects).

The data is placed in a file in JSON format as an array of JSON objects. The insert command parses the JSON and sends the resulting objects to the Vantiq services for insert into the database.

The operation performed is a standard insert action. If an object with the same values already exists and the type allows duplicates. Each invocation of the insert command using the same file will add duplicate objects to the database. See Upsert for an alternative that will not insert duplicate objects.

type is the data type in which to insert the objects.

file is the name of the file containing the array of JSON objects to upsert.

Upsert

The upsert command is a convenience for loading relatively small quantities of data into the Vantiq database (recommended maximum 1000 objects).

The data is placed in a file in JSON format as an array of JSON objects. The upsert command parses the JSON and sends the resulting objects to the Vantiq services for insert or update into the database.

An update is performed if the naturalKey for the object references an object already in the database. An insert is performed if the naturalKey for the object does not reference an object already in the database. The naturalKey consists of those properties specified as the natural key for the type. If no naturalKey is specified, name is assumed to be the natural key.

vantiq upsert <type> <file>

type is the data type in which to upsert the objects.

file is the name of the file containing the array of JSON objects to upsert.

CheckedInsert/CheckedUpsert

When loading larger quantities of data it is not always convenient to construct the data as a single array of JSON objects in a text file. CheckedInsert and CheckUpdate support a file format in which each object is represented as a separate JSON object with the JSON object definitions arranged sequentially within the file.

At runtime each object is parsed separately and added to the database. If a JSON object fails to parse, an error is reported with the index number of the object within the file and an attempt is made to continue the operation with the next JSON object in the file.

To ensure parsing errors can easily and uniquely identify the cause, the file should be formatted in the following manner:

Example:

[{
  "name": "a sample name",
  "address": "a sample address"
},
{
  "name": "second sample name",
  "address": "second sample address"
}]

Example of illegal JSON file:

[{
  "name": "a sample name",
  "address": 
  {
  "street": "a sample street",
  "city": "a sample city"
  }
},
{
  "name": "second sample name",
  "address": "second sample address"
}]

This example is illegal because the brace opening the definition of the nested address object is the first character on the line. The example could be converted to a legal form by placing the opening brace directly following the address property name as follows:

 [{
  "name": "a sample name",
  "address": {
  "street": "a sample street",
  "city": "a sample city"
  }
},
{
  "name": "second sample name",
  "address": "second sample address"
}]

Insert and upsert behaviors are the same as the insert and upsert commands.

Execute

The execute command can be used to execute a VAIL procedure.

execute <procedureName> <p1Name>:<p1Value> ... <pNName>:<pNValue>

procedureName must be the name of a previously defined procedure.

Procedure parameters are specified as <name>:<value> pairs using a colon (:) as the separator character. Spaces cannot be embedded in the <name>:<value> pair

The result is the JSON response produced by the executed procedure.

Recommend

The recommend command can be used to submit requests for recommendations to the server if you have created the corresponding rules to process the request.

The recommend command takes two parameters:

The response is a list of recommendations.

Export

The export command writes either the resource meta-data or data stored in user defined types into files stored in a directory on the local machine. The command takes an optional parameter used to indicate what should be exported:

If neither option is provided the default is to export the metadata.

If the -d <directoryName> option is specified, the directoryName is the name of the directory in which the export should be placed. If the -d option is not specified, the export is placed in the current working directory.

When the export runs it creates the following sub-directories and places the exported artifacts and data in the equivalently named directory. The formats used are the same as those described earlier for the find command.

Meta-Data directories:
Data Directories:

The output of the export command may be imported into any namespace using the import command.

Import

The import command reads all artifact definitions stored in a directory and loads them into the current namespace. The command takes an optional parameter used to indicate what should be imported:

The target directory must be structured as documented for the export command. In addition, files stored in the data sub-directory will have their contents loaded into the type with the same name as the file.

The import command supports the following options to customize the import behavior:

The export/import command pair can be used to conveniently migrate a system from one namespace to another namespace by creating an export directory, running the export command and then running the import command on the same directory using credentials for a user in the target namespace.