Mailbox Extract Begin Service

The Mailbox Extract Begin service begins the extraction of a message from a mailbox. Call this service in a business process to automate the extraction of messages from designated mailboxes.

The following table provides an overview of the Mailbox Extract Begin service:

Category	Description
System name	Mailbox Extract Begin Service
Graphical Process Modeler (GPM) categories	All Services, Internet B2B > Mailbox
Description	Begins the extraction of a message from a mailbox.
Business usage	Use this service to begin extracting a message from a mailbox.
Usage example	Extract all purchase orders from a mailbox and deliver them to the SAP adapter for back-office processing.
Preconfigured?	Yes
Requires third party files?	No
Platform availability	All supported application platforms
Related services	The Mailbox Extract Begin service works with the other Sterling B2B Integrator Mailbox services to provide mailboxing capability: Mailbox Add service – Enables the insertion of messages into a mailbox. Mailbox Extract Commit service – Provides the ability for a business process to signal Sterling B2B Integrator Mailbox that the message extract request has successfully completed. Mailbox Extract Abort service – Enables a business process to signal a failed message extraction to Sterling B2B Integrator Mailbox. Mailbox Query service – Enables querying messages. Mailbox Delete service – Enables deletion of messages. Mailbox Evaluate All Automatic Rules service – Provides for the scheduling of automatic routing rules for Sterling B2B Integrator Mailbox. Mailbox Evaluate Routing Rule service – Enables triggering of mailbox routing rules from a business process.
Application requirements	Nothing external to Sterling B2B Integrator is required to use this service.
Initiates business processes?	No
Invocation	User with appropriate permissions to access the target mailbox must run the business process.
Business process context considerations	The user permissions are extracted from the business process context at run time to confirm authorization of the business process to add messages to the target mailbox.
Returned status values	The possible status values a service can return are: Success – Normal completion. User Permission Error – The user associated with the business process does not have permission to use the target mailbox. Invalid Mailbox Error – The mailbox does not exist. Invalid Mailbox Parameter Error – An error occurred passing parameters to this service such as a message ID in an invalid format. Message Not Found Error – The requested message cannot be found for extraction. Message Not Extractable Error – The target message's extraction policy forbids extraction. Mailbox Extract Invalid State Error – The current business process has not performed an extract begin request. Mailbox Repository Error – A generic error associated with the mailbox repository occurred. Mailbox Service Error – A generic error associated with the mailbox service occurred.
Restrictions	The limitations of this service are based on the assignment of mailbox permissions to users and groups.
Testing considerations	Troubleshooting information for this service can be found in Sterling B2B Integrator Mailbox log files.

How the Mailbox Extract Begin Service Works

Use the Mailbox Extract Begin service to extract messages from a mailbox. This service checks the extractability and availability of a message and verify whether the user that is running the business process has permissions on the mailbox.

If the extractability is ExtractableCount = 1, the Mailbox Extract Begin service locks the message until the extraction is complete. After the extraction is complete, the count is decremented. If the ExtractableCount = x, x number of Mailbox Extract Begin services can lock the message.

You can use this service in one of the following modes:

Mailbox Extract Begin with CommitNow = No. This is the default mode. In this mode, you must include the Mailbox Extract Abort service and Mailbox Extract Commit service in your business process. This mode is useful to control the extract count. If an error occurs during the extraction, such as a protocol failure, the message count is set to the original count. The business process locks the message until the Mailbox Extract Commit service or the Mailbox Extract Abort service completes.
Mailbox Extract Begin with CommitNow = Yes. In this mode, all message extracts are extracted and committed in a single step. This mode is useful if you do not need control over the extract count. If an error occurs during the extract, such as a protocol failure, the message count will not be incremented back to the original count. The business process does not lock the message.

Business Process Example

The following BPML extracts the message 1234 from a Sterling B2B Integrator mailbox. This business process succeeds if the user associated with this BPML has permission to the mailbox contains message 1234.

<!-- Read in the payload. -->
    <operation name="Mailbox ExtractBegin Service">
       <participant name="MailboxExtractBegin"/>
           <output message="ExtractBeginRequest">
               <assign to="." from="*"></assign>
               <assign to="MessageID">1234</assign>
            </output>
             <input message="inmsg">
                 <assign to="." from="*"></assign>
            </input>
    </operation>

Implementing the Mailbox Extract Begin Service

To implement the Mailbox Extract Begin service for use in a business process:

Create a Mailbox Extract Begin service configuration. For information, see Managing Services and Adapters.
Configure the Mailbox Extract Begin service. For information, see Configuring the Mailbox Extract Begin Service.
Use the Mailbox Extract Begin service in a business process.

Configuring the Mailbox Extract Begin Service

The following table describes the fields used to configure the Mailbox Extract Begin service in the GPM:

Field	Description
Config	Name of the adapter configuration.
CommitNow	Valid values are: Yes – Automatically commits the message for extraction without the use of Mailbox Extract Commit service. The business process does not lock the message. No – Requires the Mailbox Extract Commit service to commit the message for extraction. The business process locks the message until the Mailbox Extract Commit or Mailbox Extract Abort service is complete. Default.
MessageID	ID of the stored message. Required. Valid values are numbers >=0 in traditional mailboxes and in UUID format in Global Mailbox.
UseGlobalMailboxes	Whether to use only Global Mailbox or only traditional Sterling B2B Integrator mailboxes. The following values are valid: Yes - The Global Mailbox is used. The UseGlobalMailboxes parameter is displayed in the business process XML, with the value set to YES. No (default) - The Global Mailbox is not used. The UseGlobalMailboxes parameter is displayed in the business process XML, with the value set to NO.

Input to Service from Business Process

The following table contains the parameters passed into the Mailbox Extract Begin service from a business process:

Parameter	Description
ViewOnly	Valid values are: Yes - the message is read only and the ExtractableCount is not changed. If CommitNow and ViewOnly both are YES then ViewOnly is in effect. No - when the message is viewed, it is extracted and ExtractableCount is decreased.

Output from Service to Business Process

The following table contains the parameters passed from the Mailbox Extract Begin service to a business process:

Parameter	Description
MessageID	ID of the stored message.
DocumentId	Document ID corresponding to the stored message.
CreateDateTime	Creation date.
MessageName	Name of the message.
MailboxPath	Path of the mailbox which the message was added to. If the user has been set up with a virtual root, the MailboxPath will be a relative path to the virtual root. The virtual root is not visible to the business process.
ContentType	Indicates the MIME type and subtype. Use the following format: `MIME Type/MIME Subtype` .
MessageSize	Size of the added message in bytes.
ExtractableCount	Number of times this message may be accessed. One of the three extractability parameters is returned.
Extractable	Indicates whether this message can be extracted. One of the three extractability parameters is returned.
ExtractableUntil	The last date and time that this message may be extracted. One of the three extractability parameters is returned.