wsf_submit_note_add

Description

The wsf_submit_note_add PHP function adds a note to a submission.

Usage

wsf_submit_note_add( $submit_id, $content, $meta, $user_id, $user_name, $locked );

Parameters

$submit_id Integer
Submission ID
$content String
Note text
$meta Array
An array containing meta data for the note. See example below.
$user_id Integer
WordPress user ID. If greater than 0, that user’s display name is used and $user_name is ignored.
$user_name String
Label used when $user_id is 0, such as the name of a custom integration or system.
$locked Boolean
If true, the note cannot be edited or deleted in the admin. Defaults to false.

Return

$submit_note_id Integer

Returns the newly created note ID as an integer.

Example

The following example adds a locked submission note after a CRM integration has successfully processed a submission. The note includes structured meta values, action buttons, a custom author name, and cannot be edited or deleted from the Submissions admin.

$submit_id = 123;

$meta = array(

	'values' => array(

		'Status'        => 'Completed',
		'Reference ID'  => 'CRM-48291',
		'Response Time' => '245 ms'
	),

	'buttons' => array(

		array(

			'url'    => admin_url(
				'admin.php?page=my-plugin-history&submit_id=' . $submit_id
			),
			'label'  => 'View History',
			'type'   => 'primary',
			'target' => '_blank'
		),

		array(

			'url'   => admin_url(
				'admin.php?page=my-plugin-settings'
			),
			'label' => 'Settings',
			'type'  => 'secondary'
		)
	)
);

$note_id = wsf_submit_note_add(
	$submit_id,
	'The submission was successfully synchronized with the CRM.',
	$meta,
	0,
	'My CRM Integration',
	true
);

if ( $note_id ) {

	error_log(
		sprintf(
			'Submission note %d was added to submission %d.',
			$note_id,
			$submit_id
		)
	);
}

In this example:

$submit_id specifies the submission the note should be added to.
$content contains the main note text.
$meta['values'] adds structured label/value pairs that appear beneath the note.
$meta['buttons'] adds action buttons that link to related pages.
$user_id is set to 0, so $user_name (My CRM Integration) is shown as the note author.
$locked is set to true, preventing the note from being edited or deleted in the Submissions admin.

Using The $meta Parameter

The $meta parameter is an optional associative array that allows you to attach structured information to a submission note. It supports two optional keys:

values – Displays label/value pairs alongside the note.
buttons – Displays one or more action buttons beneath the note.

A typical $meta array looks like this:

$meta = array(

	'values' => array(

		'Status'       => 'Completed',
		'Reference ID' => 'CRM-48291'
	),

	'buttons' => array(

		array(

			'url'   => admin_url( 'admin.php?page=my-plugin-history' ),
			'label' => 'View History',
			'type'  => 'primary'
		)
	)
);

Values

The values element is an associative array where each array key becomes a label and each array value is displayed alongside it in the note.

'values' => array(

	'Status'        => 'Completed',
	'Reference ID'  => 'CRM-48291',
	'Response Time' => '245 ms'
)

Common uses for meta values include:

Integration reference IDs
Processing status
Response times
Transaction IDs
Export IDs
Workflow results

Buttons

The buttons element contains an indexed array of button definitions. Each button is rendered beneath the note and provides a convenient link to related resources.

'buttons' => array(

	array(

		'url'    => admin_url( 'admin.php?page=my-plugin-history' ),
		'label'  => 'View History',
		'type'   => 'primary',
		'target' => '_blank'
	)
)

Each button supports the following properties:

Property	Required	Description
`url`	Yes	The URL the button links to.
`label`	Yes	The text displayed on the button.
`type`	No	`primary` (default) or `secondary`.
`target`	No	Optional link target, such as `_blank`.

You can use values, buttons, or both together within the same $meta array.