Appboard/2.4/builder/associations: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
No edit summary
 
(14 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]]


Line 12: Line 13:
==Creating Associations==
==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 configuring an Association:
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:


[[Image:appboard-2.4-associations.png|frame|Creating an Association Between Two Data Source entities]]
[[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 (i.e. one-to-many) of corresponding entries in the ''sparkline_svc_history'' data source entity. 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, as shown below when previewing a data collection based on this entity:
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.


[[Image:appboard-2.4-associations-preview.png|frame|Previewing data collection with association]]
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:


==Using an Association as a Data Source==
[[Image:appboard-2.4-associations-preview.png|frame|Previewing data collection with one-to-many association (history), and one-to-one association (status_info)]]


After an association is created, there is a new Data Source available, as shown in the following illustration:
==Using One to One Associations==


[[Image:CountyAssociationExample.jpg|thumb|center|500px|Selecting a Data Association as a Widget Data Source]]
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.


Associations are indicated by the -> symbol in an AppBoard drop-down listing of Data Sources.
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:


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.
[[File:appboard-2.4-associations-1to1-usage.png]]


==Using One to Many Associations==


==Using Associations to Filter Data==
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.


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.
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.


The following example uses a different approach to achieve the same result:
Translating the rules into words, the configuration below will:


[[Image:StateAssociationExample.jpg|thumb|center|500px|Using an Association to Launch Contextual Widgets on Another Board]]
* 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).


Two things are observed in the above example:
[[File:appboard-2.4-associations-1tomany-usage.png]]
# 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.
# 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.




==Summary==
==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.


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]].
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.
 
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]].

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"