Interface Inx_Api_Recipient_BatchChannel

Description

An Inx_Api_Recipient_BatchChannel can (and should) be used for manipulation of large amounts of data.

An Inx_Api_Recipient_BatchChannel can (and should) be used for manipulation of large amounts of data. The createRecipient() and selectRecipient() methods are used to create and/or select a recipient. After creating or selecting a recipient, the following batch commands operate on this until another recipient is selected. An Inx_Api_Recipient_BatchChannel may be used to perform the following operations:

  • Select recipients: selectRecipient($sKeyValue)
  • Create recipients: createRecipient($sKeyValue, $blSelectIfExistant)
  • Remove recipients: removeRecipient($sKeyValue)
  • Manipulate recipient attributes write($oAttribute, $oValue) and writeIfNull($oAttribute, $sValue)
  • Subscribe recipients: subscribeIfNotUnsubscribed($oListContext, $sSubscriptionDate)
  • Unsubscribe recipients: unsubscribe($oListContext)
The selection, creation and removal of recipients requires a value corresponding to the recipient key. Usually, this key is the email address. It is possible to use a different attribute as recipient key for the BatchChannel. To do this, use the Inx_Api_Recipient_RecipientContext::createBatchChannel($oAttribute) method to create the Inx_Api_Recipient_BatchChannel object and pass the attribute used as key. However, be aware that the attribute used as key should be unique, although this is no hard technical requirement. Using a non unique attribute as key will return any of the matching recipients (undetermined). Also, the creation of recipients using a different key attribute is not possible.

Note: Resubscription is not supported by

  1. BatchChannel
. If you wish to resubscribe a recipient, use In_Api_Recipient_UnsubscriptionRecipientRowSet::resubscribe($sDate) instead.

The following snippet shows how to add two new addresses and change their "Firstname" and "Lastname" attributes. If the addresses exist already, these attribute values will be overwritten.

 $oRecipientContext = $oSession->createRecipientContext();
 $oBatchChannel = $oRecipientContext->createBatchChannel();
 $oRecipientMetaData = $oRecipientContext->getMetaData();

 $oBatchChannel->createRecipient( "mueller@yourcompany.com", true );
 $oBatchChannel->write( $oRecipientMetaData->getUserAttribute( "Firstname" ), "George" );
 $oBatchChannel->write( $oRecipientMetaData->getUserAttribute( "Lastname" ), "Müller" );

 $oBatchChannel->createRecipient( "clinton@yourcompany.com", true );
 $oBatchChannel->write( $oRecipientMetaData->getUserAttribute( "Firstname" ), "Bill" );
 $oBatchChannel->write( $oRecipientMetaData->getUserAttribute( "Lastname" ), "Clinton" );

 $retArr = $oBatchChannel->executeBatch();
Note: The boolean parameter of createRecipient defines how to handle already existent recipients. If the parameter is set to true - as in the example - the recipient will only be created if it does not already exist. Existent recipients are selected instead. If the parameter is set to false the BatchChannel will attempt to create the recipient. If the recipient is not already existing it will be created and selected. However, if the recipient exists already, the result will be RESULT_FAILURE_DUPLICATE_KEY and the recipient will <strong>not</strong> be selected. Therefore, all succeeding operations on this recipient will not be committed (RESULT_NOT_COMMITTED).

The selection and removal of recipients works very much the same, except that removeRecipient($sKeyValue) will not select the deleted recipient of course. After deleting a recipient, a new recipient must be selected (or created) before any tasks may be invoked. This is because the remove() method resets the currently selected recipient.

The writeIfNull($oAttribute, $sValue) method allows you to set an attribute value only, if no value was assigned previously (i.e. the attribute value is null). A similar technique is used by subscribeIfNotUnsubscribed($oListContext, $sDate). This method subscribes the selected recipient to the given list, only when the recipient was not unsubscribed from that list before.

Each command to the BatchChannel results in a value in the returned integer array. By scanning the array, you can find out which of the commands have been executed, and which have not.

The values produced by

:
  • The recipientId is returned if the recipient is removed
  • RESULT_FAILURE_KEY_NOT_FOUND is returned if the recipient doesn't exists

The values produced by selectRecipient():

  • The recipientId is returned if the recipient is selected
  • RESULT_FAILURE_DUPLICATE_KEY is returned if the unique key already exists
  • RESULT_FAILURE_BLOCKED_BY_BLACKLIST is returned if the email address is blocked
  • RESULT_FAILURE_KEY_NOT_FOUND is returned if the recipient doesn't exist

The values produced by createRecipient():

  • The recipientId is returned if the recipient was successfully created or selected
  • RESULT_FAILURE_DUPLICATE_KEY is returned if the unique key already exists
  • RESULT_FAILURE_BLOCKED_BY_BLACKLIST is returned if the email address is blocked
  • RESULT_FAILURE_ILLEGAL_VALUE is returned if the key value is illegal

The values produced by write() and writeIfNull()

  • RESULT_COMMITTED is returned if the value is set and committed
  • RESULT_NOT_COMMITTED is returned if the value is set, but could not be committed
  • RESULT_FAILURE_ILLEGAL_VALUE is returned if the value of the attribute is illegal

The values produced by subscribeIfNotUnsubscribed()

  • RESULT_COMMITTED is returned if the recipient was subscribed
  • RESULT_NOT_COMMITTED is returned if the recipient was unsubscribed before

The values produced by unsubscribe()

  • RESULT_COMMITTED is returned if the recipient was unsubscribed
  • RESULT_NOT_COMMITTED is returned if the recipient was already unsubscribed before

For more information on recipients, see the Inx_Api_Recipient_RecipientContext documentation.

Located in /Api/Recipient/BatchChannel.php (line 124)


	
			
Class Constant Summary
Method Summary
void createRecipient (string $sKeyValue, bool $blSelectIfExistant)
array executeBatch ()
void removeRecipient (string $sKeyValue)
void selectRecipient (string $sKeyValue)
void subscribeIfNotUnsubscribed (Inx_Api_List_ListContext $lc, subscriptionDate $subscriptionDate)
void write (Inx_Api_Recipient_Attribute $oAttribute, string $sValue)
void writeIfNull (Inx_Api_Recipient_Attribute $oAttribute, string $sValue)
Methods
createRecipient (line 194)

Create and/or select a recipient identified by the given key value.

Create and/or select a recipient identified by the given key value. The behaviour of this method depends on the value of the bool parameter and the recipient state (existing or not existing). The behaviour is defined as follows:

  • Recipient does not exist, parameter is false: The recipient will be created and selected.
  • Recipient already exists, parameter is false: The recipient will neither be created nor selected.
  • Recipient does not exist, parameter is true: The recipient will be created and selected.
  • Recipient already exists, parameter is true: The recipient will not be created but selected.
<strong>Note:</strong> If a key different from the email address is used by this Inx_Api_Recipient_BatchChannel this method will not create any recipient. To use this method you must use the email address as recipient key.

  • access: public
void createRecipient (string $sKeyValue, bool $blSelectIfExistant)
  • string $sKeyValue: the key value of the recipient to create/select.
  • bool $blSelectIfExistant: true if existent recipients shall be selected, false if existent recipients shall neither be created nor selected.
executeBatch (line 257)

Execute the batched commands.

Execute the batched commands.

  • return: an array of int, with each element indicating the result of a the corresponding command. May be one of:
    • RESULT_COMMITTED
    • RESULT_NOT_COMMITTED
    • RESULT_FAILURE_BLOCKED_BY_BLACKLIST
    • RESULT_FAILURE_DUPLICATE_KEY
    • RESULT_FAILURE_ILLEGAL_VALUE
    • RESULT_FAILURE_KEY_NOT_FOUND
    • RESULT_PERMISSION_DENIED
  • access: public
array executeBatch ()
getContext (line 265)

Retrieves the Inx_Api_Recipient_RecipientContext which created this BatchChannel.

Retrieves the Inx_Api_Recipient_RecipientContext which created this BatchChannel.

  • return: the RecipientContext which created this BatchChannel.
  • access: public
removeRecipient (line 159)

Removes the recipient identified by the given key value from the system.

Removes the recipient identified by the given key value from the system. A key different from the email address may be specified using Inx_Api_Recipient_RecipientContext::createBatchChannel($oAttribute). However, be careful with that method, as the selected recipient for non unique key attributes is not determined. In such a case, any of the matching recipients may be removed.

  • access: public
void removeRecipient (string $sKeyValue)
  • string $sKeyValue: the key value of the desired recipient.
selectRecipient (line 172)

Selects an existing recipient identified by the given key value.

Selects an existing recipient identified by the given key value. A key different from the email address may be specified using Inx_Api_Recipient_RecipientContext::createBatchChannel($oAttribute). However, be careful with that method, as the selected recipient for non unique key attributes is not determined. In such a case, any of the matching recipients may be selected.

  • access: public
void selectRecipient (string $sKeyValue)
  • string $sKeyValue: the key value from the desired recipient.
subscribeIfNotUnsubscribed (line 238)

Subscribes a new recipient to the given list, if she/he was not unsubscribed from it before.

Subscribes a new recipient to the given list, if she/he was not unsubscribed from it before. Use the write() method to overwrite the unsubscription of the recipient or use Inx_Api_Recipient_UnsubscriptionRecipientRowSet::resubscribe($sDate) instead.

  • since: API 1.6.0
  • access: public
void subscribeIfNotUnsubscribed (Inx_Api_List_ListContext $lc, subscriptionDate $subscriptionDate)
  • lc $lc: the list to which the recipient should be subscribed.
  • subscriptionDate $subscriptionDate: the subscription date. May <strong>not</strong> be null.
unsubscribe (line 226)

Unsubscribes the current recipient from the specified list.

Unsubscribes the current recipient from the specified list. Requires a previously invoked select or create command and the recipient must be a member of the list.

  • since: API 1.6.0
  • access: public
void unsubscribe (Inx_Api_List_ListContext $lc)
  • lc $lc: the list from which the recipient should be unsubscribed.
write (line 205)

Sets a new value to the specified attribute.

Sets a new value to the specified attribute. Requires a previously invoked select or create command. If the attribute is changed several times during a batch command, the last will be the new value.

  • access: public
void write (Inx_Api_Recipient_Attribute $oAttribute, string $sValue)
writeIfNull (line 216)

Sets a new value to the specified attribute, only if the current value is null.

Sets a new value to the specified attribute, only if the current value is null. Requires a previously invoked select or create command. If this method is invoked several times during a batch command, the first value will be set.

  • access: public
void writeIfNull (Inx_Api_Recipient_Attribute $oAttribute, string $sValue)
Class Constants
RESULT_COMMITTED = -100 (line 128)

RESULT_COMMITTED is returned if the value is set and committed.

RESULT_COMMITTED is returned if the value is set and committed.

RESULT_FAILURE_BLOCKED_BY_BLACKLIST = -103 (line 137)

RESULT_FAILURE_BLOCKED_BY_BLACKLIST is returned if the email address is blocked by a blacklist entry.

RESULT_FAILURE_BLOCKED_BY_BLACKLIST is returned if the email address is blocked by a blacklist entry.

RESULT_FAILURE_DUPLICATE_KEY = -104 (line 140)

RESULT_FAILURE_DUPLICATE_KEY is returned if the unique key already exists.

RESULT_FAILURE_DUPLICATE_KEY is returned if the unique key already exists.

RESULT_FAILURE_ILLEGAL_VALUE = -102 (line 134)

RESULT_FAILURE_ILLEGAL_VALUE is returned if the key value is illegal.

RESULT_FAILURE_ILLEGAL_VALUE is returned if the key value is illegal.

RESULT_FAILURE_KEY_NOT_FOUND = -105 (line 143)

RESULT_FAILURE_KEY_NOT_FOUND is returned if the recipient doesn't exist.

RESULT_FAILURE_KEY_NOT_FOUND is returned if the recipient doesn't exist.

RESULT_NOT_COMMITTED = -101 (line 131)

RESULT_NOT_COMMITTED is returned if the data was not committed.

RESULT_NOT_COMMITTED is returned if the data was not committed.

RESULT_PERMISSION_DENIED = -200 (line 146)

RESULT_PERMISSION_DENIED is returned if the permission is denied to create, update or remove a recipient.

RESULT_PERMISSION_DENIED is returned if the permission is denied to create, update or remove a recipient.

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