Transcription
Wonderlic Data Exchange API 2013, 2017 Wonderlic, Inc.www.wonderlic.com 800.323.3742
Wonderlic Data Exchange APITable of ContentsIntroduction. 5Who is Wonderlic?. 5What is Wonderlic Online?. 5What is Wonderlic Data Exchange?. 5What needs to be built?. 6In the simplest terms . 7Testing the Integration. 7Add Candidates and Launch Tests. 8The Process. 8On-site Testing. 8Off-site Testing. 9Launch Methods. 10The Technology. 11Create Candidate Web Service Call. 11Initiate Workflow Web Service Call. 11Form Post. 12Integration ID. 12Additional Initiation Processes. 13Retest through Initiate Workflow Web Service Call. 13Retest through Wonderlic Online Candidate Summary. 13Re-use of test results. 14Job-specific interpretations. 14Collect Notifications. 15Notification Types. 15Results Ready (Standard). 15Retrieve Results. 16Get Candidate Data Web Service Call. 16Get Candidate Data Response. 16Additional Web Service Calls. 17Get Products Web Service Call. 17Get Proctors Web Service Call. 17Version 3.7 2013, 2017 Wonderlic, Inc.Page 2
Wonderlic Data Exchange APIGet Custom Fields Web Service Call. 17Set Custom Fields Web Service Call. 17Get Jobs Web Service Call. 18Technical Details. 18Decision Checklist. 19AppendixCreate Candidate Fields. 20Create Candidate Example. 21Create Candidate Response Fields. 21Create Candidate Response Example. 21Initiate Workflow XML Fields. 22InitiateWorkflow Example. 26InitiateWorkflow XML Response Fields. 26InitiateWorkflow XML Response Example. 27Results Ready/Results Reused Notification Fields. 28Results Ready/Results Reused Notification Example. 29Workflow Initiated Notification Fields. 29Workflow Initiated Notification Example. 30Job Updated Notification Fields. 30Job Updated Notification Example. 30GetCandidateData Fields. 31GetCandidateData Example. 32GetCandidateData Response Fields. 32GetCandidateData Response Example. 36GetProducts Fields. 38GetProducts Example. 38GetProducts Response Fields. 39GetProducts Response Example. 39GetProctors Fields. 40GetProctors Example. 40GetProctors Response Fields. 40Version 3.7 2013, 2017 Wonderlic, Inc.Page 3
Wonderlic Data Exchange APIGetProctors Response Example. 41GetCustomFields Fields. 42GetCustomFields Example. 42GetCustomFields Response Fields. 42GetCustomFields Response Example. 43SetCustomFields Fields. 44SetCustomFields Example. 44SetCustomFields Response Fields. 44SetCustomFields Response Example. 45GetJobs Fields. 45GetJobs Example. 45GetJobs Response Fields. 46GetJobs Response Example. 46Version 3.7 2013, 2017 Wonderlic, Inc.Page 4
Wonderlic Data Exchange APIIntroductionWho is Wonderlic?Wonderlic, Inc., a founding member of the Association of Test Publishers, is a privately held businessheadquartered in Chicagoland. The company provides proven assessments and surveys that helpemployers and schools select, develop and retain top performing individuals. For over 70 years,Wonderlic has delivered over 200 million employment and student assessments and surveys to morethan 50,000 organizations, government agencies and accrediting bodies.What is Wonderlic Online?In serving over 50,000 global clients, Wonderlic has developed a deep understanding in implementingautomated assessment systems. This understanding is culminated in our third generation assessmentlaunch and results delivery platform: Wonderlic Online.Wonderlic Online enables our clients to implement a consistent assessment process and ensures ourassessments are used in a purposeful manner. Client experience emphasis– Collect information– Organize results– Compare candidates– Make decisions Candidate experience emphasis– Learn about the client– Apply for job(s)/program(s)– Demonstrate abilities, skills, and fit Data Exchange experience emphasis– Launch assessments from external system– Retrieve results from Wonderlic OnlineWhat is Wonderlic Data Exchange?Wonderlic Data Exchange is a toolkit that allows clients to embed Wonderlic assessments into theirexisting Applicant Tracking Systems (ATS) and application processes.Wonderlic Data Exchange allows clients to: Incorporate Wonderlic tests into their existing application process as they see fit Use their existing system to launch assessments using any of the methods available onWonderlic Online Retrieve available candidate results at a regular interval or near real time View Wonderlic assessment results in their existing systemVersion 3.7 2013, 2017 Wonderlic, Inc.Page 5
Wonderlic Data Exchange APIBasic Data Exchange ScenarioClientActivities on Client SiteClient Collects ResultsNotificationBackend ActivitiesCandidate createdWorkflow initiatedResults notification sentWonderlicCandidate CompletesWonderlic Online ActivitiesResults StoredRequests resultsDisplay in ATSReturns resultsWonderlic Accepts RequestWonderlic Data Exchange is: Standard: Data exchange utilizes a standard interface, which keeps integration costs down andtimelines short Flexible: Clients choose which test launch and results retrieval features work best fortheir process Robust: Data exchange provides all methods of test launch and results viewing options that existon Wonderlic OnlineWhat needs to be built?Data Exchange passes multiple candidate data points, including assessment results, demographicdata, a unique candidate identifier, and test language between the client system and Wonderlic’ssystem. Clients must build the final step of the integration into their ATS, as every ATS is unique,and every client uses their ATS differently. This way, Wonderlic resources are not required to writecustom code to return results to a third party system. The options available through Data Exchangeempower clients to utilize Wonderlic content in the method that best meets their needs.Version 3.7 2013, 2017 Wonderlic, Inc.Page 6
Wonderlic Data Exchange APIData Exchange utilizes the following technologies: Data is exchanged using a secure data transfer incorporating Web Services over HTTPS Data exchange format is XML XML notifications indicate when data is available or the data can be pulled on-demandIn the simplest terms Wonderlic data exchange allows client to embed Wonderlic assessments into their existingApplicant Tracking Systems and application processes. Data Exchange allows assessments tobe launched seamlessly from the client ATS and for results to be retrieved by the client’ssystem and populated into the ATS to be viewed by the end user. To enable this integration,the following three components must be built by the client:1) A mechanism to add a candidate to Wonderlic’s system and launch tests2) A mechanism to collect results notifications3) A mechanism to request results packages from Wonderlic’s systemThat’s it!Note: When beginning an integration, Wonderlic requires that the client’s code first be testedin a non-production environment on the Wonderlic side, which we call our “sandbox.” It isstrongly recommended that the client also build their code in a non-production environmenton their end, to ensure that all potential issues have been resolved prior to any data beingadded to the production environment. Once all code has been built and tested, and allscenarios have been successfully validated, then the client can migrate the code to theirproduction environment, and run against the Wonderlic production servers. As part of thisswitchover from the Wonderlic sandbox environment to production, Wonderlic will providenew a new client token.Version 3.7 2013, 2017 Wonderlic, Inc.Page 7
Wonderlic Data Exchange APIAdd Candidates and Launch TestsThe ProcessSome Wonderlic assessments can be launched off-site (remotely), while others must belaunched on-site at the client’s facility. Data Exchange supports both off-site and on-site testlaunch scenarios.On-site TestingOn-site testing is required for a number of Wonderlic assessments, and can be used for anyassessment. In the event of an on-site testing session, the candidate will begin their applicationon the client’s ATS system, typically entering identifying information and often completing anapplication or pre-screen. If the candidate is completing the application on-site, they can thenbe seamlessly directed to the Wonderlic assessment(s) that are available for the position/program. If they completed the application remotely, the candidate can be invited to the client’slocation to complete Wonderlic assessments, which will be launched from the client’s ATS. Uponcompletion of the Wonderlic assessments, the candidate can be re-directed to additionalapplication steps, or politely exited from the system. The workflow below details this scenario:Integrating Wonderlic Assessments into ATS (On-Site Testing)Client’s ATSClientClient reviewsapplication andinvites candidateon-site for testingATS platformstores responsesto applicationfor candidateWonderlic launchesproctored assessmentto be completed bycandidateWonderlicCandidateATS passescandidateinformation toWonderlicCandidate appliesto position/program viaworkflow hostedby ATSVersion 3.7Candidate completesproctored Wonderlicassessment 2013, 2017 Wonderlic, Inc.Go toresultsRetrievalPage 8
Wonderlic Data Exchange APIOff-site TestingOff-site testing allows candidates to complete Wonderlic assessments without having to comeon-site to the client’s facility. In a hiring setting, this reduces the amount of time that is investedin candidates who do not show a minimum level of qualification. In an educational setting, thisallows for the assessment of potential distance learners, or for educators to evaluate anindividual’s ability to learn and be trained before coming on-site. In the event of an off-sitetesting session, the candidate will begin their application on the client’s ATS system, typicallyentering identifying information and often completing an application or pre-screen. Thecandidate can then be seamlessly directed to the Wonderlic assessment(s) that are available forthe position/program, or sent an invitation to complete the assessment(s) at a later time.Additional information about assessment launch options is discussed on the next page. Theworkflow below details the scenario in which the candidate is immediately directed to theWonderlic assessment(s):Integrating Wonderlic Assessments into ATS (Off-Site Testing)ATS platformstores responsesto application forcandidateATS passescandidateinformation toWonderlicWonderlic launchesassessment to becompleted bycandidateCandidate appliesto position/program viaworkflow hostedby ATSVersion 3.7CandidatecompletesWonderlicassessment 2013, 2017 Wonderlic, Inc.Go toResultsRetrievalPage 9
Wonderlic Data Exchange APILaunch MethodsThere are three ways in which assessments can be launched. A Wonderlic consultant will workwith the client to determine which options are best for their process/goals.1. Immediate LaunchData exchange supports the seamless launch of Wonderlic assessments immediatelyfollowing the application steps on the client’s ATS. The candidate is directed from the client’sATS hosted application to Wonderlic assessments and completes them as part of theapplication process. This method of test initiation can be used for on-site or off-site testing.2. Email InvitationFor candidates who are applying remotely, it may be preferable that they receive an emailinvitation to complete Wonderlic assessments at their convenience, rather than requiringthat they complete the assessment(s) in one session. Wonderlic’s Data Exchange supportsemail invitation requests from the client’s ATS, which prompts Wonderlic’s system to senda testing invitation to the candidate’s email address. It also supports sending the ATS back acode so that the ATS can email a candidate in any format that they want.3. PINIn the event of a large testing session with multiple candidates on-site, it may be preferableto request a unique testing PIN number for each candidate from Wonderlic’s system. In thiscase, Wonderlic’s system will return a PIN number for each candidate which can then beprinted out and handed to the candidate. The candidate can then navigate to https://www.wonderliconline.com/pin (either by typing in that address or opening a bookmark saved onthe testing machine) and enter their PIN number to begin the testing session. For testing inthe sandbox environment, please use the following URL for the PIN rsion 3.7 2013, 2017 Wonderlic, Inc.Page 10
Wonderlic Data Exchange APIThe TechnologyThe following section provides detailed information for creating a candidate in Wonderlic’s system andlaunching assessments for that candidate.Web ServicesWonderlic recommends utilizing web services for data exchange, as this provides the most robustfeature set.Create Candidate Web Service CallThe Create Candidate web service call is used to add a candidate to Wonderlic’s system. This methoddoes not launch any assessments for the candidate, and therefore must be used inconjunction with the Initiate Workflow web service call.This web service call is useful in the event that the client wishes to add multiplecandidates to Wonderlic’s system at once, without launching any tests. For example, in the event of alarge on-site testing session, all of the candidates could be added to Wonderlic’s system, and then theInitiate Workflow web service call could be used to request a PIN number for all of those candidates.Additionally, this web service call can be used to add a candidate to Wonderlic’s system as soon as theyare created in the client’s ATS, which ensures that the two systems remain in sync.Note: See Appendix page 20 for a complete list of fields to include in the Create Candidate web servicecall, and an example of how the XML should be formatted.Initiate Workflow Web Service CallThe Initiate Workflow web service call is used to launch Wonderlic assessments for a candidate oncethe candidate has been added to the Wonderlic system. The most common scenario is to add thecandidate to the Wonderlic system using the Create Candidate call, and immediately launch a test orrequest a PIN or email using the Initiate Workflow call. Additionally, the client’s system can request aretest for a candidate using this method.Note: See Appendix page 22 for a complete list of fields to include in the Initiate Workflow webservice call, and an example of how the XML should be formatted.Version 3.7 2013, 2017 Wonderlic, Inc.Page 11
Wonderlic Data Exchange APIIntegration IDWhen creating a candidate in the Wonderlic system, the client’s system will need to specify anintegration ID for the candidate. This ID is used by Wonderlic’s system to identify when the same personis being created, and allows the system to tie multiple candidates to the same person without requiringmanual intervention. This field is restricted to alpha-numeric characters.Version 3.7 2013, 2017 Wonderlic, Inc.Page 12
Wonderlic Data Exchange APIAdditional Initiation ProcessesIn some cases, it may be necessary to test a candidate again. The reasons for this are varied, butcould include: An interruption in the testing session (such as a fire alarm or loss of internet connection) An unusual response pattern that could indicate that the candidate did not understand theinstructions. In cases such as these, Wonderlic’s system will provide a warning in the resultspackage indicating that a retest may be advisable. A Wonderlic account team will work with theclient in determining when retests may be warranted.A retest can be given in one of two ways:1. Retest through Initiate Workflow Web Service CallThe standard method for initiating a retest for a candidate is to use the Initiate Workflow web servicecall. This call contains a field indicating whether the client’s system is requesting a retest or not. Theclient’s ATS should be configured to allow clients to request a retest for a particular candidate, andbehind the scenes the client’s system would make the Initiate Workflow web service call with theretest flag set to “yes.”2. Retest through Wonderlic Online Candidate SummaryA retest can also be launched through the Candidate Summary page. The link to the Candidatesummary page is provided in the original results package, and is the same link that can be used to viewand print assessment reports. From the Candidate Summary page, the client can click the “Retest” iconto launch a retest immediately, send an email to the candidate to re-take the assessment (fornon-proctored assessments), or generate a PIN to give to the candidate which will allow them tore-take the assessment. The image below shows what this Retest icon looks like:Version 3.7 2013, 2017 Wonderlic, Inc.Page 13
Wonderlic Data Exchange APIRe-use of test resultsCandidates that have completed the required assessment(s) for a position or program may also apply foranother position or program that requires completion of the same assessment(s). If a candidateinitiates an assessment that they have already completed, they can be prevented from taking therespective assessment(s) twice and notified that all assessments are complete. In turn, the client’s ATSshould be configured to reflect that the applicant applied to another position or program. If the clientwishes to manage which positions the candidate is referred to, or which program the candidate isenrolled in, their ATS should be configured to update the candidate record with the most recentposition or program. A Wonderlic consultant will assist the client in determining the rules for re-use oftest results.Job-specific interpretationsIn the event that a candidate applies to a different position or program that requires the sameassessment(s), the scoring ranges on each assessment may differ. Therefore while a candidate may attainan acceptable assessment score for one program or position, that score may not be acceptable foranother position or program. Job or program-specific interpretations of scores are provided as partof the results returned upon request from Wonderlic’s system. These results are displayed as desired;however, it is important that job or program-specific interpretations accompany scores to ensure thatcandidate’s results are understood as they relate to each position or program requirements. A Wonderlicimplementation expert will work with you to recommend specific scoring ranges based on your goals foreach job or program.Version 3.7 2013, 2017 Wonderlic, Inc.Page 14
Wonderlic Data Exchange APICollect NotificationsWhen a candidate has started a testing workflow or completed a Wonderlic assessment, Wonderlic’ssystem will send a flat file XML notification to the client’s system. The client will need to build a page toaccept these notifications. The notifications allow the client’s system to monitor the progression of acandidate through the testing session. The Results Ready notification provides information to identifythe candidate and the test and administration, which allows the client’s system to pull the results.Notification TypesResults Ready (Standard)The Results Ready notification informs the client’s system that a candidate has completed an assessment and it has been scored and interpreted by Wonderlic’s system. The notification includes information to identify the candidate, the assessment that was completed, and a unique ID for the result. Theclient’s system should use this information to request the results package from Wonderlic’s system.Note: See Appendix page 28 for the fields that appear in the Results Ready notification and anexample of how the notification will be formatted.Results Re-Used (Optional)The Results Re-Used notification informs the client’s system that a candidate has entered a workflowthat contained an assessment that the candidate had previously completed within the re-use timespan, and therefore was not required to take the assessment again. The purpose of this notification isto aid the client’s system in re-requesting the results package for the candidate if desired. For example,often the client’s system has many reqs that map to one req on the Wonderlic system, and in this case,the candidate is not presented with the assessment again, nor is a new results ready notificationgenerated, as this is the same candidate and req on the Wonderlic side.Note: See Appendix page 29 for the fields that appear in the Results Re-Used notification and anexample of how the notification will be formatted.Workflow Initiated (Optional)The Workflow Initiated notification informs the client’s system that a candidate has entered a testingsession. This allows the client to monitor where a candidate is in the application process withouthaving to log in to Wonderlic Online. This notification can be turned on or off based on the client’spreference.Note: See Appendix page 29 for the fields that appear in the Workflow Initiated notification and anexample of how the notification will be formatted.Job Updated (Optional)The Job Updated notification informs the client’s system that a job has been added, removed, ormodified. Possible modifications that will trigger a notification include changes to the JobID, job name,or active status. The purpose of this notification is to alert the client’s system when jobs have beenmodified, such as previously ac
3. PIN In the event of a large testing session with multiple candidates on-site, it may be preferable to request a unique testing PIN number for each candidate from Wonderlic’s system. In this case, Wonderlic’s system will return a PIN number for each candidate which can then be printed out and handed to the candidate.
