ampEducator:API

From ampEducator

Introduction

The ampEducator Web API (or web services) are a set of web services you can use to access your data in ampEducator in order to integrate with other application you may be using.

Getting Started

In order to start using the web services you must do two things.

Enable the web services under the Control Panel->Prefences modules.
Create a new user and assign the a 'Web Services' role. This user will be used to authenticate any requests you make through the web services. Note the username and password for this user as it is required.
Download or dynamically access the appropriate WSDL file through a programming language of your choice. ASP.NET, Java and PHP all have methods which can make accessing the web services easy.

Error Reporting

If something goes wrong processing your web services request, you will receive a SOAP Fault object containing the relevant details.

Web Services

If there are any methods which your institution requires and these are not available below please contact us.

Prospective Students

The prospective student services allows you to create, update and retrieve prospective students from ampEducator. The most common use of this web service is to add prospects into ampEducator from information forms on institution and lead generation websites.

WSDL File

The WSDL file for the prospective student web services can be found here:

https://PURL.ampeducator.com/ProspectWS?wsdl

where PURL is the unique identifier for your institution.

Methods

getProspect(String prospectID)

Returns a Prospect object from the ampEducator database using the prospect's unique id. See the example PHP code below. Note: The following PHP example uses the nuSoap toolkit.


//getProspect Method

<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $clientPURL, $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "password";


// Setup Endpoint and Namespace, no need to alter anything here

$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl";
$nameSpace = "http://webservices.ampeducator.amperea.com/";


// Get SOAP client and set authorization

$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");


// Prospects can be retrieved by ID only

$prospectID = "30"; 
$param = array('ProspectID'=>$prospectID);


// Submit to web service

$prospect = $soapclient->call('getProspect', $param, $nameSpace);

// If successfull you will get back a prospect object
// To access the object you can use it like an associative array

$FirstName = $prospect['firstName'];
$LastName = $prospect['lastName'];

?>

addProspect(Prospect prospect)

Adds a prospect to the ampEducator database and returns the prospect id as an int. The function will return 0 if the operation was not successfull. Only the 'First Name' and 'LocationID' of the prospect is required. Also see Configuration->Prospects for default values when fields are not included. Note: The following PHP example uses the nuSoap toolkit.


// addProspect Method

<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $clientPURL, $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "password";


// Setup Endpoint and Namespace, no need to alter anything here

$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl"
$nameSpace = "http://webservices.ampeducator.amperea.com/";

// Get SOAP client and set authorization

$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

 
// Setup prospect object - normally you would populate this from a form
// submitted on your website 

$prospect = array();

$prospect['firstName']="Test"; // Required
$prospect['middleName']=""; 
$prospect['lastName']=""; 
$prospect['addressOne']=""; 
$prospect['addressTwo']=""; 
$prospect['city']=""; 
$prospect['province']=""; 
$prospect['postalCode']=""; 
$prospect['country']=""; 
$prospect['phone']=""; 
$prospect['altPhone']=""; 
$prospect['dateofBirth']=""; 
$prospect['email']=""; 
$prospect['followUpDate']=""; // YYYY-MM-DD Format - This will add a follow up activity with this date
$prospect['heardThrough']=""; 
$prospect['sharedStatus']=""; 
$prospect['expectedDate']=""; // YYYY-MM-DD Format
$prospect['funnelStatus']=""; 
$prospect['locationID']="1"; // Required, normally 1 if single location


// Custom Fields
// 50 Character max, can be defined in ampEducator under Configuration
// Any date fields must be in YYYY-MM-DD Format

$prospect['customField1']=""; 
$prospect['customField2']=""; 
$prospect['customField3']=""; 
$prospect['customField4']=""; 
$prospect['customField5']=""; 
$prospect['customField6']=""; 
$prospect['customField7']=""; 
$prospect['customField8']=""; 
$prospect['customField9']="";
$prospect['customField10']=""; 
$prospect['customField11']=""; 
$prospect['customField12']=""; 
$prospect['customField13']=""; 
$prospect['customField14']=""; 
$prospect['customField15']=""; 
$prospect['customField16']=""; 
$prospect['customField17']=""; 
$prospect['customField18']=""; 
$prospect['customField19']=""; 
$prospect['customField20']=""; 
$prospect['customField21']=""; 
$prospect['customField22']=""; 
$prospect['customField23']=""; 
$prospect['customField24']=""; 
$prospect['customField25']=""; 
$prospect['customField26']=""; 
$prospect['customField27']=""; 
$prospect['customField28']=""; 
$prospect['customField29']=""; 
$prospect['customField30']=""; 

$param = array('Prospect'=>$prospect);

// Submit new prospect to web service
$response = $soapclient->call('addProspect', $param, $nameSpace);


// If successfull you will get back a ProspectID number otherwise you 
// will get back 0. From there users should be redirected accordingly.

if ($response==0) {

    echo "There was a problem adding the prospect.";

} else {

    echo "The prospect was successfully added with ID ".$response;

}


?>

updateProspect(Prospect prospect)

Returns a boolean indicating whether or not the update was successfull.

getHeardThroughList()

Returns the list of institution defined 'Heard Through' items in ampEducator. The web services will return an array of HeardThrough objects each one containing a value/option pair. See HeardThrough for reference. Note: The following PHP example uses the nuSoap toolkit.


<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "userpass";
 
// Setup Endpoint and Namespace, no need to alter anything here
$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl";

$nameSpace = "http://webservices.ampeducator.amperea.com/";
     
// Get SOAP client and set authorization
$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

// No params are necessary
$param = array();
     
// Submit to web service
$heardThroughList = $soapclient->call('getHeardThroughList', $param, $nameSpace);
  
// To create a select list iterate through each heard through list element
// Each element is an HeardThrough Object (2 fields, 'heardThroughValue' and 'heardThroughOption')

echo '<select name="HeardThrough">';

foreach($heardThroughList as $heardThrough) {

	echo '<option value="'.$heardThrough['heardThroughValue'].'">'.$heardThrough['heardThroughOption'].'</option>';

}

echo '</select>';


?>

getInterestedProgramList()

Returns the list of institution defined programs from ampEducator. The web services will return an array of InterestedProgram objects. See InterestedProgram for reference. Note: The following PHP example uses the nuSoap toolkit.


<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "userpass";
 
// Setup Endpoint and Namespace, no need to alter anything here
$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl";

$nameSpace = "http://webservices.ampeducator.amperea.com/";
     
// Get SOAP client and set authorization
$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

// No params are necessary
$param = array();
     
// Submit to web service
$programList = $soapclient->call('getInterestedProgramList', $param, $nameSpace);
  
// To create a select list iterate through each program list element
// Each element is an InterestedProgram Object (2 fields, 'programCode' and 'programName')

echo '<select name="InterstedProgramCode">';

foreach($programList as $interestedProgram) {

	echo '<option value="'.$interestedProgram['programCode'].'">'.$interestedProgram['programName'].'</option>';

}

echo '</select>';


?>

getProgramIntakeList(String programCode, String startDate, String endDate)

Returns the list of institution defined program intakes (i.e. program start dates) from ampEducator. The web services will return an array of ProgramIntake objects. Provided startDate and endDate must be in 'YYYY-MM-DD' format. See ProgramIntake for reference. Note: The following PHP example uses the nuSoap toolkit.


<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "userpass"; 
 
// Setup Endpoint and Namespace, no need to alter anything here
$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl";

$nameSpace = "http://webservices.ampeducator.amperea.com/";
     
// Get SOAP client and set authorization
$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

// 3 params are required
// programCode - the program code for the program we are requesting program intake dates for
// startDate - the start date of the date range we are looking for (YYYY-MM-DD format)
// endDate - the end date of the date range we are looking for (YYYY-MM-DD format)
$programCode = "BA";
$startDate = "2008-01-01";
$endDate = "2009-12-01";

$param = array('programCode'=>$programCode, 'startDate'=>$startDate, 'endDate'=>$endDate);
     
// Submit to web service
$programIntakes = $soapclient->call('getProgramIntakeList', $param, $nameSpace);
  
// To create a select list iterate through each program intake element
// Each element is an ProgramIntake Object 
// See reference for complete object description

echo '<select name="CustomField1">';

foreach($programIntakes as $programIntake) {

	echo '<option value="'.$programIntake['programIntakeID'].'">'.$programIntake['programIntake'].' ('.$programIntake['programIntakeDateDisplay'].')</option>';

}

echo '</select>';


?>

getCourseList(String locationID, String startDate, String endDate, String showPending)

Returns the list of active (and pending if desired) courses from ampEducator. The web services will return an array of CourseListItem objects. Provided startDate and endDate must be in 'YYYY-MM-DD' format and showPending can either be 'true' or 'false'. See CourseListItem for reference. Note: The following PHP example uses the nuSoap toolkit.


<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "userpass"; 
 
// Setup Endpoint and Namespace, no need to alter anything here
$endpoint = "https://".$clientPURL.".ampeducator.com/ProspectWS?wsdl";

$nameSpace = "http://webservices.ampeducator.amperea.com/";
     
// Get SOAP client and set authorization
$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

// 3 params are required
// locationID - the location id of the location where the courses we are requesting are - normally '1'
// startDate - the start date of the date range we are looking for (YYYY-MM-DD format)
// endDate - the end date of the date range we are looking for (YYYY-MM-DD format)
// showPending - whether or not to return courses with a 'Pending' status (true or false)
$locationID = "1";
$startDate = "2008-01-01";
$endDate = "2009-12-01";
$showPending = "true";
 
$param = array('locationID'=>$locationID, 'startDate'=>$startDate, 'endDate'=>$endDate, 'showPending'=>$showPending);
     
// Submit to web service
$courseItems = $soapclient->call('getCourseList', $param, $nameSpace);
  
// To create a select list iterate through each course item element
// Each element is an CourseListItem Object 
// See reference for complete object description

echo 'We received '.count($courseItems).' courses.<br/>';
 
echo '<select name="CustomField1">';

foreach($courseItems as $courseItem) {

	echo '<option value="'.$courseItem['courseID'].'">';
        echo $courseItem['courseCode'].' '.$courseItem['CourseName'].' ('.$courseItem['courseStartDisplay'].')';
        echo '</option>';

}

echo '</select>';


?>

Objects

Prospect

Unless otherwise stated, all fields are strings.

Fields
- FirstName
- MiddleName
- LastName
- DateofBirth (YYYY-MM-DD)
- AddressOne
- AddressTwo
- City
- Province
- PostalCode
- Country
- Phone
- AltPhone
- WorkPhone
- MobilePhone
- Email
- LocationID
- LocationName
- RecruiterID
- RecruiterName
- DateAdded (YYYY-MM-DD)
- HeardThrough
- InterestedProgram
- SharedStatus
- ExpectedDate (YYYY-MM-DD)
- FunnelStatus
- CustomField1
- CustomField2
- CustomField3
- CustomField4
- CustomField5
- CustomField6
- CustomField7
- CustomField8
- CustomField9
- CustomField10
- CustomField11
- CustomField12
- CustomField13
- CustomField14
- CustomField15
- CustomField16
- CustomField17
- CustomField18
- CustomField19
- CustomField20
- CustomField21
- CustomField22
- CustomField23
- CustomField24
- CustomField25
- CustomField26
- CustomField27
- CustomField28
- CustomField29
- CustomField30

HeardThrough

Fields
- heardThroughValue
- heardThroughOption

InterestedProgram

Fields
- programCode
- programName

ProgramIntake

Fields
- programIntakeID
- academicYearID
- programIntakeCode
- programIntake
- programIntakeDate (YYYY-MM-DD)
- programIntakeDateDisplay
- expectedEndDate (YYYY-MM-DD)
- expectedEndDateDisplay
- programCode
- deleted

CourseListItem

Fields
- courseID
- academicYearID
- academicYear
- locationID
- locationName
- courseCode
- courseName
- courseStart (YYYY-MM-DD)
- courseStartDisplay
- courseEnd (YYYY-MM-DD)
- courseEndDisplay
- courseDays
- courseHours
- courseCredits
- status
- totalTuition
- numEnrolled

Hour Clock

The hour clock web services allows you to tie in external applications to the built in ampEducator hour clock. Note: ampEducator already has a built in Hour Clock which works with a bar code scanner and id cards generated by the system.

WSDL File

The WSDL file for the hour clock web services can be found here:

https://PURL.ampeducator.com/HourClockWS?wsdl

where PURL is the unique identifier for your institution.

Methods

getCurrentDateTime()

Returns a string containing the current date and time of the hour clock in YYYY-MM-DD HH:MM:SS from ampEducator. Note: Currently the returned time is in Eastern Standard Time. Changes are underway to allow institutions to select their own time zone. The following PHP example uses the nuSoap toolkit.


// getCurrentDateTime

<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $clientPURL, $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "password";

// Setup Endpoint and Namespace, no need to alter anything here

$endpoint = "https://".$clientPURL.".ampeducator.com/HourClockWS?wsdl";
$nameSpace = "http://webservices.ampeducator.amperea.com/";

// Get SOAP client and set authorization

$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");

// No parameters are required

$param = array();

// Submit request to web service

$response = $soapclient->call('getCurrentDateTime', $param, $nameSpace);


// If succesfull you will get the date and time in YYYY-MM-DD HH:MM:SS format.

?>

singInOut(String id)

Returns an HourClockResponse object. The ID passed is the ID of the user (i.e. Student ID, Staff ID, Educator ID) appended by an 'S' for staff and 'E' for educator. ID Cards generated and scanned from ampEducator will automatically generate the correct ID. ampEducator automatically will determine whether or not the user is signing in or out. See Hour Clock Configuration for details on setting up hour clocks. Note: The following PHP example uses the nuSoap toolkit.


//signInOut

<?php

require_once('lib/nusoap.php');

// Setup variables, you will need to setup a user with a 'Web Service' role and
// replace the $clientPURL, $userName and $userPass below

$clientPURL = "demo";
$userName = "username";
$userPass = "password";


// Setup Endpoint and Namespace, no need to alter anything here

$endpoint = "https://".$clientPURL.".ampeducator.com/HourClockWS?wsdl";
$nameSpace = "http://webservices.ampeducator.amperea.com/";

 
// Get SOAP client and set authorization

$soapclient = new nusoap_client($endpoint);
$soapclient->setCredentials($userName, $userPass, "basic");


// You need to retrieve the user ID normally from a form submission

$id = $_REQUEST['id']; 
$param = array('id'=>$id);


// Submit id to web service
// The web service will automatically determine if this user is signing in or out.

$hourClockResponse = $soapclient->call('signInOut', $param, $nameSpace);


// If successfull you will get back an HourClockResponse object
// To access the object you can use it like an associative array

$TotalHours = $hourClockResponse['totalHours'];

?>

Objects

HourClockResponse

Fields
- responseCode (int)
- userId
- userName
- userType
- locationName
- dateTime
- dateTimeAdjusted
- totalHours
- totalWeeklyHours
- other
Response Code List
- 0 NONE
- 1 SIGNED_IN
- 2 SIGNED_OUT
- 3 CLOCK_CLOSED
- 4 ERROR_SIGNING_IN
- 5 ERROR_SIGNING_OUT
- 6 NO_HOUR_CLOCK_ASSIGNED
- 7 ERROR_UNKNOWN

ampEducator:API

From ampEducator

Contents

Introduction

Getting Started

Error Reporting

Web Services

Prospective Students

WSDL File

Methods

getProspect(String prospectID)

addProspect(Prospect prospect)

updateProspect(Prospect prospect)

getHeardThroughList()

getInterestedProgramList()

getProgramIntakeList(String programCode, String startDate, String endDate)

getCourseList(String locationID, String startDate, String endDate, String showPending)

Objects

Prospect

HeardThrough

InterestedProgram

ProgramIntake

CourseListItem

Hour Clock

WSDL File

Methods

getCurrentDateTime()

singInOut(String id)

Objects

HourClockResponse

Views

Personal tools

ampEducator Manual

Search

Toolbox