lr_publish.module

<?php

/**
 * @file
 * A module to publish drupal node metadata to a Learning Registry node.
 *
 * This module takes the specified node content and publishes it to a
 * Learning Registry node.
 */


/**
 * Display help and module information.
 *
 * @param string $path
 *   A string that specifies which path of the site we're displaying help.
 * @param string $arg
 *   An array that holds that current path as would be returned from arg().
 *
 * @return string $help
 *   A string that contains the help text for the specified path.
 */
function lr_publish_help($path, $arg) {
  $output = '';
  switch ($path) {
    case "admin/help#lr_publish":
      $output = '<p>' .
        t("Pushes Drupal node data to the specified Learning Registry node.") .
        '<p>';
      break;
  }
  return $output;
} // function lr_publish_help


/**
 * Valid permissions for this module
 *
 * @return array
 *   An array of valid permissions for the lr_publish module.
 */
function lr_publish_perm() {
  return array('administer lr_publish_perm');
} // function lr_publish_perm


/**
 * Implementation of hook_menu().
 */
function lr_publish_menu() {
  $items['admin/settings/lr_publish'] = array(
    'title' => t('LR publish settings'),
    'description' => t('Publish selected node metadata to a Learning Registry node.'),
    'page callback' => 'drupal_get_form',
    'page arguments' => array('lr_publish_admin_settings'),
    'access arguments' => array('access administration pages'),
    'type' => MENU_NORMAL_ITEM,
    'file' => 'lr_publish.admin.inc',
  );

  return $items;
}


/**
 * Implementation of hook_nodeapi()
 */
function lr_publish_nodeapi(&$node, $op) {
  $nodes_to_publish = variable_get('lr_publish_node_types', array());
  if (in_array($node->type, $nodes_to_publish) &&
    $node->nid);
  switch($op) {
    case 'insert':
      if ($node->status == 1) {
        
        if (variable_get('lr_publish_queuing', 0) == 1) {
         _lr_queue_node($node->nid); 
        } else {
          _lr_publish_publish($node);
        }
      }
      break;
    // case 'update':
    //   if ($node->status == 0) {
    //     _lr_publish_set_deleted($node);
    //   }
    //   else if ($node->status == 1) {
    //     _lr_publish_update($node);
    //   }
    //   break;
    // case 'delete':
    //   _lr_publish_set_deleted($node);
    //   break;
  }
}


/**
 * Implementation of hook_cron()
 * 
 * Reads unprocessed nodes from lr_publish table and attempts to push them to
 * the Learning Registry.
 */
function lr_publish_cron() {
  // Pull node IDs of records queued for processing
  $records = db_query('SELECT nid FROM {lr_publish} WHERE queued = 1');

  while ($record = db_fetch_array($records)) {
    $node = node_load($record["nid"], NULL, TRUE);
    _lr_publish_publish($node, TRUE);
  }
  
}

/**
 * Implementation of hook_node_operations()
 * 
 * Allows for publishing using the bulk operations content page.
 */
function lr_publish_node_operations() {
  return array(
    'process_orders' => array(
    'label' => 'Publish to Learning Registry',
    'callback' => '_lr_publish_bulk_operations_publish',
    'disabled' => TRUE,
  ));
}

/**
 * Callback function for lr_publish_node_operations()
 */
function _lr_publish_bulk_operations_publish($nids) {
  $success = 0; $failure = 0;
  
  foreach ($nids as $nid) {
    // Load the node
    $node = node_load($nid);
    // Send it to the Learning Registry
    $result = _lr_publish_publish($node, TRUE);
    
    // If successful, update the count.
    if ($result) { $success++; } 
  }
  
  if (variable_get('lr_publish_queuing', 0) == 1)
    drupal_set_message($success.' nodes queued to the registry. '.$failure.' nodes failed.' );
 else
    drupal_set_message($success.' nodes published to the registry. '.$failure.' nodes failed.' );
}

/**
 * Publish node metadata to specified Learning Registry node.
 *
 * @param object &$node
 *   A reference to the node object. We have to be very careful to not set
 *   anything, only read from the node object reference since the node
 *   reference allows us to edit the node content.
 * 
 * @param bool $headless
 *   A flag to determine if this is called from cron (non-user session).
 * 
 * @return bool $result
 *   Returns TRUE if operation was successful, FALSE if not.
 */
function _lr_publish_publish(&$node, $headless = FALSE) {
  $content_info = _lr_get_content_info(&$node);
  $resource_data = _lr_def_resource_data($content_info);
  $empty_submission = _lr_build_envelope();
  //watchdog('lr_publish', json_encode($empty_submission));
  $prepared_submission =
    _lr_add_resource_data_to_submission($empty_submission, $resource_data);
  $resource_post_payload = json_encode($prepared_submission);
  //watchdog('lr_publish', $resource_post_payload, array(), WATCHDOG_DEBUG);

  $result = _lr_send_to_registry($node->nid, $resource_post_payload, 0, $headless);
  return $result;
}


/**
 * Sets the deleted status for a deleted Drupal node in the LR node.
 *
 * @param object &$node
 *   A reference to the node object. We have to be very careful to not set
 *   anything, only read from the node object reference since the node
 *   reference allows us to edit the node content.
 */
function _lr_publish_set_deleted(&$node) {
  return;
}


/**
 * Update the info published to the node.
 *
 * @param object &$node
 *   A reference to the node object. We have to be very careful to not set
 *   anything, only read from the node object reference since the node
 *   reference allows us to edit the node content.
 */
function _lr_publish_update(&$node) {
  return;
}

/**
 * Return info we submit about nodes to the LR.
 *
 * @param object &$node
 *   A reference to the node object. We have to be very careful to not set
 *   anything, only read from the node object reference since the node
 *   reference allows us to edit the node content.
 */
function _lr_get_content_info(&$node) {
  $content_info = array();
  $content_info['resource_locator'] = _lr_get_node_url($node);
  // TODO: correctly specify resource data type
  // resource_data_type is currently hardcoded, will be fixed in a later version
  $content_info['resource_data_type'] = 'metadata';
  $content_info['submitter'] = variable_get('lr_publish_submitter', NULL);
  $content_info['tos'] = variable_get('lr_publish_tos', NULL);
  
  // currently set curator and submitter the same, once we get a better sense
  // of what each field means, this will change
  $content_info['curator'] = $content_info['submitter'];
  // TODO: correctly set active value, currently hardcoded to TRUE
  $content_info['active' ] = TRUE;
  $content_info['payload_schema'] = "DC 1.1";

  $resource_data=_lr_create_dublincore_payload($node);
 
  $content_info['resource_data'] = $resource_data;

  return $content_info;
}


/**
 * Return the absolute URL to a node.  If alias available, return alias as friendlier URL.
 *
 * @param int $nid
 *   The numerical node id.
 *
 * @return string $node_url
 *   The absolute URL to the node.  If alias available, return alias.
 */
function _lr_get_node_url(&$node) {
  
  // URL Type is an admin setting.  Return either alias or node ID.
  if (variable_get('lr_publish_url_type', 0) == 1)
    return url("node/".$node->nid, array("absolute" => TRUE, "alias" => FALSE));
  else
    return url("node/".$node->nid, array("absolute" => TRUE, "alias" => TRUE));
}

/**
 * Make the curl calls to send to the LR node.
 *
 * All the specified nodeapi operations ($ops) call this function to actually send the data.
 *
 * @param string $nid
 *    A string containing the node ID for submission into the registry.
 * @param string $json
 *    A string containing the json object that will be sent to the registry node.
 * @param int $service_num
 *    An int that specifies the service that will be called.
 *    0 - publish (default value)
 *    1 - update
 *    2 - delete
 * @param bool $headless
 *    A flag to determine if this is called from cron (non-user session).
 * 
 * @return bool $result
 *    True if operation was successful, false if error.
 */
function _lr_send_to_registry($nid, $json, $service_num = 0, $headless = FALSE) {
  $services = array(
    'publish',
    'update',
    'delete',
  );

  if ($service_num >= count($services)) {
    return;
  }

  $ch = curl_init();
  $curl_options = array(
    // TODO: allow more than publish! Currently hardcoding the publish
    // bit. this function needs to take an argument to add the appropriate
    // service at the end of the curl URL
    CURLOPT_URL => variable_get('lr_publish_node_url', NULL) . "/publish",
    CURLOPT_POST => TRUE,
    CURLOPT_POSTFIELDS => $json,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_HTTPHEADER => array("Content-type: application/json",),
  );
  // file_put_contents("/tmp/foo.json", $json);
  curl_setopt_array($ch, $curl_options);
  $result=curl_exec($ch);
  $error = curl_error($ch);
  curl_close($ch);
  
  $submission_result = _lr_parse_result($result, $error);
  
  // dsm($submission_result);

  if ($result) {
    $result = _lr_update_submission_status($nid, $result);
    
    if (!$headless) {
      $submissionURL = variable_get('lr_publish_node_url', NULL)."/harvest/getrecord?by_doc_ID=TRUE&request_ID=".$result;
      drupal_set_message(sprintf( 'Node ID %d published to the registry. <a href="%s" target="_new">(View node on registry.)</a>', $nid, $submissionURL), "status");
    }
    
    return TRUE;
  } else {
    if (!$headless) {
      drupal_set_message("Error publishing node to registry.", "warning");
    }
    
    return FALSE;
  }
  
}


/**
 * Define the Learning Registry resource data.
 *
 * @param array $content_info

 * @returns object $resource_data
 */
function _lr_def_resource_data ($content_info) {
  // values specified as immutable in the LR spec.
  define("LR_DOC_TYPE", "resource_data");
  define("LR_DOC_VERSION", "0.23.0");
  define("LR_SUBMITTER_TYPE", "agent");
  // commented since we aren't signing submissions
  // define("LR_SIGNING_METHOD", "LR-PGP.1.0");
  define("LR_PAYLOAD_PLACEMENT", "inline");

  $opt_id_fields = array(
    'curator',
    'owner',
    'signer',
  );

  $opt_res_fields = array(
    'submitter_timestamp',
    'submitter_TTL',
    'keys',
    'resource_TTL',
    'payload_schema_locator',
    'payload_schema_format',
  );

  // we don't really do much with these since we aren't currently signing
  // submissions.
  $opt_sig_fields = array(
    'signature',
    'key_server',
    'key_locations',
    'key_owner',
    'signing_method',
  );

  $opt_tos_fields = array(
    'tos_submission_attribution', // need to figure out more about this value.
  );
  $identity->submitter_type = LR_SUBMITTER_TYPE;
  $identity->submitter = $content_info["submitter"];

  $tos->submission_TOS = $content_info["tos"];;

  //TODO: extract these foreach calls into their own function
  // Add the optional keys / objects if they are passed in $content_info

  // optional identity values.
  foreach ($opt_id_fields as $field) {
    if (array_key_exists($field, $content_info)) {
      $identity->$field = $content_info[$field];
    }
  }

  // optional resource_data values
  foreach ($opt_res_fields as $field) {
    if (array_key_exists($field, $content_info)) {
      $resource_data->$field = $content_info[$field];
    }
  }

  // create an empty stdClass since the digital_signature is completely
  // optional.
  $digital_signature = new stdClass;
  // optional digital signature  values
  foreach ($opt_sig_fields as $field) {
    if (array_key_exists($field, $content_info)) {
      $digital_signature->$field = $content_info[$field];
    }
  }

  // optional TOS values
  foreach ($opt_tos_fields as $field) {
    if (array_key_exists($field, $content_info)) {
      $tos->$field = $content_info[$field];
    }
  }


  $resource_data->doc_type = LR_DOC_TYPE;
  $resource_data->doc_version = LR_DOC_VERSION;
  $resource_data->resource_data_type = $content_info['resource_data_type'];
  $resource_data->active = $content_info['active'];
  $resource_data->identity = $identity;
  $resource_data->TOS = $tos;

  // only add the signature key if signature data are defined.
  if (!empty($digital_signature)) {
    $resource_data->digital_signature = $digital_signature;
  }

  $resource_data->resource_locator = $content_info['resource_locator'];
  $resource_data->payload_placement = LR_PAYLOAD_PLACEMENT;
  $resource_data->payload_schema = array($content_info['payload_schema']);
  $resource_data->resource_data = $content_info['resource_data'];

  return $resource_data;
}


/**
 * Return a basic LR submission envelope.
 *
 * @return object $submission
 *   An empty LR submission envelop.
 */
function _lr_build_envelope() {
  $submission->documents = array();
  return $submission;
}


/**
 * Adds resource data to a LR submission envelope.
 *
 * @param object $submission
 *    An LR submission object.
 * @param object $resource_data
 *    An LR resource data object.
 *
 * @return object $submission
 *    The submission object with $resource data pushed on to the documents array.
 */
function _lr_add_resource_data_to_submission($submission, $resource_data) {
  $submission->documents[] = $resource_data;
  return $submission;
}


/**
 * Adds a status record in the lr_publish table to record submission
 *
 * @param int $nid
 *    Drupal node ID of item to submit.
 * @param string $result
 *    JSON response from Learning Registry.
 *
 */
function _lr_update_submission_status($nid, $result) {
  //TODO:  Refactor candidate.  This method has two responsiblities:  a.) to determine if the node was published to
  // the Learning Registry, b.) then to update that status to the lr_publish table.  The first step should stand on its own.
  if ($result) {

    $result_array = json_decode($result);

    if ($result_array->document_results[0]->OK) {
    // check to see if submission already in database
      $submission_check_result = db_query('SELECT * FROM {lr_publish} WHERE nid = %d', $nid);
      $submission_record = db_fetch_object($submission_check_result);
      
      // Check if this has been published before.  If no, set the published timestamp.  Else,
      // the updated timestamp.
      if ($submission_record) {
        if ($submission_record->published==0) {
          $sql = 'UPDATE {lr_publish} SET published=%d, docid=\'%s\', queued=0 WHERE nid = %d';
        } else {
          $sql = 'UPDATE {lr_publish} SET updated=%d, docid=\'%s\', queued=0 WHERE nid = %d';
        }
        
        db_query($sql, time(), $result_array->document_results[0]->doc_ID, $nid);
      }
      else {
      // Insert new record

      // fill parameter array
        $data = array(
            'nid' => $nid,
            'published' => time(),
            'docid' => $result_array->document_results[0]->doc_ID,
        );
        // write it to the database
        drupal_write_record('lr_publish', $data);
      }
      return $result_array->document_results[0]->doc_ID;
    }
    else {
      watchdog('lr_publish', "Error publishing node ID %nid to the registry.  Full response: %msg",
          array ('%nid' => $nid,'%msg' => $result));
      return false;
    }
  }
}

/** 
 * Parse out result from Learning Registry submission
 * 
 * @param object $result
 *    JSON array result from Learning Registry submission
 * 
 * @param string $error
 *    Error string from curl (if error occured)
 *
 * @return object $submission_result
 *    Array with status information from submission
 */
function _lr_parse_result($result, $error) {
  $submission_result = array();
  
    if ($result) {
      // We have something back from the Learning Registry service
      $result_array = json_decode($result);

      if ($result_array->document_results[0]->OK) {
        // Submission okay
        $submission_result["success"] =  TRUE;
        $submission_result["doc_id"] = $result_array->document_results[0]->doc_ID;
      } else {
        $submission_result["success"] = FALSE;
        if (!is_null($result_array->document_results[0]->error))
          $submission_result["error_message"] = $result_array->document_results[0]->error;
        else {
          // If the error message comes back in form of a HTML page, let's just
          // pop off the title tag as Couch will tell us what's wrong there.
          // Current impl of LR spits two title tags, so we're grabbing the last one
          // as it displays better error message.  If not two present, we'd just grab
          // the first.
          if (strpos($result, "<html") > 0) {
            $start = strripos($result, "<title>");
            $end = strripos($result, "</title");
            $submission_result["error_message"] = substr($result, $start+7, $end - $start - 7); // what's between the title tags (+7 skips first title tag)
        }
      }
    }
  } else {
    // We didn't contact the Learning Registry service, must be a network error
     $submission_result["SUCCESS"] = FALSE;
     $submission_result["error_message"] = $error;
  }
  
  return $submission_result;
}
/**
 * Queues a node for submission to the LR via the lr_publish table
 *
 * @param int $nid
 *    Drupal node ID of item to submit.
 */
function _lr_queue_node($nid) {
  
  // Check if this record exists in submission table
  $submission_check_result = db_query('SELECT * FROM {lr_publish} WHERE nid = %d', $nid);
  $submission_record = db_fetch_object($submission_check_result);
  
  // If exists, update, else insert new record
  if ($submission_record) {
    $sql = 'UPDATE {lr_publish} SET queued=1 WHERE nid = %d'; 
  } else {
    $sql = 'INSERT INTO {lr_publish} (nid, queued) VALUES (%d, 1)';    
  }

  // Write to database
  db_query($sql, $nid);
}

/**
 * Creates Dublin Core 1.1 XML document with information from node
 *
 * @param object $node
 *    Drupal node
 * 
 * @return object $returnXML
 *    XML document
 */
function _lr_create_dublincore_payload (&$node) {
  
  // Set the initial RDF XML DC envelope body.
  $source = '<?xml version="1.0"?>
    <!DOCTYPE rdf:RDF PUBLIC "-//DUBLIN CORE//DCMES DTD 2002/07/31//EN"
      "http://dublincore.org/documents/2002/07/31/dcmes-xml/dcmes-xml-dtd.dtd">
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:dc ="http://purl.org/dc/elements/1.1/">
      <rdf:Description rdf:about="http://dublincore.org/">
      </rdf:Description>
    </rdf:RDF>';
  
  $xmlDoc = new DOMDocument;
  $xmlDoc->loadXML($source);
  
  // Retrieve just the DC node
  $nodeList = $xmlDoc->getElementsByTagNameNS('http://www.w3.org/1999/02/22-rdf-syntax-ns#', 'Description');
  $dcNode = $nodeList->item(0);
    
  // Set the DC title to the node title.
  $element = $xmlDoc->createElementNS('http://purl.org/dc/elements/1.1/', 'title', $node->title);
  $dcNode->appendChild($element);

  // Set the DC description to the node body.
  $element = $xmlDoc->createElementNS('http://purl.org/dc/elements/1.1/', 'description', $node->body);
  $dcNode->appendChild($element);
  
  // Set the DC date to the node create date.
  $dateCreated = format_date($node->created, 'custom', 'Y-m-d');
  $element = $xmlDoc->createElementNS('http://purl.org/dc/elements/1.1/', 'date', $dateCreated);
  $dcNode->appendChild($element);

  // Set the DC identifier to the absolute URL of the node.  
  $element = $xmlDoc->createElementNS('http://purl.org/dc/elements/1.1/', 'identifier', _lr_get_node_url($node));
  $dcNode->appendChild($element);
  
  // Pretty format the XML before sending it to the LR.  Makes it easier to read and debug.  
  // Must be reloaded, won't work if just set on $xmlDoc. 
  $returnXML = new DOMDocument;
  $returnXML->preserveWhiteSpace = false;
  $returnXML->formatOutput = true;
  $returnXML->loadXML($xmlDoc->saveXML());

  return $returnXML->saveXML();  
    
  
  /* References
    
   http://dublincore.org/documents/usageguide/elements.shtml 
   
    
  <dc:title>Dublin Core Metadata Initiative - Home Page</dc:title>
  <dc:description>The Dublin Core Metadata Initiative Web site.</dc:description>
  <dc:date>2001-01-16</dc:date>
  <dc:format>text/html</dc:format>
  <dc:language>en</dc:language>
  <dc:contributor>The Dublin Core Metadata Initiative</dc:contributor> 

  <!ENTITY % dcmes "dc:title | dc:creator | dc:subject | dc:description |
  dc:publisher | dc:contributor | dc:date | dc:type | dc:format |
  dc:identifier | dc:source | dc:language | dc:relation | dc:coverage |
  dc:rights" > 
   */
  
}