Getting Started

Everything you need to know to get started with Formant.

    Configure or add new Commands

    A command is a directive to the device to perform a specific task. Commands  are listed on the device channel. Before a command is listed on the device channel, it must be configured by an administrator.

    There are two types of commands that can be created. 

    1. Built-in commands - These are commands available by default.
    2. Custom commands - These are commands created by the user/admin using Formant API. For more information, visit the help documentation on creating custom commands

    Both of these commands can be configured on the Commands page. You can add a friendly name, description, and specify the device channel on which the commands should appear. 

    A command is defined by the following information:

    Field Description

    Name

    Name your command to help you and others identify it

    Definition

    Determines what command to invoke on the device

    Enable parameters

    Toggle determines if additional data should be sent with the command

    Parameter value

    Optional parameter value to be sent with this command (otherwise the parameter value will be collected from the user when the command is issued)

    Description Description to display to the user when the command is run

    Choose device

    Use tags to constrain the devices on which to enable the command

    Add a new command

    Before a command can be sent to a device, the command must be defined by an administrator.

    From the burger menu select Settings  ⇒ Command  

    This page lists the commands that are defined.

    To create a new command, click Add Command

    Name

    Choose a friendly name that other users can understand. This is the name that will be listed under the device channel.

    Choose devices

    Choose devices on which this command should be enabled. The device list should be filtered down using the tags you have defined for devices. 

    Don't have devices set with tags?

    Check out our documentation for adding tags on devices

    Configure Commands

    Choose command definition

    Choose the system command that you want to enable. The built-in commands are displayed as a drop-down menu. You will have to type in any custom commands.

    Enable/disable command parameters

    Commands have the option to be assigned parameters. If you want to restrict the command to specific parameters, or if the command has no parameters, use the toggle button to disable parameters.

    Enter default parameters

    Add the default parameters here. If a default parameter is entered, users will not see a screen to set parameters. This is useful when you want to restrict the scope of a command to the default parameter set. 

    For example, you could limit run_script command to only running a specific script on the device. In order to do this, first set Enable Parameters to ON. Then set the path of the command you want to run.

    Add description

    Add a description so that users can understand what the command is about and/or any required parameters. This is a field that is displayed to the users when they run the command.

    Monitoring Commands

    There are three states that an issued command can be in. 

    When a command is issued, it is added to the command queue in the cloud and is moved to the Issued state. It stays in this state until the device is online. If the device is unreachable after 72 hours, the commands are expired and will not be delivered to the device.

    If/when the device comes online, the commands are delivered to the device. Unlike the Cloud command queue, the maximum number of pending command requests on a device (saved on the device but not yet read by the agent API) is 10. If a new command comes in after that, the oldest one will be dropped.

    After the agent has processed the command, it sends a response, which is then passed on to the cloud along with a status of Success or Failure.  

    These states are represented by events on the timeline and the event list page.

    © 2020 Formant • 1999 Bryant St · San Francisco, CA 94110