telogis-tde v1.0.2

telogis-tde

With telogis-tde, it’s easier to use Node.js to manage and execute TDE templates, which allow you to import and export data from Telogis tables.

Installation

$ npm install telogis-tde

Examples

How to upload a TDE template

var TDE = require('telogis-tde');
// Load the fs module to access the file system for reading the template content
var fs = require('fs');
// Read the account information from a JSON file
var details = fs.readFileSync('./account-details.json');
var accountInfo = JSON.parse(details);
// The constructor takes the customer name, username, and password to authenticate
var tde = new TDE(accountInfo.customerName, accountInfo.userName, accountInfo.password);
// Define the variable to use as the input string for the tde function
var template = fs.readFile('Template.txt').toString();
// The function call takes the template file contents as a string
tde.createOrUpdateTemplate(template).then(callback).catch(errorHandler).done();

How to execute a TDE template

var TDE = require('telogis-tde');
var tde = new TDE(accountInfo.customerName, accountInfo.userName, accountInfo.password);
// Specify the template to execute by name or ID, both of which should be passed to the function as a string
var templateName = 'DriverRetrieve';
tde.executeTemplate(templateName).then(callback).catch(errorHandler).done();

Available method calls

The following functionality is supported:

• Authenticating in TDE
• Creating a template
• Updating a template
• Retrieving a template
• Retrieving all templates
• Deleting a template
• Executing a template
• Modifying request properties

Authenticating in TDE

When you instantiate TDE, you must provide login credentials for authentication.

// Read the account information from a JSON file
var details = fs.readFileSync('./account-details.json');
var accountInfo = JSON.parse(details);
// Authenticate using login credentials
var tde = new TDE(accountInfo.customerName, accountInfo.userName, accountInfo.password);

Creating a template

The createTemplate method creates a new template. The template contents must be defined as a string and passed to the method as a variable.

// Define the template contents as a string either explicitly 
// or read the contents in from the file system using the File System module (fs) or something similar
fs.readFile(templateLocation, function(err, data) {
    if (!err) {
        var template = data;
        tde.createTemplate(template).then(callback).catch(errorHandler).done();
    } else {
        console.log(err);
    }
})

The JSON response contains the template name and templateId, either of which can be used when you need to reference the template in other calls.

{
    "name": "RetrieveHistoryPoints",
    "templateId": 12345678
}

You will receive an error if another template already exists with the same template name.

Updating a template

The template string that you pass to the createOrUpdateTemplate method determines whether a template is created or updated. If another template exists with the same name, then that template is updated with the contents that you input. Otherwise, a new template is created.

fs.readFile(templateLocation, function(err, data) {
    if (!err) {
        var template = data;
        tde.createOrUpdateTemplate(template)
            .then(callback).catch(errorHandler).done();
    } else {
        console.log(err);
    }
})

Retrieving a template

The getTemplate method retrieves the template matching the specified template name or templateId.

tde.getTemplate(templateNameOrID).then(callback).catch(errorHandler).done();

The response contains the template content in plain text.

Retrieving all templates

The method listTemplates retrieves all templates for the authenticated user.

tde.listTemplates().then(callback).catch(errorHandler).done();

The response is a JSON Array containing the template names and Ids, which can be used when you need to reference one of the templates in another call.

{  
   "templates":[  
      {  
         "name":"RetrieveHistoryPoints",
         "templateId":12345678
      },
      {  
         "name":"UpdateMarker",
         "templateId":23456789
      }
   ]
}

Deleting a template

When you use the deleteTemplate method, you must provide the name or templateId for the template that you want to delete.

tde.deleteTemplate(templateNameOrID).then(callback).catch(errorHandler).done();

Executing a template

Use the executeTemplate method to run a TDE template to create, retrieve, update, or delete data in a Telogis table. Note that a template must already be defined before you can execute it.

It can take three arguments:

• templateNameOrID - (required) The name or templateId of the template to execute.
• input - (optional) The input data to use when executing the template. Providing input data is only required when you execute Create or Update templates that use input data for the operation.
• qs - (optional) Specify any query string parameters that should be submitted with the request. The parameters must be sent as a JSON object, as shown in the example below.

// Define the input contents as a string either explicitly 
// or read the contents in from the file system using the File System module (fs) or something similar
var input = 'input data';
// An example of query string parameters to submit with the request
var qs = {
    ID: "123654",
    Latitude: "30.39761",
    Longitude: "-97.72958"
};
tde.executeTemplate(templateNameOrID, input, qs)
    .then(callback).catch(errorHandler).done();

When you successfully execute a Retrieve template, then the response contains the data you requested. For example, if your template submitted a request to retrieve Markers in a CSV format, then your response might look something like this:

label,Lat,Lon
Marker 1,30,-97
Marker 2,30,173.000021457673
Marker 4,31,-97.7000002682209

When you successfully execute Create, Update, or Delete templates, the return value indicates the number of failed, created, updated, and deleted changes. It also indicates the Commit mode that the template ran in; when your template sets the Commit entry to false, then your data is only validated when you execute the template.

{  
   "Commit":true,
   "Failed": 0,
   "Created": 3,
   "Deleted": 0,
   "Updated": 0
}

The JSON string may also include items describing specific failures. For example:

{
  "Parse Failed Records": [
    {
      "Reason": "Cannot parse color Blue as it is not formatted as a hexadecimal RGB color",
      "InputRow": 2,
      "Row": "Category 1,Blue",
      "errorInfo": [
        {
          "errorText": "Cannot parse color Blue as it is not formatted as a hexadecimal RGB color",
          "errorCode": "3.1.10"
        }
      ]
    }
  ],
  "Commit": true,
  "Failed": 1,
  "Created": 0,
  "Deleted": 0,
  "Updated": 2
}

See Status codes and responses for more information about template web service calls.

Modifying request properties

The following methods modify the request's properties made to the TDE servers.

setTimeout

(defaults to 1 hour) This method sets the number of milliseconds to wait for the server to send response headers and start the response body before aborting the request. It takes a number as its only parameter.

Note that if the underlying TCP connection cannot be established, then the OS-wide TCP connection timeout overrides the timeout option (the default in Linux can be anywhere from 20-120 seconds).

// Sets the request to timeout after 3 seconds
tde.setTimeout(3000);

usePreview

(defaults to false) This method takes a boolean flag and sets whether the request URL should go to the Live TDE release or to the Preview TDE release.

• true - Sets the request URL to use the Preview release: https://<customer>-preview.api.telogis.com/
• false - Sets the request URL to use the Live release: https://<customer>.api.telogis.com/

tde.usePreview(true);

Response

Possible return status codes are:

• 200 - OK: the template was saved to the server with no errors.
• 400 - Bad Request: the template name was invalid.
• 401 - Authentication error: the user authentication is incorrect or expired.
• 500 - Server error: the server encountered an error while attempting to save the supplied template.

Getting help

If you run into a problem using telogis-tde, open a new issue against the project in GitHub. If you have a general TDE issue, please open a support case by contacting Telogis directly.

For additional information about managing and executing TDE templates and the Core API, see the TDE documentation.

License

telogis-tde is released under the MIT License.