ac sdk documentation

8/3/2019 AC SDK Documentation

1/30

PROFILES OFFICE PARK 5205 LAKE SHORE DRIVE WACO, TEXAS 76710-1732 USA 254.751.1644 WWW.PROFILESINTERNATIONAL.COMCOPYRIGHT 2001-2009 PROFILES INTERNATIONAL, INC.

Assessment Central IntegrationDocument

March 23, 2008

Building and Retainingthe

High-Performance

Company


2/30

Last Updated: 5/4/2012 Page 2 of 30Copyright 2004-2009 Profiles International, Inc

TABLE OF CONTENTS

Introduction 3Whats Included in this SDK 5Installation 6Running the Sample App 8Integrating the Sample App 9

Database changes required for integration 9Integration Points 10

Assessment Central Integration Requirements 12Checklist for Successful Assessment Central Implementation 12General Process 14

HR-XML Assessments Messages 14HR-XML Assessments Use Cases 15Example Messages 17

Testing 27Appendix A: Version History 28Appendix B: Differences from HR-XML Assessment Standard 29

Values Stored in Messages 29Web Services vs. POST 30


3/30


INTRODUCTION

Assessment Central is a rich portal providing access to a broad range of Profiles Internationalassessments. Assessment Central is not a stand-alone website but is designed to be integratedwith a clients website or processes.

Assessment Central consists of four parts: a Web Service which is called to schedule ProfilesInternationals assessments, a Website which takes the candidates through the assessments andcollects their answers, a client-hosted callback Web Service that accepts notification when thecandidate completes the assessment, and a Website which allows a client to look at a candidatesassessment details include scores, reports and comparisons with other candidates and to customizethe process.

Assessment Centrals Web Service communication is based upon the HR-XML Assessmentsstandard (http://www.hr-xml.org/).

The HR-XML Consortium is an independent, non-profit organization dedicated to

the development and promotion of a standard suite of XML specifications toenable e-business and the automation of human resources-related dataexchanges.

The HR-XML Assessments standard sets up the following scenario allowing a Client (you) to workwith an Assessment Vendor (Profiles International, Inc.) to assess a Candidate (your candidates).
http://www.hr-xml.org/http://www.hr-xml.org/http://www.hr-xml.org/http://www.hr-xml.org/


4/30


Assessment Central uses a secure connection for all communication with your application.

With Assessment Central, you do not have to create any new web pages on your site. You canintegrate assessments into your existing web pages and workflows.

1) During some process on your system you will make a Web Service call to AssessmentCentral to register your candidate for an assessment.

2) Assessment Central will return a URL and credentials that the candidate can use to take theirassessment.

3) You provide a link to your candidate so that they can take the assessment.4) When the candidate has completed the assessment you will receive notification and details

describing the candidates scores on the assessments. Integrate that information into yoursystem to help you make better decisions about the candidate.

5) Then send your employees (Hiring Manager, Department Head, etc) over to AssessmentCentrals portal to view information to help you make better decisions about the candidate.

Data retained on your servers:

Scheduling Request some data about the scheduled assessment will be retained to allowyou to send the candidate to the assessment.

Data retained on our servers:

Assessment Central retains information about each candidate and each scheduledassessment and retains the candidates answers and scores.

Assessment Central retains any Performance Models, Scheduling Templates, and Teamsthat might be used in this process.

Information retained on Assessment Central servers may be purged after an assessment iscomplete or the scheduling request has expired.


5/30


WHATS INCLUDED IN THIS SDK

AC SDK Documentation.doc - This document.

ACSDK.Setup.msi - Installer for the sample application and source

code for simplifying an integration.

AssessmentCentral.wsdl - WSDL file that can be used by some tools to speedup the creation of client stubs to accessAssessment Central.

ACClient.wsdl WSDL file that can be used by some tools to speedup the creation of server stubs to write a callbackWeb Service to be hosted on the clients side.


6/30


INSTALLATION

The Assessment Central SDK Sample App is delivered as a single Microsoft .NET C# solution. Itincludes business components for communicating with Assessment Central and a Web Service forresponding to callbacks from Assessment Central. These solutions were developed against the

.NET Framework version 2.0 using Microsoft Visual Studio 2005.

1) Install ACSDK.Setup.msi

This setup installs a sample app that demonstrates the functionalities available from theAssessment Central Web Service.

2) Create the sample database

The sample application uses a database for storing scheduling information. The samplecode also requires a table to store candidate information. The following script(s) will beinstalled in the ACSDK\Database folder during step 1.

CreateDatabase.sqlwill create a database named ACLSampleApp and a SQL usernamed ACLSampleUser. You can skip this script if you have a database and user alreadyin mind, otherwise, this must be the first script executed. Each of the remaining scriptsreferences the ACLSampleApp database in the first line with a use statement.

Candidate.sql will create tables and stored procedures used by the sample application toidentify candidates.

* Because the sample app needs some information that will already be in your system(like an individuals unique id, first name and last name), you may not need this tableat all when you integrate with your own system. If you use your own candidate table,you will need to modify the code in GetCandidate.sql.

ACSDK.sql will create tables and stored procedures used by the sample application.

GetCandidate.sqlcontains the stored procedure that obtains a candidates name anddetails along with the assessments scheduled.

* Because the sample app needs some information that will already be in your system(like an individuals unique id, first name and last name), you may end up modifyingthis single stored procedure to point to your existing data.

3) Configure the installation

For ease of use there are application configuration items in the ACSampleApp\web.config

file. Values for the following items will be provided by Profiles International, Inc.


7/30


There are a couple items that need to be configured in the web.config with values providedby you:

The Client Owner ID is merely an identifier of who is responsible for defining theelements in the Client Order section of the AssessmentOrderRequest message. Thiscould merely be your company name. The Client Order section of theAssessmentOrderRequest allows you to supply custom data that could be used fortracking like department names, purchase order numbers. This data does not haveany bearing on our processing, but will be returned to you with our callback to yourclient-hosted Web Service, so it may be useful to you in tracking the responses.

The Assessment Requester is the individual who requested the assessment. That

information is tracked by Assessment Central. In the SDK, this is a single valuepulled from the web.config. Your process may likely want to make this a unique valuebased upon on the candidate or position, but that is up to you to change.

The sample app is designed to pick up its database connection string from the sameconfiguration file. For purposes of running the sample, fill in your connection string valuehere:

If you have used the CreateDatabase.sql script exactly as provided and your database in on

the same server, then insert the following connection string value:

Server=(local);UID=ACLSampleUser;PWD=Password;Database=ACLSampleApp

Note: If you are using SQL Server 2000, be sure that youve configured it to supportauthentication based upon both SQL Server logins and Windows accounts. By default, SQLServer 2000 is setup to accept only Windows account authentication (Tools-Menu\SQLServer Configuration Properties\Security-Tab).


8/30


RUNNING THE SAMPLE APP

NOTE: Before you can run the sample app completely, youll need to provide Profiles with thecallback URL of the ACClient.asmx Web Service. To do that you may need to place the web serviceon an IP address outside of your firewall. If you dont do this step, you cannot receive notification

when the candidate completes their assessment.

In a web browser on the development machine installed, navigate to the following URL:

http://localhost/ACSampleApp/default.aspx

These web pages are not designed to be incorporated into your application, but merely to show youhow it would be possible to integrate some its functions into your existing web pages.

The New Candidate link goes to a page to create a sample candidate. This page does nothing morethan create a candidate in the local system by collecting a unique candidate id, name, optional emailaddress, and optional gender and optional salutation. To use this page, simply enter any Candidate

ID (a Candidate ID is the same as a UserID or LoginID on your system) and other information andclick Create Candidate.

The next step is to click the Register the candidate for an assessment. You must enter a SchedulingTemplate id and click the Add button. You will need a Scheduling Template to be created beforeyou can continue with this step. This will send an HR-XML AssessmentOrderRequest message toAssessment Central and will immediately return the information to allow the candidate to take anassessment. The Candidate URL on the user interface will be populated with the URL that youwould give to the candidate. Your system could put this value into an email or an integrated link onyour screen.

If you follow the Candidate URL, this will transition you to the Profiles Assessment Center and allow

you to take the assessment just as a candidate would.

While youre taking the assessment you could open a second web browser and navigate to thesame URL as above:http://localhost/ACSampleApp/default.aspx . You find the same candidate andthen click the Check Progress button. This will send an HR-XML AssessmentStatusRequestmessage and retrieve the candidates current progress.

When the candidate completes the assessment, Assessment Central will make a callback sending aHR-XML AssessmentResult message to the ACClient Web Service hosted on your server. NOTE: Ifyou have not provided Profiles with the URL of this callback, then you wont receive the call andcannot go any further with your testing.

The sample code will accept the callback which will provide percent matches to Performance Modelsin our system (where appropriate) and a URL to view the candidates results and allow you torequest printable reports. Once this occurs, the URL will be populated in the Client URL of thissample application. When you follow this URL, youll be asked to login using Profiles AssessmentCentral credentials.
http://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspxhttp://localhost/ACSampleApp/default.aspx


9/30


INTEGRATING THE SAMPLE APP

The Sample App code is specifically designed to make integration simple. The main differencebetween the sample and your existing application is that you already have the candidates name andif necessary their salutation and gender.

Throughout the source code of the Sample App, you will find comments that begin with//DESIGN_TODO:. Each of these includes a description of the change that is required or should beconsidered.

You will not use the Default.aspx or CreateCandidate.aspx web pages in your application. You willuse the concepts within them in other pages within your application.

However you can use the ACClient.asmx web service completely as is.

DATABASE CHANGES REQUIRED FOR INTEGRATION

Remove the CreateDatabase.sql as needed. This script creates a new database. Youll want toinclude the rest of these tables and stored procedures as part of your applications database. Thisscript also creates a SQL user account. You will likely re-use an existing SQL user account on yourdatabase or use a trusted account.

Remove the Candidate.sql script to remove the creation of the ACCandidate database table andremove the usp_ACCreateCandidate stored procedure.

Run the ACSDK.sql script as is to create the ACCandidateScheduling table and supporting storedprocedures.

Modify GetCandidate.sql script and change the usp_ACGetCandidate stored procedure toreplace the results returned from the ACCandidate table and return them from a database table inyour own system. If the candidate ID in your system is not a string, convert it to a string whenreturned. There are two possible candidate IDs that need to be returned. The UniqueCandidateIDis meant to be a permanent ID that would remain with the individual if they were to transition fromsay a candidate to an employee. The other candidate ID is meant to be more temporary as acurrent identifier. You can return the same ID for both values if that fits your situation. If you donthave a value for Salutation, return a 4 and Assessment Central will ask the candidate if its required.If you dont have a value for Gender, return a 2 and Assessment Central will ask the candidate if itsrequired. Some Profiles International reports use sentences like Mr. Smith likes or He canbe to make the report flow more naturally.

If you return a different set of fields you may need to change

ACSDK\BusinessComponents\ClientHelper.cs in order to fill in the required values.


10/30


INTEGRATION POINTS

Even if you dont use any of the SDKs web pages, by u sing the classes provided you can saveyourself considerable programming effort. For instance the RegistrationHelper class encapsulateseverything needed to call our web service to schedule a candidate.

Look at each of the Processes below to see if they fit your needs.

Process: Scheduling a candidateCode required:

ICandidate candidate = newCandidateHelper(candidateID);string packageID = ConfigurationManager.AppSettings["Package ID"];string assessmentRequester =

ConfigurationManager.AppSettings["Assessment Requester"];

RegistrationHelper.RegisterCandidate(candidate, packageID,null, assessmentRequester);

Note: By supplying a Hashtable as the third parameter you can send additional informationsuch as purchase order numbers or department name where the request for the assessmentcame from. Assessment Central will return this information to you in the AssessmentResultmessage when a candidate completes the assessment(s) as well as other status requests.The ACSDK does not use this information as the ReceiptID unique identifier serves as alookup in a local database to uniquely identify the scheduling request.

Process:Client is interested in a candidates progress and clicks a button on their site (or throughsome other automated process.)

NOTE: It is possible to setup an automated reminder directly from Assessment Central, but

that email would come from Profiles International and not from your company which may ormay not desired.

Code Required:

ICandidate candidate = newCandidateHelper(candidateID);RegistrationHelper.CheckStatus(candidate);if (candidate.Schedulings[0].Status != SchedulingStatusEnum.Completed){

//Candidate has not completed the assessment, so we could// send a gentle reminder//NOTE: Could also check candidate.Schedulings[0].ScheduledDate to// verify when the candidate was scheduled and could check// candidate.Schedulings[0].LastStatusDate to determine when the

// candidate last worked on the assessment}


11/30


Process: Sending a candidate to their assessment via emailEmail Content Required:

URL for them to take their assessment.

NOTE: When the candidate first arrives at the Profiles Assessment Center site, they will be asked tocreate a password to be used for re-entry. They can return and resume an assessment at any time

up until the scheduling request has expired.

To retrieve the URL:

ICandidate candidate = newCandidateHelper(candidateID);string URL = candidate.Schedulings[0].CandidateURL;

NOTE: Even if your implementation has more than one scheduling for the candidate, theCandidateURL in each of those Scheduling objects will have the same value.

Process: Sending a candidate to their assessment via your websiteCode Required:

You can merely place a link on your site with the candidates URL.

Code to receive the URL is the same as above.

Process: Receiving a callback when the candidate completes their assessment.Solution: The ACClient.asmx page could be used as is to perform this step. It merely accepts thecallback and then updates the candidates scheduling status. Its possible that this may mark thecandidate as having completed their assessments or may have cancelled their assessments if theyhave expired.


12/30


ASSESSMENT CENTRAL INTEGRATION REQUIREMENTS

If you use the code in the sample application included in this SDK in your own application, then youllhave code that will satisfy Profiles Internationals requirements for a successful implementation. Ifyou need to design an implementation of your own, the sample application code is a good place tostart, but it must include all of the following:

CHECKLIST FOR SUCCESSFUL ASSESSMENT CENTRAL IMPLEMENTATION

General Requirements:1. No user should be able to see a report they're not authorized for.

General Capture Requirements:2. Need to log errors so that you can identify / recreate any problem3. Capture and supply the candidates first and last name.4. Optionally supply the candidates gender and salutation to be used in reports5. Create a unique candidate identifier. It can be any string value up to 50 characters.6. Fill in all required fields in messages sent to Profiles International.

Storage Requirements:7. Store a record for each scheduling request made by the client system and use the ReceiptID

as the unique identifier8. Store the URL, token and key returned as a response to a scheduling request to be able to

re-provide that information to your candidate9. Store a list of Scheduling Template names along with their Scheduling Template IDs to be

used upon scheduling a candidate.10. Optionally store a list of Security Group names if the candidates should be secured against

specific users in the Profiles Assessment Center.11. Optionally store a list of Optional Code IDs and values that can be applied to candidates to

facilitate better searching for candidates in Profiles Assessment Center. These values canbe sourced from the clients system and allowed to be automatically added in the ProfilesAssessment Center upon scheduling.

General XML messaging:12. Xml messages require all fields even though the WSDL may indicate that all fields are

optional

Call Limitations:13. Calls to schedule a candidate for a particular package should not occur more than once.14. Calls to check the status of a candidates assessments should not be automated.

a. Calls should not occur more than 4 times per day for an individual candidate.15. The Consumer Token is only valid for 8 hours.

a. Calls to get a Consumer Token should not occur more than 8 times per day.

To make an implementation easier:16. Pull all system properties (ConsumerID, username, password, Assessment Central URL,

Environment Name, API Version) in retrievable storage locally.17. Write code to always trust our https URL18. Ensure that the servers are all synchronized for time. If one server is using a different patch

for daylight savings time or the time is off for other reasons, then the code in


13/30


ProductHelper.cs which uses an absolute time for synchronizing the Consumer Token acrossservers may cause the token to be cached longer than its usable.


14/30


15/30


HR-XML ASSESSMENTS USE CASES

Assess a CandidateThe main process involved in any Assessment Central integration is the action of scheduling acandidate to take an assessment. The following use case diagram describes this process:


16/30


Query Assessment StatusOnce a candidate has been scheduled, and youve sent them to Assessment Central to take theirassessments, you dont know about their progress until they complete the assessment. If you wantto check on their progress, you can ask for that information through the AssessmentStatusRequestmessage.

Cancel an AssessmentIf after a candidate has been scheduled, you want to stop the candidate from taking an assessment,you need to notify Assessment Central to stop the assessment.


17/30


EXAMPLE MESSAGES

AssessmentOrderRequest message:

The schema file is superceded by the AssessmentCentral.wsdl. The wsdlcontains a superset of all of the information contained in the schema file.

[Guid][Username][Password]

The ConsumerID, Username, and Password will be provided to you by Profiles

1[Sandbox|Production]

Use Sandbox when developing against our PubTest site.

PXT

The value PXT is a sample Scheduling Template ID that may not exist. You willneed to provide a way to store the potential Scheduling Template IDs on yoursystem.

Profiles International, Inc.

The ProviderId section is defined by you. You can put your own values foridOwner and IdValue. For almost all implementations this information is notimportant as you will be dealing directly with Profiles International and expectresponses back directly from Profiles International.

CodeValue

CodeValue

The ComparisonGroupId nodes are optional. The ComparisonGroupId nodeallows you to mark candidates with Optional Codes inside Profiles AssessmentCenter. These can be used to make searching for candidates more efficient.


18/30


53RR20031618Administration

The ClientOrderId node is an optional node allowing you to pass multiple

arbitrary values which will be returned to you in the AssessmentResult message.The names and values are up to you to provide.

Johnny Employer

The assessment requester is the person at the client requesting that thiscandidate take an assessment.

1234512345

The SubjectID defines the unique id provided by the client. You can supply oneor both of the UniqueID and CandidateID values. If both are provided, theCandidate ID value will be the one visible on screen inside Profiles AssessmentCenter. The UniqueID is expected to be maintained indefinitely for a candidate.The CandidateID is allowed to change over time. For example a candidate for a

job may be given a candidate id by an applicant tracking system. Later whenthat candidate is an employee, he may be given an employee id.

[Salutation= Mister,Misses][Gender=Male,Female]

The Salutation and Gender values are optional. Profiles Internationalassessments use pronouns and salutation in the printed reports to make thesentences flow more naturally. So if this information is not provided here, we willask the candidate to provide it later.

AssesseTommy

[email protected]

The ContactMethod node is optional. The ContactMethod is where you wouldsupply the candidates personal email address. Users of the ProfilesAssessment Center can send candidates email reminders to complete theirassessment either manually or automatically.

EN-US


19/30


AssessmentLanguage defines the language the candidate can take theassessment in. Contact your representative to determine the languages that areavailable to you as choices.

EN-US

The ResultLanguage defines the language that the AssessmentResult messageshould be returned using.

Admin

The OwningSecurityGroup node is optional. Candidates can be secured withinProfiles Assessment Center so that only certain users are able to see thecandidate. You can automatically place the candidate in one of those securitygroups by supplying the Security Group Name here. Your system will have to

maintain the possible values for security groups and decide when to use eachvalue.


20/30


AssessmentOrderAcknowledgement message:

[GUID]

The ClientId, ProviderId, and ClientOrderId nodes here are included because theHRXML standard requires them. The original HRXML standard was based upona One-Way communication standard and therefore these values were required inorder to verify the identity of the which request this acknowledgement was for.You will not need to use these nodes in this message only.


[Guid]

The ReceiptId value will be provided upon successful completion of scheduling.This value can be used to match this scheduling request with AssessmentResultmessages sent by Profiles system at a later date.


businesshttps://www.profilesac.com/ABCDEFGHIJ

URL for subject to access assessment.

The InternetWebAddress is the unique URL for this candidate to access and taketheir assessments.

AcknowledgedThe assessment order has been processed.2003-04-24

The AssessmentStatus/Status may return Error if youve provided a bad

parameter. The Details node in that case should identify the problem with therequest. When the status is an error, the ReceiptId and AccessPoint nodes willnot be provided.


21/30


AssessmentCancelRequest message:

[GUID][Username][Password]





[Guid]

Use the ReceiptId value provided in the AssessmentOrderAcknowledgmentmessage to uniquely identify the scheduling to cancel.



22/30


AssessmentStatusRequest message:

[GUID][Username][Password]





[Guid]

Use the ReceiptId value provided in the AssessmentOrderAcknowledgmentmessage to uniquely identify the scheduling to cancel.



23/30


AssessmentResult message:

[GUID]



[Guid]

Match this ReceiptId value to the one provided in theAssessmentOrderAcknowledgment message to identify which candidate thismessage is being sent for

PXT3

The Profile field contains the assessment identifier for the results below.

12345

This Candidate ID value is not an effective means of uniquely identifying thisresponse. The Profiles Assessment Center user interface allows users to modifyCandidate IDs in our system. Any update to that information would be presentedhere. Use the ReceiptId above for unique identification of the Schedulingrequest.

2004-03-08

The EffectiveDate shows the date the candidate completed the assessment. Ifmultiple assessments were involved, this AssessmentResult message will not

have been automatically sent until all assessments are complete.

Assessmentstext/html

Joe SmithProfiles International Inc.2004-03-08


24/30


This dc:date is the date of the information in this SupportingMaterials node.

https://www2.profilesac.com/Assessments.aspx?cid=E9B0709D-

2475-4f1a-A583-77A2DDDA79EE

The InternetWebAddress is the URL that a client user could use to follow toretrieve additional information about this candidates results. The URL is secureand the user will be challenged to provide login credentials. This URL is not tobe given to the candidate.

Access URL

Overall Job Match651-100

The OverallResult node will only be available for Profiles assessments that usePerformance Models for comparison.

Thinking Style801-100

Behavioral Traits60

1-100

Interests501-100

Some Profiles assessments have additional percent match values available.Those values will appear as DetailResult nodes when available.

Distortion

1Distortion

Some Profiles assessments measure Distortion. When provided, a value of 1 ispassable. A value of 0 should be noted as the candidate may not haveanswered consistently and other scores should not be used in a hiring decision.


25/30


If multiple assessments were scheduled in a single Scheduling Template, thenadditional Results nodes will be returned in the AssessmentResult message.

SOS3

1237712882

2004-03-06Assessmentstext/html

Joe SmithProfiles International Inc.2004-03-06

https://www2.profilesac.com/Assessments.aspx?cid=E9B0709D-2475-4f1a-A583-77A2DDDA79EE

The InternetWebAddress is not specific to an assessment or scheduling andcould be stored once per candidate.

Access URL

Distortion

0Distortion

CompletedCandidate has completed the assessment2003-04-05

If the AssessmentResult message is sent automatically to your web service, thenthe status will be Completed. If you request status, you may also find the statusto be either Scheduled or InProgress. Other possible values are Cancelled

or Error.

en-us


26/30


Acknowledge message:

ShowAssessmentResult[GUID]

The MessageId value should be the value of your ConsumerId

[Guid]

The UniquePayloadTrackingId is the ReceiptId value.

[TodaysDate]

Three places in the Acknowledge message require a properly formated date timestamp string (example: 5/1/2008 8:30:52 AM)

[TodaysDate]

http://ns.hr-xml.org/2_5/HR-XML-

2_5/StandAlone/AssessmentResult.xsd

/AssessmentResult1AssessmentResult

[TodaysDate]



27/30


TESTING

When developing an Assessment Central implementation, Profiles International provides a set of

PubTest servers with which you can test and re-test your integration.

For successful testing, youll need to create a test environment that is available outside of yourfirewall.

Youll need to provide Profiles International with a URL of your callback Web Service (thathandles the ShowAssessmentResult HR-XML message) so that we can send younotifications when candidates complete their assessment.

Profiles International personnel needs to verify functionality before you can move your codeto production.

You cannot point your Production Application against our PubTest Assessment Central servers.The candidate results will be marked temporary and you could lose access to your candidates data,

so its important that you only point a Production Application against our Production AssessmentCentral servers.


28/30


APPENDIX A: VERSION HISTORY

APIVersion Release Date Description

1 3/24/2008 Initial Release. Based upon HR-XML Assessments v. 2.5


29/30


30/30

Last Updated: 5/4/2012 Page 30 of 30Copyright 2004 2009 Profiles International Inc

WEB SERVICES VS. POST

The HR-XML consortium has been around for a while and some of its standards pre-date WebServices as a protocol for inter-computer communication. As such the HR-XML Assessmentsversion 2.5 standard did not have an ratified Web Service interface. Our Web Service is based upon

their proposal for a Web Service interface. In both cases, the protocol is merely a transport for theHR-XML Assessments messages such as AssessmentOrderRequest.

ac sdk documentation

Documents