ProjectDocument.setTaskFieldAsync method (JavaScript API for Office v1.1)

Asynchronously sets the value of the specified field for the specified task. Important: This API works only in Project 2016 on Windows desktop.

Office.context.document.setTaskFieldAsync(taskId, fieldId, fieldValue[, options][, callback]);

Parameters

taskId
    The GUID of the task. Required.

fieldId
    The ID of the target field, as a ProjectTaskFields constant or its corresponding integer value. Required.

fieldValue
    The value for the target field, as a string, number, boolean, or object. 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 setTaskFieldAsync method, the returned AsyncResult object contains following properties.

Remarks

First call the getSelectedTaskAsync or getTaskByIndexAsync method to get the task GUID, and then pass the GUID as the taskId argument to setTaskFieldAsync. Only a single field for a single task can be updated in each asynchronous call.

Example

The following code example calls getSelectedTaskAsync to get the GUID of the task that's currently selected in a task view. Then it sets two task field values by calling setTaskFieldAsync recursively.

The getSelectedTaskAsync method used in the example requires that a task view (for example, Task Usage) is the active view and that a task is selected. See the addHandlerAsync method for an example that activates a button based on the active view type.

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="set-info" type="button" value="Set 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.
            app.initialize();
            $('#set-info').click(setTaskInfo);
        });
    };

    // Get the GUID of the task, and then get the task fields.
    function setTaskInfo() {
        getTaskGuid().then(
            function (data) {
                setTaskFields(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();
    }

    // Set the specified fields for the selected task.
    function setTaskFields(taskGuid) {
        var targetFields = [Office.ProjectTaskFields.Active, Office.ProjectTaskFields.Notes];
        var fieldValues = [true, 'Notes for the task.'];

        // Set the field value. If the call is successful, set the next field.
        for (var i = 0; i < targetFields.length; i++) {
            Office.context.document.setTaskFieldAsync(
                taskGuid,
                targetFields[i],
                fieldValues[i],
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        i++;
                    }
                    else {
                        onError(result.error);
                    }
                }
            );
        }
        $('#message').html('Field values set');
    }

    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

getSelectedTaskAsync method getTaskByIndexAsync AsyncResult object ProjectTaskFields enumeration ProjectDocument object