Appboard/2.4/builder/associations: Difference between revisions

imported>Jason.nicholls
No edit summary
imported>Jason.nicholls
No edit summary
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Data Source Associations}}
{{DISPLAYTITLE:Data Source Associations}}
[[Category:AppBoard 2.4]]
[[Image:HeaderFlow01.png]]
[[Image:HeaderFlow01.png]]


Associations are a method of linking AppBoard Data Sources to one another. The concept is similar to creating a Foreign Key in a database table.  Once you establish an Association, you can then use that Association as a Data Source in AppBoard Widgets.
Associations are a method of linking AppBoard Data Source entities to one another. The concept is similar to foreign keys in database tables where the key links rows within one table to one or more rows in another table, or even the same table.


Associations are made on the Server side of AppBoard.  If there are certain relationships that you will always want to enforce among data sources, then it will be more efficient to make Associations than to use [[Action_Apply_a_Filter_to_a_Data_Collection|Client-side filtering]].  So having the proper Associations in place is an important part of maximizing AppBoard's performance.
An advantage of AppBoard providing this mechanism is allowing for associations between ''different'' data sources, so for example, rows within a database query with static information in a CSV file.


__TOC__
Associations can represent a one-to-one mapping or a one-to-many mapping. In cases of one-to-one mappings the fields from the associated data source entity are available for use alongside the fields from the main data source entity.


==Creating an Association==
One-to-many mappings are useful to represent relationships and certain widgets rely on these being configured in order to visualize the data correctly. In particular the Tree Map widget, the Topology widget, and when using Sparkline column renderers with the Table widget.


To create an Association, edit the Data Source for which you want to create the Association.  The Associate screen in the Data Source Wizard will allow you to select the field in each of the two Data Sources that you want to Associate.  The following is an example of configuring an Association:
==Creating Associations==


[[Image:CreatingAnAssociation.jpg|thumb|700px|center|Creating an Association Between Two Data Sources]]
To create an Association, edit the Data Source for which you want to create the Association.  The Associate screen in the Data Source Wizard will allow you to select the field in each of the two Data Sources that you want to Associate. The following is an example of both one-to-many and one-to-one associations:


In the above example, the "sample.USA_States" Data Source is being edited.  The field "StateLabel" in that Data Source is being Associated with the field "StateLabel" in the "sample.USA_Counties" Data Source.
[[Image:appboard-2.4-associations.png|frame|Creating associations]]


In the above example, each entry in the ''sparkline_services'' data source entity has a set of corresponding entries in the ''sparkline_svc_history'' entity, i.e. a one-to-many relationship. The relationship is made by matching the ''Service'' field in both entities. This association is called ''history'' and will appear as an additional field to the ''sparkline_services'' entity.


==Using an Association as a Data Source==
The one-to-one association maps the ''Status'' field to the ''sparkline_statuses'' entity which is a simple lookup providing a name to the numerical ''Status'' value. This association is called ''status_info'' and will also appear as an additional field to the ''sparkline_services'' entity, as shown below:


After an association is created, there is a new Data Source available, as shown in the following illustration:
[[Image:appboard-2.4-associations-preview.png|frame|Previewing data collection with one-to-many association (history), and one-to-one association (status_info)]]


[[Image:CountyAssociationExample.jpg|thumb|center|500px|Selecting a Data Association as a Widget Data Source]]
==Using One to One Associations==


Associations are indicated by the -> symbol in an AppBoard drop-down listing of Data Sources.
When a data collection is based on a data source entity with one-to-one associations then the associated fields are available in most places just as the native fields for that entity, such as widget configuration and color/shape/icon filter rules.


Selecting the "County Table -> USA_Counties" Data Source for a widget will automatically enforce the relationship established in the above Association. In this example, "County Table" is the name of the Board that contains the widget, and "USA_Counties" is the name of the field that was created by the Association in the example illustrated above.
Following from the example above see below the configuration of a table widget and notice the associated fields with the syntax ''association_name.associated_field'', highlighted in the image. In this case we want the ''status_info.Name'' column which maps the numerical status to a string and the result can be seen in the Preview section at the bottom:


[[File:appboard-2.4-associations-1to1-usage.png]]


==Using Associations to Filter Data==
==Using One to Many Associations==


In the article [[Filtering_Collections_Concepts#Using_Actions_To_Filter_and_Collect_Data|Filtering Collections Concepts]], it was illustrated how an action in a Widget can invoke a client-side filter being applied to a Data Collection, which then presented filtered data in a different Widget on a Child Board.
As mentioned in the introduction certain widgets require associations in order to work correctly - for these refer to the specific widget documentation. In general however it's possible to use one-to-many associations in color/shape/icon filter rules.


The following example uses a different approach to achieve the same result:
For example, following on from the previous examples, the configuration below uses the ''history'' one-to-many association to drive a status shape. When specifying a one-to-many association in the rules the field is shown with square brackets to indicate the property is actually an array of values. The comparator will progressively check against each entry in the array until a match is found or move onto the next rule.


[[Image:StateAssociationExample.jpg|thumb|center|500px|Using an Association to Launch Contextual Widgets on Another Board]]
Translating the rules into words, the configuration below will:


Two things are observed in the above example:
* show a red circle if '''any''' values in the ''history[].Availability'' array are less than or equal to 50.
# A special filter did not need to be applied to the "Zip Codes" Data Collection when the action was invoked on the "States Map" widget. The data is filtered automatically by the Association that exists between the "States" and "Zip Codes" Data Sources.
* otherwise show a yellow circle if '''any''' values in the ''history[].Availability'' array are less than or equal to 75.
# In this example, The action in the "States Map" Widget does not need to modify the Data Collection. It simply launches the "Zip Code" Widgets.
* otherwise show a green circle if '''any''' values in the ''history[].Availability'' array are less than or equal to 100.
* otherwise no match (will default to widget default status shape and color).


[[File:appboard-2.4-associations-1tomany-usage.png]]


==Summary==


This article outlined a method for configuring an action to launch a Board with relevant data by pre-configuring a server-side Association among the Data Sources in the current Board and the Child Board. Another way to launch a Board with information associated to a selected item is by applying a client-side filter. For more information about this approach, see [[Action_Apply_a_Filter_to_a_Data_Collection|Action - Apply a Filter to a Data Collection]].
==Handling Updates to Data==
A Widget may have elements that are impacted by a primary data source, as well as one or more associations.  AppBoard checks data sources for updates to determine whether the display needs to be updated to reflect those updates.  Sometimes the primary data will not change, but the data in an associated data source will have changed.  An associated record's most recent update time will override the parent's last update time. This will allow data to be updated in a Widget when the primary data does not change, but the data changes in an associated data set. This only works, however, for the immediate child record, and not for associations that go multiple levels deep.


A common concept in AppBoard is to click on an item in a Widget to request more detailed information about that specific item.  In many cases, this will launch a Child Board with Widgets detailing data for the selected item, as described in this article above.  This concept of digging deeper into the data is called a "Drill-down".  For information about other Drill-down configuration options, see [[Action_Switch_To_A_Board|AppBoard Drill-Downs]].
In cases where a Widget needs to be updated to reflect changes that occur multiple layers down in an Association, a [[appboard/2.4/builder/data_processing_scripts|Data Processing Script]] can be used to touch the records, which will ensure that AppBoard detects the change and updates the display.

Latest revision as of 06:50, 14 December 2013

HeaderFlow01.png

Associations are a method of linking AppBoard Data Source entities to one another. The concept is similar to foreign keys in database tables where the key links rows within one table to one or more rows in another table, or even the same table.

An advantage of AppBoard providing this mechanism is allowing for associations between different data sources, so for example, rows within a database query with static information in a CSV file.

Associations can represent a one-to-one mapping or a one-to-many mapping. In cases of one-to-one mappings the fields from the associated data source entity are available for use alongside the fields from the main data source entity.

One-to-many mappings are useful to represent relationships and certain widgets rely on these being configured in order to visualize the data correctly. In particular the Tree Map widget, the Topology widget, and when using Sparkline column renderers with the Table widget.

Creating Associations

To create an Association, edit the Data Source for which you want to create the Association. The Associate screen in the Data Source Wizard will allow you to select the field in each of the two Data Sources that you want to Associate. The following is an example of both one-to-many and one-to-one associations:

Creating associations

In the above example, each entry in the sparkline_services data source entity has a set of corresponding entries in the sparkline_svc_history entity, i.e. a one-to-many relationship. The relationship is made by matching the Service field in both entities. This association is called history and will appear as an additional field to the sparkline_services entity.

The one-to-one association maps the Status field to the sparkline_statuses entity which is a simple lookup providing a name to the numerical Status value. This association is called status_info and will also appear as an additional field to the sparkline_services entity, as shown below:

Previewing data collection with one-to-many association (history), and one-to-one association (status_info)

Using One to One Associations

When a data collection is based on a data source entity with one-to-one associations then the associated fields are available in most places just as the native fields for that entity, such as widget configuration and color/shape/icon filter rules.

Following from the example above see below the configuration of a table widget and notice the associated fields with the syntax association_name.associated_field, highlighted in the image. In this case we want the status_info.Name column which maps the numerical status to a string and the result can be seen in the Preview section at the bottom:

Appboard-2.4-associations-1to1-usage.png

Using One to Many Associations

As mentioned in the introduction certain widgets require associations in order to work correctly - for these refer to the specific widget documentation. In general however it's possible to use one-to-many associations in color/shape/icon filter rules.

For example, following on from the previous examples, the configuration below uses the history one-to-many association to drive a status shape. When specifying a one-to-many association in the rules the field is shown with square brackets to indicate the property is actually an array of values. The comparator will progressively check against each entry in the array until a match is found or move onto the next rule.

Translating the rules into words, the configuration below will:

  • show a red circle if any values in the history[].Availability array are less than or equal to 50.
  • otherwise show a yellow circle if any values in the history[].Availability array are less than or equal to 75.
  • otherwise show a green circle if any values in the history[].Availability array are less than or equal to 100.
  • otherwise no match (will default to widget default status shape and color).

Appboard-2.4-associations-1tomany-usage.png


Handling Updates to Data

A Widget may have elements that are impacted by a primary data source, as well as one or more associations. AppBoard checks data sources for updates to determine whether the display needs to be updated to reflect those updates. Sometimes the primary data will not change, but the data in an associated data source will have changed. An associated record's most recent update time will override the parent's last update time. This will allow data to be updated in a Widget when the primary data does not change, but the data changes in an associated data set. This only works, however, for the immediate child record, and not for associations that go multiple levels deep.

In cases where a Widget needs to be updated to reflect changes that occur multiple layers down in an Association, a Data Processing Script can be used to touch the records, which will ensure that AppBoard detects the change and updates the display.

Retrieved from "http://ab.edge-technologies.com/docs/index.php?title=Appboard/2.4/builder/associations&oldid=4521"