| Table of Contents |
|---|
Overview
Sites typically have a recruitment website that contains forms for potential volunteers to answer questions about themselves and express interest in volunteering for a study.
ClinSpark exposes APIs designed to be used to integrate with recruitment websites. One such use case is accepting these form submissions into ClinSpark, but there are others that our APIs can help achieve.
This document describes:
Basic capabilities of a website integration
An overview of ClinSpark configurations needed to support the use case of accepting form submissions
Overview of the API testing tooling, helpful to Recruitment Website technical teams
Process Overview
ClinSpark provides the required APIs that customer website developers use to integrate, enabling technical teams to complete the integration as a self-serve task. IQVIA support team members can assist in the process through inquiries raised in the service desk portal.
| Info |
|---|
All development of the integration should be done against the customer test instance. |
...
Website Integration Capabilities
The following provides a brief demonstration of an integration use case, where a recruitment website sends form submissions for interested volunteers into ClinSpark.
...
Recruitment Website Form Design
In order to support submission of a recruitment website form directly to ClinSpark via API, the website’s form must align to the API expectations. Here are some basic examples:
Data types must match; if a field value in ClinSpark is numeric, requests sent via the API must be 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.
The look and feel of your website’s recruitment forms can be anything that the designer wants on the website front-end. Only upon submission do the values from the form need to be populated into the API fields and sent along.
We recommend that customers perform testing with of a variety of user answers. 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 API documentation is built using Open API standards and can be explored using Swagger. This provides a rich documentation feature set for the API. It also supports invocation of the client directly from the documentation. This is what we recommend customers and technical teams review to learn about the APIs and their capabilities.
More information about learning API functions and Swagger through our documentation site can be reviewed here: https://foundryhealth.atlassian.net/wiki/spaces/DOCS/pages/3700260906/ClinSpark+APIs#Learning-API-Functions
Exploring the Recruit / Recruitment APIs
Currently, ClinSpark supports two APIs to support the needs of website integrations.
For very basic recruitment workflows and integrations, the Recruitment API is recommended.
For sites who wish to explore a broader range of capabilities and workflows, the Recruit API is recommended.
Granting the Website Integrators Appropriate Access
The team performing the technical integration between ClinSpark and the recruitment website will need sufficient access to a ClinSpark test instance. Typically, this involves the following:
Invoking the ClinSpark API for development, testing, and troubleshooting
Viewing the Volunteer > Inbound submissions, to ensure that data is properly received in ClinSpark
For all of our APIs, there basic prerequisites for use which involve ClinSpark account setup and selection of a supported authentication scheme. Those are explained here:
We recommend that customers create a specific role in their test environments for technical teams who are involved with website integrations, which grants them access only to API functions and viewing the Volunteer > Inbound queue. This will ensure they have a basic path into ClinSpark to test out form submissions during development.
...
This is what these users will see in ClinSpark:
...
Viewing Recruitment API Documentation with Swagger
The follow video demonstrates how to review and use the Recruitment API documentation via 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.
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
The following demonstrates how to test form submission workflows into ClinSpark, using the Recruitment API.
...
Technical Website Design and Integration
The business and website teams are expected to collaborate in order to design a workflow that works both between website and ClinSpark. For example, noting in ClinSpark the required fields to receive the submissions from the website, and, testing these as shown in prior videos.
The goal is to ensure the website integrators have a clear understanding to call API functions 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.
Helpful Tip! We suggest adding in ‘extra’ information coming from the website into a 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 however does not continue on and get saved to the volunteer's profile by default.
If customers want to preserve these notes, a common workaround 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 visible 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
...