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, 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 and Export to Azure Event Hubs for more details.

InfluxDBSyncWrite

InfluxDBSyncWrite uses influxdb-client-go library to synchronously write EdgeX events to the InfluxDB v2.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}"

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]

ConvertDDATAToEvent

ConvertDDATAToEvent is a proprietary built-in function to convert Sparkplug DDATA messages to Edgex events. This function expects to receive Sparkplug DDATA messages in byte array and will return an error and stop the pipeline if a non-Sparkplug DDATA message is received or if any error occurs during conversion. To use this function, you must specify UseTargetTypeOfByteArray to true and provide three mandatory parameters per your Sparkplug settings: Namespace, GroupId, and EdgeNodeId.

Sample Configuration:

[Writable.Pipeline]
UseTargetTypeOfByteArray = true
  [Writable.Pipeline.Functions.ConvertDDATAToEvent]
    [Writable.Pipeline.Functions.ConvertDDATAToEvent.Parameters]
    Namespace="spBv1.0"
    GroupId="group"
    EdgeNodeId="node"

Compress

Compress is a proprietary built-in function to compress messages. If any error occurs during the compression process, this function will return an error and stop the pipeline. To use this function, you must provide mandatory parameters per your Compress settings: Algorithm, Base64Encode.

Sample Configuration:

[Writable.Pipeline]
  [Writable.Pipeline.Functions.Compress]
    [Writable.Pipeline.Functions.Compress.Parameters]
    Algorithm="zlib"
    Base64Encode="true"

• The Algorithm is a required parameter which indicates the pipeline-function should compress message into the specified format. The available values are gzip and zlib.
• The Base64Encode is an optional parameter which indicates whether the pipeline-function encodes the message from binary data to base64 string after compression. The available values are true and false and the default value is true.

Decompress

Decompress is a proprietary built-in function to decompress the compressed messages. This function expects to receive compressed messages in a byte array and will return an error and stop the pipeline if it receives non-compressed messages or if any error occurs during decompression. To use this function, you must specify UseTargetTypeOfByteArray to true and provide mandatory parameters according to your Decompress settings: Algorithm, Base64Decode.

Sample Configuration:

[Writable.Pipeline]
UseTargetTypeOfByteArray = true
  [Writable.Pipeline.Functions.Decompress]
    [Writable.Pipeline.Functions.Decompress.Parameters]
    Algorithm="zlib"
    Base64Decode="true"

• The Algorithm is a required parameter which indicates the pipeline-function should decompress message compressed in the specified format data. The available values are gzip and zlib.
• The Base64Decode is an optional parameter which indicates whether the pipeline-function decodes the message from base64 string to binary data before decompression. The available values are true and false and the default value is true.

TransformToParquet

TransformToParquet is a proprietary built-in function to transforms EdgeX events to parquet format. This function can only accept an EdgeX event, an array of EdgeX events, or batched EdgeX events; otherwise, an error will be returned and the pipeline will be stopped.

Sample Configuration:

[Writable.Pipeline.Functions.TransformToParquet]

ReadFile

ReadFile is a proprietary built-in function to read file from the specified file path and return the binary data. If any error occurs during the reading process, this function will return an error and stop the pipeline. To use this function, you must provide mandatory parameters per your ReadFile settings: FolderPath, Filename, the pipeline-function will construct the full file path with the FolderPath and Filename and read the file from the filesystem.

Sample Configuration:

[Writable.Pipeline]
  [Writable.Pipeline.Functions.ReadFile]
    [Writable.Pipeline.Functions.ReadFile.Parameters]
    FolderPath="/path/to/folder"
    Filename="test.jpg"

• The FolderPath is a required parameter which indicates the folder path on the filesystem.
• The Filename is a required parameter which indicates the filename.

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]

[Clients.core-metadata]
Protocol = "http"
Host = "localhost"
Port = 59881

-
  name: "Int8"
  isHidden: false
  description: "Generate random int8 value"
  tags:
    manufacturer: "IOTech"
    category: "testing tools"
  properties:
    valueType: "Int8"
    readWrite: "RW"
    defaultValue: "0"

{
    "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]

[Clients.core-metadata]
Protocol = "http"
Host = "localhost"
Port = 59881

{
  "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": "AWS-Home-profile",
  "protocolName": "modbus-tcp",
  "protocols": {
    "modbus-tcp": {
      "Address": "localhost",
      "Port": "502",
      "UnitID": "1"
    }
  }
}

{
  "apiVersion": "v2",
  "id": "c3c8ae98-62b6-4cf1-a86b-51b088fd9189",
  "origin": 1602168089665565200,
  "deviceName": "IOT-Button",
  "profileName": "AWS-Home-profile",
  "sourceName": "FanSpeed",
  "readings": [
    {
      "deviceName": "IOT-Button",
      "id": "7202cc14-c53a-4c40-ad08-7096c075c0f1",
      "modified": 1594975851631,
      "origin": 1602168089665565200,
      "profileName": "AWS-Home-profile",
      "resourceName": "FanSpeed",
      "value": "39",
      "valueType": "Int32"
    }
  ],
  "tags": {
    "network":"us-east-1",
    "site":"factory-001"
  }
}

AddTags

AddTags pipeline function receives an Edgex Event type and adds the collection of specified tags to the Event's Tags collection.

Sample Configuration:

    [Writable.Pipeline.Functions.AddTags]
        [Writable.Pipeline.Functions.AddTags.Parameters]
        tags = "GatewayId:HoustonStore000123,Latitude:29.630771,Longitude:-95.377603"

• The tags is a required string parameter containing comma separated list of tag key/value pairs. The tag key/value pairs are colon seperated.

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]