Office.AsyncResult interface

  • Reference
Package:
office

An object which encapsulates the result of an asynchronous request, including status and error information if the request failed.

When the function you pass to the callback parameter of an "Async" method executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

Remarks

Examples

// The following is an example applicable to content and task pane add-ins.
// The example shows a call to the getSelectedDataAsync method of the Document object.
Office.context.document.getSelectedDataAsync(
    Office.CoercionType.Text,
    {
        valueFormat: Office.ValueFormat.Unformatted,
        filterType: Office.FilterType.All
    },
    (result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            const dataValue = result.value; // Get selected data.
            console.log('Selected data is ' + dataValue);
        } else {
            const err = result.error;
            console.log(err.name + ": " + err.message);
        }
    }
);
// The anonymous function passed as the callback argument ((result) => {...}) has a single 
// parameter named result that provides access to an AsyncResult object when the function executes.
// When the call to the getSelectedDataAsync method completes, the callback function executes, 
// and the following line of code accesses the value property of the AsyncResult object to 
// return the data selected in the document:
// const dataValue = result.value;
// Note that other lines of code in the function use the result parameter of the callback function 
// to access the status and error properties of the AsyncResult object.

Properties

asyncContext

Gets the user-defined item passed to the optional asyncContext parameter of the invoked method in the same state as it was passed in. This returns the user-defined item (which can be of any JavaScript type: String, Number, Boolean, Object, Array, Null, or Undefined) passed to the optional asyncContext parameter of the invoked method. Returns Undefined, if you didn't pass anything to the asyncContext parameter.
diagnostics

Gets an object that may provide additional information if an error occurred.
error

Gets an Office.Error object that provides a description of the error, if any error occurred.
status

Gets the Office.AsyncResultStatus of the asynchronous operation.
value

Gets the payload or content of this asynchronous operation, if any.

Property Details

asyncContext

Gets the user-defined item passed to the optional asyncContext parameter of the invoked method in the same state as it was passed in. This returns the user-defined item (which can be of any JavaScript type: String, Number, Boolean, Object, Array, Null, or Undefined) passed to the optional asyncContext parameter of the invoked method. Returns Undefined, if you didn't pass anything to the asyncContext parameter.

asyncContext: any;

Property Value

any

Examples

function getDataWithContext() {
    const format = "Your data: ";
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text, 
        { asyncContext: format }, 
        showDataWithContext);
}

function showDataWithContext(asyncResult) {
    write(asyncResult.asyncContext + asyncResult.value);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

Gets an object that may provide additional information if an error occurred.

diagnostics: any;

Property Value

any

Remarks

This property returns additional information if the following errors occur with these supported APIs.

Supported APIs

Office.context.mailbox.item.getCallbackTokenAsync, Office.context.mailbox.item.getUserIdentityTokenAsync

Supported errors

AsyncResult.error.name AsyncResult.error.message Description of diagnostics object returned
HTTPRequestFailure The request has failed. Please look at the diagnostics object for the HTTP error code. The HTTP error code in a JSON object e.g., {"HTTPCode":"401"}.
InternalServerError The Exchange server returned an error. Please look at the diagnostics object for more information. The error message from the Exchange server in a JSON object e.g., {"ErrorText": "The mailbox database is temporarily unavailable"}.

error

Gets an Office.Error object that provides a description of the error, if any error occurred.

error: Office.Error;

Property Value

Office.Error

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

status

Gets the Office.AsyncResultStatus of the asynchronous operation.

status: AsyncResultStatus;

Property Value

Office.AsyncResultStatus

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

value

Gets the payload or content of this asynchronous operation, if any.

value: T;

Property Value

T

Remarks

You access the AsyncResult object in the function passed as the argument to the callback parameter of an "Async" method, such as the getSelectedDataAsync and setSelectedDataAsync methods of the Document object.

Note: What the value property returns for a particular "Async" method varies depending on the purpose and context of that method. To determine what is returned by the value property for an "Async" method, refer to the "Callback value" section of the method's topic.

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}