ProjectDocument.getProjectFieldAsync method

Asynchronously gets the value of the specified field in the active project.


Hosts:	Project
Available in Requirement set	Selection
Added in	1.0

Office.context.document.getProjectFieldAsync(fieldId[, options][, callback]);

Parameters

Name	Type	Description
fieldId	ProjectProjectFields	The ID of the target field. 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 getProjectFieldAsync method, the returned AsyncResult object contains the 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 fieldValue property, which represents the value of the specified field.

Example

The following code example gets the values of three specified fields for the active project, and then displays the values in the add-in.

The example calls getProjectFieldAsync recursively, after the previous call returns successfully. It also tracks the calls to determine when all calls are sent.

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

<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 () {

            // Get information for the active project.
            getProjectInformation();
        });
    };

    // Get the specified fields for the active project.
    function getProjectInformation() {
        var fields =
            [Office.ProjectProjectFields.Start, Office.ProjectProjectFields.Finish, Office.ProjectProjectFields.GUID];
        var fieldValues = ['Start: ', 'Finish: ', 'GUID: '];
        var index = 0; 
        getField();

        // Get each field, and then display the field values in the add-in.
        function getField() {
            if (index == fields.length) {
                var output = '';
                for (var i = 0; i < fieldValues.length; i++) {
                    output += fieldValues[i] + '<br />';
                }
                $('#message').html(output);
            }
            else {
                Office.context.document.getProjectFieldAsync(
                    fields[index],
                    function (result) {

                        // If the call is successful, get the field value and then get the next field.
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            fieldValues[index] += result.value.fieldValue;
                            getField(index++);
                        }
                        else {
                            onError(result.error);
                        }
                    }
                );
            }
        }
    }

    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
Minimum permission level	ReadDocument
Add-in types	Task pane
Library	Office.js
Namespace	Office

Support history

Version	Changes
1.0	Introduced

Docs