Filters help refine the search for items on a user's account. Views reduce the number of elements returned on each item.
The following sections contain more information:
Filters refine a search for items. createCursorRequest and getItemsRequest use filters. Filters are defined in the types.xsd schema. You should keep your filters as simple as possible.
To create a simple filter, instantiate a Filter element and a FilterEntry element. Then, in the FilterEntry element, add a field, value, and operation. For example, a field could have a subject value that is set to “Novell.” The operation could have a contains value. The filter then returns a list of items if the subject contains “Novell.”
Filter gwFilter = new Filter();// Instantiate a Filter FilterEntry gwFE = new FilterEntry();// Instantiate a FilterEntry gwFE.setField("subject"); gwFE.setValue("Novell"); gwFE.setOp(FilterOp.contains); gwFilter.setElement(gwFE);// getItemsRequest is called with the filter.
The getItemsRequest and Response follows:
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject</view> <filter> <element type="FilterEntry"> <op>contains</op> <field>subject</field> <value>Novell</value> </element> </filter> <count>-1</count> </getItemsRequest> <getItemsResponse> <items> <item> <id>4513CC01.domain1.po1.100.16E3837.1.1057.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>received</source> <subject>Novell announces Linux</subject> </item> <item> <id>4513CD2E.domain1.po1.100.16E3837.1.1059.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>received</source> <subject>Novell exceeds Sales</subject> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
To create a more complicated filter, instantiate a Filter element and two FilterEntry elements. Next, in both FilterEntry elements, add a field, value, and operation. Group the two FilterEntry elements with a FilterGroup element. The FilterGroup element defines a FilterOp with a limited set of values: and, or, and not.
The first FilterEntry returns items that have a subject that contains the string “Novell.” The second FilterEntry returns items that have a date greater than a specific date. The two FilterEntry elements are grouped together with an and operation.
Filter gwFilter = new Filter();// Instantiate a Filter FilterGroup gwFG = new FilterGroup();// Instantiate a FilterGroup FilterEntry[] gwFE = new FilterEntry[2];// Instantiate two FilterEntries gwFE[0] = new FilterEntry();// Fill in FilterEntry one gwFE[0].setField("subject"); gwFE[0].setValue("Novell"); gwFE[0].setOp(FilterOp.contains); gwFE[1] = new FilterEntry();// Fill in FilterEntry two gwFE[1].setField("created"); gwFE[1].setValue("2012-09-22T17:45:00Z"); gwFE[1].setOp(FilterOp.gt); gwFG.setOp(FilterOp.and);// Group the two FilterEntries with an “and” gwFG.setElement(gwFE);// Add the two FilterEntries to the FilterGroup gwFilter.setElement(gwFG);// Add the FilterGroup to the Filter
The getItemRequest and Response are shown below:
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject</view> <filter> <element type="FilterGroup"> <op>and</op> <element type="FilterEntry"> <op>contains</op> <field>subject</field> <value>Novell</value> </element> <element type="FilterEntry"> <op>gt</op> <field>created</field> <value>2012-09-22T17:45:00Z</value> </element> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item> <id>4513CD2E.domain1.po1.100.16E3837.1.1059.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>received</source> <subject>Novell exceeds Sales</subject> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
Filtering is based on the different item types: mail, the GroupWise Address Book, and personal address books.
You can search on dates relative to a floating date. The date options that are available are Today, Tomorrow, ThisMonth, ThisWeek, ThisYear, and Yesterday. These values are defined in the FilterDate element.
Filters for mail, calendar, and documents use the following schema element names for the FilterEntry field. Some fields accept only certain FilterOp operations.
created
delivered
modified
startDate
startDay
endDate
endDay
dueDate
@type–use FilterOp.eq on a single type, or use FilterOp.IsOf on multiple item types
to, bc, cc–string fields that are not a part of the recipient list
subject
source–use only FilterOp.isOf or FilterOp.isNotOf or FilterOp.eq
status–use only FilterOp.isOf or FilterOp.isNotOf or FilterOp.eq
msgId
displayName
from/displayName
creator/displayName
author/displayName
versionCreator/displayName
from/email
creator/email
author/email
versionCreator/email
uuid
from/uuid
creator/uuid
author/uuid
versionCreator–use FilterOp.eq only
iCalId
text–a QuickFinder search that searches all text fields, message body, and attachments
acceptLevel–use only FilterOp.eq
place
subType–used with custom messages
caller, company, phone (Phone messages)
versionDescription
size (attachment size)
custom field or user-defined field
allDayEvent (--for GroupWise 2012 and later)
originalId (--for GroupWise 2012 and later)
documentNumber (--for GroupWise 2012 and later)
versionNumber (--for GroupWise 2012 and later)
category (--for GroupWise 2012 and later)
originalSubject (--for GroupWise 2012 and later)
taskCategory (--for GroupWise 2012 and later)
taskPriority (--for GroupWise 2012 and later)
xField (--for GroupWise 2012 and later)
retentionModified (--for GroupWise 2012 and later)
folder (--for GroupWise 2012 and later)
sid (--for GroupWise 2012 and later)
assignedDate (--for GroupWise 2012 and later)
This section contains the following examples:
Suppose you want to return only appointments in the Mailbox by calling getItemsRequest. Use the @type attribute in the field value. The @ signals an attribute in the schema.
The following example request and response use the @type = Appointments on the Mailbox container:
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject</view> <filter> <element type="FilterEntry"> <op>eq</op> <field>@type</field> <value>Appointment</value> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item type="Appointment"> <id>44FEDC3B.domain1.po1.100.1676834.1.76F.1@4:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>received</source> <subject>Delegated Appt</subject> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
The following example returns all items from a container that are sent items by calling getItemsRequest. The value in the filter could be replaced with received, sent, draft, or personal.
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject</view> <filter> <element type="FilterEntry"> <op>eq</op> <field>source</field> <value>sent</value> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item> <id>44E0A6E4.domain1.po1.100.16E3837.1.EFD.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>sent</source> <subject>moving an item</subject> </item> ... </items> <status> <code>0</code> </status> </getItemsResponse>
The following example searches all text element fields, including the message body and attachments for a specific string by calling getItemsRequest:
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject message</view> <filter> <element type="FilterEntry"> <op>eq</op> <field>text</field> <value>Test of the emergency broadcast system.</value> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item> <id>4513F160.domain1.po1.100.16E3837.1.105B.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>received</source> <subject>Test mail message</subject> <message> <part contentType="text/plain" length="112">VGhpcyBpcyBhIHRlc3Qgb2YgdGhlIGVtZXJnZW5 jeSBicm9hZGNhc3Qgc3lzdGVtLiAgVGhpcyBpcyBvbmx5IGEgdGV zdC4KCmFzZGZhc2RmCg== </part> </message> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
The following example demonstrates retrieving all items with a startDate greater than or equal to two days before today by calling getItemsRequest.
In the date element below, the relative date is Today. The field is the startDate with a value of -2. Using -2 as tje value subtracts two days from Today.
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>subject</view> <filter> <element type="FilterEntry"> <op>fieldGTE</op> <field>startDate</field> <value>-2</value> <date>Today</date> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item type="Mail"> <id>452A40F1.domain1.po1.100.16E3837.1.109B.1@1:7. domain1.po1.100.0.1.0.1@16</id> <container>7.domain1.po1.100.0.1.0.1@16</container> <source>personal</source> <subject>Relative Date Example</subject> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
Creating a filter for GroupWise Address Book items can use the following schema element names for the FilterEntry field. Some fields take only certain FilterOp operations. The email address is not a part of the fields that are available to search. The email address is not indexed. It is built from the parts, such as displayName@iDomain.
created
@type–use FilterOp.eq only
department
fullName/firstName
fullName/lastName
username–login ID to GroupWise
uuid–use FilterOp.eq only
domain
postOffice
Filtering the GroupWise Address Book using firstName, lastName, displayName, or department is fastest because the fields are indexed. If you filter using any of the other fields, the searches are time-consuming because the fields are not in the index.
The following example demonstrates calling getItemsRequest:
<getItemsRequest> <container>GroupWiseSystemAddressBook@52</container> <view>null</view> <filter> <element type="FilterEntry"> <op>eq</op> <field>lastName</field> <value>LAST01010000</value> </element> </filter> <count>-1</count> </getItemsRequest> <getItemsResponse> <items> <item type="Contact"> <id>07B4A660-18CA-0000-B989- BA00EB000D00@56:GroupWiseSystemAddressBook@52</id> <name>FIRST01010000 LAST01010000</name> <version>1</version> <modified>2005-10-31T20:06:55Z</modified> <container>GroupWiseSystemAddressBook@52</container> <created>2005-10-31T20:06:39Z</created> <uuid>07B4A660-18CA-0000-B989-BA00EB000D00</uuid> <domain>domain1</domain> <postOffice>po2</postOffice> <distinguishedName>USER01010000.SERVER</distinguishedName> <userid>USER01010000</userid> <fullName> <displayName>FIRST01010000 LAST01010000</displayName> <firstName>FIRST01010000</firstName> <lastName>LAST01010000</lastName> </fullName> <emailList primary="USER01010000@phantom.com"> <email>USER01010000@phantom.com</email> </emailList> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
Creating a filter for personal address book items can use the following schema element names for the FilterEntry field. Some fields only take certain FilterOp operations.
@type–use FilterOp.eq only
department
displayName or name
fullName/firstName
fullName/lastName
fullName/middleName
fullName/namePrefix
fullName/nameSuffix
postOffice
username–login id to GroupWise
uuid–use FilterOp.eq only
emailList/email
emailList/@primary
created
modified
organization (for GroupWise 2012 and later)
The following example returns group items in a personal address book by calling getItemsRequest:
<getItemsRequest> <container>42C510EA.domain1.po1.104.16E3837.1.3.1@53</container> <view>null</view> <filter> <element type="FilterEntry"> <op>eq</op> <field>@type</field> <value>Group</value> </element> </filter> <count>-1</count> </getItemsRequest>
<getItemsResponse> <items> <item type="Group"> <id>44FD7AC1.domain1.po1.104.16E3837.1.FF.1@58:42C510EA. domain1.po1.104.16E3837.1.3.1@53</id> <name>G2</name> <version>1</version> <modified>2012-09-05T19:25:21Z</modified> <container>42C510EA.domain1.po1.104. 16E3837.1.3.1@53</container> <created>2012-09-05T19:25:21Z</created> <comment>asdf</comment> </item> <item type="Group"> <id>44EB3142.domain1.po1.104.16E3837.1.F0.1@58:42C510EA. domain1.po1.104.16E3837.1.3.1@53</id> <name>Group</name> <version>5</version> <modified>2012-09-05T15:12:09Z</modified> <container>42C510EA.domain1.po1.104.16E3837. 1.3.1@53</container> <created>2012-08-22T22:30:58Z</created> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
It might be useful to search for items that have a certain type of attachment.
SharedAttachmentTypes - (shared attachments)
PersonalAttachmentTypes - (personal attachments)
The filter operations that can be used with these fields are:
exists
isOf
isNotOf
The values that can be in the value element are:
MessageBody
File
Recipients
The value string is a space delimited combination of the above values.
You have to test for the existence of the field as well as the values. For example, to return items that have a personal message body or HTML message body (text.htm), the filter would be:
<filter> <element xsi:type="FilterGroup"> <op>and</op> <element xsi:type="FilterEntry"> <op>exists</op> <field>PersonalAttachmentTypes</field> </element> <element xsi:type="FilterEntry"> <op>isOf</op> <field>PersonalAttachmentTypes</field> <value>MessageBody File</value> </element> </element> </filter>
Using the isNotOf operation is tricky. Contact development if you want to use this operation. Here is an example of getting items that have shared attachments only (no personal):
<filter> <element xsi:type="FilterEntry"> <op>notExist</op> <field>PersonalAttachmentTypes</field> </element> </filter>
This section contains the following topics:
Views reduce the elements returned on each item. Your applications can leverage views to retrieve only the item elements you are interested in. For example, suppose an application is retrieving items in the mailbox folder. You need to display only the subject and modified date. The application can specify a subject modified view. Each item in turn returns the subject and modified date. There are a few additional fields that are returned, such as the container, the item ID, and the source.
The view element is a space-delimited list of leaf elements defined in types.xsd schema. For example, types.xsd defines the subject element as <subject" type="string"/>. The element name is subject, which can be added to the view.
The following methods have a view parameter:
It is a good idea to look at the responses for the respective requests to determine the type of elements that can be added to the view. It does not make sense to add subject to the view when calling getFolderListRequest because getFolderListRequest does not return a subject.
Some important view strings are as follows:
The administrator can limit what fields are returned when getting the GroupWise Address Book entries. If you supply this value and you have logged in as a trusted application, you can get back all of the fields.
This is also used to get all the status from the access right list in a shared folder.
When a task is originally created, the startDate is also put in the assginedDate field. After the dueDate is reached and the task has not yet been completed, the startDate is changed to the current date.
For GroupWise 2012 and later.
The attachment reference is returned with the item. getAttachmentRequest is used to retrieve the actual file attachments.
The HTML message body is included as an attachment. It is the first attachment and is named text.htm.
Retrieve the attachment information only when necessary. This view requires the POA to do more work, which affects performance.
Returns the checklist/tasklist elements: sequence number, due date, percent completed, completed date, and checklist thread.
Returns the clientMessageId. This is the same id that you will see when you open an item in the GroupWise Windows client. Select Properties and find the Message Id.
Starting in GroupWise 8.0 SP3, contact notes are not returned by default when getting contacts from a personal address book. You must now pass this value to get the contact notes.
For GroupWise 2012 and later.
If the item type is a folder, a count of items that are in the folder is returned.
If the item type is a Contact (UserContact) folder or personal address book, the count of items in the container is returned.
For GroupWise 2012 and later.
To get a specific custom value returned, you must specify the custom field name prefixed with “custom/”. For example, if you want to get the custom field “MyAppRead”, you would put “custom/MyAppRead” in the view. You must list each custom field name separately. Here is an example of getting two different custom fields:
<view>default custom/MyAppRead custom/alexStrField</view>
An important subset of elements is returned, based on the item type. Additional keywords can be included with the default keyword, which reduces the need to include all elements in the view.
The default keyword returns a different set of elements, based on the item type.
The user’s folder list is cached while the user is logged in. Use the flush keyword to make sure a fresh copy of the folders and their attributes are read when accessing a folder.
The subject text can include certain formatting codes (underline, bold and italics). To get these formatting codes returned, specify "format" in the view. The allowed formatting codes in the text are:
<b> bold on </b> bold off <i> italics on </i> italics off <u> underline on </u> underline off
These values are only on the subject field or the originalSubject field if the subject is personalized. Here is an example of a personalized subject::
<subject>This is my subject!</subject> <originalSubject><b>This</b> <u>is</u> the <i>subject</i>!</originalSubject>
Note: the '<' and '>' are escaped in the XML. The strings would be:
"This is my subject!" "<b>This</b> <u>is</u> the <i>subject</i>!"
Hidden items are returned.
Returns the members of a personal address group.
The message body is returned. If message is included, the plain text message body is returned. If message/RTF is included, the rich text format of the message body is returned.
NOTE:The plain text message body can be stored in two different formats, plain text or RTF. If you want to get the message body as plain text (no RTF codes), you request “message” in the view. If you want to get back the message body, with the RTF codes, you request “message/RTF”. If the message body is stored as plain text (no RTF codes), the message body will always be returned as plain text. We do not add RTF codes to the plain text.
Retrieve the message body only when necessary. This view requires the POA to do more work, which affects performance.
A shortened version of the item ID is returned. This shortened version matches the IMAP item ID. The SOAP version of the item ID is msgID.
In GroupWise 8.0 SP2, it was determined that getting the contact notes on contacts could significantly affect the performance of the POA. This keyword was added to not get the contact notes.
For GroupWise 8.0 SP2 and later.
In GroupWise 8.0, the display settings for folders where returned by default. Setting noDisplay prevents those settings from being returned.
For GroupWise 8.0 SP2 and later.
Usually, when the peek flag is passed in the view and the message body is requested, the item is not marked as opened. A third-party downloaded flag is set to indicate that the user may have seen the message body. In some cases, this is undesirable. It gives a user an indication that someone or some application has viewed the message body. Pass this keyword to prevent the third-party downloaded flag from being set. This flag is dependent on the application having logged into the user’s account with a trusted application name and key.
For GroupWise 8.0 SP3 and later.
By default, if you log in with a trusted application, you get all entries from the GroupWise Address Book (even the hidden ones). If you want to be able to only get the entries the user has rights to see, you must pass “normal” in the view.
If an application reads an item and its message body, the item is marked as opened and read. With the peek keyword, however, the item is marked as opened but not read. The item is marked as downloaded by a third party.
The recipients list is returned. Typically, the recipient or recipients keyword is required only if you are responding to a distribution list. If you need to display the recipients, there is a string representation of the To, CC, and BC fields that are returned with the default keyword.
Retrieve the recipient's information only when necessary. This view requires the POA to do more work, which affects performance.
When a user sends an item to other users, recipientStatus information is tracked. On sent items, the recipientStatus information is returned. Also, recipientStatus is available to the received item if you are the sender of the item. The recipientStatus implies recipients and recipient information is returned also.
Retrieve the recipientStatus information only when necessary. This view requires the POA to do more work, which affects performance.
Returns the RSS URL.
If you put sid in the view, the <sid> values are returned as the values in the <item> elements.
For GroupWise 8.0 HP1 and later.
If you put sid and sids in the view, the <sid> values are returned in a space delimited <sids> element instead of the <items> element.
For GroupWise 2012 and later.
Returns stubbed items. See the stubbing/archive documentation for more information.
Returns the discussion threading for an item.
If the item type is a folder, the count of unread items that are in the folder is returned.
Returns the MIME RFC 822 X-Field values.
For GroupWise 2012 and later.
The following list of elements can be added to the view:
message
message/RTF
acceptLevel
allDayEvent
itemType
startDate
delivered
source
company
caller
phone
created
endDate
to
cc
bc
from
name
timezone
attachment
attachments
peek
default
hidden
modified
id
msgId
messageID
place
subject
priority
recipientStatus
uuid
version
security
statusTracking
requestReply
sendoptions
iCalId
recurrenceKey
recipients
recipient
recipientStatus
hasAttachments
count
unReadCount
parent
description
sequence
all
container
priority
expires
created
size
smimeType
subType
mimeEncoding
nntpOrImap
alarm
all (for GroupWise Address Book fields)
category
checklist
clientMessageId
flush
members
normal (for GroupWise Address Book entries)
originalSubject
rssURL
stored (Return the stored name folder name for a system folder instead of the language dependent name.)
stubbed
threading
The following list of elements were added in GroupWise 8.0 SP2:
noDisplay
noContactNotes
The following list of elements were added in GroupWise 8.0 SP3:
contactNotes
noDownload
retentionModified
The following list of elements were added in GroupWise 2012:
assignedDate
pabName (Return the address book name as the name of the corresponding user contact folder.)
xField
This section contains the following examples:
The following example gets an item from the Mailbox with the default view by calling getItemsRequest:
<getItemsRequest> <container>7.domain1.po1.100.0.1.0.1@16</container> <view>default</view> </getItemsRequest>
<getItemsResponse> <items> <item> <id>43BA73CB.domain1.po1.100.1676834.1.6FB.1@1:7. domain1.po1.100.0.1.0.1@16</id> <version>3</version> <modified>2012-01-03T19:59:40Z</modified> <container>7.domain1.po1.100.0.1.0.1@16</container> <created>2012-01-03T19:53:31Z</created> <status> <opened>1</opened> <read>1</read> </status> <msgId>43BA73CB.domain1.po1.200.20000CB.1.111D.1</msgId> <source>received</source> <delivered>2012-01-03T19:53:31Z</delivered> <security>Normal</security> <subject>Fwd: Test Message from U1</subject> <distribution> <from> <displayName>u1</displayName> <email>u1.po1.domain1</email> <uuid>1DEB6970-175B-0000-890F-6E00D5004E00</uuid> </from> <to>u2</to> <sendoptions> <statusTracking>None</statusTracking> </sendoptions> </distribution> <options> <priority>Standard</priority> </options> <hasAttachment>1</hasAttachment> <size>1189</size> </item> </items> <status> <code>0</code> </status> </getItemsResponse>
The following example is the same as the preceding one, except that it includes the attachments, recipients, message, and peek keywords by calling getItemRequest. It also contains the attachments, recipients, and message elements.
<getItemRequest> <id>4512B362.domain1.po1.100.1676834.1.798.1@1:7. domain1.po1.100.0.1.0.1@16</id> <view>default message attachments recipients peek</view> </getItemRequest> <getItemResponse>
<item> <id>4512B362.domain1.po1.100.1676834.1.798.1@1:7. domain1.po1.100.0.1.0.1@16</id> <version>2</version> <modified>2012-09-21T21:44:48Z</modified> <container>7.domain1.po1.100.0.1.0.1@16</container> <created>2012-09-21T21:44:34Z</created> <status/> <msgId>4512B362.domain1.po1.200.20000CA.1.673.1</msgId> <messageId><4512B362.261E.00CA.0@phantom.com></messageId> <source>received</source> <delivered>2012-09-21T21:44:34Z</delivered> <security>Normal</security> <subject>Test message</subject> <distribution> <from> <displayName>u2</displayName> <email>u2@phantom.com</email> <uuid>42F9A600-175B-0000-890F-6E00D5004E00</uuid> </from> <to>u2</to> <recipients> <recipient> <displayName>u2</displayName> <email>u2@phantom.com</email> <uuid>42F9A600-175B-0000-890F-6E00D5004E00</uuid> <distType>TO</distType> <recipType>User</recipType> </recipient> </recipients> <sendoptions> <statusTracking>None</statusTracking> </sendoptions> </distribution> <message> <part contentType="text/plain" length="40">VGhpcyBpcyBhIG1lc3NhZ2UgYm9keS4KCmFzZGYK</part> </message> <attachments> <attachment> <id>4512B362.domain1.po1.200.20000CA.1.671.1@45: 4512B362.domain1.po1.100.1676834.1.798.1@1:7. domain1.po1.100.0.1.0.1@16</id> <name>Web Services Abstracts.odt</name> <contentType>application/vnd.oasis. opendocument.text</contentType> <size>15500</size> <date>2012-09-15T12:39:06Z</date> <hidden>0</hidden> </attachment> </attachments> <options> <priority>Standard</priority> </options> <hasAttachment>1</hasAttachment> <size>16346</size> </item> <status> <code>0</code> </status> </getItemResponse>