Mailbox Add Service

The Mailbox Add service adds a message to one or more mailboxes.

The following table provides an overview of the Mailbox Add service:

Category	Description
System name	Mailbox Add Service
Graphical Process Modeler (GPM) categories	All Services, Internet B2B > Mailbox
Description	Adds a message to one or more mailboxes.
Business usage	Use this service to add a message to a mailbox.
Usage example	A trading partner sends a business document to a receiver requiring action.
Preconfigured?	Yes
Requires third party files?	No
Platform availability	All supported platforms for Sterling B2B Integrator
Related services	The Mailbox Add service works with the other Mailbox services to provide mailbox capability: Mailbox Extract Begin service – Enables the extraction of messages from 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. Release service - Refreshes the `DocumentId` in Process Data when using the Mailbox Add service in a loop.
Application requirements	None
Initiates business processes?	No
Invocation	A user with appropriate permissions to access the target mailbox must run the business process.
Business process context considerations	The user ID is extracted from the business process context at run time to confirm authorization of the business process to add messages to the target mailbox. If Global Mailbox Mode is specified in the process data or service parameters, a storage blob is created with data copied from the `DocumentId` passed into the service. The service returns the storage id to the workflow.
Returned status values	Returned status values: Success – Normal completion. User Permission Error – The user associated with the business process does not have appropriate permission to use the target mailbox. Invalid Mailbox Error – The target mailbox identified does not exist. Invalid Mailbox Parameter Error – An error occurred in passing parameters to this service. Multiple Extractable Types Specified By Business Process Error – The business process has improperly requested multiple extractability policies for the message. 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	Limitations for users and groups. When messages are added to a mailbox, message names are limited to 100 characters on DB2 and z/OS platforms. All other platforms support 255 character message names.
Testing considerations	Troubleshooting information for this service can be found in the Mailbox log files.

How the Mailbox Add Service Works

Use the Mailbox Add service to add messages to a mailbox.

Business Process Example

The following BPML adds the current primary document to the mailbox named Acme with a message content type of ASCII. This business process will succeed only if the user associated with it has permissions for the Acme mailbox.

<!-- Add Msg to Acme mailbox --> 
    <operation name="Mailbox Add Service"> 
       <participant name="MailboxAdd"/> 
           <output message="MailboxAddServiceTypeInputMessage"> 
              <assign to="." from="*"></assign> 
              <assign to="MailboxPath">/Acme</assign>
              <assign to="MessageName">GDHA</assign>
              <assign to="UseGlobalMailboxes">YES</assign>
              <assign to="ContentType">ascii</assign> 
           </output> 
            <input message="inmsg"> 
                <assign to="AddResults" from="*"></assign> 
           </input> 
    </operation>

Implementing the Mailbox Add Service

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

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

Configuring the Mailbox Add Service

GPM Configuration

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

Consider the following when providing the MessageName and DocumentId:

If a primary document is available in the business process for the Mailbox Add service, DocumentId and MessageName are not required.

If no primary document is available in the business process for the Mailbox Add service, (OutputMsg is set to MessageOnly), DocumentId is required. When both PrimaryDocument and DocumentId are present in the Process Data, PrimaryDocument is ignored and only DocumentId is recognized by the Mailbox Add Service. When using the Mailbox Add service in a loop, you can use the Release service to remove DocumentId node from the Process Data.

Parameter	Description
Config	Name of the adapter configuration.
ContentType	Indicates the MIME type and subtype. Use the following format: `MIME Type`/`MIME Subtype.`
DocumentId	Valid document ID for an existing document.
Extractable	Indicates whether this message can be extracted. Valid values are Yes and No. Restriction: You must provide a value for this field or one of the following: `ExtractableCount` `ExtractableUntil`
ExtractableCount	Number of times this message may be accessed. Valid values are greater than or equal to 0. Restriction: You must provide a value for this field or one of the following: `Extractable` `ExtractableUntil`
ExtractableUntil	Last date and time that this message may be extracted. Valid values are dates and times in `yyyyMMddThhmm` format. Restriction: You must provide a value for this field or one of the following: `ExtractableCount` `Extractable`
MailboxPath	Mailbox path that the user has permission to use. If a user is set up with a virtual root, the `MailboxPath` is a relative path to the virtual root. The virtual root is not visible to the business process. Required. Valid values are UNIX-style paths where the folders correspond to a mailbox name. A path must begin with the / (slash) character and use the / to separate mailboxes in the hierarchy. Following is an example of a valid mailbox path:/Customers/DallasHardware/Inbound The following characters cannot be used in a mailbox name: `? < > \| ' " : \ / % *`
MessageName	User-defined. The following characters cannot be used in a message name: `? < > \\ \| / \ " %` If you do not provide a value for `MessageName`, Sterling B2B Integrator uses the document name of the document referred to in the `DocumentId` parameter passed to the service.
PayloadAvailableDate	The date the payload becomes available for download. Applies only when UseGlobalMailboxes=Yes. Valid values are dates and times in `yyyyMMddThhmm` format. If no value is specified for PayloadAvailableDate, the payload can be downloaded immediately.
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. Important: The Cassandra consistency setting for Mailbox Services in Sterling B2B Integrator is `EACH_QUORUM`, regardless of replication type. Tip: In addition to No and Yes, you can also select the blank selection in the Graphic Process Modeler (GPM). When you select the blank value, the Global Mailbox is not used. Also, the UseGlobalMailboxes parameter is not displayed in the business process XML.

Output from Service to Business Process

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

Parameter	Description
Input Msg	Identifies how to gather information from the business process. Allow process data write – The message response from the service will be written to the process data. Allow message write – Allows the service to write to the message.
MessageId	ID of the stored message.
DocumentId	Document ID corresponding to the stored message.
CreateDateTime	Creation date.
MessageName	User-defined. The following characters cannot be used in a message name: `? < > \\ \| / \ " %` If you do not provide a value for `MessageName`, Sterling B2B Integrator uses the document name of the document referred to in the `DocumentId` parameter passed to the service.
MailboxPath	Mailbox path that the user has permission to use. If a user is set up with a virtual root, the `MailboxPath` is a relative path to the virtual root. The virtual root is not visible to the business process. Required. Valid values are UNIX-style paths where the folders correspond to a mailbox name. A path must begin with the / (slash) character and use the / to separate mailboxes in the hierarchy. Following is an example of a valid mailbox path:/Customers/DallasHardware/Inbound The following characters cannot be used in a mailbox name: `? < > \| ' " : \ / % *`
ContentType	Indicates the MIME type and subtype. Use the following format: `MIME Type/MIME Subtype.`
MessageSize	Size of the added message in bytes. The following note is applicable in the case of Mailbox Add Service only. Note: The Global Mailbox will add small messages (=<10 KB) to payload type MEIG_Storage in the FS instead of Inline_Storage in the Cassandra DB.
ExtractableCount	Number of times this message can 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.
StorageId	Storage data id corresponding to the copied payload, for Global Mailbox usage