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.

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>

REST

AssessmentProvider

https://api1.lumesse-talenthub.com/AssessmentProvider/REST/AssessmentProvider/results-template.xml?system-name=ABC&api_key=123DFG
https://api2.lumesse-talenthub.com/AssessmentProvider/REST/AssessmentProvider/results-template.xml?system-name=ABC&api_key=123DFG
https://api3.lumesse-talenthub.com/AssessmentProvider/REST/AssessmentProvider/results-template.xml?system-name=ABC&api_key=123DFG
https://apiapac.lumesse-talenthub.com/AssessmentProvider/REST/AssessmentProvider/results-template.xml?system-name=ABC&api_key=123DFG

ServiceDescriptionParametersMethodReturns
results-template Returns the results template structure which can then be used in conjunction with the submitResults method. system-name GET an empty StructuredDocument with the structure that this particular requester should use to submit results
submit-report Allows the service provider to submit arbitrary binary files containing results or other data regarding the given external request.

requestId -- the ID of the external request being processed,

report - Binary representation of file.

POST

     "operation-result" -- an output object with two fields:

  • "success" (boolean/required): indicates if the operation was successfully completed in TalentLink,
  • "details" (string/optional): status description.
submit-resource Allows the service provider to submit a URL.

request-id -- the ID of the external request being processed,

name : The type of URL. Can be "AssessmentUrl", "VerificationUrl" or "ProtectedAssessmentUrl".

location : The URL

 

 

 

 

POST

     "operation-result" -- an output object with two fields:

  • "success" (boolean/required): indicates if the operation was successfully completed in TalentLink,
  • "details" (string/optional): status description.
submit-results Allows the service provider to submit results for a given external request.

  "request-id" -- the ID of the external request being processed,

-       "results" -- a StructuredDocument (in JSON or XML format) with results for the given request. This document should have the same structure as the one returned by the getResultsTemplate operation

POST

  "operation-result" -- an output object with two fields:

  • "success" (boolean/required): indicates if the submission was accepted by TalentLink,
  • "details" (string/optional): status description.
submit-status Allows the service provider to submit hints on the current state of a given external request, as well as to control the way its results are recorded in TalentLink.

  "request-id" -- the ID of the external request being processed,

-       "status" -- an enumerated (case-sensitive) value: one of Unknown, Initiated, Started, Updated, Locked, Saved, Completed, CALCULATED.

POST

    "operation-result" -- an output object with two fields:

  • "success" (boolean/required): indicates if the operation was successfully completed in TalentLink,
  • "details" (string/optional): status description.

Queue

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


Method getResultTemplate returns the results template structure which can then be used in conjunction with the submitResults method.

This method must be called with Talentlink backoffice user credentials.
The user name must be set to the following format: CompanyName:saif:BO.
The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
system-name
String
[mandatory] Internal TLK external system name

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
results-template
StructuredDocumentDto
Document representing result template
  questions
List
List of questions for document
    questions
AssignedQuestionDto
Document question
      id
Long
Assigned question ID that is specific for document, copy of the question from template, form
      label
String
Question label
      order
Long
Order of a question in the form
      type
String
Answer type
      localizedLabel
String
Question label translated to the language specified in langCode
      questionId
Long
Question ID that value does not changed for documents based on the same form
      index
Integer
Question index
  id
Long
Assigned question ID that is specific for document, copy of the question from template form
Method submitReport allows an assessment provider to submit a physical file containing a report.

This method must be called with Talentlink backoffice user credentials.
The user name must be set to the following format: CompanyName:saif:BO.
The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
request-id
String
[mandatory] Internal TLK ID of request
report
AttachedFileDto
[mandatory] Representation of report file
  id
Long
TLK Internal ID
  fileName
String
[mandatory] Name of the file with file extension
  description
String
Description of the file.
  docType
DocumentType
[mandatory] Business type of the current document (cover letter, resume, mail...) Click to see possible values
  docLanguage
String
Language code used whilst uploading of the document.
  binaryData
DataHandler
The binary representation of the file
  creationDate
Date
Time and date of the document was added to the post
  size
Long
Size of file
  author
String
Name of the user who uploaded the document
  docId
Long
ID for the document that needs to be used for downloading the attachements. (Use method downloadAttachedFile within the Document web service to download).
  publishable
Boolean
TRUE or FALSE

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
operation-result
OperationResultDto
Result of operation processing
  success
Boolean
Is operation successful
  details
String
Details if operation fails
Method submitResource allows an assessment provider to pass a URL to TLK. The URL will typically be used by a candidate to take an assessment.

This method must be called with Talentlink backoffice user credentials.
The user name must be set to the following format: CompanyName:saif:BO.
The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
request-id
String
[mandatory] Internal TLK ID of request
name
String
[mandatory] name of additional resource
location
URL
Link to additional resource
value
String
Resource content

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
operation-result
OperationResultDto
Result of operation processing
  success
Boolean
Is operation successful
  details
String
Details if operation fails
Method submitResults allows an assessment provider to submit a structured document containing a results.

This method must be called with Talentlink backoffice user credentials.
The user name must be set to the following format: CompanyName:saif:BO.
The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
request-id
String
[mandatory] Internal TLK ID of request
results
StructuredDocumentDto
[mandatory] Filled result template document to be submitted
  questions
List
List of questions for document
    questions
AssignedQuestionDto
Document question
      id
Long
Assigned question ID that is specific for document, copy of the question from template, form
      label
String
Question label
      order
Long
Order of a question in the form
      type
String
Answer type
      localizedLabel
String
Question label translated to the language specified in langCode
      questionId
Long
Question ID that value does not changed for documents based on the same form
      index
Integer
Question index
  id
Long
Assigned question ID that is specific for document, copy of the question from template form

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
operation-result
OperationResultDto
Result of operation processing
  success
Boolean
Is operation successful
  details
String
Details if operation fails
Method submitStatus allows an assessment provider to update the status of a candidate's assessment.

This method must be called with Talentlink backoffice user credentials.
The user name must be set to the following format: CompanyName:saif:BO.
The password must be the user password for example: "Saif123!"

Post Parameter

 
Parameter Data Type Description
request-id
String
[mandatory] Internal TLK ID of request
status
STATUS
[mandatory] Represents submit status. Possible values: Unknown, Initiated, Started, Updated, Locked, Saved, Completed, CALCULATED

Request Parameter

 
Parameter Data Type Description
APi Key Alphanumeric Will be provided by Lumesse

Response Parameter

 
Parameter Data Type Description
operation-result
OperationResultDto
Result of operation processing
  success
Boolean
Is operation successful
  details
String
Details if operation fails