Mailbox Query Service (V5.2.0 - 5.2.5)

The Mailbox Query service performs a query of Sterling B2B Integrator mailboxes for messages that meet specified criteria and returns results.

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

Category	Description
System name	Mailbox Query Service
Graphical Process Modeler (GPM) categories	All Services, Internet B2B > Mailbox
Description	Performs a query of Sterling B2B Integrator mailboxes for messages that meet specified criteria and returns results.
Business usage	Use this service to find messages in Sterling B2B Integrator Mailbox.
Usage example	Search for messages in one or more Sterling B2B Integrator mailboxes.
Preconfigured?	Yes
Requires third-party files?	No
Platform availability	All supported Sterling B2B Integrator platforms
Related services	The Mailbox Query 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 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 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	A business process using this service must be run by a user with permission to access all applicable mailboxes. A user with Mailbox Global Query permission can query any message in any mailbox.
Business process context considerations	The service extracts the user permissions at run time to confirm authorization of the business process to access the referenced mailboxes.
Returned status values	Returned status values: Success – Normal completion. User Permission Error – The user associated with the business process either does not have Mailbox Global Query permission, or does not have permission to use the target mailboxes. Invalid Mailbox Error – The mailbox identified as the query target does not exist. Invalid Mailbox Parameter Error – An error occurred passing parameters to this service such as a message ID in an invalid format. 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. A Mailbox Global Query permission allows access to all mailboxes.
Testing considerations	Troubleshooting information for this service can be found in Sterling B2B Integrator Mailbox log files.

How the Mailbox Query Service Works

Use the Mailbox Query service to query Sterling B2B Integrator Mailbox and find messages.

Business Process Example

The following BPML queries all messages currently in the Abcd mailbox. If the user has a virtual mailbox root, then the Abcd mailbox path is relative to the user's virtual mailbox root.

The user must have permission for the Abcd Mailbox, or have the Mailbox Global Query permission.

<process name="AbcdQuery">
    <sequence name="Query">
   <!-- Query the Mailbox -->
        <operation name="Mailbox Query Service">
           <participant name="MailboxQuery"/>
           <output message="QueryRequest">
              <assign to="." from="*"></assign>
             <assign to="MailboxPath">/Abcd</assign>
          </output>
           <input message="inmsg">
               <assign to="QueryResults" from="*"></assign>
          </input>
       </operation>
   </sequence> 
</process>

Implementing the Mailbox Query Service

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

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

Configuring the Mailbox Query Service

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

Field	Description
Config	Name of the adapter configuration.
Ascending	Whether the business process should sort the result of a query in ascending order. Valid values are Yes and No.
EndDateTime	Defines the latest value for this query. Valid values are any date and time in the following format: Year-Month-Day Hour:Minute:Second (yyyy-mm-dd hh:mm:ss) For example, 2006-02-21 04:02:20
MailboxPath	One or more mailbox paths that the user has permission to use. If the user has been set up with a virtual root, then MailboxPath will be a relative path to the virtual root. The virtual root is not visible to the business process. Required if you do not have Mailbox Global Query Permission. Valid values are UNIX-style paths where the folders correspond to a mailbox hierarchy. Paths must begin with the ‘/' character and use the ‘/' to delimit mailboxes in the hierarchy. The space character is allowed in the middle of a mailbox name. The following characters are not allowed anywhere in a mailbox name: ? < > \| / \ " % * !
MessageExtractable	Constraint to query messages based on their Extractability: Yes – Either ExtractableCount >0, ExtractableUntil is current date or later, or Extractable = Yes. No – Either ExtractableCount = 0, ExtractableUntil is an earlier date, or Extractable = No.
MessageId	ID of the stored message. Required. Valid values are numbers greater than or equal to 0.
MessageNamePattern	Pattern to select messages with names matching the pattern. The following characters cannot be used in a message name: ? < > \| / \ " % * ! You can use an asterisk () as a wildcard such as .po
OrderBy	Enables the business process to sort the result of a query by any of the following: Message Path Message Size Message ID Mailbox Path Created Date and Time
StartDateTime	Defines the earliest value for this query. Valid values are any date and time in the following format: Year-Month-Day Hour:Minute:Second (yyyy-mm-dd hh:mm:ss). For example, 2006-02-21 04:02:20.
User ID	User ID that added the message.

Parameters Passed from a Business Process to the Service

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

Parameter	Description
MailboxPath	One or more mailbox paths that the user has permission to use. If the user has a virtual root, then MailboxPath is a relative path to the virtual root. The virtual root is not visible to the business process. Required if you do not have Mailbox Global Query Permission. Valid values are UNIX-style paths where the folders correspond to a mailbox hierarchy. Paths must begin with the ‘/' character and use the ‘/' to delimit mailboxes in the hierarchy. The space character is allowed in the mailbox name. The following characters are not allowed anywhere in a mailbox name: ? < > \| / \ " % * !
MessageNamePattern	Pattern to select messages with names matching the pattern. The following characters cannot be used in a message name: ? < > \| / \ " % * ! You can use an asterisk () as a wildcard such as .po
StartDateTime	Defines the earliest value for this query. Valid values are any date and time in the following format: Year-Month-Day Hour:Minute:Second (yyyy-mm-dd hh:mm:ss). For example, 2006-02-21 04:02:20.
EndDateTime	Defines the latest value for this query. Valid values are any date and time in the following format: Year-Month-Day Hour:Minute:Second (yyyy-mm-dd hh:mm:ss). For example, 2006-02-21 04:02:20.
DocumentId	A valid document ID for an existing document in Sterling B2B Integrator.
MessageExtractable	Constraint to query messages based on their Extractability: Yes – Either ExtractableCount >0, ExtractableUntil is current date or later, or Extractable = Yes. No – Either ExtractableCount = 0, ExtractableUntil is an earlier date, or Extractable = No.
QueryStartPos	Specifies the starting position value for the query results. Use to pull a portion of the query results when there are a large number of messages. Use in conjunction with QueryEndPos to determine how many page links to display, and the size of the result set. Valid value is any positive integer. Optional.
QueryEndPos	Specifies the ending position value for the query results. Use to pull a portion of the query results when there are a large number of messages. Use in conjunction with QueryStartPos to determine how many page links to display, and the size of the result set. Valid value is any positive integer. Optional.
GetVisibilityData	Get message metadata including visibility information. Valid values are Yes or No. Optional. Yes - Will return the following parameters: AddedByProtocol, AddedByPrincipal, AddedByIP, AddedByWorkflowID, AddSecure, AvailableExtractCount, Extracted, and ExtractAttempt.
RecentExtractLimit	Specifies the maximum number of extracts to return based on the most recent communications sessions. Valid value 1 – 100,000. Optional.

Parameters Passed from Service to Business Process

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

Parameter	Description
MessageId	ID of the stored message.
DocumentId	Document ID corresponding to the stored message.
CreateDateTime	Creation date. Format `yyyyMMdd'T'hhmm`.
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.
ExtractableUntil	The last date and time that this message may be extracted.
QueryTotal	The total number of messages in the query. Based on the values of QueryStartPos and QueryEndPos, the service returns a limited result set. If QueryStartPos and QueryEndPos are specified, the QueryTotal output is returned.
ContentEncrypted	Indicates whether or not the message content is encrypted. Valid values are True or False.
AddedByProtocol	Indicates whether or not the message was added by a protocol. Valid values are SFTP, FTP, WebDAV, CDInterop, HTTP, MailboxService, MBI, or AS2. Returned when GetVisibilityData=Yes.
AddedByPrincipal	Indicates if the message was added by the Sterling B2B Integrator user. Valid values include any possible User ID. Returned when GetVisibilityData=Yes.
AddedByIP	Specifies the IP address of the user responsible for adding the message. Returned when GetVisibilityData=Yes.
AddedByWorkflowID	Specifies the ID of the Business Process responsible for adding the message. Returned when GetVisibilityData=Yes.
AddSecure	Indicates whether or not the message is encrypted or was added with a protocol configured for SSL. Valid values are True or False. Returned when GetVisibilityData=Yes.
CurrentlyExtractable	Based on the extractability policy; indicates whether or not the message is currently extractable.
AvailableExtractCount	From the available recorded extracts; indicates the number of times the message was successfully extracted. Returned when GetVisibilityData=Yes.
Extracted	A set of recent extract attempts. Returned when GetVisibilityData=Yes.
ExtractAttempt	A recent extract attempt. Returned when GetVisibilityData=Yes.
Principal	Indicates the user who performed the extract. Subelemtent of ExtractAttempt.
IP	Specifies the IP address from which the extract was performed. Subelemtent of ExtractAttempt.
Protocol	Specifies the protocol used to perform the extract. Valid values are SFTP, FTP, WebDAV, CDInterop, HTTP, MailboxService, MBI, or AS2. Subelemtent of ExtractAttempt.
Date	Extract attempt date. Format `yyyyMMdd'T'hhmm`. Subelemtent of ExtractAttempt.
Status	Indicates whether or not the extract attempt was sucessfull. Subelemtent of ExtractAttempt.
Secure	Indicates whether or not the extract attempt was secure. Valid values are True or False. Subelemtent of ExtractAttempt.
Binary Transfer	Indicates whether or not the extract attempt was performed in binary mode. (For FTP protocol.) Subelemtent of ExtractAttempt.
WorkflowID	Specifies the ID of the Business Process responsible for the extract. Subelemtent of ExtractAttempt.

Sample Visibility Data

The GetVisibilityData parameter allows you to retrieve extra information about a message. For example, consider the following input parameters:

<attribute name=”GetVisibilityData”>Yes</attribute> 
<attribute name=”RecentExtractLimit”>10</attribute> 
Based on these settings, the following output is returned in addition to the 
standard message details. 
<AddedByIP>192.168.100.1</AddedByIP> 
<AddedByPrincipal>Bob</AddedByPrincipal> 
<AddedByProtocol>FTP</AddedByProtocol> 
<AddedByWorkflowId>-1</AddedByWorkflowId> 
<AddSecure>false</AddSecure> 
<AvailableExtractCount>1</AvailableExtractCount> 
<Extracted>
 <ExtractAttempt>
    <Principal>Jim</Principal>
   <IP>192.168.100.5</IP>
    <Protocol>SFTP</Protocol>
   <Date>01/01/2001</Date>
    <Status>success</Status>
   <Secure>true</Secure>
    <BinaryTransfer>true</BinaryTransfer>
   <WorkflowId>-1</WorkflowId>
  </ExtractAttempt> 
</Extracted>