Know How: associate accounts to newsletters

Business

This example proposes inscribe a person, based to its email, to a newsletter.

Concepts

Subscription to a newsletter is usually handled through a contact criterion. If the institution manages many newsletters (for example, newsletters for specific topics), it’ll use so many criteria.

If we want to register a contact and subscribe him to a newsletter, we’ll have to:

• Search if a contact already exists with the given email.
  • If No : create it, and set its authorisation to receive emails from the organization to true.
  • If yes, retrieve its contactNumber
• Then update the contact criterion corresponding to the newsletter (many criteria can be updated at once, if necessary)

Demo method

private void demo() {
    // Initializing the service.
    ContactInformationPublicService service = initService();

    // Generate a sample email, for demonstration purpose.
    String generatedEmail = "example.person" + System.currentTimeMillis() + "@do-not-send.com";

    // Here put the contact criterion id code for your newsletter.
    String criterionCode = "NEWSLET";
    boolean contactSubscribesToNewsletter = true;

    // Here is the code of the authorization that checks if a person accepts to receive emails or not.
    // This code is most the of the time this one.
    String authorizationCode = "CNIL_O";
    boolean contactAcceptsToReceiveEmails = true;

    // Those two calls are not necessary every time, but they guarantee that we are using real and available
    // authorization and criterion codes.
    Assert.isTrue(checkThatAuthorizationCodeExists(service, authorizationCode));
    Assert.isTrue(checkThatCriterionCodeExists(service, criterionCode));

    registerToNewsletter(service, generatedEmail, criterionCode, contactSubscribesToNewsletter, authorizationCode, contactAcceptsToReceiveEmails);
}

Subscribing to newsletter

protected void registerToNewsletter(ContactInformationPublicService service, String contactEmail, String criterionCode,
    boolean contactSubscribesToNewsletter, String authorizationCode, boolean contactAcceptsToReceiveEmails) {

    // Searches if a contact with the given email is already registered in the database.
    ContactTextSearch searchCriteria = new ContactTextSearch();
    searchCriteria.setSearchFields(Collections.singletonList(SearchField.EMAIL));
    searchCriteria.setSearchText(contactEmail);
    ContactSearchResult searchResult =
        service.searchContactByCriteria(null, null, null, null, null, null, searchCriteria, null, true, 0l, 1l);

    final String contactNumber;
    final IndividualContactData individualContactData;
    final List<AuthorizationData> listOfAuthorizationsToUpdate;
    if (searchResult.getContacts() != null && searchResult.getContacts().size() > 0) {
        // A contact with the given email already exists !
        contactNumber = searchResult.getContacts().get(0).getContactNumber();
        individualContactData = null;
        listOfAuthorizationsToUpdate = null; // If the contact already exists, we do not update its authorizations.
    } else {
        // The contact has to be created. We fill the minimal values.
        contactNumber = null;
        individualContactData = new IndividualContactData();
        individualContactData.setEmail(contactEmail);
        individualContactData.setIndividualFirstname("-");
        individualContactData.setIndividualLastname("-");
        individualContactData.setIndividualPreferredLanguage("EN");
        individualContactData.setIndividualTitle("UNDEFINED");
        // Here we set the authorization.
        AuthorizationData authorization = new AuthorizationData();
        authorization.setAuthorizationCode(authorizationCode);
        authorization.setAllowed(contactAcceptsToReceiveEmails);
        listOfAuthorizationsToUpdate = Collections.singletonList(authorization);
    }

    Assert.isTrue(contactNumber != null || individualContactData != null);

    // Here we set the criterion (inscription to newsletter)
    ExternalContactCriterionData criterion = new ExternalContactCriterionData();
    criterion.setCriterionIdCode(criterionCode);
    criterion.setValues(Collections.singletonList("" + contactSubscribesToNewsletter));

    // Contact is created (if necessary), and authorization and criterion are set.

    ContactDataResult saveIndividualResult =
      service.saveIndividualContactData(contactNumber, individualContactData, null, false,
        listOfAuthorizationsToUpdate, false, Collections.singletonList(criterion), false, null, false, null);

    Assert.isTrue(saveIndividualResult.getStatusCode().equals("success"));
}

Checking authorization and criterion

Warning : those methods must NOT be called everytime. They are here to demonstrate how, in development process, it is possible to check the existence of a criterion or an authorization code.

protected boolean checkThatCriterionCodeExists(ContactInformationPublicService service, String criterionCode) {
    ExternalContactCriterionResult availableCriteriaResult = service.getAvailableContactCriteria();

    boolean criteriaCodeExists = false;
    for (ExternalContactCriterionDefinitionData criterionData : availableCriteriaResult
        .getContactCriterionDefinitionDatas()) {
        if (criterionData.getCriterionIdCode().equals(criterionCode)) {
            criteriaCodeExists = true;
            break;
        }
    }
    return criteriaCodeExists;
}

protected boolean checkThatAuthorizationCodeExists(ContactInformationPublicService service, String authorizationCode) {
    AvailableAuthorizationsResult availableAuthorizationResult = service.getAvailableAuthorizations();

    boolean authorizationExists = false;
    for (AuthorizationDefinitionData authorizationData : availableAuthorizationResult
        .getAuthorizationDefinitionData()) {
        if (authorizationData.getAuthorizationCode().equals(authorizationCode)) {
          authorizationExists = true;
          break;
        }
    }
    return authorizationExists;
}