1.8 Free/Busy

Free/busy information is a real-time view of calendar free/busy time for a set of users. The free/busy time is returned in blocks of time. Each block of time has an associated acceptLevel of free, busy, tentative, or out of the office.

There are three methods used in retrieving free/busy time:

  • startFreeBusySessionRequest, which creates a server-side object to gather free/busy information for a set of users with a start and end date.

  • closeFreeBusySessionRequest, which destroys the server-side object and should be called when a free/busy search is complete.

  • getFreeBusyRequest, which retrieves the free/busy blocks for the users provided in the startFreebusySessionRequest.

Because of the real-time lookup, it might take time to gather free/busy blocks for users on different post offices. In the getFreeBusyResponse, there is a freebusystats element, which returns the total number of users in the free/busy call. It also returns the number of users that have responded with free/busy information and the number of outstanding users that have not returned busy/free information yet. You might need to call getFreeBusyRequest more than one time to retrieve all the free/busy time for the list of users. If a user has proxy rights to a user, the subject is returned in the free/busy block.

In the following example, startFreeBusySessionRequest provides a list of users and a start and end date for the free/busy search. The startFreeBusySessionResponse returns a freeBusySessionId, which identifies the server-side free/busy. The freeBusySessionId needs to be passed in as a parameters to both the getFreeBusyRequest and the closeFreeBusySessionRequest.

<startFreeBusySessionRequest> 
   <users> 
      <user> 
         <displayName>u2</displayName> 
         <email>u2@phantom.com</email> 
         <uuid>42F9A600-175B-0000-890F-6E00D5004E00</uuid> 
      </user> 
      <user> 
         <displayName>FIRST01010000 LAST01010000</displayName> 
         <email>USER01010000@phantom.com</email> 
         <uuid>07B4A660-18CA-0000-B989-BA00EB000D00</uuid> 
      </user> 
   </users> 
   <startDate>20121009T060000Z</startDate> 
   <endDate>20121030T060000Z</endDate> 
</startFreeBusySessionRequest>

<startFreeBusySessionResponse> 
   <freeBusySessionId>4250</freeBusySessionId> 
   <status> 
      <code>0</code> 
   </status> 
</startFreeBusySessionResponse>

In the following request, one user out of two has responded. The freeBusyInfo element returns the blocks of free/busy time for the one user. You might want to wait up to a minute to call getFreeBusyRequest to get the free/busy time for the second user.

<getFreeBusyRequest> 
   <freeBusySessionId>4250</freeBusySessionId> 
</getFreeBusyRequest>
<getFreeBusyResponse> 
   <freeBusyStats> 
      <responded>1</responded> 
      <outstanding>1</outstanding> 
      <total>2</total> 
   </freeBusyStats> 
   <freeBusyInfo> 
      <user> 
         <email>u2@phantom.com</email> 
         <uuid>42F9A600-175B-0000-890F-6E00D5004E00</uuid> 
         <blocks> 
            <block> 
               <startDate>2012-10-09T06:00:00Z</startDate> 
               <endDate>2012-10-09T14:00:00Z</endDate> 
               <acceptLevel>Busy</acceptLevel> 
            </block> 
            ...
            <block> 
               <startDate>2012-10-27T23:00:00Z</startDate> 
               <endDate>2012-10-30T07:00:00Z</endDate> 
               <acceptLevel>OutOfOffice</acceptLevel> 
            </block> 
         </blocks> 
      </user> 
   </freeBusyInfo> 
   <status> 
      <code>0</code> 
   </status> 
</getFreeBusyResponse>

To destroy the server-side free/busy session, call closeFreeBusySessionRequest.

<closeFreeBusySessionRequest> 
   <freeBusySessionId>4250</freeBusySessionId> 
</closeFreeBusySessionRequest>

<closeFreeBusySessionResponse> 
   <status> 
      <code>0</code> 
   </status> 
</closeFreeBusySessionResponse>

Starting with GroupWise 8.0 SP3, external users are not included in the list of free/busy users. The startFreeBusySessionRequest returns the users that are external in the problems element.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<SOAP-ENV:Envelope
  xmlns:SOAPSDK1="http://www.w3.org/2001/XMLSchema"
  xmlns:SOAPSDK2="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header SOAP-ENV:encodingStyle="">
    <session>XVNjlFPCVRwvvrED</session>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body SOAP-ENV:encodingStyle="">
    <startFreeBusySessionRequest>
      <users>
        <user>
          <displayName>Preston Stephenson</displayName>
          <email>Preston.Stephenson@myhost.com</email>
        </user>
        <user>
          <displayName>Preston Stephenson</displayName>
          <email>pstephenson@prestons.provo.novell.com</email>
          <uuid>2D16B180-0922-0000-846C-82BD300F9E1C</uuid>
        </user>
      </users>  
      <startDate>20110119T070000Z</startDate>
      <endDate>20110209T070000Z</endDate>
    </startFreeBusySessionRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:SOAPSDK2="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:SOAPSDK1="http://www.w3.org/2001/XMLSchema">
  <SOAP-ENV:Header SOAP-ENV:encodingStyle=""/>
  <SOAP-ENV:Body SOAP-ENV:encodingStyle="">
    <startFreeBusySessionResponse>
      <freeBusySessionId>154702</freeBusySessionId>
      <status>
        <code>0</code>
        <problems>
          <entry>
            <element>Preston.Stephenson@myhost.com</element>
            <code>53505</code>
            <description>User not on post office</description>
          </entry>
        </problems>
      </status>
    </startFreeBusySessionResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

NOTE:The ProblemEntry only has one element entry. The value that is put in the element entry is from the user element from the request. The order of the value to add is the email, displayName, then uuid element values.

Starting in GroupWise 2012, the external email addresses are dropped by default. There are two optional attributes that can be put on the FreeBusyUserList element: external and externalGroupWise.If 1 or true is passed for the value of the attribute, the external email address is passed in the free/busy search.The external attribute passes in all external users. The externalGroupWise attribute only passes GroupWise users that are in external domains.