Mailbox Services

Mailbox services allow you to add, extract, query, or delete messages.

Mailbox Add Service

The Mailbox Add service enables you to add messages to a particular mailbox. The service enables the specification of a message name, the mailbox where the message should be added, and the extraction policy. Before the Mailbox Add service runs, it verifies a user’s permission to use a mailbox. The primary role of this mailbox is to provide temporary data storage until the administrator can correct the problem.

One of three extraction policies is assigned to a message when it is added to a mailbox. These policies control when extraction of a message is allowed. The following table describes the extraction policies:

Policy	Description
Extract a limited number of times	Carries a count, which is reduced each time the document is extracted. Following are two ways you can use this policy: When the count is one, the message is like a normal letter placed into a drop-box. After the message is extracted once, it is no longer available. When the count is greater than one, the message is available to multiple users. The extraction succeeds, but after the count goes to zero, no one can extract the message.
Extractable until some future date	Enables extraction until the date is reached and disables extraction after the date is passed. This policy is like a coupon that expires on a certain date.
Extractable (or not) until further notice	Enables or disables all extractions until an administrator changes the policy.

Mailbox Extraction Services

Extraction is the term for reading a message from a mailbox, typically into the primary document of a business process. Extracting a message within a business process consists of two steps:

The Mailbox Extract Begin service verifies permissions, availability and extractability. If the operation is allowed, the data is provided to the business process.
After the business process has finished processing the data, the extraction can be completed by invoking either the Mailbox Extract Abort service or the Mailbox Extract Commit service. If there is an error after the Mailbox Extract Begin service, the Mailbox Extract Abort service is invoked, which restores the extractable count to the original value as if the Mailbox Extract Begin service never took place. If no errors occur, the Mailbox Extract Commit service is invoked, which formally completes the extraction.

If business processes do not need this failure handling, you can combine the Mailbox Extract Begin service and the Mailbox Extract Commit service into a single service by setting a parameter in the Mailbox Extract Begin service.

When a business process executes the Mailbox Extract Begin service, a message “hold” table tracks the processing of a message by a particular business process. Access to a message is controlled by the extraction policy.

It is possible that a user begins to extract a message, but then decides that it is not possible to process the document. For example, a business process may extract a message and send it to a trading partner over the network. If the transfer fails, the extraction does not succeed (to prevent one of the limited copies of the message from being extracted).

Mailbox Query Service

The Mailbox Query service enables you to select a similar grouping of messages. For example, a user can use the Mailbox Query service to find messages added between two dates. A user must have permission to query a mailbox.

The Mailbox Query service supports multiple parameters, including:

Mailbox path
Message name pattern
Message ID
User ID
Start date and time
End date and time
Messages extractable
Order by
Ascending/descending

Mailbox Delete Service

The Mailbox Delete service enables you to remove outdated or obsolete messages. This service supports a parameter list similar to that of the Mailbox Query service. The user must either have permission on each of the mailboxes, or must have the mailbox global delete.permission, which allows the holder to delete messages from any mailbox.