Only one workflow request can be active for any given page; however, a page may have a number
of historical, closed workflow requests.
The WorkflowRequest object shouldn't be directly edited. Instead, you call "workflow step"
methods on the object, that will update the object appropriately.
To create or retrieve a WorkflowRequest object, call {@link SiteTreeCMSWorkflow::openOrNewWorkflowRequest()}
or {@link SiteTreeCMSWorkflow::openWorkflowRequest()} on the relevant {@link SiteTree} object.
The following examples show how a workflow can be created.
Request publication:
$wf = $page->openOrNewWorkflowRequest('WorkflowPublicationRequest')
$wf->request("Can you please publish this page");
Reject changes:
$wf = $page->openWorkflowRequest()
$wf->deny("It's not acceptable. Please correct the spelling.");
Approve changes:
$wf = $page->openWorkflowRequest()
$wf->approve("Thanks, looks good now");
Make the changes 'go live' changes:
$wf = $page->openWorkflowRequest()
$wf->action();
{@link WorkflowRequest::Changes()} will provide a list of the changes that the workflow has gone through,
suitable for presentation as a discussion thread attached to the page.
public function trigger()
{
$page = Page::getByID($this->cID);
$pk = PermissionKey::getByID($this->pkID);
$pk->setPermissionObject($page);
return parent::trigger($pk);
}
function notifyAwaitingEdit($comment)
{
$emailsToSend = array();
$userWhoRequestedEdits = Member::currentUser();
if (WorkflowRequest::should_send_alert(get_class($this->owner), 'requestedit', 'publisher')) {
$publishers = $this->owner->Page()->PublisherMembers();
foreach ($publishers as $publisher) {
$emailsToSend[] = array($userWhoRequestedEdits, $publisher);
}
}
if (WorkflowRequest::should_send_alert(get_class($this->owner), 'requestedit', 'approver') && $this->Page()->hasMethod('ApproverMembers')) {
$approvers = $this->owner->Page()->ApproverMembers();
foreach ($approvers as $approver) {
$emailsToSend[] = array($userWhoRequestedEdits, $approver);
}
}
if (WorkflowRequest::should_send_alert(get_class($this->owner), 'requestedit', 'author')) {
$emailsToSend[] = array($userWhoRequestedEdits, $this->owner->Author());
}
if (count($emailsToSend)) {
foreach ($emailsToSend as $email) {
if ($email[1]->ID == Member::currentUserID()) {
continue;
}
$this->owner->sendNotificationEmail($email[0], $email[1], $comment, 'requested edit');
}
}
}
public function __construct($status = null, $id = null, $workflowRuleName = null, $entityId = null, $entityType = null, $type = null, $WorkflowRequestType = null)
{
parent::__construct();
$this->status = $status;
$this->id = $id;
$this->workflowRuleName = $workflowRuleName;
$this->entityId = $entityId;
$this->entityType = $entityType;
$this->type = $type;
$this->WorkflowRequestType = $WorkflowRequestType;
}
function testNotificationEmails()
{
WorkflowRequest::$enable_all_alerts = true;
$page = $this->objFromFixture('SiteTree', 'custompublisherpage');
$custompublisher = $this->objFromFixture('Member', 'custompublisher');
$customauthor = $this->objFromFixture('Member', 'customauthor');
// awaiting approval emails
$this->session()->inst_set('loggedInAs', $customauthor->ID);
$wf = $page->openOrNewWorkflowRequest('WorkflowPublicationRequest');
$this->assertNotNull($wf);
$wf->request("Can you publish this please?");
$this->assertEmailSent($custompublisher->Email, $customauthor->Email);
// published emails
$this->session()->inst_set('loggedInAs', $custompublisher->ID);
// doesn't work because onAfterWrite() is not called
//$page->publish('Stage','Live');
// Save and publish is an alias for approve
$wf->saveAndPublish('Looks good');
$this->assertEmailSent($customauthor->Email, $custompublisher->Email);
$this->session()->inst_set('loggedInAs', null);
WorkflowRequest::$enable_all_alerts = false;
}
public static function get($class, $status = null)
{
return WorkflowRequest::get($class, $status);
}
/**
* Creates a WorkflowProgress object (which will be assigned to a Page, File, etc... in our system.
*/
public static function add($wpCategoryHandle, Workflow $wf, WorkflowRequest $wr)
{
$db = Loader::db();
$wpDateAdded = Loader::helper('date')->getLocalDateTime();
$wpCategoryID = $db->GetOne('select wpCategoryID from WorkflowProgressCategories where wpCategoryHandle = ?', array($wpCategoryHandle));
$db->Execute('insert into WorkflowProgress (wfID, wrID, wpDateAdded, wpCategoryID) values (?, ?, ?, ?)', array($wf->getWorkflowID(), $wr->getWorkflowRequestID(), $wpDateAdded, $wpCategoryID));
$wp = self::getByID($db->Insert_ID());
$wp->addWorkflowProgressHistoryObject($wr);
return $wp;
}
function testCmsActionsLimited()
{
// For 2.3 and 2.4 compatibility
$bt = defined('DB::USE_ANSI_SQL') ? "\"" : "`";
$custompublisherspage = $this->objFromFixture('SiteTree', 'custompublisherpage');
$custompublishersgroup = $this->objFromFixture('Group', 'custompublishergroup');
$custompublisher = $this->objFromFixture('Member', 'custompublisher');
$workflowadmin = $this->objFromFixture('Member', 'workflowadmin');
$custompublisher->Groups()->add($custompublishersgroup);
$customauthorsgroup = $this->objFromFixture('Group', 'customauthorsgroup');
$customauthor = $this->objFromFixture('Member', 'customauthor');
$customauthor->Groups()->add($customauthorsgroup);
$unpublishedRecord = new Page();
$unpublishedRecord->CanEditType = 'LoggedInUsers';
$unpublishedRecord->write();
$unpublishedRecord->PublisherGroups()->add($custompublishersgroup);
$custompublisher->logIn();
$publishedRecord = new Page();
$publishedRecord->CanEditType = 'LoggedInUsers';
$publishedRecord->write();
$publishedRecord->doPublish();
$publishedRecord->PublisherGroups()->add($custompublishersgroup);
$deletedFromLiveRecord = new Page();
$deletedFromLiveRecord->CanEditType = 'LoggedInUsers';
$deletedFromLiveRecord->write();
$deletedFromLiveRecord->doPublish();
$deletedFromLiveRecord->deleteFromStage('Live');
$deletedFromLiveRecord->PublisherGroups()->add($custompublishersgroup);
$deletedFromStageRecord = new Page();
$deletedFromStageRecord->CanEditType = 'LoggedInUsers';
$deletedFromStageRecord->write();
$deletedFromStageRecord->PublisherGroups()->add($custompublishersgroup);
$deletedFromStageRecord->doPublish();
$deletedFromStageRecordID = $deletedFromStageRecord->ID;
$deletedFromStageRecord->deleteFromStage('Stage');
$deletedFromStageRecord = Versioned::get_one_by_stage("SiteTree", "Live", "{$bt}SiteTree{$bt}.{$bt}ID{$bt} = {$deletedFromStageRecordID}");
$changedOnStageRecord = new Page();
$changedOnStageRecord->CanEditType = 'LoggedInUsers';
$changedOnStageRecord->write();
$changedOnStageRecord->publish('Stage', 'Live');
$changedOnStageRecord->Content = 'Changed on Stage';
$changedOnStageRecord->write();
$changedOnStageRecord->PublisherGroups()->add($custompublishersgroup);
// test "publish" action for author
$this->session()->inst_set('loggedInAs', $customauthor->ID);
$this->assertNotContains('action_publish', $unpublishedRecord->getCMSActions()->column('Name'), 'Author cant trigger publish button');
$this->assertNotContains('action_publish', $publishedRecord->getCMSActions()->column('Name'), 'Author cant trigger publish button');
$this->assertNotContains('action_publish', $deletedFromLiveRecord->getCMSActions()->column('Name'), 'Author cant trigger publish button');
$this->assertNotContains('action_publish', $changedOnStageRecord->getCMSActions()->column('Name'), 'Author cant trigger publish button');
// test "publish" action for publisher
$this->session()->inst_set('loggedInAs', $custompublisher->ID);
WorkflowRequest::set_force_publishers_to_use_workflow(false);
$this->assertContains('action_publish', $unpublishedRecord->getCMSActions()->column('Name'), 'Publisher cant trigger publish button');
$this->assertContains('action_publish', $publishedRecord->getCMSActions()->column('Name'), 'Publisher cant trigger publish button');
$this->assertContains('action_publish', $changedOnStageRecord->getCMSActions()->column('Name'), 'Publisher cant trigger publish button');
WorkflowRequest::set_force_publishers_to_use_workflow(true);
$this->assertFalse(in_array('action_publish', $unpublishedRecord->getCMSActions()->column('Name')), 'Publisher can trigger publish button even when forced to use workflow');
$this->assertFalse(in_array('action_publish', $publishedRecord->getCMSActions()->column('Name')), 'Publisher can trigger publish button even when forced to use workflow');
$this->assertFalse(in_array('action_publish', $changedOnStageRecord->getCMSActions()->column('Name')), 'Publisher can trigger publish button even when forced to use workflow');
// test "request publication" action for author
$this->session()->inst_set('loggedInAs', $customauthor->ID);
$this->assertContains('action_cms_requestpublication', $unpublishedRecord->getCMSActions()->column('Name'), 'Author can trigger request publication button if page is not published');
$this->assertNotContains('action_cms_requestpublication', $publishedRecord->getCMSActions()->column('Name'), 'Author cant trigger request publication button if page has been published but not altered on stage');
$this->assertContains('action_cms_requestpublication', $changedOnStageRecord->getCMSActions()->column('Name'), 'Author can trigger request publication button if page has been changed on stage');
// test "request removal" action for author
$this->session()->inst_set('loggedInAs', $customauthor->ID);
$this->assertNotContains('action_cms_requestdeletefromlive', $unpublishedRecord->getCMSActions()->column('Name'), 'Author cant trigger request removal button if page hasnt been altered');
$this->assertNotContains('action_cms_requestdeletefromlive', $publishedRecord->getCMSActions()->column('Name'), 'Author cant trigger request removal button if page has been published but not altered on stage');
$this->assertNotContains('action_cms_requestdeletefromlive', $changedOnStageRecord->getCMSActions()->column('Name'), 'Author cant trigger request removal button if page has been changed on stage but not deleted from stage');
// test "request removal" action for publisher
$this->session()->inst_set('loggedInAs', $custompublisher->ID);
// reset login
$this->session()->inst_set('loggedInAs', null);
}
function testWorkflowPublicationApprovalTransition()
{
WorkflowRequest::$enable_all_alerts = true;
$page = $this->objFromFixture('SiteTree', 'custompublisherpage');
$custompublisher = $this->objFromFixture('Member', 'custompublisher');
$customapprover = $this->objFromFixture('Member', 'customapprover');
$customauthor = $this->objFromFixture('Member', 'customauthor');
// nothing -> awaiting approval
$customauthor->logIn();
$request = $page->openOrNewWorkflowRequest('WorkflowPublicationRequest');
$request->request("ARGGGGG!");
$this->assertNotNull($request);
$this->assertEquals($request->AuthorID, $customauthor->ID, "Logged-in member is set as the author of the request");
$this->assertEquals($request->Status, 'AwaitingApproval', "Request is set to AwaitingApproval after requestPublication() is called");
// awaiting approval -> approved
$customapprover->logIn();
$request->approve('Looks good');
$this->assertEquals($request->Status, 'Approved', "Request is set to Approved after page is approved");
$this->assertEquals($request->ApproverID, $customapprover->ID, "Currently logged-in user is set as the Approver for this request");
// place comment
$customauthor->logIn();
$request->comment("YARRRRRR!");
// approved -> completed
$custompublisher->logIn();
$request->publish('Avast, ye scoundrels!', $custompublisher, false);
$this->assertEquals($request->Status, 'Completed', "Request is set to Completed after page is published");
$this->assertEquals($request->PublisherID, $custompublisher->ID, "Currently logged-in user is set as the Publisher for this request");
// Test save and publish
$this->objFromFixture('Member', 'admin')->logIn();
$this->assertTrue(is_string($page->openOrNewWorkflowRequest('WorkflowPublicationRequest')->saveAndPublish("S&P")));
// Test the get_by_* functions. These are cursory tests, covering functionality
// but none of the multitude of edge cases
$this->assertContains($page->ID, WorkflowThreeStepRequest::get_by_author('WorkflowPublicationRequest', $customauthor)->column('ID'));
$this->assertContains($page->ID, WorkflowThreeStepRequest::get_by_approver('WorkflowPublicationRequest', $customapprover)->column('ID'));
$this->assertContains($page->ID, WorkflowThreeStepRequest::get_by_publisher('WorkflowPublicationRequest', $custompublisher)->column('ID'));
}
/**
* Gets the $Status property as a translated natural language value.
*
* @return string
*/
public function getStatusDescription()
{
return WorkflowRequest::get_status_description($this->Status);
}
