Update API Guide

Introduction

The SDR Service API provides access to the core of SDR. It allows you to do four main actions:

Submit Metadata
Approve/Reject Metadata
Update a Release Flag

Submitting new metadata to SDR creates a new metadata version (SDRVersion) for a given URL. It does not matter whether or not the URL is already in the SDR database. There will always be one resource (SDRResource) per URL. Duplicate resources will never be added, only duplicate versions for a resource.

Someone should add a new resource if they find a relevant online resource that is not already in SDR, or if they create a new content resource at Shodor. New versions for an existing resource are typically submitted when someone wants to suggest revisions for an existing resource.

What You Need

To submit metadata, we need:

a cserdId (either a URL or the numeric ID of an existing resource)
metadata stored in an SDRMetadataObj
the agent performing the action, represented by an SDRAgent
a comment about the submission
if we are creating a new resource, we need an array of projects (either as project names or as SDRProject objects)

Example

An example of submitting a new resource:

// The URL for which we are submitting metadata
$url = 'http://my-sample-url.com';

// Create an object to store our metadata
$metadata = new SDRMetadataObj();
// Metadata can either be added like this:
$metadata->@ref SDRMetadataObj::setXML "setXML"('
<metadata>
<Title>Free Sample URLs</Title>
<Description>An amazing website that generates sample URLs for you to use in examples</Description>
</metadata>
');

// Or like this:
$metadata->@ref SDRMetadataObj::addTag "addTag"('Publisher', 'Shodor');

// Generate an agent (typically from your SWAT global or project user)
$agent = SDRAgent::agentFromSUser($SWAT->getGlobalUser());
// or $agent = SDRAgent::agentFromCSERDUser($SWAT->getProjectUser());
if ($agent === false)
    $prm->flashAndExit('Unable to find or create an agent for your user.');

// Generate a comment
$comment = 'Testing the SDR service';

// Specify projects. The first project in the array will be the object's primary project/collection.
// (Add this resource with NCSI Resources as the primary project, but also make it a part of CSERD
// so that it will show up in CSERD searches.)
$projects = array('NCSI Resources', 'CSERD');

// Submit the resource
$version = SDRService::submit($url, $metadata, $agent, $comment, $projects);

// If you are using SWAT, report on the status of the submission
if ($version === false)
    $prm->flashAndExit('Your resource could not be submitted.');
else
    $SWAT->getGlobalUser()->setFlash('Your resource was successfully submitted');

You can use the $version returned from submit() to do further actions, such as running approve(). You can also use it to look up the cserdId of the newly added resource:

$cserdId = $version->cserdId;

To add new versions for the same URL, the code would be identical except that it would not be necessary to specify the projects.

Approve/Reject Metadata

Approving an SDRVersion makes it become the single active metadata version for its parent SDRResource.

The status of the version you approve is changed from its existing state (typically "pending," if recently submitted, or "history," if rolling back to an older version) to "approved." If there is an existing active metadata version, that version will be marked as "history" first. If there is no existing active version, existing versions are not affected.

Rejecting is the opposite of approving. Rejecting a "pending" version will simply mark that version as "rejected" and other versions will not be affected. Rejecting an "approved" version will additionally set the release flag of the resource to 0, since it is impossible for a resource to be publicly released with no approved versions.

What You Need

When approving or rejecting a version, one must include:

an SDRVersion to be modified
the agent performing the action, represented by an SDRAgent

Simple Example

If you already have a version and an agent (for instance, if you just ran SDRService::submit()):

// Approve the version and report on the result
$result = SDRService::approve($version, $agent);
if ($result === false)
    $prm->flashAndExit('Your resource could not be approved.');
else
    $prm->flashAndExit('Your resource was approved.');

Complete Example

If you need to first find an agent and a version:

// Query SDRVersion for your versionId (or other criteria)
$versions = SDRVersion::getList(array('id' => x));
if (!$versions || !count($versions))
    $prm->flashAndExit('Unable to load version');
$version = $versions[0];

// Get an agent from your user object (or use SDRAgent::getList() to search on other criteria)
$agent = SDRAgent::agentFromSUser($SWAT->getGlobalUser());
if ($agent === false)
    $prm->flashAndExit('Unable to find or create an agent for your user.');

// Approve the version and report on the result
$result = SDRService::approve($version, $agent);
if ($result === false)
    $prm->flashAndExit('Your resource could not be approved.');
else
    $prm->flashAndExit('Your resource was approved.');

Update a Release Flag

The release flag on a resource determines whether or not it is viewable to the outside world. Setting the release flag to 1 is equivalent to publishing a resource to the live metadata catalog; setting it to 0 hides the resource.

Changing the release flag does not affect a resource's versions; it simply determines whether or not the current active version can be seen publicly.

A resource's release flag cannot be set to 1 unless there is an active version for that resource (otherwise, there would be no approved metadata to display publicly). Likewise, if a resource's release flag is 1 and its active version is rejected, the release flag will automatically be set back to 0.

When a release flag is changed, the resource's search cache is automatically updated so that the resource will immediately appear in searches (without having to rebuild the entire search DB).

What You Need

To release or unrelease a resource, you need:

A resource's URL or numeric ID
the new value of the release flag (1 for released or 0 for private)
the agent performing the action, represented by an SDRAgent

Example

An example of changing the release flag on a resource:

// A resource ID can either be a URL or numeric ID
$id = 'http://my-sample-url.com';

// Get an agent from your user object (or use SDRAgent::getList() to search on other criteria)
$agent = SDRAgent::agentFromSUser($SWAT->getGlobalUser());
if ($agent === false)
    $prm->flashAndExit('Unable to find or create an agent for your user.');

// Release your resource and report the result
$result = SDRService::updateReleaseFlag($id, 1, $agent);
if ($result === false)
    $prm->flashAndExit('Your resource could not be released.');
else
    $prm->flashAndExit('Your resource was released.');