Image by Freestock

The access classes provide an easy way to make use of the BeaconLive SOAP interface for applications written in PHP5. You can purchase the right to use them for a modest fee – please contact us for details.  The classes require no knowledge of SOAP and use the PHP SOAP extension (which must be installed).  The major actions are handled by the conflinkBeaconRequests class.  A set of classes is provided for the objects that are relevant to the BeaconLive interface, namely conferenceWs, registrantWs, attendantWs.  The classes incorporate validation and any errors result in a SoapFault exception being thrown.

Common Features of the BeaconLive Objects

A new instance of any of the objects can be created using the standard PHP new construct.  This must only be done after an instance of conflinkBeaconRequests has been created using new.  The object will have properties of a suitable type, that is to say integers are set to zero, strings are set to a null string, and booleans are set to the most likely boolean value for most purposes.  This means that they may be invalid for use with BeaconLive, but see the setDefaults method below.  All the properties are public.  Any of the legitimate properties for a BeaconLive object can be set using standard PHP code, but where appropriate, the value will be validated.  An assignment that fails validation or is to an invalid property will cause a SoapFault exception to be thrown.  All use of the classes should be done within a try block.  There are two methods implemented by each of the BeaconLive objects:

setDefaults requires no parameters and will set a legal default value for any field that is validated.  The defaults are AccessType = ‘ValidPIN’, ConferenceType = ‘AudioWeb’, CallerRole = ‘Participant’, SessionType = ‘Web’.  For detail on which default applies to which object, please review the BeaconLive WSDL.

enclass is a static method, and requires a single parameter that is an object.  It will create a new object from the class to which it is applied.  Wherever the provided object has a property that has the same name as a property of the new object, the value is transferred.  Note that this could cause an exception because validation is applied.  The new object is returned.  For example, the following code will assign to $conference an object of the conferenceWs class that uses any relevant data in the $confdata object supplied as a parameter:

$conference = conferenceWs::enclass($confdata);

The conflinkBeaconRequests Class

This class should be instantiated before any of the other classes is used.  A configuration object must be provided as the sole parameter.  For example, you could write:

$requestor = new conflinkBeaconRequests($config);

The configuration object should have properties similar to those generated by applying the PHP function json_decode to the following JSON string (although JSON does not have to be used to create the configuration object it is one possibility):

{
        "wsdl": "http://38.101.246.154:8080/EcProvWs/EcProvWs?wsdl",
        "namespace": "http://ws.ecprovws.bcs.com/",
        "authHeader": "ecProvAuthHeader0",
        "clientId": "abcdT100",
        "clientKey": "abcdW0510@bcs02bl",
        "organizationAlias": "abcdTst",
        "startTimeComment": "The value shown below is only a placeholder",
        "startTime": "2010-01-01",
        "endTime": "2030-12-31",
        "historyDays": "7",
        "baseWebinarURL": "http://66.77.138.124/join?jrd="
}

The keys are the left hand item on each line, and are the names of the properties that must be set in the configuration object. The values are the right hand items and should be set correctly for the particular application, including the use of information provided by BeaconLive.

Once the conflinkBeaconRequests object has been created there are methods that provide for all the main functions of the BeaconLive SOAP interface.  Please note that the code will report any error conditions by throwing a SoapFault exception, so all your code should be within a try block.  The actual PHP SOAP interface can also raise SoapFault exceptions.  Note that all results from these methods are BeaconLive objects.  The methods are:

getConferences ($startDate=”, $endDate=”) will return an array of conferenceWs objects (possibly an empty array) that are within the specified date (and time) range, if specified.  If $endDate is not specified then the value from the configuration object will be used.  If $startDate is not specified, it will be computed by taking today’s date and subtracting the number of days given in the configuration item “historyDays”.

getConference ($conferenceId) should be passed an integer and will return a conferenceWs object that is the conference with the given ID, or is a default conferenceWs object.

getRegistrants ($conferenceId) should be passed an integer and will return an array of registrantWs objects (which could be empty) that are the registrants for the identified conference.

getConferenceReport ($conferenceId) behaves very like getRegistrants except that it is used for a conference that has finished, and returns an array of attendantWs objects.

createConference (conferenceWs $conference) should be passed a conferenceWs object, and will create a conference at BeaconLive.  It returns a conferenceWs object that has additional values, assigned by BeaconLive when a conference is created.

updateConference (conferenceWs $conference) takes a conferenceWs object and updates the conference at BeaconLive that matches the given object.

deleteRegistrant ($registrantId, $conferenceId, $pin) has to be passed the ID number of the registrant to be deleted, along with the ID number of the conference and the registrant’s PIN.

createRegistrant (registrantWs $registrant) adds a new registrant at BeaconLive and has to be given a registrantWs object as its parameter.

makeBeaconURL (registrantWs $registrant, conferenceWs $conference) requires a registrantWs object and a conferenceWs object, and from these will compute the URL that should be used by the registrant to access the conference and automatically log in.

Example Code

A simple (incomplete, purely for illustration) example of using the classes is:

try {
    $config = json_decode($configstring);
    $requestor = new conflinkBeaconRequests($config);
    $conference = new conferenceWs();
    $conference->title = 'My Latest Conference';
    // Other properties may need to be set
    $conference->setDefaults();
    $newconference = $requestor->createConference($conference);
    $registrant = registrantWs::enclass($localregistration);
    $registrant->conferenceId = $newconference->id;
    // Other properties may need to be set
    $requestor->createRegistrant($registrant);
    // Report success by some means
}
catch (SoapFault $exception) {
    // Report failure, probably mentioning $exception->getMessage() for the reason
}