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

apps for Office

Learn how to get or set the subject when the user is composing an appointment or message in Outlook.

Last modified: November 13, 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

In this article, "Outlook" refers to Outlook for Windows, Outlook RT, OWA for Devices, and Outlook Web App. This article doesn't apply to Outlook for Mac. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

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

The JavaScript API for Office provides asynchronous methods (getAsync and setAsync of the Subject object) to get and set the subject of an appointment or message 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 subject property is available for read access in both compose and read forms of appointments and messages. In a read form, you can access the property directly from the parent object, as in:

item.subject

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

item.subject.getAsync

The subject property is available for write access in only compose forms and not in read forms.

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 subject of the appointment or message that the user is composing, and displays the subject. This code sample assumes a rule in the app manifest that activates the mail app in a compose form for an appointment or message, as shown below.

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
</Rule>

To use item.subject.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 subject as a plain text string 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 subject of the item being composed.
        getSubject();
    });
}

// Get the subject of the item that the user is composing.
function getSubject() {
    item.subject.getAsync(
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully got the subject, display it.
                write ('The subject is: ' + asyncResult.value);
            }
        });
}

// 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 subject of the appointment or message that the user is composing. 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 or message.

To use item.subject.setAsync, specify a string of up to 255 characters in the data parameter. Optionally, you can provide a 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 subject string as plain text, overwriting any existing subject 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 subject of the item being composed.
        setSubject();
    });
}

// Set the subject of the item that the user is composing.
function setSubject() {
    var today = new Date();
    var subject;

    // Customize the subject with today's date.
    subject = 'Summary for ' + today.toLocaleDateString();

    item.subject.setAsync(
        subject,
        { asyncContext: { var1: 1, var2: 2 } },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully set the subject.
                // 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