How to: Get or set the time when composing an appointment in Outlook

apps for Office

Learn how to get or set the time of an appointment in Outlook.

Last modified: February 27, 2014

Applies to: Exchange Online | Exchange Server 2013 SP1 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.1

   Apps for Office manifests schema: v1.1

Note Note

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
Prerequisites for getting or setting the start or end time in a compose form
To get the start or end time
To set the start or end time
Additional resources

The JavaScript API for Office provides asynchronous methods (getAsync and setAsync of the Time object) to get and set the start or end time of an appointment that the user is composing. These asynchronous methods are available to only compose apps. To use these methods, make sure you have set up the app manifest appropriately for Outlook to activate the mail app in compose forms, as described in the section Setting up mail apps for compose forms of Create mail apps for compose forms in Outlook.

The start and end properties are available for appointments in both compose and read forms. In a read form, you can access the properties directly from the parent object, as in:

item.start

and in:

item.end

But in a compose form, because both the user and your mail app can be inserting or changing the time at the same time, you must use the asynchronous method getAsync to get the start or end time, as shown below:

item.start.getAsync

and:

item.end.getAsync

As with most asynchronous methods in the JavaScript API for Office, getAsync and setAsync take optional input parameters. For more information about specifying these optional input parameters, see passing optional parameters to asynchronous methods in Asynchronous programming in apps for Office.

This section shows a code sample that gets the start time of the appointment that the user is composing and displays the time. You can use the same code and replace the start property by the end property to get the end time. This code sample assumes a rule in the app manifest that activates the mail app in a compose form for an appointment, as shown below.

<Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>

To use item.start.getAsync or item.end.getAsync, provide a callback method that checks for the status and result of the asynchronous call. You can provide any necessary arguments to the callback method through the asyncContext optional parameter. You can obtain status, results and any error using the output parameter asyncResult of the callback. If the asynchronous call is successful, you can get the start time as a Date object in UTC format using the AsyncResult.value property.

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the start time of the item being composed.
        getStartTime();
    });
}

// Get the start time of the item that the user is composing.
function getStartTime() {
    item.start.getAsync(
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully got the start time, display it, first in UTC and 
                // then convert the Date object to local time and display that.
                write ('The start time in UTC is: ' + asyncResult.value.toString());
                write ('The start time in local time is: ' + asyncResult.value.toLocaleString());
            }
        });
}

// Write to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

This section shows a code sample that sets the start time of the appointment or message that the user is composing. You can use the same code and replace the start property by the end property to set the end time. Note that if the appointment compose form already has an existing start time, setting the start time subsequently will adjust the end time to maintain any previous duration for the appointment. If the appointment compose form already has an existing end time, setting the end time subsequently will adjust both the duration and end time. If the appointment has been set as an all-day event, setting the start time will adjust the end time to 24 hours later, and uncheck the UI for the all-day event in the compose form.

Similar to the previous example, this code sample assumes a rule in the app manifest that activates the mail app in a compose form for an appointment.

To use item.start.setAsync or item.end.setAsync, specify a Date value in UTC in the dateTime parameter. If you get a date based on an input by the user on the client, you can use Mailbox.convertToUtcClientTime to convert the value to a Date object in UTC. You can provide an optional callback method and any arguments for the callback method in the asyncContext parameter. You should check the status, result and any error message in the asyncResult output parameter of the callback. If the asynchronous call is successful, setAsync inserts the specified start or end time string as plain text, overwriting any existing start or end time for that item.

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Set the start time of the item being composed.
        setStartTime();
    });
}

// Set the start time of the item that the user is composing.
function setStartTime() {
    var startDate = new Date("September 27, 2012 12:30:00");
    
    item.start.setAsync(
        startDate,
        { asyncContext: { var1: 1, var2: 2 } },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully set the start time.
                // Do whatever appropriate for your scenario
                // using the arguments var1 and var2 as applicable.
            }
        });
}

// Write to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
Show:
© 2014 Microsoft