Assessment Provider

The Assessment Provider bundle provides access to the Queue and AssessmentProvider web services.

Work Flow

A typical work flow would be :

  • A recruiter moves a candidate to an application step that is linked to an assessment.
  • The request is added to a “Queue”.
  • Optionally an alert is sent to the assessment provider.
  • The assessment provider calls the Queue web service to retrieve details of the request.
  • Provider registers candidate.
  • The assessment provider calls the Queue web service to remove the request from the queue.
  • Provider calls submitResource method of the AssessmentProvider service and passes in a URL for the candidate to take the assessment.
  • An email containing the URL is sent to the candidate.
  • Candidate takes assessment.
  • Provider sends results back either as a report or as a TalentLink defined form.
  • Provider sends Assessment status 'Completed'; which closes the selection step and automatically Rejects or proceeds Candidate to next selection step based on auto-scoring rules set-up within TalentLink.

Registering a Candidate for an Assessment

A recruiter will mark a candidate as needing to take an assessment, which will add the request to our "Queue".

The request in the queue will contain the following fields :

Field Description
additionalParameters A list of pairs (key-value) containing details. The configuration of the pairs is done by Lumesse when creating the assessments in TalentLink. For example if an assessment provider requires the candidate first name, surname and email, these three fields can be added to the additionalParameters section.
candId internal (Lumesse) ID of the candidate the request refers to.
candidateStatus current status of the candidate the request refers to.
candidateType type of candidate this request refers to (e.g. External Candidate, Employee)
externalClientId String that identifies TalentLink as a client of the external system
externalServiceId External ID that indentifies the current service in this external system. Typically it would be used to identify a particular assessment.
tlkRequestId public ID (aka "Correlation ID") of the current request. This ID is used to submit results back to TalentLink.

An example response from "getExternalSystemRequestFromQueue"

  <ns2:getExternalSystemRequestFromQueueResponse xmlns:ns2="http://ws.mrted.com/">
  <ns2:externalSystemRequest>
  <additionalParameters>
  <entry>
  <key>EmailAddress</key>
  <value>joe.bloggs@testco.com
  </value>
  </entry>
  <entry>
  <key>FirstName</key>
  <value>Joe</value>
  </entry>
  <entry>
  <key>LastName</key>
  <value>Bloggs</value>
  </entry>
  </additionalParameters>
  <candId>28890</candId>
  <candidateStatus value="New" />
  <candidateType>Employee</candidateType>
  <externalClientId>Lumesse123</externalClientId>
  <externalServiceId>ABC1234</externalServiceId>
  <tlkRequestId>OT-ABC-3hq-3grb-h</tlkRequestId>
  </ns2:externalSystemRequest>
  </ns2:getExternalSystemRequestFromQueueResponse>

Alerting the Candidate

Once the provider has registered a candidate for an assessment, the URL for taking the assessment is passed back to TalentLink by the provider calling the submitResource method.

 

  <ws:submitResource>
  <ws:request-id>OT-ABC-3hq-3grb-h</ws:request-id>
  <ws:name>AssessmentUrl</ws:name>
  <ws:location>http://assessmentURL.com?testid1234</ws:location>
  </ws:submitResource>

Calling this method will cause an email containing the URL to be sent to the candidate.

A successful response will return :

 

  <ns2:operation-result>
  <success>true</success>
  <details></details>
  </ns2:operation-result>

If the request results in an error, <success> will be false and the details of the error will be seen in <details>.

 

Submitting Results

The Assessment provider has two methods for submitting results. A physical file (pdf, docx etc) can be passed to the submitReport method. Alternatively, a TalentLink structured document can be passed to the submitResult method.

To be able to use a structured document, the document structure can be retrieved by calling getResultsTemplate. The response will look something like :

 

  <ns2:results-template>
  <questions>
  <ns2:question>
  <id>30740</id>
  <label>Status</label>
  <answer>
  <values>
  <value>
  </value>
  </values>
  </answer>
  </ns2:question>
  <ns2:question>
  <id>30741</id>
  <label>Overall Score</label>
  <answer>
  <values>
  <value>
  </value>
  </values>
  </answer>
  </ns2:question>
  <ns2:question>
  <id>30742</id>
  <label>Test result URL</label>
  <answer>
  <values>
  <value>
  </value>
  </values>
  </answer>
  </ns2:question>
  </questions>
  </ns2:results-template>

 

To use the structured document to pass back a result, submitResults can be called.

submitResults Example

 

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mrted.com/">
  <soapenv:Header/>
  <soapenv:Body>
  <ws:submitResults>
  <ws:request-id>OT-ABC-3o4-3psh-h</ws:request-id>
  <ws:results>
  <questions>
  <ws:question>
  <id>30740</id>
  <label>Status</label>
  <answer>
  <values>
  <value>Completed</value>
  </values>
  </answer>
  </ws:question>
  <ws:question>
  <id>30741</id>
  <label>Overall Score</label>
  <answer>
  <values>
  <value>5</value>
  </values>
  </answer>
  </ws:question>
  <ws:question>
  <id>30742</id>
  <label>Test result URL</label>
  <answer>
  <values>
  <value>http://demo.com/Result/Index/?id=681b1801-f5f1-4ed8-ba1e-8faf19fc7f3b</value>
  </values>
  </answer>
  </ws:question>
  </questions>
  </ws:results>
  </ws:submitResults>
  </soapenv:Body>
  </soapenv:Envelope>

 

 

SOAP

AssessmentProvider

https://api1.lumesse-talenthub.com/AssessmentProvider/SOAP/AssessmentProvider?api_key=123DFG
https://api2.lumesse-talenthub.com/AssessmentProvider/SOAP/AssessmentProvider?api_key=123DFG
https://api3.lumesse-talenthub.com/AssessmentProvider/SOAP/AssessmentProvider?api_key=123DFG
https://apiapac.lumesse-talenthub.com/AssessmentProvider/SOAP/AssessmentProvider?api_key=123DFG

At the time of activation, you will be told which URL to use.

WSDL

Method Description Parameters
getResultsTemplate Returns the results template structure which can then be used in conjunction with the submitResults method. System Name
submitReport Allows an assessment provider to submit a physical file containing a report. requestId, binary representation of file.
submitResource Allows an assessment provider to pass a URL to TLK. The URL will typically be used by a candidate to take an assessment. requestId, name, URL, value
submitResults Allows an assessment provider to submit a structured document containing a results. requestId, structured document.
submitStatus Allows an assessment provider to update the status of a candidate's assessment. requestId, Status. Valid values for Status are : Unknown, Initiated, Started, Updated, Locked, Saved, Completed, CALCULATED

Queue

WSDL

More information on queues can be seen on the Queue page.

Method Description Parameters
getExternalSystemRequestFromQueue Returns the assessment provider request from the queue. Queue Name
removeExternalSystemRequestFromQueue Removes the oldest assessment provider request from the queue. Queue Name

The "getExternalSystemRequestFromQueue" method returns the following fields :

  • "additionalParameters": a list of pairs (key-value) containing details. The configuration of the pairs is done by Lumesse when creating the assessments in TalentLink. For example if an assessmsnet provider requires the candidate first name, surname and email, these three fields can be added to the additionalParameters section.
  • "candId" -- internal (Lumesse) ID of the candidate the request refers to,
  • "candidateStatus" -- current status of the candidate the request refers to,
  • "candidateType" -- type of candidate this request refers to (e.g. External Candidate, Employee),
  • "externalClientId" -- String that identifies TalentLink as a client of the external system .
  • "externalServiceId" -- External ID that indentifies the current service in this external system. Typically it would be used to identify a particular assessment.
  • "tlkRequestId" -- public ID (aka "Correlation ID") of the current request. This ID is used to submit results back to TalentLink.

An example response from "getExternalSystemRequestFromQueue"

  <ns2:getExternalSystemRequestFromQueueResponse xmlns:ns2="http://ws.mrted.com/">
  <ns2:externalSystemRequest>
  <additionalParameters>
  <entry>
  <key>EmailAddress</key>
  <value>joe.bloggs@testco.com
  </value>
  </entry>
  <entry>
  <key>FirstName</key>
  <value>Joe</value>
  </entry>
  <entry>
  <key>LastName</key>
  <value>Bloggs</value>
  </entry>
  </additionalParameters>
  <candId>28890</candId>
  <candidateStatus value="New" />
  <candidateType>Employee</candidateType>
  <externalClientId>Lumesse123</externalClientId>
  <externalServiceId>ABC1234</externalServiceId>
  <tlkRequestId>OT-PREEMPLOYMENTCHECKAPI-13f-5kf8-4</tlkRequestId>
  </ns2:externalSystemRequest>
  </ns2:getExternalSystemRequestFromQueueResponse>

Queue

The Queue web service is only available using SOAP. Please see above for details.