Get started with Adobe Connect Web Services

Meklēšana
Connect

Connect

Atvērt lietotni

Learn the key concepts and know the basics to get started with Adobe Connect Web Service APIs.

To get started with Adobe Connect Web Services, you need to understand three key concepts:

  • Principals, who are users and groups

  • SCOs, which are Shareable Content Objects and represent meetings, courses, and just about any content that can be created on Adobe Connect. SCOs (pronounced sko, which rhymes with snow) are compatible with the industry standard Shareable Content Object Reference Model (SCORM) specification and can be used with a Learning Management System (LMS).

  • Permissions, which define how principals can act on objects

This chapter describes basic tasks you can do with Web Services, regardless of which Adobe Connect applications you have licensed. Many tasks are described as if you are running them in a browser. If you want to make the call from an application, translate the XML request to the language you are working in (for an example of how to do this in Java™, see Send XML requests).

Find a principal-id

A principal is a user or group that has a defined permission to interact with a SCO on the server. You can create users and groups for your organization and modify their permissions.

Adobe Connect also has built-in groups: Administrators, Limited Administrators, Authors, Training Managers, Event Managers, Learners, Meeting Hosts, and Seminar Hosts. You can add users and groups to built-in groups, but you can’t modify the permissions of built-in groups.

Piezīme.

The built-in groups that are available depend on your account.

Each Adobe Connect user and group has a principal-id. In some API calls, the principal-id is called a group-id or user-id to distinguish it from other values. The value of the ID that identifies a user or group is always the same, regardless of its name.

Get the principal-id of a user or group

  1. Call principal-list with a filter:

     https://example.com/api/xml?action=principal-list&filter-name=jazz doe

    It is best to use filter-name, filter-login, or filter-email for an exact match. Be careful with filter-like-name, as it may affect server performance.

  2. Parse the principal elements in the response for the principal-id:

     <principal principal-id="2006282569" account-id="624520" type="user" 
         has-children="false" is-primary="false" is-hidden="false"> 
     <name>jazz doe</name>  
     <login>jazzdoe@example.com</login>  
     <email>jazzdoe@newcompany.com</email>  
 </principal>

Get the principal-id of the current user

  1. Call common-info after the user is logged in:

     https://example.com/api/xml?action=common-info

  2. Parse the user elements in the response for the user-id:

     <user user-id="2007124930" type="user"> 
         <name>jazz doe</name>  
         <login>jazz@doe.com</login>  
 </user>

    Here, the principal-id is called user-id, because it always represents a user who is authenticated to Adobe Connect. A group cannot log in to the server. You can pass the user-id value as a principal-id in other actions.

List principals or guests

A principal with a type of user is a registered Adobe Connect user, while a user with a type of guest has entered a meeting room as a guest. The server captures information about the guest and gives the guest a principal-id.

List all principals on the server

  1. Call principal-list with no parameters:

     https://example.com/api/xml?action=principal-list

    This call returns all Adobe Connect users, so be prepared for a large response.

  2. Parse the principal elements in the response for the values you want:

     <principal principal-id="2006282569" account-id="624520" type="user" 
         has-children="false" is-primary="false" is-hidden="false"> 
     <name>jazz doe</name>  
     <login>jazzdoe@example.com</login>  
     <email>jazzdoe@newcompany.com</email>  
 </principal>

List all guests on the server

  1. Call report-bulk-users, filtering for a type of guest:

     https://example.com/api/xml?action=report-bulk-users&filter-type=guest

  2. Parse the row elements in the response:

     <row principal-id="51157227"> 
     <login>joy@acme.com</login>  
     <name>joy@acme.com</name>  
     <email>joy@acme.com</email>  
     <type>guest</type>  
 </row>

List all users who report to a specific manager

When you call principal-info with a principal-id, the response shows the principal. If the principal is a user who has a manager assigned in Adobe Connect, the response also shows data about the principal’s manager in a manager element:

 <manager account-id="624520" disabled="" has-children="false" is-hidden="false" is-primary="false" principal-id="2006282569"        type="user"> 
     <ext-login>jazzdoe@example.com</ext-login>  
     <login>jazzdoe@example.com</login>  
     <name>jazz doe</name>  
     <email>joy@example.com</email>  
     <first-name>jazz</first-name>  
     <last-name>doe</last-name>  
     <x-2006293620>23456</x-2006293620>  
     <x-2007017651>chicago</x-2007017651>  
 </manager>

You can use the manager’s principal-id with principal-list to list all users who are assigned to the manager.

  1. Call principal-list, filtering on manager-id:

     https://example.com/api/xml?action=principal-list    &filter-manager-id=2006282569

  2. Parse the response for the principal elements:

     <principal principal-id="2006258745" account-id="624520" type="user" has-children="false" is-primary="false" is-hidden="false" manager-id="2006282569"> 
     <name>Pat Lee</name>  
     <login>plee@mycompany.com</login>  
     <email>plee@mycompany.com</email>  
 </principal>

Create users

To create a new user, you need Administrator privilege. Adobe recommends that you create a user who belongs to the admins group for your application to use to make API calls that require Administrator privilege.

Create a new user and send a welcome e-mail

  1. In your application, log in as an Administrator user.

    See Log in from an application for various ways to log in.

  2. Call principal-update with at least these parameters:

     https://example.com/api/xml?action=principal-update 
         &first-name=jazz&last-name=doe&login=jazz99@doe.com&password=hello 
         &type=user&send-email=true&has-children=0&email=jazz99@doe.com

    The type must be user, has-children must be 0 or false, send-email must be true, and email must have a valid e-mail address.

    The server sends a welcome e-mail with login information to the user’s e-mail address.

  3. Parse the principal element in the response for the user’s principal-id:

     <principal type="user" principal-id="2007184341" has-children="0" 
         account-id="624520"> 
     <login>jammdoe@example.com</login>  
     <ext-login>jammdoe@example.com</ext-login>  
     <name>jamm doe</name>  
 </principal>

Create a new user without using an e-mail address as a login ID

  1. In Adobe Connect Central, navigate to Administration > Users and Groups > Edit Login and Password Policies. Make sure that Use E-mail Address as the Login is set to No.

  2. In your application, log in as an Administrator user.

  3. Call principal-update to create the new user, passing both login and email parameters:

     https://example.com/api/xml?action=principal-update&first-name=jazz 
     &last-name=doe&login=jazz&email=jazzdoe@company.com 
     &password=nothing&type=user&has-children=0

  4. Parse the response for the principal-id of the new user:

     <principal type="user" principal-id="2007184341" has-children="0" 
             account-id="624520"> 
     <login>jazzdoe@example.com</login>  
     <ext-login>jazzdoe@example.com</ext-login>  
     <name>jazz doe</name>  
 </principal>

    In the response, ext-login has the same value as login by default, until the user logs in successfully using external authentication (see Log in using HTTP header authentication).

Update users

Once you create users, you often need to update their information. You can update standard fields that Adobe Connect defines for users by calling principal-update with the user’s principal-id. The standard fields include email, login, first-name, and last-name.

If you have defined custom fields for the principal, use acl-field-update to update them.

You need Administrator privilege to update users, so your application must first log in as a user in the admins group. You cannot log in as the user and then have the user update his or her own profile.

Update standard user information

  1. Log in as an Administrator user.

  2. Call principal-list with a filter to get the user’s principal-id (see Find a principal-id).

  3. Call principal-update to update the user:

     https://example.com/api/xml?action=principal-update 
     &principal-id=2006282569&email=jazzdoe@newcompany.com

  4. Parse the response for a status code of ok.

Update custom field values for a user

  1. Log in as an Administrator user.

  2. Call custom-fields to get the field-id of the custom field:

     https://example.com/api/xml?action=custom-fields

  3. Get the principal-id, sco-id, or account-id you want to update.

    This value is the acl-id you pass to acl-field-update.

  4. Call acl-field-update to update the value of the custom field:

     https://example.com/api/xml?action=acl-field-update&field-id=x-2007396975&acl-id=2006258745&value=44444

Create custom fields

Custom fields are additional data fields that you define. You can define up to eight custom fields on a principal or SCO using custom-field-update.

Once you define the custom field, by default you can set its value either by editing the value in Adobe Connect Central or by calling custom-field-update.

To specify that the value can only be updated through the API, call custom-field-update with the parameter object-type=object-type-read-only.

Define a custom field and set it on a user

  1. First, create the field with custom-field-update: 

     https://example.com/api/xml?action=custom-field-update 
     &object-type=object-type-principal&permission-id=manage 
     &account-id=624520&name=Location&comments=adobe%20location 
     &field-type=text&is-required=true&is-primary=false&display-seq=9

    The name field defines the field name as your application displays it, so use appropriate spelling and capitalization. The custom field in this example is defined for all Adobe Connect principals.

  2. Parse the field element in the response for the field-id:

     <field field-id="2007184366" object-type="object-type-principal" 
         display-seq="9" account-id="624520" is-primary="false"  
         permission-id="manage" is-required="true" field-type="text"> 
 <comments>test</comments>  
 <name>Country</name>  
 </field>

  3. Get the principal-id of the user (see Find a principal-id).

  4. Call acl-field-update to set the value of the field, passing a field-id, the user’s principal-id as acl-id, and a value:

     https://example.com/api/xml?action=acl-field-update 
     &acl-id=2006258745&field-id=2007017474&value=San%20Francisco

  5. Parse the response for a status code of ok.

Create groups

To add users to groups, you need to call principal-update as your application’s Administrator user.

Add a user to a group

  1. Log in as your application’s Administrator user.

  2. (Optional) If the user does not yet exist, create the user with principal-update.

     https://example.com/api/xml?action=principal-update 
     &first-name=jazzwayjazz&last-name=doe&login=jazz@doe.com 
     &password=nothing&type=user&has-children=0

  3. (Optional) Parse the response for the new user’s principal-id.

  4. If the user already exists, call principal-list to get the user’s principal-id:

     https://example.com/api/xml?action=principal-list&filter-type=user

  5. Parse the response for the principal-id:

     <principal principal-id="5611980" account-id="624520" type="user"  
         has-children="false" is-primary="false" is-hidden="false"> 
     <name>Joy Black</name>  
     <login>joy@acme.com</login>  
     <email>joy@acme.com</email>  
 </principal>

  6. Call principal-list again to get the group’s principal-id:

     https://example.com/api/xml?action=principal-list&filter-type=group

  7. Call group-membership-update with is-member=true to add the user to the group:

     https://example.com/api/xml?action=group-membership-update 
     &group-id=4930296&principal-id=2006258745&is-member=true

    • The principal-id is the user’s principal-id.

    • The group-id is the group’s principal-id.

    • The parameter is-member must be true.

Check whether a specific user is in a group

  1. Call principal-list with a group-id, filter-is-member, and a filter that identifies the principal:

     https://example.com/api/xml?action=principal-list&group-id=624523 
         &filter-is-member=true&filter-like-name=bob

  2. Parse for a principal element in the response. A successful response looks like this:

     <principal-list> 
     <principal principal-id="624660" account-id="624520" type="user"  
             has-children="false" is-primary="false" is-hidden="false"> 
         <name>Bill Jones</name>  
         <login>bjones@acme.com</login>  
         <email>bjones@acme.com</email>  
         <is-member>true</is-member>  
     </principal> 
 </principal-list>

    If the user is not a group member, the principal-list element is empty:

     <?xml version="1.0" encoding="utf-8" ?>  
 <results> 
     <status code="ok" />  
     <principal-list />  
 </results>

Check which users are in a group

  1. To get the group’s principal-id, call principal-list with filters:

     https://example.com/api/xml?action=principal-list&filter-type=group 
         &filter-name=developers

    With filter-type and filter-name, principal-list should return a unique match.

  2. Parse the response for the principal-id:

     <principal principal-id="2007105030" account-id="624520"  
         type="group" has-children="true" is-primary="false"  
         is-hidden="false"> 
     <name>developers</name>  
     <login>developers</login>  
     <is-member>false</is-member>  
 </principal>

  3. Call principal-list again, with the principal-id as a group-id and filter-is-member=true:

     https://example.com/api/xml?action=principal-list&group-id=2007105030 
         &filter-is-member=true

  4. Parse the response for the principal elements:

     <principal principal-id="5698354" account-id="624520" type="group"  
             has-children="true" is-primary="false" is-hidden="false"> 
     <name>Bob Jones</name>  
     <login>bobjones@acme.com</login>  
     <is-member>true</is-member>  
 </principal>

List all groups a user belongs to

  1. Call principal-list with the user’s principal-id and filter-is-member=true:

     https://example.com/api/xml?action=principal-list 
     &principal-id=2006258745&filter-is-member=true

  2. Parse the response for the principal elements:

     <principal principal-id="5698354" account-id="624520" type="group"  
             has-children="true" is-primary="false" is-hidden="false"> 
     <name>Bob Jones</name>  
     <login>bobjones@acme.com</login>  
     <is-member>true</is-member>  
 </principal>

Find SCOs

All objects on Adobe Connect are Shareable Content Objects, or SCOs. The word Shareable comes from learning management systems in which content is combined into courses or curriculums and shared among them.

On the server, a SCO can be any content object that is combined with other content objects into a course or curriculum. Courses, curriculums, presentations, and other types of content are SCOs. Meetings, events, folders, trees, links, graphics files, or any other object are also SCOs.

Each SCO has a unique integer identifier called a sco-id. The sco-id is unique across the entire server. On a Adobe Connect hosted account, the sco-id is unique across all accounts.

Each SCO also has a type, such as content, course, meeting, and so on. You can see the sco-id and type values in the response from sco-info or other actions:

 <sco account-id="624520" disabled="" display-seq="0" folder-id="2006258747" 
         icon="producer" lang="en" max-retries="" sco-id="2006334909" 
         source-sco-id="" type="content" version="1">

Characteristics of SCOs

When you study the XML responses of various calls, you notice more characteristics of SCOs:

  • A SCO’s identifier is called a sco-id in some actions, but can also be called folder-id, acl-id, or another name in other actions. It’s the same unique ID.

  • Each SCO can be accessed by various principals, either users or groups. The specific principals who can access a SCO are defined in access control lists, or ACLs.

  • Each SCO has a unique URL, with two parts: a domain name (like http://example.com) and an URL path (like /f2006123456/). You can concatenate these to form the full URL that accesses the SCO.

  • Each SCO has a navigation path that describes where it resides in the folder hierarchy.

  • Each SCO has a permission defined for each principal who can access it.

  • Some SCOs have description fields, which are text strings that give you information about the SCO.

Often you need to find the ID of a SCO or some information about it. SCOs are arranged in a specific folder hierarchy where folders have names that indicate whether they are at the top level, contain shared content or templates, or hold user content and templates.

When you call sco-shortcuts, it returns a list of folders. Notice that folders have different types:

 <?xml version="1.0" encoding="utf-8" ?>  
 <results> 
     <status code="ok" />  
     <shortcuts> 
         <sco tree-id="624530" sco-id="2006258751" type="my-meeting-templates"> 
             <domain-name>http://example.com</domain-name>  
         </sco> 
         <sco tree-id="624530" sco-id="2006258750" type="my-meetings"> 
             <domain-name>http://example.com</domain-name>  
         </sco> 
         <sco tree-id="624529" sco-id="624529" type="meetings"> 
             <domain-name>http://example.com</domain-name>  
         </sco> 
         <sco tree-id="624530" sco-id="624530" type="user-meetings"> 
             <domain-name>http://example.com</domain-name>  
         </sco> 
         ... 
     </shortcuts> 
 </results>

The folders shown in this example happen to be for meetings, but folders for other types of SCOs follow a similar pattern. Each folder type stores certain types of objects, with certain access privileges, as follows:

content, courses, meetings, events, seminars

These are shared folders, such as Shared Meetings, Shared Training, and so on. The Adobe Connect Administrator has access to this folder. The Administrator can assign Manage permission to any user, but only members of the built-in group associated with the folder can create new content or meetings within it.

user-content, user-meetings, user-courses, user-events

These folders each contain a folder for each user who can create content within it (for example, one folder for each meeting host or training developer).

my-courses, my-events, my-meetings, my-meeting-templates, my-content

Users create their own content in these folders and have Manage permission on the content. For example, meeting hosts create meetings in their my-meetings folder and have Manage permission on those meetings.

shared-meeting-templates

This folder is within the Shared Meetings folder, contains meeting templates, and inherits permissions from Shared Meetings.

You can list the contents of any folder to get information about a specific SCO. When you need to search for a SCO but do not have a sco-id, move through folders using sco-shortcuts and sco-expanded-contents. Do not use sco-search, as it returns only certain types of SCOs.

Find a SCO when you do not know the sco-id

  1. Call sco-shortcuts to get a list of root folders on Adobe Connect:

     https://example.com/api/xml?action=sco-shortcuts

  2. Parse the response for a type of the root folder that would logically contain the SCO, for example, my-courses for a course the user has created.

  3. Parse the resulting sco element for a sco-id:

     <sco tree-id="4930295" sco-id="2006258748" type="my-courses"> 
     <domain-name>http://example.com</domain-name>  
 </sco>

  4. Create a call to sco-expanded-contents to list the contents of the folder, adding an exact match filter, if possible:

     https://example.com/api/xml?action=sco-expanded-contents 
     &sco-id=2006258748&filter-name=All About Web Communities

    You have several choices of filters:

    • An exact match filter on name or url-path (like filter-name or filter-url-path), if you know the name or URL of the SCO.

    • A greater-than or less-than date filter (filter-gt-date or filter-lt-date) on date-begin, date-created, or date-modified, if you know one of those dates.

    • A partial name filter (like filter-like-name), if you do not know the exact SCO name. However, using this filter might affect system performance.

  5. Parse the response for the sco-id:

     <sco depth="1" sco-id="2006745671" folder-id="2006258748" type="folder" 
         icon="folder" lang="en" source-sco-id="2006745669" display-seq="0" 
         source-sco-type="14"> 
     <name>A Day in the Life Resources</name>  
     <url-path>/f28435879/</url-path>  
     <date-created>2006-06-12T14:47:59.903-07:00</date-created>  
     <date-modified>2006-06-12T14:47:59.903-07:00</date-modified>  
 </sco>

Get information about a SCO

  1. Call sco-info with the sco-id:

     https://example.com/api/xml?action=sco-info&sco-id=2006745669

  2. Parse the response for name, url-path, or any other value:

     <sco account-id="624520" disabled="" display-seq="0"  
         folder-id="2006258748" icon="curriculum" lang="en" max-retries="" 
         sco-id="2006745669" source-sco-id="" type="curriculum" version="0"> 
     <date-begin>2006-06-12T14:45:00.000-07:00</date-begin>  
     <date-created>2006-06-12T14:47:59.903-07:00</date-created>  
     <date-modified>2006-06-12T14:47:59.903-07:00</date-modified>  
     <name>A Day in the Life</name>  
     <url-path>/day/</url-path>  
 </sco>

Construct the URL to a SCO

  1. Call sco-shortcuts:

     https://example.com/api/xml?action=sco-shortcuts

  2. Parse the response for the domain-name value in any sco element:

     <sco tree-id="624530" sco-id="2006258750" type="my-meetings"> 
     <domain-name>http://example.com</domain-name>  
 </sco>

  3. Call sco-info with the sco-id:

     https://example.com/api/xml?action=sco-info&sco-id=2006334909

  4. Parse the response for the url-path :

     <sco account-id="624520" disabled="" display-seq="0"  
         folder-id="2006258747" icon="producer" lang="en"  
         max-retries="" sco-id="2006334909" source-sco-id=""  
         type="content" version="1"> 
     <date-created>2006-05-11T12:00:02.000-07:00</date-created>  
     <date-modified>2006-05-16T15:22:25.703-07:00</date-modified>  
     <name>Test Quiz</name>  
     <url-path>/quiz/</url-path>  
     <passing-score>10</passing-score>  
     <duration>15100.0</duration>  
     <section-count>6</section-count>  
 </sco>

    The url-path has both leading and trailing slashes. You can take the url-path from report-my-meetings, report-my-training, or any call that returns it.

  5. Concatenate the url-path with the domain-name:

     http://example.com/f2006258748/

Download files

You can download zip files from Adobe Connect to a user’s local computer. A zip file is a SCO. To download it, you need to construct a download URL to the zip file, which looks like this:

 http://server-domain/url-path/output/url-path.zip?download=zip

You probably already know the domain name of your server (such as example.com). If you do not, you can get it by calling sco-shortcuts.

Download a zip file from the server

  1. Call sco-shortcuts:

     https://example.com/api/xml?action=sco-shortcuts

  2. Extract any domain-name value from the response:

     http://example.com

  3. Call sco-info with the sco-id of the zip file:

     https://example.com/api/xml?action=sco-info&sco-id=2006258747

    The SCO is the entire zip file.

  4. Parse the response for the url-path element:

     <sco account-id="624520" disabled="" display-seq="0" folder-id="624522" 
         icon="folder" lang="en" max-retries="" sco-id="2006258747"  
         source-sco-id="" type="folder" version="1"> 
     <date-created>2006-04-18T10:21:47.020-07:00</date-created>  
     <date-modified>2006-04-18T10:21:47.020-07:00</date-modified>  
     <name>joy@acme.com</name>  
     <url-path>/f124567890/</url-path>  
 </sco>

  5. Construct the download URL, for example:

     https://example.com/quiz/output/quiz.zip?download=zip

    Be sure to remove the trailing slash from the url-path value before adding .zip to it (so you have a value like /quiz.zip, not /quiz/.zip).

Check permissions

Permissions define the ways in which a principal can interact with a SCO.

A permission mapping, indicating what permissions a principal has for a particular SCO, is called an access control list or ACL. An ACL consists of three pieces of information:

  • The ID of a principal (a principal-id).

  • The ID of a SCO, account, or principal being acted on. In permission calls, it’s called an acl-id. In other calls, the ID might be called a sco-id, account-id, or principal-id.

  • A keyword that indicates the permission level the principal has, which is one of the valid values in permission-id.

Check the permission a principal has on a SCO

  1. Call permissions-info with both an acl-id and principal-id:

     https://example.com/api/xml?action=permissions-info&acl-id=2006334909 
     &principal-id=2006258745

    To check for permissions on a SCO, the acl-id is a sco-id. The acl-id can also be a principal-id or account-id.

  2. Parse the response for a permission-id:

     <?xml version="1.0" encoding="utf-8" ?>  
 <results> 
     <status code="ok" />  
     <permission acl-id="2007035246" permission-id="view"  
             principal-id="2006258745" />  
 </results>

    If a principal does not have an explicit permission to the SCO (in other words, if permission-id=""), the principal’s permissions on the SCO’s parent object apply.

Check all principals’ permissions on a SCO

  1. Call permissions-info with an acl-id, but no principal-id:

     https://example.com/api/xml?action=permissions-info&acl-id=2006293572

  2. Iterate through the principal elements and parse them for permission-id values:

     <principal principal-id="2596608" is-primary="false" type="user"  
                 has-children="false" permission-id="view"> 
         <name>Jay Arnold</name>  
         <login>jay@example.com</login>  
 </principal>

    The valid permission values are listed in permission-id.

 Adobe

Saņemiet palīdzību ātrāk un vienkāršāk

Jauns lietotājs?

Ātrās saites

Skatīt visus plānus Pārvaldiet savus plānus
Skatīt ātrās saites
Slēpt ātrās saites
Adobe MAX 2024

Adobe MAX
Radošuma konference

14.–16. oktobris Maiami pludmalē un tiešsaistē

Reģistrēties tūlīt

Adobe MAX

Radošuma konference

14.–16. oktobris Maiami pludmalē un tiešsaistē

Reģistrēties tūlīt
Adobe MAX 2024

Adobe MAX
Radošuma konference

14.–16. oktobris Maiami pludmalē un tiešsaistē

Reģistrēties tūlīt

Adobe MAX

Radošuma konference

14.–16. oktobris Maiami pludmalē un tiešsaistē

Reģistrēties tūlīt

Legal Notices    |    Online Privacy Policy