Conductor - Data Platform | JavaScript SDK

Conductor JavaScript API

The Conductor JavaScript API is published at

 http://conductor.link-labs.com/conductor-api.min.js

Introduction

The Conductor JavaScript API allows web-based clients to access device and message data from Conductor. This API abstraction includes elements from the access, clientEdge and network Asset system calls. It provides a single interface to build an integrated user experience. For example, the Conductor JavaScript API is used by the Conductor web interface.

Getting Started

The basic workflow with the Conductor JavaScript wrapper is:

Load the API directly from conductor.link-labs.com
Create a session
Access data for streams as needed

Load the API

Load the Conductor JavaScript API from http://conductor.link-labs.com/conductor-api.min.js along with other utility libraries such as jquery and knockout.js. The jquery library is required and it provides AJAX and Promise implementations. Knockout is optional.

<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/knockout/3.4.0/knockout-min.js"></script>
<script src="//conductor.link-labs.com/conductor-api.min.js"></script>

Create a session

Create a Conductor object and initialize a session:

  var conductor = new Conductor();
  conductor.getSession().then( function onValidSession() {
    // An authenticated Conductor account is available, proceed normally
  }, function onInvalidSession() {
    // In this case, the user does not have access to Conductor, so a
    // login operation is necessary.  The best practice is to redirect
    // to a login page, and then return here once conductor.login() 
    // succeeds.  This way, you avoid operating with the conductor object
    // unless the session-based cookies are working correctly. 
    window.location = 'login.html';
  });

Access data

For a streaming client, the easiest way to access message traffic is to use an observable array data structure such as the one in knockout.js. For example:

  var dataType = 'gateway';  // could also be 'application', 'network', or 'node'
  var dataHolder = {
    gatewayId: '$101-0-0-0-xxxxxxxxx',   // for nodeType=='gateway'
    messages: new ko.ObservableArray()
  }
  conductor.attachMessages( dataType, dataHolder );
  // Use dataHolder.messages as appropriate.
  // sometime later…
  conductor.detachMessages( dataType, dataHolder );

Methods

Conductor()

Constructor for the Conductor API.

login( options )

options - an object with the following keys:

username - User name for the Conductor account, usually an email address.
password - Password for the Conductor account.

This API call logs into Conductor and creates a session, returning a Promise. The returned Promise-value includes account information about the now authenticated user.

logout()

Ends the current Conductor session, returning a Promise that resolves upon completion.

getSession()

Fetches the current session, if still valid. If the returned Promise object is resolved as a rejection, then the client should create a new session using the login call.

getMessages( nodeType, nodeId, maxResults )

nodeType - type of data stream to access, could be ‘gateway’, ‘network’, ‘application’, or ‘module’ 
nodeId - the identifier appropriate for the node type. For example, if nodeType=’gateway’, then nodeId will be of the form $101-0-0-0-xxxxxxxxx 
maxResults - optional max number of messages to load, defaults to 20

This call loads messages for the given node type from Conductor as a single connection (without streaming or polling). No messages older than 5 days will be returned. Returns a Promise that resolves to the requested data.

attachMessages( nodeType, streamOptions, decoder, options )

nodeType - type of data stream to access, could be ‘gateway’, ‘network’, ‘application’, or ‘module’ 
streamOptions - an object with the following fields:
-  gatewayId - identifier of the form $101-0-0-0-xxxxxxxxx, required when nodeType is ‘gateway’
-  networkToken - 8 character hex string, required when nodeType is ‘network’ 
- applicationToken - 20 character hex string, required when nodeType is ‘application’
-  module - Identifier of the form $301-0-0-0-xxxxxxxxx, required when nodeType is ‘module’ 
- messages - Array, Array-like object (with push(), length, and shift() operations), or knockout ObservableArray to be populated with messages from the data stream 
decoder - An optional function that is called when each new message arrives. The call parameter is the message that was just received. The return value must be a Promise. Once the returned Promise resolves with success, the streamOptions.messages array will have the new message pushed into it. 
options - an optional object with the following field: 
- maxResults - The number of messages to hold in the streamOptions.messages array, default value is 20. This is also passed to Conductor at first connection as a maximum number of history messages to pre-populate.

Creates a streaming connection to Conductor and populates messages from the nodeType/nodeId combination as they arrive. The first time a stream is attached, the JavaScript API will populate up to options.maxResults history messages from the previous 5 days of traffic. Returns a Promise that resolves to the Conductor.Subscription object that implements the streaming connection.

detachMessages( nodeType, streamOptions )

Closes a stream created by the attachMessages operation. The nodeType and streamOptions.<gatewayId, networkToken, applicationToken, or module> parameters must match the corresponding attachMessages call. There is no return value.

issueCommand( payload, options )

payload - the hex string to send to the target module 
options - an object with the following required fields:
-  module - the destination module for this message (or $301-0-0-0-fffffffff for broadcast) 
- gateway - An optional id for the gateway to use in routing. It is noAck - If false or omitted, then the requiredAckRatio and requiredSuccessfulAckRatio commReqs options are both set to 0. If true, then the values will be 1.

Sends a hex payload to the given destination. If a gateway is provided, then the message will use Conductor’s commandRoutes mode for transmission. Otherwise, commandTargets mode is used. All messages sent with this API wrapper have a ttl of 60 seconds. The return value is a Promise that resolves to Conductor’s envelope information about the command.

loadGateways()

Loads all gateways in the current session’s account, returning a Promise that resolves into the known Gateway objects.

updateGateway( gatewayInfo )

gatewayInfo - an object with the following fields:
- apiBase - the URL for this gateway (rel.href) as returned by the loadGateways() call
- gatewayName - new name for the gateway

Updates the name of a given gateway, returning a Promise that resolves upon completion.

registerGateway( args )

args - an object with the following fields: 
- gatewayId - the id of the gateway to register 
- networkToken - the network token to assign to this gateway

Updates the network token registration for the given gateway, returning a Promise that resolves upon completion.

loadNetworks()

Loads all network tokens in the current session’s account, returning a Promise that resolves into the known Network objects. Universal (Open) network(s) are also discovered as a side effect.

updateNetwork( networkInfo )

networkInfo - an object with the following fields:
-  apiBase - the URL for this network (rel.href) as returned by the loadNetworks() call. 
- networkName - new name for the network token

Updates the friendly name of a given network token, returning a Promise that resolves upon completion.

loadApplications()

Loads all application ids in the current session’s account, returning a Promise that resolves into the know Application objects.

updateApplication( applicationInfo )

applicationInfo - an object with the following fields:
- apiBase - the URL for this network (rel.href) as returned by the loadApplications() call
- applicationName - new name for the application id

Updates the friendly name of a given application, returning a Promise that resolves upon completion.

createApplication( applicationName )

applicationName - optional name for the newly created application id. Default value is a name derived from the username and current time.

Creates a new application id and associates it with the current account. Returns a Promise that resolves upon completion of the creation process.

loadApplicationStats( options )

options - an optional object with the following field: 
- refreshRate - time, in milliseconds, between poll updates to refresh the module list

Accesses Conductor to find all modules registered to this account, updating the various data structures returned from loadApplications(), loadGateways(), and loadNetworks(). Returns a Promise that resolves upon the first completion of the Conductor call. If refresh is enabled (with a value greater than 0 ms), then subsequent calls will not have an effect on the Promise.

loadUsers()

Loads all users in the current session’s account, returning a Promise that resolves into the known User objects.

updateUser( userInfo )

userInfo - An object with at least one of the following fields - name, company, phoneNumber, address1, address2, city, state, zipCode, country. In addition, the following field is required:
-  apiBase - the URL for this user (rel.href) as returned by the loadUsers() call

Updates the personal information for the given user. Returns a Promise that resolves upon successful update of the user.

updatePassword( userInfo, oldPassword, newPassword )

userInfo - an object with the following fields:
-  apiBase - the URL for this user (rel.href) as returned by the loadUsers() call.
-  email - the user’s login name (usually an email address) 
oldPassword - the old password on the account 
newPassword - the desired replacement password

Updates the user’s password. Unlike most other calls in this API wrapper, updatePassword() does not use the current session. This call returns a Promise that resolves upon successful completion of the change operation, logout, login, and getSession. The Promise may reject upon a failure at any of those steps, so refer to the Promise’s value for a description of how it failed.

createUser( userInfo )

userInfo - An object with the new user’s email, password, and name. Additional fields such as company, phoneNumber, address1, address2, city, state, zipCode, and country are optional.

Creates a new user. If there is an authenticated session, then the new user will be provisioned as a member of the current account. Otherwise, the user will be anonymously provisioned. Returns a Promise that resolves with the new user’s information upon completion of the provisioning process.