3. VidyoPortal API Overview

The VidyoPortal exposes a set of web services APIs that allow third parties to develop their own custom portals or endpoints based on Vidyo’s technology. These services are exposed via following SOAP/WSDL interfaces:

• VidyoPortalSuperService.wsdl
• VidyoPortalAdminService.wsdl
• VidyoPortalGuestService.wsdl
• VidyoPortalUserService.wsdl

One of the advantages of utilizing Vidyo’s Web Services Platform is the small number of APIs that are needed. Only a set of very basic and obvious APIs need be employed when interfacing the Conferencing Endpoint Subsystem to the Conferencing Middleware Subsystem hosted by Vidyo’s Web Services Platform.

The following sets of APIs are provided:

Super APIs – (com.vidyo.portal.super) – A set of super administrative APIs to manage tenants, licenses, and System components etc. as defined in this document. These APIs are restricted to authorized user with “super admin” privileges. These APIs can be used towards developing “super admin” tools.

Admin APIs – (com.vidyo.portal.admin) – A set of administrative APIs to manage members, rooms, gateways, etc. as defined in this document. These APIs are restricted to authorized users with “admin” or “operator” privileges. These APIs can be used towards developing “admin” tools.

Guest APIs – (com.vidyo.portal.guest) – A set of APIs for developing guest user functionality via Web Services API. The concept of Vidyo Portal Guest API is to allow temporary users to login, temporarily link to an endpoint client and join a conference. These guest users will be automatically deleted by the VidyoPortal once they leave the conference.

User APIs – (com.vidyo.portal.user) – A set of APIs for developing third party endpoints or applications targeted for end users, providing functionality like search, join meeting rooms, make direct calls, and so on, as defined in this document.

To start using the web services API, it’s important to understand the User Login process. An overview of the login process is included in this section.

Data Model

The data model for 2.x logically consists of Members, Rooms, Gateways, and legacy devices as illustrated in this figure:

Members — Members are users who have authorized accounts to use the portal. Members always use their login name and password for authentication. Members can originate/receive direct calls (also known as two party calls), join meeting rooms and they can be “invited” to meeting rooms. Members may have a display name and other parameters. Each Member belongs to a Group.

Rooms — Rooms are named conferences that members (or guests) may join, depending on the status, PIN, availability, etc. Rooms are of three types:

• Personal
• Public
• Scheduled

Each room has an owner. The owner can modify the room’s properties; control the conference when in session, etc. Each member has one personal room. When a member or a legacy device (via gateway) tries to reach a member with a personal room, they will have an option of either joining the personal room or placing a direct call to the member. Like members, Rooms may also have more descriptive display names. Rooms may also have multiple aliases for addressing purposes. For example, the unique names “alice meeting” and “2001” could both refer to the same meeting room, which has the display name “Alice Jones’ Meeting.”

Group — A group has a set of properties. All the members belonging to a group share these properties.

Gateways — Gateways are used to make and receive calls to external legacy devices that are not part of Vidyo Conferencing system. Calls to these legacy devices are identified by prefixes followed by the devices address. Based on the prefix, the request is routed to the appropriate gateway to bring a legacy device to the conference.

Guests — Guests do not belong to the system; however, they are allowed to join the room without any authentication. Guest can be invited to a meeting room by using Guest WS API.

Overview of Super APIs

This section describes the Super interface. Implicit in each request are authorization parameters (login and password) identifying the requester These APIs can be used towards developing “super admin” tools. Only members with the role defined as “Admin” are able to use these APIs.

VidyoPortal Super Service URL:

http://VIDYOPORTAL/services/VidyoPortalSuperService?wsdl

The following functionality is available under Super APIs:

Member Tenants Management

• Create a new Tenant
• Delete a Tenant
• Update a Tenant
• Get Tenant’s details—all or search based on matching prefixes
• Get list of tenants in the system

Other Methods

• Get system licenses
• Get list of service
• Delete Database
• Get System components
• Get IPC domain access control level
• Get allowed / blocked IPC Domains
• Set IPC control
• Add / Remove allowed IPC Domain
• Get router pool
• Get location tags

Overview of Admin APIs

This section describes the Admin interface. Implicit in each request are authorization parameters (login and password) identifying the requester These APIs can be used towards developing “admin” tools. Only members with the role defined as “Admin” are able to use these APIs.

VidyoPortal Admin Service URL:

http://VIDYOPORTAL/services/v1_1/VidyoPortalAdminService?wsdl

VidyoReplay Content Management Service URL:

http://VIDYOPORTAL/replay/services/VidyoReplayContentManagementService?wsdl

The following functionalities are available under admin APIs:

Member Account Management

• Create a new Member
• Delete a Member
• Update a Member
• List Member’s details—all or search based on matching prefixes

Meeting Room Management

• Create a Room
• Delete a Room
• Update a Room
• List Rooms — all or search based on matching prefixes

Group Management

• Create a Group
• Delete a Group
• Update a Group
• List Groups – all or search based on matching prefixes
• ListHeader
• ListHeader

The functionality available under the Admin > Settings tab like Shutdown, Restart, Upgrade Software, Changing IP address, adding Gateways, etc. are not exposed via web services APIs.

Record Control

• Start Recording
• Stop Recording
• Resume Recording
• Pause Recording
• Get Recording Profiles

Content Management

• Search Recorded File
• Update Recorded File
• Delete Recorded file

Webcasting

• Create Webcast URL
• Remove Webcast URL
• Get Webcast URL
• Remove Webcast Pin
• Get Recording Profiles

Using Search APIs

When using search APIs, follow these guidelines:

• Searches are not case sensitive.
• Hyphens and periods are delimiters that modify the query to only return exact matches for entire strings.
• Underscores are always treated as part of a string.
• All other special characters are treated as delimiters between strings.
• All strings in the query need to have a match for a record to be returned.

Overview of Guest APIs

This section describes the Guest APIs aimed at developing third party endpoints or applications targeted for end users providing functionality like login as a guest and Join the conference as defined in this section. Guest API methods do not require authorization parameters (login and password).

VidyoPortal Guest Service URL:

http://VIDYOPORTAL/services/VidyoPortalGuestService?wsdl

The following functionality is available under Guest APIs:

• Login as a guest
• Link EndPoint
• Join a Conference as a guest

Guest User Login Process Overview

Definitions — The following parameters are used as part of the Guest Login process:

• guestName
• roomKey
• Portal Access Key (PAK) — PAK is provided as part of login response by VidyoPortal
• EndpointID (EID) — A unique identifier representing an Endpoint. This is provided by the VidyoDesktop.
• guestID — A unique identifier representing a Guest within the VidyoPortal. This is provided as part of login response by VidyoPortal.

The following steps describe the sequence of events in the Guest Login process:

1. SOAP-Request from Application to VidyoPortal — LogInAsGuest (roomKey, guestName)
2. SOAP-Response from VidyoPortal to Application — LogInAsGuest (PAK)
3. For WS Application only:
1. HTTP-Request from Application to VidyoDesktop on 127.0.0.1:63457 with the following parameters:
• Redirect URL (URL): The VidyoDesktop provides response using a HTTP redirect. The application provides this Redirect URL and processes the information to retrieve the response parameters.
• VidyoManager (vm) address
• VidyoPortal (portal) service address
• VidyoProxy (proxy) address
• UN (UN):Temporary Username
• PAK (PAK): Portal Access Key
• For example:

http://127.0.0.1:63457/dummy?url=http://dev20.vidyo.com/linkendpoint.ajax?vm=P VCVG7NXUC5YER8FCXBC1ZD88NK6PQ7VYR2918XAXRQA600VM0001@dev20.vidyo.com:17992;transport=TCP&un=XpMgcsgdEl5z5vT8&pak=9YprUdCg8gPKpr5H&proxy=64.71.164.195:443&po rtal=http://main.vidyo.com/services/&loctag=Default_Location

2. HTTP-Redirect from VidyoDesktop to Application
• EID
• VidyoDesktop version
• ListHeader
4. For Custom Client and WS Application(unified client):

Note If you’re not developing a custom client using the VidyoClient Library please skip this section and go to step 4. The following steps are required usage of VidyoClient library.

1. Client API: Send VIDYO_CLIENT_IN_EVENT_SIGN_IN (LogInAsGuest response params)
2. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGN_IN
3. Check param.activeEid field to see if the EID is already set up

If the EID is not set up (equal NULL):

4. Client API: Send VIDYO_CLIENT_IN_EVENT_LICENSE
5. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_LICENSE
6. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGN_IN Returns activeEID (which should be active at this point-equal 1)
7. Client API: Send VIDYO_CLIENT_REQUEST_GET_EID Returns EID string
8. WS GuestAPI: LinkEndpointToGuest (guestID, EID)
• LinkEndpointToGuest (OK)
9. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_LINKED
10. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGNED_IN

Process complete. Wait a few seconds before joining the conference.

11. SOAP-Request from Application to VidyoPortal
• GuestJoinConference(guestID, pin)

Note To retrieve EID from you browser please run you client go to http://127.0.0.1:63457/?retrieve=eid.

5. SOAP-Request from Application to VidyoPortal
• LinkEndpointToGuest (guestID, EID)
6. SOAP-Response from VidyoPortal to Application
• LinkEndpointToGuest (OK)
7. SOAP-Request from Application to VidyoPortal
• GuestJoinConference(guestID, pin)

Overview of User APIs

This section describes the User APIs aimed at developing third party endpoints or applications targeted for end users providing functionality like search, join meetings rooms, make direct calls, etc. as defined in this section. Implicit in each request are authorization parameters (login and password) identifying the requester if any API method allows anonymous requests (e.g. allowing guests to join a meeting room), then the requester will be assumed to be Guest if the request does not contain credentials.

VidyoPortal User Service URL:

http://VIDYOPORTAL/services/v1_1/VidyoPortalUserService?wsdl

VidyoReplay Content Management Service URL:

http://VIDYOPORTAL/replay/services/VidyoReplayContentManagementService?wsdl

The following functionality is available under User APIs:

Member Account and Preference

• Get Member account details
• Update Member Account details

Member Speed Dial Settings

• Get Member’s Speed Dial list
• Update Member’s Speed Dial list

Search Operations

• List Members and status — all or search based on matching prefixes. If all is specified, the result set will be limited to a fixed maximum item and further queries are required to fetch rest of the items.
• List Rooms and status — all or search based on matching prefixes

Meeting Room and Direct Call

• Member LogIn so that the other Members will be able to invite and place direct calls to this Member.
• Member LogOut so that this member is not available anymore
• Place a Direct Call to other Member
• Join a Meeting Room
• Invite another Member to a Meeting Room

Room Settings and Control

• Generate a meeting room URI. Members and Guest users can follow this Uri link to join the meeting room.
• Delete the meeting room URI.
• Lock meeting room for restricting access to a meeting.
• Unlock meeting room for allowing access to a meeting.
• List participants in a given meeting.
• Disconnect participant from a given meeting. Deleting a room automatically disconnects the meeting room participants.
• Mute / Unmute audio for a given participant in a meeting.
• Start / Stop Video for a given participant in a meeting.
• Create or update PIN for a room.

Record Control

• Start Recording
• Stop Recording
• Resume Recording
• Pause Recording
• Get Recording Profiles

Content Management

• Search Recorded File
• Update Recorded File
• Delete Recorded file

Webcasting

• Create Webcast URL
• Remove Webcast URL
• Get Webcast URL
• Remove Webcast Pin
• Get Recording Profiles

Using Search APIs

When using search APIs, follow these guidelines:

• Searches are not case sensitive.
• Hyphens and periods are delimiters that modify the query to only return exact matches for entire strings.
• Underscores are always treated as part of a string.
• All other special characters are treated as delimiters between strings.
• All strings in the query need to have a match for a record to be returned.

User Login Process Overview — Definitions

The following parameters are used as part of the User Login process:

• Username (UN)
• Used in HTTP Authentication header for every WS API request. This is provided by the WS API application.
• Password (PW)
• Used in HTTP Authentication header for every WS API request. This is provided by the WS API application.
• Portal Access Key (PAK)
• PAK is provided as part of login response by VidyoPortal.
• EndpointID (EID)
• A unique identifier representing an Endpoint
• This is provided by the VidyoDesktop
• EntityID
• A unique identifier representing an Entity within the VidyoPortal
• This is provided as part of login response by VidyoPortal
• The EntityID is used follow web services API after login to represent any Entity in the VidyoPortal

The following steps describe the sequence of events in the User Login process:

1. SOAP-Request from Application to VidyoPortal: logIn (UN, PW)
2. SOAP-Response from VidyoPortal to Application: logIn (PAK)
3. HTTP-Request from Application to VidyoDesktop on 127.0.0.1:63457 with the following parameters:
• Redirect URL (URL): The VidyoDesktop provides response using a HTTP redirect. The application provides this Redirect URL and processes the information to retrieve the response parameters.
• VidyoManager (vm) address
• VidyoPortal (portal) service address
• VidyoProxy (proxy) address
• UN (UN): Username
• PAK (PAK): Portal Access Key
• For example:

http://127.0.0.1:63457/dummy?url=http://dev20.vidyo.com/linkendpoint.ajax?vm=PVCVG 7NXUC5YER8FCXBC1ZD88NK6PQ7VYR2918XAXRQA600VM0001@dev20.vidyo.com:17992;transport=T

CP&un=chetan&pak=9YprUdCg8gPKpr5H&proxy=64.71.164.195:443&portal=http://main.vidyo

.com/services/&loctag=Default_Location

4. HTTP-Redirect from VidyoDesktop to Application
• EID
• VidyoDesktop version

Note To retrieve EID from you browser please run you client go to: http://127.0.0.1:63457/?retrieve=eid

5. SOAP-Request from Application to VidyoPortal: linkEndpoint (UN, PW, EID)
6. SOAP-Response from VidyoPortal to Application: linkEndpoint (OK)
7. The Entity structure includes EntityID.

Note For guaranteed successful logged in process please check your endpoint status in web browser http://127.0.0.1:63457/?retrieve=epstatus. This will help to safely conclude if the endpoint change the status (online/busy/offline).

Getting the VidyoDesktop Version

Custom Application can retrieve the VidyoDesktop version and compare it with the VidyoDesktop which resides at VidyoPortal appliance in order to make a decision if VidyoDesktop Upgrade requires.

VidyoPortal version information is included into the HTTP redirect response from VidyoDesktop to the Custom Application (step 4 of the Sign in procedure).

For example:

HTTP Request:

HTTP Response:

First-Time license Implementation User Login Process

Note If you’re not developing a custom client using the VidyoClient Library please skip this section.

The following login steps are required usage of VidyoClient library. These steps should be followed only if you’re developing a custom client.

1. Client API: Send VIDYO_CLIENT_IN_EVENT_LOGIN (portal addr, username, passw)
2. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_LOGIN
3. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGN_IN
4. Check param.activeEid field to see if the EID is already set up.

If the EID is not set up:

1. Client API: Send VIDYO_CLIENT_IN_EVENT_LICENSE
2. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_LICENSE
3. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGN_IN Returns EID (which should be active at this point.)
5. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_LINKED
6. Client API: Wait for VIDYO_CLIENT_OUT_EVENT_SIGNED_IN Process complete. Wait a few seconds before joining the conference.

Note Check your endpoint status after login process complete.

7. Client API: Send VIDYO_CLIENT_REQUEST_GET_ENDPOINT_STATUS