Docs API Reference

ProjectDocument.getTaskAsync method

Asynchronously gets the specified task's name, assigned resources, and the ID of the task in the synchronized SharePoint task list.

Hosts: Project
Available in Requirement set Selection
Added in 1.0
Office.context.document.getTaskAsync(taskId [,options][, callback]);

Parameters

Name Type Description Support notes
taskId string The GUID of the task. Required.
options object Specifies any of the following optional parameters.
asyncContext array, boolean, null, number, object, string, or undefined A user-defined item of any type that is returned in the AsyncResult object without being altered.
callback object A function that is invoked when the callback returns, whose only parameter is of type AsyncResult.

Callback Value

When the callback function executes, it receives an AsyncResult object that you can access from the parameter in the callback function.

For the getTaskAsync method, the returned AsyncResult object contains following properties.


Name Description
asyncContext The data passed in the optional asyncContext parameter, if the parameter was used.
error Information about the error, if the status property equals failed.
status The succeeded or failed status of the asynchronous call.
value Contains the following properties:

  • taskName - The name of the task.
  • wssTaskId - The ID of the task in the synchronized SharePoint task list. If the project is not synchronized with a SharePoint task list, the value is 0.
  • resourceNames - The comma-separated list of the names of resources that are assigned to the task.

Remarks

Before you call the getTaskAsync method, call the getSelectedTaskAsync method to get the GUID of the task.

Example

The following code example calls getSelectedTaskAsync to get the task GUID of the currently selected task. Then it calls getTaskAsync to get the properties for the task that are available from the JavaScript API for Office.

The example assumes your add-in has a reference to the jQuery library and that the following page controls are defined in the content div in the page body.

<input id="get-info" type="button" value="Get info" /><br />
<span id="message"></span>
(function () {
    "use strict";

    // The initialize function must be run each time a new page is loaded.
    Office.initialize = function (reason) {
        $(document).ready(function () {

            // After the DOM is loaded, add-in-specific code can run.
            $('#get-info').click(getTaskInfo);
        });
    };

    // Get the GUID of the task, and then get local task properties.
    function getTaskInfo() {
        getTaskGuid().then(
            function (data) {
                getTaskProperties(data);
            }
        );
    }

    // Get the GUID of the selected task.
    function getTaskGuid() {
        var defer = $.Deferred();
        Office.context.document.getSelectedTaskAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get local properties for the selected task, and then display it in the add-in.
    function getTaskProperties(taskGuid) {
        Office.context.document.getTaskAsync(
            taskGuid,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    var taskInfo = result.value;
                    var output = String.format(
                        'Name: {0}<br/>GUID: {1}<br/>SharePoint task ID: {2}<br/>Resource names: {3}',
                        taskInfo.taskName, taskGuid, taskInfo.wssTaskId, taskInfo.resourceNames);
                    $('#message').html(output);
                }
            }
        );
    }

    function onError(error) {
        $('#message').html(error.name + ' ' + error.code + ': ' + error.message);
    }
})();

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Office for Windows desktop Office Online (in browser)
Project Y
Available in requirement sets Selection
Minimum permission level ReadDocument
Add-in types Task pane
Library Office.js
Namespace Office

Support history

Version Changes
1.0 Introduced

See also

Other resources

getSelectedTaskAsync method AsyncResult object ProjectDocument object