diff --git a/docs/images/dp_settings_individual.png b/docs/images/dp_settings_individual.png new file mode 100644 index 0000000000000000000000000000000000000000..f9e3e7531d0a69239cc90e16f1201e247fa4fe25 Binary files /dev/null and b/docs/images/dp_settings_individual.png differ diff --git a/docs/images/dp_settings_tokesn.png b/docs/images/dp_settings_tokesn.png new file mode 100644 index 0000000000000000000000000000000000000000..85c9a05410e0e93bd8fdf23a0c10d94313a055c5 Binary files /dev/null and b/docs/images/dp_settings_tokesn.png differ diff --git a/docs/images/dps_activityfilter1.png b/docs/images/dps_activityfilter1.png new file mode 100644 index 0000000000000000000000000000000000000000..324cfd915f41e39c34894558da6d5363725b9ade Binary files /dev/null and b/docs/images/dps_activityfilter1.png differ diff --git a/docs/images/dps_activityfilter2.png b/docs/images/dps_activityfilter2.png new file mode 100644 index 0000000000000000000000000000000000000000..9410be0a1fd64dd7ea584ebefea679a7e8bf2ed2 Binary files /dev/null and b/docs/images/dps_activityfilter2.png differ diff --git a/docs/images/dps_activityfilter3.png b/docs/images/dps_activityfilter3.png new file mode 100644 index 0000000000000000000000000000000000000000..dcd688dd0ebb1f3eae1e812ca816dcfea78dbce6 Binary files /dev/null and b/docs/images/dps_activityfilter3.png differ diff --git a/docs/images/dps_tokenfields.png b/docs/images/dps_tokenfields.png new file mode 100644 index 0000000000000000000000000000000000000000..2a958df9c52db1cf361bf29c2e5ab7b968266aec Binary files /dev/null and b/docs/images/dps_tokenfields.png differ diff --git a/docs/images/dps_tokens_output.png b/docs/images/dps_tokens_output.png new file mode 100644 index 0000000000000000000000000000000000000000..d7affb2c3208c4c1d8688d974c5c9e9e08705b74 Binary files /dev/null and b/docs/images/dps_tokens_output.png differ diff --git a/docs/images/dps_tokens_output_search.png b/docs/images/dps_tokens_output_search.png new file mode 100644 index 0000000000000000000000000000000000000000..e5fbb2bc8c472a11115c22eb8a31f3a057bbb8fb Binary files /dev/null and b/docs/images/dps_tokens_output_search.png differ diff --git a/docs/uc-mailtokens.md b/docs/uc-mailtokens.md index ffe869cee369a1f4c94b6af3d208989524785b2a..7f12a72f1e0b4836cc1383e114cd6f4b43b906cb 100755 --- a/docs/uc-mailtokens.md +++ b/docs/uc-mailtokens.md @@ -1,59 +1,68 @@ -# Use Case: Member Organisations presented on website +# Use Case: Create tokens that can be used in mail sent from CiviCRM ## Situation -Many organisations that have organisations as their members, publish their member organisations on their website. Sometimes with limited data such as the name, country and website URL. Others publish full member information, with descriptions and whatever else they collect of their member organistaions. -This use case describes how to create the API with the Data Processor that a website can use to pick up the data from CiviCRM. +When sending mail from CiviCRM, in bulk or individual - manual or automated, organisations usually want to personalise the content of mail (Dear John rather than Dear Sir/Madam) or add specific data from CiviCRM so the mail. This use case is about the need to send an automated appointment reminder to contacts, a day before the appointment. The reminder should contain date and time, with who and where the appointment is. + +Note: by default, CiviCRM has a number of default tokens available. There are also a number of CiviCRM extensions that provide extra tokens. Check those out since they might also provide you with what you need. The advantage here is that you can define any tokens yourself, so that you'll have the non-default tokens all in one place, rather than some default, some from extensions and some from the Data Processor. ## Requirements * CiviCRM installed * The Data Processor Extension installed (https://lab.civicrm.org/extensions/dataprocessor) * The Data Processor Token Output extension installed ( https://lab.civicrm.org/extensions/dataprocessor-token-output) +* Activity type "Appointment" (or any other type you want to use for this goal) -## Setting up the Data Processor for Member publication +## Setting up the Data Processor extra tokens ### Datasources + 1. In CiviCRM go to Administer / DataProcessor / Add DataProcessor -1. Enter basic information on your Data Processor (Name, description) - -1. Add Datasource "Organisation" - no need to add filters -1. Add datasource "Address" - leave default values for filters (primary address is 'yes' - Join type "Select fields to join on - not required" since we may not have address data of this organisation and in that case the organisation would not be shown at all. Join on field "Contact ID" and "Organisation :: Contact ID" - -1. Add Datasource "Website" - leave default values for filters - Joint type "Select fields to join on - not required" and Joint on field "Contact" and "Organisation :: contact ID" - -1. Add Datasource "Membership" - Filter on "Membership Status ID" "is one of" and then pick the statusses you want shown (current, new, pending) on the website - Select Join type should be set to "Select fields to join on" since the organisation must be a member in order to be shown and therefore there must be a membership and Join on Field "Contact ID" and "Organsisation:: Contact ID" - +1. Enter basic information on your Data Processor (Name, description) Note that the Name you give this dataprocessor will be the title of the tokenset such as it appears to users when writing their mail or mail template. + +We will only need two data sources: +1. Add Datasource "Activity" - Filter on Activity Type "Appointment" and Activity Status "Scheduled" and at the bottom of the filters Activity contact :: Record Type ID - is one of - "Activity Assignees" (so that the staff member the appointment is with can be added to the reminder) and Save it + + + +1. Add Datasource "Individual" no need to add filters - Jointype "Select fields to join on" (i.e. there has to be a contact to send it to) and join on fields "Conact ID and "Activity::Activity contact::Contact ID (match to contact)" + Those were the required Datasources. + ### Fields -Now lets go to the fields that are necessary: Organisation Name, Organisation Country of primary address and Organisation Website. We'll also add the Organisation Contact ID so that we can also create an output Search. With it we can quickly check if the output API should work. -1. Add field "Contact ID" - Raw Field Value, i.e. what is written in this field in CiviCRM; -1. Add field "Name" - Raw field Value -1. Add field "Country" - Option Label (the label of the field, i.e. the country name here, rather than the country ID which would just be a number; and the Option from Option Label is because the field "Country" in CiviCRM is an option list, i.e. a list of all countries that you select the country from beloging to this address) -1. Add field "Website" - Raw Field Value +Now lets go to the fields that are necessary: Display Name of the staff member, the location of the appointment and the date and time of the appointment. We'll also add the Activity ID and the Contact ID so that we can also create an output Search. With it we can quickly check if the output Token provides the correct fields/tokens. +1. Add field "Activity ID" - Raw Field Value, i.e. what is written in this field in CiviCRM; +1. Add field "Contact ID )match to contact" - Raw field Value and give it a title. +1. Add field "Individual::Display Name" - Raw Field Value and give it a title. +1. Add field "Location" - Raw Field Value and give it a title. +1. Add field "Activity Date" - Date field value and give it a title. You should now have a list of fields like this: - + Those are the required fields. Since we don't need any sorting or more filters (we've done those on the datasources), we can now continue with the output. -Note: if you want users on the website to be able to sort or filter, add filters here that can then be used by the webdeveloper through the API output we're creating in the next step. -### Output (API) -The output we're creating is an API that can be used by the webdeveloper that is creating the page with the member organisations on it. +Note: the title you give to each field is the name of the token such as it will appear in the tokenlist when writing an email or email template! + + +### Output (Tokens) +The output we're creating is "Tokens" that can be used by any user of this CiviCRM install to add to manual-, automated- or bulkmail. 1. Go to the Output part of the Dataprocessor and choose "Add Output" -1. From the "Select output*" dropdown, select "API" (which will only be available if you have isntalled the The Data Processor Token Output extension ( https://lab.civicrm.org/extensions/dataprocessor-token-output) -1. Enter a name in the API Entity field - keep that simple and do not use spaces in between characters; this is the name the webdeveloper will use to call the API; -1. leave the aPI Action Name and API GetCount Action Name with their default values -1. define the CiviCRM permission that is required to enable the use of this API; teh default value is perfect for this purpose. +1. From the "Select output*" dropdown, select "Tokens" (which will only be available if you have isntalled the The Data Processor Token Output extension ( https://lab.civicrm.org/extensions/dataprocessor-token-output) +1. Define the Contact ID field, i.e. in this situation the contact the mail with these tokens will be sent to: "Activity contact::Contact ID (match to contact)" +1. Hidden fields - select the Activity ID and the Contact ID (match to contact) since we don't need those as tokens (but for searches based on this dataprocessor so as to check that all works as expected) +1. No sorting required 1. Save the Data Processor Output -1. provide the API Enitity field value to the webdeveloper: - + + +Note: once saved, the tokens will be available for selection on the appropriate places when writing emails or email templates. The name of the dataprocessor will also be the name of the tokenset the user gets to see when writing email or emailtemplate. + -Note: your webdeveloper will also need a Sitekey and API key in order to access CiviCRM data in the first place. Find out in CiviCRM manuals how to provide those. ### Output (Search) To make sure that I have defined all properly, I usually also create a Search output so that I can check in CiviCRM that my dataprocessor does what I expect it to do. -1. Add a second output, but this time select "Search/Report" from the Select output dropwdown. +1. Add a second output, but this time select "Activity Search" from the Select output dropwdown. 1. Add the Search form to a Parent menu in CiviCRM 1. Define the permission, the default is perfect. -1. The ID field here would be the Contact ID +1. The ID field here would be the Activity ID 1. Define whether or not you want the ID field hidden 1. Save the form and look for the Search form under the menu you defined in step 2 here. +