Skip to content
Snippets Groups Projects
Select Git revision
  • 1.113.x
  • main default protected
  • 1.25.x
  • 1.95.x
  • issue_141
  • 132-symfony-component-eventdispatcher-event-is-deprecated-consider-using-civi-core-event
  • 1.56.x
  • 1.46.x
  • 1.24.x
  • issue_114
  • 1.11.x
  • 1.9.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
  • 1.113.1
  • 1.120
  • 1.119
  • 1.118
  • 1.117
  • 1.116
  • 1.25.8
  • 1.25.7
  • 1.25.6
  • 1.115
  • 1.114
  • 1.113
  • 1.112
  • 1.111
  • 1.110
  • 1.109
  • 1.108
  • 1.107
  • 1.106
  • 1.105
36 results
Blame Permalink
how_to_create_search.md 10.26 KiB

How to create a search

In this tutorial we are going to create a search action. We search all people who have an active relationship with a household. We will show the name, email address of the person and we will show the name and address of the household.

We will also add a filter to the search so the user can search on gender and/or birth date.

Our search will look like as follows:

screenshot 12

Create the data processor

Go to Administer --> Data Processor --> Add data processor. Give your data processor an title. You can also add a description, the description is only shown in the manage data processors screen.

screenshot 1

Press Next.

Add the data sources

In the next step we will add the data sources. A data processor has at least one data source. A data source could be CiviCRM entity, such as Individual, Household, Activity, Relationship etc. Or it could be something else, e.g. a CSV file.

Add a data source for the household member

In this tutorial we start with adding the data source for Individual To do so press Add data source

Select as type Individual and give your data source an title. In our example give it the title of Household Member. If you wish you can filter the Individuals, by default only individuals who are alive and not deleted are retrieved.

After you have configured the data source press Save.

This is how our data source should look like:

screenshot 2

Add a data source for the email address of the household member

Now it is time to add a data source to retrieve the email address of the household member. Press Add data source

Select as type Email and give it a title such as Email. Leave the filter criteria to use the primary email address. At the join section we will link this email data source the Household Member data source.

Select at the Select fields to join on (not required) as Join Type. And select Email Contact = Household Member :: Contact ID as join fields.

Press Save.

This is how the email data source should look like:

screenshot 3

What is a join?

A join connects two data sources to each other. In the example above we link the email to the individual. We did this
with the field Email Contact - which is a field on the CiviCRM Email entity which holds the contact id - and we link it the Contact ID of the Household Member.

What does 'Select fields to join on (not required)' mean?

This means that the data processor tries to link an email address to the household member, but what if the household member does not have an email address? The not required means in this case the household member still appears in our data set but with an empty email address.

Add the Relationship data source

In this step we add a data source for the Relationship between the household member and the household. Later on we will add the household data source.

Press Add data source

At type select Relationship. Give it the title Relationship. At Filter criteria select by relationship type Household Member and Head of household and set is active to yes. This means we only want to show activity relationship with a household.

At the join configuration select Select fields to join on and set fields to Contact A = Household member :: Contact ID.

Press Save

This is how the relationship data source should look like:

screenshot 4

Why do we use 'Select fields to join on'?

This join type means that only records who are present in both data sources are retrieved. Meaning that as an Individual does not have an active relationship it will not be present in the data processor.

Add the Household data source

In this step we will add the Household data source. We join this data source to the relationship data source on Contact B of the relationship.

Press Add data source

Select as type Household and give the data source the title Household.

At the join configuration select Select fields to join on and set fields to Contact ID = Relationship :: Contact B.

Press Save

This is how the household data source should look like:

screenshot 5

Add the address data source

The last data source is the address data source and this data source will be joined to the household data source.

Press Add data source

Select as type Address and give the data source the title Address

Select at the Select fields to join on (not required) as Join Type. And select Contact ID = Household :: Contact ID as join fields.

Press Save

The address data source should look like:

screenshot 6

Add the fields

We want to add the following fields:

  • Contact ID of the household member; we need this field so that the user can select the contact to perform actions on it e.g. Send an email or add to an group.
  • Name of the household member
  • Household name
  • Email address of the household member
  • Gender
  • Birth date
  • Address
  • Postal code
  • City

Press Add Field and select Household Member :: Contact ID and give it the title Contact ID. See screenshot below.

screenshot 7

Press Add Field and select Household Member :: Display name and give it the title Name.

Press Add Field and select Household :: Display name and give it the title Household.

Press Add Field and select Email :: Email and give it the title Email address.

Press Add Field and select Household Member :: Gender (Option) and give it the title Gender.

There are two fields for gender one with the addition '(option)' and one without. The first one shows the label of the option the latter the value. E.g. in CiviCRM the value 1 for gender has the value of Female.

Press Add Field and select Household Member :: Birth Date and give it the title Birth Date.

Press Add Field and select Address :: Street Address and give it the title Address.

Street address is the CiviCRM field which holds the full address, e.g. street name plus housenumber.

Press Add Field and select Address :: Postal code and give it the title Postal code.

Press Add Field and select Address :: City and give it the title City.

Now we are finished with defining which fields we want to present to the user.

Add the exposed filters

In this step we add the exposed filters. A filter is something the user can use to refine the search the results. We will add a filter for Gender and for Birth Date. An exposed filter could be required which means that the user first needs to enter a value for the filter before performing the search.

Press Add Filter and select Field Filter as filter type. Give the filter the title Gender and select Household Member :: Gender as field. Press Save

screenshot 8

Press again Add Filter and select Field Filter as filter type. Give the filter the title Birth date and select Household Member :: Birth Date as Field. Press Save

screenshot 9

Add the Contact Search Output

Each data processor have one or more outputs. An output defines how the data processor is accessible. At the moment you can chose between Contact Search, Activity Search, API or CSV Export. In this example we will both use the Contact Search and the CSV Export. The latter will present a button on the search screen to download the search results as a CSV file.

Add the Contact Search form output