ProjectDocument.getTaskByIndexAsync method

Asynchronously gets the GUID of the task that has the specified index in the task collection.

Important: This API works only in Project 2016 on Windows desktop.

Office.context.document.getTaskByIndexAsync(taskIndex[, options][, callback]);

Parameters

taskIndex
    Type: number

    The index of the task in the collection of tasks for the project. Required.

options
    The following optional parameter:

    _asyncContext_
        Type: 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. Optional.

        For example, you can pass the asyncContext argument by using the format {asyncContext: 'Some text'} or {asyncContext: <object>}.

callback
    Type: function

    A function that is invoked when the method call returns, where the only parameter is of type AsyncResult. Optional.

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 getTaskByIndexAsync method, the returned AsyncResult object contains following properties.

Remarks

To get the maximum index of the collection of tasks for the project, use the getMaxTaskIndexAsync method. The 0 index task represents the project summary task.

Example

The following code example calls getMaxTaskIndexAsync to get the maximum index in the project's task collection, and then calls getTaskByIndexAsync to get the GUID for each task.

The example assumes that 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";
    var taskGuids = [];

    // 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.
            app.initialize();
            $('#get-info').click(getTaskInfo);
        });
    };

    // Get the maximum task index, and then get the task GUIDs.
    function getTaskInfo() {
        getMaxTaskIndex().then(
            function (data) {
                getTaskGuids(data);
            }
        );
    }

    // Get the maximum index of the tasks for the current project.
    function getMaxTaskIndex() {
        var defer = $.Deferred();
        Office.context.document.getMaxTaskIndexAsync(
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    onError(result.error);
                }
                else {
                    defer.resolve(result.value);
                }
            }
        );
        return defer.promise();
    }

    // Get each task GUID, and then display the GUIDs in the add-in.
    function getTaskGuids(maxTaskIndex) {
        var defer = $.Deferred();
        for (var i = 0; i <= maxTaskIndex; i++) {
            getTaskGuid(i);
        }
        return defer.promise();
        function getTaskGuid(index) {
            Office.context.document.getTaskByIndexAsync(index,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        taskGuids.push(result.value);
                        if (index == maxTaskIndex) {
                            defer.resolve();
                            $('#message').html(taskGuids.toString());
                        }
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
    }
    function onError(error) {
        app.showNotification(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.

Support history

See also

Other resources

getMaxTaskIndexAsync AsyncResult object ProjectDocument object