Conference Service V5.0

Conference Service v5.0

Web Service Usage

Contents

Introduction 2

Web Service Calls – Basic Information 2

UsernameToken 2

Video Conference Creation 2

Requestor Information 3

Conference & Site Details 3

Producer Assisted and Monitored 3

Endpoint Connect 4

Bridge Connect 5

Self Service 6

Room Reservation 7

Conference Series 7

Daily 7

Weekly 7

Monthly 8

Video Conference Update 8

Video Conference Cancel 9

Example Video Conference Creation Soap Call 9

Supporting Operations 10

retrieveConference 10

retrieveInitialSetup 11

retrieveProfile 11

retrieveBillingAllocations 11

retrieveSiteList 11

retrieveFavoriteSites 11

retrieveSite 11

retrieveReservations 11

retrieveConfTypes 12

retrieveConfOptions 12

retrieveEOptions 12

createRequester 12

Introduction

The Conference Service Web Service supports the management of Video Conferences at BT Conferencing. The Web Service is used predominately to create, update and cancel Video Conference reservations at BT Conferencing.

Conference reservation creation requires multiple pieces of information. The Web Service can supply many parts of this information such as Site details and User Profile information, but there will be some information required by the user. Also before the Web Service can be used, manual configuration will be required at BT.

This documentation is to be used in conjunction with the other web services documentation:

· WSDL

o WSDL structure

o Valid Values

§ List of enumerated types required by specific fields in the WSDL

o Validation Issues

§ List of error messages returned by the Web Service

o WSDL Documentation

§ Explanation of each field in the WSDL

Below are instructions on how to successfully use the Web Service to manipulate Video Conferences.

Web Service Calls – Basic Information

Before the Web Service may be used to create data in the BT conference management system (Onward), the user of the Web Service must be configured in Onward. This will be a manual process performed with your BT liaison. Once this is done, the user will be supplied with authentication information (username and password) to be used with each Web Service call.

UsernameToken

The authentication information will be placed in a UsernameToken component and passed as the first part of every Web Service call (see example of the soap call below).

Video Conference Creation

To create a Video Conference reservation in Onward, the “createConference” operation is called and the following basic elements are required:

· Requestor Information

· Conference Features

· Site Details

Requestor Information

The Requestor is the individual who is requesting the conference. There are three ways to identify this individual:

1. System Id*

a. This is the numeric id given to the requestor if they have been previously set up in Onward

2. Customer Reference Id*

a. This is the alphanumeric id defined by the requestor and stored in Onward

3. Auto Provisioning

a. If the company of the requestor is setup in Onward to support auto provisioning, the requestor does not need to be previously setup in Onward. Note the individual’s time zone will be set to that of the conference being created. The following information can be passed to the Web Service and the individual will then be setup in Onward:

i. First Name

ii. Last Name

iii. Email Address

iv. Country Code

v. Base Phone number

vi. Time Zone

* The requestor will require a login with the “Web Service” Service to use a Person Profile. If the requestor does not have the Web Service login, the Company Profile will be used.

Conference & Site Details

The conference type is the ‘driver’ for the creation of a conference. It determines what set of features are available and required for a conference. Below is a description of how features should be set on a conference based on conference type.

· Leg Allocations

o Leg Allocations are descriptive records frequently used to track information about the Site during a conference. The most common example is for Travel Savings, ’Number of Participants saving a Flight’.

o Leg Allocations may include a list of acceptable values for validation.

Producer Assisted and Monitored

This type of conference requires assistance from a producer. The following features are available, the features marked with a single asterisk are always required and features marked with a double asterisk are not used, thus do not need to be set, if the “autoBuild” flag is set:

· conferenceName*

· conferenceType = “Producer Assisted and Monitored”

· conferenceMode**

· beginDateTime*

· useDaylightSavingsRuleYN*

· conferenceDuration*

· setupDuration

· monitoring*

· greeting

· autoExtendDuration

· specialInstructions

· conferenceRequestor*

o see Requestor Information above

· billingAccountId

· billingAllocations

o allocationType*

o allocationValue*

· audioParticipantCount

· timezone*

· entryexitTone

· endWarningTone

· videoRecording

· videoMediaType

· audioMediaType

· numOfCopy

· shipMethod

· shipAddress

· autoBuild

· dcpTypes

· conferenceSites*

o customerSpecifiedSiteID or systemSiteID*

o hostSiteYN (required for only one site in conference)

o transmissionRate**

o dialDirection**

o catering

o isIP

o participant

o Leg Allocations

Endpoint Connect

This is a self service conference with no conference producer support. This conference will have 2 sites that connect directly to each other. The following features are available, the features marked with an asterisk are required:

· conferenceName*

· conferenceType = “Endpoint Connect”

· conferenceMode*

· beginDateTime*

· useDaylightSavingsRuleYN*

· conferenceDuration*

· setupDuration

· autoExtendDuration

· specialInstructions

· conferenceRequestor*

o see Requestor Information above

· billingAccountId

· billingAllocations

o allocationType*

o allocationValue*

· timezone*

· launchNow

· entryexitTone

· endWarningTone

· telepresenceSwitchingPolilcy (required if telepresence conference)

· telepresenceVideoAnnounce

· conferenceSites*

o customerSpecifiedSiteID or systemSiteID*

o hostSiteYN (required for only one site in conference)

o transmissionRate*

o dialDirection*

o catering

o isIP

o participant

Bridge Connect

This is a self service conference with no conference producer support. This conference will have either more than 2 sites, or if only two site, the sites are not Endpoint Connect capable. The following features are available, the features marked with an asterisk are required:

· conferenceName*

· conferenceType = “Bridge Connect”

· conferenceMode*

· beginDateTime*

· useDaylightSavingsRuleYN*

· conferenceDuration*

· setupDuration

· autoExtendDuration

· specialInstructions

· conferenceRequestor*

o see Requestor Information above

· billingAccountId

· billingAllocations

o allocationType*

o allocationValue*

· audioParticipants

· timezone*

· launchNow

· entryexitTone

· endWarningTone

· telepresenceSwitchingPolilcy (required if telepresence conference)

· telepresenceVideoAnnounce

· conferenceSites*

o customerSpecifiedSiteID or systemSiteID*

o hostSiteYN (required for only one site in conference)

o transmissionRate*

o dialDirection*

o catering

o isIP

o participant

o Leg Allocations (if required)

Self Service

When this conference type is selected, the minimal amount of information is needed. This will use the requestor’s profile to determine what type of conference to create. The following features are available, the features marked with an asterisk are required:

· conferenceName*

· conferenceType = “Self Service”

· beginDateTime*

· useDaylightSavingsRuleYN*

· conferenceDuration*

· specialInstructions

· conferenceRequestor*

o see Requestor Information above

· billingAccountId

· billingAllocations

o allocationType*

o allocationValue*

· audioParticipants

· timezone*

· launchNow

· autoBuild*

· conferenceSites*

o customerSpecifiedSiteID or systemSiteID*

o hostSiteYN (required for only one site in conference)

o participant

o Leg Allocations (required depending on the company configuration)

Room Reservation

This type of conference reserves the sites but does not create a Video conference. The following features are available, the features marked with an asterisk are required:

· conferenceName*

· conferenceType = “Room Reservation”

· beginDateTime*

· useDaylightSavingsRuleYN*

· conferenceDuration*

· conferenceRequestor*

o see Requestor Information above

· timezone*

· autoBuild (available but not effective)

· conferenceSites*

o customerSpecifiedSiteID or systemSiteID*

o hostSiteYN (required for only one site in conference)

o catering

o participant

Reserve Dial (aka GVE Reserve Dial)

Reserve Dial conferences allow hosts to include participants from other business entities. Reserve Dial conferences are either of type ‘host’ or ‘invitee’, with ‘host’ Reserve Dial conferences using BT Bridge resources, and ‘invitee’ using another Reserve Dial host bridge resources. Reserve Dial conferences are currently only of the ‘Self Service’ conference type, and the ‘autobuild’ flag must be true.

The number of external participant sites is required to create a Reserve Dial ‘host’ conference, with a Dial In access Number and Participant Code returned following a successful conference creation. An Access Number and Participant Code are required to create a Reserve Dial ‘invitee’ conference. Please note that during the Reserve Dial ‘invitee’ conference creation, the Access Number and Participant Code and conference start time may be validated.

The SiteInfo object contains a flag gveRDCapable, which must be true to include a site in a Reserve Dial conference. The type ‘GveReserveDIalDefinition’ must be set in the Conference object, and the ‘gveReserveDial’ must be true. The following elements are required in the Conference object:

· gveReserveDial* = ‘true’

· gveReserveDialDefinition

o type = ‘host’ or ‘invitee’

o hostNumberInvitees = <number> (required for a ‘host’ conference’)

o inviteeAccessNumber = E164 dial-in number (required for a ‘invitee’ conferece)

o inviteeParticipantCode = Access number from Reserve Dial provider

Conference Series

To create a recurring series of conferences, the RecurrencePattern component must be populated. There are three types of recurrence patterns that can be created. Below explains how the RecurrencePattern component should be populated for each type of recurrence.

Daily

The following elements are available; the elements marked with an asterisk are required:

· recurrenceType = “Daily”

· beginDate*

· (endDate or numberOfConferences)*

· dailyWeekdaysOnly

Weekly

The following elements are available, the elements marked with an asterisk are required:

· recurrenceType = “Weekly”

· beginDate*

· (endDate or numberOfConferences)*

· frequency

· weeklyDays

Monthly

The following elements are available, the elements marked with an asterisk are required:

· recurrenceType = “Monthly”

· beginDate*

· (endDate or numberOfConferences)*

· frequency

· (monthlyDate or monthlyWeekNumber)*

· monthlyWeekDay

Video Conference Update

To update a conference, the “updateConference” operation is called and the same information that is sent in during a conference create must be sent to the Web Service, not just the changed elements. See “Conference & Site Details” above for elements needed per conference type. Also the systemConferenceID or customerSpecifiedConferenceID of the conference is required.

To update a single conference is a series, the “updateConference” operation is called, passing the same conference detail as discussed above. But instead of passing in the conference id, pass in the systemConferenceSeriesID and the beginDate of the conference. Please note that a single conference of a series cannot change the date of the conference since the date passed in is used to look up the conference (if the date is changed, the system will not be able to find the conference). The time can be changed.

To update a series of conferences, the “updateSeries” operation is called and the same information that is sent in during a series create must be sent to the Web Service, not just the changed elements. See “Conference & Site Details” above for elements needed per conference type. The systemConferenceSeriesID is required to identify the series.

Also needed is the “beginDate” of the first conference in the series to be updated. For example, if the last 3 conferences of a series of 5 conferences need to be updated, the beginDate of the 3rd conference in the series is required.

Note that conference series cannot be updated when the “autoBuild” flag is set.

For both operations, the requestor information is required as described in “Video Conference Creation”.

Video Conference Cancel

To cancel a single conference, the “cancelConference” operation is called and only one of the following elements is required:

· systemConferenceID or customerSpecifiedConferenceID

To cancel a single conference is a series, the “cancelConference” operation is called, passing the systemConferenceSeriesID and the beginDate of the conference.

To delete a series of conferences, the “cancelSeries” operation is called and the following elements are required:

· systemConferenceSeriesID

· beginDate^

^The “beginDate” specifies the first conference in the series to be deleted. All conferences occurring after that date will also be deleted.

For both operations, the requestor information is required as described in “Video Conference Creation”.

Example Video Conference Creation Soap Call

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="http://www.conferencesetup.com/wsdl" xmlns:types="http://www.conferencesetup.com/wsdl/encodedTypes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<tns:createConference>

</tns:createConference<q1:UsernameToken id="id1" xsi:type="q1:UsernameToken" xmlns:q1="http://www.conferencesetup.com/types">

<username xsi:type="xsd:string">webserviceuser</username>

</q1:UsernameToken<q2:Conference id="id2" xsi:type="q2:Conference" xmlns:q2="http://www.conferencesetup.com/types">

<conferenceName xsi:type="xsd:string">Testmeeting</conferenceName>

<conferenceType xsi:type="xsd:string">Producer Assisted and Monitored</conferenceType>

<conferenceMode xsi:type="xsd:string">Voice Activated</conferenceMode>

<useDaylightSavingsRulesYN xsi:type="xsd:boolean">false</useDaylightSavingsRulesYN>

<monitoring xsi:type="xsd:string">Scanned Monitoring</monitoring>

<greeting xsi:type="xsd:string">Greet Each Site By Video</greeting>

</q2:Conference<q3:Requester id="Requester1" xsi:type="q3:Requester" xmlns:q3="http://www.conferencesetup.com/types">

<lastName xsi:type="xsd:string">Smith</lastName>

</q3:Requester<soapenc:Array id="id3" xmlns:q3="http://www.conferencesetup.com/types" soapenc:arrayType="q3:BillingAllocation[2]">

</soapenc:Array<q5:BillingAllocation id="BillingAllocation1" xsi:type="q5:BillingAllocation" xmlns:q5="http://www.conferencesetup.com/types">

<allocationType xsi:type="xsd:string">Cost Center</allocationType>

</q5:BillingAllocation<q6:BillingAllocation id="BillingAllocation2" xsi:type="q6:BillingAllocation" xmlns:q6="http://www.conferencesetup.com/types">

<allocationValue xsi:type="xsd:string">Jim Smith</allocationValue>

</q6:BillingAllocation<soapenc:Array id="id4" xmlns:q4="http://www.conferencesetup.com/types" soapenc:arrayType="q4:ConferenceSite[2]">

</soapenc:Array<q7:ConferenceSite id="Site1" xsi:type="q7:ConferenceSite" xmlns:q7="http://www.conferencesetup.com/types">

<hostSiteYN xsi:type="xsd:boolean">false</hostSiteYN>

<dialDirection xsi:type="xsd:string">Site Receives</dialDirection>

</q7:ConferenceSite<q8:ConferenceSite id="Site2" xsi:type="q8:ConferenceSite" xmlns:q8="http://www.conferencesetup.com/types">

<dialDirection xsi:type="xsd:string">Site Receives</dialDirection>

</q8:ConferenceSite</soap:Body</soap:Envelope>

Supporting Operations

The Web Service contains Operations used to gather data that support the management of conferences.

retrieveConference

This will retrieve information about a conference stored in Onward. The Conference component will be fully populated. Only the “systemConferenceID” or the “customerSpecifiedConferenceID” is required.

retrieveInitialSetup

Based on requestor id, the following information is returned. The requestor id is the requestor’s system id stored in Onward.