webex-api-client

A node module to simplify interacting with Cisco WebEx XML-based APIs from the browser or server

🚨 Disclaimer 🚨

Due to the extent of the XML WebEx APIs, this repository is no longer being actively developed, and is given to be used "as-is". However, the innovation edge team will continue to take additional pull-request for fixes or new features, but we appologize for the inconvenience.

The nature of XML-based WebEx APIs requires the construction of many intricate XML elements, which can be tediuous to build in a robust, succinct fashion. The webex-api-client alleviates these pain points through a Builder that provides flatter and simplified objects to be used for XML construction. In addition, the client offers some level of validation for enumerated types, required properties, and value constraints to help prevent malformed request prior to being sent to the WebEx services.

Nutshell Features:

• ✅ Builder pattern to create complicated XML in a DRY and partial application fashion
• ✅ Some validation for XML values, constraints, and WebEx enumerated type
• ✅ Built-in parsers that provide simpler, flatter objects to create heavily nested, and redudant XML trees
• ✅ Robust and well-tested code built in a test-driven fashion with more than 95% coverage

Note:

Not all WebEx services are completely supported by the client, refer to Meeting Service for the available services. If there is something you would like to be added, submit a issue and we can consider it as a feature request developed by our team, otherwise we are open to taking additional Pull Requests for additional features :).

Install

$ npm install --save webex-api-client

Usage

Basic Usage: Get Site Information

const WebExClient = require('webex-api-client');
const securityContext = {
  webExID: 'Test User',
  password: 'pass123',
  siteName: 'hello-world'
};

const requestBuilder = new WebExClient.Builder(securityContext, 'https://hello-world.webex.com/WBXService/XMLService');

const getSite =
   requestBuilder
      .setService('GetSite')
      .build();
      
getSite.exec().then(console.log) // XML WebEx Site Information

Advance Usage: Create Meetings

const WebExClient = require('webex-api-client');
const securityContext = {
  webExID: 'Test User',
  password: 'pass123',
  siteId: 'hello-world'
};

const requestBuilder = new WebExClient.Builder(securityContext, 'https://hello-world.webex.com/WBXService/XMLService');

const createMeeting = 
  requestBuilder
    .metaData({
      confName: 'Sample Meeting',
      meetingType: 1,
    })
    .participants({
      attendees: [
        {
          name: 'Jane Doe',
          email: '[email protected]'
        }
      ]
    })
    .schedule({
      startDate: new Date(), // today
      openTime: 900,
      duration: 30,
      timezoneID: 5
    })
    .setService('CreateMeeting')
    .build();

// Initiate meeting whenever you are ready
createMeeting
  .exec()
  .then((resp) => console.log('success'));

Builder(securityContext, serviceUrl)

const Builder = new Client.Builder(securityContext, serviceUrl)

Returns a request object that is executed with .exec()

securityContext

Type: object

WebEx Security Context (securityContext)

Using a SessionTicket from Common Identity Webex Teams site

First use an oauth2 flow from Webex Teams integration to obtain a token. This user will need to be an administrator of the webex meeting site.

Use that token below to get a session token from the webex meetings api.

const getSessionToken =
   requestBuilder
      .accessToken('token from common identity webex teams user, previously generated from oauth2 flow')
      .setService('AuthenticateUser')
      .build();

getSessionToken.exec().then(console.log);

This token will be used as sessionTicket in the security context headers.

serviceUrl

Type: string

The url for the WebEx service for the request to be sent to

build()

Construct the final XML and returns a Request

Builder XML WebEx Elements

All XML WebEx elements are passed a JSON representation of the XML equivalent unless specified, please refer to the schemas provided for more details. To prevent deeply nested JSON, specific methods will document simpler expected structures that will be converted by the Builder.

Element Method Signature

Builder.elementName(XMLObj)

accessControl

XML Schema

assistService

XML Schema

attendeeName

XML Schema

attendeeOptions

XML Schema

enableOptions

XML Schema

fullAccessAttendees(attendees)

XML Schema

attendees

Type: array of modified attendee

limitedAccessAttendees

XML Schema

attendees

Type: array of modified attendee

listControl

XML Schema

order(listOfOrderSettings)

XML Schema

listOfOrderSettings

Type: array of order settings { orderBy, orderAD }
Example:

[
  {
    orderBy: 'STATUS',
    orderAD: 'DESC'
  },
  {
    orderBy: 'HOSTNAME',
    orderAD: 'ASC'
  }
]

metaData

XML Schema

meetingKey

XML Schema

order(input)

XML Schema

Input

Type: array containing { orderBy: ENUM_VALUE, orderAD: ENUM_VALUE } Example:

// Input Example
[
  {
    orderBy: 'STATUS',
    orderAD: 'ASC'
  }
]

participants

XML Schema

XMLObj.attendees

Type: array of modified attendee
Example:

attendees: [
  {
    name: 'James Kirk',
    email: '[email protected]',
    joinStatus: 'REGISTER'
  },
  {
    email: '[email protected]',
    name: 'Jane Doe',
    firstName: 'Jane',
    lastName: 'Doe',
    notes: 'Testing',
    joinStatus: 'INVITE'
  }
]

repeat

XML Schema

XMLObj.expirationDate

Type: Date, RFC 2822, ISO-8601
Example: new Date()

XMLObj.dayInWeek

Type: Array of Day
Example: ['MONDAY', 'TUESDAY', 'THURSDAY']

remind

XML Schema

XMLObj.emails

Type: Array of emails
Example: ['[email protected]', '[email protected]']

sessionKey

XML Schema

schedule

XML Schema

telephony

XML Schema

teleconference

Not all required properties are validated
XML Schema

tracking(input)

XML Schema

input

Type: Array of trackingCodes
Example: ['1', 'code231', 'code4516', '3']

Modified Types

Attendee

The attendeeType has a nested person object, in the client, this is denested and abstracted for easier use.

Properties:

• name
• firstName
• lastName
• title
• company
• webExID
• address
• phones
• email
• notes
• url
• type
• sendReminder
• joinStatus

XML Misc Options

setEncoding(encoding)

encoding

Type: ENUM

Any of the following encodings: 'UTF-8', 'ISO-8859-1', 'BIG5', 'Shift_JIS', 'EUC-KR', 'GB2312'.

setService(WebExService)

Type: ENUM

A matching WebEx service type, currently webex-api-client only supports the following:

Meeting Service

• CreateMeeting
• DelMeeting
• GethosturlMeeting
• GetjoinurlMeeting
• GetMeeting
• GetTeleconferenceSession
• SetMeeting
• LstsummaryMeeting
• GetSite

Request

exec()

Executes the XML request and sends it to the serviceUrl

toBuilder()

Return to Builder retaining all elements used during construction

Example Usage:

const WebExBuilder = Client.Builder(accessControl, 'http://test.webex.com/')
const FirstMeeting = WebExBuilder
                      .metaData({
                        confName: 'First Meeting'
                      })
                      .schedule({
                        startDate: new Date(2017, 0, 20),
                        openTime: 100,
                        duration: 20
                      })
                      .setService('CreateMeeting')
                      .build();
										
const SecondMeeting = CreateMeeting
                      .toBuilder()
                      .metaData({ confName: 'Second Meeting' })
                      .build();

// Create both meetings
const f1Promise = FirstMeeting.exec();
const f2Promise = SecondMeeting.exec();

// Log when both meetings are created
Promise.all([f1Promise, f2Promise])
  .then((responses) => { console.log('meetings created!') })
  .catch(console.log);

newBuilder([securityContext, serviceUrl])

Destroys the previous builder with all XML elements, and returns a new Builder object with the existing security context and service url set. This can be overridden by the optional parameters passed in.

Example Usage:

const WebExBuilder = Client.Builder(accessControl, 'http://test.webex.com/');
const CreateMeeting = WebExBuilder
                        .metaData({
                          confName: 'First Meeting'
                        })
                        .schedule({
                          startDate: new Date(2017, 0, 20),
                          openTime: 100,
                          duration: 20
                        })
                        .setService('CreateMeeting')
                        .build();

const delMeeting = CreateMeeting
                    .newBuilder()
                    .meetingKey(12345)
                    .setService('DelMeeting')
                    .build();

delMeeting.exec();

Related

If you found this client useful, don't forget to star this repository and check other related open-source Cisco modules by the Innovation Edge team:

• cisco-tp-client - A node API client to ease interactions with Cisco WebEx Telepresence-enabled endpoints / codecs.
• rrule-to-webex - Converts a RRULE (iCalendar RFC-5545) to Cisco's WebEx recurrence repeat XML tree.
• webex-time-zones - 🌐 An enumerated list of Cisco WebEx supported time zones
• webex-date - 🕰 Convert a JavaScript date type, RFC 2822, ISO-8601 to the WebEx XML API supported format.
• webex-enum-types - 🍭 A JSON mapping of enumerated types for Cisco's WebEx XML API

License

MIT © Cisco Innovation Edge