Skip to content

Example Soft Credit Search and Display

In this example I am going to create a Soft Credit search and a table display.

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.

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

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

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.

Once I clicked the New Search button I get an empty form where I can create the search:

Create New Search

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

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

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

If I press the Search button above the field names it will actually display the data:

Initial fields with data

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

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

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

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

If I press on the Search button I can check the results of my transformations:

Result after transformation

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

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:

Add display

As you can see there are different types of displays that can be added: * a smart group which will create a smart group of my search results * a table which shows an overview in table form of my results * a list list which will show a (vertical) list of my results * a grid which will show an unformatted grid of my search results

The table option is most common and what I will need in my example. So I am going to select Table and will then see a form like this:

New table

First of all I am going to name my table with results at the top of the form and press Save.

Tip

Do not forget to press Save regularly when building your search or table so you do not lose stuff....

In the section Sort by I can select what fields I want my table sorted by. In this example on Soft Credit contact name, contribution contact name and receive date in descending order:

Sort by

In the section just below that I can specify if I want to allow an actions box on my table, how many results I want to show, the table style, what text to show if I have no results and if the search should be run automatically. In my example I have changed the text for no results and left the rest with default values:

Actions and such

Next I see a list of all the fields that are on my search. I can drag them around and change the order by clicking and holding the handle and moving it around:

Column handle

To remove a column I can click on the remove icon:

Remove column

For each column I can change the heading, change the alignment, if inline-edit is allowed etc.

If I want to I can click on the Add button at the top of the column list. From the list I can add a column that is in my defined search results but not yet on my table. Or add a link, a button, a menu of a bit of custom code. In my example I want to add a little menu that allows: * viewing the soft credit contact * viewing the contribution contact * viewing the contribution

First I have clicked on the Add button and selected the menu option:

Add menu

This will add a new menu column at the bottom of my list. I have edited this menu to look like this:

My menu

If you click on the add within the menu column you will get a few suggestions based on the entities you have selected and luckily they include all the ones I want for this example.

At this point, also changing the headers, I am really content with my table. I click on View Results to see my final table:

Final table

Now I can add a menu option for my table by copying the URL in my browser:

Copy url

and adding it to the CiviCRM menu. I will do this by navigating to Administer>Customize Data and Screens>Navigation Menu and then clicking on the Add Menu Item button:

New menu item

I will enter all the options and add the URL (at least the part starting with civicrm/)

Add menu item