Overview
Sites typically have a recruitment website. These websites often have forms for potential volunteers to answer questions about themselves and express interest in volunteering for a study.
ClinSpark exposes an API designed to be used to accept these form submissions into ClinSpark. This document describes:
The capabilities of this integration
Required ClinSpark configuration to support accepting volunteer submissions
Use of the API testing tooling, to support full exploration and testing of the API prior to actual website integration by both the Recruitment Website technical teams
Process Overview
Note that while Foundry Health provides the required APIs that customer website developers use to integrate the website, the integration with your website is fully self serve.
All development of the integration should be done against the customer test instance.
Website Integration Capabilities
Recruitment Website Form Design
In order to support submission of a recruitment website form directly to ClinSpark via the API, the website’s form must align to the API expectations. Data types must match, so that for instance field values which in ClinSpark are numeric, are sent via the API as numeric and not strings. For Custom Volunteer Questions in ClinSpark, the incoming text of the custom question body must match the values of what is expected in the API submission. And so on. Additional examples and demos will be added here over time. Please feel free to open a support ticket to request a review of recruitment website needs and integration considerations specific to your use case.
The look and feel of your website’s recruitment forms can be anything that the designer wants on the website end. Only upon submission do the values from the form need to be populated into the API fields and sent along.
Note that testing with of a variety of user answers is highly recommended. The API catches a range of input errors and returns machine-readable error messages. However in order to provide a user friendly experience for your volunteers using the form, it is advisable to perform these data validations prior to submitting the API call to ClinSpark. This provides the opportunity to present user friendly messages when required fields are missing or data is in the wrong format, etc.
ClinSpark API Exploration using Swagger
The Recruitment API Documentation is built using Open API and can be explored with using Swagger. This provides a rich documentation feature set for the API. It also supports invocation of the client directly from the documentation. Let’s see how this works in practice.
Granting the Website Integrators Appropriate Access
The folks performing the technical integration between ClinSpark and the recruitment website will need sufficient access to a ClinSpark instance to perform the following:
Invoke the ClinSpark API for development, testing and troubleshooting purposes.
View the Volunteer > Inbound submissions in a test environment to ensure that data is properly received in ClinSpark.
Access the ClinSpark documentation, which needs to be accessed from an active ClinSpark session.
We recommend that you create a special role in your test instance for these website integrators which grants access only to API invocation and viewing the Volunteer > Inbound queue:
This is what these users will see in ClinSpark:
This role fulfills the requirements listed and should provide sufficient access to perform the integration.
Viewing API Documentation with Swagger
Note that as documented in the Swagger site, you can easily create straight from Swagger docs custom bindings for the ClinSpark API in your language. So if you are using ruby or python in your website, you can directly export API client bindings in your native language.
Testing Your Form Submissions into ClinSpark
Technical Website Integration
The first step is for the business and website team to design within ClinSpark the required fields to receive the submissions from the website. And test these as shown in the prior videos.
At this point, the website integrators will have a very clear API to call along with working examples. Using their tooling, what remains is to hook into the submission on the website, and write binding code which makes the API call to ClinSpark.
TIP: Adding extra information from the website in the notes field.
The ‘notes’ field in the inbound volunteer screen is designed to give some background information to the recruiter on the request in question. That information does not go to the volunteers profile by default.
A common workaround for this is to create a custom question with type text, and have the API also submit the same text to that custom question. A custom question answer is not displayed by default on the Volunteer > Inbound screen, therefore the same info can be submitted to both fields.
Create a custom question with type ‘text’:
Have your API request submit the same request to both the ‘notes’ field (for the inbound screen) and the ‘custom question’ (to keep the information visiable after the volunteer is added to the volunteer database.
After submitting, the notes will display in the notes field on the Volunteer > Inbound screen…
… and at the custom question in the volunteer profile when added
