Filter uncanny-automator

automator_api_call

Filters parameters for an outgoing API call, allowing modifications before the request is sent.

add_filter( 'automator_api_call', $callback, 10, 1 );

Description

This filter hook, `automator_api_call`, fires before an API call is processed. Developers can use it to modify or add parameters to the API request, allowing for custom data manipulation or integration-specific adjustments. It's crucial to maintain the expected array structure for `$params`.

Usage

add_filter( 'automator_api_call', 'your_function_name', 10, 1 );

Parameters

$params (mixed): This parameter contains the arguments passed to the API call, which can be filtered and modified by various hooks.

Return Value

The filtered value.

Examples

/**
 * Example: Modify the parameters for an API call to a specific integration.
 *
 * This function demonstrates how to hook into 'automator_api_call' to modify
 * the parameters before an API call is made. In this specific example,
 * it checks if the integration is 'google_sheets' and, if so, modifies the
 * 'body' to ensure a specific sheet ID is used.
 *
 * @param array $params The parameters for the API call.
 * @return array The modified parameters.
 */
add_filter(
	'automator_api_call',
	function ( $params ) {
		// Check if the integration is 'google_sheets'
		if ( ! empty( $params['integration'] ) && 'google_sheets' === $params['integration'] ) {
			// Ensure the 'body' key exists and is an array
			if ( ! isset( $params['body'] ) || ! is_array( $params['body'] ) ) {
				$params['body'] = array();
			}

			// Example: Add or override a specific sheet ID if it's not already set.
			// In a real-world scenario, this might come from a user setting or a dynamic source.
			$default_sheet_id = 'YOUR_DEFAULT_SPREADSHEET_ID'; // Replace with a real default ID.
			if ( empty( $params['body']['sheet_id'] ) ) {
				$params['body']['sheet_id'] = $default_sheet_id;
			}

			// Example: Log or display the modified parameters for debugging.
			// error_log( 'Modified Google Sheets API params: ' . print_r( $params, true ) );
		}

		// Always return the parameters, modified or not.
		return $params;
	},
	10, // Priority
	1  // Accepted arguments
);

/**
 * Example: Modify parameters for a specific action within an integration.
 *
 * This example hooks into a more specific filter: 'automator_google_sheets_create_row_api_call'.
 * It demonstrates how to modify parameters only when the integration is 'google_sheets'
 * and the action within the API call body is 'create_row'.
 *
 * @param array $params The parameters for the API call.
 * @return array The modified parameters.
 */
add_filter(
	'automator_google_sheets_create_row_api_call',
	function ( $params ) {
		// Example: Ensure that the 'values' for creating a row are formatted as an array of arrays.
		// This is a common requirement for many spreadsheet APIs.
		if ( isset( $params['body']['values'] ) && ! empty( $params['body']['values'] ) ) {
			// If 'values' is a simple array, wrap it in another array to represent a single row.
			if ( ! is_array( $params['body']['values'][0] ) ) {
				$params['body']['values'] = array( $params['body']['values'] );
			}
		} else {
			// If 'values' is missing, ensure it's an empty array to avoid errors downstream.
			$params['body']['values'] = array();
		}

		// Example: Add a timestamp to the row data if a specific column is designated.
		// Let's assume there's a column named 'automator_timestamp'.
		if ( ! empty( $params['body']['values'] ) && is_array( $params['body']['values'][0] ) ) {
			$header_row = array( 'automation_id', 'user_id', 'timestamp', 'automator_timestamp' ); // Example headers
			$timestamp_column_index = array_search( 'automator_timestamp', $header_row );

			if ( $timestamp_column_index !== false ) {
				// Ensure the row has enough columns to insert the timestamp
				while ( count( $params['body']['values'][0] ) <= $timestamp_column_index ) {
					$params['body']['values'][0][] = ''; // Pad with empty strings if necessary
				}
				$params['body']['values'][0][ $timestamp_column_index ] = current_time( 'mysql' );
			}
		}


		// Always return the parameters.
		return $params;
	},
	10, // Priority
	1  // Accepted arguments
);

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/core/classes/class-api-server.php:328

public function filter_params( $params ) {

		$params = apply_filters( 'automator_api_call', $params );

		if ( ! empty( $params['integration'] ) ) {
			$params = apply_filters( 'automator_' . $params['integration'] . '_api_call', $params );

			if ( ! empty( $params['body']['action'] ) ) {
				$params = apply_filters( 'automator_' . $params['integration'] . '_' . $params['body']['action'] . '_api_call', $params );
			}
		}

		return $params;
	}