Posts in Category "XML API"

Using the XML API with Enhanced Security

With the release of Adobe Connect 9.0.4 and beyond (view KB here), we have introduced the Enhanced Security feature (documentation) and it is ON by default on our hosted system.  If you are an Adobe Connect Hosted customer, you can toggle the Enhanced Security feature on or off (if you are an Administrator) by logging into your Adobe Connect Hosted account and navigating to: Administration > More Settings.  You will see the following Security Settings:

es

 

If you have ‘Enable Enhanced Security’ checked (and you save the settings), your account will now issue TWO session cookies to a user when they authenticate.  This is crucial to understand and plan for if you are using the XML API to integrate with another system.  Also, if you are a partner or developer who has built an application that integrates with Adobe Connect, you will need to rework your application to account for the possibility of this feature being ON or OFF.

From my experience, it is best to simply code the application to look for the second session cookie all the time (after initially authenticating the user) rather than try to check for the feature being on or off.

Typically in Adobe Connect Hosted accounts before this feature was implemented (and with this setting OFF), your application would first make a ‘common-info’ call as below, to obtain a session cookie before logging a user in:

https://myaccountURL/api/xml?action=common-info

<results>
<status code=”ok”/>
<common locale=”en” time-zone-id=”35″ time-zone-java-id=”US/Eastern”>
<cookie>naXbreezecookie123456789</cookie>
<date>2013-12-02T19:50:38.983-05:00</date>
<host>https://myaccountURL</host>
<local-host>connecthost01</local-host>
<admin-host>naXcps.adobeconnect.com</admin-host>
<url>/api/xml?action=common-info</url>
<version>9.1.2</version>
<tos-version>7.5</tos-version>
<product-notification>true</product-notification>
<account account-id=”12345678″/>
<user user-id=”45678901″ type=”user”>
<name>Jim Johnson</name>
<login>Jim</login>
</user>
<user-agent>
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/31.0.1650.57 Safari/537.36
</user-agent>
<mobile-app-package>air.com.adobe.connectpro</mobile-app-package>
</common>
<reg-user>
<is-reg-user>false</is-reg-user>
</reg-user>
</results>

Then you would log the user in:

https://myaccountURL/api/xml?action=login&login=Jim&password=XXXXXXX&session=naXbreezecookie123456789

<results>
<status code=”ok”/>
</results>

That would normally be it.

Then, all subsequent calls, you would normally just append that same session cookie as the ‘session’ parameter and you’d be all set.  However, with Enhanced Security ON, that session cookie you obtained from the first common-info call will NOT work in calls after the login call authenticates the user.  Once the login API is called, you MUST call common-info one more time immediately after the OK response comes back from the login call.  When you run common-info again, you will notice you will get a DIFFERENT session cookie value.  That second cookie value is the session you need to include in your subsequent calls going forward.  If you do not use that second value in your API call, and instead include the value from the first common-info call result, you will get the following error response:

<results>
<status code=”no-access” subcode=”no-login“/>
</results>

So in summary:

Before Enhanced Security the workflow was:

1) common-info API to get cookie session value
2) login API using the cookie session value
3) continue on making API calls with that same session cookie throughout the user session

After Enhanced Security (post 9.0.4):

1) common-info API to get cookie session value
2) login API using the cookie session value
3) common-info API again a second time to get the final cookie session value to use going forward in all other calls
4) continue on making API calls with that NEW session cookie throughout the user session

Again, it is best to code your application to always look for a session cookie again AFTER logging a user in.  That way, even if you are still using the same session (say if the account had Enhanced Security set to OFF), your application will still work fine and in the cases where the account does have Enhanced Security turned ON, it will still continue to work as expected.

Adding the Passcode Feature for Connect Meetings

You may add a passcode feature as an additional security option for Connect Meeting room access in Connect versions 8 and 9. Each Meeting room can have its own passcode.  The parameter will appear under the Edit Information tab of the Connect Meeting:

pc2.fw

This is a great option. For example, it allows you to pop up a fast ad hoc meeting with full guest access while requiring guests to apply a pass-code to enter:

pc.fw

It also allows an additional layer of security for registered users as well; they also would need to enter a passcode in addition to any permissions (even host-level) granted to the room.

pc1.fw

Once applied, when a users hits the Meeting URL they will be presented with the passcode field:

pc3.fw

To add this feature, simple log onto your on-premise adobe Connect server as a Connect Administrator and enter the following into the URL line in Connect Central:

http://YOURDOMAINNAME/api/xml?action=meeting-feature-update&account-id=7&feature-id=fid-meeting-passcode-notallowed&enable=false

Where “YOURDOMAINNAME” is actually your domain name.

If this executes correctly, you will see the following output when you follow-up by entering this command into the same URL line in Connect Central:

http://YOURDOMAINNAME/api/xml?action=meeting-feature-info&account-id=7

Output: feature-id=fid-meeting-passcode-notallowed

Alternatively you could simply check and see if the feature is available under the Edit Information tab of any Meeting.

Note: Your Meeting passcode can be up to 16 letters or numbers; keep in mind that it is a convenient supplementary security mechanism rather than a primary means. You will see this warning if your passcode is not supported go over that: Your passcode must be between 1 and 16 characters long (letters or numbers, no spaces).

In adding this feature you have invoked the Web Services API in Connect. If you are not familiar with the API see the following document; it is rich with options: http://help.adobe.com/en_US/connect/9.0/webservices/connect_9_webservices.pdf

Note also that with Connect 9.2, in Connect Central under Administration > Users and Groups > Edit Login and Password Policies, there are two relevant check boxes, one to enable and the other one to force the use of the passcode:

passcode.fw

Vantage Point is not just about Bandwidth

Vantage Point from Refined Data works with Connect and provides remote control of Cameras, Microphones, Telephones, Volumes, Tech Support, Motion Detection, Mouse Detection, Continuous attendance tracking and reporting and much more so it’s not just about bandwidth reduction.

On the bandwidth front, Vantage Point publishes streams to Refined Data servers at 100Kbps for each participant in the room; this is less than Connect in most cases, but the Host only consumes as many streams as they can view at one time. The host can see as few as 5 or 6 students at one time or as many as 50 or more depending on their screen resolution, window size, Vantage Point settings, connectivity and bandwidth availability.

This means that even with 100 Participants in a Connect room and one Host the bandwidth consumption looks like this:

  • Participant Load: 100kbps Up (to publish their own camera to Vantage Point), 100kbps down (to view the Host in Connect). This is a small signature on the network.
  • Host Load: 100kbps Up (to publish their own camera in Connect), 2.5mbps down (assuming they view 25 participant cameras in Vantage Point at one time). The Host is the only one who needs a really good connection.
  • Total Load on Adobe Connect: 1 publish stream + 99 subscribers

The host can always reduce their own load simply by viewing fewer simultaneous Video pods in Vantage Point. The bandwidth load for students or participants is not affected at all by class size. Bandwidth load for Hosts rises linearly with class size but can be limited by the host at any time based on the maximum number of cameras they view at one time.

In Connect, the bandwidth load rises with the number of cameras being shared:

  • 4 Cameras: 16 Connections on the Server, each user publishes 100kbps and consumes 300kbps
  • 10 Cameras: 100 Connections on the Server, each user publishes 100kbps and consumes 900kbps
  • 20 Cameras: 400 Connections on the Server, each user publishes 100kbps and consumes 1.9mbps

Even if Connect could technically support 50 or 100 simultaneous web cams in a single meeting (2,500 streams risks significant latency), consider the requirement that participants would need 5-10mbps of bandwidth to support the load, before accounting for VoIP, screen-sharing and basic overhead. Anything above 10 simultaneous web cameras may be difficult for a host to manage and apart from any other considerations, there may not be enough real-estate for content if you are showing 10 or more web cams in the meeting room.

Vantage Point only publishes at 100kbps, most of the time; DSL and Standard quality is already more than twice this load in Connect and can easily rise higher if the room is set to use the Highest video quality at 16:9. With Vantage Point, Adobe Connect saves the server load, participants are not affected by class size, Hosts can see all of their students, all of the time and enjoy unparalleled control of the classroom environment.

Check it out at Refined Data: http://vantagepoint.refineddata.com/

Troubleshooting Caption Colorado Domain Names in Meeting Pod

Issue: Sometimes the Closed Captioning pod fails to connect to Caption Colorado.

Symptom looks like this:

CC.fw

Always make certain you have the correct pod version: http://www.adobe.com/products/adobeconnect/feature-details/closed-captioning.html

There are two names available at Caption Colorado, one is a legacy name for Breeze and the other is for Connect. Both point to the same TCPIP address:

C:\flyfishing\frank>nslookup connect.captioncolorado.com
Server:  dns.adobe.com
Address:  xx.xx.xx.xx
Non-authoritative answer:
Name:    connect.captioncolorado.com
Address:  216.241.103.7
C:\flyfishing\frank>nslookup breeze.captioncolorado.com
Server:  dns.adobe.com
Address:  xx.xx.xx.xx
Non-authoritative answer:
Name:    breeze.captioncolorado.com
Address:  216.241.103.7

Workaround: When either of these domain names (Breeze or Connect) fails to connect, use the other. This is a known issue at Caption Colorado and they are working to resolve it. Simply juxtaposing connect.captioncolorado.com for breeze.captioncolorado.com or visa versa in the pod configuration will solve the connection issue and facilitate closed-captioning.

XML API Tips: Modification of Help / Support Links

In Adobe Connect (both On Prem and Hosted accounts), there are methods to modify existing support and help links using the XML API.  This was implemented to provide the capability to replace the in product support / help links and details with partner or organization-specific links / contact information.

Use Case

Say a partner or organization wants to be able to replace the help / support links embedded in the Connect meeting client or Connect web app with links to their own version of the help documentation / support information or support portal. They need to provide a combined cohesive help / support channel to their customers or their users.

The following undocumented APIs are provided to modify the support or help link customization on a per-account basis. Here is how it works:

Link 1 – Contact Support (In Meeting)

First, the ‘Contact Support’ link in the Meeting interface itself (as seen below):

contactsupport
To modify this, use the XML API call: account-support-link-update to enable or disable the account feature and modify the support link.

The default support link is: http://helpx.adobe.com/adobe-connect.html

XML API Call Info:
account-support-link-update
parameters:
account-id = the account-id of the account you are modifying the links for
enable = true or false – enables (true) or disables (false) this feature
support-link = link to partner or customer support site (must be http link)
– if enable is true, must provide support-link
– if enable is false, remove support-link for the account

To enable a custom link:

https://{AccountURL}/api/xml?action=account-support-link-update&enable=true&support-link=http://mySupportsiteURL

Results:

<results>
<status code=”ok”/>

</results>

To verify it is now active (aside from testing in a new meeting session), you can run the ‘feature-info’ API call which will return that feature as part of account information if the feature is enabled on the account.

Example:

https://{AccountURL}/api/xml?action=feature-info&account-id=XXXXXXXX

<results>
<status code=”ok”/>
<disabled-features>
….snip snip….
<feature account-id=”XXXXXXXX” feature-id=”fid-non-partner-support-link“>
<date-begin>2013-10-29T16:53:09.533-04:00</date-begin>
<date-end>2999-12-31T19:00:00.863-05:00</date-end>
<recordcreated>2013-10-29T11:53:09.553-04:00</recordcreated>
</feature>
….snip snip….
</disabled-features>
</results>

Note: it’s deceiving, but it WILL be listed in the ‘disabled-features’ XML node if it is ENABLED.  If it is NOT enabled, it will NOT show up in the results of this call.

To disable (or set back to the original default setting):

https:{AccountURL}/api/xml?action=account-support-link-update&enable=false

Results:

<results>
<status code=”ok”/>
</results>

Note: For meetings that are still active and have not unloaded from memory yet, the links will not change until it fully shuts down.  For new meeting sessions, the link will immediately be updated/reflected to show the intended webpage.

Link 2 – Help Link (Login Page)

Second, the ‘Help’ link on the login page (as seen below):

help

The default value will take you to: http://helpx.adobe.com/adobe-connect.html

XML API Call Info:
account-custom-help-link-update
parameters:
account-id = the account-id of the account you are modifying the links for
field-id = the field-id of the help link you are trying to modify. Values are:
account-login-help-link
– account-webapp-help-link
value = link to partner or customer support site (The help link must start with either ‘http://’ or ‘https://’.  No javascript urls are allowed as values.)

 

To enable a custom link (use the ‘account-login-help-link’ field-id above):

https://{AccountURL}/api/xml?action=account-custom-help-link-update&account-id=XXXXXXX&field-id=account-login-help-link&value=http://mySupportURL

Results:

<results>
<status code=”ok”/>
</results>

Link 3 – Help Link (Connect Central Page)

Third, the ‘Help’ link on the top of the Connect Central page (as seen below):

central

The default value will be: http://help.adobe.com/en_US/connect/9.0/using/index.htm

XML API Call Info:
account-custom-help-link-update
parameters:
account-id = the account-id of the account you are modifying the links for
field-id = the field-id of the help link you are trying to modify. Values are:
– account-login-help-link
account-webapp-help-link
value = link to partner or customer support site (The help link must start with either ‘http://’ or ‘https://’.  No javascript urls are allowed as values.)

 

To enable a custom link (use the ‘account-webapp-help-link’ field-id above):

https://{AccountURL}/api/xml?action=account-custom-help-link-update&account-id=XXXXXXX&field-id=account-webapp-help-link&value=http://mySupportURL

Results:

<results>
<status code=”ok”/>
</results>

To REMOVE any of these link customizations, simply leave the VALUE param empty:

https://{AccountURL}/api/xml?action=account-custom-help-link-update&account-id=XXXXXXX&field-id=account-webapp-help-link&value=

Results:

<results>
<status code=”ok”/>
</results>

And:

https://{AccountURL}/api/xml?action=account-custom-help-link-update&account-id=XXXXXXX&field-id=account-webapp-help-link&value=

Results:

<results>
<status code=”ok”/>
</results>

To view any custom help links set on the account:

XML API Call Info:
account-custom-help-links
parameters:
none.

https://{AccountURL}api/xml?action=account-custom-help-links

If NO help links have been customized, you will see only an ‘ok’ result returned.

Results if no help links:

<results>
<status code=”ok”/>
</results>

 Results if help links are customized:

<results>
<status code=”ok”/>
<custom-help-links>
<links>
<login-help-link>http://www.mysupport.com</login-help-link>
<webapp-help-link>http://www.mysupport.com</webapp-help-link>
</links>
</custom-help-links>
</results>

Using the FMS API for On-Prem Adobe Connect

For monitoring purposes, you can build an application which utilizes additional API calls that hook directly into the Flash Media Administration Server services.  This is undocumented but may help you with additional monitoring or statistics on the FMS side.

A full list of FMS/FCS API entries for the 9.1 version of FMS (which is version 4) can be found here:
http://help.adobe.com/en_US/flashmediaserver/adminapi/WSa4cb07693d12388431df580a12a34991ebc-8000.html

Previously, as an Adobe Connect administrator, you probably have always had the additional FMS service (Flash Media Administration Server) shut off.  In order to utilize the API, you need to make sure this service is running:

fmsadmin

In order to hit the API for FMS, you need to use the FMS admin username and password.

This can be found in:

[install drive]:\Connect\9.1.1\comserv\conf

# An administrator for the server. Users.xml
DEFAULT_FCS_USER=XXXXXX
# Password for this vhost administrator. Users.xml
DEFAULT_FCS_PASSWORD=XXXXXX

In order to use all the calls (or a select few, depending on your desire), you need to modify one additional FMS file (see below).

Continue reading…

XML API Tips: User Manager Associations

A common workflow for Adobe Connect admins is to associate users to managers via the UI.

In the UI, you can navigate to the Administration > Users and Groups > {select a user} > Edit Team Members area to select users who will be direct reports of that manager.

This information will show up in the ‘My Profile‘ > Organization area for the user, where they will be able to see their Manager information (if they have a manager set) and their Team Members (if they are a manager themselves).

But with the XML API, this process is undocumented. Here’s how you accomplish this:

How do I associate a user to a Manager?

http://connectURL/api/xml?action=user-manager-update&manager-id=XXXXXXX&principal-id=XXXXXXX

Where:
action=user-manager-update
manager-id= principal-id of user who is going to be the manager
principal-id= principal-id of the user who is being assigned a manager

Note:
The user-manager-update call is UNDOCUMENTED.

Results:

<results>
<status code="ok"/>
</results>

How do I disassociate a user from a Manager?

http://connectURL/api/xml?action=user-manager-update&manager-id=XXXXXXX&principal-id=XXXXXXX

Where:
action=user-manager-update
manager-id= the account-id (‘7′ if an on-prem/Licensed customer or a longer numeric value for an Adobe Hosted customer)
principal-id= principal-id of the user who is being assigned a manager

Note:
The user-manager-update call is UNDOCUMENTED.

Results:

<results>
<status code="ok"/>
</results>

 

The below IS documented, however it is applicable to this post, so I will include it:

How do I list all direct reports of a Manager?

http://connectURL/api/xml?action=principal-list&filter-manager-id=XXXXXX

Where:
action=principal-list
filter-manager-id= the sco-id of the user who is the manager

Results:

<results>

<status code="ok"/>
<principal-list>
<principal principal-id="XXXXXXXXX" account-id="XXXXXXXXX" type="user" has-children="false" is-primary="false" is-hidden="false" manager-id="XXXXXXXXX" training-group-id="">
<name>USER NAME (FIRST AND LAST)</name>
<login>USER LOGIN VALUE</login>
<email>USER EMAIL VALUE</email>
<display-uid>USER LOGIN VALUE</display-uid>
</principal>
</principal-list>
</results>

 

XML API Tips: Adding a Telephony Profile to a Meeting Room

Another one of the undocumented workflows for Adobe Connect with regards to the XML API is adding telephony profiles to Adobe Connect Meeting rooms.

How do I add a telephony profile to a meeting?

https://connectURL/api/xml?action=acl-field-update&field-id=telephony-profile&value=XXXXXXXX&acl-id=XXXXXXXX

Where:
action=acl-field-update
field-id = set to ‘telephony-profile’
value = profile-id value
acl-id = meeting sco-id value

Results:

<results><results>
<status code=”ok”/>
</results>

To find the profile-id, you can run the telephony-profile-list API call, which will list the API caller’s telephony profiles.

XML API Tips: Setting/Changing Recording Permissions

One of the undocumented workflows for Adobe Connect with regards to the XML API is working with permission levels of recordings (archives).  A recording can either be Public or Private.

The workflow is similar to that of the permission level for Meetings.  See below for the steps for making a recording Public or Private in Adobe Connect 9.1:

How do I make a Private Adobe Connect Recording Public?

https://connectURL/api/xml?action=permissions-update&principal-id=public-access&permission-id=view&acl-id=XXXXXXX

Where:
action=permissions-update
acl-id= ‘sco-id’ of the recording.
principal-id=public-access
permission-id=view

Results:

<results>
<status code=”ok”/>
</results>

 

How do I make a Public Adobe Connect Recording Private?

https://connectURL/api/xml?action=permissions-update&principal-id=public-access&permission-id=remove&acl-id=XXXXXXX

Where:
action=permissions-update
acl-id= ‘sco-id’ of the recording.
principal-id=public-access
permission-id=remove

Results:

<results>
<status code=”ok”/>
</results>

Working with Chat Transcripts

As part of the Compliance and Control settings in Adobe Connect, administrators have the ability to enable Chat Transcripts for logging all chat happening on the Adobe Connect server.  This setting is located at: Administration > Compliance and Control > Recordings and Notice > Enable Chat Transcripts.

chattranscript-1

This transcript is stored on the Adobe Connect server in XML format.  One file for each meeting session.  Each file contains the chat from all chat pods used during that session.  When a meeting session has begun, the chat transcript is not created until someone first starts typing in the chat pod.  At the moment the first chat begins, a new sco (unrelated to the meeting sco itself) is created in the file system ({root}\Connect\content\7\XXXXX-1 where XXXXX = the unique sco-id that gets assigned by Connect for this item). The folder inside of the sco folder will be named ‘input‘ for the duration of the meeting session and will then change to ‘output‘ once the session is ended and fully unloads from memory.  Once the session is over, the chat transcript is available for retrieval.

chattrans2

Only administrators have the ability to navigate to and obtain these chat transcripts.  Here is the workflow you can use to download chat transcripts from the server, if the chat transcripts are enabled:

1) Find the folder for Chat Transcripts on the Connect system.  This is actually a hidden folder and you cannot navigate to it by the normal UI.  To do this, run the following API call:

http://{myServer}/api/xml?action=sco-contents&sco-id=7&filter-like-name=Chat

where sco-contents = the api call.
where sco-id = the account-id of the system (for On Prem Connect licenses this will be ‘7’)
where filter-like-name=Chat

It will return the location of the Chat Transcripts folder.

Results will look like this:

<results>
<status code=”ok”/>
<scos>
<sco sco-id=”11011″ source-sco-id=”” folder-id=”7″ type=”tree” icon=”folder” display-seq=”0″ duration=”” is-folder=”0″>
<name>Chat Transcripts</name>
<url-path>/f88952271-4-14/</url-path>
<date-created>2013-10-24T07:30:08.460-07:00</date-created>
<date-modified>2013-10-24T07:30:08.460-07:00</date-modified>
<is-seminar>false</is-seminar>
</sco>
</scos>
</results>

2) Take the sco-id from this result set (in the above example it’s 11011) and run the following call:

http://{myServer}/api/xml?action=sco-contents&sco-id=11011

where the call is again ‘sco-contents’
where sco-id = the sco-id from the result of the first call.

This will list out all the Chat Transcripts on the system and the result will look like this:

<results>
<status code=”ok”/>
<scos>
<sco sco-id=”11140″ source-sco-id=”11137″ folder-id=”11011″ type=”content” icon=”transcript” display-seq=”0″ duration=”645″ is-folder=”0″><name>r35s9d4oskg_0</name>
<url-path>/p16jb8mcs6v/</url-path>
<date-begin>2013-10-24T12:17:15.127-07:00</date-begin>
<date-end>2013-10-24T12:28:00.263-07:00</date-end>
<date-created>2013-10-24T12:17:15.127-07:00</date-created>
<date-modified>2013-10-24T12:28:00.263-07:00</date-modified>
<is-seminar>false</is-seminar>
</sco>
</scos>
</results>

(in this example, I ONLY have 1 transcript on the system, so it only shows 1 above).

If you have a lot of transcripts (which you will after you enable this setting), you may want to filter on the meeting for which the transcripts were from.  This can be done by filtering on the ‘source-sco-id’ which is the sco-id of the meeting that was held.   So if you know the sco-id of the meeting, and you know the date range for which you had the session, you can filter on either the source-sco-id value (which will = the sco-id of the meeting) and/or the date/time fields to limit the data returned and find the transcripts you are looking for.

Now, the URL-path you see above in the second XML result is NOT accessible directly.  You cannot just append the value above (like ‘/p16jb8mcs6v/‘) to the Connect domain and expect to get the transcript.  This is what you need to do to download the file directly:

3)  Take your Connect domain + the url-path value + ‘output/foo.zip?download=zip‘ so the URL example would be:

http://mycomany.connect.com/p16jb8mcs6v/output/foo.zip?download=zip

This will get you a downloaded zip file that contains the Chat Transcript (in XML format).