-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #323 from AmericaSCORESBayArea/sandbox
README Update (support for both IDEs), Patch Enrollments, Minor Fixes
- Loading branch information
Showing
6 changed files
with
358 additions
and
97 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,132 +1,144 @@ | ||
| # salesforce-data-api 📡 | ||
|
|
||
| Our MuleSoft app is built to interact with Scores data in Salesforce database. It is a RESTful API that allows us to perform CRUD operations on Salesforce objects. We use Code Builder to build the app and CloudHub to deploy it. | ||
| Our core Mulesoft app was built to interact with Scores data in Salesforce database. In a few words, is a RESTful API server that allows us to perform CRUD operations on Salesforce objects. Yet we extend its functionality! | ||
|
|
||
| --- | ||
|
|
||
|  | ||
|  | ||
|  | ||
|
|
||
| [API Documentation](https://anypoint.mulesoft.com/exchange/portals/americascores-bayarea/6c091e72-50d1-49ac-b04d-ee5bb9bc9dbd/salesforce-data-api/minor/3.0/console/summary/) (in review 🚧) | ||
|
|
||
| [Postman Collection](https://github.com/AmericaSCORESBayArea/salesforce-data-api/blob/master/docs/Scores%20-%20Salesforce%20Data%20API.postman_collection.json) (in progress 👨💻) | ||
|
|
||
| [CloudHub Deployment](https://github.com/AmericaSCORESBayArea/salesforce-data-api/blob/master/cloudhub-deployment.md) (outdated 🚧) | ||
| ### 🕺 [Postman Collection (API Documentation)](https://github.com/AmericaSCORESBayArea/salesforce-data-api/blob/master/docs/Scores%20-%20Salesforce%20Data%20API.postman_collection.json) | ||
|
|
||
| --- | ||
| # Development and Testing the app | ||
|
|
||
| For development and testing purposes, we can run the app using MuleSoft Code Builder. | ||
|
|
||
| **MuleSoft Code Builder** is a modern development environment designed to simplify and streamline the process of building and deploying integrations and APIs. It offers both *local* and *cloud-based* versions. | ||
|
|
||
| Below we outline how to use the **cloud-based** version. If you want to setup the environment locally, you can check instructions [here](./docs/local_setup.md) (succesfully tested only on macOS). | ||
| For development and testing purposes, we have 2 IDEs: | ||
| 1) [Anypoint Code Builder](https://www.mulesoft.com/platform/api/anypoint-code-builder) (based on VS Code) | ||
| 2) [Anypoint Studio](https://www.mulesoft.com/platform/studio) (based on Eclipse) | ||
|
|
||
| ## Cloud-based setup | ||
| Code Builder is supposed to replace the Studio IDE, but it is still missing some functionality that would make development simpler. For small fixes, we use Code Builder. For adding new flows or introducing major changes, we use Anypoint Studio. Since anything can be achieved in either IDE, setting up just one should be sufficient. | ||
|
|
||
| ### I. Get your virtual instance | ||
| Note: Code Builder offers both *local* and *cloud-based* versions. | ||
|
|
||
| 1. Create [Anypoint Platform Account](https://anypoint.mulesoft.com/login/). | ||
| 2. Go to [the main dashboard](https://anypoint.mulesoft.com/). | ||
| 3. Under "Anypoint Code Builder", click `Get Started` button. | ||
| 4. Accept the terms and conditions (if you agree). | ||
| 5. Click `Launch` button (if it's greyed out, refresh the page and wait). | ||
| 6. Wait for the environment to get allocated and load. The first time it might take a while. | ||
|
|
||
| ### II. Get the environment ready | ||
|
|
||
| 1. **Clone the repository:** | ||
| 1. Click on the `Source Control` icon on the left sidebar. | ||
| 2. Click on the `Clone Repository` button. | ||
| 3. Select `Clone from GitHub` option (you will need you GitHub account later, so it's a preferred option). | ||
| 4. Choose the repository `AmericaSCORESBayArea/salesforce-data-api`. | ||
| 5. Click `Clone` button. | ||
| 2. **Open the project.** | ||
| 3. **Create `local.properties` file in the `src/main/resources/properties` folder.** | ||
| ## Anypoint Code Builder Setup (based on local version) | ||
|
|
||
| 1. Download [VS Code](https://code.visualstudio.com/) | ||
| 2. Install [Mulesoft Extenssion Pack](https://marketplace.visualstudio.com/items?itemName=salesforce.mule-dx-extension-pack) | ||
| 3. Clone the repository and open the folder | ||
| 4. Create `local.properties` file in the `src/main/resources/properties` folder (reach out to someone from America SCORES to get Sandbox properties): | ||
| ```properties | ||
| http.host=0.0.0.0 | ||
| http.private.port=8091 | ||
| http.listener.host=0.0.0.0 | ||
| http.listener.port=8091 | ||
| fullDomain=0.0.0.0:8091 | ||
|
|
||
| sfdc.user[email protected] | ||
| sfdc.url=https://americascoresbayarea--scoresqa.sandbox.my.salesforce.com/services/Soap/u/48.0 | ||
| api.id= | ||
| keystore.key.password= | ||
| keystore.password= | ||
|
|
||
| sfdc.user= | ||
| sfdc.url= | ||
| sfdc.tkn= | ||
| sfdc.password= | ||
|
|
||
| typeform.clientid=1234 | ||
| typeform.clientsecret=1234 | ||
| typeform.tkn=1234 | ||
|
|
||
| ``` | ||
|
|
||
| Please note: | ||
| - The `sfdc.tkn` and `sfdc.password` fields are sensitive. Please **contact the developers** to get the values. | ||
| - Production and Sandbox Salesforce URLs are different. The URL above is for the Sandbox environment. | ||
| - The `typeform.clientid`, `typeform.clientsecret`, and `typeform.tkn` fields are not used as we are moving away from Typeform. You can leave them as is. | ||
|
|
||
| 3. **Add `-M-Denv=local` to Mule Runtime arguments:** | ||
| 1. Right-click on "Mule" extension (letter M) at the left sidebar. | ||
| 2. Click on the "Settings" icon (gear icon) at the top right corner of the extension window. | ||
| 3. Find "Mule › Runtime: Default Arguments" and add `-M-Denv=local` to the list of arguments: | ||
|
|
||
| `-M-Dmule.forceConsoleLog -M-Dmule.testingMode -M-XX:-UseBiasedLocking -M-Dfile.encoding=UTF-8 -M-XX:+UseG1GC -M-XX:+UseStringDeduplication -M-Dcom.ning.http.client.AsyncHttpClientConfig.useProxyProperties=true -M-Dmule.debugger.test.port=8000 -M-Dmule.debug.enable=true console0 -M-Denv=local` | ||
|
|
||
| 4. **Config Run and Debug settings.** | ||
|
|
||
| 1. Click on the "Run and Debug" icon on the left sidebar. | ||
| 2. Click on `create a launch.json file` link (below the "Run and Debug" button). | ||
| 3. In the "Select debugger", choose "Mule Xml Debugger". | ||
|
|
||
| 5. **Install [Thunder Client extension](https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client).** | ||
|
|
||
| 1. Click on the `Extensions` icon on the left sidebar. | ||
| 2. Search for `Thunder Client` and install it. | ||
|
|
||
| ### III. Run the app | ||
|
|
||
| 1. Click on the "Run" button. | ||
| 2. Verify that the app has started successfully. | ||
| 3. Try the following request using Thunder Client: | ||
|
|
||
| ```http | ||
| GET http://localhost:8091/api-internal/contacts?firstName=John&lastName=Doe | ||
| ``` | ||
| typeform.clientid= | ||
| typeform.clientsecret= | ||
| typeform.tkn= | ||
|
|
||
| Ta-da! You are now running the Mule app in the cloud-based environment. 🚀 | ||
| slack.enabled= | ||
| slack.client_id= | ||
| slack.client_secret= | ||
| ``` | ||
|
|
||
| ## Tips | ||
| 5. Configure Runtime | ||
| - Add `-M-Denv=local` and `-M-Danypoint.platform.gatekeeper=disabled` to [Default Runtime Arguments](https://docs.mulesoft.com/anypoint-code-builder/ref-mule-settings) | ||
| - Select Mule and Java versions | ||
| (click on any xml file in `src/main/mule` -> "Set Versions" button should appear; if not, right-click on any xml file in `src/main/mule` and select `Project Properties`). At the moment, we use Mule 4.6.X and Java 17 | ||
| 6. Install Java seperately (depends on the system, visit https://www.java.com) | ||
| 7. Using terminal, generate the a new key pair (public and private keys) and a self-signed certificate (required for HTTPS, even for local) AND move it to `./src/main/resources` folder: | ||
| ``` | ||
| keytool -genkeypair -keystore keystore.jks \ | ||
| -dname "CN=localhost, OU=Unknown, O=America SCORES Bay Area, L=San Francisco, ST=California, C=US" \ | ||
| -keypass $YOUR_KEYPASS_PASSWORD$ \ | ||
| -storepass $YOUR_STOREPASS_PASSWORD$ \ | ||
| -keyalg RSA \ | ||
| -sigalg SHA256withRSA \ | ||
| -keysize 2048 \ | ||
| -alias mule \ | ||
| -ext SAN=DNS:localhost,IP:127.0.0.1 \ | ||
| -validity 9999 | ||
| mv keystore.jks `/src/main/resources` | ||
| ``` | ||
| 8. Add `$YOUR_KEYPASS_PASSWORD$` and `$YOUR_STOREPASS_PASSWORD$` to the `local.properties` file into `keystore.key.password` and | ||
| `keystore.password` fields | ||
|
|
||
| - The API code is located in `src/main/mule/api` folder. | ||
| - When changing the code, you need to restart the app. Use stop button, then run button. Restart button doesn't work. | ||
| - If anything stops working as expected, you need to reboot the virtual instance: | ||
| 1. Go to [the Anypoint Code Builder dashboard](https://anypoint.mulesoft.com/codebuilder/) | ||
| 2. Select `Manage your IDE` option. | ||
| 3. Click on the `Reboot` button. | ||
| 9. Run the project using VS Code Start button (`Debug Mule Application`). Ta-da! 🚀 | ||
|
|
||
| ### ☁️ What if I want to run a cloud instance? | ||
|
|
||
| ## Build and Deployment | ||
| The local build performed during the run differs from the build performed during the deployment. When running the app locally, `raml` files in local `src/main/resources/api` folder are used. When deploying the app, the `raml` files fetched from the Exchange are used. When building the app for deployment, the `global.xml.anypoint` should be used instead of `global.xml`. (handled by the `local-build.sh` script) | ||
| 1. Create [Anypoint Platform Account](https://anypoint.mulesoft.com/login/) | ||
| 2. Go to [the main dashboard](https://anypoint.mulesoft.com/) | ||
| 3. Under "Anypoint Code Builder", click `Get Started` button | ||
| 4. Accept the terms and conditions (if you agree) | ||
| 5. Click `Launch` button (if it's greyed out, refresh the page and wait) | ||
| 6. Wait for the environment to get allocated and load. The first time it might take a while | ||
|
|
||
| To manually build the app for deployment, you need to execute the `local-build.sh` script. Then, you can manually upload the generated `.jar` file to CloudHub. Make sure the following properties are set in Mule Runtime secrets: | ||
| ## Anypoint Studio Setup | ||
|
|
||
| 1. Download [Anypoint Studio](https://www.mulesoft.com/lp/dl/anypoint-mule-studio) | ||
| 2. Clone the repository and import the folder (`salesfroce-data-api`) WITHOUT copying the content to Studio's workspace | ||
| 3. Create `local.properties` file in the `src/main/resources/properties` folder (reach out to someone from America SCORES to get Sandbox properties): | ||
| ```properties | ||
| anypoint.platform.config.analytics.agent.enabled= | ||
| anypoint.platform.client_id= | ||
| anypoint.platform.client_secret= | ||
| http.listener.host=0.0.0.0 | ||
| http.listener.port=8091 | ||
| fullDomain=0.0.0.0:8091 | ||
|
|
||
| keystore.password= | ||
| api.id= | ||
| keystore.key.password= | ||
| sfdc.password= | ||
| keystore.password= | ||
|
|
||
| sfdc.user= | ||
| sfdc.url= | ||
| sfdc.tkn= | ||
| sfdc.password= | ||
|
|
||
| typeform.clientsecret= | ||
| typeform.clientid= | ||
| typeform.clientsecret= | ||
| typeform.tkn= | ||
|
|
||
| api.id= | ||
| slack.enabled= | ||
| slack.client_id= | ||
| slack.client_secret= | ||
| ``` | ||
|
|
||
| env= | ||
| 5. Configure Runtime | ||
| - Right click on the project and select "Run As" -> "Run Configurations..." | ||
| - Create a new configuration under "Mule Applications" | ||
| - Select the project to launch: `salesforce-data-api` | ||
| - Scroll down, click "Install Runtime" and install `Mule Server 4.6.X`. Once installed and the Studio is restarted (you can trace progress at the right bottom), go back to the menu and select the correct Mule server | ||
| - Click "Apply" | ||
| - Switch to 'Arguments' and add `-M-Denv=local` and `-M-Danypoint.platform.gatekeeper=disabled` to VM arguments | ||
| - Click "Apply" | ||
| - Switch to 'JRE' and make sure that 17+ version is selected | ||
| - Close configurations window | ||
|
|
||
| 6. Install Java seperately (depends on the system, visit https://www.java.com) | ||
| 7. Using terminal, generate the a new key pair (public and private keys) and a self-signed certificate (required for HTTPS, even for local) AND move it to `./src/main/resources` folder: | ||
| ``` | ||
| keytool -genkeypair -keystore keystore.jks \ | ||
| -dname "CN=localhost, OU=Unknown, O=America SCORES Bay Area, L=San Francisco, ST=California, C=US" \ | ||
| -keypass $YOUR_KEYPASS_PASSWORD$ \ | ||
| -storepass $YOUR_STOREPASS_PASSWORD$ \ | ||
| -keyalg RSA \ | ||
| -sigalg SHA256withRSA \ | ||
| -keysize 2048 \ | ||
| -alias mule \ | ||
| -ext SAN=DNS:localhost,IP:127.0.0.1 \ | ||
| -validity 9999 | ||
| mv keystore.jks `/src/main/resources` | ||
| ``` | ||
| 8. Add `$YOUR_KEYPASS_PASSWORD$` and `$YOUR_STOREPASS_PASSWORD$` to the `local.properties` file into `keystore.key.password` and | ||
| `keystore.password` fields | ||
|
|
||
| 9. Run the project using the run or debug buttons. Ta-da! 🚀 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.