Transformer Implementation Guide (BETA Feature)

Last modified: May 23, 2019 @ 08:31

Prerequisites

Install the following:

  • VSIX Template Package – needed for the Visual Studio template that is used for the implementation of transformers
  • MSI Installation file – needed in order to test the transformer during development, to simulate a transformer that is receiving values. This application can send values to the transformer and ensure the functionality.

Note: Contact Ericsson Operations to obtain the packages mentioned above.

Create a transformer

  1. Start Visual Studio and select Create new project.
  2. Select Visual C# in the project types.
  3. Scroll down and select the Ericsson DDM Template Transformer.
  4. Name the project (complete with namespace) and then Create the project.
    Note: The name of the transformer must end with the word Transformer, for example, TestTransformer.
    Result: Visual Studio creates a new project, which implements the base class for transformers, with stubs of all methods and properties to implement.
  5. Run Update-package –reinstall in the Package Manager console to fetch all necessary dependencies. This command downloads all missing packages from nuget.org.
  6. The project will not compile at this point because the Transformer class, and its TransformerState class, has periods in the name. This is inherited from the full name of the project when it was created. Follow these steps:
  7. Remove the namespace from the class names, keeping only the name of the transformer.
  8. Remove the namespace from the TransformerType attribute decorating the transformer class.
  9. Remove the namespace from the Name property in the transformer class.
  10. Remove the namespace from the transformer state class and its constructor, below the transformer class.
    Result: The transformer should be in a state where it compiles.
  11. Add a display name and a short description to the transformer in the DisplayName and Description attributes decorating the transformer class.

Implementation

ConfigurationDefinitions

This property defines how the transformer will trigger; for example, if it should be triggered by all, any, or a single resource, or if it should be triggered by a timer.

Here is an example of how to set up a configuration that triggers on a single resource:

SourceTypeDefinitions

This property defines the type and number of resources to use as sources for the transformer. Define 1 to N number of resources with a specific data type, or one specific resource URI, such as a specific resource type, within a specific smartobject type.

Here is an example of a SourceTypeDefinition which accepts any number and type of resources:


Here is an example of a SourceTypeDefinition which specifies two specific resource types:

TargetTypeDefinitions

The target is where the output of the transformer is specified. As with SourceTypes, it is possible to specify the type of resource that the transformer should send the output to. The level of specification of the resource filters the list of resource types in the target type selector during transformer creation.
Here is an example of a TargetTypeDefinition which defines an output for the transformer as any resource with the data type “float”:

Reset

This method is called from inside the Reset-method from the DDM platform. Here is a good place to do logic that will reset our transformer, such as reset the latest transformed value:

TransformAsync

This is the method to use for all transformation logic.

We have to work with the following in this method:

ITransformerState

The state injected from the DDM platform, which handles all persistence of the state outside of the transformer. It has a few properties, but the most important is the property Current, where the transformer state is accessed.

The TargetOutputIndexResourceIdDictionary property contains a dictionary of the target output resources.

The ResourceSmartObjectTypeTypeIdDictionary property contains a dictionary of the source resources.

Properties contains a dictionary of the configurations definitions, and what the user has set the configurations to.

GetValues

This is an injected function from the DDM platform which can be selected. If not selected, it will not be executed. If it is executed, it will give the latest value for the specified resource ids. For example, if there are two source resources (A and B), and a value is received from the source A, this function can be called to find out the latest value for the resource B, or vice versa.

Here is an example on how to accomplish this:

It is crucial that we await this (and all async methods) in our Transformer code, and do not use .Result on an async method. Since the Transformer code is executed within Orleans it does not accept .Result, and it will result in the Transformer code timing out and not being responsive.

The IDs of the resources are fetched from the states ResourceSmartObjectTypeTypeIdDictionary property.

GetAggregations

This is an injected function that works the same way as GetValues. This function returns all available resolutions for the specified resource ID. It requires defined resolutions for the specified resource, and enough time for the DDM platform to produce the aggregated resolution value. For instance, if the resolutions setting is 10 minutes, then at least 10 minutes must pass after the first value is received in order for the DDM platform to be able to perform the aggregated value calculation.

TransformerMeasurementMessage

This is the actual incoming value, coming from any of the defined source resources. It contains information such as what kind of data type the value has, the value itself, what time the value came, the resource URI, the resource ID, and the Device´s endpoint.

  • If the value is a number, the value is in the property Value.
  • If the value is a boolean, the value is in the property BooleanValue.
  • If the value is a string, the value is in the property StringValue.

TransformerState

The transformer state class is the place to declare and store all information that must persist in the transformer between the transformations. The DDM platform handles all persistence of the state, so the only thing that needs to be done when implementing a transformer is to declare the properties that should persist, and use them in the logic. The properties cannot be of any complex type, but simple types and structs only.

Debugging

To test the transformer during development, use the MSI-package that installs the TransformerTester. This package makes it possible to launch the tester by running the application while developing the transformer. The TransformerTester runs the transformer, and any/all values are passed to the source resources, showing how the transformer performs. See the Prerequisites section for instructions on how to install this package.

The TransformerTester can also be connected to a real DDM platform device, via SignalR, which means that the transformer, via the TransformerTester, can receive values from the DDM platform directly and perform the transformations on these values in a sandboxed and safe environment.

Connect the TransformerTester to a device

To connect the TransformerTester to the DDM platform, to be able to receive values, enter all the input fields immediately below the activation button like this:

The bearer token is the authentication token used in every request in the platform, when the user has signed in.

  • The URL is the base URL for the current API environment.
  • The DeviceNetwork is the guide for the Device Network the current device is registered to.
  • The ResourceId/ResourceUri fields, are the guides respectively the URI for the specified resource.

It is possible to add more resources to listen to, by clicking the Add Resource button. Finally click Connect to SignalR to set up the connection.