├── .gitignore ├── CHANGELOG.md ├── CONTRIBUTING.md ├── Comment-standards.md ├── INSTALL.md ├── LICENSE ├── LICENSE.md ├── README.md ├── TERMS.md ├── _pages ├── APIs-use-and-generation-in-general.md ├── Agile-Methodology.md ├── Appendices.md ├── Bulkify-Code.md ├── Center-of-Excellence.md ├── Deployment-Pipeline.md ├── Exception-Handling.md ├── FAQs.md ├── FISMA-and-NIST-references.md ├── Guiding-Principles.md ├── Logging-&-Debugging.md ├── Org-Chart.md ├── Querying-Datasets-and-SOQL.md ├── Record-Level-Sharing.md ├── Salesforce-Best-Practices.md ├── Salesforce-Naming-Conventions.md ├── Security-Model-(Permission-Sets,-Profiles).md ├── SoftWare-Advisory-Group.md ├── Source-code-and-configuration-management.md ├── Technical-Approach.md ├── Testing.md ├── Tooling.md ├── Top-10-Best-Practices.md ├── Triggers.md ├── Unit-testing.md ├── Visualforce-Pages.md ├── Writing-good-tests.md ├── architecture-view.md ├── mission-vision.md ├── operations.md └── roles-&-responsibilities.md ├── img ├── Deployment-Pipeline.png ├── Outbound_Change_Set.png ├── PMO-ConOps.png ├── SWAGActivities.png ├── ep_team.png ├── failed_test.png ├── group_naming_example.png ├── group_naming_example_1.png ├── meeting-cadence.png ├── operations.png ├── package.png ├── passed_test.png ├── profile_model.png └── screenshot.png ├── opensource-checklist.md └── screenshot.png /.gitignore: -------------------------------------------------------------------------------- 1 | *.swp 2 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | All notable changes to this project will be documented in this file. 2 | We follow the [Semantic Versioning 2.0.0](http://semver.org/) format. 3 | 4 | 5 | ## 2.0.2 6 | - Added sections on naming public groups and queues, comment standards, updated testing requirements, fixed code block errors, fixed table formatting 7 | 8 | ## 2.0.1 9 | - Fix typos, grammar, etc. 10 | 11 | ## 2.0.0 12 | - Initial public release 13 | 14 | ## 0.9.0 15 | 16 | ### Added 17 | - Created initial repo. Will add content mid-August 18 | 19 | ### Deprecated 20 | - Nothing. 21 | 22 | ### Removed 23 | - Nothing. 24 | 25 | ### Fixed 26 | - Nothing. -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Guidance on how to contribute 2 | 3 | > All contributions to this project will be released under the CC0 public domain 4 | > dedication. By submitting a pull request or filing a bug, issue, or 5 | > feature request, you are agreeing to comply with this waiver of copyright interest. 6 | > Details can be found in our [TERMS](TERMS.md) and [LICENCE](LICENSE). 7 | 8 | 9 | There are two primary ways to help: 10 | - Using the issue tracker, and 11 | - Changing the code-base. 12 | 13 | 14 | ## Using the issue tracker 15 | 16 | Use the issue tracker to suggest feature requests, report bugs, and ask questions. 17 | This is also a great way to connect with the developers of the project as well 18 | as others who are interested in this solution. 19 | 20 | Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in 21 | the issue that you will take on that effort, then follow the _Changing the code-base_ 22 | guidance below. 23 | 24 | 25 | ## Changing the code-base 26 | 27 | Generally speaking, you should fork this repository, make changes in your 28 | own fork, and then submit a pull-request. All new code should have associated unit tests that validate implemented features and the presence or lack of defects.Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing code-base. 29 | -------------------------------------------------------------------------------- /Comment-standards.md: -------------------------------------------------------------------------------- 1 | ###Source Code and Configuration Management 2 | 3 | ####Comment Standards 4 | 5 | All methods should begin with a brief comment describing the functional characteristics of the method (what it does). This description should not describe the implementation details (how it does it) because these often change over time, resulting in unnecessary comment maintenance work, or worse yet erroneous comments. The code itself and any necessary inline or local comments will follow the standards as defined by the [SalesforceFoundation](https://github.com/SalesforceFoundation/ApexDoc#documenting-class-files): 6 | 7 | #####Class Comments 8 | 9 | Located in the lines above the class declaration. The special tokens are all optional. 10 | 11 | |token | description| 12 | |-------------|:--------| 13 | |@author | the author of the class| 14 | |@date | the date the class was first implemented| 15 | |@group | a group to display this class under, in the menu hierarchy| 16 | |@group-content | a relative path to a static html file that provides content about the group| 17 | |@description | one or more lines that provide an overview of the class| 18 | 19 | Example 20 | 21 | ``` 22 | /** 23 | * @author Salesforce.com Foundation 24 | * @date 2014 25 | * 26 | * @group Accounts 27 | * @group-content ../../ApexDocContent/Accounts.htm 28 | * 29 | * @description Trigger Handler on Accounts that handles ensuring the correct system flags are set on 30 | * our special accounts (Household, One-to-One), and also detects changes on Household Account that requires 31 | * name updating. 32 | */ 33 | public with sharing class ACCT_Accounts_TDTM extends TDTM_Runnable { 34 | ``` 35 | 36 | #####Property Comments 37 | 38 | Located in the lines above a property. The special tokens are all optional. 39 | 40 | |token | description| 41 | |-------------|:--------| 42 | |@description | one or more lines that describe the property| 43 | 44 | Example 45 | 46 | ``` 47 | /************************************************************************** ***************************** 48 | * @description specifies whether state and country picklists are enabled in this org. 49 | * returns true if enabled. 50 | */ 51 | public static Boolean isStateCountryPicklistsEnabled { 52 | get { 53 | ``` 54 | 55 | #####Method Comments 56 | 57 | In order for ApexDoc to identify class methods, the method line must contain an explicit scope (global, public, private, testMethod, webService). The comment block is located in the lines above a method. The special tokens are all optional. 58 | 59 | |token | description| 60 | |-------------|:--------| 61 | |@description | one or more lines that provide an overview of the method| 62 | |@param _param name_ | a description of what the parameter does| 63 | |@return | a description of the return value from the method| 64 | |@example | Example code usage. This will be wrapped in tags to preserve whitespace| 65 | 66 | Example 67 | 68 | ``` 69 | /************************************************************************** ***************************** 70 | * @description Returns field describe data 71 | * @param objectName the name of the object to look up 72 | * @param fieldName the name of the field to look up 73 | * @return the describe field result for the given field 74 | * @example 75 | * Account a = new Account(); 76 | */ 77 | public static Schema.DescribeFieldResult getFieldDescribe(String objectName, String fieldName) { 78 | ``` 79 | 80 | -------------------------------------------------------------------------------- /INSTALL.md: -------------------------------------------------------------------------------- 1 | # Installation instructions 2 | 3 | Detailed instructions on how to install, configure, and get the project running. 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 |
3 | CFPB Salesforce Development Standards 4 |
5 | 6 | **Status**: Live "production" version 2.0.1 7 | - [CHANGELOG](CHANGELOG.md). 8 | 9 | ### Purpose and Scope 10 | 11 | **This documentation describes guidelines for how applications in Salesforce should be built and deployed at the CFPB. The intended audience are Salesforce developers, administrators, and release managers.** 12 | 13 | It establishes the standards, controls, and guidance 14 | that enforce technical quality of the platform and product work that goes into CFPB’s Salesforce platform. It also describes the primary interfaces between the Enterprise Platforms Team (aka the CoE - Center of Excellence) 15 | and the various Product Teams building application solutions on the Salesforce platform. 16 | 17 | 18 | #### What this **is**: 19 | - Best practices for developing applications on the Salesforce platform 20 | - Coding standards 21 | - Automated testing standards 22 | - Security best practices 23 | - Deployment pipelines practices (continuous integration) 24 | 25 | 26 | #### What this is **not**: 27 | - Specific to the CFPB's operating environment 28 | - Operational instructions for how to get support; e.g., how to set up a developer sandbox; how to reset your password 29 | - How to integrate with third-party systems 30 | - A list of CFPB applications or products 31 | 32 | 33 | ### Goals 34 | 35 | 1. Provide a canonical reference for technical standards and guidelines 36 | 1. Assure only high quality software is built and deployed to CFPB’s Salesforce platforms 37 | 1. Maintain confidence in the deployment process and a high degree of availability for the CFPB salesforce org 38 | 1. Establish efficient developer workflows and share knowledge and practices across product development teams 39 | 1. Minimize operational burden for the Salesforce Platform Admin Team and the CFPB at large 40 | 1. Provide pertinent information to partners and vendors 41 | 42 | 43 | ### Salesforce Governance 44 | 45 | #### 1. Charter, Roles, and Operations 46 | - [Roles & Responsibilities](/_pages/roles-&-responsibilities.md) 47 | - [Salesforce Platform Charter](/_pages/mission-vision.md) 48 | - [Operations](/_pages/operations.md) 49 | 50 | 51 | #### Standards 52 | 53 | Note that technical design and implementation is reviewed by the Software Advisory Group (SwAG) 54 | and signed off by the Principal Architect and the CoE. 55 | 56 | - [FAQs](/_pages/FAQs.md) 57 | - [T&I Org Structure](/_pages/Org-Chart.md) 58 | - [Architectural View](/_pages/architecture-view.md) 59 | - [Security Model (Permission Sets, Profiles)](/_pages/Security-Model-(Permission-Sets,-Profiles).md) 60 | - [Sharing & Security](/_pages/Record-Level-Sharing.md) 61 | - [Software, Architecture, Data, and Visual Design Standards References] 62 | - [Technical Approach](/_pages/Technical-Approach.md) 63 | - [Agile Methodology](/_pages/Agile-Methodology.md) 64 | - [Center of Excellence (COE)](/_pages/Center-of-Excellence.md) 65 | - [Software Advisory Group (SwAG)](/_pages/SoftWare-Advisory-Group.md) 66 | - [Salesforce Best Practices](/_pages/Salesforce-Best-Practices.md) 67 | - [Exception Handling](/_pages/Exception-Handling.md) 68 | - [Testing & Debugging](/_pages/Testing-&-Debugging.md) 69 | - [Logging & Troubleshooting](/_pages/Logging-&-Debugging.md) 70 | - [Appendices](/_pages/Appendices.md) 71 | 72 | 73 | ---- 74 | 75 | ### Get involved 76 | 77 | Any feedback and contributions are welcome! 78 | 79 | Please familiarize yourself with the [CONTRIBUTING](CONTRIBUTING.md). Then, make suggestions for edits, report issues, etc., in the [issues section](/issues) of this repository. 80 | 81 | 82 | 83 | ### Open source licensing info 84 | 1. [TERMS](TERMS.md) 85 | 2. [LICENSE](LICENSE.md) 86 | 3. [CFPB Source Code Policy](https://github.com/cfpb/source-code-policy/) 87 | 88 | 89 | ---- 90 | 91 | ## Credits and references 92 | 93 | 1. TODO 94 | 95 | ---- 96 | -------------------------------------------------------------------------------- /TERMS.md: -------------------------------------------------------------------------------- 1 | As a work of the United States Government, this package (excluding any 2 | exceptions listed below) is in the public domain within the United States. 3 | Additionally, we waive copyright and related rights in the work worldwide 4 | through the [CC0 1.0 Universal public domain dedication][CC0]. 5 | 6 | Software source code previously released under an open source license and then 7 | modified by CFPB staff or its contractors is considered a "joint work" 8 | (see 17 USC § 101); it is partially copyrighted, partially public domain, 9 | and as a whole is protected by the copyrights of the non-government authors and 10 | must be released according to the terms of the original open-source license. 11 | Segments written by CFPB staff, and by contractors who are developing software 12 | on behalf of CFPB are also in the public domain, and copyright and related 13 | rights for that work are waived through the CC0 1.0 Universal dedication. 14 | 15 | For further details, please see the CFPB [Source Code Policy][policy]. 16 | 17 | 18 | ## CC0 1.0 Universal Summary 19 | 20 | This is a human-readable summary of the [Legal Code (read the full text)][CC0]. 21 | 22 | ### No Copyright 23 | 24 | The person who associated a work with this deed has dedicated the work to 25 | the public domain by waiving all of his or her rights to the work worldwide 26 | under copyright law, including all related and neighboring rights, to the 27 | extent allowed by law. 28 | 29 | You can copy, modify, distribute and perform the work, even for commercial 30 | purposes, all without asking permission. See Other Information below. 31 | 32 | ### Other Information 33 | 34 | In no way are the patent or trademark rights of any person affected by CC0, 35 | nor are the rights that other persons may have in the work or in how the 36 | work is used, such as publicity or privacy rights. 37 | 38 | Unless expressly stated otherwise, the person who associated a work with 39 | this deed makes no warranties about the work, and disclaims liability for 40 | all uses of the work, to the fullest extent permitted by applicable law. 41 | When using or citing the work, you should not imply endorsement by the 42 | author or the affirmer. 43 | 44 | [policy]: https://github.com/cfpb/source-code-policy/ 45 | [CC0]: http://creativecommons.org/publicdomain/zero/1.0/legalcode 46 | 47 | 48 | ## Exceptions 49 | 50 | _Source code or other assets that are excluded from the TERMS should be listed 51 | here. These may include dependencies that may be licensed differently or are 52 | not in the public domain._ 53 | -------------------------------------------------------------------------------- /_pages/APIs-use-and-generation-in-general.md: -------------------------------------------------------------------------------- 1 | ### Integrating Salesforce with External Systems 2 | 3 | There are many different APIs that Salesforce has to offer within its toolkit. Just as with using Lightning and Visualforce there are many considerations you must make when choosing a specific API to use. 4 | 5 | #### Inbound Requests 6 | 7 | Salesforce offers two primary types of APIs based on industry standards. The first is a SOAP based API, and the second is a REST based API. The REST API is very lightweight, has no WSDL definition file that is needed to install, and performs very well. The SOAP API is much heavier and slower than the REST API, but offers many more features and can handle many more records than the REST API. 8 | 9 | **SOAP API** 10 | 11 | The SOAP API was the very first API that Salesforce offered and as such is the most complete API available today. There are two flavors of this API available based on the type of user you are, and application that you are developing. The first is the enterprise API and the second is the partner API. Don’t be fooled by the names of the APIs. Just because you are not a partner, doesn’t mean that you can’t use the partner API. 12 | 13 | The SOAP API supports database operations such as query, insert, update, delete, as well as supports many other meta-data related requests related to users or understanding the Salesforce data model. For a complete reference to the functionality of the SOAP API you may view the developers guide at: 14 | 15 | [http://developer.salesforce.com/docs/atlas.en-us.api.meta/api/](http://developer.salesforce.com/docs/atlas.en-us.api.meta/api/) 16 | 17 | - **Enterprise API** 18 | 19 | The only difference between the enterprise and partner API is that the enterprise API is strongly typed to a specific Salesforce environment. The API exposes every Salesforce object standard and custom as data structures within the API. This makes it much quicker for one to develop, as there is no need to spend time creating data structures for each object you wish to work with within the org. 20 | 21 | The downside of the SOAP API is that every time you add a new field or object, or delete a field or object, you must re-import the WSDL that represents the new data structure. Deleting objects and fields is especially dangerous, as that will break your current integrations if you do not update the WSDL. 22 | 23 | - **Partner API** 24 | 25 | The partner API on the other hand is not strongly typed for any one particular environment. It was originally designed for Salesforce partners to use where the data model could be different for each customer using their integration. Many customers also use this API because it reduces the risk of something breaking because a field was deleted, and in the long term reduces the overall maintenance cost since a new WSDL does not need to be imported every time the data model changes and you wish to access the new fields and/or objects in the data structure. 26 | 27 | The downside of the Partner API is that there is a substantial amount of additional coding and work required for the initial implementation because you must generate your own XML within your code to bind to each object and field. Once the initial setup is complete, the ongoing maintenance is the same, if not less than that of the Enterprise API. 28 | 29 | **REST API** 30 | 31 | The REST API is an API that has similar functionality to that of the SOAP API, but is based on REST standards. That means there is no WSDL to download and maintain, and all requests are HTTP based using common Verbs such as Post, Get, Put, Patch, and Delete. The rest API takes requests and returns responses in either XML or JSON. 32 | 33 | The REST API is a good API to use when you need to make lightweight operations with a quick response, such as on mobile devices. 34 | 35 | Just like the SOAP API, the REST API supports database operations such as query, insert, update, and delete except that since the REST API is a newer API it is not as complete as the SOAP API. 36 | 37 | Aside from the actual functionality differences between the two APIs it is good to understand in general the differences between REST and SOAP. For more information on REST and SOAP visit the following sites below. 38 | 39 | [http://en.wikipedia.org/wiki/SOAP](http://en.wikipedia.org/wiki/SOAP) 40 | 41 | [http://en.wikipedia.org/wiki/Representational_state_transfer](http://en.wikipedia.org/wiki/Representational_state_transfer) 42 | 43 | **BULK API** 44 | 45 | The REST and SOAP APIs are great tools for general transactional real-time applications, but tend to fall apart when you need to work with large volumes of data. When working with data volumes of above 50,000 records you should look to using the BULK API. 46 | 47 | The BULK API is a REST based asynchronous API designed to handle inserting, updating, and deleting large amounts of data. Generally speaking the BULK API can act on up to 50 million records in a rolling 24-hour period according to the official documentation. If you need to work with a larger amount of data than 50 million records per day, you can contact Salesforce support to have your limits increased with proper justification. 48 | 49 | For more information on the developing with the BULK API and limits of the BULK API visit the following sites below. 50 | 51 | [https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_concepts_limits.htm](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_concepts_limits.htm) 52 | 53 | [https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/) 54 | 55 | **BEWARE OF YOUR DAILY API LIMITS** 56 | 57 | Every time you make a call to the SOAP or REST API you use an API call that is allotted to your organization on a rolling 24 hour period. If you use up all of your API calls on at 24 hour period then you will be no longer allowed to make calls to the SOAP or REST API until your rolling 24 hour usage has dropped below the limit. 58 | 59 | This is one of the main reasons why it is recommended that if you need to process more than 50,000 records, you use the BULK API, as the BULK API does not take up your daily API limits. For example, if you need to process 1 million records and use the SOAP API processing 200 records at a time, you will use up 5,000 of your API calls. Not only does this take a long time to process you are will endanger your organization of breaching this limit. This is especially true as you add more services to your organization that are using the SOAP or REST APIs. 60 | 61 | **Apex Web Services** 62 | 63 | If the SOAP API or the REST API won’t easily accomplish your business requirements, Salesforce allows you to create your own custom SOAP or REST API that you can expose for consumption by external systems. This API allows you to implement you own custom API methods with more complex logic than is available with the out of the box SOAP and REST APIs. 64 | 65 | Think of Apex Web Services as the "Custom API" where the SOAP and REST APIs are the “Out of the Box” APIs. The primary function for the out of the box APIs are for data movement and manipulation. Where the Custom API is more for working with smaller numbers of records where you need more complex logic application them. 66 | 67 | **BEWARE OF LONG RUNNING PROCESSES** 68 | 69 | When a custom API call that takes longer than 5 seconds to complete gets put into what is called a "long running process queue". If you have too many concurrent methods that are in this long running process queue, Salesforce will block all future calls to your custom APIs, long and short running, until the long running process queue drops below the max allowed value of 10 concurrent long running process. Any additional calls to the custom API while the long running process queue is full will receive the error “Concurrent Requests Limit Exceeded”. This limit is in place to protect customers against denial of service attacks. 70 | 71 | It is imperative that you take care when designing custom apex services that they do not take longer than 5 seconds to complete. This is why it is recommended that you only utilize these service to operate on smaller numbers of records to avoid long running processes. 72 | 73 | If you find that your methods are taking too long to complete you may want to think about breaking them up into multiple transactions. For example you may want to first call the SOAP API to retrieve the records and then send a smaller number of records at a time to the custom API. 74 | 75 | **Outbound Requests** 76 | 77 | In addition to exposing APIs to external systems, Salesforce also has a few mechanisms for making calls out to external systems. 78 | 79 | 1. **HTTP call-outs using Apex** 80 | 81 | If you need to make a call out to an external web service, using apex you can use the HTTPRequest and HTTPResponse objects to make and receive HTTP calls to external systems. This is ideal for communicating with simple services that require simple HTTP messages to be passed like a REST API. 82 | 83 | 2. **Call-Outs to SOAP APIs** 84 | 85 | Salesforce also supports making more complex call-outs to SOAP APIs as well. In order to communicate with an external SOAP service you will need to import the WSDL under Develop->Classes. Once the WSDL has been imported a facade class is generated for each of the methods in the SOAP service. You then can use apex to execute those methods to make a call-out to the SOAP service. 86 | 87 | Occasionally the WSDL will not import because the Salesforce WSDL parser does not understand the WSDL. In this case you will manually need to recreate the facade by hand. This procedure is out of scope of this document. 88 | 89 | 3. **Outbound Messaging** 90 | 91 | Using the WSDL importer and the HttpRequest or HTTPResponse apex objects are fine to use when you need to make point-to-point calls. The only drawback is if you are unable to connect to the external service and/or failures occur there is not retry mechanism. 92 | 93 | When you need more complex handling with retry mechanisms built-in in, you may want to consider using Salesforce Outbound Messaging services. Outbound Messaging is part of the Salesforce workflow and approvals system. An outbound message can be automatically executed when a record has been inserted or updated. The real power behind Outbound Messaging is that if an error occurs while communicating with the external service, the outbound message will retry later. The Outbound Messaging system will retry to send the message for up to 24 hours. 94 | 95 | There are a couple drawbacks to using Outbound Messaging. Multiple messages can be sent at the same time if multiple updates occur to a specific record. Don’t use outbound messaging if sequence of events is important, such as with logging. 96 | 97 | Additionally in order to use outbound messaging you must export a WSDL and implement the service on the other end. Many times the time required to implement this service is less time that it would take to implement the retry mechanisms already built into the Outbound Messaging capability. 98 | 99 | For more information on how Outbound Messaging works visit the page below. 100 | 101 | [https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_om_outboundmessaging_understanding.htm](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_om_outboundmessaging_understanding.htm) 102 | -------------------------------------------------------------------------------- /_pages/Agile-Methodology.md: -------------------------------------------------------------------------------- 1 | # CFPB Values and Agile Values 2 | 3 | CFPB's values - Lead, Serve, Innovate - are strong influences on our Agile practices. Our own Agile values, as written in this document, represent an integration of the CFPB's values with the values of the [Agile Manifesto](http://agilemanifesto.org/). 4 | 5 | ## __Individuals and interactions over processes and tools__ 6 | * Innovation starts with people and their needs - both consumers and our team members. We serve by leading (and vice-versa). 7 | * By valuing individuals, we can both serve and lead those individuals more effectively. 8 | * We should not justify the use of any process or tool simply because "we've always done it that way." 9 | 10 | ## __Working software over comprehensive documentation__ 11 | * In order to best serve the public and our coworkers, we must produce working software and iterate on that software. 12 | * We value demonstrating the capabilities of a product via working versions of that product. 13 | * We value documentation and retaining institutional knowledge, but no document can describe a product as well as a working version can demonstrate it. 14 | 15 | ## __Customer collaboration over contract negotiation__ 16 | * The best path to serving the public is to collaborate closely with internal and external stakeholders, subject matter experts, and others who can help us iterate to develop better products. 17 | * Servant-leadership requires finding ways to collaborate to constructive ends, to focus on shared values to decide upon shared goals, and to communicate effectively with any and all collaborators. 18 | * We value in-depth, close collaboration instead of detailed documents or memorandums. By focusing on shared goals, we can serve and satisfy stakeholders without the need for strict contracts. 19 | 20 | ## __Responding to change over following a plan__ 21 | * While we expect change, we can never fully anticipate what changes may come. Changes can come from new information about consumer or coworker needs, from usability research, or from the ever-changing consumer markets themselves. 22 | * We value turning each unexpected change into an opportunity to improve our product. What is important is not the change itself, but our response to the change. 23 | * Innovation requires thoughtful, constructive responses when changes come from outside the team. In this way, innovating creates leadership and service opportunities, where we can both trail-blaze new ways to solve problems and new ways to serve consumers and coworkers. -------------------------------------------------------------------------------- /_pages/Appendices.md: -------------------------------------------------------------------------------- 1 | 2 | - [Salesforce Naming Conventions](/_pages/Salesforce-Naming-Conventions.md) 3 | - [FISMA and NIST References](/_pages/FISMA-and-NIST-references.md) -------------------------------------------------------------------------------- /_pages/Bulkify-Code.md: -------------------------------------------------------------------------------- 1 | ## Bulkify All Code 2 | Bulkifying Apex code refers to the concept of making sure the code properly handles processing multiple records at one time. When a batch of records initiates Apex, a single instance of that Apex code is executed, but it needs to handle all of the records in that given batch. For example, a trigger could be invoked by a Force.com SOAP API call that inserted a batch of records. That trigger would need to be able to handle at least 200 records since triggers break up records into 200 record batches. As a rule of thumb make sure all apex code written can handle at least 200 records at a time. This number could be much greater as well for custom methods querying against large datasets. -------------------------------------------------------------------------------- /_pages/Center-of-Excellence.md: -------------------------------------------------------------------------------- 1 | ###Center of Excellence 2 | 3 | ###Overview 4 | 5 | This document is the charter for the Consumer Financial Protection Bureau (CFPB) Office of the Chief Information Officer (OCIO) Enterprise Platforms (EP) Center of Excellence (COE) (hereafter referred to as “COE”), and as such formalizes the responsibilities, process, and authority of this body. 6 | 7 | ###Authority 8 | 9 | This document includes the authority and responsibilities of the COE and its members who will abide by the practices set forth in this charter. This charter authorizes the COE to perform the following: 10 | - Review, approve, disapprove, and prioritize development initiatives within T&I’s enterprise platforms and commit resources to the development of approved initiatives 11 | - Review, approve, disapprove, and prioritize changes to configuration items within T&I’s enterprise platforms and commit resources to the implementation of approved changes 12 | - Manage T&I’s enterprise platforms application development, operations and maintenance processes 13 | - Ensure the technical quality of all software deployed to T&I’s enterprise platforms and of services integrated with these platforms 14 | 15 | ###Purpose 16 | 17 | This document establishes the authority, membership, roles, and administrative procedures for the Center of Excellence (COE). The COE is a decision-making body that provides oversight and management of CFPB’s enterprise platforms. The COE is the official mechanism for controlling the strategic direction of CFPB’s enterprise cloud, web-enabled and/or on-premise platforms and tools, such as Salesforce.com. The COE serves the following primary functions: 18 | - **Strategic Platform Roadmap and Standards** - for driving the technical direction and standards of the Bureau’s platforms in support of enabling business and process automation 19 | - **New Solution Review** - for new applications, initiatives, concepts, and high-level requirements provided by internal customers to determine enterprise applicability, collaboration opportunities, and platform destination 20 | - **Design Review** - for initial system designs prior to entering a development sprint 21 | - **Go Live Review** - for completed systems and releases prior to production deployment 22 | - **Change Request (CR) Review** - for changes to production applications / features or approved plans / processes 23 | 24 | ###Responsibilities 25 | 26 | The COE is responsible for making project-level tactical decisions for applications deployed to the Bureau’s Salesforce platform that support the strategic direction established by the Chief Information Officer in line with the Bureau’s Strategic Plan. 27 | 28 | The COE shall be responsible for the following activities, organized by primary function: 29 | 30 | - Strategic Platform Roadmap and Standards: 31 | - Define scope and permitted uses of enterprise application platforms at CFPB 32 | - Define strategy for use of CFPB’s enterprise platforms 33 | - Define technology and process standards for EP, the Platform Software Advisory Group (“SwAG” ) or COE 34 | - Render decisions in a timely manner 35 | - Maintain records of decisions 36 | - Perform due diligence 37 | - Communicate decisions to appropriate parties 38 | - Ensure adherence to approved processes 39 | - Share business and technology best practices across the organization 40 | - Escalate issues as needed to the CIO, Business Executive Sponsors, and higher level governance bodies 41 | 42 | - New Solution Review: 43 | - Review and approve every application concept and initiative considered for an enterprise platform within CFPB (e.g., Salesforce etc.), prior to T&I Project Gate 0 44 | - Authorize, categorize and prioritize development initiatives which use EP resources or will be hosted on an EP-controlled technology 45 | - Act as governance liaison to the Technology Committee and the CIO for all EP-related activities 46 | - Ensure alignment of priorities with enterprise initiatives, Enterprise Architecture (EA) and direction from higher level governance 47 | 48 | - Design Review: 49 | - Review design artifacts and “approve” or “disapprove” initial system / solution designs. This review is conducted by the SwAG and a final recommendation for approval or disapproval will be presented to the COE by the Principal Platform Architect. 50 | - Determine level and extent of resources within EP purview to commit to detailed analysis of approved initiatives 51 | 52 | - Go Live Review: 53 | - Validate that necessary activities prescribed by the EP COE process have been completed 54 | - Grant authority to move a system to Production (“Go-Live”) on one of the Bureau’s enterprise platforms (will still require T&I Project Gate 2 review and approval prior to release) 55 | 56 | - Change Request (CR) Review: 57 | - Authorize, categorize and prioritize configuration changes to T&I EP-controlled configuration items, which may include software or cloud environments, processes, approved plans, and other configuration items as defined by the EP COE 58 | - Support enterprise CR review and reporting for T&I’s Enterprise Change Control Board (CCB) based on T&I PMO’s published CCB criteria and thresholds 59 | 60 | **Roles** 61 | 62 | Membership of the COE consists of the following voting and non-voting member roles. 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 |
RolesGovt / Ctr*New Sol VoteDESIGN VoteGO LIVE VoteCR Vote
COE ChairGovt☑☑☑☑
Alternate COE ChairGovt☑☑☑☑
Platform Program ManagerGovt☑☑☑☑
Principal Platform ArchitectGovt☑☑☑☑
Platform Project Gov LeadGovt☑☑☑☑
Enterprise Architecture RepGovt☑☑☑☑
Data Team RepGovt☑☑☑
COE Solution ArchitectGovt or Ctr☑☑☑☑
COE Technical ArchitectGovt or Ctr☑☑☑
Cyber Security RepGovt or Ctr☑☑☑
COE FacilitatorGovt or Ctr
Platform Business AnalystGovt or Ctr
Project Management Office RepresentativeGovt or Ctr
Business Line RepresentativesGovt
185 | 186 | *Note: Only government employees may be voting members. In the event that a role above is being filled by a contractor, the voting check mark in the table above is instead a recommendation for those roles which are considered to have especially appropriate input to the type of vote indicated. 187 | 188 | ###COE Administration 189 | 190 | Normal COE meetings will be held on a weekly basis. If there are no items for review, COE meetings will be canceled at the discretion of the COE Chair. Additional meetings may also be scheduled at the Chair’s discretion to handle a high volume of agenda items. 191 | 192 | The COE Facilitator is responsible for maintaining calendar invites, reserving rooms, setting up WebEx or conference bridges, taking requests for agenda time, recording meeting attendance, and documenting / posting meeting minutes. The COE Facilitator will prepare an agenda for each COE meeting. Items to be considered for a COE meeting must be submitted to the Facilitator no later than one hour prior to the meeting. See request agenda request form here. 193 | 194 | Links to the COE agendas and meeting minutes can be accessed through the T&I Enterprise Platforms team Google Documents collection. 195 | 196 | ###Decisions 197 | 198 | - **New Solution Review** 199 | New solution concepts will be introduced at COE meetings by Platform Business Analysts (BA) who will be expected to present high-level requirements and the analysis conducted (Project Detail, Fit Gap Analysis) to make a platform decision to the COE. After each new solution concept is discussed, a vote will be taken to **approve, defer, or disapprove** the proposed item. The EP Program team will work with the business line(s) involved and T&I PMO to review scheduling, resources, and budget for the new solution request. 200 | 201 | - **Design Review** 202 | In order for an application or set of requirements to proceed to a development sprint or development contract, they must first go through a design review with the Platform Software Advisory Group (SwAG). The COE may decide to **approve or disapprove design** based on recommendation from the SwAG and Principal Platform Architect. 203 | 204 | - **Go Live Review** 205 | Prior to a new or updated platform release being approved for deployment to a production environment it must undergo a Go Live Review. The Go Live Review is driven by a Go Live checklist for the project / iteration and will happen prior to the T&I PMO Gate 2 review. The COE will vote to **approve go live, disapprove go live** as is, or **approve go live contingent** upon an ensuing task. For the latter decision, the approval will be considered to take effect once the contingent action is fulfilled. 206 | 207 | - **Change Requests (CRs)** 208 | CRs will be introduced to the COE by the product project teams or support and operations groups (e.g., centralized O&M team or app-specific groups). The COE will review the business justification for the CR submitted. At the conclusion of the CR review, the COE will **approve, disapprove, or defer** the CR. The COE Facilitator will notify the product manager and business owner and the T&I CCB (if required by threshold criteria). 209 | 210 | - **Emergency Requests** 211 | A virtual COE vote will be held for **only** emergency requests. The virtual voting process will follow the normal COE process except that no actual meeting will be held and voting will be conducted through email. 212 | 213 | The COE will be responsible for: 214 | 215 | - Validating that the request is an actual emergency 216 | - Ensuring that no action is taken in the event that a quorum is not reached 217 | - Recording the decision 218 | - Ensuring that each emergency request is processed in a timely manner 219 | 220 | - **Quorum Requirement** 221 | COE members are expected to participate in each meeting. In order for the outcome of a COE vote to be official there must be a minimum of three voting members present (in person or remotely via WebEx or conference call), including a COE Chair or Alternate COE Chair. In the event that neither the official COE Chair or Alternate Chair may be present, they may each designate in writing a secondary alternate who may fulfill the quorum requirement in their absence. Note that only government employees may be voting members or COE Chairs. 222 | 223 | When a quorum is present, COE decisions will be based on a majority vote of the present voting COE members. In the event of a tie, the COE Chair will exercise executive decision making authority to approve, defer, or disapprove the decision. 224 | 225 | The COE Chair has the authority to veto all decisions, though in cases where a veto goes against the majority the rationale for the veto must be documented. All change requests, excluding Emergency Change Requests, will be voted on during the weekly COE Meetings. If a quorum is not present, voting will be deferred until the next COE meeting. 226 | 227 | - **Supporting Tool(s)** 228 | Change Requests will be tracked in the Remedyforce application and any changes that elevate to the level of a CCB review will also be tracked in the Bureau’s Redmine Tool. 229 | 230 | ###Changes to the Charter 231 | Any proposed changes to this COE Charter may be reviewed and approved as a standard CR. This charter will be reviewed annually or as required. Any necessary revisions will be made and tracked via the charter revision history. 232 | 233 | ###Appendix A 234 | 235 | **Acronym List** 236 | 237 | BA - Business Analyst
238 | CCB - Change Control Board (or Configuration Control Board)
239 | COE - Center of Excellence
240 | CR - Change Request
241 | SwAG - Software Advisory Group - The SwAG is composed of a diversified team of architects (technical, solution, product-specific) with expertise in technologies the Bureau supports 242 | T&I - Technology & Innovation 243 | 244 | ###Appendix B 245 | 246 | **COE Membership** 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 |
NameCOE RoleGovt or Ctr
Katherine KravchonokChairGovt
Dave CassidyAlternate Chair / Platform Program ManagerGovt
Bill SheltonPrincipal Platform ArchitectGovt
Adebimpe AbanishePlatform Project Gov LeadGovt
Miklane ChangEnterprise Platform DeveloperGovt
Tim RyanEnterprise Architecture RepGovt
TBDData Team RepGovt
Jo DengCOE Solution ArchitectCtr
Joe GrefenstetteCOE Technical ArchitectCtr
Rincy Issacs / Bryan RoundtreeCOE Data ArchitectCtr
Dwayne McDonaldCyber Security RepGovt
Alexis WuCOE FacilitatorCtr
Platform Business Analyst
Project Management Office Representative
Business Line Representatives
330 | 331 | 332 | 333 | -------------------------------------------------------------------------------- /_pages/Deployment-Pipeline.md: -------------------------------------------------------------------------------- 1 | ###Deployment Pipeline 2 | 3 | ####Process Overview 4 | The goal of the release management process is to create a process that defines 5 | 6 | 1. The environments necessary to enable multiple project teams to concurrently develop applications on the Salesforce platform 7 | 1. The mechanism that enables project teams to easily move Salesforce configuration and code from one environment to another 8 | 1. The process that all Salesforce project teams follow to deploy code and configuration from one environment to another in a repeatable fashion to ensure business continuity while reducing the total time of deployment of applications to production. 9 | 10 | ####Development Models 11 | There are two different models that a project team can use while developing their applications. 12 | 13 | 1. **Centralized Development Model** - A centralized development model is a development structure in which all team members configure and develop Salesforce applications in a single environment. This structure is typically used when there are a small number of developers working on separate capabilities that do not conflict with each other. 14 | 1. **Distributed Development Model** - A distributed development model is a development structure in which each developer has their own dedicated Salesforce sandbox where they develop application features. They can perform configuration and code changes in their dedicated environment. When they have completed a specific feature, that feature is then deployed to a master team development environment that is typically controlled by a project lead. This allows many developers to function independently without impacting other team members. This structure is typically used for larger development teams. 15 | 16 | ####Salesforce Environments 17 | The salesforce environments used for Salesforce releases are broken up into categories: 18 | 19 | **Project Environments** - Project environments are Salesforce sandbox environments that are dedicated to a single project team. The project team has full access to the environments and does not share the environments with any other project team. The project team members manage all releases among all of their environments and choose the level of access each member has to each of their environments. 20 | 21 | Project team environments consist of the the following environments: 22 | 23 | 1. **Project Dev** - The project development environment is where the master code and configuration will reside for the project’s application. 24 | 25 | 1. **Project UAT/Build** - The project UAT/Build environment is the environment where the project team will deploy their code on a routine basis from the project dev environment to test and demo their application to end users. No development should occur in the Project UAT/Build environment. 26 | 27 | 1. **Individual Developer Environments** - If a project team is using the distributed development model, then they will have individual developer sandboxes dedicated to each developer. When a developer is done with a particular feature, then that feature is deployed to the Project Dev environment. 28 | 29 | 1. **Project Data** - If a project team is conducting a data migration they may request an additional sandbox in which to practice their data migration. The type of sandbox may vary based on the number of records being loaded. 30 | 31 | **NOTE:** Individual developer environments can also be used in either model for proof of concepts. Project teams should avoid creating proof of concepts in their Project Dev org if at all possible. 32 | 33 | **Platform Environments** - Platform environments are Salesforce sandbox environments that are shared across all project teams. Access to these environments is limited for the project team members. The platform release manager is the owner of the platform environments and manages all releases among the different environments including production. 34 | 35 | Platform environments consist of the the following environments: 36 | 37 | 1. **Integration** - The integration environment is the first environment where all project teams deploy to the same environment. The purpose of the integration environment is to verify that each project’s applications will deploy and not adversely affect another project team’s application. Once a project team’s application is deployed to the integration environment successfully, the project team would then perform system level testing to verify that the application works as expected. Also at this time the project team will also test any integrations to other external systems. 38 | 39 | 1. **UAT** - The UAT environment is where all of the user acceptance testing is performed for each project’s applications that will be deployed to production. The UAT environment is a full sandbox allowing for a complete end to end testing to occur with a complete data set. Because this environment contains production data, only users that have been cleared to interact with production data are granted access to this environment. Typically access in this environment will mirror the access levels granted in production. 40 | 41 | 1. **Staging** - The staging environment is an environment primarily reserved for the release manager. This environment is used by the release manager to perform the final deployment rehearsal before deploying to production. This gives the release manager one more chance to catch any problems with the deployment steps. Once the deployment has been completed to staging, the release manager will grant temporary access to the project team to perform a sanity check to make sure that the deployment to staging was successful and the application performs as expected. 42 | 43 | 1. **Production** - This is the live environment where users are actively using the system. 44 | 45 | ####Deploying to Production 46 | In order to deploy a release to production, the project team must first deploy their code and configuration to the different platform environments described above. The reason that the team must first deploy to these lower environments is so that we can verify that your application works as expected, does not conflict with other teams environments, and does not experience any complications during deployment. 47 | 48 | 49 | Below you will find a diagram of the environments described above depicting the flow a deployment must go through in order to be deployed to production. 50 | 51 | ![Deployment](/img/Deployment-Pipeline.png) 52 | -------------------------------------------------------------------------------- /_pages/Exception-Handling.md: -------------------------------------------------------------------------------- 1 | 2 | ## Exception Handling 3 | 4 | ### Abstract 5 | 6 | Similar to most modern languages, Apex supports exception handling using try/catch blocks. As a best practice you should always encapsulate your code within a try/catch when there is a possibility of an exception occurring within your code. 7 | 8 | ### Catching Exceptions 9 | 10 | As of version 36.0 of the Salesforce API, there are 24 different types of exceptions that can be caught. When catching exceptions you should always try to catch the specific types of exceptions, whenever possible, as well as include a try/catch block to catch general exceptions outside of the specific ones when it makes sense. 11 | 12 | Working with our example from before notice that we are catching a "DMLException". Since this is the only type of exception that could occur within this code, there was no need to wrap the entire code within a general exception block. 13 | 14 | ```java 15 | public with sharing class SampleClass 16 | { 17 | public List updateLeads(List leads) 18 | { 19 | try 20 | { 21 | insert leads; 22 | } 23 | catch(DMLException e) 24 | { 25 | System.Debug(‘An error occurred while inserting leads. Exception: ‘ + e.getLineNumber() + ‘:’ + getStackTraceString); 26 | } 27 | } 28 | } 29 | ``` 30 | 31 | If we expand our example with some more logic we need to make sure that we catch any unexpected exceptions that would occur when looping through our lead list. Perhaps we are setting a value that is not an acceptable value for the data type of a field on the lead record. 32 | 33 | Take note that we are catching 3 types of exceptions: 34 | 35 | 1. QueryException – To catch any exceptions that occur when retrieving the lead records. 36 | 37 | 2. DMLException – To catch any exceptions that occur when inserting the lead records. 38 | 39 | 3. Exception – To catch any other exceptions that may occur when looping through the lead records. 40 | 41 | ```java 42 | public with sharing class SampleClass 43 | { 44 | public List getLeads(Date CreatedDate) 45 | { 46 | List leads; 47 | 48 | try 49 | { 50 | leads = [SELECT id,FirstName,LastName FROM Lead WHERE CreatedDate =: CreatedDate]; 51 | } 52 | catch(QueryException e) 53 | { 54 | System.Debug(‘An error occurred while retrieving leads. Exception: ‘ + e.getLineNumber() + ‘:’ + getStackTraceString); 55 | } 56 | 57 | System.Debug(‘Leads Retrieved: ‘ + leads); 58 | Return leads; 59 | } 60 | 61 | public List updateLeads(List leads) 62 | { 63 | try 64 | { 65 | try 66 | { 67 | for(integer i=0;i getLeads(Date CreatedDate) 17 | { 18 | List = leads = [SELECT id,FirstName,LastName FROM Lead WHERE CreatedDate =: CreatedDate]; 19 | System.Debug('Leads Retrieved: ' + leads); 20 | } 21 | } 22 | ``` 23 | 24 | While writing Apex code you should always make sure to add debug statements in key areas of your code that would help in debugging should errors occur. 25 | 26 | Take a look at the example below that expands our example above. 27 | 28 | ```java 29 | Public with sharing class SampleClass 30 | { 31 | public List getLeads(Date CreatedDate) 32 | { 33 | List = leads = [SELECT id,FirstName,LastName FROM Lead WHERE CreatedDate =: CreatedDate]; 34 | System.Debug('Leads Retrieved: ' + leads); 35 | } 36 | 37 | public List updateLeads(List leads) 38 | { 39 | try 40 | { 41 | insert leads; 42 | } 43 | catch(DMLException e) 44 | { 45 | System.Debug('An error occurred while inserting leads. Exception: ' + e.getLineNumber() + ':' + getStackTraceString); 46 | } 47 | } 48 | } 49 | ``` 50 | Notice in the code above that we have added a new method to update our lead records and have added a try/catch block to catch an exception that has occurred. 51 | 52 | Adding debug statements within the catch block is an excellent way to help troubleshoot issues in the future. 53 | 54 | ### Custom Logging 55 | 56 | The Salesforce debug log is good way to debug your code when you have a limited amount of logs that you want to review over a short period of time. When the Salesforce debug log breaks down is when you want to review logs for issues that occurred the previous day or before. Additionally, if you wish to receive a notification of when an issue occurred this is also outside the scope of functionality of the Salesforce debug log. 57 | 58 | It is for use cases like these that you want to use a custom logging framework in addition to the debug log to adequately troubleshoot your code. 59 | 60 | The logging framework should write log entries to a custom object. From there you can create workflow rules to send email notifications, create tasks, or even create a ticket in an external system when an error event occurs. 61 | 62 | Although this is a very helpful approach to logging and error notification in Salesforce you must take care when using it. Unlike using the debug log you must write records to the logging object for this approach, which takes up DML calls (Apex's Data Manipulation Language) that may be needed for your application. Keep in mind your DML limits at all times when using this approach. Also keep in mind that every record created will also take up storage in your org so you will need to develop an approach for deleting log records that are no longer needed. 63 | 64 | Make sure that when using this custom logging approach, you write a mechanism that will allow you to set the logging level and turn on/off logging by user and/or profile using custom settings by application. This will help you to avoid creating thousands of logging records unnecessarily taking up storage limits. 65 | -------------------------------------------------------------------------------- /_pages/Org-Chart.md: -------------------------------------------------------------------------------- 1 | ## Technology & Innovation Overview 2 | 3 | 4 | **Chief Data Officer** 5 | - Data policy and engineering 6 | 7 | **Cyber Security** 8 | - Information security policy, engineering, and monitoring 9 | 10 | **Design and Development** 11 | - Custom application development for http://consumerfinance.gov and other platforms 12 | 13 | **_Enterprise Platforms Teams_** 14 | - Programs: Manage customer and business engagement, manage contracts 15 | - Operations: Manage technical implementation of platform, including deployments, change management, and support requests 16 | 17 | **Infrastructure** 18 | - Responsible for data centers and operating environments 19 | - Also responsible for end-user support, laptops, Blackberries, etc 20 | 21 | **Project Management Office (PMO)** 22 | - Coordinates all T&I projects, including intake, and prioritization 23 | 24 | 25 | 26 | ____ 27 | 28 | #### T&I Enterprise Platforms Team (EPT) 29 | The Enterprise Platforms Team provides consultative platform services to T&I’s business line customers and is a decision-making body that provides program and engineering oversight and management of CFPB’s enterprise platforms; this includes project selection and implementation. (e.g., Salesforce) Support is focused around T&I Enterprise Platforms. (e.g., Salesforce, Box.) 30 | 31 | ##### Mission 32 | To enable the success of our business partners in achieving their mission by leveraging the Bureau’s enterprise platforms to deliver comprehensive solutions in a cost-effective, efficient manner 33 | 34 | ##### Vision 35 | Striving to be the Bureau’s leader in business enablement, innovation and delivery excellence 36 | 37 | 38 | #### CoE - Center of Excellence structure 39 | ![Enterprise Platforms - CoE](/img/ep_team.png) 40 | 41 | 42 | 43 | -------------------------------------------------------------------------------- /_pages/Querying-Datasets-and-SOQL.md: -------------------------------------------------------------------------------- 1 | ## Querying Large Data Sets 2 | The total number of records that can be returned by SOQL queries in a request is 50,000. If returning a large set of queries causes you to exceed your heap limit, then a SOQL query for loop must be used instead. It can process multiple batches of records through the use of internal calls to query and queryMore. If is possible to hit the heap limit and never even reach the max record limit of 50,000 records if you are querying a large number of fields in an object. 3 | 4 | // A runtime exception is thrown if this query returns 5 | // enough records to exceed your heap limit. 6 | Account[] accts = [SELECT id FROM account]; 7 | 8 | Instead, use a SOQL query for loop as in one of the following examples: 9 | 10 | // Use this format for efficiency if you are executing DML statements 11 | // within the for loop. Be careful not to exceed the 150 DML statement limit. 12 | for (List acct : [SELECT id, name FROM account 13 | WHERE name LIKE 'Acme']) 14 | { 15 | // Your code here 16 | update acct; 17 | } 18 | 19 | Let the Force.com platform chunk your large query results into batches of 200 records by using this syntax where the SOQL query is in the for loop definition, and then handle the individual datasets in the for loop logic. 20 | 21 | **Note:** This approach is the one time when it is acceptable to use DML (insert, update, delete) inside of a for loop. You still need to be weary of the 150 DML statement limit within the loop. 22 | 23 | ## SOQL Query Optimization 24 | When writing SOQL queries you want to make sure that your queries will perform when running against both small and large datasets. The following are some best practices to use to build performing SOQL queries. 25 | * Always limit the number of records that to be returning by the query by using the LIMIT keyword. 26 | * Never use fields that are not indexed in the WHERE clause. 27 | * Keep your queries as selective as possible and use custom indexes to improve performance. 28 | * Try to avoid using the “NOT IN” keyword as this is a very expensive in regards to performance. 29 | * Try to use the “AND” operator, and limit the use of OR operators in your statements. 30 | * Try to avoid using a combinations or “AND” and “OR” operators in your statements. 31 | * Try to avoid using the “ORDER” operator as it takes a lot of processing 32 | * Use StartsWith as much as possible for query filters. Techniques such as reverse phone numbers can be used in this approach. 33 | * Use record types to help with data segmentation 34 | * Create skinny tables for commonly searched fields to decrease search times. 35 | * Use the Salesforce query optimizer located in the developer console to make sure that your query will perform. Performing queries should have a score of less than 1. The closer to 1 the score, the worse the query will perform. 36 | 37 | #### Demonstrative Example 38 | The following are examples of bad SOQL queries. 39 | 40 | |Query | Reason | 41 | |-------------|:--------| 42 | ```SELECT Id, Name FROM Account```|This will return every record in the account object. This query will most likely never finish. 43 | ```SELECT Id, Name FROM Account WHERE Active = true```|This query is more selective than the last, but still would return too many records and would most likely never finish. 44 | ```Select Id, Name FROM Account WHERE Name NOT IN: myAccountsList```|This query fairly selective, but would still be an expensive query because the “NOT IN” operator is very processing intensive. Use the “IN” operator instead of “NOT IN” wherever possible. 45 | 46 | The following are examples of good SOQL queries 47 | 48 | |Query | Reason | 49 | |-------------|:--------| 50 | ```Select, Id, Name FROM Account WHERE name = ‘Salesforce’ LIMIT 1``` |Very selective query limiting the records returned to 1. 51 | ```Select Id, Name FROM Account WHERE CreatedDate = Yesterday LIMIT 99```|Very selective query limiting to just the records created within the past 24 hours. Also the query limits the total records returned to 100. 52 | 53 | ## Never use SOQL queries or DML statements inside FOR loops 54 | A common mistake is that queries or DML statements are placed inside a for loop. There is a governor limit that enforces a maximum number of SOQL queries. There is another that enforces a maximum number of DML statements (insert, update, delete, undelete). When these operations are placed inside a for loop, database operations are invoked once per iteration of the loop making it very easy to reach these governor limits. 55 | 56 | Instead, move any database operations outside of for loops. If you need to query, query once, retrieve all the necessary data in a single query, then iterate over the results. If you need to modify the data, batch up data into a list and invoke your DML once on that list of data. 57 | 58 | This practice definitely creates some complications but is critical to ensuring governor limits are not reached. 59 | Here is an example of what NOT to do (*incorrect lines): 60 | 61 | //For loop to iterate through all the incoming Account records 62 | for(Account a: accounts) { 63 | 64 | //THIS FOLLOWING QUERY IS INEFFICIENT AND DOESN'T SCALE 65 | //Since the SOQL Query for related Contacts is within the FOR loop, if this 66 | //trigger is initiated 67 | //with more than 100 records, the trigger will exceed the trigger governor limit 68 | //of maximum 100 SOQL Queries. 69 | 70 | *List contacts = [select id, salutation, firstname, lastname, email 71 | from Contact where accountId = :a.Id]; 72 | 73 | for(Contact c: contacts) { 74 | c.Description=c.salutation + ' ' + c.firstName + ' ' + c.lastname; 75 | 76 | //THIS FOLLOWING DML STATEMENT IS INEFFICIENT AND DOESN'T SCALE 77 | //Since the UPDATE DML (data manipulation language) operation is within the FOR loop, if this trigger is 78 | //initiated with more than 150 records, the trigger will exceed the trigger 79 | //governor limit of 150 DML Operations maximum. 80 | 81 | *update c; 82 | } 83 | } -------------------------------------------------------------------------------- /_pages/Record-Level-Sharing.md: -------------------------------------------------------------------------------- 1 | ###Sharing & Security 2 | 3 | There are many different mechanisms in which access to Salesforce is controlled. It is easiest to think of security in Salesforce broken up into the following 3 different categories: 4 | 5 | 1. **Object Level Access** – Object level access controls the access various Salesforce standard and custom objects such as Account, Contact, Opportunity, or custom objects you create. Object level access defines if a user has access to Read, Create, Update, or delete records within that object. Additionally object level access also controls which fields users are allowed to view or update on those objects. All object level access within Salesforce is controlled by Profiles and Permission Sets. 6 | 7 | 1. **Record Level Access** – Once a user has access to a specific object, users can then be limited to view or edit only specific records within that object. This is what we refer to as "Record Level" sharing within Salesforce. Sharing of records is controlled by Salesforce Organization-wide defaults, Criteria Based Sharing, Roles, manual sharing, and Apex Sharing. 8 | 9 | 1. **System & Application Level Access** – System and application level access is access users are granted to perform specific actions across the Salesforce application. There are many different actions a user can perform that can be controlled such as user creation, ability to export data, ability to modify setup objects, etc. These permissions are controlled by Profiles and Permission Sets. 10 | 11 | ###Profiles & Permission Sets 12 | 13 | As mentioned above Profiles & Permission Sets control the object level access and System & Application level access for users. You can pretty much do the same thing with Profiles and Permission Sets except for that a user can only have one profile where you can assign multiple permission sets to a user or profile. 14 | 15 | It is recommended to use profiles to create a base set of permissions for users of specific groups. Then create permission sets for each application that users will need access to for each type of role in that application. For example: 16 | 17 | **Profiles** 18 | 19 | System Administrator 20 | 21 | Sales User 22 | 23 | Legal User 24 | 25 | Marketing User 26 | 27 | 28 | **Permission Sets** 29 | 30 | Order Management Application User 31 | 32 | Order Management Application Admin 33 | 34 | The permission sets would be assigned on a user-by-user basis based on the applications that the users need access to. This allows you to easily add or remove access to users for specific applications instead of having to create profiles of various different combinations to handle the same use cases. Think of permission sets as similar to Access Control Lists (ACL). 35 | 36 | 37 | 38 | ###Salesforce Sharing 39 | 40 | Salesforce sharing controls what records users have access to view and edit. Keep in mind that since the profile and permission sets control object level access, if a user doesn’t have access to a particular object, then even if sharing allows them to view or edit records within that object, they will not have access to those records since they don’t have access to the entire object through profiles or permission sets. 41 | 42 | When working with Salesforce sharing it is always best to use the most global sharing mechanisms first, then move to the more granular controls. As you move to the more granular sharing controls you need to be more aware of performance considerations. 43 | 44 | The following are the Salesforce sharing controls available. 45 | 46 | ###Organization-Wide Defaults 47 | Organization-Wide defaults are the highest level and most restrictive sharing controls available on the platform. These settings control the visibility of records on a global scale for objects. These settings are set on an object by object basis. 48 | 49 | The following are the available options: 50 | 51 | ***Public Read/Write/Transfer*** 52 | Public Read/Write/Transfer is the least restrictive organization-wide default and is available only for the lead and case object. This setting allows every user to view, edit, and change ownership of every record within the lead or case objects that are set to “Public Read/WriteTransfer” regardless of their other sharing settings. 53 | 54 | ***Public Read/Write*** 55 | Public Read/Write is the second least restrictive organization-wide default and is available for most standard and all custom objects. This setting allows every user to view and edit every record within the objects that are set to “Public Read/Write” regardless of their other sharing settings. 56 | 57 | ***Public Read Only*** 58 | Public Read Only is the second most restrictive organization-wide default and is available for most standard and all custom objects. This setting allows every user to view every record within the objects that are set to “Public Read Only” regardless of their other sharing settings. Users cannot edit records within the objects set to “Public Read Only” unless they are granted “edit” access through other sharing settings. 59 | 60 | ***Private*** 61 | Private is the most restrictive organization-wide default and is available for most standard and all custom objects. This setting restricts every user from viewing or editing records within the objects that are set to “Private” unless they are granted “view” or “edit” access through other sharing settings. 62 | 63 | ###Criteria Based Sharing (Sharing Rules) 64 | Criteria based sharing is rule or owner based sharing that grants read or read/write access for a set of records to specific groups of users. Criteria Based Sharing is the next level of sharing controls below organization wide defaults. 65 | 66 | There are two types of rules that can be created. 67 | 68 | ***Based on Record Owner*** 69 | Rules based on record owner grant access to users in specific roles or groups to records that are owned by users within specific roles or groups. 70 | 71 | ***Based On Criteria*** 72 | Criteria based rules grant access to users in specific roles or groups to records that match specific criteria on the records within the object. 73 | 74 | ###Role Based Sharing 75 | Roles are hierarchal groupings of users within a Salesforce org. Role based sharing propagates the access to records that users have to users up the role hierarchy. 76 | 77 | For example: If the following role hierarchy exists: 78 | 79 | Sales VP 80 | | 81 | Sales Executives 82 | 83 | Then anyone that is a member of the “Sales VP” role will inherit the access from everyone in the “Sales Executives” role. 84 | 85 | ***Note:*** In order for access to be granted via role hierarchies the setting “Grant Access Via Hierarchies” must be checked for each object that you wish to respect role hierarchy sharing. 86 | 87 | 88 | 89 | ###Manual Sharing 90 | Manual sharing is the most granular and least performing of all sharing mechanisms within Salesforce. Care must be taken when using manual sharing as too many manual sharing rules on any single object can cause a delay in response time when viewing records on that object. 91 | 92 | Manual sharing allows the owner of a record to manually grant (share) read or read/write access to a record to another user, group, or role. 93 | 94 | Manual shares can also be created programmatically using apex or apex triggers. Use caution while programmatically creating manual shares via apex as you can easily cause performance degradation if you are adding a large number of shares to a single object. 95 | 96 | ###Special Permissions That Affect Sharing 97 | There are special permissions that can be set via profiles and permission sets that can override the Salesforce sharing settings. 98 | 99 | These permission exist in two types: 100 | 101 | ***System / Administrative*** 102 | Under the system permissions you will find the permissions “view all data” and “modify all data”. If a user has these permissions, the user will be able to view and/or edit all records for all objects regardless of the sharing settings set. 103 | 104 | Be very careful when setting these permissions, as these permissions will open up access to all of your data to a single user. Even if a field is set as read-only on the object profile permissions, the user will still have full access to the object as well. 105 | 106 | ***Object Level*** 107 | In addition to the ability to grant global read or edit access to all records across all objects, you can set read or edit access for all records for only a single object. At the object level if you set the permissions “view all” or “modify all” then all users in the profile or permission set will be able to view and/or edit all records within that object regardless of the sharing settings. 108 | -------------------------------------------------------------------------------- /_pages/Salesforce-Best-Practices.md: -------------------------------------------------------------------------------- 1 | - Secure coding practices [Contribute!](../CONTRIBUTING.md) 2 | - [Querying Datasets and SOQL](/_pages/Querying-Datasets-and-SOQL.md) 3 | - [Bulkify Code](/_pages/Bulkify-Code.md) 4 | - [Triggers](/_pages/Triggers.md) 5 | - [Visualforce Pages](/_pages/Visualforce-Pages.md) 6 | -------------------------------------------------------------------------------- /_pages/Salesforce-Naming-Conventions.md: -------------------------------------------------------------------------------- 1 | ##Salesforce Naming Conventions 2 | 3 | Naming conventions make the application easier to read and maintain. The naming standards documented here cover customization and configuration areas of salesforce. Regardless of the context in which names are used, Names should be descriptive, concrete, and specific rather than general. Having a generalized name such as ProductLine can have different semantics depending upon the context. It’s better to use something the business identifies with and that will not create a potential conflict with other applications; e.g., ReverseMortgage. 4 | 5 | ### 1. Custom Objects 6 | #### Rules for Naming 7 | Custom object names should be unique, beginning with an uppercase letter. Whole words should be used and use of acronyms and abbreviations should be limited. The object name should be singular (e.g. Review vs. Reviews, or OrderItem vs. Order Items) and should not include any underscores "_". The object label when at all possible should be similar to that of the object name since giving the label a different name than the object will make the object hard to find in some place within Salesforce. 8 | 9 | #### Exceptions 10 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. Added an underscore is acceptable if you are prefixing the object name to denote it is part of an application. For example: OrderApplication_Order and OrderApplication_OrderItem. Notice that OrderItem does not have any underscores. 11 | 12 | #### Demonstrative Example 13 | The following are examples of custom object naming that should _not_ be used 14 | The following are examples of custom object naming that should _not_ be used 15 | 16 | |Object Name | Reason | 17 | |-------------|:--------| 18 | ```CustAsset```| Abbreviations have made this object name hard to understand 19 | ```Orders``` | Object names should always be singular. 20 | ```Order_Item``` | Object names should not have underscores. 21 | 22 | The following are examples of the naming convention that will be used: 23 | 24 | |Object Name | Reason | 25 | |-------------|:--------| 26 | ```CustomerAsset``` | Removing ambiguity from the name will improve readability and maintainability 27 | ```Order``` | Making object names singular will ensure a standard naming convention across all objects. 28 | ```OrderItem``` | Removing all underscores will help keep a standard naming convention as many times there are words that some may separate into two words and other may not. For example: ```Zipcode``` vs. ```Zip Code```. 29 | 30 | ____ 31 | 32 | ### 2. Custom Fields 33 | 34 | ##### Rules for Naming 35 | Custom object names should be unique, beginning with an uppercase letter. Whole words should be used and use of acronyms and abbreviations should be limited. Similar to custom object naming, custom fields should not contain any underscores "_". When creating custom fields always complete the “Description” field unless the field name would be completely obvious to someone not familiar to the application as to what is the purpose of the field. 36 | 37 | ##### Exceptions 38 | 39 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. 40 | 41 | ##### Demonstrative Example 42 | 43 | The following are examples of custom field naming that should not be used 44 | 45 | | Custom Field Name | Reason | 46 | |-------------------|:--------| 47 | ```C``` | Ambiguous names will cause confusion. Description was not completed. 48 | ```Zip_Code``` | Field names should not have underscores. 49 | 50 | The following are examples of the naming convention that will be used 51 | 52 | | Custom Field Name | Reason 53 | |-------------------|:--------| 54 | ```CountryCode``` | A succinct description of the object using whole words. Description is not required since the name is a commonly understood term. 55 | ```ZipCode``` | Removing all underscores will help keep a standard naming convention as many times there are words that some may separate into two words and other may not. Description is not required since the name is a commonly understood term. 56 | ```CompletionDate``` | Date that the order process was completed. Should only be set once payment is received and order was fulfilled. Even though the name seems to make sense, there are business rules that need to be explained, and as such, a longer description was needed. 57 | 58 | ____ 59 | 60 | ### 3. Validation Rules 61 | 62 | #### Rules for Naming 63 | 64 | Validation rule names should be unique, beginning with an uppercase letter. Whole words should be used and use of acronyms and abbreviations should be limited. e.g. 65 | 66 | <FIELD> <RULE> <OPTIONAL DEPENDENCY> 67 | 68 | ```Postal Code Required (Suburb)``` 69 | 70 | The above example shows that Postal Code is required dependent on values in the Suburb field. The exact rule definition is in the detail but keeping this format helps keeps the naming as intuitive as possible without being too restrictive. 71 | 72 | #### Exceptions 73 | 74 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read. 75 | 76 | #### Demonstrative Example 77 | 78 | The following are examples of validation rule naming that should **not** be used: 79 | 80 | | Validation Rule Name | Reason | 81 | |----------------------|:-------| 82 | ```Validate Address``` | Superfluous use of the word validate and does not allow future additional validation rules to easily distinguish what the rule is checking 83 | 84 | The following are examples of the naming convention that will be used: 85 | 86 | | Validation Rule Name | Reason | 87 | |----------------------|:-------| 88 | ```Street Address < 60 chars``` | Field and rule clearly identified 89 | ```Zipcode not blank``` | ibid 90 | ```Occupation required``` | ibid 91 | ``` Zipcode required (Suburb)``` | FIELD, RULE, and DEPENDENCY clearly identified 92 | 93 | ____ 94 | 95 | ### 4. Workflow Rules 96 | 97 | #### Rules for Naming 98 | 99 | Workflow rule names will follow the following convention: 100 | 101 | |Attribute | Naming Convention | 102 | |----------|:----------------| 103 | |Workflow Rule Name | Note that this is not the action or actions being performed but the original event that fired the workflow rule. This allows the workflow actions to change over time. Including the salesforce object in the rule name is unnecessary as there is a standard field in the list view that can show this and filter on it. Whole words should be used and use of acronyms and abbreviations should be limited.| 104 | |Description | A full description of the rule and what actions it performs| 105 | 106 | #### Exceptions 107 | 108 | As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read 109 | 110 | #### Demonstrative Example 111 | 112 | The following are examples of workflow rule naming that should not be used: 113 | 114 | |Attribute | Example | Reason| 115 | |----------|:---------|--------| 116 | |Workflow Rule Name | Contact – Send Email and Update Inactive Flag | Name is too long and describes the actions performed as part of the rule that may change over time making the name potentially confusing in the future.| |Description | Sends an email | Not enough detail to be immediately clear what the workflow rule actions. Who is the email to? What about the field update?| 117 | 118 | The following are examples of the naming convention that will be used: 119 | 120 | | Attribute | Example | Reason | 121 | |-----------|:---------|:-------| 122 | |Workflow Rule Name | Date of Death Changed | Describes the event that will fire the rule in a succinct way | 123 | |Description | Sends an email to the Deceased Customer public group and updates the inactive flag of the contact for batch processing | Provides a clear and brief description of the intention of the actions performed. The description can be more easily updated and migrated as changes are made over time| 124 | 125 | ____ 126 | 127 | ### 5. Field Updates 128 | 129 | #### Rules for Naming 130 | 131 | Field update names will follow the following convention: 132 | 133 | |Attribute | Naming Convention | 134 | |-----------|:---------| 135 | |Field Update Name | Set <NAME OF FIELD> - <VALUE> Whole words should be used and use of acronyms and abbreviations should be limited. By using this convention the field update can be reused across workflow rules and approval processes and it is clear to the reviewer what action, field and value will be used. 136 | |Description | A full description of the field update including if other processes are dependent on the value 137 | 138 | #### Exceptions 139 | 140 | As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read 141 | 142 | #### Demonstrative Example 143 | 144 | The following are examples of field update naming that should not be used : 145 | 146 | |Attribute | Example | Reason | 147 | |----------|:--------|--------| 148 | |Field Update Name | Customer Date of Death | This describes the rule that fires the field update but does not tell me which field is updated and to what value | 149 | |Description | Updates the customer inactive flag | Doesn’t tell the reviewer at first glance what value is used and if this flag is used in other processes| 150 | 151 | The following are examples of the naming convention that will be used : 152 | 153 | |Attribute | Example | Reason | 154 | |----------|:--------|--------| 155 | |Field Update Name | Set Customer Inactive Flag – False | Describes the field being updated and what value will be used when updating the field 156 | | Description | Updates the inactive flag on the customer record which will be used by batch apex for processing | Briefly describes interdependencies that may rely on this action being performed | 157 | 158 | 159 | ### 6. Email Alerts 160 | 161 | #### Rules for Naming 162 | 163 | Email alert names will follow the following convention: 164 | 165 | |Attribute | Naming Convention 166 | |----------|:----------------- 167 | |Email Alert Description | Email <Description of Recipient> - <Email Template Used> Whole words should be used and use of acronyms and abbreviations should be limited. By using this convention the email alert can be reused across workflow rules and approval processes and it is clear to the reviewer who the email will be sent to.| 168 | 169 | #### Exceptions 170 | 171 | As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read 172 | 173 | #### Demonstrative Example 174 | 175 | The following are examples of email alert naming that should not be used: 176 | 177 | |Attribute | Example | Reason 178 | |----------|:--------|------- 179 | |Email Alert Description | Inform team of change | Mixed case not used and it is unclear where the email will be sent 180 | 181 | The following are examples of the naming convention that will be used : 182 | 183 | |Attribute | Example | Reason 184 | |----------|:--------|------- 185 | Email Alert Description |Email Deceased Customer Team – New Deceased Customer | Describes who is emailed and which template is used 186 | 187 | ____ 188 | 189 | ### 7. Approval Processes 190 | 191 | #### Rules for Naming 192 | 193 | Approval process names will follow the following convention: 194 | 195 | |Attribute | Naming Convention 196 | |----------|:---------------- 197 | |Process Name | <Event that fired the approval> Note that this is not the action or actions being performed but the original event that will trigger the entry criteria. This allows the approval actions to change over time.
Including the salesforce object in the rule name is unnecessary as there is a standard field in the list view that can show this and filter on it. Whole words should be used and use of acronyms and abbreviations should be limited. 198 | |Description | A full description of the rule and what actions it performs 199 | 200 | #### Exceptions 201 | 202 | As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read 203 | 204 | #### Demonstrative Example 205 | 206 | The following are examples of approval process naming that should not be used : 207 | 208 | Approval Process Name | Reason 209 | ----------------------|:---------- 210 | |Comp | Abbreviations can cause confusion. Whole words should be used. 211 | |Send Email On Reject | Actions performed in the approval process should not be used in the parent process name 212 | 213 | The following are examples of the naming convention that will be used : 214 | 215 | Approval Process Name | Reason 216 | ----------------------|:---------- 217 | | Conflict Completed | Brief description of the entry criteria indicate a clear intention of when the process will be used 218 | 219 | ____ 220 | 221 | ### 8. Approval Process Steps 222 | 223 | #### Rules for Naming 224 | 225 | Approval process step names will follow the following convention: 226 | 227 | Attribute | Naming Convention 228 | ----------|:---------- 229 | Step Name | <Decision Outcome> - <User Friendly Description> 230 | Description | A full description of the step including what it does and the intended actions that will be performed (e.g. who will it be assigned to) 231 | 232 | #### Exceptions 233 | 234 | As there is an upper limit for the number of characters in the name field the use of abbreviations will be permitted if by including them the name becomes easier to read 235 | 236 | #### Demonstrative Example 237 | 238 | The following are examples of approval process step naming that should not be used : 239 | 240 | Approval Process Step Name | Reason 241 | ---------------------------|:------- 242 | Step 1 | This is not descriptive enough as it will be displayed in the approval related list to users. Does not provide what was evaluated. 243 | Complex Approval – Step 1 | More descriptive but does not provide users with a clear enough picture of what was evaluated 244 | 245 | The following are examples of the naming convention that will be used: 246 | 247 | Approval Process Step Name | Reason 248 | ---------------------------|:------- 249 | Auto Approved – Value within personal limit | The approval step becomes self documenting showing the administrator and user the result of the approval step 250 | Auto Rejected – Value exceeds company policy | The approval step becomes self documenting showing the administrator and user the result of the approval step 251 | Approval – Sent to Manager | The approval step becomes self documenting showing the administrator and user the result of the approval step 252 | Approval – Sent to Legal | The approval step becomes self documenting showing the administrator and user the result of the approval step 253 | 254 | ____ 255 | 256 | ### 9. Visualforce Pages 257 | 258 | #### Rules for Naming 259 | 260 | Visualforce page names and labels should be unique, beginning with an uppercase letter. It should not contain underscores or spaces. The words should be concatenated with Initial uppercase and subsequent internal words capitalized. Whole words should be used and use of acronyms and abbreviations should be limited. 261 | 262 | #### Exceptions 263 | 264 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL. 265 | 266 | #### Demonstrative Example 267 | 268 | The following are examples of Visualforce Page naming that should not be used: 269 | 270 | Visualforce Page Name | Reason 271 | ----------------------|:------- 272 | Override_Customer_View | Underscores should not be used 273 | Custoverrideview | Name and Label becomes hard to read without capitalization 274 | 275 | The following are examples of the naming convention that will be used : 276 | 277 | Visualforce Page Name | Reason 278 | ----------------------|:------- 279 | CustomerView | Clearly defined and succinct name 280 | MailFaxRequest | Clearly defined and succinct name 281 | 282 | ____ 283 | 284 | ### 10. Apex Classes 285 | 286 | #### Rules for Naming 287 | 288 | Class names should be unique, beginning with an uppercase letter. It should not contain underscores or spaces. The words should be concatenated with Initial uppercase and subsequent internal words capitalized. Whole words should be used and use of acronyms and abbreviations should be limited. Apex classes that are custom controller classes should be suffixed with Controller Apex classes that are controller extensions should be suffixed with XController, where X is the name of the Visualforce page that is extended. That allows for easy searching of controllers related to Visualforce pages. 289 | 290 | #### Exceptions 291 | 292 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. 293 | 294 | #### Demonstrative Example 295 | 296 | The following are examples of Apex class naming that should not be used : 297 | 298 | Class Name | Reason 299 | -----------|:------ 300 | FHACustomer | Using acronyms should be avoided as they are not mnemonic 301 | GrtBgClass | Whole words should be used in place of shortened versions GreatBigClass 302 | addresshandler | Class does not begin with an uppercase letter 303 | Address_Handler | Underscores should be avoided 304 | 305 | The following are examples of the naming convention that will be used: 306 | 307 | Class Name | Reason 308 | -----------|:------ 309 | Customer | Full word used to describe the class and starts with uppercase 310 | AddressHandler | Multiple words concatenated with subsequent words capitalized 311 | MailFaxController | Controller Extension for the Mail_Fax__c object 312 | CustomerController | Customer controller for the customer object 313 | 314 | ____ 315 | 316 | ### 11. Apex Batch, Schedulable, and Queueable Classes 317 | 318 | #### Rules for Naming 319 | 320 | Class names should be unique, beginning with an uppercase letter. It should not contain underscores or spaces. The words should be concatenated with Initial uppercase and subsequent internal words capitalized. Whole words should be used and use of acronyms and abbreviations should be limited. Apex classes that are batch classes should be suffixed with _Batch Apex classes that are Scheduleable classes should be suffixed with _Schedule Apex classes that are Queuable classes should be suffixed with _Queueable 321 | 322 | #### Exceptions 323 | 324 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. 325 | 326 | #### Demonstrative Example 327 | 328 | The following are examples of Apex batch, scheduleable, and queueable class naming that should not be used 329 | 330 | Class Name | Reason 331 | -----------|:------ 332 | GrtBgClass | Whole words should be used in place of shortened versions GreatBigClass and the appropriate suffix should be used. 333 | contactbatch | Class does not begin with an uppercase letter and an underscore should always precede the suffix. 334 | Address_Update_Batch | Underscores should be avoided other than for the suffix 335 | 336 | The following are examples of the naming convention that will be used 337 | 338 | Class Name | Reason 339 | -----------|:------ 340 | RoleExpiry_Batch | Multiple words concatenated with subsequent words capitalized. Suffixed with _Batch denoting that this is a batch apex class. RoleExpiry_Schedule | Multiple words concatenated with subsequent words capitalized. Suffixed with _Schedule denoting that this is a scheduleable apex class. 341 | RoleExpiry_Queueable | Multiple words concatenated with subsequent words capitalized. Suffixed with _Queueable denoting that this is a queueable apex class. 342 | 343 | ____ 344 | 345 | ### 12. Apex Triggers 346 | 347 | #### Rules for Naming 348 | Triggers should always be named using the format [object Name][Operation]Trigger OR [Object Name]Trigger for triggers that include all operations for that object. For example: AccountInsertTrigger, AccountUpdateTrigger, OrderInsertTrigger. There should only be one trigger per operation per object. It is strongly recommended to include only a single trigger with all operations inside that trigger per object. 349 | 350 | #### Exceptions 351 | 352 | None 353 | 354 | #### Demonstrative Example 355 | 356 | The following are examples of trigger naming naming that should not be used 357 | 358 | Validation Rule Name | Reason 359 | -----------|:------ 360 | UpdateAccountAddresses | The object name should always be before the operation in the name. 361 | AccountUpdateContacts | Is specific to a business function and would allow for other update triggers to be created for the same object. 362 | 363 | The following are examples of the naming convention that will be used 364 | 365 | Trigger Name | Reason 366 | -----------|:------ 367 | AccountUpdateTrigger | Generic trigger that performs only update operations. AccountInsertTrigger | Generic trigger that performs only insert operations AccountTrigger | Generic trigger that performs insert,update, and delete operations. This would be the only trigger for the account object. 368 | 369 | ____ 370 | 371 | ### 13. Apex Test Classes 372 | 373 | #### Rules for Naming 374 | 375 | Test class names should be unique, beginning with an uppercase letter. It should not contain spaces. The words should be concatenated with Initial uppercase and subsequent internal words capitalized. Whole words should be used and use of acronyms and abbreviations should be limited. The test class will use the convention Test. This keeps the alphabetical order of the classes intact. 376 | 377 | #### Exceptions 378 | 379 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. 380 | 381 | #### Demonstrative Example 382 | 383 | The following are examples of Apex class naming that should not be used Class Name Reason TESTCustomerManagement Test classes should not have "TEST" in the prefix, but rather have “Test” in the suffix. The following are examples of the naming convention that will be used 384 | 385 | Class Name | Reason 386 | -----------|:------ 387 | CustomerManagementTest | Test class for the CustomerManagement Apex class. Will be listed alphabetically under the class being tested. 388 | 389 | ____ 390 | 391 | ### 14. Apex Methods 392 | 393 | #### Rules for Naming 394 | 395 | Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. Whole words should be used and use of acronyms and abbreviations should be limited. 396 | 397 | #### Exceptions 398 | 399 | Widely used and commonly understood acronyms and abbreviations can be used instead of the long form. For example HTTP or URL or ACMA. 400 | 401 | #### Demonstrative Example 402 | The following are examples of Apex method naming that should not be used 403 | 404 | Method Name | Reason 405 | -----------|:------ 406 | handleCalculation() | What is being handled?! 407 | performServices() | Perform what services? 408 | dealWithInput() | How exactly is the input being dealt with? 409 | NTInQ1() | Cannot determine from the name what the function does 410 | 411 | The following are examples of the naming convention that will be used 412 | 413 | Method Name | Reason 414 | -----------|:------ 415 | ammortizationCalculation() | Describes what calculation is performed repaginateDocument() | Describes the service being performed getEmployeeDetail() | Describes what is being done 416 | numberOfTransactionsInQ1() | Longer names are better if they are needed for clarity 417 | 418 | ____ 419 | 420 | ### 15. Apex Variables 421 | 422 | #### Rules for Naming 423 | Variables should be in mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should be short yet meaningful. The choice of a variable name should be mnemonic— that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k,m, and n for integers; c, d, and e for characters. 424 | 425 | #### Exceptions 426 | None 427 | 428 | #### Demonstrative Example 429 | 430 | The following are examples of Apex variable naming that should not be used 431 | 432 | Variable Name | Reason 433 | -----------|:------ 434 | x = x – y | Variable names are ambiguous 435 | 436 | The following are examples of the naming convention that will be used 437 | 438 | Variable Name | Reason 439 | -----------|:------ 440 | currentBalance = lastBalance - lastPayment | Unambiguous names that have a clear meaning 441 | 442 | 443 | ____ 444 | 445 | ### 16. Apex Constants 446 | 447 | #### Rules for Naming 448 | The names of variables declared class constants should be all uppercase with words separated by underscores ("_"). Common constants used across the application should be declared in the GlobalConstants class (see section 7.6) Constant scope should be kept to the minimal required. Private class attributes are preferred to publicly defined constants. 449 | 450 | #### Exceptions 451 | None 452 | 453 | #### Demonstrative Example 454 | 455 | The following are examples of Apex constant naming that should not be used 456 | 457 | Class Name | Reason 458 | -----------|:------ 459 | maxCharacters | Indistinguishable from a variable name 460 | 461 | The following are examples of the naming convention that will be used 462 | 463 | Class Name | Reason 464 | -----------|:------ 465 | MAX_CHARACTERS | Uppercase letters help the reviewer determine that it is a constant 466 | 467 | ____ 468 | 469 | ### 17. Apex Type Names 470 | 471 | #### Rules for Naming 472 | 473 | Type names should use an uppercase first letter. This follows the Java naming conventions. This is to ensure that the type names are not similar to the variable names that immediately proceed them. 474 | 475 | #### Exceptions 476 | None 477 | 478 | #### Demonstrative Example 479 | 480 | The following are examples of Apex type naming that should not be used 481 | 482 | Type Name | Reason 483 | -----------|:------ 484 | map Contacts | "map", “id”, and “string” do not start with an uppercase letter. 485 | String Contact | “string” does not start with an uppercase letter. 486 | 487 | The following are examples of the naming convention that will be used 488 | 489 | Type Name | Reason 490 | -----------|:------ 491 | Map Contacts | Starts with an uppercase letter String Contact Starts with an uppercase letter 492 | 493 | ____ 494 | 495 | ### 18. Public Groups 496 | 497 | Public Groups and Queues are very similar in how they are used within Salesforce and as such should follow the same naming conventions. 498 | 499 | _What is a Public Group?_ 500 | Public groups in Salesforce are a security mechanism in Salesforce that allows you to “group” users together that need common access to something in Salesforce. 501 | 502 | Instead of manually assigned users to the “thing” you want them to have access, you just add or remove the user from the group. When you want to remove access from all users in the group to the “thing”, you just remove the group from having access. 503 | 504 | _Examples of Types of Access_ 505 | - Granting access to a listview on an object to a group of users 506 | - Using criteria based sharing to grant access to a set of users who are in a group 507 | - Sharing access to a record to a set of users who are in a group 508 | 509 | #### Rules for Naming 510 | 511 | Business users will view public group labels while viewing the users and groups a record is shared with. Group labels will need to make sense to business users pertaining to their business process. Administrators will need to be able to easily sort public groups when adding/removing users from groups. Group name will need to make sense to administrators pertaining to specific applications. 512 | 513 | - Always prefix the group name with the application. ie: “Mosaic_Complaints”. This will allow easy sorting of the groups by the administrator by application. 514 | - Give the label of the group the same postfix name as what was given to the name. ie: “Complaints”. This allows for business users to easily associate the group with a business process, but also makes it easy for a system administrator to match a group name to the label in the application. 515 | 516 | #### Exceptions 517 | None 518 | 519 | #### Demonstrative Example 520 | 521 | ![Create a new Group](/img/group_naming_example.png) 522 | 523 | ![Public Groups](/img/group_naming_example_1.png) 524 | ____ 525 | 526 | ### 19. Queues 527 | 528 | Public Groups and Queues are very similar in how they are used within Salesforce and as such should follow the same naming conventions. 529 | 530 | _What is a Queue?_ 531 | Queues are similar to public groups in that they allow you to assign one or more users as members of the queue. Where queues differ is that when you setup a queue, you also associate one or more Salesforce objects with the queue. Once you associate a Salesforce object with a queue, you can then set the queue as the owner of a record of an associated object. 532 | 533 | 534 | _Examples of Types of Access_ 535 | -Queue granted as owner of a record grants all users read access to the record 536 | -Using criteria based sharing to grant access to a set of users who are in a queue 537 | 538 | #### Rules for Naming 539 | 540 | Business users will view queue labels while working with list views and viewing record owners. Queue labels will need to make sense to business users pertaining to their business process. Administrators will need to be able to easily sort queues when adding/removing users from the queues. Queue names will need to make sense to administrators pertaining to specific applications. 541 | 542 | -Always prefix the queue with the application. ie: “Mosaic_Complaints”. This will allow easy sorting of the queues by the administrator by application. 543 | -Give the label of the queue the same postfix name as what was given to the name. ie: “Complaints”. This allows for business users to easily associate the queue with a business process, but also makes it easy for a system administrator to match a queue name to the label in the application. 544 | 545 | #### Exceptions 546 | None 547 | 548 | #### Demonstrative Example 549 | 550 | ![Create a new Group](/img/group_naming_example.png) 551 | 552 | ![Public Groups](/img/group_naming_example_1.png) 553 | -------------------------------------------------------------------------------- /_pages/Security-Model-(Permission-Sets,-Profiles).md: -------------------------------------------------------------------------------- 1 | ### Objectives 2 | CFPB requires a profile and permission set approach that is optimized based on the following parameters: 3 | 4 | * Profile Maintenance Effort 5 | * Permission Set Maintenance Effort 6 | * Profile Consistency 7 | * Permission Set Consistency 8 | * Ease of Provisioning Regular Users 9 | * Ease of Provisioning Crossover Users 10 | * Page Layout Flexibility 11 | * Permissions Model 12 | 13 | The selected approach is as follows (for example in SES): 14 | ![Profile Model](/img/profile_model.png) 15 | 16 | This is an example of roles with two (2) example permissions sets (SES Examiner, SES Super User); the actual diagram may vary from project to project. 17 | 18 | 19 | #### Classification 20 | Permission/Profile Type | Description | Naming Guidelines 21 | ----|----|----------------- 22 | Common Profile | This serves as a single profile assigned to all CRM license users. As the org grows, there may be a need for additional profiles: - Special purpose ones where the common profile does not meet requirements - Profiles to match additional license types (e.g., Platform, Communities, etc.) This does not account for system administrator or API profiles.|CRM User, Platform User, Customer Community User, etc. 23 | Baseline Permission Set | This permission set will be assigned by default to all Service Cloud users. As the org grows, there may be a need for additional baseline permission sets to align with license types or other user groups. | Global - Baseline - Service Cloud User 24 | Base Application User Permission Set | Each application will have a permission set that contains the minimum permissions needed for use of the application. This is essentially the “regular user” permission set. | App - SES, App - Mosaic, etc. 25 | Feature Permission Set | These permission sets enable additional functionality from the base application permission set. There should be no permissions repeated here from the base application permission set. | App - Mosaic - Approve KB Article 26 | Function Permission Set | These permission sets are for users with enhanced permissions within the application (e.g., super users and supervisors). There should be no permissions repeated here from the base application permission set. | App - Mosaic - Power User 27 | Overlay Permission Set | These permissions sets are for features or functions that are not application-specific. These would be of two types: - Pervasive permissions, assigned to a large number of users (though not all users, otherwise the permissions would go in the baseline permission set) - Special purpose permissions, such as data stewards or super users of org functions that are not application-specific | Global - View All Data, Global - API Enabled, Global - Author Apex, etc. 28 | 29 | 30 | ### Rules and Guidance 31 | 1. Each new application will have a single permission set that is assigned to all users of that application, regardless of function. In special circumstances, there can be two base permission sets if not enough commonality can be established in a single one. 32 | 1. Feature and function permission sets for applications (e.g., super users and supervisors) will contain only the delta against the base permission set for that application. Under no circumstances will permissions be repeated from the base permission set within feature permission sets. 33 | 1. The creation of overlay permission sets should be coordinated with the COE. These are cross-functional permission sets used for parts of the org that are not application-specific (e.g., management of regulations, product lines, etc.). 34 | 1. The creation of new profiles is possible only under exceptional circumstances. Any new profiles must have proper justification and require approval from COE before development begins. 35 | 1. The COE may revisit the decision for a single profile by license type and opt for division-specific profiles if there is a business need in the future. The objective is to minimize places where permission updates need to be made, thereby reducing maintenance costs. 36 | 1. Additions to the baseline permission set(s) will be governed and managed by the COE. Development teams can petition for new permissions in the baseline, but this would be a rare circumstance since development teams should focus on application-specific functionality. 37 | 1. System administrators will use a new profile that is cloned from the out-of-the-box System Administrator profile, per best practices. 38 | 1. API profiles will be created as needed, though every effort should be made to keep all integration users on a single API profile. The specifics of the profile must be defined in conjunction with the security team. 39 | 40 | ____ 41 | 42 | ### TODO/Outstanding Tasks 43 | - Identify the system and object permissions that need to go in the common profile (these should be minimal, if any) and a name for it, according to the agreed upon standards 44 | - Identify the system and object permissions that need to go in the baseline permission set and a name for it, according to the agreed upon standards 45 | Define an SOP for review of permission set and profile creation 46 | - The CoE needs to sign off on this policy and include it in the technical guidelines 47 | - The SES Development Team needs to realign its profile and permission sets in accordance with this policy 48 | Come up with naming convention for permission sets 49 | - Define a base API profile 50 | - Clone the System Administrator to a custom profile 51 | - Define a policy for “view all” and “modify all” on permission sets and profile 52 | 53 | -------------------------------------------------------------------------------- /_pages/SoftWare-Advisory-Group.md: -------------------------------------------------------------------------------- 1 | SoftWare Advisory Group (SWAG) 2 | ======================= 3 | The SWAG is a peer-group of software and technology experts who will define and guide strategies and decisions for software products and key delivery platforms; e.g., ConsumerFinance.gov. All technologies and software product implementations will be reviewed by this group and approved by the Software Development Lead in order to ensure alignment with D&D and T&I architectures and strategy. This group will equally serve as a panel of experts to help solve challenging technical issues and support teams’ goals and objectives throughout the life of the product. 4 | 5 | ![swag](/img/SWAGActivities.png) -------------------------------------------------------------------------------- /_pages/Source-code-and-configuration-management.md: -------------------------------------------------------------------------------- 1 | ###Source Code and Configuration Management 2 | 3 | [Source code Comment standards for this project](_pages/Comment-standards.md) 4 | 5 | All methods should begin with a brief comment describing the functional characteristics of the method (what it does). This description should not describe the implementation details (how it does it) because these often change over time, resulting in unnecessary comment maintenance work, or worse yet erroneous comments. The code itself and any necessary inline or local comments will follow the standards as defined by the [SalesforceFoundation](https://github.com/SalesforceFoundation/ApexDoc#documenting-class-files): 6 | 7 | #####Class Comments 8 | 9 | Located in the lines above the class declaration. The special tokens are all optional. 10 | 11 | |token | description| 12 | |-------------|:--------| 13 | |@author | the author of the class| 14 | |@date | the date the class was first implemented| 15 | |@group | a group to display this class under, in the menu hierarchy| 16 | |@group-content | a relative path to a static html file that provides content about the group| 17 | |@description | one or more lines that provide an overview of the class| 18 | 19 | Example 20 | 21 | ``` 22 | /** 23 | * @author Salesforce.com Foundation 24 | * @date 2014 25 | * 26 | * @group Accounts 27 | * @group-content ../../ApexDocContent/Accounts.htm 28 | * 29 | * @description Trigger Handler on Accounts that handles ensuring the correct system flags are set on 30 | * our special accounts (Household, One-to-One), and also detects changes on Household Account that requires 31 | * name updating. 32 | */ 33 | public with sharing class ACCT_Accounts_TDTM extends TDTM_Runnable { 34 | ``` 35 | 36 | #####Property Comments 37 | 38 | Located in the lines above a property. The special tokens are all optional. 39 | 40 | |token | description| 41 | |-------------|:--------| 42 | |@description | one or more lines that describe the property| 43 | 44 | Example 45 | 46 | ``` 47 | /************************************************************************** ***************************** 48 | * @description specifies whether state and country picklists are enabled in this org. 49 | * returns true if enabled. 50 | */ 51 | public static Boolean isStateCountryPicklistsEnabled { 52 | get { 53 | ``` 54 | 55 | #####Method Comments 56 | 57 | In order for ApexDoc to identify class methods, the method line must contain an explicit scope (global, public, private, testMethod, webService). The comment block is located in the lines above a method. The special tokens are all optional. 58 | 59 | |token | description| 60 | |-------------|:--------| 61 | |@description | one or more lines that provide an overview of the method| 62 | |@param _param name_ | a description of what the parameter does| 63 | |@return | a description of the return value from the method| 64 | |@example | Example code usage. This will be wrapped in tags to preserve whitespace| 65 | 66 | Example 67 | 68 | ``` 69 | /************************************************************************** ***************************** 70 | * @description Returns field describe data 71 | * @param objectName the name of the object to look up 72 | * @param fieldName the name of the field to look up 73 | * @return the describe field result for the given field 74 | * @example 75 | * Account a = new Account(); 76 | */ 77 | public static Schema.DescribeFieldResult getFieldDescribe(String objectName, String fieldName) { 78 | ``` 79 | 80 | #### Release Management 81 | 82 | ####Versioning & Deploying Code and Configuration Between Environments 83 | 84 | Versioning of code and configuration has always been a rather large pain point for project teams and developers. Salesforce itself does not support versioning of the code and configuration within an org. Project teams cannot use standard development practices to check-in both your code and configuration. 85 | 86 | The first problem is that developers can write apex code on their local machines or directly in the Salesforce UI. Even if they are developing code in an external tool as soon as they save their changes are being “deployed” to the Salesforce org. The developer could then “commit” the code to source control, but what if someone made a change to the code directly in the UI without the developer’s knowledge? That code would never get checked into source control. 87 | 88 | The second problem is the management of the configuration. You cannot easily edit configuration files and then check them into source control. Instead you perform the configurations directly in the UI. It would then take a developer to download all the configuration files using a development tool such as eclipse to check them into source control. This is definitely not a feasible practice. 89 | 90 | If you want to create a more repeatable process to retrieve/deploy Salesforce code and configuration you would use the Salesforce metadata API along with some ANT scripts to automate the deployments. This only gets you halfway there. Even after you create the automated scripts, you still would need to manually create the ```package.xml``` file that lists all of the files that you wish to retrieve or deploy. This is a very tedious and time consuming practice. 91 | 92 | ####Salesforce Change Set to the Rescue! 93 | 94 | Salesforce offers a feature in the UI that allows you to “package” the components of an application by adding each of the components to a Change Set. This Change Set then acts as an inventory for all of the components in your application for a particular release. You can then use ANT and the Salesforce metadata API to create automated scripts that retrieve the components of a Change Set and then commit those components into source control. You can then use the same scripts to take the Change Set in source control and deploy the code and configuration to a target Salesforce environment. 95 | 96 | This is the basis of the deployment process outlined in this document. Below you will find a sample of what a Change Set in Salesforce looks like. 97 | 98 | ![Package](/img/Outbound_Change_Set.png) 99 | 100 | ####Deploying between Salesforce Environments 101 | 102 | An automation engine called “Jenkins” helps you automate deployments by executing step-by-step tasks. We have created a series of ANT scripts that use the Salesforce metadata API to retrieve Salesforce packages and commit them to Git/GitHub source control. Then other ANT scripts take what has been committed to Git or GitHub source control and deploys them to a specified target Salesforce environment. Jenkins is used to automate these scripts so that you do not need to type into a command line every time you wish to perform a deployment. 103 | 104 | A typical basic release from one environment to another environment would proceed as follows: 105 | 106 | 1. A developer or configurator creates a new Change Set in a Salesforce org per Release. 107 | 1. A developer or configurator adds code and components to that Change Set for a particular release. 108 | 1. An automated Jenkins job runs on an hourly basis committing any new or updated components to GitHub source control. 109 | 1. A manually initiated Jenkins job is executed by the release manager to deploy the code and configuration from the GitHub source control repository to the target Salesforce environment. 110 | 111 | #### PackageSource Control 112 | As mentioned above, Salesforce out of the box does not support versioning of the code and configuration. This is why we are using GitHub with individual repositories to store and version the code and configuration for each Salesforce Change Set that is created. 113 | 114 | The following are the different repositories that will be used for releases. 115 | 116 | 1. **Project Master Repository** - Every project team will have their own dedicated repository in GitHub. When a new project is established a new GitHub repository for that team will be created. The naming for project master repository is {Project Name} - Deploy.

This repository is managed by the release management team and is used to deploy Change Sets to the various platform environments such as Integration, UAT, Staging, and Production.

Project teams will fork this repository to manage their day-to-day versioning of code currently in flight. Once the coding and configuration for a Change Set is complete for a release, a pull request will be made by that project team requesting the release manager to merge the forked repository specfic release branch with the corresponding release branch on master. 117 | 1. **Project Master Forked Repository** - This is a repository that has been forked from the “Project Master Repository” or {Project Name} - Deploy repository. This repository will be mapped directly to the “Project Dev” environment. A Jenkins job will be configured that will automatically take any code or components checked into the Change Set in the “Project Dev” environment and will automatically commit those code and components to the forked repository. 118 | 1. **Individual Developer Forked Repositories** - In the case that a project team is using a distributed development model with one or more individual developer environments in addition to their “Project Dev” environment, one or more developer repositories will be forked from the “Project Master Forked Repository”. These are in essence double forked repositories. Each of these double forked repositories will be mapped directly to an individual developer sandbox similar to how the “Project Master Forked Repository” is mapped to the “Project Dev” environment.

For each individual developer environment and repository, a Jenkins job will be created that will take any components that are in a Change Set in the individual developer sandbox and will commit them to their dedicated double forked repository on a routine basis automatically. Once the developer is ready to move their code and configuration to the “Project Dev” environment, the developer will create a pull request requesting that their repository be merged with the “Project Master Forked Repository”. The project lead developer would then accept the pull request and would execute a Jenkins job that would automatically deploy the package within the developer’s double forked repository to the “Project Dev” sandbox. 119 | 120 | ####Auditing and Tracking of a Release 121 | There are two mechanisms that are used by the release management team to ensure that appropriate approvals are given for deployments to various environments and to track all communication throughout the process. 122 | 123 | 1. **Pull Requests** - Pull requests in GitHub are a mechanism to request that code from a forked repository release branch are merged into a corresponding parent repository release branch. Within the pull request the requester and release manager can collaborate with each other about the release. Any metadata item that cannot be deployed via Change Set has to be detailed as a pre or post deployment manual step in the deployment document and this has to be attached with the pull request.The pull request stays open till the code reviews are complete for a release. Once the release manager accepts the pull request, the code is ready to be deployed to upstream environments. 124 | 125 | 1. **RemedyForce Tickets** - RemedyForce tickets are used for audit tracking to ensure that the requester has the authority to request deployment from one environment to another. When a pull request is opened a RemedyForce ticket must also be opened requesting the deployment from one environment to another. Once the deployment has been completed, the RemedyForce ticket is then closed. Multiple RemedyForce tickets will be open throughout the entire release process for each time a deployment to a new environment is requested. Each time a ticket is opened that ticket must be notated in the pull request. 126 | 127 | ####Wrapping Things Up and Walk-through the Entire Process 128 | Now that you understand the individual components involved in the release management process, you can walk through a complete release scenario by team member role from start to finish below. 129 | 130 | The simulation below walks through the following: 131 | 1. Initiation of a new project. 132 | 1. What happens on day one of development for the project. 133 | 1. What happens every day after day one during development for the project. 134 | 1. Requesting of a project package to be deployed to the Integration sandbox. 135 | 1. Requesting of a project package to be deployed to the UAT sandbox. 136 | 1. Requesting of a project package to be deployed to production. 137 | 1. What happens after deployment to production. 138 | 139 | ###Release Management Scenario 140 | 141 | 142 | ####New Project Initiation 143 | A new Salesforce project has just been established. The project has team members and is ready to start development. The following are the steps that must be performed before the project team can begin development. 144 | 145 | 146 | **ROLE: Project Manager / Lead Developer** 147 | 148 | 1. Submits RemedyForce ticket for the setup of a new Salesforce project for {Project Name}. 149 | 1. Optionally the project manager / lead developer specify additional individual sandboxes needed if they are opting for a distributed development model. 150 | 1. Once submitted the RemedyForce ticket must go through the appropriate approvals. Once approved the ticket is then routed to the release manager. 151 | 152 | **Release Manager** 153 | 154 | 1. Receives notification of the RemedyForce ticket to setup a new Salesforce project. 155 | 1. Creates Project Team Dev and Project Team Build/UAT sandboxes and grants the project lead access to the sandboxes. 156 | 1. Creates additional individual developer sandboxes as requested in the ticket. 157 | 1. Creates a new repository in GitHub named {Project Name}-deploy. 158 | 1. Creates a new {Project Name} folder in Jenkins. 159 | 1. Clones the following Jenkins jobs and puts them in the {Project Name} folder. 160 | 1. **{Project Name}-Retrieve and Commit** - Retrieves all code and components in the Project Dev sandbox on a hourly basis and commits to the project forked Repository. 161 | 1. **{Project Name}-Deploy Package** - Deploys the package in the forked project team repository to the project team build/UAT environment. 162 | 1. **{Project Name}-Deploy to Integration** - Retrieves the package from the Project Dev environment and commits it to the Project Master Repository. It then deploys the package from the Project Master Repository to the Integration platform sandbox. 163 | 1. **{Project Name}-Deploy to UAT** - Deploys the package from the Project Master Repository to the platform UAT sandbox. 164 | 1. **{Project Name}-Deploy to Staging** - Deploys the package from the Project Master repository to the platform Staging sandbox. 165 | 1. **{Project Name} - Deploy to Production** - Retrieves all configuration and code in production and backs up to the Salesforce Master Repository. Then deploys the package from the Project Master Repository to production. Then performs another backup of all code and configuration in production to the Salesforce Master repository. 166 | 1. **{Project Name} - Deploy Specific Version** - Template job that can be used to perform ad-hoc deployments from a specific commit in GitHub to a Salesforce environment. For example, if you needed to roll back changes from a previous commit this job would be used. 167 | 1. Updates settings in the Jenkins jobs for the project specific settings such as git repositories, package name, usernames, and passwords. 168 | 169 | **Lead Developer** 170 | 171 | 1. Forks the Project Master Repository ( {Project Name}-deploy ) to {Team}/{Project Name}-deploy 172 | 1. Creates a new empty Change Set based on a Release in their Project Dev sandbox. 173 | 1. Creates a new empty Release branch in {Team}/{Project Name}-deploy. 174 | 1. Informs the release manager of the new change set name. 175 | 176 | **Release Manager** 177 | 178 | 1. Creates the release specific branch in ( {Project Name}-deploy ) Project Master Repository. 179 | 1. Creates the retrieve-commit and deploy Jenkins jobs for that specific release. 180 | 181 | **Developers (for each individual developer sandbox)** 182 | 183 | 1. Creates a fork for their individual specific sandbox. e.g.,( {developer name}/{Project Name}-deploy ) in their indivdual GitHub account. This is the double forked repository we mentioned earlier. 184 | 1. Create new empty change set in their respective individual developer sandbox. 185 | 186 | 187 | ####Day 1 Project Step 188 | Now that all of the initial project initiation steps have been completed, the project team can now begin development. 189 | 190 | **Developer 1** 191 | 192 | 1. Creates a new apex class in Eclipse IDE and saves to the Platform Dev sandbox. 193 | 1. Creates a new Visualforce page in the Salesforce UI. 194 | 1. Creates a new custom object in the Salesforce UI. 195 | 1. Adds the new apex class, Visualforce page, and custom object to the Change Set. 196 | 197 | **Configurator 1 (working on same org as developer)** 198 | 199 | 1. Creates a new page layout, record type, custom field, etc in the Salesforce UI. 200 | 1. Adds the new page layouts, record types, workflow rules, etc to the Change Set. 201 | 202 | **Jenkins/Ant {Project Name}-Retrieve and Commit job** 203 | 204 | 1. Syncs Change Set with git repository hourly and pushes to fork, {Team}/{Project Name}-deploy. All components not currently in the repository that are in the Change Set are added to the repository. Any existing components in the Change Set that are also in the repository are updated in the repository. 205 | 206 | **Note:** Only code and components that are in the Change Set are committed to the repository. 207 | 208 | ####Day 1+X Project Step 209 | This step represents every day after the first day of development. 210 | 211 | **Developer 1** 212 | 213 | 1. Refreshes the Eclipse IDE from the Project Dev. 214 | 1. Updates an existing apex class. 215 | 216 | **Developer 2** 217 | 218 | 1. Creates a new apex class in the Eclipse IDE. 219 | 1. Adds a new apex class to the package. 220 | 221 | **Configurator 1** 222 | 223 | 1. Creates a new object in the Salesforce UI. 224 | 1. Creates an approval process in the salesforce UI. 225 | 1. Adds the object and approval process to the package. 226 | 227 | **Configurator 2** 228 | 229 | 1. Updates an existing page layout in the Salesforce UI. 230 | 1. Updates an existing workflow rule in the Salesforce UI. 231 | 232 | **Jenkins/Ant {Project Name}-Retrieve and Commit job** 233 | 234 | 1. Syncs Change Set with git repository hourly and pushes to fork, {Team}/{Project Name}-deploy. All components not currently in the repository that are in the Change Set are added to the repository. Any existing components in the Change Set that also in the repository are updated in the repository. 235 | 236 | **Note:** Only code and components that are in the package are committed to the repository. 237 | 238 | ####Deploy to Team QA 239 | In this step the project team now has enough code and configuration completed that they are ready to start testing their application and demoing it to end users. In order to QA and demo to end using they need to deploy their application to their project team’s build / QA sandbox. 240 | 241 | **Lead Developer** 242 | 243 | 1. Verifies Change Set, and updates ```README.md``` in fork, {Team}/{Project Name}-deploy, and captures the manual pre-deploy and post deploy steps. 244 | 245 | 1. Performs pre-deploy manual steps in Team Build/QA. 246 | 247 | 1. Executes Jenkins job {Project Name} - Deploy to QA. 248 | 249 | **Jenkins / ANT** 250 | 1. Executes git repository sync that pushes to fork, {Team}/{Project Name}-deploy to make sure the repository is current. 251 | 1. Deploys from the repository to the Team QA org. 252 | 1. Performs post deploy manual steps in Team QA. 253 | 254 | **Note:** Notice that the lead developer entered any manual steps in the ```README.md``` in their repository. The ```README.md``` is used throughout the release management process to track any pre or post manual changes needed in addition to the automated deployment. This should be updated on a routine basis when new manual steps are needed. 255 | 256 | ####Deploy to Integration 257 | In this step the project team has completed the current version of their application and is ready to start the deployment process to production. The first step in that process is deploying their application to the platform integration sandbox. 258 | 259 | **Lead Developer** 260 | 261 | 1. Verifies that the Change Set is tested and ready to deploy to integration. 262 | Creates a pull request from fork ( {Team}/{Project Name}-deploy ) release branch to ( {Salesforce}/{Project Name}-deploy ) release branch. 263 | 1. Adds label/version in pull request. e.g., v2.5.09 … v2.5.10. 264 | 1. Creates a new ticket in RemedyForce for the deployment. Includes link to pull request in the ticket. 265 | 1. Creates a comment in the pull request, requesting to deploy to integration and references the ticket in the pull request. 266 | 267 | **Note:** Notice that the lead developer added a label to the pull request. Labels are used so we can track each version that is committed. The labels can be any nomenclature that the project team wants to use to track each release. 268 | 269 | **Release Manager** 270 | 271 | 1. Reviews the pull request and RemedyForce ticket. Verifies that the appropriate approval have been given in the ticket. 272 | 1. Release manager and COE Reviews code and provides comments for any required changes in the pull request. 273 | 1. Once all comments have been addressed, the release manager accepts the pull request and merges into the {Salesforce}/{Project Name}-Deploy repository release branch. 274 | 1. Tag a release in GitHub for future reference purposes and deploying a specific release to upstream environments. 275 | 1. Executes any pre-deployment steps specified from the ```README.md```. 276 | 1. Executes Jenkins job “{Project Name}-Deploy to Integration” to deploy the release tag from the {Salesforce}/{Project Name}-Deploy repository to the Integration Sandbox. 277 | 1. Executes any post deployment steps specified from the ```README.md```. 278 | 1. This process of pull request could iterate a couple of times in order to fix defects found during the integration tests. Please note that for each integration fix cycle, a pull request has to be generated and a new release tag with an incremental number will to be generated. 279 | 1. Comments on the pull request that the deployment is complete or failed accordingly. 280 | 1. Closes the ticket in RemedyForce once deployment is complete, regardless if the deployment was successful or failed. If the deployment failed the project team must fix any issues and create a new RemedyForce ticket. 281 | 282 | 283 | ####Deploy to UAT 284 | In this step the project team has successfully completed all system testing in the platform integration sandbox and has verified that there are no functional issues with their application and that their application hasn’t impacted any other applications in the integration sandbox. 285 | 286 | **Lead Developer** 287 | 288 | 1. Creates a ticket in RemedyForce requesting to deploy to UAT. Includes link to the pull request in the ticket. 289 | 1. Creates a comment in the pull request asking to deploy from {Project Name}-Deploy repository to UAT and includes the RemedyForce ticket number in the comment. 290 | 291 | **Release Manager** 292 | 293 | 1. Reviews pull request and RemedyForce ticket. Verifies that the appropriate approvals have been given in the ticket. 294 | 1. Performs any pre-deployment steps as outlined in the ```README.md``` file. 295 | 1. Executes Jenkins job “{Project Name}-Deploy to UAT” to deploy the latest release tag from repository {Project Name}-Deploy to the UAT sandbox. 296 | 1. Performs any post deployment steps as outlined in the ```README.md``` file. 297 | 1. Comments on the pull request that the deployment is complete or failed accordingly. 298 | 1. Closes the ticket in RemedyForce once deployment is complete, regardless if the deployment was successful or failed. If the deployment failed the project team must fix any issues and then open a new remedyForce ticket to deploy to integration again. Once tests pass in integration they can then request deployment to UAT again. 299 | 300 | **Project Team** 301 | Tests to make sure everything is functioning as expected in the UAT sandbox. 302 | 303 | ####Deploy to “X Platform Sandbox” 304 | This is an optional step that can be used if the project team wishes to deploy their application to another sandbox now listed in this scenario. 305 | 306 | **Lead Developer** 307 | 308 | 1. Creates a ticket in RemedyForce requesting to deploy to “X Platform Sandbox”. Includes link to pull request in the ticket. 309 | 1. Creates comment in pull request asking to deploy from {Project Name}-Deploy repository to “X Platform Sandbox” and includes RemedyForce ticket number in the comment. 310 | 311 | **Note:** If the project team needs to deploy to another sandbox at the project level and not the platform level they can have the release manager clone a Jenkins job that they can run to deploy to their other sandboxes without requiring a pull request or RemedyForce ticket. 312 | 313 | **Release Manager** 314 | 315 | 1. Reviews the pull request and RemedyForce ticket. Verifies that the appropriate approval have been given in the ticket. 316 | 1. Performs any pre-deployment steps as outlined in the ```README.md``` file. 317 | 1. Executes Jenkins job “{Project Name}-Deploy to X Platform Sandbox” to deploy the latest release tag from repository {Project Name}-Deploy to “X Platform Sandbox”. 318 | 1. Performs any post deployment steps as outlined in the ```README.md``` file. 319 | Comments on the pull request that the deployment is complete or failed accordingly. 320 | 1. Closes the ticket in RemedyForce once deployment is complete, regardless if the deployment was successful or not. Just as with failures when deploying to UAT, if any failures occur they must open a new RemedyForce ticket to deploy to integration first and then they can deploy again to this environment if they make any changes to their code or configuration. 321 | 322 | ####Deploy to Staging 323 | Once all testing has been completed in UAT and signed off, the release manager will then perform a practice deployment to staging just as if a deployment to production was occurring. This step is entirely for the release manager to make sure that he has all of the deployment steps correct before deploying to production. 324 | 325 | **Lead Developer** 326 | 327 | 1. Provides comment in pull request asking to deploy from {Project Name}-Deploy repository to production. 328 | 1. Creates a ticket in RemedyForce requesting to deploy to production. Includes link to pull request in the ticket. 329 | 330 | **Release Manager** 331 | 332 | 1. Approves request for deployment to production and schedules deployment to production. 333 | 1. Performs any pre-deployment steps as outlined in the ```README.md``` file. 334 | 1. Executes Jenkins job “{Project Name}-Deploy to Staging” a specific release tag. 335 | 1. Performs any post-deployment steps as outlined in the ```README.md``` file. 336 | If the deployment failed, removes the deployment from the schedule and closes the ticket in RemedyForce. As with previous steps the project team must fix any issues in code and configuration. Once they fix the issues they can open a ticket in RemedyForce to deploy to integration again. 337 | 338 | **Project Team / Release** 339 | 340 | 1. Performs final smoke tests to make sure everything is working as expected in the staging sandbox. 341 | 342 | **Note:** Only project team members who are authorized to access production data will be granted access to test in the staging sandbox. 343 | 344 | ####Deploy to Production 345 | This is the final step in the release management process. 346 | 347 | **Release Manager** 348 | 349 | 1. The day before the scheduled deployment date, uses Jenkins to perform a full backup of the production environment and commits into the Salesforce master repository with a new version/label for the backup. 350 | 1. On the scheduled deployment date performs any pre-deployment steps as outlined in the ```README.md```. 351 | 1. Executes Jenkins job “{Project Name}-Deploy to Production” a specific release tag. 352 | 1. Performs any post deployment steps as outlined in the ```README.md```. 353 | 1. If the deployment failed, works with the project team to remedy the failure. If the failure cannot be easily remedied, the release is rolled back. 354 | 1. Uses Jenkins to perform a full post deployment backup of the production environment and commits into the master Salesforce repository. 355 | 1. Closes the remedyForce ticket. 356 | 1. Closes the pull request. 357 | 358 | **Project Team** 359 | 360 | 1. Performs testing in production to validate everything is working as expected. 361 | 362 | ####Next Release Initiation 363 | This is the first step in the next release cycle. 364 | 365 | It is recommended that at the beginning of each release, the existing sandboxes for the previous release are retired and replaced with new sandboxes so that all sandboxes reflect the most recent version of production. This step is optional and up to each individual project team. 366 | The longer a project team goes without refreshing their sandboxes, the higher the risk that there will be problems when they attempt to deploy to the platform sandbox environments and production. 367 | 368 | **Release Manager** 369 | 370 | 1. Refreshes the platform, UAT, and staging sandboxes as needed. It is recommended that this is done once a month after a release to ensure that all platform sandboxes match production to reduce deployment issues. 371 | 372 | **Project Team** 373 | 374 | 1. Creates RemedyForce ticket to create environments for the next release. 375 | 376 | **Release Manager** 377 | 378 | 1. Creates a new sandbox for the project team dev for the next release. 379 | 1. Creates and/or refreshes any developer specific sandboxes (as requested). 380 | 381 | **Project Team** 382 | 383 | 1. Creates RemedyForce ticket to retire the previous version sandboxes when no longer needed. 384 | 385 | **Release Manager** 386 | 387 | 1. Deletes previous version project sandboxes. 388 | -------------------------------------------------------------------------------- /_pages/Technical-Approach.md: -------------------------------------------------------------------------------- 1 | - [Guiding Principles](/_pages/Guiding-Principles.md) 2 | - Configuration over code 3 | - Loosely bound APIs 4 | - [APIs use and generation in general](/_pages/APIs-use-and-generation-in-general.md) -------------------------------------------------------------------------------- /_pages/Testing.md: -------------------------------------------------------------------------------- 1 | ###Effective Testing and Debugging 2 | 3 | - [Writing good tests](/_pages/Writing-good-tests.md) 4 | - [Unit testing](/_pages/Unit-testing.md) 5 | - Browser Testing (SauceLabs) - More to come 6 | - Security Testing (Checkmarx) - More to come 7 | - 508/WCAG - More to come 8 | - [Top 10 Best Practices](/_pages/Top-10-Best-Practices.md) 9 | 10 | ####Testing 11 | 12 | (NOTE: http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_testing_best_practices.htm) 13 | 14 | The following principles apply to unit testing Apex code 15 | 16 | 1. Cover as many lines of code as possible 17 | 18 | * Salesforce requires that you have at least 75% of your Apex scripts covered by unit tests to deploy your scripts to production environments. In addition, all triggers should have some test coverage. 19 | 20 | * Salesforce recommends that you have 100% of your scripts covered by unit tests, where possible. 21 | 22 | * In order for a project team to deploy to production or pre-production instances at CFPB, it is required that ALL classes and triggers have at least 90% of code covered by unit tests. 23 | 24 | 2. In the case of conditional logic (including ternary operators), execute each branch of code logic. 25 | 26 | 3. Make calls to methods using both valid and invalid inputs. 27 | 28 | 4. Complete successfully without throwing any exceptions, unless those errors are expected and caught in a try…catch block. 29 | 30 | 5. Always handle all exceptions that are caught, instead of merely catching the exceptions. 31 | 32 | 6. Use ```System.assert``` methods to prove that code behaves as expected. 33 | 34 | 7. Use the ```runAs``` method to test your application in different user contexts. 35 | 36 | 8. Use the isTest annotation. Classes defined with the isTest annotation do not count against your organization limit of 1 MB for all Apex scripts. 37 | 38 | 9. Exercise bulk trigger functionality—use at least 201 records in your tests. 39 | 40 | 10. Write comments stating not only what is supposed to be tested, but the assumptions the tester made about the data, the expected outcome, and so on. 41 | 42 | 11. Debug statements and Comments are not included in the Code coverage. 43 | 44 | 12. User records are not covered by test methods. 45 | 46 | 13. Web service calls should be tested using a Mock class. 47 | 48 | 14. Large amounts of test data should be loaded by using the Test.loadData. 49 | 50 | 15. Never use @seeAllData. Accessing data specific to a sandbox can result in deployments failing 51 | 52 | 16. Do not write test classes merely to get code coverage. It is much more effective to write the test code to cover specific business cases. You will find that if you use this method you will cover much more code, much faster than just writing test code to get coverage only. Additionally this will help ensure that you are meeting the business requirements in addition to testing for bugs. 53 | 54 | 55 | -------------------------------------------------------------------------------- /_pages/Tooling.md: -------------------------------------------------------------------------------- 1 | ## Development Tools 2 | 3 | Below are some of the tools our technologists use. This is exemplary and not intended to be exhaustive. 4 | 5 | 1. Mac 6 | 1. SublimeText 7 | 1. Mavensmate 8 | 1. Eclipse 9 | 1. Data Loader 10 | 2. Java 11 | 1. Ant 12 | 2. Checkmarx 13 | 1. OmniGraffle 14 | 1. Google Apps 15 | 1. Git/GitHub 16 | 2. Jenkins 17 | 3. Jira 18 | -------------------------------------------------------------------------------- /_pages/Top-10-Best-Practices.md: -------------------------------------------------------------------------------- 1 | 2 | #Summary: Top 10 Best Practices (in no order) 3 | 4 | (Source: http://blog.force365.com/2014/09/19/apex-unit-test-best-practice/) 5 | 6 | **Test Driven Development** 7 | 8 | Follow Test Driven Development practice wherever possible. There is no excuse for writing unit tests after the functional code, such an approach is indicative of a flawed development process or lax standards. It’s never a good idea to estimate or deliver functional code without unit tests – the client won’t appreciate an unexpected phase of work at the point of deployment, not to mention the pressure this approach puts on system testing. 9 | 10 | **Code Quality** 11 | 12 | Ensure unit tests are written to cover as many logical test cases as possible, code coverage is a welcome by-product but should always be a secondary concern. Developers who view unit tests as a necessary evil, or worse, need to be educated in the value of unit tests (code quality, regression testing, early identification of logical errors etc. etc.). 13 | 14 | **Test Code Structure** 15 | 16 | For some time now I’ve adopted a Test Suite, Test Helper pattern. A suite class groups tests related to a functional area. A test helper class creates test data for a primary object such as Account (i.e. ```AccountTestHelper.cls```), secondary objects such as price book entry would be created within the product test helper class. The suite concept provides a logical and predictable structure, the helper concept emphasizes that test data creation should be centralized. 17 | 18 | **Test Code Structure (continue)** 19 | 20 | Put bulk tests in a separate class e.g. AccountTriggerBulkTestSuite.cls (in addition to AccountTriggerTestSuite.cls). Bulk tests can take a long time to complete – this can be really frustrating when debugging test failures – particularly in production. 21 | 22 | **Test Code Structure (over and over)** 23 | 24 | Ensure test classes contain a limited number of test methods. I tend to limit this to 10. As with point 4, this relates to test execution time, individual methods can’t be selectively executed – the smallest unit of execution is the class. 25 | 26 | **SeeAllData** 27 | 28 | Always use SeeAllData=true by exception and at the test method level only. Legacy test code related to pricebooks that historically required this can now be refactored to use Test.getStandardPricebookId(). Also, set the [Independent Auto-Number Sequence] flag to avoid gaps in auto number sequences through the creation of transient test data. 29 | 30 | **Test Case Types** 31 | 32 | As the Apex Language reference proposes, write unit tests for the following test case types. 33 | * _Positive Behavior_ – logical tests that ensure the code behaves as expected and provides successful positive outcomes 34 | * _Negative Behavior_ – logical tests for code behavior where parameters are missing, or records do not adhere to defined criteria – does the code protect the integrity of unaffected records – does the runtime exception handling function as expected 35 | * _Bulk_– trigger related tests primarily – how the code behaves with a batch of 200 records – mix the batch composition to stress the code against governor limits 36 | * _Restricted User_ – test relevant combinations of user role and profile – this test case type is prone to failure through sharing model adjustments – triggers should delegate processing to handler classes that have the “with sharing” modifier 37 | 38 | **Debugging** 39 | 40 | Always use the syntax below for debug statements within code (test and non-test code). An efficient practice is to add sensible outputs whilst writing the code. This approach avoids a code update or re-deployment to add debug statements during error diagnostics. Note – in such cases Checkpoints could be a better approach anyway – particularly in production. The use of the ERROR logging level enables a restrictive log filter to be applied such a clear debug log is produced and max log size truncation is avoided – note, log filters can also have a positive impact on transaction execution time. 41 | System.debug(LoggingLevel.ERROR, 'my message'); 42 | 43 | **Commenting** 44 | 45 | Always comment test methods verbosely to ensure the test case intent is clear and that the test code can be mapped to the related non-test code. Test classes should be fully self documenting and be viewed as the primary enabler for the future maintenance of the non-test code. 46 | 47 | **Maintenance** 48 | 49 | Test code is highly dependent on the environment state. Any configuration change can require test code to be updated; this could be a new mandatory custom field or a sharing model adjustment. In many cases the resultant unit test failure state is not encountered until the next deployment to production, which can’t proceed until the tests are fixed. This scenario will be familiar to many people. The mitigation requires the local administrator to understand the risk, frequently run the full set of unit tests and to manage the test code update cycle proactively. 50 | -------------------------------------------------------------------------------- /_pages/Triggers.md: -------------------------------------------------------------------------------- 1 | ## Triggers 2 | There are many considerations that must be taken in account when developing apex triggers. A poorly written trigger can easily cause your application to cease to function. 3 | ## Muting Triggers 4 | It is a best practice when developing triggers that you have the ability to easily disable the functionality of triggers. This is especially useful for when you need to perform data loads, or if a trigger is causing user errors. By default there is no easy way to disable a trigger using configuration. Once a trigger or other apex class has been migrated to production, the only way to disable it would be by using the metadata API to delete it. 5 | 6 | In order to allow for making it easy to disable triggers, all triggers must have logic allowing the triggers to be disabled by profile and/or user using custom settings or custom metadata types. 7 | 8 | The example below shows how to implement the logic to disable a trigger using custom settings. 9 | 10 | ```java 11 | Public with sharing class Helper 12 | { 13 | public static Boolean IsTriggerEnabled() 14 | { 15 | TriggerExecutionSettings__c settings = TriggerExecutionSettings__c.getValues(“AccountInsertUpdate”); 16 | 17 | List profileIds = settings.EnabledProfileIds__c.split(‘’’); 18 | Map profileIdMap = new Map(); 19 | 20 | For(integer i=0;i rtypes = [Select Name, Id From RecordType 99 | where sObjectType='Account' and isActive=true]; 100 | 101 | //Create a map between the Record Type Name and Id for easy retrieval 102 | Map accountRecordTypes = new Map{}; 103 | for(RecordType rt: rtypes){ 104 | accountRecordTypes.put(rt.Name,rt.Id); 105 | } 106 | 107 | for(Account a: Trigger.new){ 108 | //Use the Map collection to dynamically retrieve the Record Type Id 109 | //Avoid hardcoding Ids in the Apex code 110 | if(a.RecordTypeId==accountRecordTypes.get('Healthcare')) 111 | { 112 | //do some logic here..... 113 | }else if(a.RecordTypeId==accountRecordTypes.get('High Tech')) 114 | { 115 | //do some logic here for a different record type... 116 | } 117 | } 118 | ``` 119 | 120 | By ensuring no IDs are stored in the Apex code, you are making the code much more dynamic and flexible - and ensuring that it can be deployed safely to different environments. 121 | 122 | ## Custom Settings 123 | Custom settings are a useful tool when you have application specific settings that you wish to store that let you configure the application rather than having to make a code change every time these settings change. 124 | 125 | Try to utilize custom settings whenever possible when you find that you need to hardcode a static value such as email addresses or Salesforce Ids within your application. 126 | 127 | Another good use of custom settings is to allow for tweaking of the performance of the application. For example: Instead of hard coding the number of records to process for a batch apex method to 200 records, you could create a custom setting that allows you to easily change the number of records to be processed for each batch. 128 | 129 | Additionally as mentioned above in the “Muting Triggers” section, Custom settings can be used to allow you to enable/disable triggers, or other code, since you are unable to do this easily from your production environment natively. 130 | 131 | ## Enforcing Sharing Rules in Controllers 132 | 133 | Like other Apex classes, all controllers and controller extensions run in system mode. Typically, we want a controller or controller extension to respect a user's organization-wide defaults, role hierarchy, and sharing rules. We can do that by using 'with sharing' keywords in the class definition. Note that if a controller extension extends a standard controller, the logic from the standard controller does not execute in system mode. Instead, it executes in user mode, in which the profile-based permissions, field-level security, and sharing rules of the current user apply. Unless you have a good reason for needing to expose all records of a class to the running user then all classes should ALWAYS use the “with sharing” keywords. 134 | 135 | If you do not use this practice it is possible that a user could gain access to records that they normally would not have access to. 136 | 137 | ## Governor Limits 138 | 139 | Because of the multitenant nature of Salesforce, various types of governor limits are enforced to ensure that one tenant does consume all of the resources. The following are best practices to avoid hitting limits. 140 | 141 | * Limiting queries by using static class variables to store query results instead of firing frequent queries. 142 | * Never use SOQL/SOSL/DML in loops. 143 | * Leverage custom settings to create custom sets of data, as well as create and associate custom data for an organization, profile, or specific user. All custom settings data is exposed in the application cache, which enables efficient access without the cost of repeated queries to the database. This data can then be used by formula fields, validation rules, Apex, and the SOAP API. 144 | * Making sure that database statements such as insert(), update(), and delete() operate in bulk 145 | * Use system methods to track governor limits: Apex has a System class called Limits that lets you output debug messages for each governor limit. There are two versions of every method. The first returns the amount of the resource that has been used in the current context, while the second version contains the word limit and returns the total amount of the resource that is available for that context. Using these methods judiciously ensures that the execution governor limits are never hit. 146 | * Enable governor limit warning emails: When an end-user invokes Apex code that surpasses more than 50% of any governor limit, you can specify a user in your organization to receive an email notification of the event with additional details. 147 | * Asynchronous execution: Use asynchronous apex (@future) appropriately. Async apex gets its own governor limits but there are a maximum of ten @future methods within a single apex transaction. Do not call future methods from triggers. 148 | * Batch Apex: Use of Batch Apex to handle millions of records. Every batch gets its own set of governor limits. Do not initiate batches from triggers. 149 | -------------------------------------------------------------------------------- /_pages/Unit-testing.md: -------------------------------------------------------------------------------- 1 | # How to Write Good Unit Tests 2 | (Source: https://developer.salesforce.com/page/How_to_Write_Good_Unit_Tests) 3 | ## Abstract 4 | This article shows how to craft good unit tests. It explores the proper structure of unit tests, the code scenarios that unit tests should cover, and the properties of well-written unit tests. There are plenty of code samples interspersed throughout the article to demonstrate and help illustrate the concepts. 5 | 6 | ## Unit Test Introduction 7 | A unit test is code that exercises a specific portion of your codebase in a particular context. Typically, each unit test sends a specific input to a method and verifies that the method returns the expected value, or takes the expected action. Unit tests prove that the code you are testing does in fact do what you expect it to do. 8 | 9 | The Force.com platform requires that at least 75% of the Apex Code in an org be executed via unit tests in order to deploy the code to production. You shouldn’t consider 75% code coverage to be an end-goal though. Instead, you should strive to increase the state coverage of your unit tests. Code has many more possible states than it has lines of code. For example, the following method has 4,294,967,296 different states: 10 | double getFraction(Integer a){ return 1/a; } 11 | 12 | Clearly, you wouldn’t want to test all of the different states for this program. Instead, you should probably test a few different inputs for this method, even if it means that you will have achieved 100% code coverage several times over. 13 | 14 | Three different states that you might consider testing are a positive input, a negative input and a 0 input. Testing with a positive input, and with a negative input will behave as expected. Testing with a 0 input however will yield a surprise System.MathException. This is just one example of why it makes sense to focus on testing the different states of your code instead of focusing on just the 75% code coverage requirement. 15 | 16 | ## The Value of Unit Tests 17 | One of the most valuable benefits of unit tests is that they give you confidence that your code works as you expect it to work. Unit tests give you the confidence to do long-term development because with unit tests in place, you know that your foundation code is dependable. Unit tests give you the confidence to refactor your code to make it cleaner and more efficient. 18 | 19 | Unit tests also save you time because unit tests help prevent regressions from being introduced and released. Once a bug is found, you can write a unit test for it, you can fix the bug, and the bug can never make it to production again because the unit tests will catch it in the future. 20 | 21 | Another advantage is that unit tests provide excellent implicit documentation because they show exactly how the code is designed to be used. 22 | 23 | Lastly Salesforce.com uses unit tests to ensure that their releases don’t break customer code. The more tests you write, the better Salesforce.com is able to ensure they are not breaking customer customizations. Before and after every release Salesforce.com will run all test code written by their customers. Then after the release will run the code again. They then make sure that all tests had the same outcome before and after the release. That is why it is in your benefit to write good tests that cover as much of your code as possible. 24 | 25 | Many developers have discovered these advantages. Some developers, including me, believe so strongly in the value of unit tests that we write our tests first and our production code second. I’m going to show you an example of this test-first development practice a little later on in the article. 26 | 27 | ## Unit Test Structure 28 | Let’s take a look at how unit tests are best structured. All unit tests should follow the same basic structure. 29 | 30 | A unit test should: 31 | * Set up all conditions for testing. 32 | * Call the method (or Trigger) being tested. 33 | * Verify that the results are correct. 34 | * Clean up modified records. (Not really necessary on Force.com.) 35 | 36 | Let’s discuss each of these in turn. 37 | 38 | ### Set Up All Conditions for Testing 39 | Typically, methods perform some sort of operation upon data. So in order to test your methods, you’ll need to set up the data required by the method. This might be as simple as declaring a few variables, or as complex as creating a number of records in the Force.com database. For example, if you have a trigger like this one that updates an Opportunity’s parent Account after the Opportunity is inserted: 40 | 41 | trigger UpdateParentAccountWithOpportunityName on Opportunity (after insert) { 42 | // Create a Map from Account Ids to Opportunities. 43 | Map accountIdOpportunityMap = new Map(); 44 | for(Opportunity oOpportunity : Trigger.new){ 45 | accountIdOpportunityMap.put(oOpportunity.AccountId, oOpportunity); 46 | } 47 | 48 | // Create a list of Accounts to Update. 49 | List accounts = new List(); 50 | for(Account oAccount : [SELECT Id, Most_Recently_Created_Opportunity_Name__c 51 | FROM Account 52 | WHERE Id IN :accountIdOpportunityMap.keySet()]) { 53 | oAccount.Most_Recently_Created_Opportunity_Name__c = 54 | ((Opportunity) accountIdOpportunityMap.get(oAccount.Id)).Name; 55 | accounts.add(oAccount); 56 | } 57 | 58 | update accounts; 59 | } 60 | 61 | Then, your setup code could look something like this: 62 | 63 | Account oAccount = new Account(Name='My Account'); 64 | insert oAccount; 65 | Opportunity oOpportunity = new Opportunity(AccountId=oAccount.Id, 66 | Name='My Oppty', StageName='Prospecting', 67 | CloseDate=Date.today()); 68 | 69 | Your unit tests should always create their own test data to execute against. That way, you can be confident that your tests aren’t dependent upon the state of a particular environment and will be repeatable even if they are executed in a different environment from which they were written. 70 | 71 | If you find that many of your unit tests require very similar setup code, be sure to properly decompose the setup code so that you don’t repeat yourself. 72 | 73 | ### Call the method (or Trigger) being tested 74 | Once you have set up the appropriate input data, you still need to execute your code. If you are testing a method, then you will call the method directly. In this case, we’re testing a Trigger, so we’ll need to perform the action that causes the trigger to execute. In our sample, that means that we will need to insert the Opportunity: 75 | 76 | insert o; 77 | 78 | ### Verify the results are correct 79 | Verifying that your code works as you expect it to work is the most important part of unit testing. It’s also one of the things that Force.com developers commonly neglect. Unit tests that do not verify the results of the code aren’t true unit tests. They are commonly referred to as smoke tests, which aren’t nearly as effective or informative as true unit tests. 80 | 81 | A good way to tell if unit tests are properly verifying results is to look for liberal use of the System.assert() methods. If there aren’t any System.assert() method calls, then the tests aren’t verifying results properly. And, no, System.assert(true); doesn’t count. 82 | 83 | Sample verification code for this trigger might look like this: 84 | 85 | oAccount = [SELECT Name, Most_Recently_Created_Opportunity_Name__c 86 | FROM Account 87 | WHERE Id = :oAccount.Id]; 88 | 89 | System.assertEquals('My Oppty', oAccount.Most_Recently_Created_Opportunity_Name__c); 90 | 91 | Notice that this unit testing code explicitly verifies that the trigger performed the action that we expected. 92 | 93 | ### Clean up (is Easy!) 94 | Cleaning up after unit tests is easy, because there’s nothing to do! Actions performed on records inside of a unit test are not committed to the database. This means that we can insert, delete, and modify records without having to write any code that will clean up our changes. Even the results of trigger executions that affect existing data are not committed! 95 | 96 | ### Where to put tests? 97 | Your Trigger files can never contain code other than the Trigger definition, so Trigger unit tests must always be located in a separate class file. 98 | 99 | Unit tests for your classes are also required to be in a separate class. The most important reason for this is that by separating your class implementation and your unit tests, you will automatically be prevented from testing private methods and private properties. You shouldn’t test private methods and private properties because doing so will cause your unit tests to become a barrier to refactoring. With your classes and unit tests separated in to different files, you will always have the option to change the internal implementation of your classes should the need arise. If you ever do find yourself compelled to test a private or protected method, this is probably a strong indication that the method should be refactored in to its own stand-alone class. 100 | 101 | As an additional incentive, this best practice of separating unit tests and classes also allows you to take advantage of the @isTest annotation. The code inside of an @isTest annotated file does not count against the overall Apex code size limitation for your org. 102 | 103 | ### Putting it all together 104 | Here's the complete unit test for the trigger, which it's put in UpdateParentAccountWithOpportunityName_Test.cls. 105 | 106 | ```java 107 | @isTest 108 | private class UpdateParentAccountWithOpptyName_Test{ 109 | static testMethod void testUpdateParentAccount() { 110 | // Set up the Account record. 111 | Account oAccount = new Account(Name='Test Account'); 112 | insert oAccount; 113 | 114 | // Verify that the initial state is as expected. 115 | oAccount = [SELECT Name, Most_Recently_Created_Opportunity_Name__c 116 | FROM Account 117 | WHERE Id = :oAccount.Id]; 118 | System.assertEquals(null, oAccount.Most_Recently_Created_Opportunity_Name__c); 119 | 120 | // Set up the Opportunity record. 121 | String sOpportunityName = 'My Opportunity'; 122 | Opportunity oOpportunity = new Opportunity(AccountId=oAccount.Id, 123 | Name=sOpportunityName, 124 | StageName='Prospecting', 125 | CloseDate=Date.today()); 126 | 127 | // Cause the Trigger to execute. 128 | insert oOpportunity; 129 | 130 | // Verify that the results are as expected. 131 | oAccount = [SELECT Name, Most_Recently_Created_Opportunity_Name__c 132 | FROM Account 133 | WHERE Id = :oAccount.Id]; 134 | System.assertEquals(sOpportunityName, oAccount.Most_Recently_Created_Opportunity_Name__c); 135 | } 136 | } 137 | ``` 138 | Note the use of the @isTest annotation, as well as the general structure of the test - first the setup, then the action, and finally the verification. 139 | -------------------------------------------------------------------------------- /_pages/Visualforce-Pages.md: -------------------------------------------------------------------------------- 1 | ##Visualforce Page Best Practices 2 | Just because you can, doesn’t mean you should! Before going down the customization route make sure you properly evaluate the pros and cons of creating custom pages. This is especially true when creating custom pages to override standard functionality. When overriding standard functionality you lose the advantage gained of new features in future releases. 3 | If you do go down the customization route you must make sure you optimize the Visualforce pages you create for better performance in order to have a positive user experience. 4 | 5 | * Avoid using the rendered=”false” if possible. Even though the components do not show up on the page, processing still needs to be done that will cause the page to render slower. If a large portion of the components of a Visualforce page have rendered=”false”, consider creating a separate page instead of using partial rendering. 6 | * Use Salesforce remote objects to perform asynchronous execution of apex using JavaScript. This will allow the user to perform operations without having to wait for the server to respond. 7 | * Cache data in custom settings, custom metadata types, and the org cache to improve the performance of the page. Access to data in these mechanisms is much faster than executing SOQL queries to retrieve the same data. Additionally they do not count against your max queries limit. 8 | * Avoid the use of iframes whenever possible as these will slow the loading of the page. If you need to create a window into Salesforce from an external system consider using Canvas instead, since it is much more tightly integrated into Salesforce and takes care of the authentication for you. 9 | * Use minified JavaScript and CSS file resources 10 | * Avoid use of references to external scripts or resources. Instead download them as static resources and reference the static resources. Static resources are cached and provide for better performance. Never reference a Salesforce unsupported JavaScript or CSS library directly as these could change at any time. Any API that is not versioned is considered an unsupported API. 11 | * Use only web optimized images and image maps to reduce the need to load multiple images. 12 | * Use paging techniques when working with large datasets on a page. Avoid displaying more than 20 results per page. Use the SOQL offset or the standardSetController to control paging. 13 | * Make sure all your SOQL queries are optimized using the query optimizer located in the developer console. 14 | * Use lazy loading techniques to load parts of the page first, giving users access to some of the functionality while other parts of the page are still loading. For example you can load the page first and then the data for the page once the page has finished loading. 15 | * Instead of polling to retrieve changes in data or refreshing the page consider using the streaming api to receive push notifications when data has changed. 16 | 17 | For more Visualforce best practices see 18 | http://www.salesforce.com/docs/en/cce/salesforce_visualforce_best_practices/salesforce_visualforce_best_practices.pdf 19 | 20 | ## Lightning Components Vs. Visualforce? 21 | Lightning components are a rather new addition to the Salesforce suite of development tools. There is much confusion as to what are lightning components and when to use lightning versus Visualforce. 22 | 23 | ### What is Lightning? 24 | Lightning is a framework that Salesforce has built to allow for a new look and feel to Salesforce, as well as the ability to create faster, more lightweight applications. 25 | 26 | There are three 3 main parts to lightning: 27 | 28 | 1. **Lightning Experience** – The lightning experience is a completely new look and feel to Salesforce that takes into account modern user interface design practices that are commonly used throughout the web today. This is based on responsive design patterns such that the format of what you can see on the screen is based on the screen size on which you are viewing the content. Each page is made up of various components that can be easily changed out or rearranged. 29 | 1. **Lightning Design System** – The design system is a new UI framework built off of angular that helps developers easily recreate the same look and feel of the Lightning Experience in their custom applications. This framework can be used in Visualforce, Lightning Components, or even in custom external based web applications. For more information on the design system visit http://www.lightningdesignsystem.com 30 | 1. **Lightning Components** – Lightning components is a new development infrastructure that Salesforce has developed to quickly create high performing web applications based on a component model. A lightning component can be a web page or even a piece of a web page. Lightning components turn HTML, JavaScript, and CSS into an object-oriented language. Everything is a first class component in this framework. What this means is that instead of having to traverse the DOM you use getters and setters to access various elements of your application. For example the following are “objects” or “components” in the framework: “div”, “form”, “input”, “head”, “body”, “span”, JavaScript events such as “onclick”, etc. 31 | The real power of lightning is that you can pass components between each other to build reusable pieces of an application. You can even pass a JavaScript event that fires from one component to another! 32 | 33 | The Salesforce Lightning Experience is even built using Lightning Components. That means you can develop your own custom components using the same technology that Salesforce uses internally. Combining that with the Lightning Design System you can completely replicate any out of the box component in the Lightning Experience. 34 | 35 | ### Lightning vs. Visualforce? 36 | The question many people ask is “Will Visualforce be going away?” Think of lightning as just yet another tool in your Salesforce Tool belt. Both have their uses based on what you are trying to do. 37 | 38 | **Visualforce Pros** 39 | 40 | * Can be made to look like the “Aloha” look and feel of Salesforce without much trouble. 41 | * Can use the Lightning Design framework to make the look feel of that of the Lightning Experience. 42 | * Allows for quick development of pages that interact directly with the Salesforce platform keeping everything on the server-side. 43 | * Is a tried and true development platform in use today by thousands of customers. 44 | * Is better for single page applications that are not component based. 45 | 46 | **Lightning Pros** 47 | 48 | * Since most everything runs client-side, and all server-side calls to Salesforce are performed asynchronously, it is very fast. 49 | * Allows you to easily make applications with the same look and feel of the lightning experience. 50 | * Since everything is component based you can separate the development out to several different developers without risking the developers stepping on each other. 51 | * Since even the styling is broken out you can have your UI designer work independently of your Salesforce developers on various components. 52 | * Allows you to quickly change, add, or remove pieces of a page without having to think about refactoring the entire page. 53 | * Ideal when you have the need to create a more component-based application made up of multiple “mini applications”, rather than a single page application. 54 | * Ideal for creating lightweight, responsive mobile applications. 55 | 56 | **Visualforce Cons** 57 | 58 | * Is very heavy, and much slower than the lightning framework because it uses a stateful infrastructure to keep the state for round-trips from the server. 59 | * Requires a lot of work to rearrange pieces of the screen. Usually requires a complete rework of the HTML. 60 | * Very difficult for multiple developers to work on the same page at the same time. Salesforce developers will typically have to wait for the UI designer to complete their work before adding functionality. 61 | 62 | **Lightning Cons** 63 | 64 | * Requires a little bit of a learning curve for seasoned Visualforce developers, as it requires strong JavaScript skills and is a completely different approach to development on the Salesforce platform. 65 | * Doesn’t support creating applications with the current “Aloha” UI look and feel. 66 | 67 | When deciding to use lightning or Visualforce, carefully consider each of the pros and and cons. Consider the following questions when making your decision? 68 | 69 | 1. Will the application be a standalone application, or can it be broken into multiple components? 70 | 1. Does the application need to be responsive and run on multiple device formats? 71 | 1. Will the application need to look and feel like the “Aloha” UI or the “Lightning Experience” UI? 72 | 1. Do our developers have strong JavaScript and CSS skills? Will there be considerable ramp up time if we choose to use lightning? 73 | -------------------------------------------------------------------------------- /_pages/Writing-good-tests.md: -------------------------------------------------------------------------------- 1 | # What to Test 2 | Broadly speaking, you should test your custom business logic. How thoroughly you test that business logic will probably vary depending on specific situations. On one end of the spectrum, you might choose to implement just a few tests that only cover the code paths that you believe are most likely to contain a bug. On the other end of the spectrum, you might choose to implement a large suite of unit tests that are incredibly thorough and test a wide variety of scenarios. Wherever a given project falls on that spectrum, you should be sure to write unit tests that verify your code behaves as expected in "normal" scenarios as well as in more "unexpected" scenarios, like boundary conditions or error conditions. 3 | 4 | In order to give you a better idea of the kinds of things that you should be testing, I'll walk through the process of writing unit tests for an implementation of a Stack data structure that can be used to store Strings. 5 | 6 | ## Stack Interface 7 | The first thing that I need to do is define the publicly accessible methods for our StringStack class: 8 | 9 | public class StringStack { 10 | public void push(String s) { } 11 | public String pop() { return null; } 12 | public String peak() { return null; } 13 | public Boolean isEmpty() { return true; } 14 | } 15 | 16 | You’ll notice that I haven’t written any real implementation code for these method definitions. That’s because I’m going to use Test Driven Development techniques in this example. In Test Driven Development, unit tests are written before any real implementation code is written. I’ve found that writing my unit tests first helps me better understand how clients of my code are going to use it. 17 | 18 | ## Testing Normal Conditions 19 | Next, I’m going to write a test that will exercise my code in the most basic way – I’m going to add just one String value to the Stack: 20 | 21 | /* Verifies that push(), pop() and peak() work correctly 22 | * when there is only 1 object on the Stack. */ 23 | static testMethod void basicTest() { 24 | // Instantiate a StringStack. 25 | StringStack oStack = new StringStack(); 26 | 27 | // Verify the initial state is as expected. 28 | System.assert(oStack.isEmpty()); 29 | 30 | // Set up some test data. 31 | String sOnlyString = 'Only String'; 32 | 33 | // Call the push() method and verify the Stack is no longer empty 34 | oStack.push(sOnlyString); 35 | System.assert(!oStack.isEmpty()); 36 | 37 | // Verify that the value we pushed on the Stack is the one we expected 38 | String sPeakValue = oStack.peak(); 39 | System.assertEquals(sOnlyString, sPeakValue); 40 | System.assert(!oStack.isEmpty()); 41 | 42 | // Verify the Stack state after pop() is called. 43 | String sPopValue = oStack.pop(); 44 | System.assertEquals(sOnlyString, sPopValue); 45 | System.assert(oStack.isEmpty()); 46 | } 47 | 48 | If you run this test right now, your code is going to fail: 49 | 50 | ![Failed Test](/img/failed_test.png) 51 | 52 | So, now that we know what we need to implement, we’re going to write the code needed to pass the first unit test: 53 | 54 | public class StringStack { 55 | private List stack; 56 | 57 | public StringStack(){ 58 | stack = new List(); 59 | } 60 | 61 | public void push(String s){ stack.add(s); } 62 | 63 | public String pop() { 64 | return stack.remove(lastItemIndex); 65 | } 66 | 67 | public String peak() { 68 | return stack.get( lastItemIndex ); 69 | } 70 | 71 | public Boolean isEmpty() { return stack.isEmpty(); } 72 | 73 | // Helper Property 74 | private Integer lastItemIndex { 75 | get { return stack.size() - 1; } 76 | } 77 | } 78 | 79 | Now if we run the unit test again, the code passes the test: 80 | 81 | ![Passed Test](/img/passed_test.png) 82 | 83 | In fact, you can see that we have 100% code coverage. We could stop here, but we really want to be confident in the code, so there are a few more conditions that we’re going to test. We haven’t yet verified that the Stack implementation handles multiple values, and that it can pop() them in the correct order, so the next test is going to verify those things: 84 | 85 | /* Verifies that push(), pop() and peak() work correctly 86 | * when there are multiple objects on the Stack. */ 87 | static testMethod void verifyCorrectOrderTest() { 88 | // Instantiate a StringStack. 89 | StringStack stack = new StringStack(); 90 | 91 | // Set up some test data. 92 | String bottomString = 'Bottom String'; 93 | String middleString = 'Middle String'; 94 | String topString = 'Top String'; 95 | 96 | // Call the push() method with multiple objects 97 | stack.push(bottomString); 98 | stack.push(middleString); 99 | stack.push(topString); 100 | 101 | // Verify that the 'top' object is the object we expected 102 | String peakValue = stack.peak(); 103 | System.assertEquals(topString, peakValue); 104 | 105 | // Verify that the order of the objects is as we expected 106 | String popValue = stack.pop(); 107 | System.assertEquals(topString, popValue); 108 | popValue = stack.pop(); 109 | System.assertEquals(middleString, popValue); 110 | popValue = stack.pop(); 111 | System.assertEquals(bottomString, popValue); 112 | System.assert(stack.isEmpty()); 113 | } 114 | 115 | The code passes this test too, so we are pretty confident that it handles the "normal" conditions pretty easily. Next, let’s test some of the more "unexpected" scenarios. 116 | 117 | ## Testing Unexpected Conditions 118 | There are many scenarios that your code shouldn’t encounter. However, you can’t trust that clients of your code will always do the right thing, so you have to make sure that the code will still handle these unexpected scenarios appropriately. Let’s look at a few examples: 119 | 120 | **Bad Input Values** 121 | 122 | One potentially unexpected condition that the code might encounter is an unexpected value, like null, being passed to the push() method. You have a few implementation options for handling this scenario. Your code could ignore the null value, it could insert a special placeholder value, or it could not allow null values to be pushed on to the Stack at all. In my implementation, I’m not going to allow null values to be pushed on to the Stack at all, and I’m going to throw an exception if a client my code attempts to do so. My unit tests should explicitly test this design decision, so I’m going to write it first: 123 | 124 | static testMethod void nullValueNotAllowedExceptionTest() { 125 | StringStack oStack = new StringStack(); 126 | 127 | try { 128 | stack.push(null); 129 | } catch (StringStack.NullValueNotAllowedException e){ 130 | // Exit the test if the expected NullValueNotAllowedException is thrown. 131 | return; 132 | } 133 | 134 | // Fail the test if the expected NullValueNotAllowedException is not thrown. 135 | System.assert(false, 136 | 'A NullValueNotAllowedException was expected, but was not thrown.'); 137 | } 138 | 139 | At this point, the code is still going to fail this new unit test, so I need to change my push() implementation to make it pass this new unit test: 140 | 141 | public void push(String s){ 142 | if (s == null) { throw new NullValueNotAllowedException(); } 143 | stack.add(s); 144 | } 145 | 146 | public class NullValueNotAllowedException extends Exception {} 147 | 148 | Now the implementation passes all unit tests again. 149 | 150 | Bad input values are one of the most commonly encountered unexpected scenarios in development. A common scenario in Apex where you might encounter unexpected, or missing data is if a query doesn’t return a record, but your code expects one to be present: 151 | 152 | Account oAccount = [SELECT Name FROM Account WHERE Id = :accountId]; 153 | String sAccountName = oAccount.Name; 154 | 155 | If the record that you are querying for has gone missing due to a deletion, or some other action, you’re going to have a bug on your hands because a won't be pointing to a record, but will be null. 156 | 157 | **Boundary Conditions** 158 | 159 | Boundary conditions are another common source of bugs. Let’s verify that our StringStack implementation handles the overflow and underflow boundary conditions. Please note that the following example was written before the list limit was removed but the concept of boundary conditions is still very much valid. 160 | 161 | The Apex documentation indicates that a List used to only contain 1,000 records. If a 1,001th object were to be added to our List-based Stack implementation, a System exception would be thrown. Instead of letting this generic exception be thrown, I’m going to design a test that expects a StringStack-specific exception be thrown when there is an overflow condition. 162 | 163 | static testMethod void stackOverflowTest() { 164 | StringStack oStack = new StringStack(); 165 | 166 | try { 167 | for (Integer nIndex = 0; nIndex < StringStack.MAX_STACK_DEPTH + 1; nIndex++) { 168 | oStack.push('String ' + nIndex); 169 | } 170 | } catch (StringStack.StackOverflowException e) { 171 | // Exit the test if the expected StackOverflowException is thrown. 172 | return; 173 | } 174 | 175 | // Fail the test if the expected StackOverflowException is not thrown. 176 | System.assert(false, 177 | 'A StackOverflowException was expected, but was not thrown.'); 178 | } 179 | 180 | Notice that the above unit test illustrates a common, and useful, pattern for verifying that a piece of code does in fact throw an exception as expected. The unit test’s try-catch block only catches a StackOverflowException. If this StackOverflowException is not thrown, this unit test would fail. 181 | Now that I have a unit test that expects a StackOverflowException to be thrown, I need to modify the code to actually throw this exception: 182 | 183 | public void push(String s) { 184 | if (s == null) { throw new NullValueNotAllowedException(); } 185 | if (this.isFull()) { throw new StackOverflowException(); } 186 | stack.add(s); 187 | } 188 | 189 | public static final Integer MAX_STACK_DEPTH = 1000; 190 | public Boolean isFull() { return MAX_STACK_DEPTH == stack.size(); } 191 | 192 | public class StackOverflowException extends Exception {} 193 | 194 | Now that I’ve handled the overflow boundary condition, I also need to test the underflow boundary condition where there is nothing in the stack to pop(). My current implementation of pop() will generate a System.ListException in this scenario. I want to hide the internal implementation of my StringStack class though, so I’m going to write a unit test that expects a StringStack-specific exception be thrown in this scenario too. 195 | 196 | static testMethod void stackPopUnderflowTest() { 197 | StringStack oStack = new StringStack(); 198 | 199 | try { 200 | oStack.pop(); 201 | } catch (StringStack.StackUnderflowException e) { 202 | // Exit the test if the expected StackUnderflowException is thrown. 203 | return; 204 | } 205 | 206 | // Fail the test if the expected StackUnderflowException is not thrown. 207 | System.assert(false, 208 | 'A StackUnderflowException was expected, but was not thrown.'); 209 | } 210 | 211 | Here’s the modified version of the pop() method that passes this new unit test: 212 | 213 | public String pop() { 214 | if (this.isEmpty()) { throw new StackUnderflowException(); } 215 | return stack.remove( lastItemIndex ); 216 | } 217 | 218 | public class StackUnderflowException extends Exception {} 219 | 220 | Notice that this exception-expecting unit test follows the same pattern as the previous exception-expecting unit test. This is a very useful pattern. 221 | 222 | **Regression Tests** 223 | 224 | Fixing bugs is usually frustrating. It’s even more frustrating when you have to fix the same bug multiple times. That’s why it’s a good idea to add tests to your test suite every time you find a bug in your code. For example, if I were to release my code in to production as it is, a StringStack client might discover that the peak() method doesn’t handle the underflow boundary condition in the same way as the pop() method. In order to verify that this bug doesn’t get reintroduced in a future release, I’m going to write one last unit test: 225 | 226 | static testMethod void stackPeakUnderflowTest() { 227 | StringStack oStack = new StringStack(); 228 | 229 | try { 230 | oStack.peak(); 231 | } catch (StringStack.StackUnderflowException e) { 232 | // Exit the test if the expected StackUnderflowException is thrown. 233 | return; 234 | } 235 | // Fail the test if the expected StackUnderflowException is not thrown. 236 | System.assert(false, 237 | 'A StackUnderflowException was expected, but was not thrown.'); 238 | } 239 | 240 | And finally, I’ll make the following change so that my code passes this new unit test: 241 | 242 | public String peak() { 243 | if (this.isEmpty()) { throw new StackUnderflowException(); } 244 | return stack.get( lastItemIndex ); 245 | } 246 | 247 | # Making use of Test.isRunningTest() method 248 | 249 | There are some situations, when you will just not be able to test some code in a normal matter; e.g., you're using objects that cannot be inserted in tests, or doing some http requests. In such case, if you think there is no other option, consider using Test.isRunningTest(). This static method allows you to discover whether the code was run from test method. Therefore, for example you might: 250 | * return hard-coded String instead of calling http request and parsing the body 251 | * return a fixed array of objects from a method 252 | It might be actually used as a basic introduction to mocks, which are very widespread in other languages. 253 | 254 | # Force.com-specific Testing 255 | In addition to verifying that your code executes properly in normal scenarios, testing edge cases and preventing regressions, you may find that you need to test certain Force.com-specific aspects of your application as well. Things like Apex Callouts, SOSL queries, Governor Limits, etc. To learn more about these topics you’ll want to read these articles: 256 | 257 | |Document Name | 258 | |-------------| 259 | | [Testing Apex Callouts](https://developer.salesforce.com/index.php?title=Virtual_Callout_Testing) | 260 | | [Testing SOSL](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_SOSL.htm) | 261 | | [Verifying Large DataSets](https://developer.salesforce.com/page/Best_Practice:_Ensure_Test_Methods_Verify_Large_Datasets) | 262 | | [Testing with RunAs](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_tools_runas.htm) | 263 | 264 | 265 | # Properties of Well-Written Unit Tests 266 | Well-written unit tests are thorough, repeatable, and independent. Let’s examine each of these properties in turn. 267 | ## Thorough 268 | The most important aspect of well-written unit tests is that your unit tests must be thorough. The Force.com platform requires 75% code coverage, but this is a minimum and should not be your end goal. You should only be satisfied with your unit tests when you’re confident that your unit tests thoroughly verify that your code works as we expect it to work. To do this, your tests must use the various System.assert() calls. Unit tests should exercise the expected as well as the unexpected conditions in your code. Special attention should be paid to areas of code that are particularly likely to break. 269 | 270 | ## Repeatable 271 | Every one of your unit tests should be able to be run repeatedly and continue to produce the same results, regardless of the environment in which the tests are being run. When your unit tests can be run in a repeatable and consistent manner, you can trust that your unit tests will only detect and alert you to real bugs, and not environmental differences. 272 | 273 | One common mistake that might prevent you from writing repeatable unit tests is relying upon hard-coded information, like server URLs. Your unit tests should not rely on hard-coded server URLs because unit tests must be written in either a sandbox org or in a developer org. Sandbox orgs will always have different URLs than the production orgs will have, and developer orgs will usually have different URLs than the production org will have. If you hard-code the server URLs, the unit tests may fail when you attempt to move your code to production. Another common mistake that might prevent your unit tests from being repeatable is relying upon hard-coded record ids. Record ids are entirely org-specific, and can not be used outside of a given org. Instead of relying upon hard-coded record ids, unit tests should create their own data, as we described in the Set Up All Conditions for Testing section. 274 | 275 | ## Independent 276 | Your unit tests should only test one aspect of your code at a time, so that it is easy to understand the purpose of each unit test. Properly written, and well-decomposed unit tests are an excellent source of documentation. This may mean that you will need to write multiple unit tests in order to fully exercise one method. I’ve shown you one example of this in the Testing Normal Conditions section. 277 | 278 | Also, keep in mind that each of your unit tests must be independent from your other unit tests. Unit tests do not alter the state of the Force.com database, and they are not guaranteed to run in a particular order, so you cannot rely upon one unit test to do the setup work for another unit test. -------------------------------------------------------------------------------- /_pages/architecture-view.md: -------------------------------------------------------------------------------- 1 | - Common and Mastered Objects 2 | - [Deployment Pipeline](/_pages/Deployment-Pipeline.md) 3 | - [Source Code and Configuration Management](/_pages/Source-code-and-configuration-management.md) 4 | - [Tooling](/_pages/Tooling.md) 5 | 6 | -------------------------------------------------------------------------------- /_pages/mission-vision.md: -------------------------------------------------------------------------------- 1 | ###Enterprise Platforms Mission & Vision 2 | 3 | ####Mission 4 | 5 | To enable the success of our business partners in achieving their mission by leveraging the Bureau’s enterprise platforms to deliver comprehensive solutions in a cost-effective, efficient manner 6 | 7 | ####Vision 8 | 9 | Striving to be the Bureau’s leader in business enablement, innovation and delivery excellence -------------------------------------------------------------------------------- /_pages/operations.md: -------------------------------------------------------------------------------- 1 | ![Integrated T&I Project Reviews](/img/PMO-ConOps.png) 2 | 3 | ###Business Application vs. Platform Governance 4 | 5 | Decisions associated with business applications and the platform should be governed by the appropriate governing body with sufficient T&I and/or business line representation. 6 | 7 | ![operations](/img/operations.png) 8 | 9 | ![Meeting Cadence](/img/meeting-cadence.png) -------------------------------------------------------------------------------- /_pages/roles-&-responsibilities.md: -------------------------------------------------------------------------------- 1 | ###Platform Center of Excellence 2 | 3 | ####Objective 4 | 5 | To provide oversight and governance for the Bureau’s standard enterprise platforms. 6 | 7 | ####Roles 8 | 9 | - **COE Chair** – Presides over the Platform Center of Excellence 10 | - **Platform Program Management** – Participants from Enterprise Platforms execution and operational arms support strategic roadmap and prioritization discussions and decisions 11 | - **Architects** – Principal Platform Architect, Solution Architect, Tech Architect, Data Architect - Advise on strategic, technical, and solution architecture; make decisions on application designs and platform release readiness 12 | - **T&I Teams Representatives** – Participants from other T&I teams, such as Data, engage in the COE to ensure collaboration and streamlined downstream integration 13 | - **Business Line Representatives** – Participants from various business divisions, such as CR and SEFL, engage in the COE to ensure platform goals are in alignment with CFPB’s business / mission goals; support decisions that impact individual applications 14 | - **COE Facilitator** – Facilitates COE and SwAG meetings, maintains technical guidelines documents, and COE Templates 15 | 16 | ####Responsibilities 17 | 18 | - Sets and enforces all platform technical standards, guidelines and conventions 19 | - Reviews technical design, solution architecture, and object model for platform products/applications 20 | - Ensures viability of platform architectures and security access model 21 | - Markets and evangelizes the benefits of the Bureau’s enterprise platforms 22 | - Synchronizes business goals with T&I platform priorities 23 | - Collaborates with EA, Data, Cyber Security, PMO and Design & Development Teams 24 | - Drives the Bureau’s Strategic Platform Roadmap 25 | - Reviews new concepts for fit and dispositioning on a particular enterprise platform 26 | - Publishes and manages platform target architectures, incl. common platform objects 27 | 28 | ####Decision Authority 29 | 30 | - Dispositioning of concept requests for fit on particular enterprise platforms 31 | - Technical design approval 32 | - Platform release readiness approval 33 | - Escalation to the CIO for business-impacting concerns 34 | 35 | ####Key Interfaces 36 | 37 | - Engages closely with T&I PMO for gate reviews / approvals 38 | - Regular representation from EA, Data, and Cyber Security to support guidance and decisions 39 | - Interfaces with the business lines to highlight opportunities for business-level decisions (e.g., standardized exam process, common definition of products, etc.) 40 | 41 | ### Platform Program & Services 42 | 43 | ####Objective 44 | 45 | To provide program oversight and consultative platform services to T&I’s business line customers. 46 | 47 | ####Roles 48 | 49 | - **Platform Program Manager** – Oversees platform services and functions offered to customers 50 | - **Platform Project Gov Leads** – Oversee platform-related projects and tasks; interface with business line customers and other T&I team members regularly; CORs for platform contracts; deliver platform procurement services 51 | - **Platform Business Analysts** – Engage with business lines customers to analysis new or enhancement requests to help determine high-level requirements, solution and LOE 52 | 53 | ####Responsibilities 54 | 55 | - Provide platform consulting services: 56 | - **New Solution Review:** Discovery, Project Detail, Fit-Gap Analysis, PMO Project Request Form 57 | - **Planning:** Scope/LOE Definition, Platform-specific acquisition support (SOW, IGCE, etc.), 58 | - **Execution:** Project monitoring and oversight for platform projects, reporting to T&I PMO for gate reviews 59 | - **Adoption:** Develop tailored user on-boarding and adoption strategies 60 | - Manage relationships with Product Owners and Business Executive Sponsors 61 | - Manage platform licensing and emerging needs 62 | - Develop and manage Enterprise Platform Budget and track spending 63 | - Maintain business product backlog 64 | - Manage platform key performance indicators (KPIs) 65 | - Manage resource needs and fulfillment 66 | 67 | ####Key Interfaces 68 | 69 | - Engage with business line customers to validate business requirements and emerging needs 70 | - Present new concepts, requirements analysis and findings at the Platform COE meetings for guidance and approval 71 | - Engage closely with T&I PMO for platform-level business roadmap roll-up to T&I Roadmap 72 | 73 | ###Platform Support Operations 74 | 75 | ####Objectives 76 | 77 | To ensure optimal performance and operations of the Bureau’s enterprise platforms. 78 | 79 | ####Roles 80 | 81 | - **Operations Lead** – Oversees O&M, Release Management, CI, DevOps; approves, holds or rejects releases; reviews and approves Release Management policy and procedural changes 82 | - **Platform Dev Team** - Centralized Agile dev team available for enterprise app dev and platform work 83 | - **O&M Team** – Centralized O&M team with expertise in platform technologies, provide Tier 1 and 2 support for platforms 84 | - **Release Team** – oversees deployment activities and transition from existing App Dev/O&M Teams; executes the physical moves of code and configuration to higher environments, including user acceptance test, integration, staging and production 85 | 86 | ####Responsibilities 87 | 88 | - Maintenance and operations of enterprise platforms, including administration and preventative maintenance, and managing platform-level technical management backlog 89 | - Bug reporting, processing and tracking 90 | - Provide Tier 1 User Support to answer general usability questions (e.g., how to create a report, etc.) 91 | - Set up and maintain version control and continuous integration (CI) infrastructure and process 92 | - Employ a standardized platform release management and environment methodology 93 | - Manage a controlled, efficient pipeline of stand-up, tear-down of various environments for Bureau’s enterprise platforms 94 | - Develop testing strategy 95 | - Establish Change Control Process for enterprise platforms 96 | 97 | ####Key Interfaces 98 | 99 | - Engages closely with T&I Change Control Board for change request notifications, reviews, and approvals 100 | - Work closely with contractor dev teams to plan releases to production 101 | - Regular representation from EA, Data, and Cyber Security to support guidance and decisions 102 | -------------------------------------------------------------------------------- /img/Deployment-Pipeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/Deployment-Pipeline.png -------------------------------------------------------------------------------- /img/Outbound_Change_Set.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/Outbound_Change_Set.png -------------------------------------------------------------------------------- /img/PMO-ConOps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/PMO-ConOps.png -------------------------------------------------------------------------------- /img/SWAGActivities.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/SWAGActivities.png -------------------------------------------------------------------------------- /img/ep_team.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/ep_team.png -------------------------------------------------------------------------------- /img/failed_test.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/failed_test.png -------------------------------------------------------------------------------- /img/group_naming_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/group_naming_example.png -------------------------------------------------------------------------------- /img/group_naming_example_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/group_naming_example_1.png -------------------------------------------------------------------------------- /img/meeting-cadence.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/meeting-cadence.png -------------------------------------------------------------------------------- /img/operations.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/operations.png -------------------------------------------------------------------------------- /img/package.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/package.png -------------------------------------------------------------------------------- /img/passed_test.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/passed_test.png -------------------------------------------------------------------------------- /img/profile_model.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/profile_model.png -------------------------------------------------------------------------------- /img/screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/img/screenshot.png -------------------------------------------------------------------------------- /opensource-checklist.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: base 3 | title: "Open Source Checklist" 4 | --- 5 | 6 | # ✓ Open Source Check List 7 | 8 | Prior to releasing a project to GitHub.com, walk through these items and ensure they are addressed. 9 | 10 | - **Has PII been removed?** 11 | - Use [Clouseau](https://github.com/virtix/clouseau) for scanning source code. 12 | - For an Open Source Release, attach the Clouseau output. 13 | - If there are images, visually inspect each image to ensure there is no CFPB-specific information. 14 | 15 | - **Have security vulnerabilities been remediated?** 16 | - Use the [OWASP Top 10](https://www.owasp.org/index.php/Top_10_2013) 17 | - [National Vulnerability Database](http://nvd.nist.gov/) 18 | - [SANS Swat Checklist](http://www.securingthehuman.org/developer/swat) 19 | 20 | - **Are we including any other open source products? If so, is there any conflict with our public domain release?** 21 | 22 | - **Is our `TERMS.md` included?** 23 | 24 | - **Is a `CHANGELOG.md` present and does it contain structured, consistently formatted recent history?** 25 | - See and 26 | - Some Inspiration: 27 | 28 | - **Are instructions for contributing included (`CONTRIBUTING.md`)?** 29 | 30 | - **Are installation instructions clearly written in the `README` _and_ tested on a clean machine?** 31 | 32 | - **Are all dependencies described in the `README`, `requirements.txt`, and/or `buildout.cfg`?** 33 | 34 | - **Are the API docs generated?** 35 | 36 | - **Are there unit tests?** 37 | 38 | - **If appplicable and possible, is it set up in TravisCI?** 39 | 40 | - **Have multiple people reviewed the code?** 41 | 42 | - **Is there a screenshot in the `README`, if applicable?** 43 | 44 | 45 | ## Copy this version to paste into a GitHub issue with live checkboxes: 46 | 47 | ~~~ 48 | - [ ] **Has PII been removed?** 49 | - Use [Clouseau](https://github.com/virtix/clouseau) for scanning source code. 50 | - If there are images, visually inspect each image to ensure there is no CFPB-specific information. 51 | - [ ] **Have security vulnerabilities been remediated?** 52 | - [ ] **Are we including any other open source products? If so, is there any conflict with our public domain release?** 53 | - [ ] **Is our `TERMS.md` included?** 54 | - [ ] **Is a `CHANGELOG.md` present and does it contain structured, consistently formatted recent history?** 55 | - [ ] **Are instructions for contributing included (`CONTRIBUTING.md`)?** 56 | - [ ] **Are installation instructions clearly written in the `README` _and_ tested on a clean machine?** 57 | - [ ] **Are all dependencies described in the `README`, `requirements.txt`, and/or `buildout.cfg`?** 58 | - [ ] **Are the API docs generated?** 59 | - [ ] **Are there unit tests?** 60 | - [ ] **If applicable and possible, is it set up in TravisCI?** 61 | - [ ] **Have multiple people reviewed the code?** 62 | - [ ] **Is there a screenshot in the `README`, if applicable?** 63 | ~~~ 64 | 65 | ---- 66 | 67 | 68 | ## Take a look at the following projects as good models to follow: 69 | 70 | - [https://github.com/cfpb/qu](https://github.com/cfpb/qu) 71 | - [https://github.com/cfpb/idea-box](https://github.com/cfpb/idea-box) 72 | - [https://github.com/cfpb/hmda-tool](https://github.com/cfpb/hmda-tools) 73 | - [https://github.com/cfpb/django-cache-tools](https://github.com/cfpb/django-cache-tools) 74 | -------------------------------------------------------------------------------- /screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfpb/salesforce-docs/0732a643e46d98ad41ed167515f0e64948a82a8d/screenshot.png --------------------------------------------------------------------------------