function webform_workflow_transition in Webform Workflow 7

Change the state of a submission.

Parameters

object $submission: The webform submission.

object $new_state: The new state for the submission.

string $message: A log message for the transition (optional).

object $account: The user account who made the transition (optional).

bool $notify: Whether to notify the configured user(s) about this transition (defaults to TRUE).

bool $set_message: Whether to display a message to the current user about this transition.

6 calls to webform_workflow_transition()

WebformWorkflowPermissionsTestCase::testFromTo in tests/webform_workflow_permissions.test

Test permissions for changing a submission's state.

WebformWorkflowPermissionsTestCase::testViewEdit in tests/webform_workflow_permissions.test

Test view and edit permissions.

webform_workflow_change_submission_state in ./webform_workflow.module

Action callback for changing the workflow state of a submission.

webform_workflow_submission_state_form_submit in includes/webform_workflow.forms.inc

Submit callback for changing the state of an existing submission.

webform_workflow_webform_submission_insert in ./webform_workflow.module

Implements hook_webform_submission_insert().

... See full list

2 string references to 'webform_workflow_transition'

webform_workflow_update_7000 in ./webform_workflow.install

Changes database field configurations to allow longer state transition messages.

webform_workflow_views_default_views in includes/webform_workflow.views_default.inc

Implements hook_views_default_views().

File

./webform_workflow.module, line 341

A simple workflow module for webforms.

Code

function webform_workflow_transition($submission, $new_state, $message = NULL, $account = NULL, $notify = TRUE, $set_message = FALSE) {
  $previous_state = webform_workflow_state_load_by_submission($submission);
  if ($submission->is_draft) {
    drupal_set_message(t('Submission #@sid is a draft, so it cannot have a workflow state.', array(
      '@sid' => $submission->sid,
    )), 'warning');
    return FALSE;
  }
  if ($previous_state->wsid == $new_state->wsid) {
    return FALSE;
  }

  // Set the new state of the submission.
  $submission->_webform_workflow_state = $new_state;

  // Write the new state to the database, along with information about the
  // transition. Use a transaction to account for possible database errors.
  $transaction = db_transaction();
  try {
    db_merge('webform_workflow_submissions')
      ->key(array(
      'sid' => $submission->sid,
    ))
      ->fields(array(
      'wsid' => $new_state->wsid,
    ))
      ->execute();
    db_insert('webform_workflow_transition')
      ->fields(array(
      'nid' => $submission->nid,
      'sid' => $submission->sid,
      'uid' => $account ? $account->uid : NULL,
      'old_state_wsid' => $previous_state->wsid,
      'new_state_wsid' => $new_state->wsid,
      'message' => trim($message),
      'timestamp' => REQUEST_TIME,
    ))
      ->execute();
  } catch (Exception $e) {
    $transaction
      ->rollback();
    throw $e;
  }

  // Force the transaction to be committed now.
  unset($transaction);

  // Notify users about the transition by e-mail.
  $users_notified = array();
  if ($notify) {
    $users_notified = webform_workflow_notify_users($submission, array(
      'account' => $account,
      'message' => trim($message),
      'previous_state' => $previous_state,
      'new_state' => $new_state,
      'timestamp' => REQUEST_TIME,
    ));
  }

  // Display a message about the transition.
  if ($set_message) {
    $notice = t("Transitioned submission #@sid from %previous_state to %new_state.", array(
      '@sid' => $submission->sid,
      '%previous_state' => $previous_state->label,
      '%new_state' => $new_state->label,
    ));

    // Add information to the message about which users have been notified.
    if ($users_notified) {
      if (count($users_notified) == 1) {
        $account_notified = reset($users_notified);
        $notice .= ' ' . t('The user !user was notified by e-mail.', array(
          '!user' => drupal_placeholder(format_username($account_notified)) . ($account_notified->uid == $submission->uid ? ' ' . t('(the original submitter)') : ''),
        ));
      }
      else {
        $items = array();
        foreach ($users_notified as $account) {
          $item = check_plain(format_username($account));
          if ($account->uid == $submission->uid) {
            $item .= ' ' . t('(the original submitter)');
          }
          $items[] = $item;
        }
        natcasesort($items);
        $notice .= ' ' . t('The following users were notified by e-mail: !list', array(
          '!list' => theme('item_list', array(
            'items' => $items,
          )),
        ));
      }
    }
    drupal_set_message($notice, 'status', FALSE);
  }

  // Invoke the Rules event 'After a webform submission changes state'.
  if (module_exists('rules')) {
    $node = node_load($submission->nid);
    $pseudo_submission = entity_load_single('webform_workflow_submission', $submission->sid);
    rules_invoke_event('webform_workflow_transition', $node, $pseudo_submission, $previous_state, $new_state);
  }
  return TRUE;
}