About System Setup Pages

Transcription

1 About System Setup Pages System Pages (Setup Admins Only) Domains Pages Page Views Reports Report Pages A list of churches that are allowed to use this database. Each church will connect via a different URL (ex. my.church.com, churchplant.church.com) A list of tables the Platform will make available for data entry/access. A table can be listed more than once if "filtered" version of the data will be made available to users. A list of every saved advanced search (queries) available on any page in MinistryPlatform. Page viewsare listed here regardless of who created them. A list of each Reporting Services (.rdl) file that can be launched by MinistryPlatform. A security role with rights to the report must be assigned to a user or she cannot see the tool. A list of every page from which a report can be launched. Reports with the word "Selected" in the title may be page/table specific. Though you can enable it on any page, it may not work properly on other pages. Tools Tool Pages Sub Pages Sub Page Views A list of web pages, actually separate web applications, that can be launched from the tools menu in MinistryPlatform. A security role with rights to the tool must be assigned to a user or she cannot see the tool. A list of every page from which a tool can be launched. While it is possible to associate any tool with any page, some tools will only work on pages related to specific tables. A list of every sub page that is accessible from an open page record. Sub pages reveal data in a table that is filtered by a foreign key on the page to which they are assigned. A list of every saved advanced searches (queries) available on any sub page in MinistryPlatform. Sub page views are listed here regardless of who created them. 1

2 Should You Mess With System Setup Pages? Domains Pages Page Views Reports Report Pages Tools Tool Pages Sub Pages Primary System Pages Sub Page Views Leave this page alone. Do not add records or edit the one record you probably see on this page. Feel free to change the default image though :). It'll appear on the login screen. Adding pages, particularly filtered pages, is quite normal. Exercise care as mistakes here can take a particular page offline until fixed. Do not mess with any pages where the Table_Name value starts with "dp_". Page views can be copied or edited. There are many reasons for doing this. Page views can be created manually as well, but it would be much easier to use the "advanced search" feature of the page to do this. Add reports whenever you have developed a report for MinistryPlatform. Think Ministry may add reports during a report or database update. Our professional services team may add a report you commission. When reports are designed, they are usually designed with specific pages in mind. If a report uses a selection to determine the scope of data, that may mean it can only work reliably from some pages. The team at Think Ministry may add a row to this page related to a new core tool in the future. Some of our partners and some of our churches also build their own core tools. Typically values are "scripted" into this page durnig a software deployment or update. When tools are designed, they are usually designed with specific pages in mind. While some tools like the Add/Edit Family Tool work on any page, some tools may lead to errors when deployed from unanticipated pages. Check with support before associating a tool with a page. Adding sub pages is quite normal. Churches may want to create sub pages simply to reveal relationships that already exist in MinistryPlatform. For example, a sub page for background checks could be added to an open contact, participant, or donor record. Sub Page Views can be copied or edited. There are many reasons for doing this. Sub Page Views can be created manually as well, but it would be much easier to use the "advanced search" feature of the sub page to do this. 2

3 Page View Tips & Tricks More on Page Views & Sub Page Views Make The View Visible to All Switch User Owner Add/Edit User Group Copy it and play Open the view, edit it, remove the user and user group, save it. Now everyone can see the page view. If a staff person leaves, you can give all of their views to someone else with the "assign" button. You can edit the user group that can see a view one view at a time or with the "assign" button. Worried you might break a useful view? Copy it and play around a bit with the copy. Copy a useful bit of SQL Are you trying to improve your view with a column or condition present in some other view? Copy the SQL from one view on that page to another. 3

4 System Lookup Pages What are System Lookup pages? They're pages Differences Uses Fairly Static There is not much difference between these pages and other pages. The main thing is we expect these to be mostly the same at all MP churches. Security Roles Ignore These Visible if dp_users.setup Admin = "True" No "Domain_ID" field in the table Primarily for Drop-down Lists that should be largely the same for all MP churches and even for two churches sharing the same MP database (very rare). For the most part, records in these lists don't change much. (ex. Genders Male & Female) Adding/Editing Adding new Lookup Pages is fine. Never delete records in existing lookup pages. Consult support@thinkministry.com before adding or editing values in these pages 4

5 Distinguishing Tables, Pages, Filtered Pages, & Page Views The Table The Page The Filtered Page Page Views Every Row from Every Domain Ex. Contacts Table This is where data lives in the DBMS Domain/Church Specific Rows Default list of columns Ex. Contacts Page Can edit in MP One rule to limit rows returned to users of the page Ex. "Current Contacts" a page that Hides Deceased Contacts Apply additional criteria to filter the rows of the page or filtered page Show Specific Columns Ex. Divorced Women 5

6 Data Security / Business Rules EXTENDING MINISTRYPLATFORM Reasons to Create a Filtered Page Only some staff should see support and recovery groups We want to hide deceased contacts from most users User Context Sally works at our downtown campus Peter only works with small groups Compartmentalization We have 15 campuses. Every main page is filtered dynamically so users only worry about their campus We have 6 Group Types. We have a page per group type so we can better manage them Approaches to Create Filtered Pages Filter the Existing Page Copy the Existing Page Make a Page From Scratch Easiest Option Quick and safer! Main page is intact. Hardest Option Existing Security Role Assignment New Security Role Assignments New Security Role Assignments What if no one can see some rows? Copy Reports & Tools! Associate Reports & Tools NOT BEST PRACTICE Maybe Copy Sub Pages & Page Views New Sub Pages & Page Views 6

7 Filtered Pages Tips & Tricks There are instructions and a video at: Sometimes you can use the view clause of a page view on an existing page as the filter clause for your filtered page. If you want a filtered page to be user aware then your filter clause must contain dp_userid. This value is passed to the filter clause by the application. You can find creative ways to determine what the person who is using the page is allowed to do on the page. Ask yourself the following question about the filtered page: o Am I risking hiding rows from all users? o How confident am I regarding my filter clause? Does it handle all possible data scenarios including null values in non-required fields? o Am I willing to increase the complexity of managing my security roles to give users a more focused page? o Have I considered what reports, tools, page views, and sub-pages the users of this filtered page may need? o How will a new page impact Processes (ex. user creates a record, submits, and someone else gets a task). Getting Help with Filtered Pages Do you need help with filtered pages? a description of your filtered page goal to support@thinkministry.com. Tell us: The existing page name The ministry reason you feel the data should be filtered The rule you believe we should apply to filter the page The name of a user who would use the newly filtered page 7

8 Custom Fields in Ministryplatform 8

9 Plan It Table/Page Name Type/Length Is it Required? Description Vertical Placement Add it Mgmt Studio-->Connect MinistryPlatform-->Tables Table-->Right Click-->Design Add the custom field as the last row in Column Name Save The Table Show it Your user account must be set to "admin=true". Click "About" Click "Refresh Cashe" EXAMPLE SCENARIO: We want to know that every Attribute added to our system is reviewed and approved. We will add _Approved as a read-only, custom bit field to the Attributes page. We will create a process that assigns a get approval task to John Smith each time an attribute is added. When he completes the task the attribute will automatically have the _Approved bit field set to true by the Process record. We will ask Think Ministry to add the field to our database because we are cloud hosted and do not currently have root level access to our SQL Server. We will create the Process in MinistryPlatform ourselves because we know how (or want to learn). 9

10 What Table/Page Will Contain This Custom Field? What record will this data in this field further describe? (Ex. Contacts.Employer_Name) What Will You Name This Custom Field? Proper case, singular, specific (Ex. Contacts.Current_School) As short as possible (Ex. Contacts.Bulk_ _Opt_Out) No spaces or special characters (Ex. Participant_Milestones.Followed_Up) Start with one underscore to make it "read only" in MP to all users. (ex. Events._Web_Approved) Start with two underscores to make it "Hidden" in MP to all users. (ex. Contacts. Age) What Field Type Will You Assign The Custom Field? This decision is critical. It will determine data validation, data formatting, and give the end user the right "pick list" Consult general SQL Server documentation for what each field type means Nvarchar is best for text (supports chinese/spanish character sets) INT is required for Foreign Keys in MP Will End Users Be Required To Add A Value To This Custom Field? In SQL Server "required" is referred to as "Not Nullable". That means that null values are not allowed. MP follows SQL Server. If the field is nullable, it is not required. By default in SQL Server new fields are nullable (not required) and this is best practice for custom fields. WARNING: Do not make custom fields required unless you establish a default value. Applications that insert data into that table will break if you add a reuqired field without a default. What Is The Purpose Or Description Of This Custom Field? Adding an SQL Server Description property to your custom field will introduce help text into MP. Where will you place your field on the page vertically? The default is at the end of the existing list of fields. WARNING: Drag it up or down as needed. Saving a table with re-ordered fields will DROP AND RECREATE the table. 10

11 Warnings, Tips & Tricks For Custom Fields Tip: Integer Foreign keys are needed for drop down lists. Making a custom field into a Foreign Key is not covered here. Foreign Keys are added in Management Studio in the standard manner for an SQL Server relationship. IF you want a drop down of values not already present in MinistryPlatform a custom page may need to be created first. Tip: Bit fields are most commonly added as not nullable with a default value of 0 (aka. False). Tip: There is a special type of bit field called the dp_separator:bit. This field can be added to provide a header/separator between fields on a large form (ex. Events.Public_Website_Settings) Tip: By default, you can t save a table in SQL Server Management Studio s Designer if fields were re-ordered. This is because the table has to be dropped and recreated. This is fairly safe to do, but the more data you have the longer it takes. Go to ToolsOptionsDesigners and uncheck the option titled prevent saving changes that require table recreation. Tip: Computed fields are supported, but should be read-only. So, start their name with an underscore. Contacts. Age is an example. DEVELOPER NOTE: The API does not know new fields exists. A user with admin=true must go to aboutrefreshe cashe. Warning: If you are re-ordering fields on a table always make a backup of the entire database first and do this after hours. Warning: never delete or rename any field. Errors may result unless care is taken to find views, pages, stored procedures & application using that field. Warning: never add or edit a table in your MinistryPlatform database that starts with dp_. Those tables are the guts of MinistryPlatform. Did you know? Every MinistryPlatform church has dozens of custom fields! We add those when we import your data. Most of them are hidden fields that store the foreign identifier from your legacy database. Adding a custom field is so easy that you should always combine this request with some other professional service request. It will take us less than 15 minutes to add a custom field and our minimum professional service charge is one hour. As far as MinistryPlatform (the application) is concerend, all fields are custom fields except those on tables with names that start with dp_. The only exception is the Contacts table. This means you can expect Assign, Export, Advanced Search, Audit Log and Security Roles to treat custom fields just like other fields. Applications like Check-in, Portal, MobileTools, Reports & Core Tools will simply ignore custom fields. NEW in 2016: Default values will appear in new records in MinistryPlatform. 11

12 Text Field Types SQL Server Field Types in MinistryPlatform Money Field Types varchar(n) o If n is 4000 or over = WYSIWYG (HTML Capable) o If n is 256 or less then = small text box nvarchar(n) o If n is 4000 or over = WYSIWYG (HTML Capable) o If n is 256 or less then = small text box char(n) nchar(n) text/ntext o Not recommended, use varchar or nvarchar instead o WYSIWYG (HTML Capable) Date Fields Types date time datetime Numeric Fields Types tinyint smallint real float decimal numeric bigint money smallmoney Special Field Types bit varbinary binary dp_ varchar(255) Custom uniqueidentifier dp_separator:bit Custom, Add a header/separator to the page Foreign Keys (Int) Foreign Keys Store the primary key of a record on another table or even on the same table. Required for drop down lists. Unsupported Field Types image xml sql_variant hierarchyid geometry geography datetime2 datetimeoffset 12

13 Page Views Reports & Tools Custom Pages Contacts) Singular Name Primary Key (Int) Identity 1:1 (Ex. Contact_ID) Domain_ID (int) Not Null The TablePlural Name (Ex. Start_Date & End_Date? FK to a Person? Other fields as needed Selected Record Expression? What is that? Contact_ID_Field can make reports & tools work! The PageStart Simple! A default view can help data entry Administrators) Add New If Needed If new, plan reports & tools needed Security RolesEdit Existing (Ex. Current, Past Records By Type or Status Past N Days? Add/Edit Family Tool Contact Reports: Ex. Directory, Labels, Mail Merge, Call List, etc. Do Do Not Make custom pages Start simple Ask for help Make redundant pages Go too fast Expect 100% success 13

14 Regular Tables To Track Something New EXTENDING MINISTRYPLATFORM Types of Custom Pages Ex. Cemetary_Plot_Assignments Many descriptive fields, Reports & Views & Tools are likely Several MP users will add data We will use Security Roles to manage this page Lookup Value Tables Ex. Cemetary_Plots A foreign key on Cemetary_Plot_Assignment to describe where the plot is located This could change periodically and a few people might need access. We will use security roles to manage this page System Lookup Value Tables Ex. Grave_Marker_Type A foreign key that describes the plot assignment. Changes are rare an Administrator will set it up and may never change it We will not use security roles to manage this Omit Domain_ID from the table / Add to the System Lookups Page Section 14

15 A report is: Where do Reports Come From? A file that ends in.rdl that is deployed onto the Reporting Services instance of your Microsoft SQL Server. Authored in Visual Studio according to MinistryPlatform conventions. Listed by name and location on the Reports page of MinistryPlatform System Setup Associated with specific Pages Assigned to specific Security Roles A report can be: Aware of the page/church/user running it and their rights. Aware of the selection of records or open record about which the user wants to report. Designed to work specifically with one table/page (ex. Donor Statements) Designed to work generically with contact records from any selection on many pages (ex. Labels) What do you need to author reports? Enough knowledge about SQL to query the database Enough knowledge about Visual Studio to author any reporting services report (not just an MP report) A report authoring environment (computer, visual studio) Read-only access to your MinistryPlatform database Are there other ways to report on your data? Export a view to CSV/Excel Self-hosted customers can connect directly via Access/Excel/Tableau API (programmatic) 15

16 Changing Data with Processes & Routines Processes: 1. Can change data on the record when a record is submitted 2. Can change data on the record when a process is complete 3. Can change data as a step in the process 4. Can be created by anyone on any edition through the UI Routines: 1. SQL Server Stored Procedures in the MinistryPlatform database (ex. Service_Data_Quality) 2. Executed by SQL Agent as a job on a schedule (ex. nightly, every 15 minutes) 3. Able to crunch through a lot of data, correct data, log things, send s. 4. Must be created by someone with root access to SQL Server. Learn about Processes at: 16

17 What does a sub-page do? Sub Pages Sub-pages show data that is related to the open record. Are there different types of sub-pages? Yes: Sub-pages can show 4 types of related data: One-to-many: The rows in the sub-page have a foreign key back to the Primary Key of the open record. For example, a contact can have many contact log entries. Therefore, we can make a Contact Log sub-page under an open contact. Many-to-one: The rows in the sub-page share a foreign key that is the same as a foreign key on the open record. For example, a contact is in a particular household and there are other contacts in that household. Therefore, we can have a Primary Family sub-page under an open Contact. Many-to-Many: The rows in the sub-page have a foreign key back to the Primary Key of the open record AS WELL as a foreign key to another primary key on another table. For example a contact can be related to many other contacts in many ways. One person could be both friend and fiancé of another contact. Therefore, the Relationships sub-page under an open Contact can show us all the people to whom the contact is related and all the ways in which they relate. This relationship type reveals the Add button. Recursive: The rows in the sub-page have a foreign key back to the Primary Key of the open record and the rows in the subpage are in the same table as the open record. For example, a group might be the parent group of any number of other groups. Therefore, the sub groups sub page on the group records shows all the child groups or groups where the open record is set as their Parent Group. 17

18 Before you add a sub page Sub Page Tips Generally a sub-page would be based upon a previously existing page which is based on a pre-existing table (create a table and page if needed). Generally a sub page is based upon a pre-existing Foreign Key (add one to the sub-page s table if needed) Sub-page fields are complex. They are described below. Also, tool-tips exist that will allow you to get a description of the field s purpose when you hover of the field name on the form. How to add a sub page: Option 1: Copy an existing sub-page and modify it to suit. Option 2: Create it from scratch Option 3: support@thinkministry.com and ask for help as a professional service. After you add a sub page: Make sure some security role has rights to it. There are some sub-pages that will not appear in security roles. These sub-pages are based upon tables that lack a Domain_ID (int, not null) field which would make these sub-pages visible ONLY to those whose dp_users.setup_admin is set to true. 18

19 19