| Table of Contents |
|---|
Overview
Sites typically have a recruitment website . These websites often have that contains forms for potential volunteers to answer questions about themselves and express interest in volunteering for a study.
ClinSpark exposes an API APIs designed to be used to accept 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:
The Basic capabilities of this a website integration
Required ClinSpark configuration An overview of ClinSpark configurations needed to support the use case of accepting volunteer form submissions
Use Overview of the API testing tooling, to support full exploration and testing of the API prior to actual website integration by both the 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 the 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.
Note We recommend that customers perform 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 Documentationdocumentation is built using Open API standards 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.. 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 folks team performing the technical integration between ClinSpark and the recruitment website will need sufficient access to a ClinSpark instance to perform test instance. Typically, this involves the following:
Invoke Invoking the ClinSpark API for development, testing, and troubleshooting purposes.
View Viewing 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.
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 you customers create a special specific role in your their test instance for these website integrators environments for technical teams who are involved with website integrations, which grants them access only to API invocation 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. So if
If you are using ruby Ruby or python 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 first step is for the business and website team to design within 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 test , and, testing these as shown in the prior videos.
At this point, The goal is to ensure the website integrators will have a very clear API 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 go continue on and get saved to the volunteers volunteer's profile by default.
A 
If customers want to preserve these notes, 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 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
...