Managing Notes with the GFAPI

Introduction

The GFAPI methods for managing notes were added in Gravity Forms 2.4.18.

See the GFAPI article for other available methods.

get_notes

Returns the notes for the given search criteria.

Method Overview

Class	GFAPI
Function	get_notes
Parameters	see_below
Returns	see_below

Source Code

public static function get_notes( $search_criteria = array(), $sorting = null ) {}

Parameters

Param	Type	Description
$search_criteria	array	Optional. An associative array containing the search arguments.
$sorting	array	Optional. An associative array containing the sorting arguments.

Search Arguments

An associative array supporting the following properties.

Prop	Type	Description
id	integer	The ID of the note to be retrieved.
entry_id	integer	The ID of the entry the notes are to be retrieved for.
user_id	integer	The ID of the user the notes are to be retrieved for.
user_name	string	The user_name of the user the notes are to be retrieved for.
note_type	string	The type of note to be retrieved. If the note is triggered by a Notification the note_type will be “notification”, if it is triggered by an add-on it will use that add-on slug, for GravityFlow it will be “gravityflow”.
sub_type	string	The sub type of note to be retrieved. The Sub Type indicates the status which can be: success, warning, error, etc.
start_date	string	Retrieves notes created on or after the date and time specified in the Y-m-d H:i:s format.
end_date	string	Retrieves notes created before the date and time specified in the Y-m-d H:i:s format.

Sorting Arguments

An optional associative array supporting the following properties.

Prop	Type	Description
key	string	The column to sort by. See the gf_entry_notes database table columns. Defaults to `id`.
direction	string	The direction to sort by: ASC or DESC. Defaults to ASC.

Returns

$result bool|array
False, or an array of note objects containing the gf_entry_notes database table columns as properties.

Usage Example

Getting all notes for the specified entry

$search_criteria = array( 'entry_id' => $entry_id );
$result = GFAPI::get_notes( $search_criteria );

get_note

Returns the specified note.

Method Overview

Class	GFAPI
Function	get_note
Parameters	see_below
Returns	see_below

Source Code

public static function get_note( $note_id ) {}

Parameters

Param	Type	Description
$note_id	integer	The ID of the note to be retrieved.

Returns

$result WP_Error|object
A WP_Error if the note was not found, or the note object containing the gf_entry_notes database table columns as properties.

Usage Example

$result = GFAPI::get_note( $note_id );

add_note

Adds a note to the specified entry.

Method Overview

Class	GFAPI
Function	add_note
Parameters	see_below
Returns	see_below

Source Code

public static function add_note( $entry_id, $user_id, $user_name, $note, $note_type = 'user', $sub_type = null ) {}

Parameters

Prop	Type	Description
entry_id	integer	The ID of the entry the note is being added to.
user_id	integer	The ID of the user adding the note.
user_name	string	The user_name of the user adding the note.
note	string	The content of the note being added.
note_type	string	Optional. The type of note being added. If the note is triggered by a Notification the note_type will be “notification”, if it is triggered by an add-on it will use that add-on slug. For example, for Gravity Flow it will be “gravityflow”.
sub_type	string	Optional. The subtype of note being added. The @sub_type indicates the status, which can be success, warning, error, etc.

Returns

$result WP_Error|int
A WP_Error if an error occurs, or the ID of the note returned by the database upon success.

Usage Example

Adding a user note

$result = GFAPI::add_note( $entry_id, $user_id, $user_name, 'this is a test note' );

Adding a Success note for a Notification

$result = GFAPI::add_note( $entry_id, $user_id, $user_name, 'This is a success note for Notification', 'notification', 'success' );

delete_note

Deletes the specified note.

Method Overview

Class	GFAPI
Function	delete_note
Parameters	see_below
Returns	see_below

Source Code

public static function delete_note( $note_id ) {}

Parameters

Param	Type	Description
$note_id	integer	The ID of the note to be deleted.

Returns

$result WP_Error|bool
A WP_Error if an error occurs, or true on success.

Usage Example

$result = GFAPI::delete_note( $note_id );

update_note

Updates the specified note.

Method Overview

Class	GFAPI
Function	update_note
Parameters	see_below
Returns	see_below

Parameters

Param	Type	Description
$note	array	An associative array containing the note properties.
$note_id	integer	Optional. The ID of the note to be updated when not included in the $note array.

Note Properties

An associative array supporting the following properties.

Prop	Type	Description
id	integer	The ID of the note to be updated.
entry_id	integer	The ID of the entry the note is for.
user_id	integer	The ID of the user the note was added by.
user_name	string	The user_name of the user the note was added by.
date_created	string	The date the note was created in the Y-m-d H:i:s format.
value	string	The content of the note.
note_type	string	The note type.
sub_type	string	The note sub type.

Returns

$result WP_Error|bool
A WP_Error if an error occurs, or true on success.

Usage Example

Updating the note content

$note = array( 'value' => 'the updated note' );
$result = GFAPI::update_note( $note, $note_id );