ProjectDocument.setResourceFieldAsync method

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

Office.context.document.setResourceFieldAsync(resourceId, fieldId, fieldValue[, options][, callback]);

Parameters

resourceId
    The GUID of the resource. Required.

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

fieldValue
    The value for the target field, as 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 setResourceFieldAsync method, the returned AsyncResult object contains following properties.

Remarks

First call the getSelectedResourceAsync or getResourceByIndexAsync method to get the resource GUID, and then pass the GUID as the resourceId argument to setResourceFieldAsync. Only a single field for a single resource can be updated in each asynchronous call.

Example

The following code example calls getSelectedResourceAsync to get the GUID of the resource that's currently selected in a resource view. Then it sets two resource field values by calling setResourceFieldAsync 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(setResourceInfo);
        });
    };

    // Get the GUID of the resource, and then get the resource fields.
    function setResourceInfo() {
        getResourceGuid().then(
            function (data) {
                setResourceFields(data);
            }
        );
    }

    // Get the GUID of the selected resource.
    function getResourceGuid() {
        var defer = $.Deferred();
        Office.context.document.getSelectedResourceAsync(
            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 resource.
    function setResourceFields(resourceGuid) {
        var targetFields = [Office.ProjectResourceFields.StandardRate, Office.ProjectResourceFields.Notes];
        var fieldValues = [.28, 'Notes for the resource.'];

        // Set the field value. If the call is successful, set the next field.
        for (var i = 0; i < targetFields.length; i++) {
            Office.context.document.setResourceFieldAsync(
                resourceGuid,
                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

getSelectedResourceAsync getResourceByIndexAsync AsyncResult object ProjectResourceFields enumeration ProjectDocument object