Knack Tutoring is a unique peer-tutoring platform used by colleges and universities across the US. Students can find tutors who attend their specific school and excelled in the exact courses they are enrolled in. Dozens of higher ed institutions rely on Knack to handle their tutoring needs, and with that comes the need to share student tutoring data with college administrators in ways that are most convenient for them.
\nAt Knack we partner with schools all over the US with student populations ranging from the hundreds to tens of thousands. Schools such as University of Florida and Auburn University have already found that students using Knack are 10% more likely to pass courses. When schools deploy Knack, it is important that they retain sight on how often students are using Knack tutoring services.
\nMany of our partners use Salesforce. Salesforce has an Education Data Architecture (EDA) extension that schools implement to allow them to securely and privately upload and share course catalogs, student enrollment data, and more. Many schools also utilize the Student Success Hub for Higher Education (formerly Advisor Link) for advising. We decided to build an integration to allow us to sync tutoring session data nightly with our partners’ Salesforce instances.
\nOur Laravel backend integrates with our Salesforce package to transfer tutoring session data from the Knack database to our partners’ Salesforce instances. We use several Salesforce API endpoints to GET and POST data to our partners’ instance. This way their administrators are able to access Knack tutoring data directly from the Salesforce instance instead of needing to log into Knack specifically to view tutoring data. Among other things, this integration empowers administrators to encourage specific students to seek out tutoring and allows them to see which courses at their institution require the most student tutoring.
\nThe different types of Salesforce packages can be read about here, but for brevity I am just going to share that we decided to use Clicks Not Code to create a managed package containing a Connected app as one of its components. A Connected app is the type of Salesforce component that allows an external application (Knack) to securely integrate with a Salesforce instance via APIs. It is important to note that our entire solution is called a package, and one of many components in our package is the Connected app which is used for authentication when using an API. This led to confusion for us early on because the AppExchange is used to download packages, which can optionally contain a component called a Connected app.
\nOur Salesforce package is made up of Custom Objects, their related Fields, a Tab, Page Layouts, and the previously described Connected app, which are some of the many types of components that can be present in a Salesforce package. It is also a hard requirement that anyone installing the Knack Salesforce package already has the previously described Education Data Architecture extension installed on their Salesforce instance.
\nA view of some of the custom components that are in our Salesforce package
\nCustom Objects are created and updated using the Object Manager, which can be found by clicking the gear in the top right corner of your Salesforce instance, clicking “Setup”, and searching “Object Manager” in the Quick Find search bar on the far left of your screen. Once you are in Object Manager click the “Create” button and then Custom Object.
\nLocating the Object Manager
\nOur custom objects mirror our Laravel models, so we created a custom object called “Tutoring Session” that mirrors what is called a Session model in our codebase and another called “Student Tutoring Session” which mirrors our internal UserSession model. The former stores all of the data related to the tutoring session, and the latter stores data related to each individual student involved in a tutoring session. These objects have a many-to-one relationship because multiple students can participate in one group tutoring session.
Student Tutoring Session custom object requires unique external ID field so that we can perform API lookups (more on that later)
\nCustom Tabs allow Salesforce users to view data related to custom objects. To add a new custom tab go to “Setup” and in the Quick Find box search for “Tabs”. Once you are in Tabs click “new” and select your custom object and the styling that you want to appear on your custom tab. On step 2 of 3 we chose to apply one tab visibility to all profiles but your individual needs may vary. The final step requires you to choose the packages you want the custom tab to appear on, and for us the EDA package was the only selection.
\nLike most companies, we hold private data, which means that we have to be careful to only present data to the intended partner. We also have to make sure all data is encrypted and secure while in transit. We created a Connected app because (like mentioned previously) that is the component that is required in our package so that we can securely use the Salesforce API when uploading data to our partner’s Salesforce instances. To create a Connected app go to “Setup” and search “App Manager”. Once in App Manager click “New Connected App” in the top right. Your connected app API Name will need to be universally unique to all of Salesforce, so if you are building a prototype application you might not want to use the API Name you want to have for your final application, because it will never become available again even if you delete your prototype. After you create your Connected app go back to App Manager, find your app, find the arrow to the far right, and click “edit”. This is where you will enable OAuth, use a digital signature, and upload a certificate. The OAuth scope needs to include This is what our OAuth settings and scope look like after we are finished editing our Connected App component Now that we have custom objects to store our data, custom tabs to present our data to end users, and a Connected app to give our Laravel instance API access to Salesforce we are ready to package up our solution. Go to Setup and search “Package Manager”. Click “new”, name your new package, and click “save”. While viewing your package’s detail page you can click “Add” to add your custom objects, custom tabs, and Connected app. Choose your component type (Custom Object, tab, etc) and add it to your package. Repeat this process until you have your Custom Objects, Tabs, Connected app, and anything else you might require for your custom Salesforce app. Once we have all of our desired components it is time to upload our package. While viewing your package click “upload” and give your package a version name and number. If you are in a test state or you are still going to be making changes to your package then it is imperative that you not mark your package as “Managed - Released”. You must mark your package as “Managed - Released” before you can release it on the AppExchange, but once you do that you lose a lot of abilities when it comes to editing your package, so it is ideal to put that off as long as possible. Steps 1, 2, and 4 of the Knack-Salesforce Data Delivery flow are simply requesting the Salesforce ID of objects so that we can use those IDs to build POST requests for steps 3 and 5. Once the app is installed we can run a connectivity test. We just need the integration user’s email, the external ID fields for the Contact and Course objects in the target Salesforce instance, and a client ID and private key that never change. Then we go to Knack’s internal admin (Laravel Nova), click Test Connectivity, and voilà!\n Operators can run a connectivity test and receive more verbose output than \"Failure\" All we need to do is receive a bearer token and we know that we have a successful connection, so if we get a good response from All actions described in this blogpost use the Laravel Actions library, which we highly recommend Now that we know that we have a successful connection we can run a full sync or partial sync of a partner’s Tutoring Session data. Once again we rely on our implementation of Laravel Nova, this time using the Full Sync action. We select a start date and the sync upserts all “Tutor Session” and “Student Tutor Session” records to Salesforce, as long as the object’s Full and partial sync options are available After the sync is complete we can check our Salesforce instance for the data. New records should be added as Tutoring Session and Student Tutoring Session custom objects. Existing records that were updated in Knack since the most recent sync will also be updated so that all data in Salesforce matches what is in our database for an organization. We can use our custom tab to view our data in Salesforce, and depending on the cron string that is set in the partner’s Data Delivery Destination a Salesforce instance could be updated as often as every hour.\n Tutoring Sessions have now been synced to SalesforceData Security
\nrefresh_token and api. This part of the process is what handles authorization so that our Laravel app can securely communicate with any Salesforce instance that has our package installed.Packaging our Solution
\nTesting Connectivity
\nRetrieveSalesforceBearerToken we know our ping was successful. As you can see in the code snippet below, we check for all config key/values, check the connector type, and meaningfully alert our Operations team if there are any errors:class TestConnectivity\n{\n use AsAction;\n\n /**\n * Execute the command.\n */\n public function handle(DataDeliveryDestination $dataDeliveryDestination): array|string\n {\n if ($dataDeliveryDestination->listMissingConfigKeys()) {\n return Action::danger('A Configuration Key is missing or misspelled.');\n }\n\n if (DataDeliveryDestinationType::SALESFORCE === $dataDeliveryDestination->connector_type) {\n $bearerTokenResponse = RetrieveSalesforceBearerToken::make()->handle($dataDeliveryDestination);\n\n if ($bearerTokenResponse->status() === 200) {\n return Action::message('Salesforce Connectivity Test Successful');\n }\n\n return Action::danger('A Configuration Value is incorrect');\n } elseif (DataDeliveryDestinationType::CSV === $dataDeliveryDestination->connector_type) {\n return Action::danger('Full sync not available for CSV Data Delivery');\n }\n\n return Action::danger('Unknown connector type');\n }\n}Putting the Knack Salesforce app to use
\nSyncing Data
\nupdated_at value is more recent than the specified time.\n