card meeting data exchange

8/2/2019 Card Meeting Data Exchange

1/29

V3.00

Author: Dave Woldrich

Copyright 2008, Woldrich, Inc.All Rights Reserved CardMeeting Data Exchange

Table of Contents

1 Introduction.............................................................................................................................................................2

2 CardMeeting Web Site Import and Export Features................................................................................................2

2.1 Navigating on the CardMeeting.com web site to the import/export tools........................................................2

2.2 Excel Exporter....................................................................................................................................................4

2.3 XML Exporter....................................................................................................................................................4

2.4 XML Importer....................................................................................................................................................4

3 CardMeeting Web Services.......................................................................................................................................6

3.1 JAX-WS in CardMeeting Web Service client examples...................................................................................6

3.2 SOAP-over-HTTP Web Service API.................................................................................................................7

3.2.1 SOAP operation: Export Meeting to XML..............................................................................................7

3.2.2 SOAP operation: Import XML into already existing CardMeeting........................................................9

3.2.3 SOAP operation: Number of users currently logged in.........................................................................12

3.3 XML/HTTP Web Service API (RESTful Web Service).................................................................................13

3.3.1 REST operation: Export Meeting to XML.............................................................................................143.3.2 REST operation: Import XML into already existing CardMeeting.......................................................16

3.3.3 REST operation: Number of users currently logged in.........................................................................20

4 Embedding the CardMeeting Applet In Your Application.....................................................................................23

Appendix A: Compiling WSDL to Java with JAX-WS...........................................................................................25

Appendix B: Compiling XSD to Java with JAXB....................................................................................................26

Appendix C: Terms and Conditions for using CardMeeting Third Party Integration API Services.......................28

Summary of Changes

Date Version Changes

01/15/07 1.00 First public version

01/20/07 2.00 Added RESTful Web Services to the API

01/21/07 2.01 Minor typographical and layout errors fixed

03/09/08 3.00 Document renamed/expanded: now also describes user import/export on website

Proprietary and Confidential Page 1

Woldrich, Inc CardMeeting


2/29

1 Introduction

It is not reasonable in today's complex, interconnected world to expect computer software to meet everyone's

requirements. CardMeeting was designed with openness in mind so that the data within meetings can be moved

into and out of the system. CardMeeting has been designed such that:

Users can get their data into and out of CardMeeting in various useful file formats (see Section 2.)

Third-party software developers can integrate their solutions directly with CardMeeting using Web

Services (see Section 3.)

The CardMeeting Applet itself can be embedded into other web applications such that it will appear on

third-party webpages (see Section 4.)

CardMeeting is a product of Woldrich, Inc., and it can be accessed at CardMeeting.com.

2 CardMeeting Web Site Import and Export Features

Any user may utilize tools available on the CardMeeting web site to import and export data from their

CardMeetings. The tools currently available represent common and easy to fulfill feature requests and are by no

means complete. Please [email protected] to discuss what your requirements look like and whether

data importers/exporters that you need are planned additions to future versions of CardMeeting.

2.1 Navigating on the CardMeeting.com web site to the import/export tools

All additional tools for manipulating your CardMeetings lie on the Community Meeting List page. You can reach

this page from the main http://CardMeeting.compage. Scroll down, and find the dark green area on the left

entitled, I want to see a list of all of my community's CardMeetings. Provide your Community's ID (of the

format Cnnnn) and Community password in the form and click List CardMeetings (see .)

Once you have gotten the listing of Meetings, an array of import and export tools are presented on the right hand

side of the page (see Figure 1.) Click the link to the file format of your choice to perform the import or export

operation.

IMPORTANT NOTE ABOUT USAGE: It is against the CardMeeting terms of service to use any automation or

scripted tools to access the CardMeeting web pages. Automated or scripted tools that integrate with CardMeeting

may do so only via the CardMeeting Third Party Integration Web Services (which are described in this document

starting with Section 3, CardMeeting Web Services.)


http://cardmeeting.com/http://cardmeeting.com/mailto:[email protected]:[email protected]://cardmeeting.com/http://cardmeeting.com/mailto:[email protected]://cardmeeting.com/http://cardmeeting.com/


3/29

Figure 1: CardMeeting.com webpage, community meeting list input form

Figure 2: CardMeeting Listing Page, Import/Export tools on the right




4/29

2.2 Excel Exporter

CardMeeting can export your meeting contents as an Excel spreadsheet. The spreadsheet contains useful

information from each card in your meeting like position, color, the text on the card, and any private external ID's

you have placed for that card.

Upon clicking the Excel export link for your meeting, you will be taken to a confirmation page which asks for

your community's password one more time as validation. Upon submitting this, your web browser should present

you with a dialog giving you a chance to decide what to do with the spreadsheet (open it directly with Excel or

save it as a file to your computer.)

2.3 XML Exporter

CardMeeting can export your meeting contents as an XML file. This XML file can be consumed by another

program, or you can use desktop tools like Altova XMLSpy to inspect and manipulate the file contents.

Upon clicking the Excel export link for your meeting, you will be taken to a confirmation page which asks for

your community's password one more time as validation. Upon submitting this, your web browser should present

you with a dialog giving you a chance to decide what to do with the spreadsheet (open it directly with Excel or

save it as a file to your computer.)

The CardMeeting XML conforms to anXML Schema that dictates its format and constraints. You can find theCardMeeting XML schema at the following web address:

http://cardmeeting.com/schema/CardMeeting.xsd

2.4 XML Importer

CardMeeting can import CardMeeting XML files into your meeting. Prior to importing the XML, you can opt to

clear the meeting first. When your meeting data is cleared, all existing cards are deleted! Woldrich, Inc., is NOTliable for any data lost accidentally when this clearing process is used. By default, the meeting data is not cleared

If your CardMeeting is not cleared prior to importing XML, then the cards defined in your XML will be added to

the cards already in the meeting. You may set hidden external ID's on each of your cards that you can use to

identify cards that you import from XML files. These external ID's do not appear on the cards in the actual

CardMeeting application, and are for your private use only. During an import, any cards defined in your XML


http://cardmeeting.com/schema/CardMeeting.xsdhttp://cardmeeting.com/schema/CardMeeting.xsd


5/29

that have a matching external ID with a card already in the meeting will replace that existing card (rather than

adding a duplicate of that card.) By judiciously using CardMeeting XML import, export, and external ID's on

cards, you can do two-way synchronizations with external applications and your CardMeeting.

The CardMeeting XML conforms to anXML Schema that dictates its format and constraints. You can find theCardMeeting XML schema at the following web address:


Figure 3: CardMeeting XML Import Input Form




6/29

3 CardMeeting Web Services

Web Services have been developed in order to facilitate your third party integrations with CardMeeting. Even

though CardMeeting is still in the alpha-testing phase of deployment, a vibrant community has already sprung up

around these services to integrate CardMeeting into the rest of their enterprise environment and groupware.

The current intent of the Web Services provided is to allow third parties to get access to their CardMeeting

meeting data and meeting status for the purposes of import, export, and synchronization with their data sources.

If you wish to use the CardMeetingWeb Services, you must understand and agree to all of the terms specified in

Appendix C: Terms and Conditions for using CardMeeting Third Party Integration API Services.

3.1 JAX-WS in CardMeeting Web Service client examples

You may use whatever Web Service tooling is appropriate to your environment to connect with CardMeeting.

The CardMeeting SOAP Web Services provided should be WS-I compliant and therefore be consumable by all

operating systems, environments, platforms, and tools that recognize WS-I compliant web services. The REST

Web Services operate over HTTP/HTTPS and send and receive XML.

The code examples provided in this document were built with Sun's JAX-WS Reference Implementation (RI)

library, version 2.1 EA3. If you are running in a Java 5.0 environment and wish to use JAX-WS to interact with

CardMeeting services, these examples should be portable to your environment.

The latest versions of JAX-WS RI libraries, tools, and documentation can be downloaded from:

https://jax-ws.dev.java.net/

Special note for JAX-WS users on Sun JVMs: JAX-WS exhibits some fairly advanced Java classloader

behavior and Java heap usage and as such places a fairly large burden on the permanent generation heap. The

result of this is that after some time, JAX-WS can create an OutOfMemoryError: PermGen space condition

when using default JVM settings. Our remedy for this was to start our Sun Java VM with the following additiona

flag which boosts the maximum size that the permanent generation heap:

-XX:MaxPermSize=256M


https://jax-ws.dev.java.net/https://jax-ws.dev.java.net/


7/29

More information (actually, way too much information) on tuning Java memory and garbage collection can be

found on Google and at:

http://java.sun.com/javase/technologies/hotspot/gc/gc_tuning_6.html

Other vendors' JVMs or subsequent versions of the Sun JVM may not be subject to the OutOfMemoryError

condition described here.

3.2 SOAP-over-HTTP Web Service API

CardMeeting provides third party integration Web Service APIs using SOAP-over-HTTP and HTTPS.

The Web Services Description Language (WSDL) file that describes the CardMeeting Web Service interface islocated at the following URL:

http://cardmeeting.com/thirdparty/integration?wsdl

You will use this WSDL in your own programs to bind to the Web Service in preparation for invocation. You can

surf to that URL in a browser to view the WSDL directly. The WSDL should be the first thing you look at when

thinking about integrating with CardMeeting. It can help you to determine if the operations provided will meet

your integration requirements.

The CardMeeting third party integrations web service itself is located at the following URL:

http://cardmeeting.com/thirdparty/integration

Surfing to that service URL in a browser displays a human-readable service dashboard that will let you know the

services current availability and status.

3.2.1 SOAP operation: Export Meeting to XML

You can dump the current contents of a CardMeeting to XML provided that you know that meetings ID and

password.


http://java.sun.com/javase/technologies/hotspot/gc/gc_tuning_6.htmlhttp://cardmeeting.com/thirdparty/integration?wsdlhttp://cardmeeting.com/thirdparty/integrationhttp://java.sun.com/javase/technologies/hotspot/gc/gc_tuning_6.htmlhttp://cardmeeting.com/thirdparty/integration?wsdlhttp://cardmeeting.com/thirdparty/integration


8/29

Here is what the export meeting to XML service operation interface roughly looks like, in Java form:

CardMeetingType exportMeeting(String meetingId,

String meetingPassword)

throws IntegrationParameterException, IntegrationUnknownException;

The meetingIdparameter should be a String that looks something like Mxxxx where xxxx is some number

greater than 2000. The return value from the operation is the CardMeetingXML document validating against the

CardMeetingType type from the schema located at:


Usage notes: This operation is computationally costly for the CardMeeting servers. Please do not regularly

invoke this operation. Any frequent, periodic polling of this operation is a misuse of the service and will be

considered a violation of the Terms and Conditions specified at the start of this document.

Assuming you have already compiled a JAX-WS web service client using the services WSDL (see Appendix A:

compiling WSDL to Java with JAX-WS), and you have the generated service classes in the Java classpath, you

can use the following sample to programmatically export the meeting to XML and print the meeting data to the

console:

// assume our generated JAX-WS client classes are in this same package as TestClient

package com.woldrich.dcards.wsclient;

import java.net.URL;

import java.util.Iterator;

import javax.xml.namespace.QName;

public class TestExportClient {

public static void main(String[] args) throws Exception {

URL servUrl;

QName servQName;

IntegrateWithCardMeetingService service;

IntegrateWithCardMeeting servicePort;

servUrl = new URL("http://cardmeeting.com/thirdparty/integration?wsdl");

servQName = = new QName("http://cardm eeting.com",

"IntegrateWithCardMeetingService");

// Create the service and portservice = new IntegrateWithCardMeetingService(servUrl, servQName);

servicePort = aService.getIntegrateWithCardMeetingPort();

// Invoke the exportMeeting operation

CardMeetingType exportedMeeting;

exportedMeeting = servicePort.exportMeeting("M2021", "myPassword");




9/29

// Ok, if no exception was thrown, we have the XML document in

// exportedMeeting. Dump to console to inspect contents...

System.out.print("M eeting: " + exportedMeeting.get Title() + ", ");

System.out.println("CardMeeting Schema version " +

exportedMeeting.getVersion());

Iterator cardIterator;

cardIterator = exportedMeeting.getCard().iterator();

while(cardIterator.hasNext()) {

CardType aCard = cardIterator.next();

System.out.println (" Card Id: " + aCard.getExternalId( ));

System.out.println (" Color: " + aCard.getColor().get Name());

System.out.println (" Xpos: " + aCard.getPosition(). getX());

System.out.println (" Ypos: " + aCard.getPosition(). getY());

System.out.println (" Text: " + aCard.getText());

}

}

}

3.2.2 SOAP operation: Import XML into already existing CardMeeting

You can import a CardMeeting XML file into an already existing CardMeeting. The data for each card may

contain a generic externalId of any format and contents (up to 16384 characters in length) that you may use to

mark your cards and correlate to data structures in your application. CardMeeting does NOT use nor edit the

externalId, but it will preserve it on cards as long as users do not delete the cards.

When a CardMeeting is imported, the importer will check to see if any cards currently in the meeting have an

externalId that exactly matches the cardsbeing imported. If there is a match, rather than creating a new card, the

existing one is replaced with the imported cards data. In this way, you can overlay new information onto an

existing meeting without affecting any new cards that the users may have created. By judiciously combining

CardMeeting XML import and XML export functionality, you can two-way synchronize your CardMeeting and

third party application data.

Here is what the import XML into existing meeting service operation interface roughly looks like, in Java form:

boolean importMeeting(String meetingId,

String meetingPassword,

CardMeetingType cardMeeting,

boolean clearMeetingFirst,

double offsetX,

double offsetY)





10/29

The meetingIdparameter should be a String that looks something like Mxxxx where xxxx is some number

greater than 2000. The cardMeeting parameter should be the XML document containing cards you want to

import. This document must conform to the CardMeetingType type from the schema located at:


The clearMeetingFirstparameter is a boolean you can use to dictate whether the current contents of the meeting

should be cleared prior to import. You should validate with users that they are ok with you clearing their meeting

prior to import, or else they might complain. (Please do not have them complain to me. In other words, use

clearMeetingFirst atyourown risk! ) offsetXand offsetYparameters are global offsets you can apply to all

cards before they are imported if you have canned meeting data you want to import, or want to duplicate a large

number of cards in the meeting, applying an offset is a handy way to reposition cards so that they do not import

directly on top of existing cards. Typically, offsetXand offsetYwill be 0.0.

Card positions are measured in pixels for the canvas fully zoomed in. The cards are 500 pixels wide and 300

pixels tall. You may position all of the cards in your import XML relative to canvas origin (0.0, 0.0) or relative to

other card locations, or whatever suits your application.


invoke this operation. Your integration design should allow for a user-requested on-demand synchronization with

a CardMeeting, or the synchronization should be triggered as a response to some special event (such as your apps

end-of-day reconciliation or when you detect your users have entered and then all have exited a CardMeeting.)

Any frequent, periodic polling of this operation is a misuse of the service and will be considered a violation of the

Terms and Conditions specified at the start of this document.

Assuming you have already compiled a JAX-WS web service client using the services WSDL (see Appendix A:

compiling WSDL to Java with JAX-WS), and you have the generated service classes in the Java classpath, you

can use the following sample to programmatically import XML into a meeting. Have a browser independently

logged into the CardMeeting to verify your import is successful. You should see the import routine make change

to the CardMeeting in real time as if it was a human meeting participant.




11/29






public class TestImportClient {


URL servUrl;

QName servQName;




servQName = new QName("http://cardmeeting.com",


// Create the service and port

service = new IntegrateWithCardMeetingService(servUrl, servQName);


// Use the JAXB ObjectFactory to make an import XML document from scratch

// in CardMeetingType object form.// Alternately, at this point you can read an XML document from a file

// (via Unmarshaller.unmarshal()) and import that into your CardMeeting

ObjectFactory objFactory = new ObjectFactory();

CardMeetingType importedMeeting = objFactory.createCardMeetingType();

CardType cardDefinition = objFactory.createCardType();

ColorType cardColor = objFactory.createColorType();

cardColor.setName("Violet");

cardDefinition.setColor(cardColor);

cardDefinition.setExternalId("This is where third parties put content\n" +

"You could even put in here\n"+

"CardMeeting takes !@#$%^\"&*() anything!");

// position the card on the canvas

PositionType cardPosition = objFactory.createPositionType();

cardPosition.setX(500.0);

cardPosition.setY(0.0);

cardDefinition.setPosition(cardPosition);

// set text that shows up to users on the front of the card

cardDefinition.setText("This is the text that shows up on the front of " +

"the card. You can place carriage returns in here and they will " +

"render correctly.\nBut other formatting, not so much yet.");

// add card to the List in the CardMeetingType importedMeeting

importedMeeting.getCard().add(cardDefinition);

// You may add more new cards to the importedMeeting.getCard() List here

// Lastly, set some top-level meeting XML attributes...

// set the meeting XML's version to 2. This must always match the// version number enumeration in the CardMeeting schema .xsd file. 2 is

// the current number as of this writing

importedMeeting.setVersion(2);

// set the meeting's new title. Note: this is an optional attribute on

// the schema and if left null, the meeting's title will not be changed.

// users will not see the title change until the next time they login to // the meeting.

This can show up on users' browser title bars, so limit

// the use of special characters in this string.

importedMeeting.setTitle("The new meeting title");




12/29

// Invoke the importMeeting operation! clearMeetingFirst == false

servicePort.importMeeting("M2021", "password", importedMeeting, false,

0.0, 0.0);

}

}

3.2.3 SOAP operation: Number of users currently logged in

CardMeetings currently lack any presence information about users that are currently logged in. In lieu of user

presence reporting, for the purposes of determining if all your users have left a meeting and knowing whether you

can safely export CardMeeting XML data to your application, a service operation has been developed to allow

you to determine the number of users currently logged into a meeting.

A user logout is registered whenever a user closes or surfs away on the browser containing their CardMeeting

session. You can trigger an import or export of CardMeeting XML data by regularly polling the CardMeeting andwaiting for the session count to drop to 0. Under normal operating conditions, the web service will report the

instantaneous active session count of all of your users in a meeting.

Here is what the number of users currently logged in service operation interface roughly looks like, in Java

form:

int getNumberOfActiveParticipantsInMeeting(String meetingId,

String meetingPassword)


The meetingIdshould be a String that looks something like Mxxxx where xxxx is some number greater than

2000. The return value is the number of users currently logged in.

Usage notes: Please do not poll this method more than once every 5 seconds so as to conserve CardMeeting

server resources. Please only poll the meeting when that information is useful to your triggers (in other words,

please do not poll the meeting 24-7 just because you can.)

Assuming you have already compiled a JAX-WS web service client using the services WSDL (please see

Appendix A: Compiling WSDL to Java with JAX-WS), and you have the generated service classes in the Javaclasspath, you can use the following sample to programmatically get the number of active users logged into a

meeting:




13/29






public class TestCountLoggedInUsers {


URL servUrl;

QName servQName;




servQName = = new QName("http://card meeting.com",


// Create the service and port

service = new IntegrateWithCardMeetingService(servUrl, servQName);


// Invoke the getNumberOfActiveParticipantsInMeeting operation

int retVal = servicePort.getNumberOfActiveParticipantsInMeeting("M2021","passwd");

System.out.println ("Number of active participants: " + retVal);

}

}

3.3 XML/HTTP Web Service API (RESTful Web Service)

CardMeeting provides third party integration Web Service APIs using XML-over-HTTP. This type of Web

Service is commonly referred to as a REST Web Service. You can find out more about Representational State

Transfer (REST) on Wikipedia at

http://en.wikipedia.org/wiki/REST

Unlike SOAP-over-HTTP Web Services, there is no standard, formal, discoverable interface description like

WSDL for RESTful Web Services. For the CardMeeting RESTful Web Services, we have opted to create an

XML schema that describes all requests and responses that would need structure. You can find the schema used

for the RESTful Web Service operations at the following URL:

http://cardmeeting.com/schema/Integration.xsd

Note: Any CardMeeting RESTful Web Service operations described below that support HTTP GET requests can

be tested directly in your web browser. Simply open a browser window and type in the URL as specified in the

sections below. RESTful Web Service operations that only support HTTP PUT will require you to submit the

request from code, you cannot exercise the operation via the webbrowser.


http://en.wikipedia.org/wiki/RESThttp://cardmeeting.com/schema/Integration.xsdhttp://en.wikipedia.org/wiki/RESThttp://cardmeeting.com/schema/Integration.xsd


14/29

3.3.1 REST operation: Export Meeting to XML

You can dump the current contents of a CardMeeting to XML provided that you know that meetings ID and

password.

You can issue a request to Export Meeting to XML via an HTTP GET or POST request in the following URL

formats

GET:

http://cardmeeting.com/thirdparty/restfulintegration?operation=exportMeeting&meetingId=M xxxx&meetingPassword=yyyy

POST:

http://cardmeeting.com/thirdparty/restfulintegration/exportMeeting/Mxxxx/yyyy

where Mxxxx is the ID to the meeting that you want to export, and yyyy is the community password for the

meeting.

Here is an example Java program that uses an HTTP GET request to export the M2013 meeting to XML:

package com.woldrich.dcards.restclient;

import java.io.StringWriter;


public class TestClient {


URL theUrl = null;

theUrl = new URL("http://cardmeeting.com/thirdparty/restfulintegration?" +

"operation=exportMeeting&" +

"meetingId=M2013&" +

"meetingPassword=passw0rd");

StringWriter outWriter = new StringWriter();

makeHttpGetRequest(theUrl, outWriter);

System.out.println("Export response was:\n" + outWriter.toString()); }

private static void makeHttpGetRequest(URL srcUrl, Writer outWriter)

throws IOException {Reader inReader = null;

try {

URLConnection urlConn = srcUrl.openConnection();

urlConn.setUseCaches(false);

inReader = new InputStreamReader(urlConn.getInputStream(),

"UTF-8");

char[] readBuf = new char[4096];

int readCount;




15/29

while((readCount = inReader.read(readBuf)) >= 0) {

if(readCount > 0) {

outWriter.write(readBuf, 0, readCount);

}

}

}

finally {

if(inReader != null) {

try {

inReader.close();

}

catch(Exception e) {

}

}

outWriter.close();

}

}

}

The output of a successful run of the above program would contain the tags similar to the following:

My name is card1, I should be a white card.

card1 externalId

My name is card2, I should be a blue card.

card2 externalId

My name is card3, I should be a canary card.

card3 externalId

Usage notes: This operation is computationally costly for the CardMeeting servers. Please do not regularlyinvoke this operation. Any frequent, periodic polling of this operation is a misuse of the service and will be

considered a violation of the Terms and Conditions specified at the start of this document.




16/29

3.3.2 REST operation: Import XML into already existing CardMeeting

You can import a CardMeeting XML file into an already existing CardMeeting. The data for each card may

contain a generic externalId of any format and contents (up to 16384 characters in length) that you may use to

mark your cards and correlate to data structures in your application. CardMeeting does NOT use nor edit the

externalId, but it will preserve it on cards as long as users do not delete the cards.

When a CardMeeting is imported, the importer will check to see if any cards currently in the meeting have an

externalId that exactly matches the cardsbeing imported. If there is a match, rather than creating a new card, the

existing one is replaced with the imported cards data. In this way, you can overlay new information onto an

existing meeting without affecting any new cards that the users may have created. By judiciously combining

CardMeeting XML import and XML export functionality, you can two-way synchronize your CardMeeting and

third party application data.

You can issue a request to Import Meeting from XML via an HTTP POST request in the following format

POST:

http://cardmeeting.com/thirdparty/restfulintegration

Here is an example XML document that will be submitted in the POST request body for Import Meeting:

My name is card1, I should be a white card.

card1 externalId

My name is card2, I should be a blue card.

card2 externalId

My name is card3, I should be a canary card.

card3 externalId




17/29

Note #1: Import Meetings request URI does not contain an operation name, meeting ID, or meeting password

parameters. Those request parameters are specified as attributes of the tag for this

operation and not on the request URI.

Note #2: CardMeeting XML Import makes a distinction between empty externalId strings (externalId tag is

empty) and null externalId's (externalId tag is missing). Do NOT expect a blank externalId to be considered to be

treated like a null/missing externalId. In general, you should OMIT the tag from your tags

unless you have a non-empty value to specify there.

Here is an example Java program that issues an HTTP POST request and that uses JAXB beans bound to the

Integration.xsd schema to construct the importMeetingRequest XML for the request (please see Appendix B:

Compiling XSD to Java with JAXB for an example of how to use Ant and JAXB to compile the Integration.xsd

schema into Java code in your program):


import java.io.StringWriter;


import javax.xml.bind.JAXBContext;

import javax.xml.bind.JAXBElement;

import javax.xml.bind.JAXBException;

import javax.xml.bind.Marshaller;


import org.apache.commons.httpclient.HttpClient;

import org.apache.commons.httpclient.methods.PostMethod;

import org.apache.commons.httpclient.methods.RequestEntity;

import org.apache.commons.httpclient.methods.StringRequestEntity;

import com.woldrich.dcards.xml.CardMeetingType;

import com.woldrich.dcards.xml.CardType;

import com.woldrich.dcards.xml.ColorType;

import com.woldrich.dcards.xml.ImportMeetingRequestType;

import com.woldrich.dcards.xml.IntegrationType;

import com.woldrich.dcards.xml.ObjectFactory;

import com.woldrich.dcards.xml.PositionType;



// ObjectFactory is a JAXB-generated class that is used to create new

// JAXB beans.

ObjectFactory objFactory = new ObjectFactory();

// The CardMeetingType class represents a complete meeting export/import

CardMeetingType cardMeetingToImport = objFactory.createCardMeetingType();

cardMeetingToImport.setVersion(2);

// white card1: Create new CardType object, add it to cardMeetingToImport

ColorType color1 = objFactory.createColorType();

color1.setName("White");

PositionType position1 = objFactory.createPositionType();

position1.setX(1000.0);

position1.setY(600.0);




18/29

CardType card1 = objFactory.createCardType();

card1.setColor(color1);

card1.setPosition(position1);

card1.setExternalId("card1 externalId");

card1.setText("My name is card1, I should be a white card.");

cardMeetingToImport.getCard().add(card1);

// blue card2: Create new CardType object, add it to cardMeetingToImport


color2.setName("Blue");

PositionType position2 = objFactory.createPositionType();

position2.setX(500.0);






card2.setText("My name is card2, I should be a blue card.");


// canary card3: Create new CardType object, add it to cardMeetingToImport


color3.setName("Canary");

PositionType position3 = objFactory.createPositionType();position3.setX(0.0);






card3.setText("My name is card3, I should be a canary card.");


// Create an importMeetingRequest object, add CardMeetingType and other

// parameters needed to make the Import Meeting request.

ImportMeetingRequestType importMeetingRequest = null;

importMeetingRequest = objFactory.createImportMeetingRequestType();

importMeetingRequest.setClearMeetingFirst(false);

importMeetingRequest.setOffsetX(0.0);

importMeetingRequest.setOffsetY(0.0);

importMeetingRequest.setCardMeeting(cardMeetingToImport);

importMeetingRequest.setMeetingId("M2013");

importMeetingRequest.setMeetingPassword("passw@rd");

// The IntegrationType object represents the root tag you will always use

// to interact in requests and responses to the CardMeeting RESTful Web

// Service.

IntegrationType integrationRootNode = objFactory.createIntegrationType();

integrationRootNode.setImportMeetingRequest(importMeetingRequest);

integrationRootNode.setVersion(2);

// Use the JAXB API's to marshal the JAXB beans we created into XML text

JAXBContext jc = JAXBContext.newInstance("com.woldrich.dcards.xml");

Marshaller jaxbMarshaller = jc.createMarshaller();

jaxbMarshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");jaxbMarshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,

Boolean.TRUE);

jaxbMarshaller.setProperty(Marshaller.JAXB_FRAGMENT, Boolean.FALSE);

jaxbMarshaller.setProperty(Marshaller.JAXB_SCHEMA_LOCATION,

"http://cardmeeting.com/schema/CardMeeting.xsd

http://cardmeeting.com/schema/Integration.xsd");

// Wrap our JAXB bean in a JAXBElement in preparation for marshal'ing.

StringWriter jaxbStringWriter = new StringWriter();

QName rootNodeName = null;




19/29

JAXBElement jaxbImportRequestDocument = null;

rootNodeName = new QName("http://cardmeeting.com/schema/CardMeeting.xsd",

"integration");

jaxbImportRequestDocument = new JAXBElement(rootNodeName,

IntegrationType.class,

integrationRootNode);

// We finally have our JAXBElement bean that represents a complete

// IntegrationType XML document. Now we marshal to XML text that we

// can use for the HTTP POST request.

jaxbMarshaller.marshal(jaxbImportRequestDocument, jaxbStringWriter);

String xmlDocumentAsString = jaxbStringWriter.toString();

// Let's see what this XML text looks like before we submit it

System.out.println("We're going to submit the following XML request:\n" +

xmlDocumentAsString);

// We use the Jakarta HttpClient utility library to issue the HTTP POST

// request to the CardMeeting servers. The following objects are types

// from that library. (Please see

// http://jakarta.apache.org/commons/httpclient for more information.)

HttpClient httpClient = null;

PostMethod postMethod = null;RequestEntity requestEntity = null;

String requestUrl = null;

httpClient = new HttpClient();

requestUrl = "http://cardmeeting.com/thirdparty/restfulintegration";

postMethod = new PostMethod(requestUrl);

requestEntity = new StringRequestEntity(xmlDocumentAsString,

"text/xml",

"UTF-8");

// Ok, we've got everything we need to submit our request. Set the

// request body and hit the gas ...

postMethod.setRequestEntity(requestEntity);

httpClient.executeMethod(postMethod);

// If we got here, the request is done and the response is ready for

// processing.

String xmlDocumentResponse = null;

int responseStatusCode = 0;

responseStatusCode = postMethod.getStatusCode();

xmlDocumentResponse = postMethod.getResponseBodyAsString();

System.out.println ("Import status code was: " + responseStatusCode);

System.out.println("Import response was:\n" + xmlDocumentResponse);

// If we wanted to, we could use JAXB here and unmarshal() the XML text

// in the response into JAXB beans to make it easier for us to process

// the data returned. In the case of Import Meeting, we can assume that

// if the response wasn't an http error code, the import was a success.

// don't forget to releaseConnection before continuing so that POST submit// resources are released ...

postMethod.releaseConnection();

}

}




20/29

A successful POST response body for Import Meeting would contain the following tags:


invoke this operation. Your integration design should allow for a user-requested on-demand synchronization with

a CardMeeting, or the synchronization should be triggered as a response to some special event (such as your apps

end-of-day reconciliation or when you detect your users have entered and then all have exited a CardMeeting.)

Any frequent, periodic polling of this operation is a misuse of the service and will be considered a violation of the

Terms and Conditions specified at the start of this document.

3.3.3 REST operation: Number of users currently logged in

CardMeetings currently lack any presence information about users that are currently logged in. In lieu of user

presence reporting, for the purposes of determining if all your users have left a meeting and knowing whether you

can safely export CardMeeting XML data to your application, a service operation has been developed to allow

you to determine the number of users currently logged into a meeting.

A user logout is registered whenever a user closes or surfs away on the browser containing their CardMeeting

session. You can trigger an import or export of CardMeeting XML data by regularly polling the CardMeeting and

waiting for the session count to drop to 0. Under normal operating conditions, the web service will report the

instantaneous active session count of all of your users in a meeting.

You can issue a request to Get Number of Users Currently Logged In via an HTTP GET or POST request in the

following URL formats

GET:

http://cardmeeting.com/thirdparty/restfulintegration?operation=getNumberOfActiveParticipantsInMeeting&meetingId=Mxxxx&meetingPassword=yyyy

POST:

http://cardmeeting.com/thirdparty/getNumberOfActiveParticipantsInMeeting/ Mxxxx/yyyy




21/29

where Mxxxx is the ID to the meeting that you want to query, and yyyy is the community password for the

meeting.

Here is an example Java program that uses an HTTP POST request to query the number of active logons in theM2013 meeting:


import org.apache.commons.httpclient.HttpClient;

import org.apache.commons.httpclient.methods.PostMethod;



HttpClient httpClient = null;

PostMethod postMethod = null;

String theUrl = null;

theUrl = "http://cardmeeting.com/thirdparty/restfulintegration/" +

"getNumberOfActiveParticipantsInMeeting/M2013/passverd";

httpClient = new HttpClient();

postMethod = new PostMethod(theUrl);

// We've got the URL, HttpClient, and PostMethod created and

// ready to submit as a request.

httpClient.executeMethod(postMethod);

String responseBody = null;

int responseStatusCode = 0;

responseStatusCode = postMethod.getStatusCode();

responseBody = postMethod.getResponseBodyAsString();

System.out.println("Status code was: " + responseStatusCode);

System.out.println("Get active participants response:\n" +

responseBody);

// If we wanted to, we could use JAXB here and unmarshal() the XML text

// in the response into JAXB beans to make it easier for us to process

// the data returned.

// don't forget to releaseConnection so that POST submit resources

// are released ...

postMethod.releaseConnection();

}}




22/29

A successful response for this operation will return an XML document with the following tags similar to the

following:

Usage notes: Please do not poll this method more than once every 5 seconds so as to conserve CardMeeting

server resources. Please only poll the meeting when that information is useful to your triggers (in other words,

please do not poll the meeting 24-7 just because you can.)




23/29

4 Embedding the CardMeeting Applet In Your Application

The CardMeeting Applet was designed so that third party developers can embed CardMeeting seamlessly into

their web applications. Embedding CardMeeting in your web application creates exciting mashup opportunitieswhereby CardMeeting can enhance and improve your customer's experience with your product.

CardMeeting should be given as much screen real estate as possible to enhance usability, so running it in a

maximized popup window is the best way to provide that screen real estate. CardMeeting can also be web

clipped by your application if you wish, and in doing that you can frame/iframe the CardMeeting such that it sits

alongside the rest of your web applications widgets.

To embed CardMeeting, compose a HTTP Get request with the following URI to open a CardMeeting in an

iframe in the browser:

http[s]://cardmeeting.com/Login

Then, add the following query string parameters as necessary (parameter names are case sensitive):

Parameter Name Optional/Required Description

meetingId Required String: Your existing CardMeetings ID with the format

Mxxxx where xxxx is a number greater than 2000.

communityPassword Required String: The community password to the meeting.

Users currently do not get their own passwords the

community password is shared by all. This makes

embedding a CardMeeting in your application trivial since

this password can be centrally cached and need not be

provided by the user.

logonFailureIsError Optional

Default is false

Boolean: This forces CardMeeting to throw an HTTP Error

401 back to your iframe immediately if meetingId or

communityPassword are incorrect.

We recommend that you always pass true here when

embedding the CardMeeting Applet.

disableConsole Optional

Default is false

Boolean: If your iframe will be too small on-screen to

effectively display a console in the applet, you can disable it

by setting disableConsole to true.




24/29

Here is an example URL that would load the M2000 CardMeeting via HTTPS:

https://cardmeeting.com/Login?meetingId=M2000&communityPassword=passwerd&logonFailureIsError=true

When embedding CardMeeting on your page using an IFRAME tag, you can style the iframe using CSS to control

size and border style. Here is an example IFRAME tag that shows a CSS style applied and a meeting URL:

Notice that the ampersands (&) in the query string are escaped in the src attrbute (with &)

To see CardMeeting applet embedding in action, two test webpages have been provided for you as an example:

http://cardmeeting.com/testEmbedding_iframe.jsp

This webpage demonstrates inlining the applet using an iframe. Use your browser's view sourcefunction to see how the iframe was constructed.

You would use this method for embedding CardMeeting when you want the meeting Applet to be

surrounded by the rest of your web application's components and widgets.

http://cardmeeting.com/testEmbedding_popup.jsp

This webpage demonstrates embedding CardMeeting in a popup window. Extensive JavaScript is

employed to manage the open/closed state of the popup so as not to overload the Java Plugin

system.

You would use this method for embedding CardMeeting when you want to launch a meeting in a

separate window via hyperlink or button in your web application.


http://cardmeeting.com/testEmbedding_iframe.jsphttp://cardmeeting.com/testEmbedding_popup.jsphttp://cardmeeting.com/testEmbedding_iframe.jsphttp://cardmeeting.com/testEmbedding_popup.jsp


25/29

Appendix A: Compiling WSDL to Java with JAX-WS

Here is a sample Ant script that automates a call to the wsimporttool, the JAX-WS tool used to generate SOAP

Web Service clients for Java. For more information about wsimport, please consult the documentation at:

https://jax-ws.dev.java.net/jax-ws-ea3/docs/wsimport.html

This sample assumes that a folder called jaxws-ri contains the JAX-WS binaries and is sharing the same root as

the current folder. A generated src folder in the current folder will contain the generated sources, the classes

folder will contain compiled classes.

Sample wsimportAnt build.xml script:


https://jax-ws.dev.java.net/jax-ws-ea3/docs/wsimport.htmlhttps://jax-ws.dev.java.net/jax-ws-ea3/docs/wsimport.html


26/29

Appendix B: Compiling XSD to Java with JAXB

Here is a sample Ant script that automates a call to thexjc tool, the JAXB tool for compiling an XML Schema file

(.xsd) to beans that can be marshaled and unmarshaled to XML text. For more information aboutxjc, please

consult the documentation at:

http://java.sun.com/webservices/docs/2.0/jaxb/xjc.html

The following Ant build.xml sample assumes that a folder called jaxb contains the JAXB binaries and is sharing

the same root as the current folder. A generated src folder in the current folder will contain the generated sources

the classes folder will contain compiled classes. JAXB works best with Java Development Kit 1.6 (but it works

with JDK 1.5 as well.) You should install JDK 1.6 and set your JAVA_HOME environment variable

appropriately. (eg. JAVA_HOME = c:\progra~1\java\jdk1.6.0 on Windows.)

This Ant build.xml sample also assumes that a folder called 'schema' contains downloaded copies of the

CardMeeting.xsd and Integration.xsd schema files and rooted at the same root as the current folder (../schema).

You can locally cache your schema files in the same way by downloading the schema files from the following

URLs:

http://cardmeeting.com/schema/Integration.xsd



http://java.sun.com/webservices/docs/2.0/jaxb/xjc.htmlhttp://cardmeeting.com/schema/Integration.xsdhttp://cardmeeting.com/schema/CardMeeting.xsdhttp://java.sun.com/webservices/docs/2.0/jaxb/xjc.htmlhttp://cardmeeting.com/schema/Integration.xsdhttp://cardmeeting.com/schema/CardMeeting.xsd


27/29

Sample JAXB compilation Ant build.xml script:




28/29

Appendix C: Terms and Conditions for using CardMeeting Third Party

Integration API Services

Thank you for your interest in the CardMeeting Third Party Integration services. By using this service ("CardMeeting Third Party Integration API")

you agree to be bound by the following terms and conditions (the "Terms and Conditions").

Personal and legitimate uses only

The CardMeeting Third Party Integration API service is made available to you for your personal, commercial, or non-commercial use only. You may

use the API only with existing, manually created CardMeeting meetings. You may not create any script or other tool that attempts to create

CardMeeting meetings in an automated fashion.

If you are interested in doing anything different than the foregoing, you must first obtain Woldrich, Inc.s written consent. If you fail to do so,

Woldrich, Inc. reserves the right to refuse service or take legal action as required.

Furthermore, you may not use CardMeeting Third Party Integration API in any manner that either directly or indirectly violates any laws or

proprietary rights. This includes laws and proprietary rights in the United States as well as in other countries. You may not intentionally or

accidentally abuse CardMeeting server computing resources via inappropriate invocations of the CardMeeting Third Party Integration APIs.

If you have questions on your contemplated use, if you have comments on CardMeeting Third Party Integration API, or if you have ideas on how to

improve it, please send email to [email protected]. Please note that by doing so, you also grant Woldrich, Inc. permission to use and incorporate

your ideas or comments into CardMeeting Third Party Integration API and the overall CardMeeting product without further compensation.

Intellectual property

You also acknowledge that Woldrich, Inc. owns all right, title and interest in and to CardMeeting Third Party Integration API, including without

limitation all intellectual property rights with the following exceptions: (1) third-party components used as part of CardMeeting Third Party

Integration API; or (2) software developed by you in conjunction with using CardMeeting Third Party Integration API.

Publicity

So long as you comply with your obligations under this Agreement, you may indicate that a product or service that you created either used or is

based on CardMeeting Third Party Integration API provided that those products or services do not in Woldrich, Inc's reasonable opinion (1) tarnish,

infringe, or dilute Woldrich, Inc's trademarks, (2) violate any applicable law, and (3) infringe any third-party rights. If you wish to use the

CardMeeting trademark and/or logo in any other manner, you must first obtain Woldrich, Inc's written consent.

Disclaimer of warranties

The CardMeeting Third Party Integration API service is currently presented in alpha form and has not been fully tested or debugged. Accordingly,

Woldrich, Inc disclaims any responsibility for any harm resulting from your use of CardMeeting Third Party Integration API.

The CardMeeting Third Party Integration API service is provided "as is," with no warranties whatsoever. Woldrich, Inc expressly disclaims to the

fullest extent permitted by law all express, implied, and statutory warranties, including, without limitation, the warranties of merchantability, fitness

for a particular purpose, and non-infringement of proprietary rights. Woldrich, Inc disclaims any warranties regarding the security, reliability,

timeliness, availability, and performance of CardMeeting Third Party Integration API.




29/29

You understand and agree that you use CardMeeting Third Party Integration API at your own discretion and risk and that you will be solely

responsible for any damages to your computer system or loss of data that results from the download or use of CardMeeting Third Party Integration

API.

Some states or other jurisdictions do not allow the exclusion of implied warranties, so the above exclusions may not apply to you. You may also have

other rights that vary from state to state and jurisdiction to jurisdiction.

Limitation of liability

The CardMeeting Third Party Integration API service is being provided free of charge. Accordingly, you agree that Woldrich, Inc shall have no

liability arising from or based on your use of CardMeeting Third Party Integration API.

Under no circumstances shall Woldrich, Inc. be liable to any user on account of that user's use or misuse of CardMeeting Third Party Integration

API. Such limitation of liability shall apply to prevent recovery of direct, indirect, incidental, consequential, special, exemplary, and punitive

damages whether such claim is based on warranty, contract, tort (including negligence), or otherwise, even if Woldrich, Inc has been advised of the

possibility of such damages). Such limitation of liability shall apply whether the damages arise from use or misuse of and reliance on the

CardMeeting Third Party Integration API, from inability to use CardMeeting Third Party Integration APIs, or from the interruption, suspension, or

termination of CardMeeting Third Party Integration APIs (including such damages incurred by third parties). Such limitation shall apply

notwithstanding a failure of essential purpose of any limited remedy and to the fullest extent permitted by law.

Some states or other jurisdictions do not allow the exclusion or limitation of liability for incidental or consequential damages, so the above

limitations and exclusions may not apply to you.

Indemnification

You hereby agree to indemnify, defend and hold Woldrich, Inc, and its officers, directors, agents, licensors and licensees (collectively, the

"Indemnified Parties") harmless from and against any and all liability and costs incurred by the Indemnified Parties in connection with any claim

arising out of your use of CardMeeting Third Party Integration API, including, without limitation, reasonable attorneys' fees. You shall cooperate as

fully as reasonably required in the defense of any claim. Woldrich, Inc reserves the right, at its own expense, to assume the exclusive defense and

control of any matter subject to indemnification by you.

CardMeeting meeting services

The CardMeeting Third Party Integration API service is designed to be used in conjunction with CardMeeting's meeting services. Accordingly, your

use of CardMeeting Third Party Integration API is also defined by CardMeeting's Terms of Service. In the event of a conflict between these Terms

and Conditions and CardMeeting's Terms of Service, these Terms and Conditions shall prevail.

Term and termination

If you wish to terminate this Agreement, you may simply cease using the CardMeeting Third Party Integration API service. Woldrich, Inc may

terminate this Agreement (and your CardMeeting meetings/accounts) at any time, with or without cause.

card meeting data exchange

Documents