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.
Setting up your development environment
Generating the Professor M module loadable packages locally
Continuous integration with Github Actions
How to fix your Sugar instance without starting completely over
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.
Watch the video below for instructions on how to install the scenario. Text-based instructions follow.
- Sugar 11.2 (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_platformsproperty is set tofalseor 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.
- Professor M's install leverages Administration REST API to install Module Loadable Package available on Sugar 11.2 and up
- Note: If you install Sugar using config_si.php, ensure that the
- Postman installed
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.
- 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.
- Login to Sugar as an Administrator
- Navigate to Administration > Module Loader
- Upload sugarcrm-ProfessorM-standard.zip
- Click Install for the ProfessorM package
- Review and accept the license agreement
- Click Commit
- Hint for Windows users: If you receive a warning with the message "Full extraction path exceed MAXPATHLEN (260)...", try the following:
- Download sugarcrm-ProfessorM-windows.zip from the latest release.
- Install the zip as a module loadable package using the steps above.
- Download sugarcrm-ProfessorM-windows-manual-install.zip from the latest release.
- 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/srcdirectory 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). - Open ProfMForWindowsReadme.txt.
- 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.
- 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.
- Hint for Windows users: If you receive a warning with the message "Full extraction path exceed MAXPATHLEN (260)...", try the following:
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.
- Login to Sugar as an Administrator if you have not already done so
- Go to Administration > Display Modules and Subpanels
- 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
- 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
- Click Save
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.
- Save a copy of ProfessorM_PostmanCollection.json
- In Postman, click Import
- Click Choose Files and import ProfessorM_PostmanCollection.json
- Click the gear icon in the upper right corner and select Manage Enviornments
- Click Add
- Input a name for your environment (for example, Professor M)
- Add the following keys and values:
- url:
the url of your Sugar installation for example: http://sugar-web1/sugar - rest_endpoint:
/rest/v11_14 - username:
the username for an admin user in your Sugar installation - password:
the password associated with the username above
- url:
- Click Add
- Close the Manage Environments dialog
- Click Runner
- Select the ProfessorM Sample Data collection
- Ensure the environment you just created is selected
- Click Run ProfessorM S...
- 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.
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.
- Checkout or download a copy of this repo.
- Install PHP 7.
- Install Composer. We use Composer to install the PHP dependencies for the project.
- Execute the following command from your
school/packagedirectory 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.
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.
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.
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.
- Set up your development environment if you have not already done so.
- In a shell, navigate to the
packagedirectory inside of yourschooldirectory. - For standard builds, execute
./pack.php -v versionNameOrNumber - For Windows builds where installing the standard build results in MAXPATHLEN errors,
execute
./pack.php -v versionNameOrNumber -w lengthOfWindowsSugarDirectoryPath
This repository is configured to work with GitHub Actions. Whenever a commit
is pushed to the repository or a Pull Request is made, Github Actions will automatically kick off a build.
When a merge is pushed to master branch a build will kick off to release and tag this version.
You can view the GitHub Actions build results at https://github.com/sugarcrm/school/actions.
You can view the latest build status at the top of this README or just below. Clicking on the build status will open the detailed results in GitHub Actions.
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 GitHub Actions build results for that Pull Request.
You can then click Details to open the build results in Travis CI.
The build has six Environment Variables that have been configured in the secrets section Professor M's school project:
SUGARCRM_USERNAME: The username for an account that has access to the SugarCRM Developer Builds Space and the Sugar StoreSUGARCRM_PASSWORD: The password associated with the above accountGTB_USERNAME: The username for a GitHub account that has access to https://github.com/sugarcrm/unit-testsGTB_PASSWORD: Thetokenassociated with the above accountSUGAR_ENTERPRISE_LICENSE_KEY: Enterprise sugar license key used in our Ent installSUGAR_PROFESSIONAL_LICENSE_KEY: Professional sugar license key used in our Pro install
This project provides 3 different workflows for CI build:
For Sugar Edition's workflows, we have the following jobs:
- Test-PackageGenerator-PHP - tests PackageGenerator in different PHP versions
- Test-PackageGenerator-PHP - tests PackageGenerator in different NodeJS versions
- Pack-Professor-M - packages professor-M in different formats
- Run-Tests-Sugar-Edition - creates sugar environtment in GitHub Actions and executes all tests.
For Professor-M Release, runs only when commit code to master branch:
- Pack-Professor-M - packages professor-M in different formats
- Create-Release - creates a new release and attach professor-m build files to that release
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.
If and when all previous GitHub Actions workflows for Sugar Editions passed, we can merge to master and kickoff the final stage to run to 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 update the brach(s) name in ci-release.yml.
- Add the branch as an option in the deploy section. For example:
on:
push:
branches:
- mybranchname1
- mybranchname2
The build calls two scripts
RunPackUnitTestsAndBuildProfMPackage.sh has three key parts:
- Run the Jasmine tests that test PackageGenerator
- Run the PHPUnit tests that test PackageGenerator
- Build the Professor M Module Loadable Packages using the PackageGenerator
This script relies on Docker images stored on Docker Hub in order to implement the three parts listed above. The sugarcrmdev/school Docker Hub repository stores two images:
- The
yarnimage has all of the dependencies managed by Yarn installed in it. The shell script uses this image to run the Jasmine tests. - The
composerimage has all of the dependencies managed by Composer installed in it. The shell script uses this image to run the PHPUnit tests as well as to generate the Professor M module loadable packages.
This script does NOT test the Module Loadable Package.
The next step is to run SetupEnvAndRunTests.sh. This script 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.
Note: if any step in the process fails (for example, a Jasmine test fails), the remaining steps will not be run.
This repository contains various automated tests. We'll discuss each category of tests below.
To see the results of the tests that are run as part of the GitHub Actions workflow build, open the build in Actions tab. You may see multiple workflows triggered by a commit, it really depends on the conditions and branch.
To see the results of the tests that are run as part of the GitHub Actions workflow build, open the build in Actions tab. You may see multiple workflows triggered by a commit, it really depends on the conditions and branch.
You can see all workflows at once, click and filter by Workflow name and/or search by commit message:
To see detailed workflow results, click on the commit message to expand to the Workflow Summary View.
In the left panel (or in the Matrix card in the main flow), notice that PackageGenerator and Jamsmin tests are executed on multiple PHP/NodeJS versions for compatibility.
By clicking in one of the job names, a list of tasks along with their execution logs is provided (notice checkmark icons are not colored when everything is ok.):
You can scroll through the job log to see the results of the PHPUnit tests.
If the build failed, a variety of things could have caused the failure including a failing PHPUnit test. Just follow the red marks (or 'X' mark)
You can follow workflow executions in realtime:
This repository contains automated PHPUnit and Jasmine tests specifically for testing PackageGenerator. Since PackageGenerator does not require the Sugar code base in order to run, these tests can be executed separate from the Sugar code base.
These tests can be executed manually or as part of a continuous integration build.
PHPUnit is a testing framework for PHP. The PHPUnit test files are located in /tests/phpunit. The /tests/phpunit directory can contain multiple test files, and each test file can contain multiple tests.
To manually execute the tests, you will need to use Composer to install PHPUnit and other PHP dependencies. If you have not installed Composer before, visit the Composer Getting Started Guide.
Execute the following command from your school/package directory in order to install the test dependencies:
composer install
If you need to update the namespaces, manually update composer.json and then run the following command from
your school/package directory:
./composer.phar update
The PHPUnit tests can be executed by running the following command from your school/tests/phpunit directory on macOS:
../../package/vendor/bin/phpunit
or on Windows:
..\..\package\vendor\bin\phpunit
The PHPUnit tests are automatically run as part of the Test PackageGenerator job of the GitHub Actions workflow. For our Sugar Edition Jobs, we will execute in different PHP versions through GA's strategy matrix mechanism. For PackageGenerator's job steps we will:
- Checkout the latest code for the commit that triggered it
- Install PHP version specified in the strategy matrix
- Cache and/or reuse cache for composer packages
- Install dependencies on the build machine by using
composer install - Run the test suite through composer, which uses the following script on composer.json
"scripts": { "test": "phpunit --configuration ../tests/phpunit/phpunit.xml" }``` - Our config indicates that the PHPUnit tests are stored in tests/phpunit.
To see the results of the tests that are run as part of the GitHub Actions workflow build, open the build in Actions tab. You may see multiple workflows triggered by a commit, it really depends on the conditions and branch.
By following the workflow, you will find a Matrix/Card with the tests for PHP and its status:
Jasmine is a testing framework for JavaScript. We have included a very simple Jasmine test in this repository as an example.
The tests are located in /tests/jasmine/specs. Currently, there is one test inside of the DummySpec.js test file. The /tests/jasmine/specs directory can contain multiple test files, and each test file can contain multiple tests.
To manually execute the tests, you will need to install a few different things on your machine before you can run the tests.
Install Yarn which is an NPM compatible package manager. See Yarn Installation Guide for more details on how to install Yarn.
Next navigate to your school directory and then execute the following commands.
Navigate to the tests/jasmine directory.
cd tests/jasmine
Install the JavaScript dependencies using Yarn. These dependencies include Grunt, Jasmine, and Phantomjs.
yarn install
Install the Grunt command line interface globally. See Grunt's Getting Started Guide for more details on installing and using Grunt.
yarn global add grunt-cli
Inside of your tests/jasmine directory, execute the following command to run the Jasmine tests:
grunt test-js
The Jasmine tests are automatically run as part of the Test PackageGenerator job of the GitHub Actions workflow. For our Sugar Edition Jobs, we will execute in different NodeJS versions through GA's strategy matrix mechanism. For PackageGenerator's job steps we will:
- Checkout the latest code for the commit that triggered it
- Setup NodeJS's version specified in the strategy matrix
- Install packages on the build machine by using
yarn install - Run the test suite through yarn, which uses the following script on package.json
"scripts": { "test": "grunt test-js --verbose" }```
To see the results of the tests that are run as part of the GitHub Actions workflow build, open the build in Actions tab. You may see multiple workflows triggered by a commit, it really depends on the conditions and branch.
By following the workflow, you will find a Matrix/Card with the tests for NodeJS and its status:
Many customizations in the Professor M Module Loadable Package require a copy of the Sugar code in order to compile and/or run. Therefore, we will only test the Professor M Module Loadable Package after it has been installed in Sugar.
In this section, we'll discuss how to run the automated tests for the Professor M Module Loadable Package. Since the setup for running the Sugar provided automated tests is so similar, we will discuss how to do that here as well.
Currently, we have PHPUnit tests and Postman tests.
PHPUnit is a testing framework for PHP. The PHPUnit test files are located in package/src/custom/tests/unit-php/School.
There are two primary ways to manually execute the PHPUnit tests. We'll explore both below.
The easiest way to run the PHPUnit tests is to run the same scripts that the automated tests run.
First, you will need to install Docker,
Docker Compose, and Perl.
If the script will be downloading a copy of Sugar from the Sugar Store or the Sugar Developer Builds Community (instead
of using a copy of Sugar stored on your machine), you will also need a package installed that can execute the sha1sum
command. On a Mac, you can install md5sha1sum by executing brew install md5sha1sum in a shell.
Then execute SetupEnvAndRunTests.sh. Note that the Sugar provided unit
tests are NOT run as part of SetupEnvAndRunTests.sh. If you want to add
them, add the following line after the call to SetupSugarPHPUnitTests.sh:
./RunSugarPHPUnitTests.sh $sugarDirectory || exit 1
If you are actively developing the Professor M Module Loadable Package, you will most likely want to run the unit tests as you are working and making updates to the code.
In order to manually execute the tests, you will need a running copy of Sugar that has been installed with no sample data. See Getting Started with Sugar Development for instructions on setting up a development environment.
You will also need to get a copy of the Sugar provided unit tests and put them in your Sugar source code directory. See the SugarCRM unit tests GitHub repo for more information.
Prepare to run the Sugar provided PHPUnit tests and the Professor M PHPUnit tests by executing the following commands:
$ cd /path/to/sugar_source_dir
$ composer install
$ cd tests/unit-php
$ chmod +x ../../vendor/bin/phpunit
Run the Sugar provided unit tests by executing the following command from the tests/unit-php directory:
$ ../../vendor/bin/phpunit
Install the standard version of the Professor M Module Loadable Package using Module Loader if you have not already done so. The code for Professor M and the associated tests will be installed in to the Sugar source directory.
Run the Professor M PHPUnit tests by executing the following command from the tests/unit-php directory:
$ ../../vendor/bin/phpunit --testsuite custom
The PHPUnit tests that test the Professor M Module Loadable Package are automatically run as part of the Run-Tests-Sugar-Edition job of the GitHub Actions workflow.
Each job in this stage is basically the same with the exception of the environment variables. Each job calls SetupEnvAndRunTests.sh, which executes the Professor M PHPUnit tests.
Note that the Sugar provided unit tests are NOT run as part of
SetupEnvAndRunTests.sh. If you want to add
them, add the following line after the call to SetupSugarPHPUnitTests.sh:
./RunSugarPHPUnitTests.sh $sugarDirectory || exit 1
Postman is an API development environment. We use Postman Collections to insert our sample data into Sugar via the REST API. Each API call in the collections has one or more associated tests to ensure the calls were successful.
The Postman Collections can be run via the Postman application as described above or the command line using Newman.
As an alternative, and as for this project, on version 11.2, Sugar has introduced a Rest API for uploading and installing Module Loadable Packages.
To upload and install the Professor M Module Loadable Package by executing the following command from the scripts directory (as an assumption, it runs on a docker as part of the build):
$ ./InstallProfessorMPackage.sh $stackVersion || exit 1
You can execute the tests against any running instance of Sugar. Note that the Postman tests will NOT be installed
as part of the Professor M module loadable package. The tests will only be available in your school repo.
The first step is to configure the Postman Environment for your particular instance of Sugar. Open ProfessorM_PostmanEnvironment and update the url, username, password, and rest_endpoint to reflect your instance.
Then you can choose to install Newman to execute the tests or use a Docker image to execute the tests.
Install Node.js if you haven't already.
Install Newman by executing the following:
npm install -g newman
Navigate to the school/data directory in your shell. Execute the tests by running the following:
newman run ProfessorM_PostmanCollection.json -e ProfessorM_PostmanEnvironment.json
You can execute the tests that leverage Advanced Workflow (only available in Enterprise and Ultimate editions of Sugar) by running the following:
newman run ProfessorM_PostmanCollection_AdvancedWorkflow.json -e ProfessorM_PostmanEnvironment.json
Install Docker if you haven't already.
Pull the Newman Docker container that we will use to run the tests by executing the following:
docker pull postman/newman_ubuntu1404
Execute the tests by running the following:
docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection.json" --environment="ProfessorM_PostmanEnvironment.json"
Be sure to replace pathToTheDataDirectoryInYourSchoolRepo with the path to the data directory in your school repo.
You can execute the tests that leverage Advanced Workflow (only available in Enterprise and Ultimate editions of Sugar) by running the following:
docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection_AdvancedWorkflow.json" --environment="ProfessorM_PostmanEnvironment.json"
Hint: If your instance of Sugar is running inside a Docker container, you may need to add the --net="host" option:
docker run -v pathToTheDataDirectoryInYourSchoolRepo:/etc/newman --net="host" -t postman/newman_ubuntu1404 run "ProfessorM_PostmanCollection.json" --environment="ProfessorM_PostmanEnvironment.json"
The Postman tests are automatically run as part of the Run Tests stage of the GitHub Actions workflow.
Each job is basically the same with the exception of the environment variables. Each job calls SetupEnvAndRunTests.sh, which executes the Postman tests.
As you customize this instance, you may do something like accidentally write broken code that seems to break your Sugar instance. Try running Quick Repair and Rebuild:
- Log in as an administrator.
- Click your profile picture in the upper-right corner and select Administration.
- In the System section, click Repair.
- Click Quick Repair and Rebuild.
If you become unable to login to your Sugar instance or running Quick Repair does not work, try the following:
- Remove the custom code that is causing problems.
- Delete the contents of the
cachedirectory. - Use a program like MySQL Workbench to truncate the
metadata_cachetable. - Access your Sugar instance in a browser. If you still receive an error, reload the page.
If the above steps do not fix your problem, you may need to start over. Delete your Sugar root directory and follow the steps in the Installation Instructions above.