Skip to content

Built-In Functions Overview

The Edge Xpert Application Service is implemented on the top of EdgeXFoundry Configurable Application Service and supports all the built-in functions as provided by EdgeXFoundry. Edge Xpert also provides additional built-in functions that can be specifed in the functions pipeline. Please refer to the function's detailed documentation by clicking the function name below.

Export

XpertHTTPExport

To send data to HTTP endpoints, Edge Xpert provides a proprietary XpertHTTPExport function, which is similar to HTTPExport of EdgeX Foundry but with additional feature enhancements, such as OAuth2 Client Credentials grant. Please refer to Export to HTTP endpoints for more details.

XpertMQTTExport

To send data to MQTT broker, Edge Xpert provides a proprietary XpertMQTTExport function, which is similar to MQTTExport of EdgeX Foundry but with additional feature enhancements to publish data to various cloud vendors, such as AWS IoT Core, Microsoft Azure, Google Cloud IoT Core, and IBM Waston. Please refer to corresponding examples for more details.

KafkaSend

KafkaSend uses sarama library to act as kafka producer and send EdgeX events to specified kafka topics. Please refer to Export to Kafka for more details.

InfluxDBSyncWrite

InfluxDBSyncWrite uses influxdb-client-go library to synchronously write EdgeX events to the InfluxDB v1.8.x or v2.0.x. Please refer to Export to InfluxDB for more details.

PostgresWrite

PostgresWrite allows users to export EdgeX device readings to Postgres. Please refer to Export to Postgres for more details.

Conversion

JavascriptTransform

JavascriptTransform will execute JavaScript codes as provided by clients against incoming data.

Sample Configuration:

[Writable.Pipeline.Functions.JavascriptTransform]
  [Writable.Pipeline.Functions.JavascriptTransform.Parameters]
  TransformScript = "{Javascript Codes}"
When preparing for the TransformScript, users can expect an embedded JavaScript object inputObject available for representing the data as passed into the JavascriptTransform function, and the execution result must be returned if the result needs to be passed to next function in the pipeline. If any error occurs when running the specified script or if no data is received, the function will return an error and the pipeline will stop. Please refer to Export to HTTP endpoints for the sample usage of JavascriptTransform.

ConvertBoolToIntReading

ConvertBoolToIntReading is a proprietary built-in function to convert readings from Bool value type to Int8 value type. A Bool reading of true will be converted to an Int8 reading of 1 and a Bool reading of false will be converted to an Int8 reading of 0. This function will return an error and stop the pipeline if a non-Edgex event is received or if any error occurs during conversion.

Sample Configuration:

[Writable.Pipeline.Functions.ConvertBoolToIntReading]

ConvertBoolToFloatReading

ConvertBoolToFloatReading is a proprietary built-in function to convert readings from Bool value type to Float32 value type. A Bool reading of true will be converted to a Float32 reading of 1 and a Bool reading of false will be converted to a Float32 reading of 0. This function will return an error and stop the pipeline if a non-Edgex event is received or if any error occurs during conversion.

Sample Configuration:

[Writable.Pipeline.Functions.ConvertBoolToFloatReading]

ConvertIntToFloatReading

ConvertIntToFloatReading is a proprietary built-in function to convert readings from Int8, Int16, Int32, Int64, Uint8, Uint16, Uint32, or Uint64 value type to Float64 value type in E-notation format. This function will return an error and stop the pipeline if a non-Edgex event is received or if any error occurs during conversion.

Sample Configuration:

[Writable.Pipeline.Functions.ConvertIntToFloatReading]

ConvertFloatToIntReading

ConvertFloatToIntReading is a proprietary built-in function to convert readings from Float32 or Float64 value type to Int64 value type. This function will truncate the decimal portion of a float number. This function will return an error and stop the pipeline if a non-Edgex event is received or if any error occurs during conversion.

Sample Configuration:

[Writable.Pipeline.Functions.ConvertFloatToIntReading]

Filter

FilterByValueMaxMin

FilterByValueMaxMin is a proprietary built-in function to remove readings with outlier value that is out of maximum and minimum as defined in device profile. This function only targets on numeric value, for example, Int, Uint, Float, and ignores non-numeric readings. This function will only filter when Maximum/Minimum is defined in the device profile; when only Maximum is defined, compare with Maximum only; when only Minimum is defined, compare with Minimum only; when both Maximum and Minimum are defined, only the readings with numeric values between Maximum and Minimum will be allowed to pass to next function in the pipeline. Please note that the use of this function does not need any parameters. This function will return an error and stop the pipeline if a non-Edgex event is received or if no data is received.

Sample Configuration:

[Writable.Pipeline.Functions.FilterByValueMaxMin]

Core Command

ExecuteCoreCommand

ExecuteCoreCommand parses the incoming JSON data to determine the core command and then issues it through the CommandClient. When configuring functions pipeline, an export function can be set after this function to send the command execution result. Please refer to ExecuteCoreCommand for more details.

Tags

XpertAddTagsFromDeviceResource

XpertAddTagsFromDeviceResource adds the pre-configured tags of device resource to the tag collection of an event. This function does not require any parameters.

Sample Configuration:

[Writable.Pipeline.Functions.XpertAddTagsFromDeviceResource]
To use XpertAddTagsFromDeviceResource in an application service, the connection information of Core MetaData service is required. Add the following [Clients] section into your application service configuration:
[Clients.core-metadata]
Protocol = "http"
Host = "localhost"
Port = 59881
Note that event tags is an optional collection of key/value pairs. The following sample device profile defines a device resource Int8 that contains two tags manufacturer and category:
-
  name: "Int8"
  isHidden: false
  description: "Generate random int8 value"
  tags:
    manufacturer: "IOTech"
    category: "testing tools"
  properties:
    valueType: "Int8"
    readWrite: "RW"
    defaultValue: "0"
After the process of XpertAddTagsFromDeviceResource, the event that contains Int8 reading will be tagged with manufacturer and category as shown below:
{
    "apiVersion": "v2",
    "id": "040bd523-ec33-440d-9d72-e5813a465f37",
    "origin": 1602168089665565200,
    "deviceName": "device-Int8",
    "profileName": "profile-Int8",
    "sourceName": "Int8",
    "readings":
    [
        {
            "deviceName": "device-Int8",
            "id": "31569347-9369-43ec-aa6a-59ea9c624a6f",
            "modified": 1594975851631,
            "origin": 1602168089665565200,
            "profileName": "profile-Int8",
            "resourceName": "Int8",
            "value": "39",
            "valueType": "Int8"
        }
    ],
    "tags":
    {
        "manufacturer":"IOTech",
        "category":"testing tools"
    }
}

XpertAddTagsFromDevice

XpertAddTagsFromDevice adds the pre-configured tags of device to the tag collection of an event. This function does not require any parameters.

Sample Configuration:

[Writable.Pipeline.Functions.XpertAddTagsFromDevice]
To use XpertAddTagsFromDevice in an application service, the connection information of Core MetaData service is required. Add the following [Clients] section into your application service configuration:
[Clients.core-metadata]
Protocol = "http"
Host = "localhost"
Port = 59881
Note that device tags is an optional collection of key/value pairs. The following sample device defines a device instance IOT-Button that contains two tags network and site:
{
  "apiVersion": "v2",
  "name": "IOT-Button",
  "description": "Home automation system",
  "adminState": "UNLOCKED",
  "operatingState": "UP",
  "labels": [
    "home",
    "hvac",
    "thermostat"
  ],
  "location": {
    "lat": 45.45,
    "long": 47.80
  },
  "tags": {
    "network": "us-east-1",
    "site": "factory-001"
  },
  "serviceName": "device-modbus",
  "profileName": "Google-Home-profile",
  "protocolName": "modbus-tcp",
  "protocols": {
    "modbus-tcp": {
      "Address": "localhost",
      "Port": "502",
      "UnitID": "1"
    }
  }
}
After the process of XpertAddTagsFromDevice, the event with specified device IOT-Button will be tagged with network and site as shown below:
{
  "apiVersion": "v2",
  "id": "c3c8ae98-62b6-4cf1-a86b-51b088fd9189",
  "origin": 1602168089665565200,
  "deviceName": "IOT-Button",
  "profileName": "Google-Home-profile",
  "sourceName": "FanSpeed",
  "readings": [
    {
      "deviceName": "IOT-Button",
      "id": "7202cc14-c53a-4c40-ad08-7096c075c0f1",
      "modified": 1594975851631,
      "origin": 1602168089665565200,
      "profileName": "Google-Home-profile",
      "resourceName": "FanSpeed",
      "value": "39",
      "valueType": "Int32"
    }
  ],
  "tags": {
    "network":"us-east-1",
    "site":"factory-001"
  }
}

Others

SetContextVariable

SetContextVariable sets the context variable per specified parameters. The name of context variable will be the value of parameter VariableName, and the value of context variable will be the value extracted from the specified JsonPath of data as passed into the function. Set continueOnError to true if users would like the pipeline to continue even when there is error during SetContextVariable. When continueOnError is true and error occurs during SetContextVariable, the function will return incoming data rather than error. Please note that if incoming data does not contain specified JsonPath, the context variable will be set to empty string "". Please refer to Export to HTTP endpoints for the sample usage of SetContextVariable.

PrintDataToLog

PrintDataToLog prints out the incoming data in the console log for debugging purpose. This function does not require any parameters.

Sample Configuration:

[Writable.Pipeline.Functions.PrintDataToLog]

Back to top