Repository files navigation

A library for populating a CiviCRM site with fake data.

CiviCRM with console access andcv

git clone https://github.com/michaelmcandrew/pop ~/src/popcd popcomposer installexport PATH=$PWD/bin

cd /var/www/example.orgpop basic-10k.yml

Note the usage of a YAML file (basic-10k.yml). This can be a built-in example (basic-250.yml,basic-1k.yml,basic-10k.yml,basic-100k.yml)or a file that you define for yourself.

Pop files are a series of instructions written in yaml. Each instruction createsone or more entities. Some examples will help explain the syntax.

You can use Pop to create 500 Individuals:

-Individual:500

Many instructions can be combined into a single file and will be carried out one after the other:

-Organization:500-Individual:5000-Event:80-MembershipType:5-Membership:500

Pop uses realistic default fields when creating entities and creates realistic 'child entities' when appropriate.

The defaults for each entity are defined in theEntityDefault directory. The defaults for an Individual is as follows:

fields:first_name:f.firstName# a realistic first namelast_name:f.lastName# a realistic first namechildren:  -Address:0-2# creates up to 2 postal addresses  -Email:0-3# creates up to 3 email addresses  -Phone:0-2# creates up to 2 phone numbers

Instead of using the defaults, you can specify the fields you want to create as follows:

-Individual:500fields:job_title:Fundraiser

You can also define child entities. The following example creates 500 donors and creates between 10 and 100 donations.

-Individual:500children:  -Contribution:10-100

Note that the count of entities can be specified as a range with lower and upper limits as in the Contribution example above.

Sometimes it is useful to supply a list of values for a field and have Pop choose one for you each time an entity is created:

-Individual:500fields:job_title:CEO:1# ~ 25 CEOsMembership manager:3# ~ 75 membership managersEvent co-ordinator:6# ~ 150 event co-ordinatorsFundraiser:10# ~ 250 fundraisers

Higher value fields are more likely to be picked.

You can also ask Pop to use theFaker library to generate field values. For example, you can use the Faker jobTitle method as follows:

-Individual:500fields:job_title:f.jobTitle

The syntax for invoking a faker method is 'f.' followed by the method name,followed by any parameters, seperated by commas. Note that a capital F willcause the first letter of the field to be capitalised. Below are some more examples of faker methods:

first_name:f.firstName# a random first nametotal_amount:f.randomFloat,2,1000,2000# an amount between 1000 and 2000receive_date:f.dateTimeBetween,-5 years,now# a date in the last 5 yearsevent_title:F.words,3,1# three wordsdescription:f.paragraph,1# a paragraph

Seehttps://github.com/fzaninotto/Faker for a full list of methods.

Sometimes it is useful to pick a random entity as the field value of another entity. This happens automatically for required fields (for example a Event and a Contact are randomly selected each time a Participant is created). Sometimes it is useful to request a random Entity tag, which you can do as follows:

-EntityTag:1fields:entity_table:civicrm_activitytag_id:r.Activity

Required options are populated automatically. Sometimes, you may want to request that pop chooses a random option from those that are available. To do this, specify choose (only valid for fields that can be passed to [Entity].getoptions API).

-Event:1fields:participant_listing_id:choose

The most common CiviCRM entities are tested to ensure they work with Pop. Other entities may or may not work. The entityProvider function in thePop test suite) tests has the most up to date list of tested entities.

• Support more entities.
• Use twig as templating language for fields (in the same way that ansible uses Jinja)
• Add command to create a single set of entities (easier than reading a pop file), e.g.civipop -e Individual -c 300
• read from stdin
• allow fields to reference each other. So that, for example, email can be set as {$first_name}.{$last_name}@{current_employer}.org
• Asign all created entities to a batch each time pop is run so that they can be easily found and deleted in future.