**This article and packaged sample is for Salesforce Integrators/Developers**
Prerequisite: You must have previously installed Viewpath_PM version 3.8 or greater!
If needed, install our latest Viewpath_PM package from our AppExchange listing at:
After you have followed the steps of our Viewpath PM 4 Installation Guide you are then ready for this optional trigger sample.
Upon installation of this unmanaged trigger sample package you will have access to the following Viewpath PM 4 use cases as well as sample source code:
- Auditing is demonstrated on changes of select fields of the Viewpath Project & Task objects.
This sample shows how a trigger can detect changes on the Viewpath Project custom object & Viewpath Task custom object to record those differences in an audit table.
- A Custom Object is updated by Viewpath Project trigger.
This sample shows how a trigger on Viewpath Project can change fields of a given Custom Object. If your company uses a Custom Object, this is a parallel to how Viewpath can automate your object.
- Standard Opportunity Object is updated by Viewpath Project trigger.
This sample shows how a trigger on Viewpath Project can change fields of a standard Salesforce Object. Learning how to do this on the Opportunity object can then easily be applied to other standard objects like Accounts.
- A) Installation Steps (written using Salesforce Classic):
- From the Salesforce app menu (top right), select 'Viewpath PM 4'.
- If you recently installed Viewpath_PM 3.6 or greater and did not yet setup integration with Opportunities, please accomplish this step. Refer to our Installation Guide as found at our Viewpath 4 Salesforce support site:
Open an existing Opportunity or create a new one.
Edit Layout to add a new section below the 'Additional Information' section (the last field of that section is Tracking Number).
Name the new section 'Viewpath Project' and set it to 1 column.
Add the Visualforce page, 'VP4_OpportunityControllerExtension' to the section you just created.
Set its Height to 500 and check to enable Scrollbars.
Save the layout, returning you to the opportunity that you opened.
In the new ‘Viewpath Project’ section, select a Viewpath4 project from the list and click 'Attach Project'.
The project should appear on the Opportunity UI.
The above enables one to make changes from this opportunity or via the 'Viewpath PM 4' tab.
- Open our Viewpath 4 - Salesforce Reports verifying our Sync is configured with your org.
In a new browser tab, open the Reports tab.
On the left edge, click on 'Viewpath_PM (Installed package...' to see our included reports.
Open report named 'Incomplete Projects in Viewpath_PM 4' in a new tab.
Open report named 'Late Tasks in Viewpath_PM 4' in the current Reports tab.
- Make changes on tasks of the project (like %Complete, Start, or Description).
Do this either on the 'Viewpath PM 4' tab or the Opportunity tab.
Click the 'Run Report' button on each tabs report to see the changes you made. Once you see Projects and Tasks changing in reports you may continue as sync is properly configured.
If you see no Projects or Tasks in Reports then you must use the Viewpath App menu to enable sync for the Organization the project(s) is in.
This following step must be done by someone that is both an administrator of the Viewpath Org as well as an Administrator of your Salesforce organization.
From Viewpath, got to Organizations and open the appropriate organization, then go to its Members tab. Look for the 3 Dot menu on the top right. Click that menu and choose 'Setup Salesforce Sync'.
If the Sync setup is successful, make some changes to a project in that org and refresh the Salesforce reports to see those changes. If the Sync setup fails, communicate with your admins and Viewpath support. You are blocked until the above is working!!
- Install our ViewpathPM4 Trigger Sample unmanaged package from this URL:
Get this installer URL by emailing firstname.lastname@example.org
Upon success of installation please continue on to verify the use cases below.
- B) Use Case Verification Steps:
- Open a new browser tab on the newly installed VP4_Audits tab. Get to this tab from the Salesforce + menu. Click the Go button to open the default view showing important fields of this object.
- Open another new browser tab on the newly installed VP4_TriggerCustomObject tab.
Click the New button on VP4_TriggerCustomObject tab as shown below:
Set name to something like MyProj1, use lookup on VP4_Project field to select a VP4_Project Name. Save this new object returning to the list. Click the Go button to open the default view showing important fields of this object.
- Make changes to tasks then reload the VP4_TriggerCustomObject tab to see its Start, Finish and ProjectStatusMsg fields populated as shown below:
- Also, reload the page for VP4_Audits to see new audit messages similar to what is shown below:
- One last thing to try is the Opportunity trigger extension.
Return to your opportunity tab and Edit Layout.
Add as the first item in the 'Viewpath Project' section the newly installed field named 'Project Status'.
Save layout to return to opportunity.
Look for a value like 'VP4 Prj Not Complete xx.x%' by the label for 'ProjectStatus' similar to what is shown below:
You are now ready to enjoy Viewpath 4 triggers on both Custom & Standard Objects.
Please connect with email@example.com if you have any questions.
If you have an interest in the code behind these samples, proceed on.
- C) Behind the scenes for developers - understanding how the code works:
The code pattern referenced here is based heavily upon an existing trigger method that was developed by Salesforce that may be found at: http://developer.force.com/cookbook/recipe/trigger-pattern-for-tidy-streamlined-bulkified-triggers.
In Salesforce open the SFDC Developer Console and the file we call out in bold at the beginning of the sections that follow:
Open class file VP_iTrigger:
As in the example at the source location listed above, we started by defining an interface that provides the template for our trigger handlers. This interface contains the method signatures each trigger handler must implement to support automation on inserts, updates and deletes.
Open class file VP_TriggerException:
Here we extended the generic Exception class creating our own VP_TriggerException.
Open class file VP4_TriggerFactory:
The key part of this file is the getHandler method at the bottom of the file. There we setup a new trigger handler class for both the Viewpath 4 Project object (Viewpath_PM__VP4Project__c) and Task object (Viewpath_PM__VP4Task__c). The triggers explained below make a call into this factory to instantiate the appropriate handler class.
Open trigger file VP4_ProjectTrigger
Here you see the one line that calls our VP4_TriggerFactory and its CreateHandler method to wire up the VP4Project__c custom object. You will also notice some commented code to throw exception for local testing of error handlers using the included VP4_UpdateTrigger_TestPage test page.
Open trigger file VP4_TaskTrigger
Here you see the one line that calls the VP4_TriggerFactory and its CreateHandler method to wire up the VP4Task__c custom object. As done with ProjectTrigger testing code is included.
Open class file VP4_Project_TriggerHandler:
We then added a handler class that implements the VP_iTrigger interface. In this file is the handler for the Viewpath_PM__VP4Project__c.
True to the example provided at the link above, we also write a record away to a custom object called VP4_Audit__c for each project deleted. This is shown in the beforeDelete method. This method is called iteratively for every Project record passed to the before delete trigger.
The other use case for Projects is located in the afterUpdate method. In the Try block we cast from the trigger fields to the get the correct types for the VP4Project fields like Key, Name, Completion, Start and Finish. A simple status message is created showing project completion or its percent complete when not finished.
Next, you will see the integration with the Opportunity object where we update our custom field (added with this sample) called ProjectStatus to the computed value of statusMessage. Note: we also extended with this sample, a lookup field for VP4_Project on Opportunity so that the user can easily associate a project to an opportunity.
Next, you will see our integration to a sample Custom Object named VP4_TriggerCustomObject__c. Simulating a large object of yours, we extended it with some fields like ProjectStatusMsg, Start and Finish.
Finally, you will see that we obtain the old values from the trigger (variable oldSo) so that we can make comparisons to detect what has changed from the new values (variable so). Each comparison then appends a changed message to the auditChangeMessage variable. Finally, we update the VP4_Audit object with the specific Project Name that was changed with a Description set to the auditChangeMessage and the VP_UpdatedBy field set to the user email of the one that made the change in Viewpath.
Open class VP4_Task_TriggerHandler:
Similar to what we did with the above Project handler, we do a simple version of auditChangeMessage for a small set of the task fields.
Contact support if you would like to extend either of these samples to a more production-ready solution.
Run the Visualforce page VP4_UpdateTrigger_TestPage
To run this page, go to Setup | Develop | Visualforce Pages and find VP4_UpdateTrigger_TestPage in the list. From the list click the link on the name to open it. From there click the Preview button to run the page.
You should see the page as shown in the screenshot below.
It has 2 sections; 1) the top for testing the VP4_ProjectTrigger and 2) the bottom for testing the VP4_TaskTrigger.
In the screenshot below, we edited the VP4_ProjectTrigger and uncommented the last line to introduce a Divide by 0 error. As we ran the top portion of the test page it displayed the error pointing to the ‘Divide by 0 Trigger: VP4_ProjectTrigger: line 9, column 1’.
If you enable this error for either Project or Task, be sure to put the comment back ASAP as the Viewpath Sync will fail if the trigger throws any errors.
The important value of this test page is to verify that your trigger code fires without error, and to easily allow you to repair errors quickly and with confidence.
Testing your Trigger Code Responsibly:
It’s critical that your trigger code is executing properly; failure to test your trigger could make it so that none of the Viewpath Projects or Tasks in your org get updated during the normal update pattern from Viewpath. Exceptions in your triggers will cause our API calls to your org to fail!
Use the above VP4_UpdateTrigger_TestPage to verify locally that your triggers do NOT throw exceptions!
- A) If you make changes to this sample trigger code, make sure you backup (external to Salesforce) all changes you made to the classes (particularly the class files for VP4_Project_TriggerHandler and VP4_Task_TriggerHandler).
- B) Viewpath_PM is a managed package, and should you decide to uninstall our package, you as a developer will need to temporarily remove all things dependent on objects that are controlled by the Viewpath_PM package. This trigger sample is an example of a dependency. You must remove (or comment code) in this sample before you could uninstall Viewpath_PM.
Ideally, you would install any new package version (without doing an Uninstall)! When installing on top of existing version our package is upgraded and you do not need to remove/comment out the dependencies. In our trigger sample, this would be the VP4Project and VP4Task objects.
- C) **Caution: Do not update or add VP4Project or VP4Task records from Salesforce** as it will result in Viewpath and these objects being out of sync. Changes in Viewpath will push to those objects and overwrite your changed values.
Happy coding and remember to test trigger changes early and test often.