The Connections WIDGET IS AVAILABLE WITH SMARTSERVER 3.3 AND HIGHER.

This section describes how to add, modify, and delete connection templates using the Connections widget. It also describes the information that appears on the CONNECTION TEMPLATES view. After you create a connection template, you can use the Connections widget to export the connection definitions to file as well as deploy the connections. 

This section consists of the following:

Creating a Connection Template

To create a connection template, follow the steps below:

1. Open the Connections widget. If a connection template has been defined and the Connections widget has been locked, then click the Unlock Operations button () to enable all widget operations.

   
   
   

2. Click the Create Connections Template button ().
   
   
   
   The Create Connection Template view appears.
   
   
   
   
3. Enter the following information for the connection template as needed:
   
   
   • Template Name – (required) defines the connection template name.
     
     
   • Use Presets – sets whether or not to use presets defined in the Datapoint Properties widget.
     
     • Exclusive – indicates to only forward updates with a preset value from a source to the destinations. 
     • Non-exclusive – indicates to forward all updates from a source, with and without preset values, to the destinations. 

     • No – indicates to ignore preset definitions. 

       See also the Using Presets, Localization, and Maps section below for more information.

   • Target Type – sets the connection target type as None, Campus, Campus Area, Building, Floor, Floor Area, or Room. 
     
     
   • Target Name – sets the target name filter that is used to filter the contexts selected by the Target Type. 
     
     
   • Contexts – sets the context filters for the connection template.
   
   
   
   

4. Click NEXT.
   
   The Add Datapoints to Connection Template view appears.

   
   
   

5. To define datapoints, click the Add Datapoint to Connection Template button () for the desired datapoint, or to select multiple datapoints, click the checkmark () next to the desired datapoints (the checkmark changes from blue to yellow), or to select all datapoints, click the Select All button ().

   You can use the Set Filters button () to refine the list of datapoints that appear on the view.

   You can use the Update button () to update the view.

   You can use the button () to hide the detailed properties view.

   
   
   

6. Click the Add Selected Datapoints to the Connection Template button ().
   
   
   
   The datapoint(s) is added to the connection template Details view and appears greyed-out on the Add Datapoints to Connection Template view.
   
   
   
   

7. Click CLOSE on the Add Datapoints to Connection Template view to bring the connection template Details into view.

   For each fixed datapoint, the qualified datapoint instance name is displayed. For each context-relative datapoint, the qualified datapoint XIF name is displayed.

   
   
   

8. Set the Ref Type switch (Fixed or Relative), specifying whether the datapoint member definition is a fixed or context-relative reference. If Fixed is selected, any instance datapoint can be selected. If Relative is selected, any XIF datapoint can be selected. 
   
   
   
   If you change the Ref Type setting from Relative to Fixed, you can set the device as follows:
   
   
   
   
   1. Click the Device field.
      
      
      
      
   2. Select the device from pulldown menu.
      
      
   3. Click SET to define the device for the fixed datapoint.
      
      
9. Set the Direction switch (Source or Destination), specifying whether the datapoint member is a source of updates for the connection, or a destination of any updates received from the source(s) in the connection. Sources can be both input and output datapoints (for external LON peer-to-peer connections, sources are always output datapoints). Destinations are writeable datapoints and typically input datapoints (for BACnet this would be an output datapoint, such as AO, BO, AV, BV). 
   
   
   
   

10. Set the Use Localized Value switch (On or Off), specifying whether or not to apply the localization transformation defined for the datapoint in the Datapoint Properties widget. If the switch is enabled (set to On) and a localization function is not specified, then the datapoint value will be the same as the localized datapoint value. The transformation that is enabled by setting this switch to On and defining a localization transform is mutually exclusive with a transformation specified in the Transform field.
    
    The Use Localized Value switch default setting is On so that the localization transform defined in the Datapoint Properties widget is used, and there is no transformation defined in the Transform field. The Use Localized Value switch will be set to Off and disabled if a transformation is defined in the Transform field.
    
    If you are not using localization settings for the connection template, set Use Localized Value to Off (defaults to on).

    See also the Using Presets, Localization, and Maps section below for more information.

    
    
    

11. If you are defining a transformation for a datapoint in the Transform field, perform the following steps:
    1. Click the Transform field for the datapoint.
       
       
       
       The Edit Transform dialog box appears.
       
       
       
       

    2. Edit the transformation as needed. For a source, the transformation will be applied to the value prior to sending the value to the destinations. For a destination, the transformation will be applied to a received value prior to sending the value to the destination. 
       
       $ represents the input of a source or destination transform and specifies the complete datapoint value. For structured datapoints, like SNVT_switch, specify $.<field name> to access a datapoint field value.
       
       Example:
       
       To access the SNVT_switch state field, specify: $.state
       To access the SNVT_switch value field, specify: $.value
       
       You need to use a transform function in the formula any time the formula uses multiplication, division, addition, subtraction, if-then, math formula, or math function.

       Math functions can be applied to datapoint values, such as limiting the range of the datapoint value

       
       These example formulas can be copied and pasted.

       Function	Function Name	Description	Formula
       min(x,y)	Min	Min is used to limit a maximum value (e.g., to limit a scalar value high value to 100 or lower)	{"transform":"min($, 100)"}
       max(x,y)	Max	Max is used to limit a minimum value (e.g., to positive numbers)	{"transform":"max($, 0)"}
       sqrt(x)	Square Root	Calculates the square root of a value	{"transform":"sqrt($.value)"}

       Example formula to limit a datapoint value to a value between 10 and 100:

       {"transform":"min(max($, 0),100)"}

       Destination map is configured by using preset map or localization

       
       These example formulas can be copied and pasted (always leave destination map blank).

       For the examples below, SNVT_switch is a structured datapoint having a value with two fields (i.e., state and value). 

       Datapoint format	Datapoint type	Direction	Formula	Notes
       Scalar to Scalar	SNVT_count to SNVT_count	Source	{"$": "$"}	Special case where value is not modified (see note 1).
       Scalar to Scalar	SNVT_count to SNVT_count	Source	{"transform":"$ * 2"}	(see note 2)
       Scalar to Scalar	SNVT_count to SNVT_count	Source	{"$": {"transform":"$ * 100"}}	(see note 2)
       Scalar to Structured	SNVT_count to SNVT_switch	Source	{"state":{"transform":"$ ? 1 : 0"},"value":"$"}	Converting Scalar Datapoint to Structure Datapoint (SNVT_switch) (see note 2). The destination state field translation requires logic so you need to use a transform formula  (see note 2). The destination value field uses the complete value of the source datapoint so it does not need to use a transform formula.
       Scalar to Structured	SNVT_count to SNVT_switch	Source	{"state":{"transform":"$ ? 1 : 0"},"value":{"transform":"min(max($, 10), 100)"}}	Converting Scalar Datapoint to Structure Datapoint (SNVT_switch) and limits destination value between 10 - 100. The destination state field translation requires logic so you need to use a transform formula  (see note 2). The destination value field translation requires a math formula so you need to use a transform formula  (see note 2).
       Scalar to Structured	SNVT_count to SNVT_switch	Source	{"state":{"transform":"$ ? 1 : 0"},"value":{"transform":"$ * 5"}}	Converting Scalar Datapoint to Structure Datapoint (SNVT_switch) (see note 2).
       Scalar to Structured	SNVT_count to SNVT_switch	Source	{"state":{"transform":"$ > 5 ? 1 : 0"},"value":{"transform":"$ * 5"}}	State: if source value > 5 then connection value = 1 else connection value = 0.
       Structured to Structured	SNVT_switch to SNVT_switch	Source	{"$": "$"}	Special case where no fields are modified (see note 1).
       Structured to Structured	SNVT_switch to SNVT_switch	Source	{"state":{"transform":"$.state ? 1 : 0"},"value":{"transform":"$.value * 5"}}	Special case using only one unmodified field (see note 1).
       Structured to Scalar	SNVT_switch to SNVT_count	Source	{"$": "$.value"}	Special case using only one field (see note 1).
       Structured to Scalar	SNVT_switch to SNVT count	Source	{"transform":"$.value * 2"}	Uses multiplication, therefore you need to use transform (see note 2).

       Note 1: This formula can only be used if the map formula has no multiplication, division, addition, subtraction, if-then, or math formula.  
       Note 2: Transform function is required when map formula has multiplication, division, addition, subtraction, if-then, or math formula. 

    3. Click UPDATE to save the transformation. (CLEAR removes all transformations and CANCEL closes the Edit Transform dialog box without saving changes.) If a transformation has been added, the Use Localized Value switch changes to Off.
       
       

12. Click SAVE to return to the Connections widget CONNECTION TEMPLATES view, which displays the connection template that was added. (BACK returns you to the connection template Details view.) 
    
    
    
    

13. If you are defining a mapping, perform the following steps:
    

    See also the Using Presets, Localization, and Maps section below for more information.

    1. From the connection template Details view, click the Map field.
       

       
       
       The Edit Map dialog box appears.
       
       
       
       

    2. Enter the mapping details.

       For IMM, LON connections

       For IMM only, and if all connections are only between LON devices, then you must always specify a map formula. If a map formula is not already specified, then you must add a map formula of "{"$":"$"}".

       
       
       

    3. Click UPDATE to save the mapping. 
       
       CLEAR removes mapping and CANCEL closes the Edit Map dialog box without saving changes.
       

If you have completed creating your connection definition and are ready to deploy connections, go to Managing Deployed Connections. If you have completed defining / deploying connection definition, but are not ready to deploy connections, click the Lock Operations button (). Doing so disables the ability to create, edit, delete, deploy connections and shows the locked state ().

Using Presets, Localization, and Map

Both connections and datapoint properties (DLA) files have presets and localization. These files are similar to each other, but not interchangeable. For example, if you want to create a connection definition that limits which datapoint values are sent to the destination using presets, you cannot use a preset defined in the datapoint properties. You must create the preset in the connection template or connection definition.  

Presets and localization can be applied to source and destinations datapoints. You should leave the cell blank in the connection template or connection definition for any rule that is not using preset, localization, or map.

Map, presets, and localization are typically only used if the datapoint type is different. That is, if both the source and destination datapoints are the same datapoint type, then in most cases you would not use map, preset, or localization for the connection rules.   

Map, presets, and localization allow you to create a connection that translates values from one datapoint type to another (e.g., SNVT_switch to SNVT_count), or to manipulate the source or destination values. For example, if the source and destination datapoints are SNVT_count, but the source has a range of -100 to 300 and the destination only allows a range of 0 to 100, you can use map or localization to change the allowed destination range.

The following scenarios are supported:

The order of the transformation for the source datapoint is IAP value → Localization → Presets → Map.

• If the source localization is defined, the datapoint is transformed to a localized value. 
• If the source presets is not NULL, the IAP value (or the local value) is transformed to a preset value.
• If the map is defined, the last transformation value, which could be a preset value, a local value or an IAP value, is transformed according to the map rules.

The reverse transformation order for the destinations datapoint is Presets → Localization → IAP value. Presets (if defined) are specified using the local values. The localization rule must be specified to reverse transform the preset value to the IAP value.

The map is specified in the source and will be applied to the source datapoint for all destinations. Only one map per connection rule ID is supported. Map should be left empty for destinations as it is not supported. Mapping for individual destinations is defined in presets or localization.  

If the datapoint value does not map to any of the presets, then the value is not sent if the onlyPreset property is set to true. Otherwise, the native value will be sent instead. If both transformation map and presets are defined on the source datapoint, then the transformation map is ignored. Only one preset can be defined in the datapoint source. If you have more than one source that has different presets, you have to split it into different connection objects. 

The connection definition has an option to specify whether to skip sending datapoint values if the presetValue is not defined or the source presetValue does not map to any of the destination presets.

Most BACnet and Modbus datapoint types are scalars values (only one number like temperature). LON datapoints can be scalar or structured datapoints. Structured datapoints have fields in which each field represents a value (e.g., SNVT_switch has a state and value fields).

For structured destination datapoints, you need to specify result for all fields. That is, if you have a five field destination, then the formulas you use must specify a destination value that has all five fields.

See also Setting Datapoint Properties for more information about presets and localization settings.

Editing a Connection Template

To edit a connection template, perform the following steps:

1. Open the Connections widget, CONNECTION TEMPLATES tab (default). If the Connections widget has been locked, then click the Unlock Operations button () to enable all widget operations.

   
   
   

2. Use the pulldown menus for Target Type or Use Presets to change the settings as needed.

   If you are NOT using presets

   If you are not using presets settings for the connection template, set Use Presets to No (defaults to Non-Exclusive).

   
   
   
   
   Select the Target Type pulldown setting
   
   
   
   Select the Use Presets pulldown setting
   
   Or, click the Action button () for the connection template and select the Edit action.
   
   
   
   Doing so opens the Edit Connection Template view where you can change the Use Presets or Target Type settings.
   
   
   
   Click SAVE to save edits and return to the CONNECTION TEMPLATES view.
   
   Click CLOSE to cancel edits and return to the CONNECTION TEMPLATES view.
   
   Click NEXT to save edits and continue to the connection template Details view where you can edit connection information and datapoints. 
   
   

3. From the CONNECTION TEMPLATES tab, use the Datapoints buttons to change the datapoint settings as needed:
   1. Details button () opens the connection template Details view for the selected datapoint. 
   2. Add button () opens the connection template Details, which allows you to add datapoints to the connection template. 
   3. Delete button () deletes the selected datapoint from the connection template.
      
      
      
      
4.  If you want to make any mapping changes, go to Defining Mapping.
   
   If you want to deploy your connection definitions, go to Managing Deployed Connections.
   
   If you have completed defining / deploying connection definitions, click the Lock Operations button (). Doing so disables the ability to create, edit, delete, deploy connections and shows the locked state ().

Deleting a Connection Template

To delete a connection template, perform the following steps:

1. Open the Connections widget, CONNECTION TEMPLATES tab (default). If the Connections widget has been locked, then click the Unlock Operations button () to enable all widget operations.

   
   
   

2. Click the Action button () for the connection template you want to delete and select the Delete action.
   
   
   Delete an individual connection template
   
   Or, to delete all connection templates or selected connection templates, click the Action button () and select the Delete All action, or the Delete Selected action if any connection templates are selected.
   
   
   Delete all connection templates
   
   
   Delete selected connection templates
   
   The connection template(s) is deleted from the CONNECTION TEMPLATES display.
   
   

If you do not see the delete changes, then click the Refresh button () to see the updates to the Connections widget.

If you have completed deleting connection templates, click the Lock Operations button (). Doing so disables the ability to create, edit, delete, deploy connections and shows the locked state ().

Viewing Connection Templates

To view connection templates, open the Connections widget. You can use the Set Filters button () to refine the list of connection templates that appear on the view.

The Connections widget opens with the CONNECTION TEMPLATES tab selected by default displaying the following information:

• Name – displays the connection template name.
  
  
• Member Count – shows the number of datapoint members in the connection template.
  
  
• Deployed Connections – defines the number of connections that have been deployed for the connection template (zero if none are deployed).
  
  
• Contexts – lists the context filters that have been defined for the connection template. 
  
  
• Target Type – displays a dropdown menu for selecting a connection target type. The Target Type and Target Name specify the type of context and a context name filter that will be applied to the connections to be created by the connection template. When a connection Target Type exists, the scope of each connection to be created is limited to the scope of the selected target. A connection Target Type and Target Name can greatly reduce the number of contexts you have to apply to a connection. Target Type values include:
  
  • None
  • Campus
  • Campus Area 
  • Building
  • Floor
  • Floor Area
  • Room
    
    

• Target Name – provides a text field for entering a target name filter. The Target Name is used to filter the contexts selected by the Target Type.  
  
  

• Datapoints – lists datapoints for the connection template. The datapoints in a connection template may be on the same device (i.e., turnaround connections), on different devices using the same driver (e.g., all BACnet, all LON, or all Modbus), on different devices using different drivers (e.g., a mix of BACnet, LON, and Modbus devices, or a combination of these). For each fixed datapoint, the qualified datapoint instance name is displayed. For each context-relative datapoint, the qualified datapoint XIF name is displayed. See Expanding / Collapsing the Datapoints View to expand connection templates to show all applied contexts and all datapoint members, or collapse connection templates into a single line each. 
  
  
• Status – shows the connection status for the connection template as follows:
  • Draft – indicates a connection template that has never been deployed, or that has been deployed but all connections were subsequently deleted from the DEPLOYED CONNECTIONS tab. This status is the default state for a new connection template.
  • Pending – indicates that a request to deploy a connection template is still in process for a Draft or Updated connection template followed by a count of the pending connections to be deployed in parentheses (or a — indicator if unknown).
  • Deployed – indicates a Pending connection template that has been successfully deployed to all requested targets. 
  • Updated – indicates a Deployed connection template that has been subsequently modified and has no reported errors.
  • Deleted – indicates a non-Draft connection template that has been subsequently deleted and is not yet deleted from all devices. Once deleted from all devices, the connection template is deleted from the list. (Draft connection templates are immediately deleted from the list.)
  • Error(s) – indicates a connection template that is in an error state. If one error occurred, the status is Error. If multiple errors occurred, the status is Errors followed by a count of the number of errors in parentheses, as well as the ability to display a list of the errors for the connection template. 
    
    
• Use Presets – displays a text field with a dropdown providing the following valid values:

  • Exclusive – indicates to only forward updates with a preset value from a source to the destinations. 

  • Non-exclusive – indicates to forward all updates from a source, with and without preset values, to the destinations. 

  • No – indicates to ignore preset definitions. Recommended when not using presets.
    
    

• Map – displays the mapping function that specifies a transformation to be applied to all source values prior to sending the value to the destinations.  
  
  
• Actions – provides the ability to add, edit, delete, deploy, export a connection template.