sugarcrmdev/school repository overview

⁠Professor M's School for Gifted Coders

Professor M's School for Gifted Coders is a module loadable package that can be installed in Sugar. The following sections explain more about the scenario and how to install the package and sample data.

⁠Contents

About the scenario⁠

Installation instructions⁠

Setting up your development environment⁠

Contribute to this project⁠

Generating the Professor M module loadable packages locally⁠

Continuous integration with Travis CI⁠

Continuous integration with Jenkins⁠

Automated tests⁠

How to fix your Sugar instance without starting completely over⁠

⁠About the scenario

Professor M aka Professor Marum has created an exclusive not-for-profit school for gifted coders.

Learn more about the implemented Use Cases⁠ in the docs⁠.

Want a quick summary? Watch the video below.

⁠Installation instructions

Watch the video below for instructions on how to install the scenario. Text-based instructions follow.

⁠Prerequisites

• Sugar 7.9.1.0 (or newer) installed with NO sample data. See Getting Started with Sugar Development⁠ for help.
  • Note: If you install Sugar using config_si.php, ensure that the disable_unknown_platforms property is set to false or is not in the file.
  • Note for Windows users: Make the path to your Sugar instance as short as possible to avoid errors of file paths being too long.
• Postman⁠ installed

⁠Install the modules and customizations

We've created a custom package you can install. The package will create and customize the modules you'll need for the scenario. The following instructions will walk you throw how to install the package.

1. Download the appropriate zip file from the latest release⁠. If you are installing in Sugar Cloud, you will need to select the production version of the release. If you are installing elsewhere, you can select the production release or the standard release. The standard release includes automated testing files while the production release does not.
2. Login to Sugar as an Administrator
3. Navigate to Administration > Module Loader
4. Upload sugarcrm-ProfessorM-standard.zip
5. Click Install for the ProfessorM package
6. Review and accept the license agreement
7. Click Commit

   • Hint for Windows users: If you receive a warning with the message "Full extraction path exceed MAXPATHLEN (260)...", try the following:

     1. Download sugarcrm-ProfessorM-windows.zip from the latest release⁠.
     2. Install the zip as a module loadable package using the steps above.
     3. Download sugarcrm-ProfessorM-windows-manual-install.zip from the latest release⁠.
     4. Unzip the file. Note that you'll find ProfMForWindowsReadme.txt and a set of directories inside of the zip. If no directories are inside the zip, then all file paths in the package/src directory have been deemed short enough to be included in a typical Windows installation and you will need to generate the zips yourself locally on your own machine (see Generating the Professor M module loadable packages locally⁠ for instructions on how to do so).
     5. Open ProfMForWindowsReadme.txt.
     6. Follow the instructions inside of the readme to manually copy the files from the zip to your Sugar instance. You may need to create directories in your Sugar directory if they do not already exist.
     7. Navigate to Administration > Repair > Quick Repair and Rebuild.

   • If the above installation still fails due to a MAXPATHLEN error, we recommend generating the zips yourself locally on your own machine. See Generating the Professor M module loadable packages locally⁠ for instructions on how to do so.

⁠Customize the modules that are displayed

Sugar will display many modules by default that you will not be using while working on the tutorials. To make things simpler, we'll hide the modules that won't be used and rearrange the modules that are displayed.

1. Login to Sugar as an Administrator if you have not already done so
2. Go to Administration > Display Modules and Subpanels
3. Drag the following modules from the Displayed Modules box to the Hidden Modules box:
   • Calendar
   • Calls
   • Meetings
   • Tasks
   • Notes
   • Emails
   • Targets
   • Target Lists
   • Forecasts
   • Documents
   • Cases
   • Tags
4. Rearrange the items in the Displayed Modules box so they are in the following order from top to bottom:
   • Accounts
   • Leads
   • Contacts
   • Professors
   • Opportunities
   • Revenue Line Items
   • Quotes
   • Reports
   • Campaigns
   • Process Email Templates
   • Process Definitions
   • Process Business Rules
   • Processes
5. Click Save

⁠Use the Sugar REST API to create the Professor M sample data

In order to create the Professor M sample data, you'll use Postman to run a collection of Sugar REST API calls. Each call in the collection has one or more simple tests associated with it to ensure the call was successful.

1. Save a copy of ProfessorM_PostmanCollection.json⁠
2. In Postman, click Import
3. Click Choose Files and import ProfessorM_PostmanCollection.json
4. Click the gear icon in the upper right corner and select Manage Enviornments
5. Click Add
6. Input a name for your environment (for example, Professor M)
7. Add the following keys and values:
   • url: the url of your Sugar installation (for example, http://localhost:8888/profm⁠)
   • rest_endpoint: /rest/v10
   • username: the username for an admin user in your Sugar installation
   • password: the password associated with the username above
8. Click Add
9. Close the Manage Environments dialog
10. Click Runner
11. Select the ProfessorM Sample Data collection
12. Ensure the environment you just created is selected
13. Click Run ProfessorM S...
14. Wait for the collection to finish running. All tests should pass. Hint: If you see many failures, you may have forgotten to install the Professor M module loadable package. See the instructions in previous section for how to do the install.

If you are using an Enterprise or Ultimate edition of Sugar, you can use the features that leverage Advanced Workflow. Save a copy of ProfessorM_PostmanCollection_AdvancedWorkflow.json⁠ and (https://raw.githubusercontent.com/sugarcrm/school/master/data/Application_Routing.bpm⁠) to your local filesystem. Update the reference to Application_Routing.bpm in ProfessorM_PostmanCollection_AdvancedWorkflow.json to point to your local filesystem location for that file. Then follow the steps above to import the collection and run it.

⁠Setting up your development environment

If you want to generate the Professor M module loadable packages yourself or make changes to the code in this repo, you will need to set up a development environment. You do NOT need to set up a development environment if you simply want to install the Professor M scenario as-is in your Sugar instance.

1. Checkout or download a copy of this repo.
2. Install PHP 7⁠.
3. Install Composer⁠. We use Composer to install the PHP dependencies for the project.
4. Execute the following command from your school/package directory in order to install the dependencies:

composer install

You may also want to set up your development environment so you can execute the unit tests. See Automated tests⁠ for more information.

⁠Contribute to this project

Professor M's School is open source⁠, and we would love for you to get involved! Below are some ways you can contribute to this project:

• Get notifications about this repo by clicking the Watch button at the top of this repo⁠.
• Explore the code and use it as a resource as you develop your integrations and customizations.
• Create a new Issue⁠ if you have ideas for improvement, a feature request, or a bug report.
• Assign yourself an Issue, update the code, and create a pull request. See CONTRIBUTING.MD⁠ for more details.

⁠ZenHub

We utilize ZenHub to organize our backlog and track our Issues. You can view our ZenHub board inside the GitHub web interface if you have a ZenHub browser extension⁠ installed. You can also view our ZenHub board at https://app.zenhub.com/workspace/o/sugarcrm/school/boards?repos=109023666⁠.

When viewing our ZenHub board, you can view our prioritized backlog as well which stories are currently in progress, blocked, under review, and closed.

⁠Generating the Professor M module loadable packages locally

The Professor M module loadable packages can be found on the Releases⁠ page of this GitHub repo. You may want to generate the module loadable packages yourself if you are a Windows user with a long Sugar directory path or if you want to make changes to the package.

1. Set up your development environment⁠ if you have not already done so.
2. In a shell, navigate to the package directory inside of your school directory.
3. For standard builds, execute ./pack.php -v versionNameOrNumber
4. For Windows builds where installing the standard build results in MAXPATHLEN errors, execute ./pack.php -v versionNameOrNumber -w lengthOfWindowsSugarDirectoryPath

⁠Continuous integration with Travis CI

This repository is configured to work with Travis CI⁠. Whenever a commit is pushed to the repository or a Pull Request is made, Travis CI will automatically kick off a build.

⁠Viewing results in Travis CI

You can view the Travis CI build results at https://travis-ci.org/sugarcrm/school⁠.

⁠Viewing results in GitHub

You can view the latest build status at the top of this README ().
Clicking on the build status will open the detailed results in Travis CI.

You can also view build results in Pull Requests. Toward the bottom of each Pull Request, you can click "Show all checks" to see the Travis CI build results for that Pull Request.

You can then click Details to open the build results in Travis CI.

⁠About the build

The build has four Environment Variables that have been configured in the project settings in Travis CI:

• SUGARCRM_USERNAME: The username for an account that has access to the SugarCRM Developer Builds Space⁠ and the Sugar Store⁠
• SUGARCRM_PASSWORD: The password associated with the above account
• GITHUB_USERNAME: The username for a GitHub account that has access to https://github.com/sugarcrm/unit-tests⁠
• GITHUB_PASSWORD: The password associated with the above account

The build is configured in .travis.yml⁠. Currently, the build has three stages:

• Test PackageGenerator
• Run Tests
• Build & Post on GitHub

All of the jobs in each stage must pass before the jobs in the following stage will begin.

The Test PackageGenerator stage is run first and has two jobs:

• Execute the PHPUnit tests associated with the PackageGenerator (see PHPUnit tests for PackageGenerator⁠ for details).
• Execute the Jasmine tests associated with the PackageGenerator (see Jasmine tests for PackageGenerator⁠ for details). The PackageGenerator is responsible for creating the Professor M Module Loadable Package. This stage ensures that the PackageGenerator is functioning as we expect that it would. This stage does NOT test the Module Loadable Package.

The next stage to run is the Run Tests stage. Each job in this stage deploys Sugar, installs the Professor M Module Loadable Package, runs the setup for the PHPUnit tests that Sugar provides, runs the PHPUnit tests written specifically for our Professor M Module Loadable Package, and runs the Postman tests. Each job in this stage is run against a different combination of Sugar versions and editions. See PHPUnit tests for the Professor M Module Loadable Package⁠ for details.

The final stage to run is the Build & Post on GitHub stage. Note that this stage is only run when the branch is Master. This stage executes the pack.php script to generate the Professor M Module Loadable Packages as zips. The zips will be automatically posted to GitHub: https://github.com/sugarcrm/school/releases⁠.

If you want the Build & Post on GitHub stage to be kicked off for a branch other than master, you should do both of the following in .travis.yml⁠.

• Remove the "if: branch = master" in the stages section
• Add the branch as an option in the deploy section. For example:

    deploy:
      provider: releases
      file: releases/sugarcrm-ProfessorM-latest.zip
      api_key:
          secure: mykey
      skip_cleanup: true
      on:
        branch: mybranchname

⁠Continuous integration with Jenkins

This repository can be configured for continuous integration with Jenkins⁠. Jenkins can be configured so that whenever a commit is pushed to the repository or at certain time intervals, Jenkins will automatically kick off a build.

⁠Installing Jenkins

Before beginning, you'll need to set up your own installation of Jenkins. Check out the Jenkins Installation Guide⁠ for more details.

To help you get started, we have provided PrepareJenkinsDockerContainer.sh⁠ that you can run to start Jenkins inside of a Docker container. The machine or container where Jenkins is running will need to have Docker Compose⁠ and Perl⁠ installed. PrepareJenkinsDockerContainer.sh⁠ will take care of installing both for you. If you use PrepareJenkinsDockerContainer.sh⁠, you should be able to access Jenkins at http://localhost:8080⁠.

We recommend installing the Jenkins suggested plugins. You will also need to install the EnvInject Plugin⁠.

⁠Storing Credentials in Jenkins

The build you will create in Jenkins needs access to credentials and configurations. We will store these using Jenkins Credentials.

The instructions below will walk you through how to create the necessary credentials and configurations. For more information on how to store credentials in Jenkins, see Credentials Binding Plugin⁠.

1. On the Jenkins dashboard, click Credentials. (If you do not see the Credentials option, you may need to install the Credentials Binding Plugin.)
2. Create new global credentials for the GitHub account that has access to the SugarCRM Unit Tests repo⁠.
   1. Kind: Username with password
   2. Scope: Global
   3. Username: your GitHub username
   4. Password: your GitHub password
   5. ID: GITHUB_SUGARCRM_UNIT_TESTS
   6. Description: GitHub account that has access to https://github.com/sugarcrm/unit-tests⁠
3. Create new global credentials for the account that has access to the SugarCRM Developer Builds Space⁠ and the Sugar Store⁠.
   1. Kind: Username with password
   2. Scope: Global
   3. Username: your SugarCRM username
   4. Password: your SugarCRM password
   5. ID: SUGARCRM_ACCOUNT
   6. Description: SugarCRM Account
4. Create a new global secret for the Sugar license key.
   1. Kind: Secret text
   2. Scope: Global
   3. Secret: Your Sugar license key. This secret is used by InstallSugarAndProfM.sh⁠.
   4. ID: SUGAR_LICENSE_KEY
   5. Description: The Sugar license key

⁠Creating a Jenkins project

Now you're ready to create a new project in Jenkins that will build the school project.

1. On the Jenkins dashboard, click New Item.

2. Name your new item something like ProfessorM.

3. Select Freestyle project and click OK. The item configuration page will display.

4. In the Source Code Management section, select Git.

5. Input your Repository URL (for example, https://github.com/sugarcrm/school) and select the GitHub credentials you created in the previous section.

6. Configure the Build Triggers section as you'd like. If you do not want to configure this now, you can skip this step and manually trigger the builds instead.

7. In the Build Environment section, select the Delete workspace before build starts option and the Use secret text(s) or file(s) option.

8. In the Bindings section, select Add > Username and password (separated). Then input the following:

   1. Username Variable: GITHUB_USERNAME
   2. Password Variable: GITHUB_PASSWORD
   3. Credentials: Specific credentials
   4. Select the GITHUB_SUGARCRM_UNIT_TESTS credentials.

9. In the Bindings section, select Add > Username and password (separated). Then input the following:

   1. Username Variable: SUGARCRM_USERNAME
   2. Password Variable: SUGARCRM_PASSWORD
   3. Credentials: Specific credentials
   4. Select the SUGARCRM_ACCOUNT credentials.

10. In the Bindings section, select Add > Secret text. Then input the following:

    1. Variable: SUGAR_LICENSE_KEY
    2. Credentials: Specific credentials
    3. Select the SUGAR_LICENSE_KEY secret text.

11. In the Bindings section, select the Inject environment variables to the build process checkbox. If you do not see this checkbox, you may need to install the EnvInject Plugin⁠. Then...

    1. In the Properties Content input box, add a line for the WORKSPACE_PATH variable. This path represents the path to the workspace for your Jenkins job on the host machine. For example, if your Jenkins home directory is /Users/lschaefer/jenkins and your Jenkins project is named ProfessorM, you would input the following: WORKSPACE_PATH=/Users/lschaefer/jenkins/workspace/ProfessorM
    2. In the Properties Content input box, add a line for the PATH_TO_SUGAR_DOCKER_ON_HOST variable. This variable represents the path to Sugar Docker on the host machine. If you want to use the default location, input the following: PATH_TO_SUGAR_DOCKER_ON_HOST=$WORKSPACE_PATH/scripts/workspace/sugardocker If you want to customize where Sugar Docker is stored, you can update this variable to reflect that.

12. In the Build section, click Add build step and select Execute shell.

13. In the Command box that appears, input the following:

    # The Sugar version you want to test
    SUGAR_VERSION="7.11"
    
    # The Sugar Edition you want to test. Options: Pro, Ent, and Ult
    SUGAR_EDITION="Ent"
    
    # Path to where the Sugar Docker directory should be stored. If you do not have a preference, leave this as is.
    SUGAR_DOCKER_DIRECTORY="workspace/sugardocker"
    
    # This variable is completely optional.  If you want to store the Sugar source zips on your local machine instead
    # of downloading them from the SugarCRM Developer Builds space or Sugar Store, input the path to where the Sugar 
    # source zips are stored. For example: /var/sugardocker/data/app/sugar_source_zips. Note that your Sugar source zips 
    # MUST follow this naming convention: Sugar$sugarEdition-$sugarVersion.zip (for example: SugarEnt-7.11.zip).
    # SUGAR_SOURCE_ZIPS_DIRECTORY=""
     
    cd scripts
     
    bash -ex RunPackUnitTestsAndBuildProfMPackage.sh $SUGAR_WORKSPACE_PATH
     
    bash SetupEnvAndRunTests.sh $SUGARCRM_USERNAME $SUGARCRM_PASSWORD $SUGAR_VERSION $SUGAR_EDITION $GITHUB_USERNAME $GITHUB_PASSWORD $SUGAR_DOCKER_DIRECTORY $SUGAR_SOURCE_ZIPS_DIRECTORY
    

    Copy

    Be sure to update the variables appropriately.

14. In the Post-build Actions section, click Add post-build action and select Archive the artifacts.

15. In the Files to archive box that appears, input the following: package/releases/*.zip

16. Click Save.

⁠Running a build and viewing the results

Once you have your Jenkins project created, it's time to see if it works!

Navigate to your ProfessorM project in Jenkins. Trigger your build manually by clicking Build Now.

View the Build History panel to quickly browse the build results. If you see a blue dot, you know all of the tests passed!

Click on a build to view more details. If the build passed, the Professor M module loadable packages will be stored as build artifacts.

To see more details on a build, click Console Output. If any step in the process fails (for example, a Jasmine test fails), the remaining steps will not be run. If everything succeeds, you'll be able to find the Jasmine test results for PackageGenerator, the PHPUnit test results for PackageGenerator, the PHPUnit test results for Sugar, the PHPUnit tests for the Professor M Module Loadable Package, and the results of the Professor M module loadable packages being generated, copied, and archived.

Jasmine results for PackageGenerator:

PHPUnit results for PackageGenerator:

PHPUnit results for the Professor M Module Loadable Package:

Postman test results:

Professor M package results:

Tip: If you see errors in the Console Output about git not being found, you may need to update your Jenkins configuration. On the Jenkins dashboard, click Manage Jenkins. Click Conifgure System. In the Global Properties section, enable the Tool Locations checkbox. In the Name box, select (Git) Default. In the Home box, input the path to the Git installation (for example, /usr/bin/git). Click Save.

Tip for those running Jenkins in Docker: If you see errors in the Console Output similar to 'Fatal error: Unable to find local grunt', you may need to update your Jenkins job. The likely cause is that your $SUGAR_WORKSPACE_PATH is not pointing to the path of the workspace that is storing the school repo's files that are being pulled out of GitHub. You can diagnose if this is the issue by adding docker exec my-yarn pwd and `docker exec my-yarn ls