Commit 7b936e91 authored by alainb's avatar alainb Committed by eileen
Browse files

Updated search kit documentation with examples

parent 17a2c51d
# External reporting
In this chapter you have found lots of useful explanation about reporting within CiviCRM.
Very useful but with two underlying assumptions:
1. You want to report directly on your "production" CiviCRM database with real-time data
2. You only want to report on data in CiviCRM, not on any data from other applications or combined data from many applications.
There are also lots of possibilities to create reports, dashboard or data transformations outside CiviCRM using tools like Metabase, Tableau, Power BI, RapidMiner, Pentaho to name just a few! There are many tools that can produce reports, overviews, dahsboards etc.
The CiviCRM database is accessible with these kind of tools, either with a direct link to the MySQL or Maria database or potentially with the CiviCRM API.
Explaining how to do this is outside the scope of this document but if you do not have the necessary skills within your organization you can always contact your CiviCRM experts (or whoever supports you with CiviCRM or reporting).
\ No newline at end of file
# Example: Donor Members to Invite
Imagine you have an event, and want to personally invite members who are also major donors but have not attended any of your events yet.
Let's build this search step by step.
## Step 1: Select Current Members
We need to select members. What will be the enitity to select in 'Search for' ?
![First entity](../../img/search-kit/members-to-invite-empty.png)
This choice is important because you cannot change this base entity after you saved your search.
In this example, we have the option to start with Contacts and then link the Memberships, or start with Memberships and then link the Contacts.
Because we ultimately want a list of contacts, let's take Contacts as the base of our search.
Add **Contacts** in 'Search for' with (required) **Memberships**.
We only want to see active members, so we need to filter on the membership status.
Add **Where** 'Status' is one of 'New' and 'Current'.
![Contacts and Memberships and Where](../../img/search-kit/members-to-invite-entities.png)
Fill in a name for the search and click 'Save'.
Feel free to click the 'Search' button to preview the result.
## Step 2: Members Who Never Attended an Event
We want a list of members who never attended an event. This actually means contacts without a participant record.
![Participants](../../img/search-kit/members-to-invite-participants.png)
## Step 3: Donors
We want to filter this list even more, by selecting members who are major donors.
Let's add the link with Contributions, with **Where** 'Financial Type' = 'Donation'.
![Contributions](../../img/search-kit/members-to-invite-contributions.png)
Because a contact can have multiple donations, and we want a contact to be listed only once, we need to **Group By** Contact ID.
![Group By](../../img/search-kit/members-to-invite-group-by.png)
When you use Group By, you have to specify a transformation for fields to combine, count, sum...
In our example, we want to sum the total amount of the contributions for each contact.
So we add the column 'Total Amount' and the field transformation:
![Sum](../../img/search-kit/members-to-invite-sum.png)
## Step 4: Major Donors
If we want to select only donors who donated a certain amount, we can add an extra filter on the sum of the total amount.
Because this is a field with a transformation, we need to use **Having** instead of **Where**.
![Having](../../img/search-kit/members-to-invite-having.png)
## Step 5: Email and Phone Number
We can now add the primary email and phone number.
![Phone and Email](../../img/search-kit/members-to-invite-phone-email.png)
Please note:
* Not everybody has an email address or phone number, that's why we add 'With _(optional)_'.
* On the Contact Summary, you can specify that a contact does not want to be phoned or emailed. We need to take this into account.
The final result might look like this:
![Result](../../img/search-kit/members-to-invite-result.png)
## Step 6: Export as CSV File
The list can now be exported as a csv file and sent to the person who is going to reach out to these donor members:
![Export as CSV](../../img/search-kit/members-to-invite-download.png)
# Case: Creating a public Membership List
There are many use cases where you'd like to show structured data from CiviCRM on a public page of your website. Let's say you are using CiviCRM as a membership organization and you are having several membership levels. Now wouldn't it be nice to have a filterable or searchable list of them with live data from CiviCRM exposed on your website? With the help of Search Kit and Form Builder it is an easy thing to do this. To show how we will create a Logo Grid with tooltips and links to our member's websites that can be filtered by membership types:
![Grid showing filterable Memberships](../../img/search-kit/membership-listing-goal.png)
Let's build this step by step.
## Step 1: Create a New Search and define the Data Sources you need
Go to **Administer > Search > Search Kit** and click **New Search**.
Then:
* fill in the name of the search (e.g. Our Members)
* select 'Memberships' from the **Search for** list
* add one **With** for 'Membership Contact' as we need data from the contact being a member – e.g. the display name to show it in a tooltip
* add a second **With** for 'Contact Websites' as we want to link to the member's homepage
![Search Screen](../../img/search-kit/membership-listing-creating-search.png)
You can always tap **Search** to check the results of your current configuration. Here we have six memberships in total as a result. Note that when adding Membership Contact and Contact Websites Search Kit automatically added some colums with data from these sources:
![Search results](../../img/search-kit/membership-listing-search-results.png)
## Step 2: Add Columns to output additional Data
The columns we see in our search result will be the data we can later use on our public website, too. So we need to add what is missing before we proceed. In our case this is only the URL of the logo:
* tap **+Add** top right of the results table
* choose 'Membership Contact: Image URL'
* again check the results clicking **Search**
This means that in our case we use the standard contact image. You could also use custom fields for that but would have to add another data source then.
Your result will now look like this:
![Search results with one more column](../../img/search-kit/membership-listing-search-results-url.png)
!!! Tip
Don't forget to **Save** your work.
## Step 3: Adding and configuring Grid as Display
To show our search results we now need to add a display. In our case we choose a 'Grid' for that with which we can organize our Output in tiles:
![Adding Grid as Display](../../img/search-kit/membership-listing-add-grid.png)
You could name this view 'Our Members'. By default Search Kit will now add all the fields (columns) of your search as dragable items:
![Adding Grid as Display](../../img/search-kit/membership-listing-grid-items.png)
When you tap **Preview** you will see the output in a 3x3 pattern grid. You will see now that this is not yet the output we want to have there. So now we are going to change this to what you can see on the screenshot below. Take the following steps:
* **Remove** all items not needed (red arrow in screenshot above) – only leave 'Membership Contact: Image URL' there
* Check the **Image checkbox** as we want to show a logo as an image
* optional: set size attributes to make the logo sizes match – here we just adjust the height to 200px
* Check **Link** > select **'Other...'** in dropdown > select 'Membership Contact - Contact Websites: Website' in the **token dropdown** appearing now
* **Attention:** remove the '/civirm' in front of the token: 'civicrm/[Membership_Contact_contact_id_01_Contact_Website_contact_id_01.url]' becomes '[Membership_Contact_contact_id_01_Contact_Website_contact_id_01.url]' only as the token will fill in the absolute url of the member's website
* Check **Tooltip** and also add it using a token representing the display name
When you tap **Refresh** now you should see the logos as we want them to be there:
![changing Grid items and preview](../../img/search-kit/membership-listing-change-grid-items.png)
Note that this configuration will only show members with logos in their data. If you want to output those without, too, you could use the checkbox **Alternative image** in addition.
## Step 4: Adding and configuring a Form
In order to show the results on our public website we need to create an Afform Form now. To do so navigate back to the Search Kit dashboard an tap **Forms > + Create Form for Our Members Grid**:
![adding Form from Search Kit dashboard](../../img/search-kit/membership-listing-add-form.png)
Then:
* Give the Form a name and a description
* enter a URL for the page on which you want your membership grid to be shown – here we use 'civicrm/members':
![configuring new Afform Form](../../img/search-kit/membership-listing-form-created.png)
As soon as you tap 'Save' the link **View Page** will appear. You should now see our grid as we know it.
Let's add a filter to influence which membership types shall be shown to us. To do so switch from 'Form Settings' tab to the tab 'Our Members Grid' and **drag the item 'Membership type' into the tab 'Form Layout'**:
![adding a filter](../../img/search-kit/membership-listing-form-adding-filter.png)
Then:
* change the preset of our filter so that it shows the membership types we want and
* change details in layout – we could add texts etc., here we only change the title of a container element:
![configuring a filter](../../img/search-kit/membership-listing-form-configuring-filter.png)
When you now open the specified URL (your.civicrm.tdl/civicrm/members/) everything looks fine already – unless you're logged out...
## Step 5: Setting Permissions
That brings us to our last step: We need to allow our form to be accessible for anonymous users. To do that you first have to go back to the configuration of the search display and **switch of the Permission handling** there so that it looks like this:
![switching permissions for search display](../../img/search-kit/membership-listing-grid-permissions.png)
Don't forget to **save changes** before you go back to the form configuration.
Now we can define who can view the page showing our grid. In our case we simply need to do two things:
* **remove all restrictions** by choosing 'Generic: Allow all users (including anonymous)' from the dropdown list.
* check **Accessible on front-end of website**:
![switching permissions for search display](../../img/search-kit/membership-listing-form-permissions.png)
Now with the help of Afform logged out users will also be able to load our form and filter them, too.
\ No newline at end of file
# Example: Upcoming Events
The default event overview looks like this:
![Default Magange Events screen](../../img/search-kit/default-manage-events.png)
You can use the Search Kit to create an alternative Manage Event overview screen that might look like this:
![upcoming event](../../img/search-kit/upcoming-events-final.png)
This event overview has the following characteristics:
* one line per upcoming event
* the event title is clickable and leads to 'Info and Settings' of the event
* for each event we see the speakers and hosts
* for each event we see the number of registered/attended participants and the number of cancellations/no-shows
* the numbers are clickable and shows the list of participants with that status
Let's build this step by step.
## Step 1: Create a New Search
Go to **Administer > Search > Search Kit** and click **New Search**.
![New Search empty screen](../../img/search-kit/new-search.png)
Then:
* fill in the name of the search (e.g. Upcoming Events)
* select 'Events' from the **Search for** list
* select only the upcoming events by filling in **Where** Event Start Date >= Now.
![Filled in search screen](../../img/search-kit/upcoming-events-step1.png)
!!! Tip
Don't forget to **Save** your work.
Click **Search** to view the result.
## Step 2: Add Event Columns
By default we see the event ID and event title. We also want to display the event start date.
You can do this by selecting that column from the list on the right-hand side.
![Add Event Start Date](../../img/search-kit/upcoming-events-add-start-date.png)
## Step 3: Add Participant Information
So far, we only have event information. We also want to show the host(s) and speaker(s) of the event. This information comes from the participants.
We will add this entity:
![Add participants](../../img/search-kit/upcoming-events-add-participants.png)
...with a filter on role in **Where**:
![Add where](../../img/search-kit/upcoming-events-add-participants-where.png)
We use 'Contains' because a participant can have multiple roles, and these roles are stored in the participant role field.
The participant role should be either 'Speaker' or 'Host'.
Lastly, we add the entity 'Participant Contact' to be able to show the name of the speakers and hosts.
The search looks like this now:
![Final search](../../img/search-kit/upcoming-events-add-participants-final-search.png)
## Step 4: Grouping on Event ID
If you click the button at the bottom of the page, you will notice that an event is listed multiple times if you have more than one speaker or host. We can avoid this by grouping on event ID.
![Group by event id](../../img/search-kit/upcoming-events-add-participants-group-by.png)
The search will display the speakers and hosts in a comma-separated list thanks to a field transformation:
![List](../../img/search-kit/upcoming-events-add-participants-list.png)
## Step 5: Add the Number of Participants
Our next task is to add the number of participants.
To achieve this we need the field transformation **Count** on the field 'Participant ID'.
But... if we do this right now, we count only the hosts and speakers because of the filter in **Where**.
The trick is to add 'Event Participants' again as an entity:
![Attended participants count](../../img/search-kit/upcoming-events-add-participants-registered.png)
...and even add it one more time to display a count of the no-shows and cancellations:
![Attended participants count](../../img/search-kit/upcoming-events-add-participants-cancelled.png)
Add the columns Participant ID of participant 2 and 3, with the **Count** transformation and **Distinct** checked:
![counts](../../img/search-kit/upcoming-events-add-participants-count-distinct.png)
## Step 6: Change Column Names and Sort Order
To be able to change the column names, we need to create a **Display** as a Table first:
![add display](../../img/search-kit/upcoming-events-add-display.png)
Give the display a name and add a Sort By:
![name and sort order](../../img/search-kit/upcoming-events-display-table.png)
Scroll down and give the columns a meaningful name in the 'Header' fields.
The preview might look like this now:
![preview](../../img/search-kit/upcoming-events-display-table-renamed.png)
## Step 7: Make the Values Clickable
To make the number of participants clickable, we will add a **Link** to their respective overview page.
![links](../../img/search-kit/upcoming-events-display-table-links.png)
The link to enter for the registered/attended count is:
* civicrm/event/search?reset=1&force=1&event=[id]&status=true
The link to enter for the cancelled/no-show count is:
* civicrm/event/search?reset=1&force=1&event=[id]&status=false
If you want, you can add a **Link** for the event title as well:
* civicrm/event/manage/settings?reset=1&action=update&id=[id]
![link event](../../img/search-kit/upcoming-events-display-table-link-event.png)
This will lead to the 'Info and Settings' page of the event.
The final result looks like this:
![upcoming event](../../img/search-kit/upcoming-events-without-form.png)
## Step 8: Add Optional Filtering
We can add a form on top of the upcoming events list for optional filtering.
In the upper right corder of the search, we find a button to do that:
![add form](../../img/search-kit/upcoming-events-add-form.png)
This will bring us to the form builder. Give the form a name and a page link:
![add form name](../../img/search-kit/upcoming-events-form-name.png)
Click on the tab 'Upcoming Events Table' and drag and drop the form elements to the form layout pane:
![add form elements](../../img/search-kit/upcoming-events-add-form-elements.png)
You probably want to add a Container first in order to nicely layout the other form elements.
![add panel](../../img/search-kit/upcoming-events-form-panel.png)
## Step 9: Add the Overview in the Navigation Menu
In the previous step, we specified a page link for our form: **civicrm/upcoming-events**.
We can create a new navigation menu item with this link.
See **Administration > Customize Data and Screens > Navigation Menu**.
![upcoming event](../../img/search-kit/upcoming-events-menu.png)
As a result, your users have a convenient way to access the upcoming events:
![upcoming event](../../img/search-kit/upcoming-events-menu2.png)
This will lead to our finalized search form:
![upcoming event](../../img/search-kit/upcoming-events-final.png)
# Example Soft Credit Search and Display
In this example I am going to create a Soft Credit search and a table display.
!!! Note "A little background on Soft Credits"
Soft Credits in CiviCRM are a way to keep track of someone you should also thank for a contribution other than the donor. For example, if I ask people to donate for my birthday and John Doe contributes 25 euro I can get recognition for that with a soft credit. For more information read the [Soft Credits section](../../contributions/soft-credits.md).
In this search I want to combine data from the contact that has the Soft Credit with data from the contact that actually contributed with data from the contribution. It should show me who my best contribution sollicitors are :-). The outcome will be something like this:\
![Soft Credits Overview](../../img/search-kit/soft-credit-search-result.png)
## Starting from the Saved Searches
First step is to navigate to Search Kit from the Search menu. I will then get a page with saved searches like this:
![Saved Searches page](../../img/search-kit/soft-credit-saved-searches.png)
On this page I get an overview of the existing searches. As you can see my Soft Credit example is already on the list but I am now going to create a new one step by step. First step is to click on the **New Search** button.
## Creating the Search
Once I clicked the **New Search** button I get an empty form where I can create the search:
![Create New Search](../../img/search-kit/soft-credit-empty-new-search.png)
On the left you see a text box with _Untitled Search_, where you can and should enter the name of your search. So I will enter _Soft Credit Example Search_.
Below that name you will see a selection box for _tags_. You can add a tag to a search which will allow you to categorize your searches, for example all Fundraising searches.
Right under that box is an _Add_ selection box, which we will ignore for now but will discuss in the [Adding a display](#adding-a-display) section of this chapter.
The next step is to select the entities that we want data from.
### Selecting entities
At the middle top of the form we can choose what entity to search for. Initially it will have the value _Contacts_:
![Search for entity](../../img/search-kit/soft-credit-entity-start.png)
You can choose what entities you want and the list is quite extensive.
I am initially going to select Contribution Soft Credits entity. This will give me the contact that has the Soft Credit, the ID of the contribution the Soft Credit is linked to, the amount of the Soft Credit (which can be different from the contribution amount) and the type of Soft Credit.
But I also want to include information about the actual contribution and about the contact that made the contribution so I need to add those entities too.
So I will use the box that says _With (optional)_ to specify the additional entities I want. Search Kit will work it out by itself how to link those entities, so it will know it needs to use the contribution ID to link to the Contribution and the contact ID in the contribution to link to Contact.
I can add additional conditions, so in this example I will only want to use the contributions that have the financial type Donation because I do not want to show payments for memberships or events.
There is also a box with _Where_. Here I can add selection criteria for my search. In this case I am only interested in contributions between 1 Jan 2021 and 30 April 2022 so I have entered these criteria.
The complete selection of my entities looks like this:
![Entities](../../img/search-kit/soft-credit-entities.png)
If you are trying this yourself whilst reading the documentation, you will probably notice that there are is also a _Group By_ box.
We are not going to use that in this example. You have the option here to select a field on which the results will be grouped. If for example you would select _Contact Display Name_ here it would group the results for each Soft Credit contact.
In the next step I am going to select the fields I want to see on my search.
### Selecting the fields
At the bottom of the form I can select what fields I am going to show as the result of my search. Initially there will probably just be an ID and sometimes a name selected so it will look like this:
![Initial fields](../../img/search-kit/soft-credit-empty-fields.png)
If I press the _Search_ button above the field names it will actually display the data:
![Initial fields with data](../../img/search-kit/soft-credit-empty-fields-search.png)
Next to the _Search_ button you see an _Action_ box. In this case you can use it to download your search results in a CSV file. This is the standard action with your search, if you want to you can switch it off on your display as I will show later.
On the right side of the form I have a list where I can select fields from the selected entities. I can add those fields to my search:
![Adding fields](../../img/search-kit/soft-credit-add-fields.png)
In my example I am going to remove the Soft Credit ID, keep the name of the Soft Credit contact and add:
* the soft credit amount
* the soft credit type
* the name of the contributing contact
* the contribution total amount
* the contribution date
* the contribution source
* the contribution status
* the contribution payment method
When I have selected them all and pressed _Search_ again my results will be:
![Fields added](../../img/search-kit/soft-credit-fields.png)
In the next step I am going to transform some of those fields.
### Transforming fields
Just below the entities section you see a section with the caption _Field Transformations_. If you open this you will see a list of the fields that are on your search with a box where you can select the transformation for that field.
![Field Transformations](../../img/search-kit/soft-credit-empty-transformations.png)
For each field I can select some transformations. Have a play yourself to check what is going to happen. In this example I am going to make the name of the contribution contact upper case because I want them to stand out. I am also going to select the _date only_ for the contribution receive date as I am not interested in the time.
![My transformations](../../img/search-kit/soft-credit-transformations.png)
If I press on the _Search_ button I can check the results of my transformations:
![Result after transformation](../../img/search-kit/soft-credit-transform-result.png)
### Having a look at the query
Just below the _Field Transformations_ section you will see a section _Query Info_. This section will show information about the technical translation of what we selected as entities and fields. It is very interesting for developers but can be ignored if you are not technically oriented.
In my example it will show this:
```
{
"version": 4,
"select": [
"ContributionSoft_Contribution_contribution_id_01_Contribution_Contact_contact_id_01.display_name",
"amount",
"soft_credit_type_id:label",
"UPPER(ContributionSoft_Contribution_contribution_id_01.contact_id.display_name) AS UPPER_ContributionSoft_Contribution_contribution_id_01_contact_id_display_name",
"ContributionSoft_Contribution_contribution_id_01.total_amount",
"DATE(ContributionSoft_Contribution_contribution_id_01.receive_date) AS DATE_ContributionSoft_Contribution_contribution_id_01_receive_date",
"ContributionSoft_Contribution_contribution_id_01.source",
"ContributionSoft_Contribution_contribution_id_01.contribution_status_id:label",
"ContributionSoft_Contribution_contribution_id_01.payment_instrument_id:label"
],
"orderBy": [],
"where": [
[
"ContributionSoft_Contribution_contribution_id_01.receive_date",
"BETWEEN",
[
"2021-01-01 11:09:00",
"2022-04-30"
]
]
],
"groupBy": [],
"join": [
[
"Contribution AS ContributionSoft_Contribution_contribution_id_01",
"LEFT",
[
"contribution_id",
"=",
"ContributionSoft_Contribution_contribution_id_01.id"
],
[
"ContributionSoft_Contribution_contribution_id_01.financial_type_id:name",
"=",
"\"Donation\""
]
],
[
"Contact AS ContributionSoft_Contribution_contribution_id_01_Contribution_Contact_contact_id_01",
"LEFT",
[
"ContributionSoft_Contribution_contribution_id_01.contact_id",
"=",
"ContributionSoft_Contribution_contribution_id_01_Contribution_Contact_contact_id_01.id"
]
]
],
"having": []
}
```
### View results
During the building of my search and once it his completed I can use the _View Results_ button to see what the results are:
![View results](../../img/search-kit/soft-credit-view-results.png)
## Adding a display
I have specified what I want to search for and what fields I want to see. So now I can add a display which shows my results. That can be added as a CiviCRM menu option. I am going to do that using the select box with the _Add_ caption on the left hand side of the form: