Advanced parsing methods

Collactr knows multiple built-in advanced parsing methods, which can be used by calling the "parserUtils" module. Down below is a list of the five methods that you can use in a Collactr (pre-)parser.

Make HTTP GET requests

parserUtils.get()

This advanced parsing method allows you to make HTTP GET requests to external resources from within a Collactr (pre-)parser.

Required parameters

This method takes two arguments. The first argument is the URL of the resource you want to make request to. The second argument is a headers object, which is optional.

Name
url
Type
string
Description
The url of the resource that you want to access.

Optional parameters

Name
headers
Type
object
Description
An object that can contain request headers.

Example usage in JavaScript

const headers = {
  Authorization: 'Bearer ' + bearerToken,
}

let response = await parserUtils.get(
  'https://jsonplaceholder.typicode.com/users',
  headers
)

console.log(response.json())

Above is an example of how this method can be used in a Collactr (pre-)parser. This example makes a GET request to an external API, to retrieve a list users. The first argument is the API endpoint. The second is a headers object, which contains an Authorization header, followed by a bearer token.

Make HTTP POST requests

parserUtils.post()

This advanced parsing method allows you to make HTTP POST requests to external resources from within a Collactr (pre-)parser.

Required parameters

This method takes three arguments. The first argument is the URL of the resource you want to make request to. The second argument is a data object. The last argument is a headers object, which is optional.

Name
url
Type
string
Description
The url of the resource that you want to access.
Name
data
Type
object
Description
The data that you want to send to your resource.

Optional parameters

Name
headers
Type
object
Description
An object that can contain request headers.

Example usage in JavaScript

const dataArray = {
  title: 'foo',
  body: 'bar',
  userId: 1,
}

const headers = {
  Content-type: 'application/json; charset=UTF-8'
}

let response = await parserUtils.post(
  'https://jsonplaceholder.typicode.com/posts',
  dataArray,
  headers
)

console.log(response.json())

Above is an example of how this method can be used in a Collactr (pre-)parser. This example makes a POST request to an external API, to create a new post. The first argument is the API endpoint. The second is a data object, which contains the data we want to send. The third argument is a headers object, which contains the content type of the data we are sending.

Add tags to {PRODUCT_NAME} devices

parserUtils.addTag()

This advanced parsing method allows you to add a tag to a device from within a Collactr device definition parser.

Required parameters

This method takes just one argument, which is the tag that you want to add to your device. You don't need to specify a device for this method, as the pre-parser/definition parser automaticaly detects a device based on your payload.

Name
tag
Type
string
Description
The tag that you want to add to a Collactr device.

Example usage in JavaScript

// payloadStr = {
//  'deviceName': 'ExampleDevice1',
//  'tag': '12345'
// }

const decoded = JSON.parse(payloadStr)
const newTag = decoded.tag

parserUtils.addTag(newTag)

Above is an example of how this method can be used in a Collactr device definition parser. This example adds a new tag to your device, which in this example will be dynamically retrieved from the data sent to the parser (payloadStr).

Remove tags to {PRODUCT_NAME} devices

parserUtils.removeTag()

This advanced parsing method allows you to remove a tag from a device from within a Collactr device definition parser.

Required parameters

This method takes just one argument, which is the tag that you want to remove from your device. You don't need to specify a device for this method, as the pre-parser/definition parser automaticaly detects a device based on your payload.

Name
tag
Type
string
Description
The tag that you want to remove from a Collactr device.

Example usage in JavaScript

parserUtils.removeTag('12345')

Above is an example of how this method can be used in a Collactr device definition parser. This example removes a specific tag ("12345") from your device.

Validates tags

parserUtils.isTagValid()

This advanced parsing method allows you verify a tag from within a Collactr device definition parser. The input should always be a string value and must not contain any restricted characters. If this tag is valid/allowed, the method will return a true boolean value. If the tag is not allowed, this method will return a false boolean value.

Required parameters

This method takes just one argument, which is the tag that you want to verify.

Name
tag
Type
string
Description
The tag that you want to remove from a Collactr device.

Example usage in JavaScript

// Example 1 - valid tag
const isThisTagValid = parserUtils.isTagValid('12345')
console.log(isThisTagValid) // this will return 'true'

// Example 2 - invalid tag
const isThisTagValid_2 = parserUtils.isTagValid('@2!_`${4E+="-"')
console.log(isThisTagValid_2) // this will return 'false'

Above is an example of how this method can be used in a Collactr device definition parser. This example validates a tag ("12345"), and shows what happens when you use an invalid tag.