Mailbox Query Service (V5.2.6 or later)

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 application platforms
Related services The Mailbox Query service works with the other Sterling B2B Integrator Mailbox services to provide mailbox 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 virtual mailbox root of the user.

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:
  1. Create an Mailbox Query service configuration. For information, see Managing Services and Adapters.
  2. Configure the Mailbox Query service. For information, see Configuring the Mailbox Query Service.
  3. 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 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 within a mailbox name. Do not use the following characters 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. In Global Mailbox, the date and time the message is created applies.
User ID User ID that added the message.

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.

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. 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. Do not use the following characters in a mailbox name: 
? < > | / \ " % * !

Required if you do not have Mailbox Global Query Permission.

Required for Global Mailbox.
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 wild card 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. In Global Mailbox, the date and time the message is created applies.
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. In Global Mailbox, the date and time the message upload is completed applies.
DocumentId A valid document ID for an existing document in Sterling B2B Integrator. In Global Mailbox, use the payload ID.
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.
Restriction: Not applicable for Global Mailbox.
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.
Restriction: Not applicable for Global Mailbox.
GetVisibilityData Get message meta data including visibility information. Valid values are Yes or No. Optional.
  • Yes - Returns the following parameters: AddedByProtocol, AddedByPrincipal, AddedByIP, AddedByWorkflowID, AddSecure, AvailableExtractCount, Extracted, and ExtractAttempt.
Restriction: For Global Mailbox, only parameters that are applicable are returned. For example, if the message is uploaded using myfilegateway then AddedByWorkflowID is not available.
RecentExtractLimit Specifies the maximum number of extracts to return based on the most recent communications sessions. Valid value 1 – 100,000. Optional.
Restriction: Not applicable for Global Mailbox.

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 a virtual root, the MailboxPath is 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.
Restriction: Not applicable for Global Mailbox.
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.
Restriction: Not applicable for Global Mailbox.
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.
Restriction: For Global Mailbox, included if available in message meta data.
AddedByPrincipal Indicates if the message was added by the Sterling B2B Integrator user. Valid values include any possible User ID. Returned when GetVisibilityData=Yes.
Restriction: For Global Mailbox, included if available in message meta data.
AddedByIP Specifies the IP address of the user responsible for adding the message. Returned when GetVisibilityData=Yes.
Restriction: For Global Mailbox, included if available in message meta data.
AddedByWorkflowID Specifies the ID of the Business Process responsible for adding the message. Returned when GetVisibilityData=Yes.
Restriction: For Global Mailbox, included if available in message meta data.
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.
Restriction: For Global Mailbox, included if available in message meta data.
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.
Restriction: Not applicable for Global Mailbox.
Extracted A set of recent extract attempts. Returned when GetVisibilityData=Yes.
Restriction: Not applicable for Global Mailbox.
ExtractAttempt A recent extract attempt. Returned when GetVisibilityData=Yes. Multiple attempts can be returned.
Restriction: Not applicable for Global Mailbox.
Principal Indicates the user who performed the extract. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
IP Specifies the IP address from which the extract was performed. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
Protocol Specifies the protocol used to perform the extract. Valid values are SFTP, FTP, WebDAV, CDInterop, HTTP, MailboxService, MBI, or AS2. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
Date Extract attempt date. Format yyyyMMdd'T'hhmm. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
Status Indicates whether or not the extract attempt was successful. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
Secure Indicates whether or not the extract attempt was secure. Valid values are True or False. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
Binary Transfer Indicates whether or not the extract attempt was performed in binary mode. (For FTP protocol.) Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.
WorkflowID Specifies the ID of the Business Process responsible for the extract. Sub-element of ExtractAttempt.
Restriction: Not applicable for Global Mailbox.

Sample Visibility Data

The GetVisibilityData parameter allows you to retrieve extra information about a message. For example, with the entered input parameters, the following data is returned:

<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>
For Global Mailbox, the sample returned data with the same input parameters is the following input and output:
<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>