Interface Inx_Api_TriggerMailing_TriggerMailingManager

Description

The TriggerMailingManager manages all trigger mailings. used to perform the following tasks:

  • Retrieve mailings
  • Create mailings
  • Clone mailings
  • Create a renderer to generate a preview of the mailing
Be aware that this manager is not able to manage normal mailings. Inx_Api_Mailing_MailingManager.

The TriggerMailingManager manages all trigger mailings. The TriggerMailingManager can be used to perform the following tasks:

  • Retrieve mailings
  • Create mailings
  • Clone mailings
  • Create a renderer to generate a preview of the mailing
Be aware that this manager is not able to manage normal mailings. Normal mailings are managed by the Inx_Api_Mailing_MailingManager. <strong>Mailing retrieval</strong>

There are several ways to retrieve trigger mailings. The simplest way is to call selectAll() which will retrieve all trigger mailings. To retrieve a single trigger mailing, use the get(int) method. To retrieve all trigger mailings of a specific list use one of the selectByState(...) methods. Using this type of method gives you the ability to define search filters, like the trigger mailing state. It is also possible to order the result.

The following snippet shows how to retrieve all trigger mailings of a specific list, which are either in the

  1. DRAFT
or the
  1. APPROVAL_REQUESTED
state and print out their names:
 $triggerMailingMgr = $session->getTriggerMailingManager();
 $mailingStateFilter = array( Inx_Api_TriggerMailing_TriggerMailingState::DRAFT(),
      Inx_Api_TriggerMailing_TriggerMailingState::APPROVAL_REQUESTED() );
 $stateFilter = $triggerMailingMgr->createMailingStateFilter( $mailingStateFilter );
 $set = $triggerMailingMgr->selectByState( $listContext, $stateFilter );

 for( $i = 0; $i < $set->size(); $i++ )
 {
      $tm = $set->get( $i );
      echo $tm->getName() . '<br>';
 }

 $set->close();
To retrieve all mailings of a specific list, disregarding their state, use the all matching state filter which can be created using the createAllMatchingStateFilter() method. This filter produces the same result as a state filter with all states.

If needed, it is possible to create much more complex select statements than the one above. This can be accomplished using filter expressions. The following snippet extends the previous select statement with a filter that restricts the result to mailings which were modified during the last hour. The result is also ordered by the mailing name:

 $triggerMailingMgr = $session->getTriggerMailingManager();

 $filterDate = date('d.m.Y H:i:s', strtotime('-1 hour'));
 $filter = 'Attribute(' . Inx_Api_TriggerMailing_TriggerMailingAttribute::MODIFICATION_DATETIME()->getId()
      . ') > #' . $filterDate . '#';

 $mailingStateFilter = array( Inx_Api_TriggerMailing_TriggerMailingState::DRAFT(),
      Inx_Api_TriggerMailing_TriggerMailingState::APPROVAL_REQUESTED() );
 $stateFilter = $triggerMailingMgr->createMailingStateFilter( $mailingStateFilter );

 $set = $triggerMailingMgr->selectByState( $listContext, $stateFilter,
      Inx_Api_TriggerMailing_TriggerMailingAttribute::NAME(), Inx_Api_Order::ASC, $filter );

 for( $i = 0; $i < $set->size(); $i++ )
 {
      $tm = $set->get( $i );
      echo $tm->getName() . '<br>';
 }

 $set->close();

<strong>Mailing creation and editing</strong>

Creating a trigger mailing can be a bit tricky as there are many settings needed to set up a trigger descriptor. There are several builders which will help you with creating a valid trigger descriptor. The following snippet exemplary shows how to create an anniversary trigger mailing:

 $optInDate = $session->createRecipientContext()->getMetaData()->getSubscriptionAttribute(
      $listContext )->getId();
 $startDate = date('c');
 $sendingTime = date('c', mktime(12, 30));

 $triggerMailingMgr = $session->getTriggerMailingManager();
 $descriptor = $triggerMailingMgr->getTriggerDescriptorBuilderFactory()
      ->createAnniversaryTriggerDescriptorBuilder()->startDate( $startDate )->sendingTime( $sendingTime )
      ->attribute( $optInDate )->columnModificator(
              new Inx_Api_TriggerMailing_Descriptor_TimeTriggerOffset(
                      Inx_Api_TriggerMailing_Descriptor_TimeTriggerOffsetType::WAS_AGO(),
                      Inx_Api_TriggerMailing_Descriptor_TimeTriggerUnit::YEAR(), 1 ) )->build();

 $mailing = $triggerMailingMgr->createTriggerMailing( $listContext, $descriptor );
 $mailing->updateName( 'One year anniversary' );
 $mailing->updateSubject( "Thank's for staying with us!" );
 $mailing->commitUpdate();
The created anniversary mailing will be sent to recipients that have been member of the specified list for one year. The descriptor in this example is set up with minimal information. If you wish to, you can configure even more aspects of the trigger. You could, for example, add commands to set recipient attributes along with sending the mailing. The available options vary from builder to builder, documented for each builder interface, including information on which settings are mandatory and which are optional.

<strong>Note:</strong> For existing trigger mailings, always call lock() before updating it, and unlock() after committing changes!

The following snippet shows how to edit an existing trigger mailing:

 $triggerMailingMgr = $session->getTriggerMailingManager();
 $mailing = $triggerMailingMgr->get( $iMailingId );

 try
 {
      $mailing->lock();
      $mailing->updateSubject( 'New Subject' );
      $mailing->commitUpdate();
      $mailing->unlock();
 }
 catch( Inx_Api_LockException $x )
 {
      // someone else has locked this mailing
 }

It is not necessary to repeatedly create almost identical mailings. This can be accomplished a lot easier using the clone() method.

The following snippet shows how to clone a mailing and put the clone in the specified list:

 $triggerMailingMgr = $session->getTriggerMailingManager();
 $triggerMailingMgr->cloneMailing( $iMailingId, $listContext );

<strong>Preview generation</strong>

To create a preview of a trigger mailing, an Inx_Api_TriggerMail_TriggerMailingRenderer is needed. A renderer can be obtained using the createRenderer() method.

The following snippet shows how to create a TriggerMailingRenderer and generate a preview of the trigger mailing:

 $triggerMailingMgr = $session->getTriggerMailingManager();
 $renderer = $triggerMailingMgr->createRenderer();
 $renderer->parse( $iMailingId, Inx_Api_TriggerMail_BuildMode::PREVIEW() );
 $preview = $renderer->build( $iRecipientId );

 echo $preview->getHtmlText() . '
';

For more information on TriggerMailings, see the Inx_Api_TriggerMailing_TriggerMailing documentation.

Note: To use trigger mailings, the following API user right is required: Inx_Api_UserRights::MAILING_FEATURE_USE

  • author: chge, 12.07.2012
  • version: $Revision: 9497 $ $Date: 2007-12-19 17:03:25 +0200 (Tr, 19 Grd 2007) $ $Author: aurimas $
  • see: Inx_Api_TriggerMailing_TriggerMailing
  • since: API 1.10.0

Located in /Api/TriggerMailing/TriggerMailingManager.php (line 166)

Inx_Api_BOManager
   |
   --Inx_Api_TriggerMailing_TriggerMailingManager
Method Summary
Methods
cloneMailing (line 262)

Copies a TriggerMailing to the specified list.

Copies a TriggerMailing to the specified list.

  • return: the new TriggerMailing which is a clone of the specified TriggerMailing.
  • throws: Inx_Api_DataException if the trigger mailing does not exist or can not be copied. See the exception reason for detailed information.
  • access: public
Inx_Api_TriggerMailing_TriggerMailing cloneMailing (int $iMailingId, Inx_Api_List_ListContext $lc)
  • int $iMailingId: the id of the trigger mailing to be cloned.
  • Inx_Api_List_ListContext $lc: the list to which the trigger mailing should be cloned.
createAllMatchingStateFilter (line 311)

Returns a Inx_Api_TriggerMailing_StateFilter which matches any mailing and trigger state.

Returns a Inx_Api_TriggerMailing_StateFilter which matches any mailing and trigger state. Note: This StateFilter is a singleton.

  • return: a StateFilter which matches any mailing and trigger state.
  • access: public
Inx_Api_TriggerMailing_StateFilter createAllMatchingStateFilter ()
createMailingStateFilter (line 280)

Creates a new Inx_Api_TriggerMailing_StateFilter which matches all of the given mailing states and any trigger state.

Creates a new Inx_Api_TriggerMailing_StateFilter which matches all of the given mailing states and any trigger state. The easiest way to create the array is to use the array() method. The following example demonstrates how to create a set of two mailing states:

 $stateFilter = array( Inx_Api_TriggerMailing_TriggerMailingState::DRAFT(),
      Inx_Api_TriggerMailing_TriggerMailingState::APPROVAL_REQUESTED() );

  • return: a new StateFilter matching the given mailing states.
  • access: public
Inx_Api_TriggerMailing_StateFilter createMailingStateFilter ([ $stateFilter = null])
  • array $stateFilter: a set of mailing states the filter shall match.
createRenderer (line 240)

Creates a new Inx_Api_TriggerMail_TriggerMailingRenderer which can be used to render a TriggerMailing.

Creates a new Inx_Api_TriggerMail_TriggerMailingRenderer which can be used to render a TriggerMailing.

  • return: a new TriggerMailingRenderer.
  • access: public
createRendererForTestrecipient (line 249)

Creates a new Inx_Api_TriggerMail_TriggerMailingRenderer which can be used to render a TriggerMailing personalized with a test recipient instead of an ordinary recipient.

Creates a new Inx_Api_TriggerMail_TriggerMailingRenderer which can be used to render a TriggerMailing personalized with a test recipient instead of an ordinary recipient.

  • return: a new TriggerMailingRenderer for test recipients.
  • access: public
Inx_Api_TriggerMail_TriggerMailingRenderer createRendererForTestrecipient ()
createStateFilter (line 300)

Creates a new Inx_Api_TriggerMailing_StateFilter which matches all of the given mailing states AND the given trigger state.

Creates a new Inx_Api_TriggerMailing_StateFilter which matches all of the given mailing states AND the given trigger state. Both filters must be matched.

  • return: a new StateFilter matching the given mailing states and trigger state.
  • access: public
Inx_Api_TriggerMailing_StateFilter createStateFilter ([ $mailingStateFilter = null], [Inx_Api_TriggerMailing_TriggerState $triggerStateFilter = null])
  • array $mailingStateFilter: a set of mailing states the filter shall match.
  • Inx_Api_TriggerMailing_TriggerState $triggerStateFilter: the trigger state the filter shall match.
createTriggerMailing (line 231)

Creates a new trigger mailing in the specified list using the given trigger descriptor. descriptor, use one of the builders provided by the Inx_Api_TriggerMailing_Descriptor_TriggerDescriptorBuilderFactory, which can be obtained using the getTriggerDescriptorBuilderFactory() method.

Creates a new trigger mailing in the specified list using the given trigger descriptor. To create a trigger descriptor, use one of the builders provided by the Inx_Api_TriggerMailing_Descriptor_TriggerDescriptorBuilderFactory, which can be obtained using the getTriggerDescriptorBuilderFactory() method.

  • return: a new TriggerMailing.
  • access: public
createTriggerStateFilter (line 289)

Creates a new Inx_Api_TriggerMailing_StateFilter which matches the given trigger state and any mailing state.

Creates a new Inx_Api_TriggerMailing_StateFilter which matches the given trigger state and any mailing state.

  • return: a new StateFilter matching the given trigger state.
  • access: public
Inx_Api_TriggerMailing_StateFilter createTriggerStateFilter ([Inx_Api_TriggerMailing_TriggerState $stateFilter = null])
getTriggerDescriptorBuilderFactory (line 323)

Returns the Inx_Api_TriggerMailing_Descriptor_TriggerDescriptorBuilderFactory used to create builders for the various trigger types.

Returns the Inx_Api_TriggerMailing_Descriptor_TriggerDescriptorBuilderFactory used to create builders for the various trigger types. Note: The factory is a singleton.

  • return: the TriggerDescriptorBuilderFactory used to create builders for the various trigger types.
  • access: public
getTriggerIntervalBuilderFactory (line 336)

Return the Inx_Api_TriggerMailing_Descriptor_TriggerIntervalBuilderFactory used to create the builders for the various interval types. interval trigger mailings.

Return the Inx_Api_TriggerMailing_Descriptor_TriggerIntervalBuilderFactory used to create the builders for the various interval types. The resulting Inx_Api_TriggerMailing_Descriptor_TriggerInterval is used for interval trigger mailings. Note: the factory is a singleton.

  • return: the TriggerIntervalBuilderFactory used to create the builders for the various interval types.
  • access: public
selectByState (line 218)

Returns a

  1. BOResultSet
containing all trigger mailings of the specified list, that pass the specified state filter and filter expression. type.

Returns a

  1. BOResultSet
containing all trigger mailings of the specified list, that pass the specified state filter and filter expression. The result will be ordered by the given attribute using the specified order type. The stateFilter parameter can be created using one of the following methods:
  • createMailingStateFilter: matches a set of mailing states.
  • createTriggerStateFilter: matches a specific trigger state.
  • createStateFilter: matches a set of mailing states and a specific trigger state. Both filters must be passed.
  • createAllMatchingStateFilter(): matches any mailing and trigger state. Note: this is a singleton.

To retrieve all trigger mailings of a list, disregarding their state, use the all matching state filter.

The filter parameter is a boolean expression on a single trigger mailing attribute. The expression syntax is almost identical to the one used by Inx_Api_Filter_Filter::updateStatement( $sStmt ) with two exceptions:

  1. The filter is not matching recipient attributes, but trigger mailing attributes. To define the mailing attribute to match, use the following pattern: 'Attribute(' . Inx_Api_TriggerMailing_TriggerMailingAttribute::XYZ()->getId() . ')'
  2. The filter may only match one column. The operators AND and OR are not allowed.

The orderAttribute parameter is the attribute used to order the result. Allowed attributes are:

  • Inx_Api_TriggerMailing_TriggerMailingAttribute::SUBJECT(): the subject of the trigger mailing - alphabetical order.
  • Inx_Api_TriggerMailing_TriggerMailingAttribute::NAME(): the name of the trigger mailing - alphabetical order.
  • Inx_Api_TriggerMailing_TriggerMailingAttribute::MODIFICATION_DATETIME(): the datetime of the last modification of the trigger mailing - chronological order.
  • Inx_Api_TriggerMailing_TriggerMailingAttribute::ACTIVATION_DATETIME(): the datetime of the first activation of the trigger mailing - chronological order.
  • Inx_Api_TriggerMailing_TriggerMailingAttribute::SINGLE_SEND_COUNT(): the number of recipients to which the trigger mailing was sent till now - numerical order.
  • Inx_Api_TriggerMailing_TriggerMailingAttribute::DEFAULT(): the default order attribute - unspecified order.
To check if an attribute can be used as order attribute, use the Inx_Api_TriggerMailing_TriggerMailingAttribute::isOrderAttribute() method.

  • return: a BOResultSet containing all trigger mailings of the specified list, that pass the specified state filter and filter expression.
  • throws: Inx_Api_IllegalArgumentException if the given order attribute is invalid.
  • throws: Inx_Api_FilterStmtException if the given filter statement could not be parsed.
  • access: public
Inx_Api_BOResultSet selectByState (Inx_Api_List_ListContext $listContext, Inx_Api_TriggerMailing_StateFilter $stateFilter, [Inx_Api_TriggerMailing_TriggerMailingAttribute $orderAttribute = null], [int $iOrderType = null], [string $sFilter = null])

Inherited Methods

Inherited From Inx_Api_BOManager

Inx_Api_BOManager::get()
Inx_Api_BOManager::remove()
Inx_Api_BOManager::selectAll()

Documentation generated on Thu, 17 Sep 2015 14:27:33 +0200 by phpDocumentor 1.3.2