Posts in Category "XML API"

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).

 

 

 

Using the XML API and Microsoft Excel to obtain additional reporting from Adobe Connect

Sometimes customers need a custom report that is not included in the normal reports in the Adobe Connect UI.   They can obtain this data by running an API call, however the results get displayed in a browser (in an XML result set) and is not in a user-friendly format as-is.  In lieu of actually building an application that can parse and display the XML in a nice format for the user to be able to display in a useful manner, we can simply use Microsoft Excel to display the data in a nice tabbed report format.

An example of this would be as follows:

Say, you want to report on what users are in a particular group within Adobe Connect, and there is no good established report to actually display this data (other than in the datagrid in the Users and Groups area)…

Here’s what you can do.

Log into the account in a browser, as an admin.

Run the following API (or any API you need to run to obtain the data you are looking for):
http://connectURL/api/xml?action=principal-list&group-id=XXXXXXX&filter-is-member=true

Where:

action=principal-list
group-id= principal-id of group you want to report on
filter-is-member=true

 The results will get returned in the browser in XML format (as seen in the screenshot below):

Save the current page as an XML file by going into the browser options and select ‘Save As’ and make sure you save the page as ‘.xml’.

xml-1

 

After saving the XML locally, open up Microsoft Excel (on Windows) and select Data > From XML Data Import.

xml-2

 

Click OK through all the next pop ups that show up after selecting the XML file and just select the defaults:

xml-3 xml-4

 

Once the data loads in the worksheet, it will be formatted in a nice tabbed display as you see below:

xml-5

API Change in 9.1 for Report-Meeting-Attendance-Details

Stemming from a previous known issue which was corrected in 9.1, we have made a change to one specific API call for reporting meeting session information.

Previously in Adobe Connect 9.0.4, the two APIs “report-meeting-sessions” and “report-meeting-attendance-details” used completely different queries, and returned different results in many legitimate use cases.

The goal was to reconcile them by making sure that the “num_participants” value returned by the former matches the number of entries returned by the latter.

The change consisted of using the main query used by report-meeting-sessions as the inside/main query for report-meeting-attendance-details as well. Previously, this was not the case, and the two queries were completely different.

However, in the course of making this change, one change was required in the report-meeting-sessions query itself in order to ensure that the numbers are in alignment.

The changes are detailed below.

report-meeting-sessions: the query has been modified slightly to return unique transcript IDs; in the vast majority of cases, this will not make a difference – however, if the same user gets a different transcript ID (e.g., if there are multiple user instances) then these will be counted as two separate user instances.

report-meeting-attendance-details: the main query in use here is now identical to the one used for report-meeting-sessions. Consequently, the number of entries returned here will be identical to the “num-participants” returned by the report-meeting-sessions API above. In addition to the fields returned earlier, this API now also returns session_date_created and session_date_end indicating when the meeting session itself started and ended.

Note that, in either case, passing ‘&report-version=deprecated’ as a separate parameter with the URL will bypass these changes and retain the older form of both these queries, should you need the calls to work as they previously did in prior Adobe Connect versions.

Specifically, if you are looking for each individual ‘start’ and ‘end’ time of a user’s session with the ‘report-meeting-attendance-details‘ API call in Adobe Connect 9.1 you need to append the ‘&report-version=deprecated‘ to the end of the call.  Otherwise, you will get the start and end time of the meeting session itself and not the user  session start/end times.

Adobe Connect Web Services Best Practices with URL Encoding

It is always good to review the best practices for URL encoding strings (http://www.w3schools.com/tags/ref_urlencode.asp) before writing your code for any sort of XML API integration with Adobe Connect.  This especially comes in handy when you need to pass in passwords for either a principal or telephony profile, or if you use something as common as the time zone value in a date filter.

One example of a common problem  is the ‘+’ in the service call URL if your time zone for instance, includes a ‘+’ sign (so GMT+01:00 for Paris as an example).  This is a conflicting standards issue with the  URL spec and the ISO8601 time spec.  All customers should make a practice of URL encoding all query strings in their application or if they are just using a web browser to make API calls to Adobe Connect.

The workaround in the case of a time zone on the plus side of GMT would be to URL encode the ‘+’ with ‘%2b’.

So an example would be:

https://{serverURL}/api/xml?action=report-meeting-attendance-details&sco-id=XXXXXXXX&filter-gte-date-end=2013-09-11T15%3A31%3A21.057%2b01%3A00&filter-lte-date-end=2013-09-11T16%3A06%3A10.650%2b01%3A00

Where I substituted the correct ‘%2b’ in the URL string instead of ‘+’ and also %3A instead of ‘:’ .

This Will return the desired:

<results>
<status code=”ok”/>
<report-meeting-attendance-details>
<row transcript-id=”XXXXXXXX” sco-id=”XXXXXXX” principal-id=”XXXXXXX” answered-survey=”0″>
<attendee-login>user@email.com</attendee-login>
<attendee-name>User Name</attendee-name>
<attendee-ip-address>XXX.XXX.XXX.XXX</attendee-ip-address>
<sco-name>Sco Name</sco-name>
<meeting-url>http://{serverURL}/meetingurl</meeting-url>
<unique-meeting-id>XXXXXXXXX-XXXXXXXXX-XXXXXXXXX</unique-meeting-id>
<customer-id>XXXXXX</customer-id>
<date-created>2013-09-11T15:31:21.057+01:00</date-created>
<date-end>2013-09-11T16:06:10.650+01:00</date-end>
</row>
<row>
….
</row>
<row>
….
</row>
</report-meeting-attendance-details>
</results>

 

Note: The error you would get if you did not encode the “+” in the above example would look like this:

<results>
<status code=”invalid”>
<invalid field=”date-end” type=”date” subcode=”format“/>
</status>
</results>