Arena Dashboard Part 1: Querying Tags & Groups

Transcription

1 Arena Dashboard Part 1: Querying Tags & Groups (Course A20) Presented by: Alex Nicoletti, Arena Product & Implementations Manager And Arnold Wheatley, Shelby Contract Trainer 2017 Shelby Systems, Inc. Other brand and product names are trademarks or registered trademarks of the respective holders.

2 Objective Learn how to query tags and groups in ArenaDB in the context of the hierarchical structures of each. What This Session Covers: How the terminology used in the tables relates to the terminology in the Arena GUI The table structure of core_profile, smgp_group, smgp_group_cluster, smgp_cluster_type, and smgp_category How to use multiple joins or recursive queries to build a hierarchy of tags or groups How to use two provided user defined functions to simplify querying on tag or group hierarchies 2

3 Terminology Cluster: term for any branch of a group tree above the level of an individual group Profile: synonymous with tag Tables Descriptions of the tables used in querying the hierarchies of tags and groups are on the following pages. core_profile: This is the only table needed to generate the hierarchies of tags. All tags can have people associated with them through the core_profile_member table, and all tags can contain other tags. This makes for extremely flexible design, but it makes reporting a challenge because rosters and other reports have to be able to list the names of tag members for any level of the hierarchy, not just the bottom level. smgp_group: This table holds the group information, the lowest level of any group hierarchy. This is the only level to which members can be added. All groups must belong to a group cluster, and each cluster can contain one or more groups. smgp_group_cluster: This table holds the majority of the hierarchy for groups. People cannot be enrolled in any cluster above a group (though a cluster can have an owner ). Clusters can only contain other clusters or groups. smgp_cluster_type: Though not a common reporting requirement, there is a level above the cluster called a cluster type. One cluster type can contain multiple clusters, and each cluster is a member of one and only one cluster type. Typically, the cluster type is ignored because there is typically not more than one cluster type in any group configuration. smgp_category: Even rarer in reporting is the need to report on the cluster type category. Usually Arena instances have only one category configured, so it is unnecessary to report on it. However, if you have sports ministry along with small groups and Sunday school classes, then you may deal with multiple categories. 3

4 core_profile one row per profile type Column Name Data Type Notes profle_id Int primary key; uniquely identifies each tag date_created date_modified created_by modified_by Datetime Datetime profile_type Int 0 = Personal, 1 = Ministry, 2 = Serving, 4 = Event organization_id Int foreign key to orgn_organization department_id Int deprecated parent_profile_id Int recursive key to profile_id; The top tag in a hierarchy has a null for this value. owner_id Int foreign key to core_person profile_name varchar(100) the name of the tag profile_desc varchar(5000) verbose description of the tag function notes varchar(2000) active Bit 1 for active, 0 for inactive display_order Int Use this value to sort the tags in the same way as they appear in the GUI. foreign_key used for imported values to tie to external data source category_level Bit blob_id Int qualifier Int foreign key to core_lookup owner_relationship_strength Int rating of 0 to 5 peer_relationship_strength Int rating of 0 to 5 guid uniqueidentifier campus_id Int foreign key to orgn_campus start_time Datetime stores the default start time end_time Datetime stores the default end time 4

5 smgp_group one row per group Column Name Data Type Notes group_id int primary key; uniquely identifies each group date_created datetime date_modified datetime created_by modified_by group_cluster_id int foreign key to smgp_group_cluster; This is the first rung on the hierarchy. leader_person_id int foreign key to core_person group_name varchar(200) group_url varchar(100) group_desc varchar(1000) group_notes varchar(1000) max_members int topic_luid int foreign key to core_lookup meeting_day_luid int foreign key to core_lookup primary_age_luid int foreign key to core_lookup primary_marital_status int foreign key to core_lookup foreign_key int used for imported values to tie back to the source data target_location_person_id int foreign key to core_person picture_url schedule varchar(200) varchar(1000) group_type_luid int foreign key to core_lookup image_blob_id int foreign key to util_blob guid is_group_private uniqueidentifier bit active bit 1 is active, 0 is inactive twitter_credentials_id int foreign key to secu_credentials flickr_user meeting_start_time meeting_end_time varchar(100) datetime datetime organization_id int foreign key to orgn_organization 5

6 smgp_group_cluster one row per cluster level above the group Column Name Data Type Notes group_cluster_id int primary key; uniquely identifies the cluster level date_created date_modified created_by modified_by datetime datetime organization_id int foreign key to orgn_organization parent_cluster_id int recursive key to group_cluster_id; The top cluster of the hierarchy has a null for this value. leader_person_id int foreign key to core_person admin_person_id int foreign key to core_person cluster_name cluster_url cluster_desc cluster_notes foreign_region_key foreign_subregion_key varchar(100) varchar(100) varchar(1000) varchar(2000) int int cluster_type_id int foreign key to smgp_cluster_type cluster_level int foreign key to smgp_cluster_level image_blob_id int foreign key to util_blob area_id int foreign key to core_area active bit 1 is active, 0 is inactive guid uniqueidentifier foreign_key int used for imported values to tie back to the source data 6

7 smgp_cluster_type one row per type of cluster Column Name Data Type Notes cluster_type_id int primary key; uniquely identifies each type type_name category_id int foreign key to smgp_category allow_registration unassigned_registration_level bit int type_order int used to sort the types in the same manner as they are displayed in the GUI allow_occurrences bit region_name_level int foreign_key int used for imported values to tie back to the source data leader_relationship_strength int peer_relationship_strength int smgp_category one row per category of cluster types Column Name Data Type Notes category_id int primary key; uniquely identifies each category category_name leader_caption parent_caption name_caption url_caption location_target_caption topic_caption meeting_day_caption age_group_caption marital_preference_caption maximum_members_caption picture_caption schedule_caption description_caption 7

8 notes_caption type_caption member_uniform_number bit default_role int foreign key to secu_role uses_area allow_bulk_updates history_is_private credit_as_small_group bit bit bit bit group_page_id int foreign key to port_portal_page cluster_page_id int foreign key to port_portal_page date_created date_modified created_by modified_by meeting_start_time_caption meeting_end_time_caption datetime datetime organization_id int foreign key to orgn_organization foreign_key int used for imported values to tie back to the source data 8

9 Building a Hierarchy with a Fixed Number of Levels If you know the number of levels in the hierarchy of either tags or groups, the best approach is to use a separate JOIN predicate for each level. This also allows you to have a separate column for each level in the hierarchy as well. These examples are based on a three level hierarchy. If you have more levels, it should be easy to extrapolate how to add more levels the examples below. To make it possible to join these values to attendance data, each example has a column for either profile_id or group_id that can be used as the link to join the hierarchy info to the attendance info. Groups with Two Cluster Levels Above (Three Levels Total) level_01_cluster_name = level_01_clusters.cluster_name, level_02_cluster_name = level_02_clusters.cluster_name, level_03_group_name = groups.group_name, group_id = groups.group_id smgp_group as groups inner join smgp_group_cluster as level_02_clusters on groups.group_cluster_id = level_02_clusters.group_cluster_id inner join smgp_group_cluster as level_01_clusters on level_02_clusters.parent_cluster_id = level_01_clusters.group_cluster_id Tags with Three Levels, Enrollment only in Bottom Tag level_01_tag_name = level_01_tags.profile_name, level_02_tag_name = level_02_tags.profile_name, level_03_tag_name = level_03_tags.profile_name, profile_id = level_03_tags.profile_id core_profile as level_01_tags left join core_profile as level_02_tags on level_01_tags.profile_id = level_02_tags.parent_profile_id left join core_profile as level_03_tags on level_02_tags.profile_id = level_03_tags.parent_profile_id where level_01_tags.parent_profile_id is null 9

10 Tags with Three Levels, Enrollment at any Level level_01_tag_name = level_01_tags.profile_name, level_02_tag_name = null, level_03_tag_name = null, profile_id = level_01_tags.profile_id core_profile as level_01_tags where level_01_tags.parent_profile_id is null union all level_01_tag_name = level_01_tags.profile_name, level_02_tag_name = level_02_tags.profile_name, level_03_tag_name = null, profile_id = level_02_tags.profile_id core_profile as level_01_tags inner join core_profile as level_02_tags on level_01_tags.profile_id = level_02_tags.parent_profile_id where level_01_tags.parent_profile_id is null union all level_01_tag_name = level_01_tags.profile_name, level_02_tag_name = level_02_tags.profile_name, level_03_tag_name = level_03_tags.profile_name, profile_id = level_03_tags.profile_id core_profile as level_01_tags inner join core_profile as level_02_tags on level_01_tags.profile_id = level_02_tags.parent_profile_id inner join core_profile as level_03_tags on level_02_tags.profile_id = level_03_tags.parent_profile_id where level_01_tags.parent_profile_id is null 10

11 Building a Tag Hierarchy with a Variable Number of Levels The only way to build a hierarchy with an unknown or variable number of levels is to use a query that can essentially repeat the process of joining one level to the next as many times as it needs to without having to be told up front how many levels there are. A common table expression (CTE) configured as a recursive CTE is the only way to achieve this goal in T SQL. Before we dive into the deep end of the pool with a recursive CTE, look at a basic, non recursive one. The first example below shows a CTE that pulls the top level tags core_profile. In this basic example, some things do not make much sense for just one level of information, but they are quite important in the recursive example. Basic CTE for Top Tags in the Hierarchy (Non Recursive) with tag_hierarchy as ( profile_type, profile_id, profile_name, parent_profile_id, depth = 1, tag_breadcrumb = convert(varchar(8000), profile_name) core_profile as p where p.parent_profile_id is null ) profile_type, profile_id, profile_name, parent_profile_id, depth, tag_breadcrumb tag_hierarchy order by tag_breadcrumb As you can see this example, a CTE is really just a subquery with a name. This simple nonrecursive example is actually redundant. The CTE does not do anything that could not be done more simply as one query rather than as a CTE and a query. However, watch what happens when we add a UNION statement and stack the results of the CTE on top of itself (That is the recursive part.). Suddenly things get a lot more interesting. 11

12 Recursive CTE for Entire Tag Hierarchy with tag_hierarchy as ( profile_type, profile_id, profile_name, parent_profile_id, depth = 1, tag_breadcrumb = convert(varchar(8000), profile_name) core_profile as p where p.parent_profile_id is null union all p.profile_type, p.profile_id, p.profile_name, p.parent_profile_id, depth = t.depth + 1, tag_breadcrumb = convert(varchar(8000), t.tag_breadcrumb + ' - ' + p.profile_name) core_profile as p inner join tag_hierarchy as t on p.parent_profile_id = t.profile_id ) profile_type, profile_id, profile_name, parent_profile_id, depth, tag_breadcrumb tag_hierarchy order by tag_breadcrumb 12

13 Building a Group Hierarchy with a CTE Building a hierarchy for groups is similar to tags, but with the added complexity that the group level is in a separate table the cluster hierarchy structure. Although it could all be done in the CTE, I find that it makes more sense to build the cluster hierarchy in the CTE and then tack on the group level in the query that follows the CTE, as in the example below. A key difference between the results of this group query and the previous example of tags is that the group results are one row per group, not one row per cluster. Recursive CTE for Group Cluster Hierarchy, with Groups Added with cluster_hierarchy as ( group_cluster_id, cluster_name, parent_cluster_id, depth = 1, cluster_breadcrumb = convert(varchar(8000), cluster_name) smgp_group_cluster as c where c.parent_cluster_id is null union all c.group_cluster_id, c.cluster_name, c.parent_cluster_id, depth = h.depth + 1, cluster_breadcrumb = convert(varchar(8000), h.cluster_breadcrumb + ' - ' + c.cluster_name) smgp_group_cluster as c inner join cluster_hierarchy as h on c.parent_cluster_id = h.group_cluster_id ) groups.group_id, groups.group_name, parent_cluster_id = groups.group_cluster_id, depth = cluster_hierarchy.depth + 1, group_breadcumb = cluster_hierarchy.cluster_breadcrumb + ' - ' + groups.group_name smgp_group as groups inner join cluster_hierarchy on groups.group_cluster_id = cluster_hierarchy.group_cluster_id order by group_breadcumb 13

14 Functions to Return Hierarchy Information for Tags and Groups As a shortcut to getting hierarchy data, you can run the following scripts to add two functions to your ArenaDB database. Once added, you can use these functions instead of building hierarchy queries every time you need such data about tags or groups. Tag Hierarchy Function if object_id(n'dbo.funct_tag_hierarchy', 'IF') is not null drop function dbo.funct_tag_hierarchy; go create function dbo.funct_tag_hierarchy (@ProfileID int) returns table as /* START OF HEADER COMMENT SECTION TITLE: funct_tag_hierarchy AUTHOR: Geoff Johnson, DBA / BI Dev. ORIGINAL DATE: 2/25/2015 REVISION HISTORY: None. DESCRIPTION: This table-valued function returns hierarchy information for the specified profile_id value. END OF HEADER COMMENT SECTION */ return (with tag_hierarchy as ( tag_id = profile_id, tag_name = convert(, profile_name), tag_breadcrumb = convert(varchar(max), null), indented_name = convert(varchar(max), profile_name), parent_tag_id = tags.parent_profile_id, tag_id_sequence = convert(varchar(max), tags.parent_profile_id) core_profile as tags where tags.profile_id union all tag_hierarchy.tag_id, tag_name = tag_hierarchy.tag_name, tag_breadcrumb = convert(varchar(max), tags.profile_name + coalesce(' - ' + tag_hierarchy.tag_breadcrumb, '')), indented_name = convert(varchar(max), '- ' + tag_hierarchy.indented_name), parent_tag_id = tags.parent_profile_id, tag_id_sequence = coalesce(convert(varchar(max), tags.parent_profile_id) + ',', '') + tag_hierarchy.tag_id_sequence core_profile as tags inner join tag_hierarchy on tags.profile_id = tag_hierarchy.parent_tag_id ) tag_id, tag_name, indented_name, tag_breadcrumb, tag_id_sequence tag_hierarchy where parent_tag_id is null) 14

15 Group Hierarchy Function if object_id(n'dbo.funct_group_hierarchy', 'IF') is not null drop function dbo.funct_group_hierarchy; go create function dbo.funct_group_hierarchy int) returns table as /* START OF HEADER COMMENT SECTION TITLE: funct_group_hierarchy AUTHOR: Geoff Johnson, DBA / BI Dev. ORIGINAL DATE: 1/13/2015 REVISION HISTORY: None. DESCRIPTION: This table-valued function returns hierarchy information for the specified group_id value. END OF HEADER COMMENT SECTION */ return (with group_hierarchy as ( group_id, group_name = convert(, group_name), cluster_breadcrumb = convert(varchar(max), null), indented_name = convert(varchar(max), group_name), parent_cluster_id = groups.group_cluster_id, cluster_id_sequence = convert(varchar(max), groups.group_cluster_id) smgp_group as groups where groups.group_id union all group_hierarchy.group_id, group_name = group_hierarchy.group_name, cluster_breadcrumb = convert(varchar(max), clusters.cluster_name + coalesce(' - ' + group_hierarchy.cluster_breadcrumb, '')), indented_name = convert(varchar(max), '- ' + group_hierarchy.indented_name), clusters.parent_cluster_id, cluster_id_sequence = coalesce(convert(varchar(max), clusters.parent_cluster_id) + ',', '') + group_hierarchy.cluster_id_sequence smgp_group_cluster as clusters inner join group_hierarchy on clusters.group_cluster_id = group_hierarchy.parent_cluster_id ) group_id, group_name, indented_name, cluster_breadcrumb, cluster_id_sequence group_hierarchy where parent_cluster_id is null) 15

16 Tag Function Usage Example hierarchy.tag_id, hierarchy.tag_name, hierarchy.indented_name, hierarchy.tag_breadcrumb, hierarchy.tag_id_sequence core_profile as tags cross apply funct_tag_hierarchy(tags.profile_id) as hierarchy order by tag_breadcrumb, tag_name Group Function Usage Example hierarchy.group_id, hierarchy.group_name, hierarchy.indented_name, hierarchy.cluster_breadcrumb, hierarchy.cluster_id_sequence smgp_group as groups cross apply funct_group_hierarchy(groups.group_id) as hierarchy order by hierarchy.cluster_breadcrumb, hierarchy.group_name 16

17 Alex Nicoletti Arena Product and Implementations Manager Alex is currently the Arena Product Owner in Shelby's Technology Development Division and is a Certified Scrum Product Owner. Prior to joining the Shelby Team, Alex Nicoletti worked as a Network and Arena Administrator at a large church in Tampa, Florida. The experience he gained during this time helped fuel his passion to empower and equip churches to successfully minister. Arnold Wheatley Shelby Contract Trainer arnold.wheatley@shelbyinc.com After Arnold, an ordained minister, pastored churches in Pennsylvania and Delaware, the Headquarters Office of the PennDel district of the Assemblies of God asked him to establish and direct their IT department. During the last 18 years he has been instrumental in transitioning their headquarters a custom ChMS to Shelby HQ, Arena HQ, and ShelbyNext. Experienced with both church ministries and the unique needs of HQ offices, his desire is to help others configure and use Shelby products more efficiently. Arnold is a Shelby Trainer for all Shelby platforms.